@metaobjectsdev/metadata 1.0.3 → 1.0.4

package/src/loader/meta-data-loader.ts

@@ -25,7 +25,7 @@ import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields, validateProjectionFilter, validateRetiredRequirementLinks } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateOneSideReferenceResolution, validateIndexLookupFields, validateProjectionFilter, validateRetiredRequirementLinks } from "./validation-passes.js";
 import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { validateSourceEscapes } from "../persistence/source/validate-source-escapes.js";
@@ -652,6 +652,12 @@ export class MetaDataLoader {
       // are invalid on a 1:N relationship.
       errors.push(...validateRelationships(root));
 
+      // Rule (e) — #368: a `@cardinality: one` relationship must resolve to
+      // exactly one identity.reference when its declaring entity holds more
+      // than one onto the same target; an unresolvable case is a load error
+      // naming the candidates (ADR-0029 §5).
+      errors.push(...validateOneSideReferenceResolution(root));
+
       // index.lookup @fields resolution — each index.lookup must name ≥1 field,
       // and every field must exist in the entity's effective (resolved) field set
       // (ADR-0039: resolving accessor, so inherited fields via extends are visible).

package/src/loader/validation-passes.ts

@@ -129,6 +129,11 @@ import {
   CARDINALITY_ONE,
   CARDINALITY_MANY,
 } from "../core/relationship/relationship-constants.js";
+import {
+  referenceCandidatesFor,
+  resolveRelationshipReference,
+} from "../core/relationship/resolve-relationship-reference.js";
+import type { MetaRoot } from "../shared/meta-root.js";
 import { stripPackage } from "../naming.js";
 import {
   FILTER_COMPOSE_OR,
@@ -1938,11 +1943,29 @@ export function validateDataGridFilterValues(root: MetaData): ParseError[] {
 //   (c) When @through is present: the named entity must exist and declare exactly
 //       two identity.reference children; @sourceRefField (if present) must match
 //       one of those references' FK fields → ERR_INVALID_RELATIONSHIP.
-//   (d) @through / @sourceRefField / @symmetric are invalid on a non-M:N
-//       relationship (@cardinality != "many", or no @through) → ERR_INVALID_RELATIONSHIP.
+//   (d) @through / @symmetric are invalid on a non-M:N relationship
+//       (@cardinality != "many", or no @through) → ERR_INVALID_RELATIONSHIP.
+//       @sourceRefField is also invalid there, EXCEPT on @cardinality: "one"
+//       (#368: it then names which of several identity.reference nodes onto
+//       the same target the relationship navigates).
 //
-// Own-relationships only: a relationship is validated on the entity that declares
-// it (matching the own-attrs policy of the other passes).
+// ADR-0039: resolving, not own-only (#368 fix round 3) — every rule above
+// validates a property of the relationship's OWN declaration (its attrs,
+// plus for rule (c) the @through target resolved against the root), so a
+// relationship inherited via extends must be validated wherever it's
+// visible, or a child entity that only SEES the relationship through
+// inheritance could carry a violation no pass ever examines. That makes an
+// inherited, UNMODIFIED relationship visited once per inheriting entity —
+// checked once below (keyed on the relationship node's own identity), not
+// once per entity, using the DECLARING entity (rel.parent) rather than
+// whichever entity's effective view got there first for every piece of
+// context a rule reads (message text, @through's package per ADR-0042, rule
+// (a)'s self-join comparison). That keeps each check's result independent of
+// which entity triggered it, which is what makes "checked once" both
+// sufficient and correct. An override replaces the node in place
+// (MetaData._effectiveChildren), so it is never the same object as what it
+// overrides and is never skipped against it — a genuinely different
+// declaration is always independently checked.
 // ---------------------------------------------------------------------------
 
 // The junction's reference view: the validator and the runtime/codegen FK
@@ -1970,14 +1993,36 @@ function _countJunctionReferences(junction: MetaData): number {
 
 export function validateRelationships(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
+  // #368 fix round 3 — the outer loop below is now resolving (obj.relationships()),
+  // so a relationship inherited unmodified by N entities is reached N times. Its
+  // own attrs never change based on who inherits it, so re-validating it more
+  // than once would report the identical finding N times — pure noise. Checked
+  // is keyed on the relationship NODE's own object identity: MetaData._effectiveChildren
+  // reuses the super's child object in place for an unmodified inherited child,
+  // so the same physical declaration IS the same object everywhere it's visible,
+  // while an override replaces it with a genuinely different object (correctly
+  // NOT skipped — a distinct declaration is a distinct finding).
+  const checked = new Set<MetaData>();
   // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
   for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
-    // ADR-0042 — a bare @through resolves in the declaring entity's package.
-    const referrerPkg = obj.package ?? obj.fileDefaultPackage ?? "";
-    // ADR-0039: own — a relationship is validated on the entity that DECLARES it
-    // (the M:N slim-vocabulary rules apply to own-declared relationships; its
-    // inheritable attrs are read resolving below).
-    for (const rel of obj.ownChildren().filter((c) => c.type === TYPE_RELATIONSHIP)) {
+    // ADR-0039: resolving — see the header comment above: rule (d) (like rule
+    // (e)) must see a relationship inherited via extends, not just this
+    // entity's own declarations. `checked` absorbs the resulting revisits.
+    for (const rel of (obj as MetaObject).relationships()) {
+      if (checked.has(rel)) continue;
+      checked.add(rel);
+
+      // Every rule below validates a property of the relationship's OWN
+      // declaration (its attrs, plus for rule (c) the @through target), so
+      // context — the entity name in messages, the package a bare @through
+      // resolves in (ADR-0042), and rule (a)'s self-join comparison — is
+      // always the entity that DECLARES `rel` (rel.parent), never `obj` (the
+      // entity whose effective view happened to reach it first). This keeps
+      // the check's result independent of iteration order/inheritance depth,
+      // which is what makes checking each node exactly once correct.
+      const declaringEntity = rel.parent ?? obj;
+      const referrerPkg = declaringEntity.package ?? declaringEntity.fileDefaultPackage ?? "";
+
       // ADR-0039: resolving — a relationship may inherit its M:N attrs via extends.
       const through = rel.attr(RELATIONSHIP_ATTR_THROUGH);
       const sourceRefField = rel.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
@@ -1999,16 +2044,23 @@ export function validateRelationships(root: MetaData): ParseError[] {
         if (hasThrough) {
           errors.push(
             new ParseError(
-              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_THROUGH} but is not a M:N ` +
+              `relationship "${declaringEntity.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_THROUGH} but is not a M:N ` +
                 `relationship (requires @${RELATIONSHIP_ATTR_CARDINALITY}: "${CARDINALITY_MANY}").`,
               { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
             ),
           );
         }
-        if (hasSourceRefField) {
+        // #368: @sourceRefField also disambiguates a `@cardinality: one`
+        // relationship when the entity holds more than one identity.reference
+        // onto the same target. Only the M:N *junction* reading is rejected
+        // here; rule (e) — validateOneSideReferenceResolution, below in this
+        // file — checks that it names a real local reference.
+        if (hasSourceRefField && cardinality !== CARDINALITY_ONE) {
           errors.push(
             new ParseError(
-              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} but is not a M:N relationship.`,
+              `relationship "${declaringEntity.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} but is neither a M:N ` +
+                `relationship (requires @${RELATIONSHIP_ATTR_THROUGH} with @${RELATIONSHIP_ATTR_CARDINALITY}: "${CARDINALITY_MANY}") ` +
+                `nor a @${RELATIONSHIP_ATTR_CARDINALITY}: "${CARDINALITY_ONE}" relationship.`,
               { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
             ),
           );
@@ -2016,7 +2068,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
         if (symmetric) {
           errors.push(
             new ParseError(
-              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but is not a M:N relationship.`,
+              `relationship "${declaringEntity.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but is not a M:N relationship.`,
               { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
             ),
           );
@@ -2028,7 +2080,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
       if (symmetric && hasSourceRefField) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" sets both @${RELATIONSHIP_ATTR_SYMMETRIC} and ` +
+            `relationship "${declaringEntity.name}.${rel.name}" sets both @${RELATIONSHIP_ATTR_SYMMETRIC} and ` +
               `@${RELATIONSHIP_ATTR_SOURCE_REF_FIELD}; they are mutually exclusive.`,
             { code: "ERR_BAD_ATTR_VALUE", source: rel.source },
           ),
@@ -2040,12 +2092,13 @@ export function validateRelationships(root: MetaData): ParseError[] {
       // in this package is self, but an FQN "other::Widget" (a different same-short-
       // name entity) is NOT (comparing stripped short names would misclassify it).
       const isSelfJoin =
-        typeof objectRef === "string" && resolveObjectRef(root, objectRef, referrerPkg).node === obj;
+        typeof objectRef === "string" &&
+        resolveObjectRef(root, objectRef, referrerPkg).node === declaringEntity;
       if (symmetric && !isSelfJoin) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but @${RELATIONSHIP_ATTR_OBJECT_REF} ` +
-              `"${String(objectRef)}" is not the declaring entity "${obj.name}"; @${RELATIONSHIP_ATTR_SYMMETRIC} is self-join-only.`,
+            `relationship "${declaringEntity.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but @${RELATIONSHIP_ATTR_OBJECT_REF} ` +
+              `"${String(objectRef)}" is not the declaring entity "${declaringEntity.name}"; @${RELATIONSHIP_ATTR_SYMMETRIC} is self-join-only.`,
             { code: "ERR_BAD_ATTR_VALUE", source: rel.source },
           ),
         );
@@ -2056,8 +2109,8 @@ export function validateRelationships(root: MetaData): ParseError[] {
       if (!junction) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" does not resolve to an entity.${didYouMeanHint(root, String(through))}`,
-            { code: "ERR_INVALID_RELATIONSHIP", source: resolvedSource(rel.source, `${obj.fqn()}::${rel.name}`, String(through)) },
+            `relationship "${declaringEntity.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" does not resolve to an entity.${didYouMeanHint(root, String(through))}`,
+            { code: "ERR_INVALID_RELATIONSHIP", source: resolvedSource(rel.source, `${declaringEntity.fqn()}::${rel.name}`, String(through)) },
           ),
         );
         continue;
@@ -2069,7 +2122,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
       if (junction.subType !== OBJECT_SUBTYPE_ENTITY) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" resolves to ` +
+            `relationship "${declaringEntity.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" resolves to ` +
               `${junction.type}.${junction.subType}, not an entity — a junction is a persisted join table ` +
               `and must be object.entity.`,
             { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
@@ -2081,7 +2134,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
       if (refCount !== 2) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" must declare exactly two ` +
+            `relationship "${declaringEntity.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" must declare exactly two ` +
               `identity.reference children (one per FK side); found ${refCount}.`,
             { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
           ),
@@ -2094,7 +2147,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
         if (!fkFields.includes(sourceRefField as string)) {
           errors.push(
             new ParseError(
-              `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} "${sourceRefField}" does not match ` +
+              `relationship "${declaringEntity.name}.${rel.name}" @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} "${sourceRefField}" does not match ` +
                 `any identity.reference FK field on junction "${through}". Available: ${fkFields.join(", ") || "(none)"}.`,
               { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
             ),
@@ -2106,6 +2159,111 @@ export function validateRelationships(root: MetaData): ParseError[] {
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Rule (e) — #368: a `@cardinality: one` relationship must resolve to exactly
+// one identity.reference. Two references onto the same target are
+// indistinguishable from the relationship's @objectRef alone, so the resolver
+// would silently emit the first one's FK column. ADR-0029 §5: a second path
+// is a load error naming the candidates.
+//
+// Registered alongside validateRelationships (the M:N slim-vocabulary pass,
+// above) — same deferred-resolution timing (after all files load + extends
+// resolution).
+//
+// Scope differs deliberately from rule (d) — in SUBJECT, not in which
+// relationships each pass walks (both walk the EFFECTIVE set; rule (d) is
+// no longer own-scoped, or an M:N declaration reached only via extends
+// would go unchecked). Rule (d) validates attrs that travel with the
+// relationship's OWN declaration (@through/@symmetric/@sourceRefField), so
+// it checks each declaration EXACTLY ONCE — deduped by node identity, and
+// reported against the entity that declares it — because those attrs don't
+// change meaning depending on who inherits the relationship. Rule (e)
+// instead validates whether THIS entity's reference set resolves the
+// relationship uniquely, which is a property of the EFFECTIVE entity, not of
+// wherever the relationship happens to be declared. A child entity that
+// extends a clean parent and adds a second identity.reference onto the same
+// target makes an INHERITED relationship ambiguous on the child even though
+// the parent (and the relationship's own declaration) are untouched — own-
+// scoping this pass would leave that case unchecked, and codegen/runtime
+// (which resolve against the effective entity) would silently drop the
+// relation (#368 fix round 2). If a parent and a child are both genuinely
+// ambiguous, both are reported — two entities are broken, not one error
+// duplicated.
+// ---------------------------------------------------------------------------
+
+export function validateOneSideReferenceResolution(root: MetaRoot): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.objects()) {
+    // ADR-0039: resolving — see the scope note above: rule (e) checks THIS
+    // entity's effective reference set against every relationship it can see,
+    // including one only inherited via extends.
+    for (const rel of obj.relationships()) {
+      // ADR-0039: resolving — @cardinality/@objectRef may be inherited via extends.
+      if (rel.attr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_ONE) continue;
+      const objectRef = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
+      if (typeof objectRef !== "string" || objectRef === "") continue;
+
+      const candidates = referenceCandidatesFor(obj, objectRef);
+
+      const sourceRefField = rel.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+      const declared = typeof sourceRefField === "string" && sourceRefField !== ""
+        ? sourceRefField
+        : undefined;
+
+      if (declared !== undefined) {
+        // A declared @sourceRefField short-circuits the ladder at ANY
+        // candidate count — checked independently of resolveRelationshipReference,
+        // whose step 1 ("exactly one candidate -> that one") would otherwise
+        // silently return the lone candidate even when it disagrees with the
+        // declared field. The author named a specific FK; it must exist,
+        // whether there are zero, one, or many candidates.
+        const matchesDeclared = candidates.some((c) => c.fields[0] === declared);
+        if (matchesDeclared) continue;
+        errors.push(
+          new ParseError(
+            `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} ` +
+              `"${declared}", which names no identity.reference targeting "${objectRef}". ` +
+              `Candidates: ${formatReferenceCandidates(candidates)}.`,
+            { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+          ),
+        );
+        continue;
+      }
+
+      // No @sourceRefField declared: ambiguity only exists with 2+ candidates —
+      // resolveRelationshipReference's name-pairing step (ladder step 3) decides.
+      if (candidates.length <= 1) continue;
+      const resolved = resolveRelationshipReference(obj, rel.name, objectRef);
+      if (resolved) continue;
+
+      errors.push(
+        new ParseError(
+          `relationship "${obj.name}.${rel.name}" is ambiguous: "${obj.name}" declares ` +
+            `${candidates.length} identity.reference nodes targeting "${objectRef}" and the ` +
+            `relationship name does not pair with exactly one. Candidates: ${formatReferenceCandidates(candidates)}. ` +
+            `Set @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} to the FK field this relationship navigates.`,
+          { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+        ),
+      );
+    }
+  }
+  return errors;
+}
+
+/**
+ * Render a candidate reference as `name(fkField)`, or `name(fieldA, fieldB)`
+ * for a composite reference — so two composite references sharing a first
+ * column (e.g. both starting `tenantId`) still print distinguishably.
+ *
+ * NOTE: this is display only. Matching (both here and in
+ * resolveRelationshipReference) still keys on `fields[0]` alone — a
+ * composite reference cannot actually be disambiguated by @sourceRefField.
+ * That's a documented limitation, not fixed by this rendering change.
+ */
+function formatReferenceCandidates(candidates: readonly MetaReferenceIdentity[]): string {
+  return candidates.map((c) => `${c.name}(${c.fields.join(", ")})`).join(", ");
+}
+
 // NOTE: identity.reference @references resolution moved to the validation registry
 // (defaultValidationRegistry → a declarative reference descriptor with dottedFieldPath).
 

package/src/parser-core.ts

@@ -945,7 +945,18 @@ function parseNodeInto(
   // "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) {
+  //
+  // FR-043 Amendment 2 — `overlay: true` LICENSES the override. The conflict error
+  // exists to catch two files that collided without knowing about each other; the flag
+  // is the author saying "I know about the other declaration and I mean to change it".
+  // The loader already treats the flag specially (find-or-throw versus create-or-find),
+  // so honouring it here makes it mean ONE thing rather than two. An unmarked
+  // redeclaration still merges and still errors, which is the case FR5c was written for.
+  if (
+    fr5cActive &&
+    preMergeAttrSnapshot !== undefined &&
+    nodeData[RESERVED_KEY_OVERLAY] !== true
+  ) {
     detectAttrMergeConflicts(
       target,
       nodeData,
@@ -1037,7 +1048,9 @@ function parseNodeInto(
  *  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. */
+ *  surfaces the conflict so a consumer can fix the metadata.
+ *
+ *  NOT called for an `overlay: true` declaration — see the call site. */
 function detectAttrMergeConflicts(
   target: MetaData,
   nodeData: Record<string, unknown>,

package/src/vocabulary-rewrite-yaml.ts

@@ -0,0 +1,21 @@
+// @metaobjectsdev/metadata/vocabulary-rewrite-yaml — the YAML arm of `meta upgrade`.
+//
+// The implementation stays under `core/`, beside the canonical-JSON rewriter it mirrors.
+// This file exists so the SUBPATH NAME mirrors the layout under `src/`, which is what
+// `tsconfig.scripts.json`'s `@metaobjectsdev/metadata/*` → `src/*` mapping requires.
+//
+// Nesting is NOT the problem — the `*` matches across `/`, which is why
+// `@metaobjectsdev/codegen-ts/templates/entity-file` resolves to
+// `src/templates/entity-file.ts` perfectly well. The problem was a subpath NAMED
+// `vocabulary-rewrite-yaml` whose source sat at `src/core/vocabulary-rewrite-yaml.ts`:
+// the substitution yields `src/vocabulary-rewrite-yaml`, and that is not where the module
+// is. Renaming the export to `./core/vocabulary-rewrite-yaml` would also have satisfied
+// the rule and was the cheaper edit, but this package is published and that subpath is
+// public API, so the name stays and the layout moves to meet it.
+//
+// When the mapping misses, tsc falls through to `node_modules` and reads `dist/` — present
+// for anyone who has built, absent on a fresh CI checkout where the `gates` lane runs
+// `bun install` and never builds. `./library` shipped that way and took the lane down;
+// this one had not been imported from anywhere `scripts/` typechecks, so it was latent.
+// `cli/test/subpath-resolves-under-scripts-paths.test.ts` now gates the class.
+export { rewriteYamlDocument, type YamlRewriteResult } from "./core/vocabulary-rewrite-yaml.js";