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

package/dist/template/template-constants.js

@@ -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
@@ -12,12 +16,15 @@
 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,
 ];
-// 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";
@@ -32,6 +39,15 @@ export const TEMPLATE_ATTR_REQUIRED_TAGS = "requiredTags";
 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/dist/template/template-constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"template-constants.js","sourceRoot":"","sources":["../../src/template/template-constants.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,iFAAiF;AACjF,wEAAwE;AACxE,iFAAiF;AACjF,4DAA4D;AAC5D,2EAA2E;AAC3E,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,6DAA6D;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,MAAM,uBAAuB,GAAG,QAAQ,CAAC;AAChD,MAAM,CAAC,MAAM,uBAAuB,GAAG,QAAQ,CAAC;AAEhD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,YAAY;IACZ,uBAAuB;IACvB,uBAAuB;CACf,CAAC;AAGX,2EAA2E;AAC3E,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAY,CAAC;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAC7C,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC;AAClD,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAC3C,mFAAmF;AACnF,+EAA+E;AAC/E,uDAAuD;AACvD,MAAM,CAAC,MAAM,2BAA2B,GAAG,cAAc,CAAC;AAE1D,+CAA+C;AAC/C,MAAM,CAAC,MAAM,wBAAwB,GAAG,WAAW,CAAC;AACpD,MAAM,CAAC,MAAM,4BAA4B,GAAG,eAAe,CAAC;AAC5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C,4EAA4E;AAC5E,gDAAgD;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM;IACN,MAAM;IACN,KAAK;IACL,KAAK;IACL,MAAM;IACN,UAAU;IACV,aAAa;CACL,CAAC"}
+{"version":3,"file":"template-constants.js","sourceRoot":"","sources":["../../src/template/template-constants.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,EAAE;AACF,8EAA8E;AAC9E,uEAAuE;AACvE,kBAAkB;AAClB,8EAA8E;AAC9E,qDAAqD;AACrD,2EAA2E;AAC3E,qDAAqD;AACrD,6EAA6E;AAC7E,kFAAkF;AAClF,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,6DAA6D;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,MAAM,uBAAuB,GAAG,QAAQ,CAAC;AAChD,MAAM,CAAC,MAAM,uBAAuB,GAAG,QAAQ,CAAC;AAChD,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAU,CAAC;AAEpD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,YAAY;IACZ,uBAAuB;IACvB,uBAAuB;IACvB,yBAAyB;CACjB,CAAC;AAGX,6EAA6E;AAC7E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAY,CAAC;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAC7C,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC;AAClD,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAC3C,mFAAmF;AACnF,+EAA+E;AAC/E,uDAAuD;AACvD,MAAM,CAAC,MAAM,2BAA2B,GAAG,cAAc,CAAC;AAE1D,+CAA+C;AAC/C,MAAM,CAAC,MAAM,wBAAwB,GAAG,WAAW,CAAC;AACpD,MAAM,CAAC,MAAM,4BAA4B,GAAG,eAAe,CAAC;AAC5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C,4EAA4E;AAC5E,8EAA8E;AAC9E,8CAA8C;AAC9C,EAAE;AACF,8EAA8E;AAC9E,sEAAsE;AACtE,yEAAyE;AACzE,gBAAgB;AAChB,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC;AAElD,4EAA4E;AAC5E,gDAAgD;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM;IACN,MAAM;IACN,KAAK;IACL,KAAK;IACL,MAAM;IACN,UAAU;IACV,aAAa;CACL,CAAC"}

package/dist/template/template-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-schema.d.ts","sourceRoot":"","sources":["../../src/template/template-schema.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AA6FjD,eAAO,MAAM,kBAAkB,2BAI7B,CAAC"}
+{"version":3,"file":"template-schema.d.ts","sourceRoot":"","sources":["../../src/template/template-schema.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAuIjD,eAAO,MAAM,kBAAkB,2BAK7B,CAAC"}

package/dist/template/template-schema.js

@@ -7,7 +7,7 @@
 // `verify` scope (Plan #3), not load-time validation.
 import { ATTR_SUBTYPE_STRING, ATTR_SUBTYPE_INT, ATTR_SUBTYPE_STRINGARRAY, } from "../core/attr/attr-constants.js";
 import { SUBTYPE_BASE } from "../shared/base-types.js";
-import { TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT, TEMPLATE_ATTR_MAX_CHARS, TEMPLATE_ATTR_OWNER, TEMPLATE_ATTR_SINCE, TEMPLATE_ATTR_REQUIRED_TAGS, TEMPLATE_ATTR_MAX_TOKENS, TEMPLATE_ATTR_REQUIRED_SLOTS, TEMPLATE_ATTR_MODEL, TEMPLATE_FORMATS, } from "./template-constants.js";
+import { TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_SUBTYPE_TOOLCALL, TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT, TEMPLATE_ATTR_MAX_CHARS, TEMPLATE_ATTR_OWNER, TEMPLATE_ATTR_SINCE, TEMPLATE_ATTR_REQUIRED_TAGS, TEMPLATE_ATTR_MAX_TOKENS, TEMPLATE_ATTR_REQUIRED_SLOTS, TEMPLATE_ATTR_MODEL, TEMPLATE_ATTR_TOOL_NAME, TEMPLATE_FORMATS, } from "./template-constants.js";
 // Generic attrs shared by template.prompt and template.output.
 const genericAttrs = [
     {
@@ -76,9 +76,49 @@ const promptOverlayAttrs = [
         description: "Target model id (LLM-specific).",
     },
 ];
+// 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 = [
+    {
+        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([
     [SUBTYPE_BASE, []],
     [TEMPLATE_SUBTYPE_PROMPT, [...genericAttrs, ...promptOverlayAttrs]],
     [TEMPLATE_SUBTYPE_OUTPUT, [...genericAttrs]],
+    [TEMPLATE_SUBTYPE_TOOLCALL, [...toolcallAttrs]],
 ]);
 //# sourceMappingURL=template-schema.js.map

package/dist/template/template-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"template-schema.js","sourceRoot":"","sources":["../../src/template/template-schema.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,kFAAkF;AAClF,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,sDAAsD;AAGtD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC3B,wBAAwB,EACxB,4BAA4B,EAC5B,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,+DAA+D;AAC/D,MAAM,YAAY,GAAiB;IACjC;QACE,IAAI,EAAE,yBAAyB;QAC/B,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,sFAAsF;KACpG;IACD;QACE,IAAI,EAAE,sBAAsB;QAC5B,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,mGAAmG;KACjH;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,MAAM;QACf,aAAa,EAAE,CAAC,GAAG,gBAAgB,CAAC;QACpC,WAAW,EAAE,yEAAyE;KACvF;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,SAAS,EAAE,gBAAgB;QAC3B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,qDAAqD;KACnE;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,yCAAyC;KACvD;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,0DAA0D;KACxE;IACD;QACE,IAAI,EAAE,2BAA2B;QACjC,SAAS,EAAE,wBAAwB;QACnC,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,kFAAkF;KAChG;CACF,CAAC;AAEF,4CAA4C;AAC5C,MAAM,kBAAkB,GAAiB;IACvC;QACE,IAAI,EAAE,wBAAwB;QAC9B,SAAS,EAAE,gBAAgB;QAC3B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,sDAAsD;KACpE;IACD;QACE,IAAI,EAAE,4BAA4B;QAClC,SAAS,EAAE,wBAAwB;QACnC,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,mEAAmE;KACjF;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,iCAAiC;KAC/C;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAuB;IAC9D,CAAC,YAAY,EAAE,EAAE,CAAC;IAClB,CAAC,uBAAuB,EAAE,CAAC,GAAG,YAAY,EAAE,GAAG,kBAAkB,CAAC,CAAC;IACnE,CAAC,uBAAuB,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC;CAC7C,CAAC,CAAC"}
+{"version":3,"file":"template-schema.js","sourceRoot":"","sources":["../../src/template/template-schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/metadata",
-  "version": "0.7.0-rc.1",
+  "version": "0.7.0-rc.11",
   "description": "Metamodel loader, types, and constants for the MetaObjects standard.",
   "type": "module",
   "main": "./dist/index.js",

package/src/core/parser-yaml.ts

@@ -1,19 +1,31 @@
 // Authoring YAML parser.
 //
-// parseYaml is a front-end: yaml.parse → desugar → the shared buildTree
-// (parser-core.ts). The desugar applies the four authoring-sugar rules so the
-// resulting typed tree is identical to the one the equivalent canonical JSON
-// produces.
+// parseYaml is a front-end: parseYamlWithPositions → desugar → the shared
+// buildTree (parser-core.ts). The desugar applies the four authoring-sugar
+// rules so the resulting typed tree is identical to the one the equivalent
+// canonical JSON produces.
+//
+// FR5b: the parse phase now preserves YAML source positions through the
+// pipeline. parseYamlWithPositions attaches a Symbol-keyed position-by-key
+// map onto every mapping object; desugar shallow-copies that property; and
+// buildTree's `format: "yaml"` mode reads the position when stamping
+// `node.source.yamlPosition` (see parser-core.ts).
 
-import { parse as parseYamlText } from "yaml";
 import { ParseError } from "../errors.js";
 import { buildTree } from "../parser-core.js";
 import type { ParseOptions, ParseResult } from "../parser-core.js";
 import type { ErrorSource } from "../source.js";
 import { desugar } from "./yaml-desugar.js";
+import { parseYamlWithPositions } from "./yaml-positions-walker.js";
 
 /** FR5a / ADR-0009 — build a YAML-source envelope rooted at "$".
- *  yamlPosition is FR5b territory and not populated here. */
+ *  yamlPosition on the envelope is left undefined here; envelopes for
+ *  THROWN parser errors carry positions only when the parse phase pushed
+ *  the path into the live parser-core builder (see populateNodeSource in
+ *  parser-core.ts). Errors raised before buildTree (e.g. yaml syntax
+ *  failures, an empty desugar result) lack a node — `yamlPosition` is
+ *  intentionally omitted, per the spec's "skip on desugar-synthesized
+ *  nodes" decision. */
 function yamlSource(sourceName: string | undefined): ErrorSource {
   return {
     format: "yaml",
@@ -31,7 +43,7 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   // The loader's per-source try/catch collects the throw into LoadResult.errors.
   let parsed: unknown;
   try {
-    parsed = parseYamlText(normalizedContent);
+    parsed = parseYamlWithPositions(normalizedContent).value;
   } catch (err) {
     throw new ParseError(
       `Invalid YAML: ${(err as Error).message}`,
@@ -52,7 +64,10 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
     );
   }
 
-  const result = buildTree(canonical, opts);
+  // FR5b — buildTree needs to know the source-format discriminant so
+  // populateNodeSource emits `format: "yaml"` envelopes (with the
+  // optional yamlPosition) instead of the default `format: "json"`.
+  const result = buildTree(canonical, { ...opts, sourceFormat: "yaml" });
 
   // Merge collected desugar errors ahead of buildTree's own collected errors.
   // Each CollectedError carries its own stable code when set (e.g.
@@ -69,5 +84,6 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
     root: result.root,
     warnings: result.warnings,
     errors: [...desugarParseErrors, ...result.errors],
+    envelopeWarnings: result.envelopeWarnings,
   };
 }

package/src/core/yaml-desugar.ts

@@ -38,6 +38,11 @@ import {
   RESERVED_KEY_IS_ARRAY,
   TYPE_SUBTYPE_SEPARATOR,
 } from "../shared/structural.js";
+import {
+  getPositionMap,
+  setPositionMap,
+  type PositionMap,
+} from "./yaml-positions.js";
 import {
   ATTR_SUBTYPE_STRING,
   ATTR_SUBTYPE_CLASS,
@@ -99,6 +104,11 @@ function desugarNode(
   const rawKey = entries[0]!;
   const rawBody = (input as Record<string, unknown>)[rawKey];
 
+  // FR5b — capture the wrapper-level position-by-key map BEFORE re-keying.
+  // The author's raw key (with `[]` suffix and possibly omitted subType) is
+  // the lookup key; the desugar's canonical key is what we emit.
+  const wrapperPositions = getPositionMap(input);
+
   // Rule 4: a trailing "[]" on the key → isArray.
   let key = rawKey;
   let isArray = false;
@@ -111,7 +121,10 @@ function desugarNode(
   const canonicalKey = resolveKey(key, registry, errors, path);
 
   // Rule 2: a scalar body → { name: <scalar> }.
-  const body = desugarBody(rawBody, registry, canonicalKey, errors, path);
+  // FR5b — propagate the wrapper-key's position into the synthesized body
+  // when the input body was a scalar (no body-side positions to inherit).
+  const wrapperKeyPos = wrapperPositions?.[rawKey];
+  const body = desugarBody(rawBody, registry, canonicalKey, errors, path, wrapperKeyPos);
 
   // Rule 4 (cont.): stamp isArray onto the canonical body.
   if (isArray) body[RESERVED_KEY_IS_ARRAY] = true;
@@ -131,7 +144,16 @@ function desugarNode(
   }
   // A non-array `children` value is left untouched — buildTree reports it.
 
-  return { [canonicalKey]: body };
+  // FR5b — emit a wrapper-level position-by-key map for the canonical wrapper
+  // so buildTree's per-child iteration can read the position via the same
+  // lookup it uses for JSON input. The single key transformation is
+  // rawKey → canonicalKey (Rule 1 fuses the subType, Rule 4 strips `[]`).
+  const outWrapper: Record<string, unknown> = { [canonicalKey]: body };
+  if (wrapperKeyPos !== undefined) {
+    setPositionMap(outWrapper, { [canonicalKey]: wrapperKeyPos });
+  }
+
+  return outWrapper;
 }
 
 // Rule 1 — resolve a possibly-bare key to a fused `type.subType` token.
@@ -169,16 +191,30 @@ function desugarBody(
   canonicalKey: string,
   errors: CollectedError[],
   path: string,
+  /** FR5b — position of the WRAPPER key (the `field.string:` line). Used to
+   *  back-fill `yamlPosition` on synthesized bodies (Rule 2's scalar lift) +
+   *  empty bodies; for mapping bodies we use the body's own position-by-key
+   *  map. */
+  wrapperKeyPos: { line: number; col: number } | undefined,
 ): Record<string, unknown> {
   if (
     typeof rawBody === "string" ||
     typeof rawBody === "number" ||
     typeof rawBody === "boolean"
   ) {
-    return { [RESERVED_KEY_NAME]: rawBody };
+    // FR5b — the synthesized `{ name: rawBody }` has no YAML-side
+    // counterpart; we attribute the `name` slot to the wrapper-key's
+    // position (the only YAML position that meaningfully belongs to this
+    // synthesis).
+    const out: Record<string, unknown> = { [RESERVED_KEY_NAME]: rawBody };
+    if (wrapperKeyPos !== undefined) {
+      setPositionMap(out, { [RESERVED_KEY_NAME]: wrapperKeyPos });
+    }
+    return out;
   }
   if (rawBody === null || rawBody === undefined) {
     // An empty body (`field.string:` with nothing after) → an empty node.
+    // No body keys to position; the wrapper carries the node's position.
     return {};
   }
   if (Array.isArray(rawBody)) {
@@ -192,20 +228,38 @@ function desugarBody(
   // Rule D2 (type-coercion guard).
   const src = rawBody as Record<string, unknown>;
   const out: Record<string, unknown> = {};
+  // FR5b — translate the body's position-by-key map across the sigil-free
+  // rewrite. A bare `filterable` key in the source maps to `@filterable` in
+  // the canonical body; the YAML position belongs to BOTH names (the YAML
+  // author only wrote one). We re-key the position map to match the canonical
+  // body's keys so buildTree's per-attr inspection (FR5b follow-ups, e.g.
+  // ERR_BAD_ATTR_VALUE) can find the position via the canonical key.
+  const srcPositions = getPositionMap(src);
+  const outPositions: PositionMap = {};
+  let hasOutPositions = false;
   const schemaIndex = attrSchemaIndex(registry, canonicalKey);
   for (const key of Object.keys(src)) {
+    let outKey: string;
     if (RESERVED_KEYS.has(key) || key.startsWith(ATTR_PREFIX)) {
       out[key] = src[key];
+      outKey = key;
       // D2 also applies to author-written @-keys (the awkward form).
       const attrName = key.startsWith(ATTR_PREFIX) ? key.slice(ATTR_PREFIX.length) : "";
       if (attrName !== "" && !RESERVED_KEYS.has(attrName)) {
         checkCoercion(attrName, src[key], schemaIndex, errors, path);
       }
     } else {
-      out[`${ATTR_PREFIX}${key}`] = src[key];
+      outKey = `${ATTR_PREFIX}${key}`;
+      out[outKey] = src[key];
       checkCoercion(key, src[key], schemaIndex, errors, path);
     }
+    const pos = srcPositions?.[key];
+    if (pos !== undefined) {
+      outPositions[outKey] = pos;
+      hasOutPositions = true;
+    }
   }
+  if (hasOutPositions) setPositionMap(out, outPositions);
   return out;
 }
 

package/src/core/yaml-positions-walker.ts

@@ -0,0 +1,101 @@
+// FR5b — YAML AST → JS walker that preserves source positions.
+//
+// This module is the only place inside @metaobjectsdev/metadata that
+// imports the `yaml` package. It lives in core/ alongside parser-yaml.ts,
+// and is reached only via that parser — never via src/index.ts. The
+// browser-safety test guards this invariant.
+
+import {
+  parseDocument,
+  isAlias,
+  isMap,
+  isScalar,
+  isSeq,
+  LineCounter,
+  type Document,
+} from "yaml";
+
+import {
+  setPositionMap,
+  type PositionMap,
+} from "./yaml-positions.js";
+
+/** Result of parsing YAML text with positions retained. */
+export interface YamlParseResult {
+  /** The JS object (same shape as `yaml.parse(text)` returns), with
+   *  position-by-key maps attached to every mapping. */
+  value: unknown;
+  /** The yaml library's LineCounter — exposed for callers that need to map
+   *  additional ranges (e.g. surfacing errors raised by the YAML library
+   *  itself). */
+  lineCounter: LineCounter;
+}
+
+/** Parse YAML text and return a JS object with positions attached.
+ *
+ *  Mirrors the contract of `yaml.parse(text)` for the shapes the metaobjects
+ *  authoring grammar uses (mappings, sequences, scalars). Aliases and tags
+ *  are deferred via the underlying parseDocument call — i.e. they resolve as
+ *  the library normally would.
+ *
+ *  Throws on YAML syntax errors (same behavior as `yaml.parse`). */
+export function parseYamlWithPositions(text: string): YamlParseResult {
+  const lineCounter = new LineCounter();
+  const doc = parseDocument(text, { lineCounter });
+  // Surface YAML syntax errors as a throw, matching `yaml.parse` behavior.
+  // (parseDocument collects them rather than throwing.)
+  if (doc.errors.length > 0) {
+    throw doc.errors[0]!;
+  }
+  const value = yamlNodeToJs(doc.contents, lineCounter, doc);
+  return { value, lineCounter };
+}
+
+// Walk a yaml AST node into a JS structure. For each YAMLMap, attach a
+// position-by-key map onto the resulting JS object — the position of each
+// key is the (line, col) of the KEY token in the YAML source.
+function yamlNodeToJs(
+  node: unknown,
+  lineCounter: LineCounter,
+  doc: Document,
+): unknown {
+  if (node === null || node === undefined) return null;
+  if (isScalar(node)) {
+    // Honour the library's default scalar typing (numbers / booleans /
+    // strings / null all come through Scalar.value).
+    return node.value;
+  }
+  if (isAlias(node)) {
+    // Resolve an anchor alias (e.g. `*col` after `&col sku_code`) to its
+    // target value — same behaviour as the library's toJS().
+    const target = node.resolve(doc);
+    return yamlNodeToJs(target, lineCounter, doc);
+  }
+  if (isMap(node)) {
+    const out: Record<string, unknown> = {};
+    const positions: PositionMap = {};
+    let hasAnyPosition = false;
+    for (const pair of node.items) {
+      // Only string-keyed entries are valid in metaobjects authoring; ignore
+      // exotic keys (numeric / complex) — they'd already break the desugar.
+      if (!isScalar(pair.key)) continue;
+      const keyText = String(pair.key.value);
+      const valueJs = yamlNodeToJs(pair.value, lineCounter, doc);
+      out[keyText] = valueJs;
+      const keyRange = pair.key.range;
+      if (keyRange !== null && keyRange !== undefined) {
+        const pos = lineCounter.linePos(keyRange[0]);
+        positions[keyText] = { line: pos.line, col: pos.col };
+        hasAnyPosition = true;
+      }
+    }
+    if (hasAnyPosition) setPositionMap(out, positions);
+    return out;
+  }
+  if (isSeq(node)) {
+    return node.items.map((item) => yamlNodeToJs(item, lineCounter, doc));
+  }
+  // Tags / unsupported — fall back to null. The metaobjects authoring
+  // grammar does not use them.
+  return null;
+}

package/src/core/yaml-positions.ts

@@ -0,0 +1,80 @@
+// FR5b — YAML authoring source-position carrier (per ADR-0009).
+//
+// This module is split into two layers so the browser bundle (which
+// imports from src/index.ts) stays free of the Node-only `yaml` package:
+//
+//   - yaml-positions.ts (this file) — pure types + Symbol + accessors. NO
+//     `yaml` import. Imported by parser-core.ts so the source-on-node
+//     stamper can read positions when stamping `format: "yaml"` envelopes.
+//   - yaml-positions-walker.ts — depends on `yaml`. Imported only by
+//     parser-yaml.ts (and parser-yaml itself only ships server-side).
+//
+// Source-map carrier (per the FR5b spec's "open question" §2): a
+// Symbol-keyed, non-enumerable property on the wrapper-mapping object. The
+// symbol is the well-known cross-port key
+// `Symbol.for("@metaobjectsdev/yamlPositionByKey")`, so any plugin that
+// touches the canonical JS can read positions if it knows to look. The
+// map's keys are the wrapper's own keys (e.g. "object.entity" for a
+// wrapper `{ "object.entity": { ... } }` or "name" / "package" /
+// "children" for the body keys of a node).
+//
+// Rationale for "symbol-keyed property" over a parallel sourcemap / wrapper
+// type:
+//   - Invisible to JSON.stringify and Object.keys (non-enumerable).
+//   - No parallel data structure to keep in sync — the position rides with
+//     the node it describes.
+//   - No wrapper type — desugar still operates on plain JS objects, so the
+//     existing Rule 1–5 logic does not need a rewrite.
+//
+// On desugar-synthesized nodes (Rule 2's scalar-body lift): the synthesized
+// body `{ name: rawScalar }` inherits the wrapper key's position from the
+// parent's position map. On any other synthesis (Rule 4's isArray stamping,
+// for example), the position survives because we shallow-copy via the
+// existing desugar path.
+
+/** Cross-port well-known symbol key for the position-by-key map. */
+export const YAML_POSITION_BY_KEY = Symbol.for(
+  "@metaobjectsdev/yamlPositionByKey",
+);
+
+/** A YAML source position — 1-indexed line and column. */
+export interface YamlPosition {
+  readonly line: number;
+  readonly col: number;
+}
+
+/** The position-by-key map attached to a mapping object. */
+export type PositionMap = Record<string, YamlPosition>;
+
+/** Read the position-by-key map from a JS object, if present.
+ *  Returns undefined for primitives, arrays, null, and untagged objects. */
+export function getPositionMap(obj: unknown): PositionMap | undefined {
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+    return undefined;
+  }
+  return (obj as { [YAML_POSITION_BY_KEY]?: PositionMap })[YAML_POSITION_BY_KEY];
+}
+
+/** Read the position for a specific key on a mapping object. */
+export function getYamlPosition(
+  obj: unknown,
+  key: string,
+): YamlPosition | undefined {
+  const map = getPositionMap(obj);
+  return map?.[key];
+}
+
+/** Attach (or replace) the position-by-key map on a mapping object. The map
+ *  property is non-enumerable so JSON.stringify and `for (const k in obj)`
+ *  loops do not see it. */
+export function setPositionMap(
+  obj: Record<string, unknown>,
+  positions: PositionMap,
+): void {
+  Object.defineProperty(obj, YAML_POSITION_BY_KEY, {
+    value: positions,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+}

package/src/core-types.ts

@@ -279,10 +279,13 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     );
   }
 
-  // template — renderable text artifacts (FR-004). prompt + output; attr-only
-  // children. A single MetaTemplate class backs both subtypes (mirrors source);
-  // per-subtype attr schemas drive validation (both require @payloadRef +
-  // @textRef; @format is a closed enum; template.prompt adds the LLM overlay).
+  // template — renderable text artifacts (FR-004) + tool-call envelopes
+  // (ADR-0011). Three subtypes: prompt + output + toolcall; attr-only children.
+  // A single MetaTemplate class backs all three subtypes (mirrors source);
+  // per-subtype attr schemas drive validation (prompt + output require
+  // @payloadRef + @textRef + @format closed enum; prompt adds the LLM overlay;
+  // toolcall has its own set — @toolName + @payloadRef + @description, no
+  // @textRef requirement since toolcalls have no renderable body).
   for (const subType of TEMPLATE_SUBTYPES) {
     const templateAttrs = TEMPLATE_ATTRS_MAP.get(subType) ?? [];
     registry.register(

package/src/errors.ts

@@ -52,9 +52,24 @@ export const ERROR_CODES = [
   // ADR-0006 D2 — YAML type-coercion guard. Emitted by every port's YAML
   // loader when a coerced scalar mismatches the schema-declared type.
   "ERR_YAML_COERCION",
+  // FR5c — multi-file overlay merge produced a conflicting attribute value:
+  // two contributors set the same @attr to different non-empty values.
+  "ERR_MERGE_CONFLICT",
   "ERR_UNKNOWN",
 ] as const;
 
+/** Warning codes — same envelope shape as errors but advisory. */
+export const WARNING_CODES = [
+  // FR5c — two contributors declared the same node identically (no semantic
+  // change). Emitted at the overlay-merge boundary.
+  "WARN_DUPLICATE_DECLARATION",
+  // Pre-FR5c legacy: parser/validator messages still surface as plain
+  // strings; wrapped at the loader boundary into the envelope shape with
+  // this code. Retired as those sites are migrated to envelopes.
+  "WARN_LEGACY",
+] as const;
+export type WarningCode = (typeof WARNING_CODES)[number];
+
 export type ErrorCode = (typeof ERROR_CODES)[number];
 
 /**

package/src/loader/meta-data-loader.ts

@@ -15,7 +15,7 @@ import { composeRegistry } from "../provider.js";
 import { TYPE_METADATA, SUBTYPE_ROOT } from "../shared/base-types.js";
 import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
-import { codeSource } from "../source.js";
+import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
 import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs } from "./validation-passes.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
@@ -321,6 +321,11 @@ export class MetaDataLoader {
     this._state = "loading";
     const warnings: string[] = [];
     const errors: Error[] = [];
+    // FR5c — envelope-shaped warnings (WARN_DUPLICATE_DECLARATION et al.)
+    // surface here untouched. Distinct from the legacy `warnings: string[]`
+    // channel: those are wrapped in a WARN_LEGACY envelope at the boundary,
+    // while these already carry their own code + source.
+    const envelopeWarnings: LoaderWarning[] = [];
 
     // Pre-load the YAML parser via dynamic import if any source declares
     // YAML format. This keeps `parseSource` synchronous and the package root
@@ -363,6 +368,10 @@ export class MetaDataLoader {
         const parseResult = this.parseSource(content, source, parseOpts);
         warnings.push(...parseResult.warnings);
         errors.push(...parseResult.errors);
+        // FR5c — collect envelope-shaped warnings (already carry code +
+        // source). The legacy `warnings` channel still flows into the
+        // WARN_LEGACY-wrapping path below for unchanged behavior.
+        envelopeWarnings.push(...parseResult.envelopeWarnings);
         root = parseResult.root;
       } catch (err) {
         errors.push(
@@ -379,10 +388,17 @@ export class MetaDataLoader {
     if (root !== undefined) {
       const failures = resolveDeferredSupers(root);
       for (const failure of failures) {
+        // FR5d — emit format=resolved with referrer + target. The referrer's
+        // parse-time source supplies files + jsonPath (the location of the
+        // broken `extends:` on disk); referrer = the declaring node's FQN;
+        // target = the unresolved supertype ref.
         errors.push(
           new ParseError(
             `the SuperClass '${failure.ref}' does not exist (referenced by ${failure.nodeFqn})`,
-            { code: "ERR_UNRESOLVED_SUPER", source: failure.source },
+            {
+              code: "ERR_UNRESOLVED_SUPER",
+              source: resolvedSource(failure.source, failure.nodeFqn, failure.ref),
+            },
           ),
         );
       }
@@ -447,13 +463,17 @@ export class MetaDataLoader {
     // LoaderWarning envelopes at the loader boundary. The parser/validator
     // surface keeps its `string[]` shape internally (parser-core is shared
     // with parseJson() / parseYaml() callers who consume string warnings
-    // directly). FR5c will retire WARN_LEGACY by routing the duplicate-
-    // declaration site through a proper envelope-shaped emit helper.
-    const envelopeWarnings: LoaderWarning[] = warnings.map((msg) => ({
+    // directly). FR5c-onward sites emit proper envelopes via parseResult.
+    // envelopeWarnings (collected above) — those surface unchanged.
+    const wrappedLegacy: LoaderWarning[] = warnings.map((msg) => ({
       code: "WARN_LEGACY",
       message: msg,
       source: codeSource("MetaDataLoader"),
     }));
-    return { root, warnings: envelopeWarnings, errors };
+    return {
+      root,
+      warnings: [...envelopeWarnings, ...wrappedLegacy],
+      errors,
+    };
   }
 }