MAL: add extension function SPI, proper numeric types in codegen (#13761)

**1. Extension Function SPI (`namespace::method()` syntax)**

Adds a pluggable extension mechanism for MAL using `::` separator syntax, enabling external modules
to contribute MAL functions that compile into direct static method calls.

- `MalFunctionExtension` SPI interface with `name()` returning namespace
- `@MALContextFunction` annotation on **static** methods — auto-detected via reflection at startup
- First parameter must be `SampleFamily` (auto-bound), return type must be `SampleFamily`
- Non-static annotated methods throw `IllegalArgumentException` at startup
- Duplicate namespace or method names throw `IllegalArgumentException` at startup
- `m.getDeclaringClass()` used for accurate FQCN in codegen (not `ext.getClass()`)
- `List` parameters validated as `List<String>` via generic type inspection
- Supports `String`, `double`, `float`, `long`, `int`, `List<String>` parameter types
- Direct static method call codegen — no reflection or registry dispatch at runtime

Example MAL script:
```
metric.sum(['svc']).test::scale(3.0)
```
Generated code:
```java
sf = TestMalExtension.scale(sf, 3.0);
```

**2. Proper numeric types in MAL codegen**

Integer-valued literals now emit `Long.valueOf(NL)` instead of `Double.valueOf(N.0)` in:
- Binary arithmetic: `metric * 100` → `sf.multiply(Long.valueOf(100L))`
- Built-in method args: `.multiply(100)` → `Long.valueOf(100L)`
- Standalone number expressions: `SampleFamily.EMPTY.plus(Long.valueOf(100L))`

Fractional values still use `Double.valueOf()`. All 1268 v1-v2 comparison tests pass.

**3. GenAI model matcher singleton**

`GenAIModelMatcher.getInstance()` — lazy singleton initialized from `gen-ai-config.yml`.
`GenAIProviderPrefixMatcher.build()` simplified to delegate to singleton (removed unused config param).

Author: wu-sheng

docs/en/concepts-and-designs/mal.md

@@ -236,6 +236,45 @@ buckets, will multiply the bucket value by 1000.)
 1. `element`: element in the array.
 2. `tags`: tags in each sample.
 
+## Extension Functions
+
+MAL supports extension functions via the `namespace::method()` syntax. Extensions are pluggable modules
+that add custom capabilities to MAL without modifying the core language. They are discovered at startup
+via Java `ServiceLoader`.
+
+### Syntax
+
+Extension functions are called with a `::` separator between the namespace and method name:
+
+```
+metric.sum(['svc']).myext::transform(2.0)
+metric.genai::estimateCost()
+```
+
+The `::` separator distinguishes extension calls from built-in `SampleFamily` methods (like `.sum()`,
+`.tag()`, `.filter()`). Method names only need to be unique within their namespace.
+
+### Supported Parameter Types
+
+Extension methods accept the following argument types from MAL expressions:
+
+| Java Type | MAL Argument Example |
+|-----------|---------------------|
+| `String` | `"value"` |
+| `double` | `2.0` |
+| `int` | `100` |
+| `List<String>` | `["tag1", "tag2"]` |
+
+The first parameter is always `SampleFamily`, which is automatically bound to the current value in the
+method chain. Only the additional parameters need to be specified in the MAL expression.
+
+### Error Handling
+
+The MAL compiler validates extension calls at compile time:
+- Unknown namespace or method name results in a compilation error.
+- Mismatched argument count results in a compilation error.
+- Type mismatches between MAL arguments and Java parameter types result in a compilation error.
+
 ## Down Sampling Operation
 MAL should instruct meter-system on how to downsample for metrics. It doesn't only refer to aggregate raw samples to
 `minute` level, but also expresses data from `minute` in higher levels, such as `hour` and `day`.

oap-server/analyzer/gen-ai-analyzer/src/main/java/org/apache/skywalking/oap/analyzer/genai/GenAIAnalyzerModuleProvider.java

@@ -66,7 +66,7 @@ public void onInitialized(final GenAIConfig initialized) {
     public void prepare() throws ServiceNotProvidedException, ModuleStartException {
         GenAIConfigLoader loader = new GenAIConfigLoader(config);
         config = loader.loadConfig();
-        GenAIProviderPrefixMatcher matcher = GenAIProviderPrefixMatcher.build(config);
+        GenAIProviderPrefixMatcher matcher = GenAIProviderPrefixMatcher.build();
         this.registerServiceImplementation(
                 IGenAIMeterAnalyzerService.class,
                 new GenAIMeterAnalyzer(matcher)

oap-server/analyzer/gen-ai-analyzer/src/main/java/org/apache/skywalking/oap/analyzer/genai/matcher/GenAIProviderPrefixMatcher.java

@@ -22,54 +22,27 @@
 import org.apache.skywalking.oap.server.library.util.genai.GenAIModelMatcher;
 import org.apache.skywalking.oap.server.library.util.genai.GenAIPricingConfig;
 
-import java.util.stream.Collectors;
-
 /**
- * Delegates to {@link GenAIModelMatcher} in library-util.
- * Converts module-specific {@link GenAIConfig} to the shared {@link GenAIPricingConfig}.
+ * Thin wrapper over the singleton {@link GenAIModelMatcher} that converts
+ * results to module-specific {@link GenAIConfig.Model} types.
  */
 public class GenAIProviderPrefixMatcher {
 
-    private final GenAIModelMatcher delegate;
-
-    private GenAIProviderPrefixMatcher(GenAIModelMatcher delegate) {
-        this.delegate = delegate;
+    private GenAIProviderPrefixMatcher() {
     }
 
-    public static GenAIProviderPrefixMatcher build(GenAIConfig config) {
-        GenAIPricingConfig pricingConfig = toPricingConfig(config);
-        return new GenAIProviderPrefixMatcher(GenAIModelMatcher.build(pricingConfig));
+    public static GenAIProviderPrefixMatcher build() {
+        // Ensure singleton is initialized (lazy init from gen-ai-config.yml)
+        GenAIModelMatcher.getInstance();
+        return new GenAIProviderPrefixMatcher();
     }
 
     public MatchResult match(String modelName) {
-        GenAIModelMatcher.MatchResult result = delegate.match(modelName);
+        GenAIModelMatcher.MatchResult result = GenAIModelMatcher.getInstance().match(modelName);
         GenAIConfig.Model modelConfig = toModuleModel(result.getModelConfig());
         return new MatchResult(result.getProvider(), modelConfig);
     }
 
-    private static GenAIPricingConfig toPricingConfig(GenAIConfig config) {
-        GenAIPricingConfig pricingConfig = new GenAIPricingConfig();
-        pricingConfig.setProviders(
-            config.getProviders().stream().map(p -> {
-                GenAIPricingConfig.Provider pp = new GenAIPricingConfig.Provider();
-                pp.setProvider(p.getProvider());
-                pp.setPrefixMatch(p.getPrefixMatch());
-                pp.setModels(
-                    p.getModels().stream().map(m -> {
-                        GenAIPricingConfig.Model pm = new GenAIPricingConfig.Model();
-                        pm.setName(m.getName());
-                        pm.setAliases(m.getAliases());
-                        pm.setInputEstimatedCostPerM(m.getInputEstimatedCostPerM());
-                        pm.setOutputEstimatedCostPerM(m.getOutputEstimatedCostPerM());
-                        return pm;
-                    }).collect(Collectors.toList())
-                );
-                return pp;
-            }).collect(Collectors.toList())
-        );
-        return pricingConfig;
-    }
-
     private static GenAIConfig.Model toModuleModel(GenAIPricingConfig.Model pm) {
         if (pm == null) {
             return null;

oap-server/analyzer/gen-ai-analyzer/src/test/java/org/apache/skywalking/oap/genai/analyzer/GenAIMeterAnalyzerTest.java

@@ -48,7 +48,7 @@ void setUp() throws ModuleStartException {
         GenAIConfigLoader loader = new GenAIConfigLoader(config);
         loadedConfig = loader.loadConfig();
 
-        matcher = GenAIProviderPrefixMatcher.build(loadedConfig);
+        matcher = GenAIProviderPrefixMatcher.build();
         analyzer = new GenAIMeterAnalyzer(matcher);
     }
 
@@ -233,7 +233,7 @@ void testEstimatedCost() throws ModuleStartException {
         GenAIConfigLoader loader = new GenAIConfigLoader(config);
         GenAIConfig loadedConfig = loader.loadConfig();
 
-        GenAIProviderPrefixMatcher matcher = GenAIProviderPrefixMatcher.build(loadedConfig);
+        GenAIProviderPrefixMatcher matcher = GenAIProviderPrefixMatcher.build();
 
         GenAIProviderPrefixMatcher.MatchResult result = matcher.match("gpt-5.4-pro");
         assertNotNull(result.getModelConfig());

oap-server/analyzer/meter-analyzer/CLAUDE.md

@@ -41,10 +41,16 @@ oap-server/analyzer/meter-analyzer/
     rt/
       MalExpressionPackageHolder.java — Class loading anchor (empty marker)
       MalRuntimeHelper.java           — Static helpers called by generated code (divReverse, regexMatch, isTruthy)
+      MalExtensionRegistry.java       — SPI registry for extension functions (namespace::method)
+
+  src/main/java/.../spi/
+    MalFunctionExtension.java         — SPI interface for extension namespaces
+    MALContextFunction.java           — Annotation marking callable methods
 
   src/test/java/.../compiler/
-    MALScriptParserTest.java          — 20 parser tests
-    MALClassGeneratorTest.java        — 32 generator tests
+    MALScriptParserTest.java          — 22 parser tests
+    MALClassGeneratorTest.java        — 20 generator tests
+    MALExtensionFunctionTest.java     — 9 extension SPI tests
 ```
 
 ## Package & Class Naming
@@ -59,12 +65,93 @@ All v2 classes live under `org.apache.skywalking.oap.meter.analyzer.v2.*` to avo
 | Filter classes | `org.apache.skywalking.oap.meter.analyzer.v2.compiler.rt.{yamlName}_L{lineNo}_filter` |
 | Package holder | `org.apache.skywalking.oap.meter.analyzer.v2.compiler.rt.MalExpressionPackageHolder` |
 | Runtime helper | `org.apache.skywalking.oap.meter.analyzer.v2.compiler.rt.MalRuntimeHelper` |
+| Extension registry | `org.apache.skywalking.oap.meter.analyzer.v2.compiler.rt.MalExtensionRegistry` |
+| Extension SPI | `org.apache.skywalking.oap.meter.analyzer.v2.spi.MalFunctionExtension` |
+| Extension annotation | `org.apache.skywalking.oap.meter.analyzer.v2.spi.MALContextFunction` |
 | Functional interface | `org.apache.skywalking.oap.meter.analyzer.v2.dsl.MalExpression` |
 
 Class names are built from `yamlSource` (file name + line number) and `classNameHint` (rule name or `filter`).
 Example: `vm_L25_cpu_total_percentage` (expression), `gateway_service_L33_filter` (filter).
 Falls back to `MalExpr_<N>` (global counter) when no hint is set.
 
+## Extension Function SPI (`namespace::method()`)
+
+MAL supports custom extension functions via the `namespace::method()` syntax. Extensions are discovered
+at startup via `java.util.ServiceLoader`.
+
+### Syntax
+
+```
+metric.sum(['svc']).genai::estimateCost()
+metric.test::scale(2.0)
+```
+
+The `::` separator distinguishes extension calls from built-in `SampleFamily` methods. The namespace
+avoids global method name conflicts — method names only need to be unique within their namespace.
+
+### Implementing an Extension
+
+1. Create a class implementing `MalFunctionExtension` with **static** `@MALContextFunction` methods:
+
+```java
+public class MyExtension implements MalFunctionExtension {
+    @Override
+    public String name() { return "myext"; }
+
+    @MALContextFunction
+    public static SampleFamily transform(SampleFamily sf, double factor) {
+        return sf.multiply(Double.valueOf(factor));
+    }
+
+    @MALContextFunction
+    public static SampleFamily filterTag(SampleFamily sf, String key, String value) {
+        return sf.tagEqual(key, value);
+    }
+}
+```
+
+2. Register via SPI file `META-INF/services/org.apache.skywalking.oap.meter.analyzer.v2.spi.MalFunctionExtension`:
+```
+com.example.MyExtension
+```
+
+3. Use in MAL scripts: `.myext::transform(2.0)`, `.myext::filterTag("env", "prod")`
+
+### Method Requirements
+
+- Methods **must** be `static` (non-static methods throw `IllegalArgumentException` at startup)
+- First parameter **must** be `SampleFamily` (auto-bound to the current chain value)
+- Return type **must** be `SampleFamily`
+- Additional parameters are matched from MAL arguments by type:
+
+| Java Type | MAL Argument |
+|-----------|-------------|
+| `String` | String literal: `"value"` |
+| `double` / `int` | Number literal: `2.0`, `100` |
+| `List<String>` | String list: `["tag1", "tag2"]` |
+
+### Compile-Time Validation
+
+The compiler validates at expression compilation time:
+- Namespace exists in registry
+- Method exists in that namespace
+- Argument count matches (excluding the implicit `SampleFamily` first param)
+- Argument types are compatible with the method signature
+
+### Generated Code
+
+The compiler generates direct static method calls — no reflection or registry dispatch at runtime.
+
+For `.myext::transform(2.0)`, the compiler generates:
+```java
+sf = com.example.MyExtension.transform(sf, 2.0);
+```
+
+For zero-arg extensions like `.myext::noop()`:
+```java
+sf = com.example.MyExtension.noop(sf);
+```
+
 ## Javassist Constraints
 
 - **No anonymous inner classes**: Javassist cannot compile `new Consumer() { ... }` or `new Function() { ... }` in method bodies.

oap-server/analyzer/meter-analyzer/src/main/antlr4/org/apache/skywalking/mal/rt/grammar/MALLexer.g4

@@ -44,6 +44,7 @@ L_BRACE:    '{';
 R_BRACE:    '}';
 SEMI:       ';';
 COLON:      ':';
+DOUBLE_COLON: '::';
 QUESTION:   '?';
 ARROW:      '->';
 ASSIGN:     '=';

oap-server/analyzer/meter-analyzer/src/main/antlr4/org/apache/skywalking/mal/rt/grammar/MALParser.g4

@@ -76,7 +76,8 @@ functionCall
     ;
 
 methodCall
-    : IDENTIFIER L_PAREN argumentList? R_PAREN
+    : IDENTIFIER DOUBLE_COLON IDENTIFIER L_PAREN argumentList? R_PAREN    // extension: .ns::method()
+    | IDENTIFIER L_PAREN argumentList? R_PAREN                            // built-in: .method()
     ;
 
 // ==================== Arguments ====================