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

package/src/naming.ts

@@ -28,6 +28,31 @@ export function toSnakeCase(s: string): string {
     .toLowerCase();
 }
 
+export function toKebabCase(s: string): string {
+  return toSnakeCase(s).replace(/_/g, "-");
+}
+
+/**
+ * Column-naming strategy applied by the persistence layer to fields with no
+ * explicit `@column` override. Persistence-layer config (set on
+ * ObjectManager / buildExpectedSchema / codegen config), not a metadata attr —
+ * the same metadata can drive snake_case (PG convention) or literal (EF
+ * convention) consumers. TS port defaults to snake_case; C# port defaults to
+ * literal.
+ */
+export type ColumnNamingStrategy = "snake_case" | "literal" | "kebab-case";
+
+/** Single source of truth for the TS-port default. */
+export const DEFAULT_COLUMN_NAMING_STRATEGY: ColumnNamingStrategy = "snake_case";
+
+export function applyColumnNamingStrategy(name: string, strategy: ColumnNamingStrategy): string {
+  switch (strategy) {
+    case "literal":     return name;
+    case "kebab-case":  return toKebabCase(name);
+    case "snake_case":  return toSnakeCase(name);
+  }
+}
+
 export function pluralize(s: string): string {
   if (/(s|x|z|ch|sh)$/i.test(s)) return s + "es";
   if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + "ies";
@@ -35,20 +60,24 @@ export function pluralize(s: string): string {
 }
 
 export function resolveTableName(entity: MetaData): string {
-  // Primary writable source carries the physical table name (@table).
+  // Primary source carries the physical table/view name (@table). Writability
+  // (table vs view/storedProc/tableFunction) only affects write-routing — for
+  // SELECT-side name resolution, a read-only primary source is the right answer.
   const source = entity.ownChildren().find(
-    (c): c is MetaSource =>
-      c instanceof MetaSource && c.isWritable() && c.role === SOURCE_ROLE_PRIMARY,
+    (c): c is MetaSource => c instanceof MetaSource && c.role === SOURCE_ROLE_PRIMARY,
   );
   const name = source?.tableName;
   if (typeof name === "string" && name !== "") return name;
   return pluralize(toSnakeCase(entity.name));
 }
 
-export function resolveColumnName(field: MetaData): string {
+export function resolveColumnName(
+  field: MetaData,
+  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+): string {
   const col = field.ownAttr(FIELD_ATTR_COLUMN);
   if (typeof col === "string" && col) return col;
-  return toSnakeCase(field.name);
+  return applyColumnNamingStrategy(field.name, strategy);
 }
 
 /**
@@ -75,12 +104,15 @@ export interface EntityNameMap {
   dbToJs: Map<string, string>;
 }
 
-export function buildNameMap(entity: MetaData): EntityNameMap {
+export function buildNameMap(
+  entity: MetaData,
+  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+): EntityNameMap {
   const jsToDb = new Map<string, string>();
   const dbToJs = new Map<string, string>();
   for (const child of entity.ownChildren()) {
     if (child.type !== TYPE_FIELD) continue;
-    const dbCol = resolveColumnName(child);
+    const dbCol = resolveColumnName(child, strategy);
     jsToDb.set(child.name, dbCol);
     dbToJs.set(dbCol, child.name);
   }

package/src/parser-core.ts

@@ -29,7 +29,9 @@ import { MetaRoot } from "./shared/meta-root.js";
 import { MetaAttr } from "./core/attr/meta-attr.js";
 import { inferAttrSubType } from "./serializer-json.js";
 import { ParseError, type ErrorCode } from "./errors.js";
+import type { ErrorSource } from "./source.js";
 import { resolveSuperRef } from "./super-resolve.js";
+import { JsonPathBuilder } from "./json-path.js";
 import {
   TYPE_ATTR,
   TYPE_FIELD,
@@ -89,18 +91,24 @@ export interface ParseResult {
 }
 
 // ---------------------------------------------------------------------------
-// Internal helper — build ParseError opts, omitting undefined fields
-// (required by exactOptionalPropertyTypes: true in the project tsconfig)
+// Internal helper — build a parse-phase ErrorSource envelope.
+//
+// FR5a / ADR-0009: ParseError carries a `source: ErrorSource` envelope. For
+// errors raised mid-parse, the envelope's jsonPath comes from the parser's
+// module-level JsonPathBuilder (synced with the walk); files[0] is the parsed
+// source id. Falls back to a code-source envelope if invoked outside a buildTree
+// run (defensive — every callsite below runs inside buildTree).
 // ---------------------------------------------------------------------------
 
-export function errOpts(
-  source: string | undefined,
-  path?: string,
-): { source?: string; path?: string } {
-  const opts: { source?: string; path?: string } = {};
-  if (source !== undefined) opts.source = source;
-  if (path !== undefined) opts.path = path;
-  return opts;
+export function errSource(): ErrorSource {
+  if (_currentPath !== undefined && _currentSourceId !== undefined) {
+    return {
+      format: "json",
+      files: [_currentSourceId],
+      jsonPath: _currentPath.toString(),
+    };
+  }
+  return { format: "code", caller: "parser-core" };
 }
 
 // ---------------------------------------------------------------------------
@@ -111,14 +119,10 @@ function reportProblem(
   msg: string,
   strict: boolean,
   warnings: string[],
-  source: string | undefined,
-  path: string,
-  code?: ErrorCode,
+  code: ErrorCode,
 ): void {
   if (strict) {
-    const opts = errOpts(source, path);
-    if (code !== undefined) throw new ParseError(msg, { ...opts, code });
-    else throw new ParseError(msg, opts);
+    throw new ParseError(msg, { code, source: errSource() });
   }
   warnings.push(msg);
 }
@@ -196,6 +200,27 @@ let _deferSuperResolution = false;
 // _deferSuperResolution.
 let _currentErrors: ParseError[] | 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 }`.
+// 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). */
+function populateNodeSource(node: MetaData): void {
+  if (_currentPath === undefined || _currentSourceId === undefined) return;
+  node.setSource({
+    format: "json",
+    files: [_currentSourceId],
+    jsonPath: _currentPath.toString(),
+  });
+}
+
 /**
  * buildTree — the shared registry-driven tree-builder.
  *
@@ -214,10 +239,16 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
   const source = opts.sourceName;
   _deferSuperResolution = opts.deferSuperResolution === true;
   _currentErrors = errors;
+  // 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>";
 
   try {
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-      throw new ParseError("Top-level metadata must be an object", { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" });
+      throw new ParseError("Top-level metadata must be an object", { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: errSource() });
     }
 
     const topLevel = parsed as Record<string, unknown>;
@@ -226,12 +257,12 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
     const wrapperKeys = Object.keys(topLevel).filter((k) => k !== JSON_KEY_SCHEMA);
 
     if (wrapperKeys.length === 0) {
-      throw new ParseError("Top-level metadata object has no type wrapper key", { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" });
+      throw new ParseError("Top-level metadata object has no type wrapper key", { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: errSource() });
     }
     if (wrapperKeys.length > 1) {
       throw new ParseError(
         `Top-level metadata object must have exactly one wrapper key (found: ${wrapperKeys.join(", ")})`,
-        { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" },
+        { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: errSource() },
       );
     }
 
@@ -239,9 +270,14 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
     const rootData = topLevel[rootKey];
 
     if (typeof rootData !== "object" || rootData === null || Array.isArray(rootData)) {
+      // The error context references the rootKey wrapper; push it so the
+      // envelope's jsonPath includes it (matches the legacy `path` slot).
+      _currentPath!.pushKey(rootKey);
+      const src = errSource();
+      _currentPath!.pop();
       throw new ParseError(
         `Top-level wrapper "${rootKey}" must contain an object`,
-        { ...errOpts(source, rootKey), code: "ERR_TOP_LEVEL_NOT_OBJECT" },
+        { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: src },
       );
     }
 
@@ -253,12 +289,22 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
       const rootTypeCode = opts.registry.allSubTypesOf(rootType).length > 0
         ? "ERR_UNKNOWN_SUBTYPE" as const
         : "ERR_UNKNOWN_TYPE" as const;
+      _currentPath!.pushKey(rootKey);
+      const src = errSource();
+      _currentPath!.pop();
       throw new ParseError(
         `Unknown root type "${rootType}.${rootSubType}" — not registered`,
-        { ...errOpts(source, rootKey), code: rootTypeCode },
+        { code: rootTypeCode, source: src },
       );
     }
 
+    // FR5a — push the wrapper-key segment onto the JSONPath stack so all
+    // descendants emit jsonPath strings rooted at "$.<rootKey>". The merge-mode
+    // path keeps the existing root's source untouched; only NEW children get
+    // populated with the current source's id (correct: the existing root was
+    // already stamped from the file that created it).
+    _currentPath!.pushKey(rootKey);
+
     if (opts.intoRoot !== undefined) {
       // --- Merge mode: parse root's attrs/children into the existing root ---
       // The JSON root's own package/super/reserved-keys are not re-applied to the
@@ -278,6 +324,7 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
         source,
         rootKey,
       );
+      _currentPath!.pop();
       return { root: opts.intoRoot, warnings, errors };
     }
 
@@ -302,10 +349,13 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
       source,
       rootKey,
     ) as MetaRoot;
+    _currentPath!.pop();
     return { root, warnings, errors };
   } finally {
     _deferSuperResolution = false;
     _currentErrors = undefined;
+    _currentPath = undefined;
+    _currentSourceId = undefined;
   }
 }
 
@@ -341,10 +391,12 @@ function parseNodeFresh(
       subType = SUBTYPE_BASE;
     } else {
       const msg = `Unknown type "${type}.${subType}" — not registered`;
-      errors.push(new ParseError(msg, { ...errOpts(source, path), code: "ERR_UNKNOWN_TYPE" }));
+      errors.push(new ParseError(msg, { code: "ERR_UNKNOWN_TYPE", source: errSource() }));
       const rawName = nodeData[RESERVED_KEY_NAME];
       const name = typeof rawName === "string" ? rawName : "";
-      return new MetaRoot(new TypeId(type, subType), name);
+      const stub = new MetaRoot(new TypeId(type, subType), name);
+      populateNodeSource(stub);
+      return stub;
     }
   }
 
@@ -355,6 +407,10 @@ function parseNodeFresh(
   // --- Create the model ---
   const def = registry.find(type, subType)!;
   const model = def.factory(def.typeId, name);
+  // FR5a — stamp the source provenance envelope using the parser's current
+  // JSONPath stack + source id. setSource happens BEFORE freeze (the parser
+  // is the only caller during loading; freeze runs in the loader after).
+  populateNodeSource(model);
 
   // --- Apply reserved keys (package, extends, abstract, isArray) ---
   applyReservedKeys(model, nodeData, strict, source, path, warnings, inheritedContextPkg);
@@ -392,7 +448,7 @@ function parseNodeFresh(
     } else {
       throw new ParseError(
         `the SuperClass '${model.superRef}' does not exist in file '${source ?? "<unknown>"}'`,
-        { ...errOpts(source, path), code: "ERR_UNRESOLVED_SUPER" },
+        { code: "ERR_UNRESOLVED_SUPER", source: errSource() },
       );
     }
   } else if (model.superRef !== undefined && accumRoot === undefined) {
@@ -401,8 +457,6 @@ function parseNodeFresh(
       `super on root node ('${model.superRef}') is not supported and will be ignored`,
       strict,
       warnings,
-      source,
-      path,
       "ERR_UNRESOLVED_SUPER",
     );
   }
@@ -487,7 +541,7 @@ function createOrFindMetaData(
     if (existing === undefined) {
       throw new ParseError(
         `Overlay operation requested for [${type}:${name}] but no existing metadata found to merge into`,
-        { ...errOpts(source, path), code: "ERR_OVERLAY_NO_TARGET" },
+        { code: "ERR_OVERLAY_NO_TARGET", source: errSource() },
       );
     }
     existing.setIsMerge(true);
@@ -524,7 +578,7 @@ function applyReservedKeys(
   const rawPkg = nodeData[RESERVED_KEY_PACKAGE];
   if (rawPkg !== undefined) {
     if (typeof rawPkg !== "string") {
-      reportProblem(`"${RESERVED_KEY_PACKAGE}" must be a string at ${path}`, strict, warnings, source, path, "ERR_BAD_ATTR_VALUE");
+      reportProblem(`"${RESERVED_KEY_PACKAGE}" must be a string at ${path}`, strict, warnings, "ERR_BAD_ATTR_VALUE");
     } else {
       const expandedPkg = contextPkg !== undefined ? expandPackageForPath(contextPkg, rawPkg) : rawPkg;
       model.setPackage(expandedPkg);
@@ -535,7 +589,7 @@ function applyReservedKeys(
   const rawExtends = nodeData[RESERVED_KEY_EXTENDS];
   if (rawExtends !== undefined) {
     if (typeof rawExtends !== "string") {
-      reportProblem(`"${RESERVED_KEY_EXTENDS}" must be a string at ${path}`, strict, warnings, source, path, "ERR_UNRESOLVED_SUPER");
+      reportProblem(`"${RESERVED_KEY_EXTENDS}" must be a string at ${path}`, strict, warnings, "ERR_UNRESOLVED_SUPER");
     } else {
       model.setSuper(rawExtends);
     }
@@ -545,7 +599,7 @@ function applyReservedKeys(
   const rawAbstract = nodeData[RESERVED_KEY_ABSTRACT];
   if (rawAbstract !== undefined) {
     if (typeof rawAbstract !== "boolean") {
-      reportProblem(`"${RESERVED_KEY_ABSTRACT}" must be a boolean at ${path}`, strict, warnings, source, path, "ERR_BAD_ATTR_VALUE");
+      reportProblem(`"${RESERVED_KEY_ABSTRACT}" must be a boolean at ${path}`, strict, warnings, "ERR_BAD_ATTR_VALUE");
     } else {
       model.setIsAbstract(rawAbstract);
     }
@@ -555,7 +609,7 @@ function applyReservedKeys(
   const rawIsArray = nodeData[RESERVED_KEY_IS_ARRAY];
   if (rawIsArray !== undefined) {
     if (typeof rawIsArray !== "boolean") {
-      reportProblem(`"${RESERVED_KEY_IS_ARRAY}" must be a boolean at ${path}`, strict, warnings, source, path, "ERR_BAD_ATTR_VALUE");
+      reportProblem(`"${RESERVED_KEY_IS_ARRAY}" must be a boolean at ${path}`, strict, warnings, "ERR_BAD_ATTR_VALUE");
     } else {
       model.setIsArray(rawIsArray);
     }
@@ -587,7 +641,7 @@ function applyInlineAttrsAndUnknownKeys(
         model.name !== "" ? `${model.type}.${model.subType} '${model.name}'` : `${model.type}.${model.subType}`;
       reportProblem(
         `Unknown key '${key}' on ${displayName} at ${path} (must be reserved or ${ATTR_PREFIX}-prefixed)`,
-        strict, warnings, source, path, "ERR_UNKNOWN_ATTR",
+        strict, warnings, "ERR_UNKNOWN_ATTR",
       );
       continue;
     }
@@ -608,14 +662,14 @@ function applyInlineAttrsAndUnknownKeys(
         `Reserved structural key '${attrName}' must not be ${ATTR_PREFIX}-prefixed ` +
         `on ${displayName} at ${path} (write it bare)`;
       if (strict) {
-        throw new ParseError(msg, { ...errOpts(source, path), code: "ERR_RESERVED_ATTR" });
+        throw new ParseError(msg, { code: "ERR_RESERVED_ATTR", source: errSource() });
       }
       // Lax mode: route through the module-level errors sink so the loader
       // sees this as a hard error (parity with attr-schema-validate's
       // ERR_BAD_ATTR_VALUE direct pushes). Falls back to warnings only if
       // _currentErrors isn't bound (unreachable when called from buildTree).
       if (_currentErrors !== undefined) {
-        _currentErrors.push(new ParseError(msg, { ...errOpts(source, path), code: "ERR_RESERVED_ATTR" }));
+        _currentErrors.push(new ParseError(msg, { code: "ERR_RESERVED_ATTR", source: errSource() }));
       } else {
         warnings.push(msg);
       }
@@ -630,7 +684,7 @@ function applyInlineAttrsAndUnknownKeys(
     } catch (err) {
       reportProblem(
         `Failed to convert attribute "${ATTR_PREFIX}${attrName}" at ${path}: ${(err as Error).message}`,
-        strict, warnings, source, path, "ERR_BAD_ATTR_VALUE",
+        strict, warnings, "ERR_BAD_ATTR_VALUE",
       );
     }
   }
@@ -703,16 +757,23 @@ function processChildren(
   if (rawChildren === undefined) return;
 
   if (!Array.isArray(rawChildren)) {
-    reportProblem(`"${RESERVED_KEY_CHILDREN}" must be an array at ${path}`, strict, warnings, source, path, "ERR_TOP_LEVEL_NOT_OBJECT");
+    reportProblem(`"${RESERVED_KEY_CHILDREN}" must be an array at ${path}`, strict, warnings, "ERR_TOP_LEVEL_NOT_OBJECT");
     return;
   }
 
+  // FR5a — push the "children" segment once; each iteration pushes/pops a
+  // numeric index + the wrapper-key segment so nested nodes see the correct
+  // jsonPath when populateNodeSource() is called during their construction.
+  _currentPath?.pushKey(RESERVED_KEY_CHILDREN);
+
   for (let i = 0; i < rawChildren.length; i++) {
     const childEntry = rawChildren[i];
     const childPath = `${path}.${RESERVED_KEY_CHILDREN}[${i}]`;
+    _currentPath?.pushIndex(i);
 
     if (typeof childEntry !== "object" || childEntry === null || Array.isArray(childEntry)) {
-      reportProblem(`Child at ${childPath} must be an object`, strict, warnings, source, childPath, "ERR_TOP_LEVEL_NOT_OBJECT");
+      reportProblem(`Child at ${childPath} must be an object`, strict, warnings, "ERR_TOP_LEVEL_NOT_OBJECT");
+      _currentPath?.pop();
       continue;
     }
 
@@ -724,19 +785,23 @@ function processChildren(
         childKeys.length === 0
           ? `Child at ${childPath} has no type wrapper key`
           : `Child at ${childPath} has multiple keys (${childKeys.join(", ")}) — each child must have exactly one wrapper key`;
-      reportProblem(msg, strict, warnings, source, childPath, "ERR_TOP_LEVEL_NOT_OBJECT");
+      reportProblem(msg, strict, warnings, "ERR_TOP_LEVEL_NOT_OBJECT");
+      _currentPath?.pop();
       continue;
     }
 
     const childKey = childKeys[0]!;
     const childData = childRecord[childKey];
     const childNodePath = `${childPath}.${childKey}`;
+    _currentPath?.pushKey(childKey);
 
     if (typeof childData !== "object" || childData === null || Array.isArray(childData)) {
       reportProblem(
         `Child wrapper "${childKey}" at ${childNodePath} must contain an object`,
-        strict, warnings, source, childNodePath, "ERR_TOP_LEVEL_NOT_OBJECT",
+        strict, warnings, "ERR_TOP_LEVEL_NOT_OBJECT",
       );
+      _currentPath?.pop(); // pop child wrapper key
+      _currentPath?.pop(); // pop array index
       continue;
     }
 
@@ -758,9 +823,11 @@ function processChildren(
         errors.push(
           new ParseError(
             `Unknown type "${childType}.${childSubType}" — not registered`,
-            { ...errOpts(source, childNodePath), code: childTypeCode },
+            { code: childTypeCode, source: errSource() },
           ),
         );
+        _currentPath?.pop(); // pop child wrapper key
+        _currentPath?.pop(); // pop array index
         continue; // skip this child
       }
     }
@@ -789,7 +856,10 @@ function processChildren(
         parent.addChild(childModel);
       }
     }
+    _currentPath?.pop(); // pop child wrapper key
+    _currentPath?.pop(); // pop array index
   }
+  _currentPath?.pop(); // pop the "children" key
 }
 
 // ---------------------------------------------------------------------------
@@ -821,7 +891,7 @@ function parseAttrChild(
   if (typeof attrName !== "string" || attrName === "") {
     reportProblem(
       `attr child at ${path} requires a non-empty "${RESERVED_KEY_NAME}" string`,
-      strict, warnings, source, path, "ERR_MISSING_REQUIRED_ATTR",
+      strict, warnings, "ERR_MISSING_REQUIRED_ATTR",
     );
     return;
   }
@@ -829,7 +899,7 @@ function parseAttrChild(
   if (attrValue === undefined) {
     reportProblem(
       `attr child "${attrName}" at ${path} is missing "${RESERVED_KEY_VALUE}"`,
-      strict, warnings, source, path, "ERR_MISSING_REQUIRED_ATTR",
+      strict, warnings, "ERR_MISSING_REQUIRED_ATTR",
     );
     return;
   }
@@ -852,7 +922,7 @@ function parseAttrChild(
   } catch (err) {
     reportProblem(
       `Failed to convert attr child "${attrName}" value at ${path}: ${(err as Error).message}`,
-      strict, warnings, source, path, "ERR_BAD_ATTR_VALUE",
+      strict, warnings, "ERR_BAD_ATTR_VALUE",
     );
     return;
   }

package/src/parser-json.ts

@@ -4,8 +4,9 @@
 // the canonical object to the shared buildTree (parser-core.ts).
 
 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";
 
 export type { ParseOptions, ParseResult } from "./parser-core.js";
 
@@ -18,9 +19,17 @@ export function parseJson(content: string, opts: ParseOptions): ParseResult {
   try {
     parsed = JSON.parse(normalizedContent);
   } catch (err) {
+    // FR5a / ADR-0009 — pre-buildTree errors can't reach the parser's
+    // module-level JsonPathBuilder; build a minimal json-source envelope
+    // rooted at "$" so cross-port callers see a consistent shape.
+    const source: ErrorSource = {
+      format: "json",
+      files: [opts.sourceName ?? "<unknown>"],
+      jsonPath: "$",
+    };
     throw new ParseError(
       `Invalid JSON: ${(err as Error).message}`,
-      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_JSON" },
+      { code: "ERR_MALFORMED_JSON", source },
     );
   }
 

package/src/persistence/source/validate-source-roles.ts

@@ -36,14 +36,14 @@ export function validateSourceRoles(root: MetaData): ParseError[] {
       errors.push(
         new ParseError(
           `object "${obj.name}" declares ${sources.length} source(s) but none has role "${SOURCE_ROLE_PRIMARY}"`,
-          { code: "ERR_SOURCE_NO_PRIMARY" },
+          { code: "ERR_SOURCE_NO_PRIMARY", source: obj.source },
         ),
       );
     } else if (primaryCount > 1) {
       errors.push(
         new ParseError(
           `object "${obj.name}" declares ${primaryCount} sources with role "${SOURCE_ROLE_PRIMARY}"; exactly one is required`,
-          { code: "ERR_SOURCE_MULTIPLE_PRIMARY" },
+          { code: "ERR_SOURCE_MULTIPLE_PRIMARY", source: obj.source },
         ),
       );
     }

package/src/semantic-diff.ts

@@ -0,0 +1,48 @@
+// server/typescript/packages/metadata/src/semantic-diff.ts
+//
+// FR5a / ADR-0009 — Cross-port-aligned semantic-equality compare for metadata
+// trees. Returns `true` if the two inputs differ in any semantically-meaningful
+// way (excluding `source`, which is loader output).
+//
+// Algorithm (ADR-0009 §semantic_diff):
+//   1. Sort attrs lexicographically; compare attr-by-attr; values by canonical
+//      structural equality (key-order independent, whitespace-insensitive).
+//   2. Children are compared as ordered sequences.
+//   3. Reserved structural keys (name, package, extends, abstract, overlay,
+//      isArray, value) participate like attrs.
+//   4. `source` excluded from the diff.
+
+type Tree = Record<string, unknown>;
+
+const EXCLUDED = new Set(["source"]);
+
+function isObject(v: unknown): v is Tree {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function equal(a: unknown, b: unknown): boolean {
+  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 (!equal(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (isObject(a) && isObject(b)) {
+    const aKeys = Object.keys(a).filter((k) => !EXCLUDED.has(k)).sort();
+    const bKeys = Object.keys(b).filter((k) => !EXCLUDED.has(k)).sort();
+    if (aKeys.length !== bKeys.length) return false;
+    for (let i = 0; i < aKeys.length; i++) {
+      if (aKeys[i] !== bKeys[i]) return false;
+      if (!equal(a[aKeys[i]!], b[bKeys[i]!])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+/** Returns `true` if the inputs differ in any semantically-meaningful way. */
+export function semanticDiff(a: Tree, b: Tree): boolean {
+  return !equal(a, b);
+}

package/src/shared/meta-data.ts

@@ -5,6 +5,7 @@ import type { DataType } from "../data-type.js";
 import type { MetaAttr } from "../core/attr/meta-attr.js";
 import { inferAttrSubType } from "../serializer-json.js";
 import { attrClassFor } from "../attr-class-map.js";
+import type { ErrorSource } from "../source.js";
 
 export type AttrValue = string | number | boolean | string[] | AttrObject;
 
@@ -57,6 +58,14 @@ export abstract class MetaData {
   // construction (for field/attr nodes). Read via MetaField/MetaAttr.dataType.
   protected _dataType?: DataType;
 
+  // ADR-0009 provenance. Always populated; defaults to `{ format: "code" }`
+  // for programmatic construction (tests, factories, in-code builders). The
+  // JSON parser overwrites via setSource() during tree walk; future phases
+  // (overlay merge, super resolution) may overwrite with merged/resolved
+  // variants. Excluded from canonical JSON serialization — loader-derived
+  // state, not metadata.
+  private _source: ErrorSource = { format: "code" };
+
   // Per-instance read cache: only populated once the node is frozen.
   private readonly _cache = new Map<string, unknown>();
 
@@ -171,6 +180,25 @@ export abstract class MetaData {
     this._dataType = dt;
   }
 
+  // ---------------------------------------------------------------------------
+  // source (ADR-0009 provenance)
+  // ---------------------------------------------------------------------------
+
+  /** Provenance envelope for this node. Always populated. See ADR-0009. */
+  get source(): ErrorSource {
+    return this._source;
+  }
+
+  /**
+   * Loader-internal: assign provenance. Called by parser and merge phases as
+   * they build the tree. Honors the frozen-guard like other setters.
+   * @internal
+   */
+  setSource(s: ErrorSource): void {
+    this._assertNotFrozen();
+    this._source = s;
+  }
+
   // ---------------------------------------------------------------------------
   // isAbstract
   // ---------------------------------------------------------------------------