feat: support aggregate mock output parameters in deserializer

Disambiguate ConsumedOutputParameter (name + JsonPath value starting with $)
from aggregate mock functions (name + static/template value) so the
deserializer routes each to the correct field (setMapping vs setValue).

Add shared mock integration test proving MCP and REST adapters produce
identical payloads from a single aggregate function mock definition.

Author: jlouvel

pom.xml

@@ -18,6 +18,8 @@
         <avro.version>1.11.4</avro.version>
         <jetty.version>12.0.25</jetty.version>
         <json-smart.version>2.5.2</json-smart.version>
+        <junit.jupiter.version>5.12.2</junit.jupiter.version>
+        <jacoco.version>0.8.13</jacoco.version>
     </properties>
     <distributionManagement>
         <repository>
@@ -158,7 +160,7 @@
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter</artifactId>
-            <version>6.0.2</version>
+            <version>${junit.jupiter.version}</version>
             <scope>test</scope>
         </dependency>
     </dependencies>
@@ -195,7 +197,7 @@
             <plugin>
                 <groupId>org.jacoco</groupId>
                 <artifactId>jacoco-maven-plugin</artifactId>
-                <version>0.8.11</version>
+                <version>${jacoco.version}</version>
                 <executions>
                     <execution>
                         <id>prepare-agent</id>

src/main/java/io/naftiko/engine/AggregateRefResolver.java

@@ -32,6 +32,7 @@
 import io.naftiko.spec.exposes.RestServerResourceSpec;
 import io.naftiko.spec.exposes.RestServerSpec;
 import io.naftiko.spec.exposes.ServerSpec;
+import io.naftiko.spec.exposes.StepOutputMappingSpec;
 
 /**
  * Resolves aggregate function references ({@code ref}) in adapter units (MCP tools, REST
@@ -136,6 +137,13 @@ void resolveMcpToolRef(McpServerToolSpec tool,
             }
         }
 
+        // Merge step output mappings (function provides default, tool overrides)
+        if (tool.getMappings().isEmpty() && !function.getMappings().isEmpty()) {
+            for (StepOutputMappingSpec mapping : function.getMappings()) {
+                tool.getMappings().add(mapping);
+            }
+        }
+
         // Merge inputParameters (function provides default, tool overrides)
         if (tool.getInputParameters().isEmpty() && !function.getInputParameters().isEmpty()) {
             for (InputParameterSpec param : function.getInputParameters()) {
@@ -191,6 +199,13 @@ void resolveRestOperationRef(RestServerOperationSpec op,
             }
         }
 
+        // Merge step output mappings
+        if (op.getMappings().isEmpty() && !function.getMappings().isEmpty()) {
+            for (StepOutputMappingSpec mapping : function.getMappings()) {
+                op.getMappings().add(mapping);
+            }
+        }
+
         // Merge inputParameters
         if (op.getInputParameters().isEmpty() && !function.getInputParameters().isEmpty()) {
             for (InputParameterSpec param : function.getInputParameters()) {

src/main/java/io/naftiko/spec/AggregateFunctionSpec.java

@@ -18,6 +18,7 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.CopyOnWriteArrayList;
 import com.fasterxml.jackson.annotation.JsonInclude;
+import io.naftiko.spec.exposes.StepOutputMappingSpec;
 import io.naftiko.spec.exposes.OperationStepSpec;
 import io.naftiko.spec.exposes.ServerCallSpec;
 
@@ -48,7 +49,7 @@ public class AggregateFunctionSpec {
     private final List<OperationStepSpec> steps;
 
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
-    private final List<Map<String, Object>> mappings;
+    private final List<StepOutputMappingSpec> mappings;
 
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     private final List<OutputParameterSpec> outputParameters;
@@ -108,7 +109,7 @@ public List<OperationStepSpec> getSteps() {
         return steps;
     }
 
-    public List<Map<String, Object>> getMappings() {
+    public List<StepOutputMappingSpec> getMappings() {
         return mappings;
     }
 

src/main/java/io/naftiko/spec/OutputParameterDeserializer.java

@@ -19,7 +19,6 @@
 import com.fasterxml.jackson.databind.DeserializationContext;
 import com.fasterxml.jackson.databind.JsonDeserializer;
 import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.node.ObjectNode;
 
 /**
  * Custom deserializer for OutputParameterSpec that handles nested structure definitions including
@@ -51,14 +50,20 @@ private OutputParameterSpec deserializeNode(JsonNode node, DeserializationContex
 
         if (node.has("mapping")) {
             spec.setMapping(node.get("mapping").asText());
-        } else if (node.has("value") && node.has("name")) {
-            // ConsumedOutputParameter uses "value" for JsonPath extraction (has name + value)
-            spec.setMapping(node.get("value").asText());
         }
 
-        if (node.has("value") && !node.has("name")) {
-            // MappedOutputParameter uses "value" for static runtime values (no name)
-            spec.setValue(node.get("value").asText());
+        if (node.has("value")) {
+            String rawValue = node.get("value").asText();
+            String trimmedValue = rawValue != null ? rawValue.trim() : "";
+
+            // ConsumedOutputParameter uses "value" for JsonPath extraction (name + value
+            // starting with $). Aggregate mock functions also use name + value, but with
+            // static/template strings — those must stay in setValue().
+            if (node.has("name") && trimmedValue.startsWith("$") && !node.has("mapping")) {
+                spec.setMapping(rawValue);
+            } else {
+                spec.setValue(rawValue);
+            }
         }
 
         if (node.has("const")) {

src/test/java/io/naftiko/engine/AggregateRefResolverTest.java

@@ -29,6 +29,7 @@
 import io.naftiko.spec.exposes.McpToolHintsSpec;
 import io.naftiko.spec.exposes.RestServerOperationSpec;
 import io.naftiko.spec.exposes.ServerCallSpec;
+import io.naftiko.spec.exposes.StepOutputMappingSpec;
 
 /**
  * Unit tests for AggregateRefResolver — ref resolution, merge semantics, hints derivation.
@@ -195,6 +196,25 @@ void resolveMcpToolRefShouldInheritInputParameters() {
         assertEquals("location", tool.getInputParameters().get(0).getName());
     }
 
+    @Test
+    void resolveMcpToolRefShouldInheritMappings() {
+        AggregateFunctionSpec fn = new AggregateFunctionSpec();
+        fn.setName("get-data");
+        fn.setDescription("Get data");
+        fn.getMappings().add(new StepOutputMappingSpec("result", "$.lookup.data"));
+
+        Map<String, AggregateFunctionSpec> map = Map.of("data.get-data", fn);
+
+        McpServerToolSpec tool = new McpServerToolSpec("get-data", null, "Get data");
+        tool.setRef("data.get-data");
+
+        resolver.resolveMcpToolRef(tool, map);
+
+        assertEquals(1, tool.getMappings().size());
+        assertEquals("result", tool.getMappings().get(0).getTargetName());
+        assertEquals("$.lookup.data", tool.getMappings().get(0).getValue());
+    }
+
     @Test
     void resolveMcpToolRefShouldInheritDescription() {
         AggregateFunctionSpec fn = new AggregateFunctionSpec();
@@ -263,6 +283,25 @@ void resolveRestOperationRefShouldInheritCallFromFunction() {
         assertEquals("mock-api.get-data", op.getCall().getOperation());
     }
 
+    @Test
+    void resolveRestOperationRefShouldInheritMappings() {
+        AggregateFunctionSpec fn = new AggregateFunctionSpec();
+        fn.setName("get-data");
+        fn.setDescription("Get data");
+        fn.getMappings().add(new StepOutputMappingSpec("result", "$.lookup.data"));
+
+        Map<String, AggregateFunctionSpec> map = Map.of("data.get-data", fn);
+
+        RestServerOperationSpec op = new RestServerOperationSpec();
+        op.setRef("data.get-data");
+
+        resolver.resolveRestOperationRef(op, map);
+
+        assertEquals(1, op.getMappings().size());
+        assertEquals("result", op.getMappings().get(0).getTargetName());
+        assertEquals("$.lookup.data", op.getMappings().get(0).getValue());
+    }
+
     // ── deriveHints ──
 
     @Test

src/test/java/io/naftiko/engine/exposes/rest/AggregateSharedMockIntegrationTest.java

@@ -0,0 +1,94 @@
+/**
+ * Copyright 2025-2026 Naftiko
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ * 
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package io.naftiko.engine.exposes.rest;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import java.io.File;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+import org.restlet.Request;
+import org.restlet.Response;
+import org.restlet.data.Method;
+import org.restlet.data.Status;
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
+import io.naftiko.Capability;
+import io.naftiko.engine.exposes.mcp.McpServerAdapter;
+import io.naftiko.engine.exposes.mcp.ProtocolDispatcher;
+import io.naftiko.spec.NaftikoSpec;
+import io.naftiko.spec.exposes.RestServerOperationSpec;
+import io.naftiko.spec.exposes.RestServerSpec;
+
+/**
+ * Integration test proving that a single aggregate function mock can be reused unchanged by
+ * both MCP and REST adapters.
+ */
+public class AggregateSharedMockIntegrationTest {
+
+    private static final ObjectMapper JSON = new ObjectMapper();
+
+    @Test
+    void aggregateMockShouldReturnSamePayloadForMcpAndRest() throws Exception {
+        Capability capability = loadCapability("src/test/resources/aggregates/aggregate-shared-mock.yaml");
+
+        McpServerAdapter mcpAdapter = (McpServerAdapter) capability.getServerAdapters().get(0);
+        ProtocolDispatcher dispatcher = new ProtocolDispatcher(mcpAdapter);
+
+        JsonNode mcpResponse = dispatcher.dispatch(JSON.readTree(
+                "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\"," +
+                        "\"params\":{\"name\":\"hello\",\"arguments\":{\"name\":\"Nina\"}}}"));
+
+        assertFalse(mcpResponse.path("result").path("isError").asBoolean(),
+                "MCP tools/call should not fail for aggregate mock ref");
+
+        JsonNode mcpPayload = JSON.readTree(mcpResponse.path("result").path("content")
+                .get(0).path("text").asText());
+
+        RestServerAdapter restAdapter = (RestServerAdapter) capability.getServerAdapters().get(1);
+        RestServerSpec restSpec = (RestServerSpec) restAdapter.getSpec();
+        ResourceRestlet restlet = new ResourceRestlet(capability, restSpec,
+                restSpec.getResources().get(0));
+        RestServerOperationSpec restOperation = restSpec.getResources().get(0).getOperations().get(0);
+
+        assertEquals(2, restOperation.getOutputParameters().size(),
+                "REST operation should inherit two aggregate output parameters");
+
+        assertTrue(restlet.canBuildMockResponse(restOperation),
+                "REST operation should inherit aggregate mock output parameters");
+
+        Request request = new Request(Method.GET, "http://localhost/hello?name=Nina");
+        Response response = new Response(request);
+        restlet.sendMockResponse(restOperation, response, Map.of("name", "Nina"));
+
+        assertEquals(Status.SUCCESS_OK, response.getStatus());
+        JsonNode restPayload = JSON.readTree(response.getEntity().getText());
+
+        assertEquals("Hello, Nina!", mcpPayload.path("message").asText());
+        assertEquals("aggregate-mock", mcpPayload.path("source").asText());
+        assertEquals(mcpPayload, restPayload,
+                "MCP and REST should share the same aggregate mock output");
+    }
+
+    private Capability loadCapability(String path) throws Exception {
+        File file = new File(path);
+        ObjectMapper mapper = new ObjectMapper(new YAMLFactory());
+        mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
+        NaftikoSpec spec = mapper.readValue(file, NaftikoSpec.class);
+        return new Capability(spec);
+    }
+}

src/test/java/io/naftiko/spec/OutputParameterDeserializationTest.java

@@ -99,6 +99,25 @@ public void testConsumedOutputParameterUsesValueField() throws Exception {
     assertEquals("userid", spec.getName(), "Name should be parsed");
     assertEquals("string", spec.getType(), "Type should be parsed");
     assertEquals("$.id", spec.getMapping(), "Value alias should populate mapping");
+    assertNull(spec.getValue(), "Consumed output JsonPath alias should not populate value");
+  }
+
+  @Test
+  public void testNamedMockOutputParameterShouldKeepStaticValue() throws Exception {
+    String yamlSnippet = """
+        name: message
+        type: string
+        value: "Hello, {{name}}!"
+        """;
+
+    ObjectMapper mapper = new ObjectMapper(new YAMLFactory());
+    OutputParameterSpec spec = mapper.readValue(yamlSnippet, OutputParameterSpec.class);
+
+    assertEquals("message", spec.getName(), "Name should be parsed");
+    assertEquals("string", spec.getType(), "Type should be parsed");
+    assertEquals("Hello, {{name}}!", spec.getValue(),
+        "Named mock output should preserve static/template value");
+    assertNull(spec.getMapping(), "Named mock output should not be re-routed to mapping");
   }
 
   @Test

src/test/resources/aggregates/aggregate-shared-mock.yaml

@@ -0,0 +1,61 @@
+# yaml-language-server: $schema=../../main/resources/schemas/naftiko-schema.json
+---
+naftiko: "1.0.0-alpha1"
+info:
+  label: "Aggregate Shared Mock Test"
+  description: "Shared aggregate mock function consumed by MCP and REST refs"
+  tags:
+    - Test
+    - Aggregate
+  created: "2026-04-09"
+  modified: "2026-04-09"
+
+capability:
+  aggregates:
+    - label: "Greeting"
+      namespace: "greeting"
+      functions:
+        - name: "hello"
+          description: "Builds a greeting payload from input parameters."
+          inputParameters:
+            - name: "name"
+              type: "string"
+              description: "Name to greet"
+          outputParameters:
+            - name: "message"
+              type: "string"
+              value: "Hello, {{name}}!"
+            - name: "source"
+              type: "string"
+              value: "aggregate-mock"
+
+  exposes:
+    - type: "mcp"
+      address: "localhost"
+      port: 9200
+      namespace: "greeting-mcp"
+      description: "MCP adapter using aggregate ref in mock mode."
+      tools:
+        - name: "hello"
+          description: "Return greeting payload."
+          ref: "greeting.hello"
+
+    - type: "rest"
+      address: "localhost"
+      port: 9201
+      namespace: "greeting-rest"
+      resources:
+        - path: "/hello"
+          name: "hello"
+          description: "Greeting resource"
+          operations:
+            - method: "GET"
+              name: "hello"
+              ref: "greeting.hello"
+              inputParameters:
+                - name: "name"
+                  in: "query"
+                  type: "string"
+                  description: "Name to greet"
+
+  consumes: []