@metaobjectsdev/metadata 0.7.0-rc.1 → 0.7.0-rc.10

package/src/parser-core.ts

@@ -27,11 +27,13 @@ import { TypeId, TypeRegistry } from "./registry.js";
 import type { MetaData } from "./shared/meta-data.js";
 import { MetaRoot } from "./shared/meta-root.js";
 import { MetaAttr } from "./core/attr/meta-attr.js";
-import { inferAttrSubType } from "./serializer-json.js";
+import { canonicalSerialize, inferAttrSubType } from "./serializer-json.js";
 import { ParseError, type ErrorCode } from "./errors.js";
-import type { ErrorSource } from "./source.js";
+import { resolvedSource, type ErrorSource, type LoaderWarning, type Contributor } from "./source.js";
+import { semanticDiff } from "./semantic-diff.js";
 import { resolveSuperRef } from "./super-resolve.js";
 import { JsonPathBuilder } from "./json-path.js";
+import { getYamlPosition, type YamlPosition } from "./core/yaml-positions.js";
 import {
   TYPE_ATTR,
   TYPE_FIELD,
@@ -82,12 +84,27 @@ export interface ParseOptions {
    * another file parsed later.
    */
   deferSuperResolution?: boolean;
+  /**
+   * FR5b — discriminant for the source-on-node envelope's `format` field.
+   * Defaults to `"json"` (parseJson supplies nothing). parseYaml passes
+   * `"yaml"` so populateNodeSource emits `format: "yaml"` and, when the
+   * desugar attached one, the optional `yamlPosition`.
+   */
+  sourceFormat?: "json" | "yaml";
 }
 
 export interface ParseResult {
   root: MetaRoot;
   warnings: string[];
   errors: ParseError[];
+  /**
+   * FR5c — envelope-shaped warnings (e.g. WARN_DUPLICATE_DECLARATION) produced
+   * during the parse/merge pipeline. Distinct from the legacy `warnings:
+   * string[]` channel: those messages get wrapped in a `WARN_LEGACY` envelope
+   * at the loader boundary, while envelope warnings already carry their own
+   * `code` + `source` and are surfaced unchanged. Defaults to `[]`.
+   */
+  envelopeWarnings: LoaderWarning[];
 }
 
 // ---------------------------------------------------------------------------
@@ -102,6 +119,20 @@ export interface ParseResult {
 
 export function errSource(): ErrorSource {
   if (_currentPath !== undefined && _currentSourceId !== undefined) {
+    // FR5b (finalized 2026-05-27, all four ports) — buildTree-emitted errors
+    // from a YAML input now emit `format: "yaml"` (was `"json"` interim while
+    // each port shipped yamlPosition tracking). The optional `yamlPosition`
+    // rides along when the desugar's position map covers the current node.
+    if (_currentFormat === "yaml") {
+      return {
+        format: "yaml",
+        files: [_currentSourceId],
+        jsonPath: _currentPath.toString(),
+        ...(_currentYamlPosition !== undefined
+          ? { yamlPosition: _currentYamlPosition }
+          : {}),
+      };
+    }
     return {
       format: "json",
       files: [_currentSourceId],
@@ -200,20 +231,49 @@ let _deferSuperResolution = false;
 // _deferSuperResolution.
 let _currentErrors: ParseError[] | undefined;
 
+// FR5c — envelope-warnings sink for the merge phase. Set at buildTree entry
+// so deeply-nested merge sites can emit WARN_DUPLICATE_DECLARATION without
+// threading another parameter through every helper signature. Safe under
+// the same synchronous-buildTree reentrancy argument as the others.
+let _currentEnvelopeWarnings: LoaderWarning[] | undefined;
+
 // FR5a / ADR-0009 — Module-level JSONPath builder + source id, set at
 // buildTree entry and updated by recursive descent (push on the way down,
 // pop on the way back up). Used by populateNodeSource() to stamp every
-// constructed MetaData with `{ format: "json", files: [sourceId], jsonPath }`.
+// constructed MetaData with `{ format: "json"|"yaml", files: [sourceId],
+// jsonPath, [yamlPosition?] }`.
 // Safe because buildTree is synchronous — same reentrancy argument as
 // _currentErrors above.
 let _currentPath: JsonPathBuilder | undefined;
 let _currentSourceId: string | undefined;
-
-/** Set the parsed-from-JSON provenance envelope on a freshly-created node.
- *  No-op when the parser is invoked outside buildTree's setup (defensive — the
- *  module-level state will always be populated during a normal parse). */
+// FR5b — source format discriminant + current node's YAML position, set
+// by the per-child iteration in processChildren (and at root) right before
+// the parseNodeFresh call. The position is read from the wrapper object's
+// position-by-key map (attached by the YAML walker in core/yaml-positions.ts
+// and preserved through core/yaml-desugar.ts).
+let _currentFormat: "json" | "yaml" = "json";
+let _currentYamlPosition: YamlPosition | undefined;
+
+/** FR5a/FR5b — stamp the source-provenance envelope on a freshly-created
+ *  node. No-op when invoked outside buildTree's setup (defensive — the
+ *  module-level state will always be populated during a normal parse).
+ *
+ *  FR5b (finalized 2026-05-27) — YAML-input nodes get `format: "yaml"`
+ *  envelopes (was `"json"` interim). The optional `yamlPosition` rides
+ *  along when the desugar's position map covers the current node. */
 function populateNodeSource(node: MetaData): void {
   if (_currentPath === undefined || _currentSourceId === undefined) return;
+  if (_currentFormat === "yaml") {
+    node.setSource({
+      format: "yaml",
+      files: [_currentSourceId],
+      jsonPath: _currentPath.toString(),
+      ...(_currentYamlPosition !== undefined
+        ? { yamlPosition: _currentYamlPosition }
+        : {}),
+    });
+    return;
+  }
   node.setSource({
     format: "json",
     files: [_currentSourceId],
@@ -235,16 +295,25 @@ function populateNodeSource(node: MetaData): void {
 export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
   const warnings: string[] = [];
   const errors: ParseError[] = [];
+  const envelopeWarnings: LoaderWarning[] = [];
   const strict = opts.strict ?? false;
   const source = opts.sourceName;
   _deferSuperResolution = opts.deferSuperResolution === true;
   _currentErrors = errors;
+  // FR5c — module-level handle so the deeply-nested merge code paths can
+  // emit envelope warnings without threading another parameter through the
+  // entire walk. Safe because buildTree is fully synchronous.
+  _currentEnvelopeWarnings = envelopeWarnings;
   // FR5a — start a fresh JSONPath stack rooted at "$"; sourceId is the
   // source's id (from FileSource / InMemoryStringSource via opts.sourceName).
   // Falls back to "<unknown>" when no name was supplied (e.g. ad-hoc parseJson
   // calls from tests).
   _currentPath = new JsonPathBuilder();
   _currentSourceId = source ?? "<unknown>";
+  // FR5b — propagate the per-parse source-format discriminant. parseJson
+  // omits the option (defaults to "json"); parseYaml supplies "yaml".
+  _currentFormat = opts.sourceFormat ?? "json";
+  _currentYamlPosition = undefined;
 
   try {
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
@@ -304,6 +373,11 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
     // populated with the current source's id (correct: the existing root was
     // already stamped from the file that created it).
     _currentPath!.pushKey(rootKey);
+    // FR5b — look up the root wrapper's YAML position (when in yaml mode)
+    // so parseNodeFresh stamps `source.yamlPosition` on the root node.
+    if (_currentFormat === "yaml") {
+      _currentYamlPosition = getYamlPosition(topLevel, rootKey);
+    }
 
     if (opts.intoRoot !== undefined) {
       // --- Merge mode: parse root's attrs/children into the existing root ---
@@ -325,7 +399,7 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
         rootKey,
       );
       _currentPath!.pop();
-      return { root: opts.intoRoot, warnings, errors };
+      return { root: opts.intoRoot, warnings, errors, envelopeWarnings };
     }
 
     // --- Fresh root mode: create a new root from the JSON ---
@@ -350,12 +424,15 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
       rootKey,
     ) as MetaRoot;
     _currentPath!.pop();
-    return { root, warnings, errors };
+    return { root, warnings, errors, envelopeWarnings };
   } finally {
     _deferSuperResolution = false;
     _currentErrors = undefined;
+    _currentEnvelopeWarnings = undefined;
     _currentPath = undefined;
     _currentSourceId = undefined;
+    _currentFormat = "json";
+    _currentYamlPosition = undefined;
   }
 }
 
@@ -446,9 +523,15 @@ function parseNodeFresh(
     if (superModel !== undefined) {
       model.setSuperResolved(superModel);
     } else {
+      // FR5d — emit format=resolved with referrer + target. referrer is the
+      // declaring node's FQN (we just built it above); target is the
+      // unresolved supertype ref string.
       throw new ParseError(
         `the SuperClass '${model.superRef}' does not exist in file '${source ?? "<unknown>"}'`,
-        { code: "ERR_UNRESOLVED_SUPER", source: errSource() },
+        {
+          code: "ERR_UNRESOLVED_SUPER",
+          source: resolvedSource(errSource(), model.fqn(), model.superRef),
+        },
       );
     }
   } else if (model.superRef !== undefined && accumRoot === undefined) {
@@ -493,6 +576,46 @@ function parseNodeInto(
   source: string | undefined,
   path: string,
 ): void {
+  // FR5c — capture pre-merge state so we can decide whether this contribution
+  // produced any semantic change. The "new contributor" is the file currently
+  // being parsed (_currentSourceId). The "base contributor" is whichever
+  // file(s) the existing target already records on its source envelope.
+  const newContributorFile = _currentSourceId ?? "<unknown>";
+  const targetIsRoot = target instanceof MetaRoot;
+  // The root is a synthetic accumulator: it is not a metadata-author node —
+  // every file declares { "metadata.root": ... } and the loader merges into
+  // a single root. We don't run FR5c diagnostics on the root itself; the
+  // merge attribution applies to author-meaningful nodes (object/field/etc).
+  const fr5cActive = !targetIsRoot && target.name !== "";
+
+  let preMergeShape: string | undefined;
+  let preMergeAttrSnapshot: Map<string, AttrValue> | undefined;
+  if (fr5cActive) {
+    preMergeShape = canonicalSerialize(target);
+    // Snapshot of own attrs (name → value) — used to detect ERR_MERGE_CONFLICT
+    // when a new contribution sets an attr the target already declared to a
+    // different non-empty value.
+    preMergeAttrSnapshot = new Map(target.ownAttrs());
+  }
+
+  // FR5c — detect attribute-level merge conflicts: for each @-prefixed inline
+  // attr in nodeData, if the target already has an own attr of that name
+  // with a non-empty value, AND the new value differs from the existing
+  // value (both sides non-empty), emit ERR_MERGE_CONFLICT with a `format:
+  // "merged"` envelope. Last-writer-wins is preserved for non-conflicting
+  // cases (one side unset, same value, etc.) — those carry through to the
+  // existing applyInlineAttrsAndUnknownKeys logic below.
+  if (fr5cActive && preMergeAttrSnapshot !== undefined) {
+    detectAttrMergeConflicts(
+      target,
+      nodeData,
+      preMergeAttrSnapshot,
+      newContributorFile,
+      errors,
+      path,
+    );
+  }
+
   // Apply inline attrs (not reserved keys — those stay on the existing model)
   applyInlineAttrsAndUnknownKeys(target, nodeData, strict, source, path, warnings, registry);
 
@@ -502,6 +625,168 @@ function parseNodeInto(
   const effectivePkg = inheritedContextPkg;
 
   processChildren(target, nodeData, accumRoot, effectivePkg, registry, warnings, errors, strict, source, path);
+
+  // FR5c — after merge: compare pre/post shape. If no semantic change → emit
+  // WARN_DUPLICATE_DECLARATION (the new contribution declared the same thing
+  // the target already had). If there was a change → upgrade the target's
+  // source envelope to `format: "merged"` with both contributors listed
+  // (ADR-0009 §Source-on-node: overlay merge with semantic change updates
+  // source; duplicate-with-no-change leaves source unchanged + emits warning).
+  if (fr5cActive && preMergeShape !== undefined) {
+    const postMergeShape = canonicalSerialize(target);
+    const preParsed = JSON.parse(preMergeShape) as Record<string, unknown>;
+    const postParsed = JSON.parse(postMergeShape) as Record<string, unknown>;
+    const changed = semanticDiff(preParsed, postParsed);
+
+    // Pull the existing contributor file(s) off the target's current source
+    // envelope (set at parse-fresh time or by a previous merge).
+    const existing = target.source;
+    const existingFiles = "files" in existing ? [...existing.files] : [];
+
+    if (changed) {
+      // Real overlay — upgrade source to merged with contributors.
+      const allFiles = [...new Set([...existingFiles, newContributorFile])];
+      // Alphabetical sort — matches DirectorySource ordering and gives a
+      // deterministic cross-port file list (ADR-0009 §"Cross-port adoption").
+      allFiles.sort();
+      const contributors: Contributor[] = allFiles.map((f, i) => ({
+        file: f,
+        role: i === 0 ? "overlay-base" : "overlay-extension",
+      }));
+      const mergedSource: ErrorSource = {
+        format: "merged",
+        files: allFiles,
+        jsonPath:
+          "jsonPath" in existing && existing.jsonPath !== undefined
+            ? existing.jsonPath
+            : (_currentPath?.toString() ?? "$"),
+        contributors,
+      };
+      target.setSource(mergedSource);
+    } else if (
+      existingFiles.length > 0 &&
+      !existingFiles.includes(newContributorFile)
+    ) {
+      // Identical re-declaration from a different file → warn.
+      const allFiles = [...new Set([...existingFiles, newContributorFile])];
+      allFiles.sort();
+      const contributors: Contributor[] = allFiles.map((f, i) => ({
+        file: f,
+        role: i === 0 ? "overlay-base" : "overlay-extension",
+      }));
+      const warnSource: ErrorSource = {
+        format: "merged",
+        files: allFiles,
+        jsonPath:
+          "jsonPath" in existing && existing.jsonPath !== undefined
+            ? existing.jsonPath
+            : (_currentPath?.toString() ?? "$"),
+        contributors,
+      };
+      _currentEnvelopeWarnings?.push({
+        code: "WARN_DUPLICATE_DECLARATION",
+        message: `duplicate declaration of ${target.fqn()} with no semantic change`,
+        source: warnSource,
+      });
+    }
+  }
+}
+
+/** FR5c — for every @-prefixed inline attr in `nodeData`, check whether the
+ *  target already declares the same attr (in `preAttrs`) with a different
+ *  non-empty value. If so, emit ERR_MERGE_CONFLICT with a `format: "merged"`
+ *  envelope naming both contributors. The merge itself proceeds (existing
+ *  last-writer-wins) so the loader sees one canonical tree; the error
+ *  surfaces the conflict so a consumer can fix the metadata. */
+function detectAttrMergeConflicts(
+  target: MetaData,
+  nodeData: Record<string, unknown>,
+  preAttrs: Map<string, AttrValue>,
+  newContributorFile: string,
+  errors: ParseError[],
+  path: string,
+): void {
+  const existingFiles =
+    "files" in target.source ? [...target.source.files] : [];
+
+  function isEmptyValue(v: unknown): boolean {
+    if (v === undefined || v === null) return true;
+    if (typeof v === "string" && v === "") return true;
+    if (Array.isArray(v) && v.length === 0) return true;
+    return false;
+  }
+
+  function attrValuesEqual(a: AttrValue, b: AttrValue): boolean {
+    // String/number/boolean — direct compare.
+    if (a === b) return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+      if (a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) return false;
+      }
+      return true;
+    }
+    if (
+      typeof a === "object" && a !== null && !Array.isArray(a) &&
+      typeof b === "object" && b !== null && !Array.isArray(b)
+    ) {
+      // Object attrs — structural compare via JSON (key order independent
+      // through Object.keys().sort()).
+      try {
+        const ak = Object.keys(a).sort();
+        const bk = Object.keys(b).sort();
+        if (ak.length !== bk.length) return false;
+        for (let i = 0; i < ak.length; i++) {
+          if (ak[i] !== bk[i]) return false;
+          if (JSON.stringify((a as Record<string, unknown>)[ak[i]!]) !==
+              JSON.stringify((b as Record<string, unknown>)[bk[i]!])) {
+            return false;
+          }
+        }
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+
+  for (const key of Object.keys(nodeData)) {
+    if (!key.startsWith(ATTR_PREFIX)) continue;
+    if (RESERVED_KEYS.has(key)) continue;
+    const attrName = key.slice(ATTR_PREFIX.length);
+    if (RESERVED_KEYS.has(attrName)) continue;
+
+    const newValRaw = nodeData[key];
+    const existingVal = preAttrs.get(attrName);
+
+    if (existingVal === undefined) continue;
+    if (isEmptyValue(newValRaw) || isEmptyValue(existingVal)) continue;
+    // Both sides set a non-empty value — compare. If equal, last-writer-wins
+    // is a no-op; if different, that's a conflict.
+    if (attrValuesEqual(existingVal, newValRaw as AttrValue)) continue;
+
+    const allFiles = [...new Set([...existingFiles, newContributorFile])];
+    allFiles.sort();
+    const contributors: Contributor[] = allFiles.map((f, i) => ({
+      file: f,
+      role: i === 0 ? "overlay-base" : "overlay-extension",
+    }));
+    const conflictSource: ErrorSource = {
+      format: "merged",
+      files: allFiles,
+      jsonPath: `${_currentPath?.toString() ?? path}.${ATTR_PREFIX}${attrName}`,
+      contributors,
+    };
+    errors.push(
+      new ParseError(
+        `attr '${ATTR_PREFIX}${attrName}' conflicts: existing value ` +
+          `${JSON.stringify(existingVal)} differs from new value ` +
+          `${JSON.stringify(newValRaw)} on ${target.fqn()}`,
+        { code: "ERR_MERGE_CONFLICT", source: conflictSource },
+      ),
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -794,6 +1079,14 @@ function processChildren(
     const childData = childRecord[childKey];
     const childNodePath = `${childPath}.${childKey}`;
     _currentPath?.pushKey(childKey);
+    // FR5b — set the current node's YAML position (if any) before the
+    // create/merge call. Save the parent's position to restore after the
+    // recursion returns (children may push deeper positions during their
+    // own processChildren walk).
+    const savedYamlPosition = _currentYamlPosition;
+    if (_currentFormat === "yaml") {
+      _currentYamlPosition = getYamlPosition(childRecord, childKey);
+    }
 
     if (typeof childData !== "object" || childData === null || Array.isArray(childData)) {
       reportProblem(
@@ -802,6 +1095,7 @@ function processChildren(
       );
       _currentPath?.pop(); // pop child wrapper key
       _currentPath?.pop(); // pop array index
+      _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
       continue;
     }
 
@@ -828,6 +1122,7 @@ function processChildren(
         );
         _currentPath?.pop(); // pop child wrapper key
         _currentPath?.pop(); // pop array index
+        _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
         continue; // skip this child
       }
     }
@@ -858,6 +1153,7 @@ function processChildren(
     }
     _currentPath?.pop(); // pop child wrapper key
     _currentPath?.pop(); // pop array index
+    _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
   }
   _currentPath?.pop(); // pop the "children" key
 }

package/src/source.ts

@@ -7,9 +7,17 @@
 // them byte-identically.
 
 /** Discriminated union over the provenance variants a metadata node or error
- *  can carry. See ADR-0009 §Decision for the canonical shape. */
+ *  can carry. See ADR-0009 §Decision for the canonical shape.
+ *
+ *  FR5b note (finalized 2026-05-27, all four ports): buildTree-emitted errors
+ *  from a YAML input emit `format: "yaml"` and carry the optional
+ *  `yamlPosition` (line/col from the desugar's position map). The
+ *  `yamlPosition` field is also declared optionally on the `format: "json"`
+ *  variant for backward shape-compat with any FR5b-interim envelopes still
+ *  serialized to disk; new YAML errors no longer use that variant. */
 export type ErrorSource =
-  | { format: "json"; files: [string]; jsonPath: string }
+  | { format: "json"; files: [string]; jsonPath: string;
+      yamlPosition?: { line: number; col: number } }
   | { format: "yaml"; files: [string]; jsonPath: string;
       yamlPosition?: { line: number; col: number } }
   | { format: "merged"; files: string[]; jsonPath: string;
@@ -59,3 +67,33 @@ export interface LoaderWarning {
 export function codeSource(caller?: string): ErrorSource {
   return caller ? { format: "code", caller } : { format: "code" };
 }
+
+/** FR5d — build a `format: "resolved"` envelope from a referrer node's source
+ *  envelope (typically a `format: "json"` or `format: "yaml"` parse-time
+ *  source) plus the referrer FQN and unresolved target string.
+ *
+ *  The resolved envelope carries:
+ *    - `files`: the referrer's source files (so editors can jump to it),
+ *    - `jsonPath`: the referrer's jsonPath when known (the location of the
+ *       broken reference on disk),
+ *    - `referrer`: the FQN of the metadata node that declared the broken
+ *       reference (e.g. "myapp::content::Video"),
+ *    - `target`:  the unresolved reference string itself (e.g. "BaseEntity",
+ *       "Program.weeks.invalid", "DoesNotExist").
+ *
+ *  `referrerSource` may be any FR5a variant — we read its files/jsonPath
+ *  best-effort and fall back to an empty `files: []` when the referrer's
+ *  source is itself a `code`/`database` envelope. */
+export function resolvedSource(
+  referrerSource: ErrorSource,
+  referrer: string,
+  target: string,
+): ErrorSource {
+  const files = "files" in referrerSource ? [...referrerSource.files] : [];
+  const jsonPath = "jsonPath" in referrerSource ? referrerSource.jsonPath : undefined;
+  const out: ErrorSource = { format: "resolved", files, referrer, target };
+  if (jsonPath !== undefined) {
+    (out as { jsonPath?: string }).jsonPath = jsonPath;
+  }
+  return out;
+}

package/src/template/template-constants.ts

@@ -1,10 +1,14 @@
-// template.* subtype vocabulary + reserved attribute names (FR-004, R1).
+// template.* subtype vocabulary + reserved attribute names (FR-004, R1; ADR-0011).
 //
-// `template` is the fourth-pillar base type: a renderable text artifact bound to
-// a typed payload. Two subtypes (by audience/structure, NOT by format):
-//   - prompt: LLM-targeted; carries the prompt-overlay attrs and is the home for
-//     future structured-prompt (role/turn/tool) divergence.
+// `template` is the fourth-pillar base type — a typed payload bound to either
+// a rendered text artifact (prompt/output) or to a tool-call envelope.
+// Three subtypes:
+//   - prompt: LLM-targeted renderable text. Carries the prompt-overlay attrs.
+//             Renderable body required via @textRef.
 //   - output: every other rendered artifact (email, export, docs, config).
+//             Renderable body required via @textRef.
+//   - toolcall: LLM tool-call envelope (no renderable body — the body IS the
+//               structured output schema resolved via @payloadRef). Per ADR-0011.
 //
 // Format is the @format ATTRIBUTE (closed set below), never a subtype — the
 // render engine keys its escaper off @format, so a new format costs one escaper
@@ -14,15 +18,18 @@ import { SUBTYPE_BASE } from "../shared/base-types.js";
 
 export const TEMPLATE_SUBTYPE_PROMPT = "prompt";
 export const TEMPLATE_SUBTYPE_OUTPUT = "output";
+export const TEMPLATE_SUBTYPE_TOOLCALL = "toolcall";
 
 export const TEMPLATE_SUBTYPES = [
   SUBTYPE_BASE,
   TEMPLATE_SUBTYPE_PROMPT,
   TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_SUBTYPE_TOOLCALL,
 ] as const;
 export type TemplateSubType = (typeof TEMPLATE_SUBTYPES)[number];
 
-// Generic reserved attrs (both subtypes). The "@" is applied at wire time.
+// Generic reserved attrs (prompt + output). The "@" is applied at wire time.
+// NOT inherited by toolcall — toolcall has no renderable body.
 export const TEMPLATE_ATTR_PAYLOAD_REF = "payloadRef";
 export const TEMPLATE_ATTR_TEXT_REF = "textRef";
 export const TEMPLATE_ATTR_FORMAT = "format";
@@ -39,6 +46,16 @@ export const TEMPLATE_ATTR_MAX_TOKENS = "maxTokens";
 export const TEMPLATE_ATTR_REQUIRED_SLOTS = "requiredSlots";
 export const TEMPLATE_ATTR_MODEL = "model";
 
+// Toolcall-specific attrs (template.toolcall only). Vendor-agnostic; vendor
+// wire details (retry semantics, fallback shapes, etc.) are added by consumer
+// providers via registry.extend per ADR-0011.
+//
+// @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.
+export const TEMPLATE_ATTR_TOOL_NAME = "toolName";
+
 // Closed format set — escaping/whitespace behavior is keyed off this in the
 // render engine's escaper registry (FR-004 R7).
 export const TEMPLATE_FORMATS = [

package/src/template/template-schema.ts

@@ -16,6 +16,7 @@ import { SUBTYPE_BASE } from "../shared/base-types.js";
 import {
   TEMPLATE_SUBTYPE_PROMPT,
   TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_SUBTYPE_TOOLCALL,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_FORMAT,
@@ -26,6 +27,7 @@ import {
   TEMPLATE_ATTR_MAX_TOKENS,
   TEMPLATE_ATTR_REQUIRED_SLOTS,
   TEMPLATE_ATTR_MODEL,
+  TEMPLATE_ATTR_TOOL_NAME,
   TEMPLATE_FORMATS,
 } from "./template-constants.js";
 
@@ -99,8 +101,49 @@ const promptOverlayAttrs: AttrSchema[] = [
   },
 ];
 
+// Toolcall attrs (template.toolcall only — does NOT inherit genericAttrs).
+// Per ADR-0011: vendor-agnostic in core; vendor wire details (retry semantics,
+// fallback shapes, parallel invocation, cache hints) added by consumer
+// providers via registry.extend(TYPE_TEMPLATE, "toolcall", { attributes: [...] }).
+//
+// Critical: @textRef is intentionally NOT required here. A tool-call has no
+// renderable text body — the body IS the structured output schema resolved
+// via @payloadRef. This is the design rationale for toolcall being its own
+// subtype rather than template.output + @toolName.
+//
+// @description is intentionally NOT declared here — it's already a documentation
+// common attr added to every type by docProvider. Tool descriptions surfaced to
+// the LLM read the same @description common attr that doc-gen uses.
+const toolcallAttrs: AttrSchema[] = [
+  {
+    name: TEMPLATE_ATTR_TOOL_NAME,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: true,
+    description: "Wire tool name surfaced to the LLM (vendor-specific format).",
+  },
+  {
+    name: TEMPLATE_ATTR_PAYLOAD_REF,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: true,
+    description: "Output value-object the tool produces (resolved against the metamodel).",
+  },
+  {
+    name: TEMPLATE_ATTR_OWNER,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Governance: the owner of this toolcall.",
+  },
+  {
+    name: TEMPLATE_ATTR_SINCE,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Governance: the version this toolcall was introduced in.",
+  },
+];
+
 export const TEMPLATE_ATTRS_MAP = new Map<string, AttrSchema[]>([
   [SUBTYPE_BASE, []],
   [TEMPLATE_SUBTYPE_PROMPT, [...genericAttrs, ...promptOverlayAttrs]],
   [TEMPLATE_SUBTYPE_OUTPUT, [...genericAttrs]],
+  [TEMPLATE_SUBTYPE_TOOLCALL, [...toolcallAttrs]],
 ]);