@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.10

package/src/parser-core.ts

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