fix(metadata-ts): resolve cross-PACKAGE cross-file extends by parse-time file-default package

Super-resolution previously matched a no-own-package node by an effective
package derived from the post-merge tree walk. When files declared DIFFERENT
file-default packages, a base node (e.g. acme::common::BaseTenantEntity) was no
longer matchable as its file-default-qualified name after merge into the shared
root — so a concrete-first cross-package extends failed with "the SuperClass
... does not exist".

Mirror Java's BaseMetaDataParser: capture each node's file-default package
(the file's top-level metadata.package) at PARSE time as a resolution-only
field (MetaData.fileDefaultPackage), expose MetaData.resolutionKey()
(<pkg>::<name>), and match against it in findInTree. Resolution is now
independent of load order and merge context. Object fqn() stays BARE (FR5d
cross-port referrer-envelope contract unchanged).

Adds permanent cross-PACKAGE regression tests (both load orders), genericized
to acme::common / acme::lms.

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

Author: dmealing

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

@@ -489,6 +489,17 @@ function parseNodeFresh(
   // is the only caller during loading; freeze runs in the loader after).
   populateNodeSource(model);
 
+  // --- Capture the file-default package at PARSE time (resolution-only) ---
+  // `inheritedContextPkg` is the package threaded down from the file's root
+  // `metadata.package` (the nearest packaged ancestor). Recording it here —
+  // when the declaring file's package is known — lets super-resolution match
+  // this node by its effective qualified key regardless of post-merge tree
+  // shape or load order. This does NOT touch the node's `package` or `fqn()`
+  // (objects stay bare per FR5d). Mirrors Java's parse-time getDefaultPackageName().
+  if (inheritedContextPkg !== "") {
+    model.setFileDefaultPackage(inheritedContextPkg);
+  }
+
   // --- Apply reserved keys (package, extends, abstract, isArray) ---
   applyReservedKeys(model, nodeData, strict, source, path, warnings, inheritedContextPkg);
 

server/typescript/packages/metadata/src/shared/meta-data.ts

@@ -24,6 +24,16 @@ export abstract class MetaData {
 
   // Identity / packaging
   package?: string;
+  // Resolution-only: the file-default package (the top-level `metadata.package`)
+  // of the FILE in which this node was declared, captured at PARSE time. This is
+  // NOT folded into fqn() (object fqn() stays BARE for the FR5d cross-port
+  // referrer-envelope contract) — it exists solely so super-resolution can match
+  // a node by its EFFECTIVE qualified key `<fileDefaultPackage>::<name>` even
+  // when the node carries no own `package`. Capturing it at parse time (when the
+  // declaring file's package is known) makes resolution independent of load
+  // order and post-merge tree shape. Mirrors Java's BaseMetaDataParser, which
+  // folds getDefaultPackageName() into the registered name at parse time.
+  fileDefaultPackage?: string;
   superRef?: string;         // raw super reference string, pre-resolution
   private _superData?: MetaData; // post-resolution pointer; set by setSuperResolved() after parsing
   isAbstract: boolean = false;
@@ -132,6 +142,31 @@ export abstract class MetaData {
     this.package = pkg;
   }
 
+  /**
+   * Loader-internal: record the file-default package captured at parse time.
+   * See the `fileDefaultPackage` field doc. Honors the frozen-guard.
+   * @internal
+   */
+  setFileDefaultPackage(pkg: string): void {
+    this._assertNotFrozen();
+    this.fileDefaultPackage = pkg;
+  }
+
+  /**
+   * The node's EFFECTIVE qualified key for super-resolution matching:
+   * `<pkg>::<name>` where pkg is the node's own package if set, else the
+   * file-default package captured at parse time. Returns the bare name when
+   * neither is available. Used by super-resolution ONLY — distinct from fqn(),
+   * which stays bare for objects per the FR5d cross-port contract.
+   */
+  resolutionKey(): string {
+    const pkg = this.package ?? this.fileDefaultPackage;
+    if (pkg !== undefined && pkg !== "") {
+      return `${pkg}${PACKAGE_SEPARATOR}${this.name}`;
+    }
+    return this.name;
+  }
+
   // ---------------------------------------------------------------------------
   // Super
   // ---------------------------------------------------------------------------

server/typescript/packages/metadata/src/super-resolve.ts

@@ -19,11 +19,28 @@ import { PACKAGE_SEPARATOR, PACKAGE_PARENT } from "./shared/structural.js";
 // ---------------------------------------------------------------------------
 
 /**
- * Recursively searches the tree for a node whose fqn() matches.
- * Returns the first match, or undefined.
+ * Recursively searches the tree for a node whose qualified name matches `fqn`.
+ *
+ * A node is matched by its own `fqn()` (covers the explicit-package and
+ * no-package-at-all cases) OR by its EFFECTIVE qualified key
+ * `<fileDefaultPackage>::<name>` (`MetaData.resolutionKey()`) — the
+ * file-default package captured at PARSE time. This mirrors Java, where
+ * `BaseMetaDataParser` folds the file-default package into the registered name
+ * at parse time (so an object `BaseEntity` declared under `package: acme` is
+ * registered as `acme::BaseEntity` and a fully-qualified `extends:
+ * acme::BaseEntity` resolves) — even though TS keeps object `fqn()` bare for
+ * the FR5d referrer-envelope cross-port contract.
+ *
+ * Because the resolution key is captured at parse time (not derived from the
+ * post-merge tree), this is independent of load order AND of whether the base
+ * node's file-default package differs from the referrer's — the cross-PACKAGE
+ * cross-file case. No package is threaded down the walk anymore.
  */
 function findInTree(root: MetaData, fqn: string): MetaData | undefined {
   if (root.fqn() === fqn) return root;
+  if (root.package === undefined && root.name !== "" && root.resolutionKey() === fqn) {
+    return root;
+  }
   for (const child of root.ownChildren()) {
     const found = findInTree(child, fqn);
     if (found !== undefined) return found;
@@ -110,18 +127,19 @@ export interface DeferredSuperFailure {
  * have been parsed with deferSuperResolution: true. Unresolved refs are
  * collected and returned — caller decides whether to throw or warn.
  *
- * Tracks an inherited context package while walking so children whose own
- * `package` is unset (e.g., fields inside an object) still resolve against
- * the parent's package — matching the parser's eager-resolution semantics.
+ * The referrer's context package (for bare/same-package shorthand refs) comes
+ * from the node's own `package`, else the file-default package captured at
+ * PARSE time (`fileDefaultPackage`). Both are order- and merge-independent, so
+ * resolution does not depend on the post-merge tree shape.
  *
  * Idempotent: nodes that already have superResolved set are skipped.
  */
 export function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[] {
   const failures: DeferredSuperFailure[] = [];
-  walk(root, "", (node, ctxPkg) => {
+  walk(root, (node) => {
     if (node.superRef === undefined) return;
     if (node.superResolved !== undefined) return;
-    const effectivePkg = node.package ?? ctxPkg;
+    const effectivePkg = node.package ?? node.fileDefaultPackage ?? "";
     const target = resolveSuperRef(node.superRef, effectivePkg, root);
     if (target !== undefined) {
       try {
@@ -136,14 +154,9 @@ export function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[] {
   return failures;
 }
 
-function walk(
-  node: MetaData,
-  ctxPkg: string,
-  visit: (n: MetaData, ctx: string) => void,
-): void {
-  visit(node, ctxPkg);
-  const nextCtx = node.package ?? ctxPkg;
+function walk(node: MetaData, visit: (n: MetaData) => void): void {
+  visit(node);
   for (const child of node.ownChildren()) {
-    walk(child, nextCtx, visit);
+    walk(child, visit);
   }
 }

server/typescript/packages/metadata/test/file-default-package.test.ts

@@ -0,0 +1,235 @@
+// file-default-package.test.ts
+//
+// Regression: a fully-qualified `extends:` that names a supertype by its
+// file-default package (the top-level `metadata.package`) must RESOLVE, even
+// though the supertype's own node carries no explicit `package:` key.
+//
+// Java's BaseMetaDataParser folds the file-default package into the registered
+// NAME (so an object `BaseEntity` under `package: acme::common` is
+// registered as `acme::common::BaseEntity`, and `extends:
+// acme::common::BaseEntity` resolves). The TS parser keeps object `fqn()`
+// BARE on purpose — the FR5d referrer-envelope cross-port contract relies on it
+// (see Fr5dReferenceResolutionTest: "TS's MetaData.fqn() does NOT propagate the
+// root package; Java uses getShortName() to match"). So the bug is NOT that the
+// object FQN should gain the package — it is that SUPER RESOLUTION must match a
+// node by its EFFECTIVE qualified name (inheritedPkg::name) even when the node's
+// fqn() is bare. Without that, the cross-ref silently fails to resolve and
+// downstream `meta gen` breaks.
+
+import { test, expect } from "bun:test";
+import { TypeRegistry } from "../src/registry.js";
+import { registerCoreTypes } from "../src/core-types.js";
+import { parseYaml } from "../src/core/parser-yaml.js";
+import { TYPE_OBJECT } from "../src/shared/base-types.js";
+import { MetaDataLoader } from "../src/loader/meta-data-loader.js";
+import { InMemoryStringSource } from "../src/loader/meta-data-source.js";
+
+function coreRegistry(): TypeRegistry {
+  const registry = new TypeRegistry();
+  registerCoreTypes(registry);
+  return registry;
+}
+
+// ---------------------------------------------------------------------------
+// 1) Same-file extends by fully-qualified (file-default) name resolves.
+// ---------------------------------------------------------------------------
+
+test("same-file extends by file-default-qualified name resolves", () => {
+  const yaml = `
+metadata:
+  package: acme::lms
+  children:
+    - object.entity:
+        name: BaseEntity
+        abstract: true
+        children:
+          - field.string: { name: id }
+    - object.entity:
+        name: Course
+        extends: acme::lms::BaseEntity
+        children:
+          - field.string: { name: title }
+`;
+  const result = parseYaml(yaml, { registry: coreRegistry() });
+  expect(result.errors).toEqual([]);
+
+  const base = result.root.childByTypeAndName(TYPE_OBJECT, "BaseEntity")!;
+  const course = result.root.childByTypeAndName(TYPE_OBJECT, "Course")!;
+
+  // Cross-port contract: object fqn() stays BARE (TS does not propagate the
+  // file-default package into the node's fqn — Java mirrors this via
+  // getShortName() for FR5d envelopes).
+  expect(base.fqn()).toBe("BaseEntity");
+  expect(course.fqn()).toBe("Course");
+
+  // The super must RESOLVE despite the fully-qualified ref — this is the fix.
+  expect(course.superData).toBeDefined();
+  expect(course.superData).toBe(base);
+});
+
+// ---------------------------------------------------------------------------
+// 2) Fields within objects keep simple names (unchanged behavior).
+// ---------------------------------------------------------------------------
+
+test("fields within objects keep simple names", () => {
+  const yaml = `
+metadata:
+  package: acme::lms
+  children:
+    - object.entity:
+        name: Course
+        children:
+          - field.string: { name: id }
+`;
+  const result = parseYaml(yaml, { registry: coreRegistry() });
+  expect(result.errors).toEqual([]);
+
+  const course = result.root.childByTypeAndName(TYPE_OBJECT, "Course")!;
+  const id = course.ownChildren().find((c) => c.name === "id");
+  expect(id).toBeDefined();
+  expect(id!.package).toBeUndefined();
+  expect(id!.fqn()).toBe("id");
+});
+
+// ---------------------------------------------------------------------------
+// 3) Cross-file extends by fully-qualified (file-default) name resolves.
+//    The base entity declares no explicit package; the fully-qualified ref
+//    `acme::common::BaseEntity` must still resolve through the loader.
+// ---------------------------------------------------------------------------
+
+test("cross-file extends by file-default-qualified name resolves", async () => {
+  const baseYaml = `
+metadata:
+  package: acme::common
+  children:
+    - object.entity:
+        name: BaseEntity
+        abstract: true
+        children:
+          - field.string: { name: id }
+`;
+  const courseYaml = `
+metadata:
+  package: acme::common
+  children:
+    - object.entity:
+        name: Course
+        extends: acme::common::BaseEntity
+        children:
+          - field.string: { name: title }
+`;
+
+  const loader = new MetaDataLoader({ registry: coreRegistry() });
+  const result = await loader.load([
+    new InMemoryStringSource(baseYaml, { id: "base.yaml", format: "yaml" }),
+    new InMemoryStringSource(courseYaml, { id: "course.yaml", format: "yaml" }),
+  ]);
+  expect(result.errors).toEqual([]);
+
+  const base = loader.root.childByTypeAndName(TYPE_OBJECT, "BaseEntity")!;
+  const course = loader.root.childByTypeAndName(TYPE_OBJECT, "Course")!;
+
+  // Bare fqn() — cross-port contract.
+  expect(base.fqn()).toBe("BaseEntity");
+  expect(course.fqn()).toBe("Course");
+
+  // Super resolves across files via the file-default-qualified ref.
+  expect(course.superData).toBeDefined();
+  expect(course.superData).toBe(base);
+});
+
+// ---------------------------------------------------------------------------
+// 4) Cross-PACKAGE cross-file extends by fully-qualified (file-default) name.
+//    The base entity lives in a DIFFERENT file-default package (acme::common)
+//    from the concrete entity (acme::lms). Loaded concrete-FIRST, so the base
+//    node does not yet exist when Course is parsed — deferred resolution must
+//    match it by its file-default-qualified key (acme::common::BaseTenantEntity)
+//    regardless of merge order. This is the real downstream shape.
+// ---------------------------------------------------------------------------
+
+test("cross-PACKAGE cross-file extends resolves (concrete loaded first)", async () => {
+  const baseYaml = `
+metadata:
+  package: acme::common
+  children:
+    - object.entity:
+        name: BaseTenantEntity
+        abstract: true
+        children:
+          - field.string: { name: id }
+`;
+  const courseYaml = `
+metadata:
+  package: acme::lms
+  children:
+    - object.entity:
+        name: Course
+        extends: acme::common::BaseTenantEntity
+        children:
+          - field.string: { name: title }
+`;
+
+  const loader = new MetaDataLoader({ registry: coreRegistry() });
+  const result = await loader.load([
+    // concrete FIRST — base not yet present when Course's super is parsed.
+    new InMemoryStringSource(courseYaml, { id: "lms.yaml", format: "yaml" }),
+    new InMemoryStringSource(baseYaml, { id: "common.yaml", format: "yaml" }),
+  ]);
+  expect(result.errors).toEqual([]);
+
+  const base = loader.root.childByTypeAndName(TYPE_OBJECT, "BaseTenantEntity")!;
+  const course = loader.root.childByTypeAndName(TYPE_OBJECT, "Course")!;
+
+  // Bare fqn() — cross-port contract (FR5d).
+  expect(base.fqn()).toBe("BaseTenantEntity");
+  expect(course.fqn()).toBe("Course");
+
+  // Super resolves across packages + files via the file-default-qualified ref.
+  expect(course.superData).toBeDefined();
+  expect(course.superData).toBe(base);
+});
+
+// ---------------------------------------------------------------------------
+// 5) Same as #4 but load-order REVERSED (base first). Resolution must be
+//    order-independent: the file-default-package key is captured at PARSE time,
+//    not derived from the post-merge tree, so either order resolves.
+// ---------------------------------------------------------------------------
+
+test("cross-PACKAGE cross-file extends resolves (base loaded first)", async () => {
+  const baseYaml = `
+metadata:
+  package: acme::common
+  children:
+    - object.entity:
+        name: BaseTenantEntity
+        abstract: true
+        children:
+          - field.string: { name: id }
+`;
+  const courseYaml = `
+metadata:
+  package: acme::lms
+  children:
+    - object.entity:
+        name: Course
+        extends: acme::common::BaseTenantEntity
+        children:
+          - field.string: { name: title }
+`;
+
+  const loader = new MetaDataLoader({ registry: coreRegistry() });
+  const result = await loader.load([
+    new InMemoryStringSource(baseYaml, { id: "common.yaml", format: "yaml" }),
+    new InMemoryStringSource(courseYaml, { id: "lms.yaml", format: "yaml" }),
+  ]);
+  expect(result.errors).toEqual([]);
+
+  const base = loader.root.childByTypeAndName(TYPE_OBJECT, "BaseTenantEntity")!;
+  const course = loader.root.childByTypeAndName(TYPE_OBJECT, "Course")!;
+
+  expect(base.fqn()).toBe("BaseTenantEntity");
+  expect(course.fqn()).toBe("Course");
+
+  expect(course.superData).toBeDefined();
+  expect(course.superData).toBe(base);
+});