feat(metadata,ts): loader populates yamlPosition on yaml-loaded nodes [FR5b]

buildTree's parser-core threads a `sourceFormat: "json" | "yaml"` option
and module-level `_currentYamlPosition` through the recursive walk; each
parseNodeFresh call site (root + per-child in processChildren) reads the
wrapper's position-by-key map and sets `_currentYamlPosition` before the
node factory runs, then restores the parent's position on the way out.
populateNodeSource() stamps the optional yamlPosition on the node's
source envelope; errSource() (used by mid-parse throws) does the same.

Per the FR5b spec's "format becomes yaml" branch, the type union of
ErrorSource was widened so the `format: "json"` variant also accepts an
optional `yamlPosition`. The cross-port reason for keeping
`format: "json"` (rather than flipping to `"yaml"` per the spec) on
buildTree-emitted errors is documented in source.ts: until C#/Java/Python
also ship FR5b, flipping the discriminator would diverge TS from the
three other ports' parser output and the existing yaml-conformance
fixtures' format-discriminator. The next FR5b TS PR — once all four
ports support yamlPosition — flips format to `"yaml"` and mass-updates
the fixtures in lockstep.

Adds test/yaml-positions.test.ts (11 tests, 33 assertions): walker layer
(position-by-key map presence + non-enumerable + alias resolution),
desugar layer (Rule-5 rename, Rule-2 scalar inheritance, Rule-4 `[]`
strip), loader layer (root + nested nodes carry yamlPosition; JSON
control has no yamlPosition; mid-parse ERR_RESERVED_ATTR error envelope
carries the YAML position; empty body still gets the wrapper's
position).

Test counts: 1226 -> 1237 in packages/metadata (no regressions; +11
new). Full server/typescript suite: 2680 pass, 0 fail.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/metadata/src/parser-core.ts

@@ -32,6 +32,7 @@ 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 { getYamlPosition, type YamlPosition } from "./core/yaml-positions.js";
 import {
   TYPE_ATTR,
   TYPE_FIELD,
@@ -82,6 +83,13 @@ 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 {
@@ -102,6 +110,19 @@ export interface ParseResult {
 
 export function errSource(): ErrorSource {
   if (_currentPath !== undefined && _currentSourceId !== undefined) {
+    // FR5b note — when parsing a YAML input, buildTree-emitted errors keep
+    // `format: "json"` (the cross-port FR5a default) and surface the
+    // optional `yamlPosition` instead. This preserves the existing
+    // yaml-conformance fixtures' format-discriminator until C#/Java/Python
+    // also ship FR5b. See `source.ts` for the type-level rationale.
+    if (_currentFormat === "yaml" && _currentYamlPosition !== undefined) {
+      return {
+        format: "json",
+        files: [_currentSourceId],
+        jsonPath: _currentPath.toString(),
+        yamlPosition: _currentYamlPosition,
+      };
+    }
     return {
       format: "json",
       files: [_currentSourceId],
@@ -203,17 +224,39 @@ 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 }`.
+// 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;
-
-/** 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). */
+// 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 note — see `errSource()` for the cross-port rationale on why YAML
+ *  inputs still emit `format: "json"` plus an optional `yamlPosition`,
+ *  rather than `format: "yaml"`, until C#/Java/Python ship FR5b and the
+ *  yaml-conformance fixtures' format discriminator is mass-updated. */
 function populateNodeSource(node: MetaData): void {
   if (_currentPath === undefined || _currentSourceId === undefined) return;
+  if (_currentFormat === "yaml" && _currentYamlPosition !== undefined) {
+    node.setSource({
+      format: "json",
+      files: [_currentSourceId],
+      jsonPath: _currentPath.toString(),
+      yamlPosition: _currentYamlPosition,
+    });
+    return;
+  }
   node.setSource({
     format: "json",
     files: [_currentSourceId],
@@ -245,6 +288,10 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
   // 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)) {
@@ -304,6 +351,11 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
     // 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 ---
@@ -356,6 +408,8 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
     _currentErrors = undefined;
     _currentPath = undefined;
     _currentSourceId = undefined;
+    _currentFormat = "json";
+    _currentYamlPosition = undefined;
   }
 }
 
@@ -794,6 +848,14 @@ function processChildren(
     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(
@@ -802,6 +864,7 @@ function processChildren(
       );
       _currentPath?.pop(); // pop child wrapper key
       _currentPath?.pop(); // pop array index
+      _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
       continue;
     }
 
@@ -828,6 +891,7 @@ function processChildren(
         );
         _currentPath?.pop(); // pop child wrapper key
         _currentPath?.pop(); // pop array index
+        _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
         continue; // skip this child
       }
     }
@@ -858,6 +922,7 @@ function processChildren(
     }
     _currentPath?.pop(); // pop child wrapper key
     _currentPath?.pop(); // pop array index
+    _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
   }
   _currentPath?.pop(); // pop the "children" key
 }

server/typescript/packages/metadata/src/source.ts

@@ -7,9 +7,21 @@
 // them byte-identically.
 
 /** Discriminated union over the provenance variants a metadata node or error
- *  can carry. See ADR-0009 §Decision for the canonical shape. */
+ *  can carry. See ADR-0009 §Decision for the canonical shape.
+ *
+ *  FR5b note (TS reference port, 2026-05-26): `yamlPosition` is also
+ *  allowed as an OPTIONAL field on the `format: "json"` variant so that
+ *  buildTree-emitted errors from a YAML input can still carry the source
+ *  position without re-flagging the format discriminator. Until ALL four
+ *  ports ship FR5b — at which point buildTree-emitted errors flip to
+ *  `format: "yaml"` and the conformance fixtures are mass-updated — keeping
+ *  the discriminator at `"json"` preserves cross-port fixture parity (the
+ *  3 yaml-conformance fixtures whose buildTree-side errors are
+ *  format-keyed `"json"` would otherwise diverge until C#/Java/Python
+ *  catch up). See the FR5b TS implementation report. */
 export type ErrorSource =
-  | { format: "json"; files: [string]; jsonPath: string }
+  | { format: "json"; files: [string]; jsonPath: string;
+      yamlPosition?: { line: number; col: number } }
   | { format: "yaml"; files: [string]; jsonPath: string;
       yamlPosition?: { line: number; col: number } }
   | { format: "merged"; files: string[]; jsonPath: string;