@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.10

package/dist/parser-core.js

@@ -25,34 +25,55 @@
 import { TypeId, TypeRegistry } from "./registry.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 } from "./errors.js";
+import { resolvedSource } from "./source.js";
+import { semanticDiff } from "./semantic-diff.js";
 import { resolveSuperRef } from "./super-resolve.js";
+import { JsonPathBuilder } from "./json-path.js";
+import { getYamlPosition } from "./core/yaml-positions.js";
 import { TYPE_ATTR, TYPE_FIELD, TYPE_OBJECT, TYPE_VALIDATOR, SUBTYPE_BASE, } from "./shared/base-types.js";
 import { RESERVED_KEYS, RESERVED_KEY_NAME, RESERVED_KEY_PACKAGE, RESERVED_KEY_EXTENDS, RESERVED_KEY_ABSTRACT, RESERVED_KEY_OVERLAY, RESERVED_KEY_IS_ARRAY, RESERVED_KEY_CHILDREN, RESERVED_KEY_VALUE, JSON_KEY_SCHEMA, ATTR_PREFIX, TYPE_SUBTYPE_SEPARATOR, PACKAGE_SEPARATOR, } from "./shared/structural.js";
 import { ATTR_SUBTYPE_PROPERTIES } from "./core/attr/attr-constants.js";
 // ---------------------------------------------------------------------------
-// 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, path) {
-    const opts = {};
-    if (source !== undefined)
-        opts.source = source;
-    if (path !== undefined)
-        opts.path = path;
-    return opts;
+export function errSource() {
+    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" };
 }
 // ---------------------------------------------------------------------------
 // Internal helper — report a problem: throw in strict mode, push warning otherwise
 // ---------------------------------------------------------------------------
-function reportProblem(msg, strict, warnings, source, path, code) {
+function reportProblem(msg, strict, warnings, code) {
     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);
 }
@@ -107,6 +128,54 @@ let _deferSuperResolution = false;
 // Safe because buildTree is synchronous — same reentrancy argument as
 // _deferSuperResolution.
 let _currentErrors;
+// 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;
+// 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;
+let _currentSourceId;
+// 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";
+let _currentYamlPosition;
+/** 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) {
+    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.
  *
@@ -121,27 +190,47 @@ let _currentErrors;
 export function buildTree(parsed, opts) {
     const warnings = [];
     const errors = [];
+    const envelopeWarnings = [];
     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;
         // --- Find the wrapper key (skip $schema) ---
         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" });
+            throw new ParseError(`Top-level metadata object must have exactly one wrapper key (found: ${wrapperKeys.join(", ")})`, { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: errSource() });
         }
         const rootKey = wrapperKeys[0];
         const rootData = topLevel[rootKey];
         if (typeof rootData !== "object" || rootData === null || Array.isArray(rootData)) {
-            throw new ParseError(`Top-level wrapper "${rootKey}" must contain an object`, { ...errOpts(source, rootKey), code: "ERR_TOP_LEVEL_NOT_OBJECT" });
+            // 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`, { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: src });
         }
         const rootDataObj = rootData;
         const { type: rootType, subType: rootSubType } = splitTypeKey(rootKey, opts.registry);
@@ -150,7 +239,21 @@ export function buildTree(parsed, opts) {
             const rootTypeCode = opts.registry.allSubTypesOf(rootType).length > 0
                 ? "ERR_UNKNOWN_SUBTYPE"
                 : "ERR_UNKNOWN_TYPE";
-            throw new ParseError(`Unknown root type "${rootType}.${rootSubType}" — not registered`, { ...errOpts(source, rootKey), code: rootTypeCode });
+            _currentPath.pushKey(rootKey);
+            const src = errSource();
+            _currentPath.pop();
+            throw new ParseError(`Unknown root type "${rootType}.${rootSubType}" — not registered`, { 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 ---
@@ -161,7 +264,8 @@ export function buildTree(parsed, opts) {
             const contextPkg = (typeof newRootPkg === "string" ? newRootPkg : opts.intoRoot.package) ?? "";
             parseNodeInto(rootDataObj, opts.intoRoot, opts.intoRoot, // accumulating root for super resolution
             contextPkg, opts.registry, warnings, errors, strict, 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 ---
         // The cast is safe within the core provider: `metadata.root` is the only
@@ -174,11 +278,17 @@ export function buildTree(parsed, opts) {
         const root = parseNodeFresh(rootType, rootSubType, rootDataObj, undefined, // no accumulating root yet — built as we go
         "", // no inherited context pkg yet for the root itself
         opts.registry, warnings, errors, strict, source, rootKey);
-        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;
     }
 }
 // ---------------------------------------------------------------------------
@@ -200,10 +310,12 @@ parent) {
         }
         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;
         }
     }
     // --- Determine name ---
@@ -212,6 +324,10 @@ parent) {
     // --- 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);
     // --- Inherit package from context if not explicitly set ---
@@ -243,12 +359,18 @@ parent) {
             model.setSuperResolved(superModel);
         }
         else {
-            throw new ParseError(`the SuperClass '${model.superRef}' does not exist in file '${source ?? "<unknown>"}'`, { ...errOpts(source, path), code: "ERR_UNRESOLVED_SUPER" });
+            // FR5d — emit format=resolved with referrer + target. referrer is the
+            // declaring node's FQN (we just built it above); target is the
+            // unresolved supertype ref string.
+            throw new ParseError(`the SuperClass '${model.superRef}' does not exist in file '${source ?? "<unknown>"}'`, {
+                code: "ERR_UNRESOLVED_SUPER",
+                source: resolvedSource(errSource(), model.fqn(), model.superRef),
+            });
         }
     }
     else if (model.superRef !== undefined && accumRoot === undefined) {
         // Root node has a super ref — not resolvable against itself.
-        reportProblem(`super on root node ('${model.superRef}') is not supported and will be ignored`, strict, warnings, source, path, "ERR_UNRESOLVED_SUPER");
+        reportProblem(`super on root node ('${model.superRef}') is not supported and will be ignored`, strict, warnings, "ERR_UNRESOLVED_SUPER");
     }
     // --- Process inline attributes and other keys ---
     applyInlineAttrsAndUnknownKeys(model, nodeData, strict, source, path, warnings, registry);
@@ -267,6 +389,36 @@ parent) {
 // extends, package) — those belong to the original model's identity.
 // ---------------------------------------------------------------------------
 function parseNodeInto(nodeData, target, accumRoot, inheritedContextPkg, registry, warnings, errors, strict, source, path) {
+    // 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;
+    let preMergeAttrSnapshot;
+    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);
     // The effective package for children: use inheritedContextPkg (from the new
@@ -274,6 +426,155 @@ function parseNodeInto(nodeData, target, accumRoot, inheritedContextPkg, registr
     // being merged into, and new children inherit from the NEW context.
     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);
+        const postParsed = JSON.parse(postMergeShape);
+        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 = allFiles.map((f, i) => ({
+                file: f,
+                role: i === 0 ? "overlay-base" : "overlay-extension",
+            }));
+            const mergedSource = {
+                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 = allFiles.map((f, i) => ({
+                file: f,
+                role: i === 0 ? "overlay-base" : "overlay-extension",
+            }));
+            const warnSource = {
+                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, nodeData, preAttrs, newContributorFile, errors, path) {
+    const existingFiles = "files" in target.source ? [...target.source.files] : [];
+    function isEmptyValue(v) {
+        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, b) {
+        // 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[ak[i]]) !==
+                        JSON.stringify(b[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))
+            continue;
+        const allFiles = [...new Set([...existingFiles, newContributorFile])];
+        allFiles.sort();
+        const contributors = allFiles.map((f, i) => ({
+            file: f,
+            role: i === 0 ? "overlay-base" : "overlay-extension",
+        }));
+        const conflictSource = {
+            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 }));
+    }
 }
 // ---------------------------------------------------------------------------
 // createOrFindMetaData — per-node merge logic.
@@ -293,7 +594,7 @@ function createOrFindMetaData(type, subType, nodeData, parent, accumRoot, inheri
     const existing = name !== "" ? parent.ownChildByTypeAndName(type, name) : undefined;
     if (isOverlayNode) {
         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" });
+            throw new ParseError(`Overlay operation requested for [${type}:${name}] but no existing metadata found to merge into`, { code: "ERR_OVERLAY_NO_TARGET", source: errSource() });
         }
         existing.setIsMerge(true);
         parseNodeInto(nodeData, existing, accumRoot, inheritedContextPkg, registry, warnings, errors, strict, source, path);
@@ -317,7 +618,7 @@ function applyReservedKeys(model, nodeData, strict, source, path, warnings, cont
     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;
@@ -328,7 +629,7 @@ function applyReservedKeys(model, nodeData, strict, source, path, warnings, cont
     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);
@@ -338,7 +639,7 @@ function applyReservedKeys(model, nodeData, strict, source, path, warnings, cont
     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);
@@ -348,7 +649,7 @@ function applyReservedKeys(model, nodeData, strict, source, path, warnings, cont
     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);
@@ -368,7 +669,7 @@ function applyInlineAttrsAndUnknownKeys(model, nodeData, strict, source, path, w
             continue;
         if (!key.startsWith(ATTR_PREFIX)) {
             const displayName = 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");
+            reportProblem(`Unknown key '${key}' on ${displayName} at ${path} (must be reserved or ${ATTR_PREFIX}-prefixed)`, strict, warnings, "ERR_UNKNOWN_ATTR");
             continue;
         }
         // Inline attribute (@-prefixed) — materialize into a MetaAttr instance.
@@ -384,14 +685,14 @@ function applyInlineAttrsAndUnknownKeys(model, nodeData, strict, source, path, w
             const msg = `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);
@@ -404,7 +705,7 @@ function applyInlineAttrsAndUnknownKeys(model, nodeData, strict, source, path, w
             model.setMetaAttr(attr);
         }
         catch (err) {
-            reportProblem(`Failed to convert attribute "${ATTR_PREFIX}${attrName}" at ${path}: ${err.message}`, strict, warnings, source, path, "ERR_BAD_ATTR_VALUE");
+            reportProblem(`Failed to convert attribute "${ATTR_PREFIX}${attrName}" at ${path}: ${err.message}`, strict, warnings, "ERR_BAD_ATTR_VALUE");
         }
     }
 }
@@ -457,14 +758,20 @@ function processChildren(parent, nodeData, accumRoot, inheritedContextPkg, regis
     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;
         }
         const childRecord = childEntry;
@@ -473,14 +780,27 @@ function processChildren(parent, nodeData, accumRoot, inheritedContextPkg, regis
             const msg = 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");
+            reportProblem(`Child wrapper "${childKey}" at ${childNodePath} must contain an 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;
         }
         const childDataObj = childData;
@@ -498,7 +818,10 @@ function processChildren(parent, nodeData, accumRoot, inheritedContextPkg, regis
                 const childTypeCode = explicit && registry.allSubTypesOf(childType).length > 0
                     ? "ERR_UNKNOWN_SUBTYPE"
                     : "ERR_UNKNOWN_TYPE";
-                errors.push(new ParseError(`Unknown type "${childType}.${childSubType}" — not registered`, { ...errOpts(source, childNodePath), code: childTypeCode }));
+                errors.push(new ParseError(`Unknown type "${childType}.${childSubType}" — not registered`, { 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
             }
         }
@@ -513,7 +836,11 @@ function processChildren(parent, nodeData, accumRoot, inheritedContextPkg, regis
                 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
 }
 // ---------------------------------------------------------------------------
 // Attr child node — materialize into a MetaAttr instance (NOT a child).
@@ -530,11 +857,11 @@ function parseAttrChild(parent, attrType, attrSubType, attrData, registry, warni
     const attrName = attrData[RESERVED_KEY_NAME];
     const attrValue = attrData[RESERVED_KEY_VALUE];
     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");
+        reportProblem(`attr child at ${path} requires a non-empty "${RESERVED_KEY_NAME}" string`, strict, warnings, "ERR_MISSING_REQUIRED_ATTR");
         return;
     }
     if (attrValue === undefined) {
-        reportProblem(`attr child "${attrName}" at ${path} is missing "${RESERVED_KEY_VALUE}"`, strict, warnings, source, path, "ERR_MISSING_REQUIRED_ATTR");
+        reportProblem(`attr child "${attrName}" at ${path} is missing "${RESERVED_KEY_VALUE}"`, strict, warnings, "ERR_MISSING_REQUIRED_ATTR");
         return;
     }
     // Resolve the attr node's own subtype (fall back to base if unregistered).
@@ -551,7 +878,7 @@ function parseAttrChild(parent, attrType, attrSubType, attrData, registry, warni
         node.setAttr(RESERVED_KEY_VALUE, desugared);
     }
     catch (err) {
-        reportProblem(`Failed to convert attr child "${attrName}" value at ${path}: ${err.message}`, strict, warnings, source, path, "ERR_BAD_ATTR_VALUE");
+        reportProblem(`Failed to convert attr child "${attrName}" value at ${path}: ${err.message}`, strict, warnings, "ERR_BAD_ATTR_VALUE");
         return;
     }
     parent.setMetaAttr(node);