feat(java): template.toolcall core subtype (ADR-0011)

dmealing · claude · dmealing · commit 4b66ca438250 · 2026-05-27T19:48:03.000-04:00
Brings the Java port to parity with TS rc.5/rc.6 for template.toolcall. Kotlin inherits the Java port automatically. - TemplateConstants: SUBTYPE_TOOLCALL + ATTR_TOOL_NAME (cross-port Tier-1 invariant strings — must match TS / C# / Python exactly) - ToolcallTemplate class (parallels PromptTemplate / OutputTemplate) with its own registerTypes block. Does NOT inheritFrom template.base because the shared @textRef / @Format / @maxchars / @requiredTags attrs do NOT apply to toolcall — binds directly to metadata.base alongside template.base itself. - TemplateTypesMetaDataProvider wires the new subtype next to prompt and output (SPI-discovered). - ValidationPhase: explicit ERR_MISSING_REQUIRED_ATTR checks for @toolname and @payloadRef on toolcall (Java enforces required-ness via per-type validation passes, not auto-driven from the requiredChild constraints). The shared R2 (@payloadRef must resolve to a root-level object.value) already iterates all template.* subtypes — toolcall picks that up automatically. Tests: TemplateToolcallTest adds 6 cases (registry shape, positive load, missing @toolname, missing @payloadRef, bad @payloadRef, plus the constants-match assertion). Full metadata suite 742 -> 748 (same 4 pre-existing ConformanceTest provider-extension failures unchanged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java b/server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java
@@ -1064,6 +1064,26 @@ private static void validateTemplateNode(MetaRoot root, MetaTemplate template) {
                 ErrorCode.ERR_MISSING_REQUIRED_ATTR, template.getSource());
         }
 
+        // R1b — template.toolcall requires @toolName + @payloadRef (ADR-0011).
+        // Mirrors the TS toolcallAttrs schema (both marked required: true).
+        if (TemplateConstants.SUBTYPE_TOOLCALL.equals(subType)) {
+            String toolName = template.hasMetaAttr(TemplateConstants.ATTR_TOOL_NAME, false)
+                ? template.getMetaAttr(TemplateConstants.ATTR_TOOL_NAME, false).getValueAsString()
+                : null;
+            if (toolName == null || toolName.isEmpty()) {
+                throw new MetaDataException(
+                    ErrorMessageConstants.ERR_MISSING_REQUIRED_ATTR
+                        + ": template.toolcall '" + template.getName() + "' is missing required @toolName",
+                    ErrorCode.ERR_MISSING_REQUIRED_ATTR, template.getSource());
+            }
+            if (payloadRef == null || payloadRef.isEmpty()) {
+                throw new MetaDataException(
+                    ErrorMessageConstants.ERR_MISSING_REQUIRED_ATTR
+                        + ": template.toolcall '" + template.getName() + "' is missing required @payloadRef",
+                    ErrorCode.ERR_MISSING_REQUIRED_ATTR, template.getSource());
+            }
+        }
+
         // R2 + R3 only apply if @payloadRef is set
         if (payloadRef == null || payloadRef.isEmpty()) return;
 
diff --git a/server/java/metadata/src/main/java/com/metaobjects/template/TemplateConstants.java b/server/java/metadata/src/main/java/com/metaobjects/template/TemplateConstants.java
@@ -18,8 +18,16 @@ private TemplateConstants() {}
     public static final String SUBTYPE_BASE = "base";
     public static final String SUBTYPE_PROMPT = "prompt";
     public static final String SUBTYPE_OUTPUT = "output";
+    /**
+     * LLM tool-call envelope subtype (ADR-0011). Does NOT inherit the
+     * generic prompt/output attrs — declares its own minimal set
+     * ({@code @toolName} required, {@code @payloadRef} required, plus
+     * governance {@code @owner} / {@code @since}). No {@code @textRef}
+     * requirement: a tool-call has no renderable text body.
+     */
+    public static final String SUBTYPE_TOOLCALL = "toolcall";
 
-    // --- Generic attributes (both subtypes) ---
+    // --- Generic attributes (prompt + output; NOT inherited by toolcall) ---
     public static final String ATTR_PAYLOAD_REF = "payloadRef";
     public static final String ATTR_TEXT_REF = "textRef";
     public static final String ATTR_FORMAT = "format";
@@ -33,6 +41,18 @@ private TemplateConstants() {}
     public static final String ATTR_REQUIRED_SLOTS = "requiredSlots";
     public static final String ATTR_MODEL = "model";
 
+    // --- Toolcall-specific attributes (template.toolcall only — ADR-0011) ---
+    //
+    // Vendor-agnostic in core; vendor wire details (retry semantics, fallback
+    // shapes, parallel invocation, cache hints) are added by consumer providers
+    // — the cross-port equivalent of TypeScript's registry.extend.
+    //
+    // @description is intentionally NOT a toolcall-specific constant — every type
+    // gets @description via the documentation common-attrs provider. Tool
+    // descriptions surfaced to the LLM use the same @description common attr
+    // doc-gen uses.
+    public static final String ATTR_TOOL_NAME = "toolName";
+
     // --- @format closed value set ---
     public static final String FORMAT_TEXT = "text";
     public static final String FORMAT_HTML = "html";
diff --git a/server/java/metadata/src/main/java/com/metaobjects/template/TemplateTypesMetaDataProvider.java b/server/java/metadata/src/main/java/com/metaobjects/template/TemplateTypesMetaDataProvider.java
@@ -6,10 +6,11 @@
 /**
  * Template Types MetaData provider.
  *
- * <p>Registers the abstract {@code template.base} type plus the two concrete
- * subtypes {@code template.prompt} and {@code template.output} (FR-004 fourth
- * pillar: cross-language prompt construction). Depends on {@code core-types}
- * for {@code metadata.base} inheritance.</p>
+ * <p>Registers the abstract {@code template.base} type plus the three concrete
+ * subtypes {@code template.prompt}, {@code template.output} (FR-004 fourth
+ * pillar: cross-language prompt construction) and {@code template.toolcall}
+ * (ADR-0011: LLM tool-call envelope). Depends on {@code core-types} for
+ * {@code metadata.base} inheritance.</p>
  *
  * <p>Discovered via the standard {@link MetaDataTypeProvider} ServiceLoader
  * mechanism — wired through
@@ -25,6 +26,10 @@ public void registerTypes(MetaDataRegistry registry) {
         // Register concrete template subtypes.
         PromptTemplate.registerTypes(registry);
         OutputTemplate.registerTypes(registry);
+        // ADR-0011 — toolcall is a sibling subtype that does NOT inherit
+        // template.base's shared attrs (no @textRef requirement; the body IS
+        // the structured output schema resolved via @payloadRef).
+        ToolcallTemplate.registerTypes(registry);
 
         // Root-level acceptance for template.* is declared on metadata.root in
         // MetaRoot's static initializer alongside object/field/attr/validator/view/
@@ -43,6 +48,6 @@ public String[] getDependencies() {
 
     @Override
     public String getDescription() {
-        return "Template Types (prompt / output — FR-004 cross-language prompt construction)";
+        return "Template Types (prompt / output / toolcall — FR-004 + ADR-0011 cross-language prompt construction)";
     }
 }
diff --git a/server/java/metadata/src/main/java/com/metaobjects/template/ToolcallTemplate.java b/server/java/metadata/src/main/java/com/metaobjects/template/ToolcallTemplate.java
@@ -0,0 +1,68 @@
+package com.metaobjects.template;
+
+import com.metaobjects.attr.StringAttribute;
+import com.metaobjects.registry.MetaDataRegistry;
+
+import static com.metaobjects.template.TemplateConstants.*;
+
+/**
+ * LLM tool-call envelope template ({@code template.toolcall}) — ADR-0011.
+ *
+ * <p>Vendor-agnostic in core; vendor wire details (Anthropic's retry-with-reminder,
+ * OpenAI's function-calling envelope, MCP's tool definitions, etc.) are NOT in
+ * core. Consumers add vendor specifics via a provider that registers additional
+ * attrs on this subtype (the Java port's equivalent of TypeScript's
+ * {@code registry.extend(TYPE_TEMPLATE, "toolcall", ...)} mechanism).
+ *
+ * <p>Crucially: {@code template.toolcall} does NOT inherit the generic
+ * {@code @payloadRef}/{@code @textRef}/{@code @format} attrs that
+ * {@link PromptTemplate} and {@link OutputTemplate} share. It declares its own
+ * minimal set: required {@code @toolName} + required {@code @payloadRef} +
+ * governance {@code @owner}/{@code @since}. {@code @textRef} is intentionally
+ * absent — a tool-call has no renderable text body; the body IS the structured
+ * output schema resolved via {@code @payloadRef}.
+ *
+ * <p>{@code @description} is intentionally NOT declared here — it's added to
+ * every type by the documentation common-attrs provider. Tool descriptions
+ * surfaced to the LLM use the same {@code @description} common attr that
+ * doc-gen uses.
+ */
+public final class ToolcallTemplate extends MetaTemplate {
+
+    public ToolcallTemplate(String name) {
+        super(SUBTYPE_TOOLCALL, name);
+    }
+
+    public static void registerTypes(MetaDataRegistry registry) {
+        registry.registerType(ToolcallTemplate.class, def -> {
+            // ADR-0011: toolcall does NOT inheritsFrom template.base because the
+            // shared @textRef / @format / @maxChars / @requiredTags attrs do NOT
+            // apply to toolcall. Bind directly to metadata.base instead — match
+            // template.base's own inheritance.
+            def.type(TYPE_TEMPLATE).subType(SUBTYPE_TOOLCALL)
+               .description("Template (LLM tool-call envelope) — ADR-0011")
+               .inheritsFrom(com.metaobjects.MetaData.TYPE_METADATA,
+                             com.metaobjects.MetaData.SUBTYPE_BASE)
+               // Accept any attr child (vendor providers add their own).
+               .optionalChild(com.metaobjects.attr.MetaAttribute.TYPE_ATTR, "*", "*");
+
+            // Required + optional toolcall-specific attrs. Mirrors the TS
+            // toolcallAttrs list in template-schema.ts.
+            def.requiredAttributeWithConstraints(ATTR_TOOL_NAME)
+               .ofType(StringAttribute.SUBTYPE_STRING).asSingle();
+            def.requiredAttributeWithConstraints(ATTR_PAYLOAD_REF)
+               .ofType(StringAttribute.SUBTYPE_STRING).asSingle();
+            def.optionalAttributeWithConstraints(ATTR_OWNER)
+               .ofType(StringAttribute.SUBTYPE_STRING).asSingle();
+            def.optionalAttributeWithConstraints(ATTR_SINCE)
+               .ofType(StringAttribute.SUBTYPE_STRING).asSingle();
+        });
+    }
+
+    /** Returns the raw value of {@code @toolName}, or {@code null} if absent. */
+    public String getToolName() {
+        return hasMetaAttr(ATTR_TOOL_NAME, false)
+            ? getMetaAttr(ATTR_TOOL_NAME, false).getValueAsString()
+            : null;
+    }
+}
diff --git a/server/java/metadata/src/test/java/com/metaobjects/template/TemplateToolcallTest.java b/server/java/metadata/src/test/java/com/metaobjects/template/TemplateToolcallTest.java
@@ -0,0 +1,156 @@
+package com.metaobjects.template;
+
+import com.metaobjects.ErrorCode;
+import com.metaobjects.MetaData;
+import com.metaobjects.MetaDataException;
+import com.metaobjects.loader.InMemoryStringSource;
+import com.metaobjects.loader.MetaDataLoader;
+import com.metaobjects.registry.MetaDataRegistry;
+import com.metaobjects.registry.SharedRegistryTestBase;
+import com.metaobjects.registry.TypeDefinition;
+import org.junit.Test;
+
+import java.util.Collections;
+import java.util.List;
+
+import static org.junit.Assert.*;
+
+/**
+ * Unit tests for {@code template.toolcall} — the third core template subtype
+ * shipped in {@code 0.7.0-rc.7} per ADR-0011, mirroring the TS port's rc.5
+ * delivery.
+ *
+ * <p>Toolcall is a sibling of {@link PromptTemplate} and {@link OutputTemplate}
+ * but does NOT inherit the generic {@code @payloadRef} / {@code @textRef} /
+ * {@code @format} attrs — it declares its own minimal set ({@code @toolName}
+ * required + {@code @payloadRef} required + governance {@code @owner} /
+ * {@code @since}). No {@code @textRef} requirement because a tool-call has no
+ * renderable text body; the body IS the structured output schema resolved via
+ * {@code @payloadRef}.
+ *
+ * <p>Vendor wire details (Anthropic's retry-with-reminder, OpenAI's function-
+ * calling envelope, MCP's tool definitions, etc.) are NOT in core. Consumers
+ * add vendor specifics via a project-local provider that registers additional
+ * attrs on this subtype.
+ */
+public class TemplateToolcallTest extends SharedRegistryTestBase {
+
+    // ---- registry shape ----------------------------------------------------
+
+    @Test
+    public void coreProviderRegistersTemplateToolcallSubtype() {
+        MetaDataRegistry registry = MetaDataRegistry.getInstance();
+        TypeDefinition def = registry.getTypeDefinition(
+            TemplateConstants.TYPE_TEMPLATE, TemplateConstants.SUBTYPE_TOOLCALL);
+        assertNotNull("template.toolcall should be registered by the template-types provider", def);
+        assertEquals(ToolcallTemplate.class, def.getImplementationClass());
+    }
+
+    @Test
+    public void templateSubtypeToolcallConstantMatches() {
+        assertEquals("toolcall", TemplateConstants.SUBTYPE_TOOLCALL);
+        assertEquals("toolName", TemplateConstants.ATTR_TOOL_NAME);
+    }
+
+    // ---- loader: positive + negative paths --------------------------------
+
+    private static final String TOOLCALL_OK =
+        "{ \"metadata.root\": { \"package\": \"acme::tools\", \"children\": [" +
+        "  { \"object.value\": { \"name\": \"WeatherToolOutput\", \"children\": [" +
+        "    { \"field.string\": { \"name\": \"summary\" } }," +
+        "    { \"field.int\":    { \"name\": \"tempCelsius\" } }" +
+        "  ] } }," +
+        "  { \"template.toolcall\": {" +
+        "      \"name\": \"lookupWeather\"," +
+        "      \"@toolName\": \"lookup_weather\"," +
+        "      \"@payloadRef\": \"WeatherToolOutput\"," +
+        "      \"@owner\": \"tools-team\"," +
+        "      \"@since\": \"0.7.0\" } }" +
+        "] } }";
+
+    private static final String TOOLCALL_MISSING_TOOL_NAME =
+        "{ \"metadata.root\": { \"package\": \"acme::tools\", \"children\": [" +
+        "  { \"object.value\": { \"name\": \"Out\", \"children\": [" +
+        "    { \"field.string\": { \"name\": \"x\" } }" +
+        "  ] } }," +
+        "  { \"template.toolcall\": {" +
+        "      \"name\": \"missingToolName\"," +
+        "      \"@payloadRef\": \"Out\" } }" +
+        "] } }";
+
+    private static final String TOOLCALL_MISSING_PAYLOAD_REF =
+        "{ \"metadata.root\": { \"package\": \"acme::tools\", \"children\": [" +
+        "  { \"template.toolcall\": {" +
+        "      \"name\": \"missingPayloadRef\"," +
+        "      \"@toolName\": \"do_thing\" } }" +
+        "] } }";
+
+    private static final String TOOLCALL_BAD_PAYLOAD_REF =
+        "{ \"metadata.root\": { \"package\": \"acme::tools\", \"children\": [" +
+        "  { \"template.toolcall\": {" +
+        "      \"name\": \"danglingPayload\"," +
+        "      \"@toolName\": \"do_thing\"," +
+        "      \"@payloadRef\": \"DoesNotExist\" } }" +
+        "] } }";
+
+    private MetaDataLoader newTestLoader() {
+        return createTestLoader("TemplateToolcallTest", Collections.emptyList());
+    }
+
+    @Test
+    public void toolcallLoadsWithRequiredAttrs() {
+        MetaDataLoader loader = newTestLoader();
+        loader.load(List.of(new InMemoryStringSource(TOOLCALL_OK, "toolcall-ok.json")));
+
+        MetaData node = loader.getRoot().getChildOfType(
+            TemplateConstants.TYPE_TEMPLATE, "acme::tools::lookupWeather");
+        assertNotNull("template.toolcall node should load", node);
+        assertEquals(TemplateConstants.SUBTYPE_TOOLCALL, node.getSubType());
+        assertTrue("expected ToolcallTemplate instance", node instanceof ToolcallTemplate);
+
+        ToolcallTemplate tc = (ToolcallTemplate) node;
+        assertEquals("lookup_weather", tc.getToolName());
+        assertEquals("WeatherToolOutput", tc.getPayloadRef());
+        assertEquals("tools-team", tc.getOwner());
+        assertEquals("0.7.0", tc.getSince());
+    }
+
+    @Test
+    public void toolcallMissingToolNameRaisesMissingRequired() {
+        try {
+            newTestLoader().load(List.of(new InMemoryStringSource(
+                TOOLCALL_MISSING_TOOL_NAME, "toolcall-missing-tool-name.json")));
+            fail("expected MetaDataException for missing @toolName");
+        } catch (MetaDataException ex) {
+            assertEquals(ErrorCode.ERR_MISSING_REQUIRED_ATTR, ex.getCode().orElse(null));
+            assertTrue("expected message to mention @toolName: " + ex.getMessage(),
+                ex.getMessage().contains("@toolName"));
+        }
+    }
+
+    @Test
+    public void toolcallMissingPayloadRefRaisesMissingRequired() {
+        try {
+            newTestLoader().load(List.of(new InMemoryStringSource(
+                TOOLCALL_MISSING_PAYLOAD_REF, "toolcall-missing-payload-ref.json")));
+            fail("expected MetaDataException for missing @payloadRef");
+        } catch (MetaDataException ex) {
+            assertEquals(ErrorCode.ERR_MISSING_REQUIRED_ATTR, ex.getCode().orElse(null));
+            assertTrue("expected message to mention @payloadRef: " + ex.getMessage(),
+                ex.getMessage().contains("@payloadRef"));
+        }
+    }
+
+    @Test
+    public void toolcallBadPayloadRefRaisesInvalidTemplate() {
+        // The shared @payloadRef must-resolve-to-root-level-object.value rule
+        // applies to toolcall the same as prompt + output.
+        try {
+            newTestLoader().load(List.of(new InMemoryStringSource(
+                TOOLCALL_BAD_PAYLOAD_REF, "toolcall-bad-payload-ref.json")));
+            fail("expected MetaDataException for dangling @payloadRef");
+        } catch (MetaDataException ex) {
+            assertEquals(ErrorCode.ERR_INVALID_TEMPLATE, ex.getCode().orElse(null));
+        }
+    }
+}
