@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.10

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

@@ -1 +1 @@
-{"version":3,"file":"template-constants.d.ts","sourceRoot":"","sources":["../../src/template/template-constants.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAChD,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD,eAAO,MAAM,iBAAiB,uCAIpB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAGjE,eAAO,MAAM,yBAAyB,eAAe,CAAC;AACtD,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAChD,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAC7C,eAAO,MAAM,uBAAuB,aAAa,CAAC;AAClD,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAC3C,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAI3C,eAAO,MAAM,2BAA2B,iBAAiB,CAAC;AAG1D,eAAO,MAAM,wBAAwB,cAAc,CAAC;AACpD,eAAO,MAAM,4BAA4B,kBAAkB,CAAC;AAC5D,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAI3C,eAAO,MAAM,gBAAgB,4EAQnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"template-constants.d.ts","sourceRoot":"","sources":["../../src/template/template-constants.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAChD,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAChD,eAAO,MAAM,yBAAyB,aAAa,CAAC;AAEpD,eAAO,MAAM,iBAAiB,mDAKpB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAIjE,eAAO,MAAM,yBAAyB,eAAe,CAAC;AACtD,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAChD,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAC7C,eAAO,MAAM,uBAAuB,aAAa,CAAC;AAClD,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAC3C,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAI3C,eAAO,MAAM,2BAA2B,iBAAiB,CAAC;AAG1D,eAAO,MAAM,wBAAwB,cAAc,CAAC;AACpD,eAAO,MAAM,4BAA4B,kBAAkB,CAAC;AAC5D,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAU3C,eAAO,MAAM,uBAAuB,aAAa,CAAC;AAIlD,eAAO,MAAM,gBAAgB,4EAQnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC"}

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.6.0",
+  "version": "0.7.0-rc.10",
   "description": "Metamodel loader, types, and constants for the MetaObjects standard.",
   "type": "module",
   "main": "./dist/index.js",

package/src/attr-schema-validate.ts

@@ -100,7 +100,7 @@ function validateNode(
         errors.push(
           new ParseError(
             `Common attr '${ca.name}' conflicts with per-type attr on ${typeKey}`,
-            { code: "ERR_PROVIDER_ATTR_CONFLICT" },
+            { code: "ERR_PROVIDER_ATTR_CONFLICT", source: node.source },
           ),
         );
         reportedConflicts.add(typeKey);
@@ -126,7 +126,7 @@ function validateNode(
       errors.push(
         new ParseError(
           `${nodeLabel(node)} is missing required attribute '@${spec.name}'`,
-          { code: "ERR_MISSING_REQUIRED_ATTR" },
+          { code: "ERR_MISSING_REQUIRED_ATTR", source: node.source },
         ),
       );
     }
@@ -145,7 +145,7 @@ function validateNode(
       const valueErrors = inst.validateValue(value);
       if (valueErrors.length > 0) {
         for (const ve of valueErrors) {
-          errors.push(new ParseError(`${nodeLabel(node)} ${ve.message}`, { code: "ERR_BAD_ATTR_VALUE" }));
+          errors.push(new ParseError(`${nodeLabel(node)} ${ve.message}`, { code: "ERR_BAD_ATTR_VALUE", source: node.source }));
         }
         continue; // type wrong → skip allowedValues
       }
@@ -159,7 +159,7 @@ function validateNode(
             `${nodeLabel(node)} attribute '@${inst.name}' has value ` +
               `'${String(value)}' which is not one of the allowed values: ` +
               `${spec.allowedValues.map((v) => String(v)).join(", ")}`,
-            { code: "ERR_BAD_ATTR_VALUE" },
+            { code: "ERR_BAD_ATTR_VALUE", source: node.source },
           ),
         );
       }
@@ -180,7 +180,7 @@ function validateNode(
         errors.push(
           new ParseError(
             `${nodeLabel(node)} must declare at least one value in '@${FIELD_ATTR_VALUES}'.`,
-            { code: "ERR_BAD_ATTR_VALUE" },
+            { code: "ERR_BAD_ATTR_VALUE", source: node.source },
           ),
         );
       } else {
@@ -194,14 +194,14 @@ function validateNode(
                 `${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' member '${member}' ` +
                   `is not a valid identifier (must match ${ENUM_MEMBER_PATTERN.source}). ` +
                   `Non-identifier-safe member strings require a symbol↔value mapping (deferred).`,
-                { code: "ERR_BAD_ATTR_VALUE" },
+                { code: "ERR_BAD_ATTR_VALUE", source: node.source },
               ),
             );
           } else if (seen.has(member)) {
             errors.push(
               new ParseError(
                 `${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' has duplicate member '${member}'.`,
-                { code: "ERR_BAD_ATTR_VALUE" },
+                { code: "ERR_BAD_ATTR_VALUE", source: node.source },
               ),
             );
           } else {

package/src/core/export-json.ts

@@ -10,13 +10,12 @@
 //   - Content errors (parse/validation failures) are collected in errors[] and
 //     returned in the result — they do NOT throw. `json` is still produced from
 //     whatever tree the Loader returned (Loader always returns a valid MetaData).
-//   - I/O failures (missing/unreadable directory) are caught by
-//     `loadFromDirectory` and returned in its `errors[]`; `loadAndExportJson`
-//     surfaces them unchanged in `ExportResult.errors`. It does not throw for
-//     directory or metadata problems.
+//   - I/O failures (missing/unreadable directory) surface as collected errors
+//     via MetaDataLoader.fromDirectory; `loadAndExportJson` surfaces them
+//     unchanged in `ExportResult.errors`. It does not throw for directory or
+//     metadata problems.
 
-import { FileMetaDataLoader } from "./file-meta-data-loader.js";
-import type { LoadOptions } from "../loader/meta-data-loader.js";
+import { MetaDataLoader, type LoadOptions } from "../loader/meta-data-loader.js";
 import { canonicalSerialize } from "../serializer-json.js";
 
 // ---------------------------------------------------------------------------
@@ -39,28 +38,26 @@ export interface ExportResult {
  * Load all metadata under `dir` and export the entire model as one flattened
  * canonical-JSON document.
  *
- * Internally constructs a fresh `FileMetaDataLoader` (using the default registry
- * composed via `composeRegistry(coreProviders)`), calls `loadDirectory`, then serializes the
- * resulting tree with `canonicalSerialize`.
+ * Routes through `MetaDataLoader.fromDirectory` (using the default registry
+ * composed via `composeRegistry(coreProviders)` when none supplied), then
+ * serializes the resulting tree with `canonicalSerialize`.
  *
  * @param dir  Absolute or relative path to the directory containing `meta.*.json` files.
- * @param opts Optional loader options forwarded to the `FileMetaDataLoader` constructor
- *             (registry, freeze, strict). The `exclude` glob list can be
- *             supplied as `opts.exclude` — see `FileMetaDataLoader.loadDirectory`.
+ * @param opts Optional loader options (registry, freeze, strict). The
+ *             `exclude` glob list can be supplied as `opts.exclude`.
  */
 export async function loadAndExportJson(
   dir: string,
   opts?: LoadOptions & { exclude?: string[] },
 ): Promise<ExportResult> {
-  const { exclude, ...loaderOpts } = opts ?? {};
-  const loader = new FileMetaDataLoader(loaderOpts);
-  // Only pass the exclude option when defined, to satisfy exactOptionalPropertyTypes.
-  const dirOpts = exclude !== undefined ? { exclude } : undefined;
-  const result = await loader.loadDirectory(dir, dirOpts);
+  const result = await MetaDataLoader.fromDirectory(dir, opts);
   const json = canonicalSerialize(result.root);
   return {
     json,
     errors: result.errors,
-    warnings: result.warnings,
+    // FR5a: LoadResult.warnings is now LoaderWarning[]; ExportResult preserves
+    // its public string[] shape (callers print warnings as text). Extract the
+    // message for back-compat.
+    warnings: result.warnings.map((w) => w.message),
   };
 }

package/src/core/index.ts

@@ -5,8 +5,14 @@
 // load-and-export convenience. The root `@metaobjectsdev/metadata` entry is
 // browser-safe and imports none of this. See the package README.
 
-export { FileSource } from "./file-source.js";
-export { FileMetaDataLoader } from "./file-meta-data-loader.js";
+// Source impls — the node:fs-backed MetaDataSource implementations. Live
+// under `loader/sources/`; re-exported here so server-side consumers can pull
+// them from the same `/core` entry that already houses the YAML parser.
+export { FileSource } from "../loader/sources/file-source.js";
+export { DirectorySource } from "../loader/sources/directory-source.js";
+export type { DirectoryOptions } from "../loader/sources/directory-source.js";
+export { UriSource } from "../loader/sources/uri-source.js";
+
 export { parseYaml } from "./parser-yaml.js";
 export { loadAndExportJson } from "./export-json.js";
 export type { ExportResult } from "./export-json.js";

package/src/core/parser-yaml.ts

@@ -1,15 +1,38 @@
 // 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, errOpts } from "../parser-core.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 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",
+    files: [sourceName ?? "<unknown>"],
+    jsonPath: "$",
+  };
+}
 
 export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   // Strip UTF-8 BOM if present (consistent with parseJson).
@@ -20,11 +43,11 @@ 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}`,
-      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" },
+      { code: "ERR_MALFORMED_YAML", source: yamlSource(opts.sourceName) },
     );
   }
 
@@ -37,11 +60,14 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
     const first = desugarErrors[0]!;
     throw new ParseError(
       first.message,
-      { ...errOpts(opts.sourceName), code: first.code ?? "ERR_MALFORMED_YAML" },
+      { code: first.code ?? "ERR_MALFORMED_YAML", source: yamlSource(opts.sourceName) },
     );
   }
 
-  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.
@@ -50,13 +76,14 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   const desugarParseErrors = desugarErrors.map(
     (e) =>
       new ParseError(e.message, {
-        ...errOpts(opts.sourceName),
         code: e.code ?? "ERR_MALFORMED_YAML",
+        source: yamlSource(opts.sourceName),
       }),
   );
   return {
     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;
+}