Merge worktree-fr5d-ts-2026-05-27 — FR5d TS reference (resolved envelopes for extends/@via/@payloadRef/@Of with referrer+target)

dmealing · dmealing · commit f505681e4dd6 · 2026-05-27T04:26:00.000-04:00
diff --git a/server/typescript/packages/metadata/conformance-expected-failures.json b/server/typescript/packages/metadata/conformance-expected-failures.json
@@ -1 +1,11 @@
-{ "language": "typescript", "fixtures": [] }
+{
+  "language": "typescript",
+  "fixtures": [
+    "error-extends-nonexistent",
+    "error-origin-bad-via-path",
+    "error-template-payload-ref-not-value",
+    "error-template-payload-ref-unresolved",
+    "error-template-required-slot-missing"
+  ],
+  "notes": "FR5d (2026-05-27): TS reference port emits format=resolved for reference-resolution errors (extends:, @via, @of, @payloadRef, @requiredSlots). Fixtures still encode the FR5a-era format=json envelope per the cross-port-safety stance — these will migrate once C#/Java/Python ship FR5d, at which point the ledger entries can be removed."
+}
diff --git a/server/typescript/packages/metadata/src/loader/meta-data-loader.ts b/server/typescript/packages/metadata/src/loader/meta-data-loader.ts
@@ -15,7 +15,7 @@ import { composeRegistry } from "../provider.js";
 import { TYPE_METADATA, SUBTYPE_ROOT } from "../shared/base-types.js";
 import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
-import { codeSource } from "../source.js";
+import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
 import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs } from "./validation-passes.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
@@ -379,10 +379,17 @@ export class MetaDataLoader {
     if (root !== undefined) {
       const failures = resolveDeferredSupers(root);
       for (const failure of failures) {
+        // FR5d — emit format=resolved with referrer + target. The referrer's
+        // parse-time source supplies files + jsonPath (the location of the
+        // broken `extends:` on disk); referrer = the declaring node's FQN;
+        // target = the unresolved supertype ref.
         errors.push(
           new ParseError(
             `the SuperClass '${failure.ref}' does not exist (referenced by ${failure.nodeFqn})`,
-            { code: "ERR_UNRESOLVED_SUPER", source: failure.source },
+            {
+              code: "ERR_UNRESOLVED_SUPER",
+              source: resolvedSource(failure.source, failure.nodeFqn, failure.ref),
+            },
           ),
         );
       }
diff --git a/server/typescript/packages/metadata/src/loader/validation-passes.ts b/server/typescript/packages/metadata/src/loader/validation-passes.ts
@@ -11,7 +11,7 @@
 
 import type { MetaData } from "../shared/meta-data.js";
 import { ParseError } from "../errors.js";
-import type { ErrorSource } from "../source.js";
+import { resolvedSource, type ErrorSource } from "../source.js";
 import {
   TYPE_OBJECT,
   TYPE_FIELD,
@@ -101,10 +101,15 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
     if (typeof payloadRef !== "string") continue; // absence handled by the required-attr schema check
     const payload = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === payloadRef);
     if (!payload || payload.subType !== OBJECT_SUBTYPE_VALUE) {
+      // FR5d — @payloadRef is a reference; emit format=resolved with
+      // referrer=template FQN, target=the unresolved payloadRef string.
       errors.push(
         new ParseError(
           `template "${tmpl.name}" @payloadRef "${payloadRef}" does not resolve to an object.value at root`,
-          { code: "ERR_INVALID_TEMPLATE", source: tmpl.source },
+          {
+            code: "ERR_INVALID_TEMPLATE",
+            source: resolvedSource(tmpl.source, tmpl.fqn(), payloadRef),
+          },
         ),
       );
       continue;
@@ -116,11 +121,17 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
     const slotList = Array.isArray(slots) ? slots : typeof slots === "string" ? [slots] : [];
     for (const slot of slotList) {
       if (typeof slot === "string" && !fieldNames.has(slot)) {
+        // FR5d — @requiredSlots is a field-on-payload reference; emit
+        // format=resolved with referrer=template FQN, target=`payloadRef.slot`
+        // (the dotted ref that did not resolve to a payload field).
         errors.push(
           new ParseError(
             `template "${tmpl.name}" @requiredSlots "${slot}" is not a field on payload "${payloadRef}". ` +
             `Available fields: ${[...fieldNames].join(", ")}`,
-            { code: "ERR_INVALID_TEMPLATE", source: tmpl.source },
+            {
+              code: "ERR_INVALID_TEMPLATE",
+              source: resolvedSource(tmpl.source, tmpl.fqn(), `${payloadRef}.${slot}`),
+            },
           ),
         );
       }
@@ -196,18 +207,28 @@ function _findRelationship(obj: MetaData, name: string): MetaData | undefined {
 function _validateFromPath(
   fromAttr: string,
   root: MetaData,
-  projectionName: string,
+  projection: MetaData,
   fieldName: string,
   originSource: ErrorSource,
   errors: ParseError[],
   label: string = "origin.passthrough.@from",
 ): void {
+  const projectionName = projection.name;
+  // FR5d — referrer is `<projection-FQN>::<fieldName>` (the canonical
+  // "where the broken reference lives" identifier).
+  const referrer = `${projection.fqn()}::${fieldName}`;
   const dotIdx = fromAttr.indexOf(".");
   if (dotIdx < 1 || dotIdx === fromAttr.length - 1) {
+    // Malformed shape (not "Entity.field") — not a reference resolution
+    // failure per se, but emit format=resolved with target=the bad string
+    // so consumers see the same envelope shape across all FR5d sites.
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: must be of form "Entity.field".`,
-        { code: "ERR_INVALID_ORIGIN", source: originSource },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, fromAttr),
+        },
       ),
     );
     return;
@@ -216,20 +237,28 @@ function _validateFromPath(
   const targetFieldName = fromAttr.slice(dotIdx + 1);
   const sourceObj = _findObject(root, entityName);
   if (!sourceObj) {
+    // FR5d — entity half of the ref didn't resolve. target = full ref.
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: no such entity "${entityName}".`,
-        { code: "ERR_INVALID_ORIGIN", source: originSource },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, fromAttr),
+        },
       ),
     );
     return;
   }
   const sourceField = _findField(sourceObj, targetFieldName);
   if (!sourceField) {
+    // FR5d — entity resolved, field on it did not. target = full ref.
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: no such field "${targetFieldName}" on ${entityName}.`,
-        { code: "ERR_INVALID_ORIGIN", source: originSource },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, fromAttr),
+        },
       ),
     );
   }
@@ -238,17 +267,23 @@ function _validateFromPath(
 function _validateViaPath(
   viaAttr: string,
   root: MetaData,
-  projectionName: string,
+  projection: MetaData,
   fieldName: string,
   originSource: ErrorSource,
   errors: ParseError[],
 ): void {
+  const projectionName = projection.name;
+  // FR5d — referrer is `<projection-FQN>::<fieldName>`.
+  const referrer = `${projection.fqn()}::${fieldName}`;
   const segments = viaAttr.split(".");
   if (segments.length < 2) {
     errors.push(
       new ParseError(
         `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: must be of form "Entity.relationship[.relationship...]".`,
-        { code: "ERR_INVALID_ORIGIN", source: originSource },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, viaAttr),
+        },
       ),
     );
     return;
@@ -259,18 +294,32 @@ function _validateViaPath(
     errors.push(
       new ParseError(
         `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such entity "${entityName}".`,
-        { code: "ERR_INVALID_ORIGIN", source: originSource },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, viaAttr),
+        },
       ),
     );
     return;
   }
+  // FR5d — track the deepest-valid-prefix as we walk. The prefix grows
+  // segment-by-segment; on a hop failure the error message names the prefix
+  // that DID resolve, so authors can fix multi-hop typos quickly.
+  // After the entity lookup above, the deepest valid prefix is just the
+  // entity name; each successful relationship hop appends a segment.
+  const validSegments: string[] = [entityName];
   for (const relName of relSegments) {
     const rel = _findRelationship(currentObj, relName);
     if (!rel) {
+      const prefix = validSegments.join(".");
       errors.push(
         new ParseError(
-          `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such relationship "${relName}" on ${currentObj.name}.`,
-          { code: "ERR_INVALID_ORIGIN", source: originSource },
+          `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such relationship "${relName}" on ${currentObj.name}. ` +
+          `Deepest valid prefix was "${prefix}".`,
+          {
+            code: "ERR_INVALID_ORIGIN",
+            source: resolvedSource(originSource, referrer, viaAttr),
+          },
         ),
       );
       return;
@@ -280,21 +329,32 @@ function _validateViaPath(
       errors.push(
         new ParseError(
           `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: relationship "${relName}" on ${currentObj.name} is missing @objectRef.`,
-          { code: "ERR_INVALID_ORIGIN", source: originSource },
+          {
+            code: "ERR_INVALID_ORIGIN",
+            source: resolvedSource(originSource, referrer, viaAttr),
+          },
         ),
       );
       return;
     }
     const nextObj = _findObject(root, refTarget);
     if (!nextObj) {
+      // FR5d — relationship's @objectRef points at a missing entity. This
+      // is the @objectRef-resolution edge of the via-path walk (the "5th
+      // site" in FR5d's scope list for @objectRef references encountered
+      // transitively).
       errors.push(
         new ParseError(
           `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: relationship "${relName}" points to non-existent entity "${refTarget}".`,
-          { code: "ERR_INVALID_ORIGIN", source: originSource },
+          {
+            code: "ERR_INVALID_ORIGIN",
+            source: resolvedSource(originSource, referrer, refTarget),
+          },
         ),
       );
       return;
     }
+    validSegments.push(relName);
     currentObj = nextObj;
   }
 }
@@ -307,6 +367,8 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
         if (origin.subType === ORIGIN_SUBTYPE_PASSTHROUGH) {
           const from = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
           if (typeof from !== "string" || from === "") {
+            // Missing-attr (not a reference resolution failure) — keep the
+            // node's own source envelope (json/yaml/merged).
             errors.push(
               new ParseError(
                 `origin.passthrough on ${obj.name}.${field.name}: missing @from.`,
@@ -315,10 +377,10 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             );
             continue;
           }
-          _validateFromPath(from, root, obj.name, field.name, origin.source, errors);
+          _validateFromPath(from, root, obj, field.name, origin.source, errors);
           const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
-            _validateViaPath(via, root, obj.name, field.name, origin.source, errors);
+            _validateViaPath(via, root, obj, field.name, origin.source, errors);
           }
         } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
           const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
@@ -331,7 +393,7 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             );
             continue;
           }
-          _validateFromPath(of_, root, obj.name, field.name, origin.source, errors, "origin.aggregate.@of");
+          _validateFromPath(of_, root, obj, field.name, origin.source, errors, "origin.aggregate.@of");
           const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
           if (typeof via !== "string" || via === "") {
             errors.push(
@@ -342,7 +404,7 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             );
             continue;
           }
-          _validateViaPath(via, root, obj.name, field.name, origin.source, errors);
+          _validateViaPath(via, root, obj, field.name, origin.source, errors);
         }
       }
     }
diff --git a/server/typescript/packages/metadata/src/parser-core.ts b/server/typescript/packages/metadata/src/parser-core.ts
@@ -29,7 +29,7 @@ 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 { resolvedSource, 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";
@@ -502,9 +502,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>"}'`,
-        { code: "ERR_UNRESOLVED_SUPER", source: errSource() },
+        {
+          code: "ERR_UNRESOLVED_SUPER",
+          source: resolvedSource(errSource(), model.fqn(), model.superRef),
+        },
       );
     }
   } else if (model.superRef !== undefined && accumRoot === undefined) {
diff --git a/server/typescript/packages/metadata/src/source.ts b/server/typescript/packages/metadata/src/source.ts
@@ -67,3 +67,33 @@ export interface LoaderWarning {
 export function codeSource(caller?: string): ErrorSource {
   return caller ? { format: "code", caller } : { format: "code" };
 }
+
+/** FR5d — build a `format: "resolved"` envelope from a referrer node's source
+ *  envelope (typically a `format: "json"` or `format: "yaml"` parse-time
+ *  source) plus the referrer FQN and unresolved target string.
+ *
+ *  The resolved envelope carries:
+ *    - `files`: the referrer's source files (so editors can jump to it),
+ *    - `jsonPath`: the referrer's jsonPath when known (the location of the
+ *       broken reference on disk),
+ *    - `referrer`: the FQN of the metadata node that declared the broken
+ *       reference (e.g. "myapp::content::Video"),
+ *    - `target`:  the unresolved reference string itself (e.g. "BaseEntity",
+ *       "Program.weeks.invalid", "DoesNotExist").
+ *
+ *  `referrerSource` may be any FR5a variant — we read its files/jsonPath
+ *  best-effort and fall back to an empty `files: []` when the referrer's
+ *  source is itself a `code`/`database` envelope. */
+export function resolvedSource(
+  referrerSource: ErrorSource,
+  referrer: string,
+  target: string,
+): ErrorSource {
+  const files = "files" in referrerSource ? [...referrerSource.files] : [];
+  const jsonPath = "jsonPath" in referrerSource ? referrerSource.jsonPath : undefined;
+  const out: ErrorSource = { format: "resolved", files, referrer, target };
+  if (jsonPath !== undefined) {
+    (out as { jsonPath?: string }).jsonPath = jsonPath;
+  }
+  return out;
+}
diff --git a/server/typescript/packages/metadata/test/fr5d-reference-resolution-errors.test.ts b/server/typescript/packages/metadata/test/fr5d-reference-resolution-errors.test.ts
