@metaobjectsdev/codegen-ts 1.0.2 → 1.0.4-rc.1

package/src/generators/shared-model-file.ts

@@ -0,0 +1,292 @@
+// FR-023 §4.3 — sharedModelFile(): the publisher's flattened shared-model artifact.
+//
+// A publisher project wires this generator to select a subset of its own metadata
+// (by the same include/exclude scope-pattern grammar `scope` already uses) and emit
+// it as ONE canonical-JSON `metadata.root` document plus a manifest — the artifact a
+// consumer's `meta deps sync` copies into its own repo (design §2.2, §3.2, §3.5).
+//
+// The algorithm (design §4.3), in order:
+//   1. Standalone load of `files` (default: the run's own source files, `ctx.sourceFiles`)
+//      with `ctx.registry` (the run's composed registry — the SAME vocabulary the
+//      project's own metadata loaded with), strict.
+//   2. Select top-level nodes: never `requirement.*` / `template.*` (a publisher's
+//      ledger and prompts are not a consumer's shapes), and matching the compiled
+//      include/exclude scope.
+//   3. Closure check: every `extends` target and every REF_BEARING_ATTR_NAMES value
+//      of a selected node (and of its own descendants) must resolve to a SELECTED
+//      node, else the selection is not self-contained and the build fails naming the
+//      (referrer, target) pairs.
+//   4. Serialize the selection with `serializeSharedDocument` — raw own-layer form,
+//      `extends` preserved, sorted by resolution key.
+//   5. Re-load the emitted document standalone with CORE providers only, strict — a
+//      consumer loads it with ITS providers, and a Phase 1 export must not need the
+//      publisher's non-core vocabulary.
+//   6. Emit `<name>.metaobjects.json` + `metaobjects.pkg.json` (design §3.2).
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  type MetaData,
+  type MetaRoot,
+  MetaDataLoader,
+  InMemoryStringSource,
+  compileScope,
+  matchesScope,
+  REF_BEARING_ATTR_NAMES,
+  resolveObjectRef,
+  serializeSharedDocument,
+  packageOfResolutionKey,
+  PACKAGE_SEPARATOR,
+  CHILD_REF_SEPARATOR,
+  TYPE_REQUIREMENT,
+  TYPE_TEMPLATE,
+  METAMODEL_VERSION,
+} from "@metaobjectsdev/metadata";
+import { FileSource } from "@metaobjectsdev/metadata/core";
+import { oncePerRun, type Generator, type GenContext, type EmittedFile } from "../generator.js";
+import { effectivePackage } from "../docs-paths.js";
+
+// The FR-023 manifest/artifact tool-file conventions (design §3.2, §4.3, "Hash
+// format"). Their single canonical source is `sdk/src/dependencies.ts`
+// (`MANIFEST_FILE`, `ARTIFACT_SUFFIX`, `INTEGRITY_PREFIX`) — codegen-ts cannot
+// import sdk (the dependency runs the other way: `cli` depends on both, design
+// §4.3's closing note), so these mirror those values locally. Keep in sync —
+// exported (not merely local) so `cli`, which depends on both packages, can
+// assert equality against `sdk`'s exports in a test; see
+// `cli/test/shared-model-constants-parity.test.ts`.
+export const MANIFEST_FILE = "metaobjects.pkg.json";
+export const ARTIFACT_SUFFIX = ".metaobjects.json";
+export const INTEGRITY_PREFIX = "sha256-";
+/** design §3.2 — the manifest schema's own version, distinct from `metamodelVersion`. */
+const MANIFEST_SCHEMA_VERSION = 1;
+
+/**
+ * Separator for `checkClosure`'s dedupe key. A resolution key never contains a NUL,
+ * so this cannot collide with either half it joins — unlike a printable separator
+ * (`->`, `→`), which would need a separate argument for why no legal FQN could ever
+ * contain it. Written as the `\0` ESCAPE, never a raw control byte: a raw 0x00 in
+ * this source file previously made `git` treat it as binary, which (a) makes
+ * `git diff`/GitHub show no content for the file at all, and (b) more seriously,
+ * makes `.githooks/pre-commit`'s public-repo-hygiene grep skip its added lines
+ * entirely (a binary file's diff is never text-enumerated) — silently defeating that
+ * guard for any future edit to this file. The escape produces the byte-identical
+ * runtime string; only the SOURCE FILE's byte content changes (readable text instead
+ * of an embedded control byte).
+ */
+const DEDUPE_KEY_SEPARATOR = "\0";
+
+export interface SharedModelFileOpts {
+  /** The dependency key a consumer will `meta deps sync` under. Also the artifact's
+   *  basename: emits `<name>.metaobjects.json`. */
+  name: string;
+  /** Scope-pattern include list (the same `acme::platform::**` grammar as `scope`). */
+  include: readonly string[];
+  /** Applied after `include`. */
+  exclude?: readonly string[];
+  /** Which of the publisher's own source files may contribute. Default: the run's
+   *  own source files (`ctx.sourceFiles` — everything `files?` narrows). */
+  files?: readonly string[];
+  /** The published version. Default: the nearest `package.json` `version` walking
+   *  up from `ctx.projectRoot`. */
+  version?: string;
+  /** Named output target, as on every other generator. */
+  target?: string;
+}
+
+/** Everything before the first `CHILD_REF_SEPARATOR` that follows the LAST
+ *  `PACKAGE_SEPARATOR` — the object part of a possibly dotted ref (ADR-0029's
+ *  addressing model: package segments never fold onto a non-root child, so a
+ *  `.` before the final `::`-segment can't occur). Mirrors the private
+ *  `splitChildTail` in `naming-refs.ts` (not exported); `extends` and the
+ *  origin `@from`/`@of`/`@via` attrs are the only REF_BEARING_ATTR_NAMES that
+ *  can carry a dotted child tail — every other ref-bearing attr is already a
+ *  bare object ref, and stripping a tail that isn't there is a no-op. */
+function refOwner(ref: string): string {
+  const lastSep = ref.lastIndexOf(PACKAGE_SEPARATOR);
+  const segStart = lastSep === -1 ? 0 : lastSep + PACKAGE_SEPARATOR.length;
+  const dotInSeg = ref.indexOf(CHILD_REF_SEPARATOR, segStart);
+  return dotInSeg === -1 ? ref : ref.slice(0, dotInSeg);
+}
+
+/** Depth-first walk of a node and its OWN descendants, node itself first. ADR-0039
+ *  sanctioned own-only case: `serializeSharedDocument` emits each selected node's
+ *  OWN layer only (`extends` preserved, not flattened — design §3.5), so the
+ *  closure check must walk exactly what will be emitted, never what `extends`
+ *  would additionally contribute (that is the base's own layer, checked
+ *  separately if the base is itself selected). */
+function walkOwn(node: MetaData): MetaData[] {
+  const out: MetaData[] = [node];
+  for (const child of node.ownChildren()) out.push(...walkOwn(child));
+  return out;
+}
+
+interface ClosurePair {
+  readonly referrer: string;
+  readonly target: string;
+}
+
+/** design §4.3 step 3. `standaloneRoot` already loaded successfully (step 1), so
+ *  every ref found here is guaranteed to RESOLVE to some node in it — the loader's
+ *  own validation passes reject a dangling `extends`/object-ref before this ever
+ *  runs. What is NOT guaranteed is that the resolved node is in `selectedKeys`. */
+function checkClosure(
+  standaloneRoot: MetaRoot,
+  selected: readonly MetaData[],
+  selectedKeys: ReadonlySet<string>,
+): ClosurePair[] {
+  const pairs: ClosurePair[] = [];
+  const seen = new Set<string>();
+  for (const top of selected) {
+    const referrerKey = top.resolutionKey();
+    for (const node of walkOwn(top)) {
+      const referrerPkg = effectivePackage(node) ?? "";
+      const candidates: string[] = [];
+      if (node.superRef !== undefined) candidates.push(node.superRef);
+      // ADR-0039 sanctioned own-only case (same rationale as walkOwn() above): an
+      // INHERITED ref-bearing attr belongs to the base node's own layer, not this
+      // one's, and is checked when the base itself is walked — reading it via the
+      // resolving `attr()` here would attribute the base's reference to this node.
+      for (const attrName of REF_BEARING_ATTR_NAMES) {
+        const value = node.ownAttr(attrName);
+        if (typeof value === "string") candidates.push(value);
+      }
+      for (const raw of candidates) {
+        const resolved = resolveObjectRef(standaloneRoot, refOwner(raw), referrerPkg).node;
+        if (resolved === undefined) continue; // already validated at load — defensive only
+        const targetKey = resolved.resolutionKey();
+        if (selectedKeys.has(targetKey)) continue;
+        const dedupeKey = `${referrerKey}${DEDUPE_KEY_SEPARATOR}${targetKey}`;
+        if (seen.has(dedupeKey)) continue;
+        seen.add(dedupeKey);
+        pairs.push({ referrer: referrerKey, target: targetKey });
+      }
+    }
+  }
+  return pairs.sort((a, b) =>
+    a.referrer === b.referrer ? a.target.localeCompare(b.target) : a.referrer.localeCompare(b.referrer),
+  );
+}
+
+/** design §2.2 — "version defaults to the host package's version". Walks up from
+ *  `startDir` for the nearest `package.json` carrying a string `version`. */
+function nearestPackageVersion(startDir: string): string | undefined {
+  let dir = startDir;
+  for (let i = 0; i < 64; i++) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: unknown };
+        if (typeof pkg.version === "string") return pkg.version;
+      } catch {
+        // An unparsable package.json is not a version source — keep walking up.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+  return undefined;
+}
+
+export function sharedModelFile(opts: SharedModelFileOpts): Generator {
+  const generator: Generator = {
+    name: "shared-model",
+    generate: oncePerRun(async (_entities, ctx: GenContext): Promise<EmittedFile[]> => {
+      const files = opts.files ?? ctx.sourceFiles ?? [];
+      if (files.length === 0) {
+        throw new Error(
+          `sharedModelFile("${opts.name}"): no source files to load — pass \`files\`, or run ` +
+            `through \`meta gen\`, which supplies the project's own files as \`ctx.sourceFiles\`.`,
+        );
+      }
+
+      // Step 1 — standalone load, the run's own composed registry (so the publisher's
+      // own consumer-supplied providers are honoured here exactly as they were for
+      // the project's main load), strict.
+      const loader = new MetaDataLoader({
+        ...(ctx.registry !== undefined ? { registry: ctx.registry } : {}),
+        strict: true,
+      });
+      const loaded = await loader.load(files.map((p) => new FileSource(p)));
+      if (loaded.errors.length > 0) {
+        throw loaded.errors[0];
+      }
+      const standaloneRoot = loaded.root;
+
+      // Step 2 — select top-level nodes. ADR-0039 sanctioned own-only case: `MetaRoot`
+      // has no super chain (it never `extends`), so its own children ARE its effective
+      // children — the same case `MetaRoot.objects()`/`findObject()` document.
+      const compiled = compileScope({ include: opts.include, exclude: opts.exclude ?? [] });
+      const selected = standaloneRoot
+        .ownChildren()
+        .filter((node) => node.type !== TYPE_REQUIREMENT && node.type !== TYPE_TEMPLATE)
+        .filter((node) => matchesScope(node.resolutionKey(), compiled));
+      if (selected.length === 0) {
+        throw new Error(
+          `sharedModelFile("${opts.name}"): selected no nodes (include/exclude, always ` +
+            `excluding requirement.* and template.*) — nothing to publish. Check \`include\`.`,
+        );
+      }
+
+      // Step 3 — closure.
+      const selectedKeys = new Set(selected.map((n) => n.resolutionKey()));
+      const closureFailures = checkClosure(standaloneRoot, selected, selectedKeys);
+      if (closureFailures.length > 0) {
+        const lines = closureFailures.map((p) => `  ${p.referrer} → ${p.target}`).join("\n");
+        throw new Error(
+          `sharedModelFile("${opts.name}"): the selection is not closed — these references ` +
+            `point outside it; include it or exclude the referrer:\n${lines}`,
+        );
+      }
+
+      // Step 4 — serialize (already sorted by resolution key; the callee also
+      // throws if a selected node has no package, per its own contract).
+      const artifactContent = serializeSharedDocument(selected);
+
+      // Step 5 — re-load standalone with CORE providers only (registry omitted ⇒
+      // MetaDataLoader's own default registry), strict. A consumer loads this
+      // artifact with ITS OWN providers, never the publisher's — so an export
+      // needing publisher-only vocabulary must fail HERE, not at the consumer.
+      const artifactPath = `${opts.name}${ARTIFACT_SUFFIX}`;
+      const coreLoader = new MetaDataLoader({ strict: true });
+      const coreLoaded = await coreLoader.load([
+        new InMemoryStringSource(artifactContent, { id: artifactPath }),
+      ]);
+      if (coreLoaded.errors.length > 0) {
+        const first = coreLoaded.errors[0]!;
+        throw new Error(
+          `sharedModelFile("${opts.name}"): the export needs a provider this toolchain does ` +
+            `not ship; Phase 1 exports must load with core vocabulary: ${first.message}`,
+        );
+      }
+
+      // Step 6 — emit the artifact + manifest.
+      const integrity = `${INTEGRITY_PREFIX}${createHash("sha256").update(artifactContent, "utf-8").digest("hex")}`;
+      const packages = [...new Set(selected.map((n) => packageOfResolutionKey(n.resolutionKey())))].sort();
+      const nodes = selected.map((n) => n.resolutionKey()).sort();
+      const version = opts.version ?? nearestPackageVersion(ctx.projectRoot ?? process.cwd());
+      if (version === undefined) {
+        throw new Error(
+          `sharedModelFile("${opts.name}"): no version available — pass \`version\` explicitly, ` +
+            `or run inside a project with a package.json version at or above the project root.`,
+        );
+      }
+      const manifest = {
+        schema_version: MANIFEST_SCHEMA_VERSION,
+        name: opts.name,
+        version,
+        metamodelVersion: METAMODEL_VERSION,
+        artifact: artifactPath,
+        integrity,
+        packages,
+        nodes,
+      };
+      return [
+        { path: artifactPath, content: artifactContent },
+        { path: MANIFEST_FILE, content: JSON.stringify(manifest, null, 2) + "\n" },
+      ];
+    }),
+  };
+  if (opts.target !== undefined) generator.target = opts.target;
+  return generator;
+}

package/src/generators/trace-helper-file.ts

@@ -28,9 +28,11 @@ import {
   TEMPLATE_ATTR_TEXT_REF,
 } from "@metaobjectsdev/metadata";
 import { responseFormatOf } from "../templates/find-inbound.js";
-import type { MetaObject } from "@metaobjectsdev/metadata";
+import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
+import { libraryManifests } from "@metaobjectsdev/metadata/library";
 import {
   type EmittedFile,
+  type GenContext,
   type Generator,
   type GeneratorFactory,
   perEntity,
@@ -39,8 +41,40 @@ import { generatePayloadInterfacesBatch } from "../payload-codegen.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { tphDiscriminatorPin } from "../templates/zod-validators.js";
 
-/** Short name of the shipped abstract base every trace entity extends. */
-const LLM_CALL_BASE = "LlmCallBase";
+/** This generator's stable name — the key a library manifest declares its anchor under. */
+const STABLE_NAME = "trace-helper";
+
+/**
+ * The FQNs this generator keys on, from the LIBRARY MANIFESTS rather than a constant
+ * here (FR-043 §6).
+ *
+ * What it replaces: `const LLM_CALL_BASE = "LlmCallBase"`, compared against `.name`
+ * anywhere in the super chain — so any adopter entity called `LlmCallBase`, in any
+ * package, triggered the generator. An anchor is a fully-qualified node the library
+ * declares, and it is resolved to a node and compared by identity below.
+ *
+ * `ctx.libraries` undefined means the caller never said which libraries are selected
+ * (a programmatic `runGen()`); every shipped manifest's anchor is then a candidate,
+ * which is still FQN-anchored. An EMPTY array is the opposite and is honoured: the
+ * caller looked, this project opted into none, and the generator matches nothing.
+ */
+function anchorFqns(ctx: GenContext): string[] {
+  const manifests = ctx.libraries ?? Object.values(libraryManifests());
+  const out: string[] = [];
+  for (const manifest of manifests) {
+    for (const g of manifest.generators ?? []) {
+      if (g.name === STABLE_NAME && g.anchor !== undefined) out.push(g.anchor);
+    }
+  }
+  return out;
+}
+
+/** Resolve each anchor FQN to the node it names, skipping any the model does not hold. */
+function anchorNodes(ctx: GenContext): MetaData[] {
+  const wanted = new Set(anchorFqns(ctx));
+  if (wanted.size === 0) return [];
+  return ctx.loadedRoot.children().filter((n) => wanted.has(n.resolutionKey()));
+}
 
 export interface TraceHelperOpts {
   /** Output directory prefix relative to the target's outDir. Default: "" (root). */
@@ -49,12 +83,17 @@ export interface TraceHelperOpts {
   target?: string;
 }
 
-/** Walk the super chain looking for a node named LLM_CALL_BASE. */
-function extendsBase(obj: MetaObject): boolean {
-  let cur = obj.superResolved;
-  while (cur !== undefined) {
-    if (cur.name === LLM_CALL_BASE) return true;
-    cur = cur.superResolved;
+/**
+ * Walk the super chain looking for one of the anchor NODES.
+ *
+ * Node identity, not `.name` and not even the FQN string: the anchors were resolved
+ * against this run's own loaded root, so an entity whose chain reaches one reaches
+ * exactly the node the library declared.
+ */
+function extendsAnchor(obj: MetaObject, anchors: readonly MetaData[]): boolean {
+  if (anchors.length === 0) return false;
+  for (let cur = obj.superResolved; cur !== undefined; cur = cur.superResolved) {
+    if (anchors.includes(cur)) return true;
   }
   return false;
 }
@@ -66,12 +105,16 @@ function pascal(s: string): string {
 
 export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts): Generator {
   const dirPrefix = opts?.outDir ? `${opts.outDir.replace(/\/$/, "")}/` : "";
+  // Resolved once per run, on first use: `perEntity` calls back per entity and the
+  // anchor set is a property of the run, not of the entity.
+  let anchors: MetaData[] | undefined;
   const generator: Generator = {
-    name: "trace-helper",
+    name: STABLE_NAME,
     generate: perEntity((entity, ctx) => {
-      // Only concrete entities derived from LlmCallBase.
+      anchors ??= anchorNodes(ctx);
+      // Only concrete entities derived from a library's declared anchor.
       if (entity.isAbstract) return [];
-      if (!extendsBase(entity)) return [];
+      if (!extendsAnchor(entity, anchors)) return [];
 
       // Find the nested template.prompt.
       // ADR-0039: resolving — a concrete trace entity may inherit its

package/src/index.ts

@@ -38,8 +38,22 @@ export {
   generatorRegistry,
   listGenerators,
   getGenerator,
+  GENERATOR_LAYERS,
 } from "./generator-registry.js";
-export type { GeneratorRegistryEntry, GeneratorTier } from "./generator-registry.js";
+export type {
+  GeneratorRegistryEntry,
+  GeneratorTier,
+  GeneratorFramework,
+  Layer,
+} from "./generator-registry.js";
+
+// The post-selection audits `meta gen` runs over a wired suite, and the impl-name →
+// stable-name resolver both of them go through. Public so the CLI can gate it.
+export {
+  warnUnsatisfiedRequires,
+  warnMixedApiFrameworks,
+  stableNameIndex,
+} from "./catalog-gates.js";
 
 export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider, GeneratorSpec, DocsConfig, ResolvedDocsConfig, DocsSurface, ApiSurface, VerifyConfig } from "./metaobjects-config.js";
 export { defineConfig, normalizeConfig, resolveGenerators, resolveDocsConfig } from "./metaobjects-config.js";
@@ -82,7 +96,7 @@ export { decideAndWrite, GitMissingError, WRITE_STATUSES } from "./overwrite-pol
 export { contentHash, readGeneratedHash, listGeneratedPaths } from "./overwrite-policy.js";
 
 export { CodegenError } from "./errors.js";
-export { GENERATED_HEADER, NAMES_FILE_SUFFIX, DEFAULT_OUT_DIR, RETIRED_CODEGEN_ATTRS, type RetiredCodegenAttr } from "./constants.js";
+export { GENERATED_HEADER, NAMES_FILE_SUFFIX, DEFAULT_OUT_DIR, RETIRED_CODEGEN_ATTRS, sidecarLine, type RetiredCodegenAttr } from "./constants.js";
 export { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 
 export { formatTs } from "./format.js";
@@ -210,7 +224,7 @@ export { renderEntityConstants, resourcePath } from "./templates/entity-constant
 export { renderQueriesFile } from "./templates/queries-file.js";
 // #348 — which CRUD verbs a generated routes file mounts. Public because an OWNED
 // routes generator (ADR-0034) composes the same render call and needs the same option.
-export { CRUD_VERBS, TPH_POLYMORPHIC_VERBS, resolveExpose, intersectExpose, exposeLine } from "./routes-expose.js";
+export { CRUD_VERBS, TPH_POLYMORPHIC_VERBS, resolveExpose, intersectExpose, exposeLine, authSeamJsDoc } from "./routes-expose.js";
 export type { CrudVerb, ExposeOption } from "./routes-expose.js";
 export { renderRoutesFile } from "./templates/routes-file.js";
 export { renderRoutesFileHono } from "./templates/routes-file-hono.js";

package/src/metaobjects-config.ts

@@ -198,21 +198,6 @@ export interface MetaobjectsGenConfig extends Omit<ResolvedGenConfig, "dbImport"
    * loader. Composed AFTER the default core+forge bundle.
    */
   providers?: readonly MetaDataTypeProvider[];
-  /**
-   * MetaObjects-shipped library packages this project loads alongside its own metadata —
-   * `["ai"]` makes `extends: "metaobjects::ai::LlmCallBase"` resolve.
-   *
-   * Sits beside `providers` because it answers the same shape of question: what does this
-   * project's model need in scope beyond the files it declares. Opt-in, because a library
-   * registers real top-level nodes and a project that never references one should not find
-   * them in its model, its generated output or its docs.
-   *
-   * Threaded to `loadMemory` by every CLI command that loads metadata. Before it existed,
-   * `librarySources` was reachable only from `MetaDataLoader.fromDirectory` — which the
-   * CLI does not use — so a generator that consumes a library was registered FOR the CLI
-   * while its input was unreachable THROUGH it (#333).
-   */
-  libraries?: readonly string[];
 }
 
 /** MetaobjectsGenConfig after applying defaults. All fields required.

package/src/projection/extract-view-spec.ts

@@ -42,16 +42,19 @@ import {
   SORT_ORDER_DESC,
   RELATIONSHIP_ATTR_OBJECT_REF,
   RELATIONSHIP_ATTR_CARDINALITY,
+  RELATIONSHIP_ATTR_SOURCE_REF_FIELD,
   CARDINALITY_ONE,
   IDENTITY_SUBTYPE_REFERENCE,
   IDENTITY_REFERENCE_ATTR_REFERENCES,
   FIELD_ATTR_COLUMN,
   OBJECT_PROJECTION_ATTR_FILTER,
-  findReferenceBetween,
+  findReferencesBetween,
+  resolveRelationshipReference,
   resolveObjectRef,
   type AggregateFunction,
+  type ReferenceLookup,
 } from "@metaobjectsdev/metadata";
-import { type MetaData, type MetaField, type MetaRoot, type MetaSource, MetaObject } from "@metaobjectsdev/metadata";
+import { type MetaData, type MetaField, type MetaReferenceIdentity, type MetaRoot, type MetaSource, MetaObject } from "@metaobjectsdev/metadata";
 import { intValueMapOf } from "../enum-meta.js";
 import {
   columnNameFromField,
@@ -330,6 +333,43 @@ function resolveHop(
   return undefined;
 }
 
+/**
+ * #368: which identity.reference does a resolved `@via` hop actually mean?
+ *
+ * `resolveHop` already found the EXACT node the hop segment named — a
+ * reference hop names the reference itself (nothing to disambiguate: two
+ * references onto the same target can coexist, but the hop picked one of them
+ * by name), and a relationship hop names a relationship whose backing
+ * reference `resolveRelationshipReference` resolves via the same SSOT ladder
+ * (unique candidate -> @sourceRefField -> unique name-pairing) that
+ * relation-resolver.ts already uses for the identical question elsewhere.
+ * Discarding `hop` and re-deriving purely from `holder`/`target` — as this
+ * file did before — throws away that specificity and reintroduces the exact
+ * ambiguity a named hop exists to resolve.
+ *
+ * Returns a single `ReferenceLookup` once resolved unambiguously, or the full
+ * candidate list when even the ladder cannot choose (a relationship hop whose
+ * name pairs with none of its candidates and no `@sourceRefField`) — the
+ * caller reports that list as a genuine ambiguity.
+ */
+function resolveHopReference(
+  holder: MetaObject,
+  hop: MetaData,
+  hopName: string,
+  target: MetaObject,
+): ReferenceLookup | ReferenceLookup[] {
+  if (hop.type === TYPE_IDENTITY && hop.subType === IDENTITY_SUBTYPE_REFERENCE) {
+    return { holder, other: target, referenceIdentity: hop as unknown as MetaReferenceIdentity };
+  }
+  // ADR-0039: resolving — @sourceRefField may be inherited via extends.
+  const sourceRefField = hop.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD) as string | undefined;
+  const matching = resolveRelationshipReference(holder, hopName, target.name, sourceRefField);
+  if (matching) {
+    return { holder, other: target, referenceIdentity: matching };
+  }
+  return findReferencesBetween(holder, target);
+}
+
 function viewName(projection: MetaObject, ctx: ExtractContext): string {
   // The read-only source carries the physical view name. FR-016: physicalName
   // implements the four-step rule (kind-matching alias → legacy @table →
@@ -750,14 +790,62 @@ function buildJoinTree(
         // a traversed relationship/reference may inherit its target via extends.
         const resolved = resolveHop(currentObj, relName);
         if (!resolved) break;
-        const { targetName, cardinality } = resolved;
+        const { hop, targetName, cardinality } = resolved;
         // @objectRef/@references may be package-qualified ("pkg::Entity"); resolve it
         // package-aware relative to the hop's source entity (the loader qualifies a
         // same-package ref even when authored bare), so the join binds the exact target.
         const target = resolveEntityRef(root, targetName, packageOf(currentObj));
         if (!target) break;
 
-        const ref = findReferenceBetween(currentObj as MetaObject, target);
+        // #368: two identity.reference declarations onto the same target are legal
+        // (e.g. Match.homeTeamRef/awayTeamRef -> Team) — resolveHopReference prefers
+        // the SPECIFIC reference/relationship the hop already named over re-deriving
+        // one from the target alone, so an explicit `@via: "Match.homeTeamRef"` (or a
+        // relationship disambiguated by @sourceRefField/name-pairing) resolves cleanly.
+        // Only a relationship hop that even the ladder cannot choose reaches the throw.
+        const resolvedRef = resolveHopReference(currentObj as MetaObject, hop, relName, target);
+        let ref: ReferenceLookup | undefined;
+        if (Array.isArray(resolvedRef)) {
+          if (resolvedRef.length > 1) {
+            // #368 round 2: @sourceRefField cannot fix this, but WHY differs by shape, and
+            // asserting the wrong reason for a given shape is itself a bug (fix round 1 of
+            // this cleanup caught exactly that). resolveRelationshipReference's ladder reads
+            // ONLY the hop's own entity's candidates (referenceCandidatesFor(currentObj, ...));
+            // it never even looks at `target`'s references. So:
+            //  - If `currentObj` itself holds one of the ambiguous candidates, resolution
+            //    already tried @sourceRefField/name-pairing against it and failed — and that
+            //    is only reachable at all when @cardinality isn't "one": a @cardinality "one"
+            //    relationship with 2+ own-side candidates is rejected at LOAD by rule (e)
+            //    (validateOneSideReferenceResolution) using this exact same ladder, so if we
+            //    got this far with an own-side candidate, @cardinality is provably not "one",
+            //    and @sourceRefField is provably illegal here (rule (d)).
+            //  - If NONE of the candidates are `currentObj`'s own, @sourceRefField could not
+            //    have mattered regardless of @cardinality — it only ever consults the hop's
+            //    OWN identity.reference children, and it has none targeting `target`. This is
+            //    rule (e)'s zero-candidate gap (validation-passes.ts:2226, `<= 1` skips 0 too):
+            //    a @cardinality "one" relationship can reach here with the FK entirely on the
+            //    far side, so @cardinality itself must NOT be asserted in this branch.
+            const holderName = (currentObj as MetaObject).name;
+            const holderOwnsACandidate = resolvedRef.some((r) => r.holder.name === holderName);
+            const whySourceRefFieldCannotHelp = holderOwnsACandidate
+              ? `it only disambiguates a @cardinality "${CARDINALITY_ONE}" relationship, and this ` +
+                `relationship's @cardinality is not "${CARDINALITY_ONE}" (declaring @sourceRefField on it ` +
+                `is itself a load error)`
+              : `it only consults "${holderName}"'s own identity.reference children, and "${holderName}" ` +
+                `declares none targeting "${target.name}" -- every candidate above belongs to the other side ` +
+                `of this join`;
+            throw new Error(
+              `projection join hop "${relName}" from "${holderName}" to "${target.name}" is ambiguous: ` +
+                `${resolvedRef.map((r) => r.referenceIdentity.name).join(", ")}. ` +
+                `@sourceRefField cannot resolve this: ${whySourceRefFieldCannotHelp}. There is no attribute ` +
+                `that disambiguates a hop like this -- remove the extra identity.reference between these two ` +
+                `entities, or restructure the model so only one remains.`,
+            );
+          }
+          ref = resolvedRef[0];
+        } else {
+          ref = resolvedRef;
+        }
         if (!ref) break;
 
         const fkField = ref.referenceIdentity.fields[0];
@@ -1090,7 +1178,40 @@ function buildSelectSpec(
       // The base↔child correlation FK — resolved exactly as buildJoinTree resolves a
       // single hop (the identity.reference is the FK-direction SSOT). Single-hop @via;
       // a multi-hop @via on origin.first is not lowered here (rare, and validated away).
-      const ref = findReferenceBetween(base, childEntity);
+      // #368: two identity.reference declarations onto the same target are legal, so
+      // this correlation cannot silently take the first — refuse rather than guess.
+      // Unlike buildJoinTree's @via hop (a named relationship/reference this file can
+      // resolve via resolveHopReference), origin.first's OWN @via (ORIGIN_FIRST_ATTR_VIA)
+      // is never read anywhere in this file — buildJoinTree explicitly skips it
+      // (ORIGIN_SUBTYPE_FIRST falls through to `continue` there) and this branch derives
+      // childEntity from @of alone, so there is no hop name here to prefer. Fixing that is
+      // a separate, larger change (wiring @via/single-hop-unique inference into this
+      // branch to match _validateViaPath/_inferViaSingleHop) — out of scope for #368's
+      // silent-first-match fix; the message below reflects the real, narrower remedy.
+      const refs = findReferencesBetween(base, childEntity);
+      // findReferencesBetween walks BOTH directions ([base,child] then [child,base]),
+      // so ">1 entry" is not by itself #368 ambiguity: a mutual 1:1 —
+      // Customer.primaryAddressRef -> Address PLUS Address.customerRef -> Customer —
+      // returns two entries pointing in OPPOSITE directions. That shape is legal
+      // (findReferenceBetween's own contract calls it "rare, but legal", and the
+      // referenceHolder: "source" | "target" branch below exists to serve it), and
+      // refusing it broke codegen for a model #368 says nothing about. The real
+      // ambiguity is two references declared by the SAME holder onto the other side —
+      // that is what the first-match below cannot choose between.
+      const ambiguousHolder = [base, childEntity].find(
+        (holder) => refs.filter((r) => r.holder === holder).length > 1,
+      );
+      if (ambiguousHolder !== undefined) {
+        const ambiguous = refs.filter((r) => r.holder === ambiguousHolder);
+        throw new Error(
+          `origin.first correlation from "${base.name}" to "${childEntity.name}" is ambiguous: ` +
+            `"${ambiguousHolder.name}" declares ${ambiguous.length} identity.reference nodes ` +
+            `onto the other side (${ambiguous.map((r) => r.referenceIdentity.name).join(", ")}). ` +
+            `origin.first's own @via is not consulted for this correlation — reduce to a ` +
+            `single identity.reference between these two entities.`,
+        );
+      }
+      const ref = refs[0];
       if (!ref) continue;
       const fkField = ref.referenceIdentity.fields[0];
       if (!fkField) continue;

package/src/reference/entity.ts

@@ -70,6 +70,7 @@ import {
   namesRef,
   namesConstArg,
   GENERATED_HEADER,
+  sidecarLine,
 } from "@metaobjectsdev/codegen-ts";
 
 export interface RenderEntityOpts {
@@ -143,8 +144,7 @@ function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntit
   const body = joinCode(sections, { on: "\n" }).toString();
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
-    `// Source metadata: ${entity.name} (${entity.fqn()})\n` +
-    `// Customize via ${entity.name}.extra.ts in this directory.\n`;
+    `// Source metadata: ${entity.name} (${entity.fqn()})\n${sidecarLine(`${entity.name}.extra.ts`)}`;
   return header + body;
 }
 
@@ -175,7 +175,16 @@ export const entityFile = function entityFile(opts?: EntityFileOpts): Generator
     generate: async (ctx: GenContext): Promise<EmittedFile[]> => {
       const files = await perEntityEmit(ctx);
       // FR-019: emit the shared-enums module once per run (null → no file).
-      const sharedEnums = renderSharedEnumsFile(ctx.loadedRoot);
+      // FR-023 §11.1 item 2: this is a REFERENCE TEMPLATE `meta init` copies into
+      // every scaffolded project's codegen/generators/ (ADR-0034) — the DEFAULT
+      // path, not an opt-in one. `select` (never `ctx.matches`, which never runs
+      // for a whole-root render like this one) excludes an enum used only by an
+      // imported, out-of-scope entity; without it every `meta init` project would
+      // silently emit shared enums the library path correctly excludes.
+      const sharedEnums = renderSharedEnumsFile(
+        ctx.loadedRoot,
+        ctx.select !== undefined ? { select: ctx.select } : undefined,
+      );
       if (sharedEnums !== null) {
         files.push({ path: `${SHARED_ENUMS_BASENAME}.ts`, content: await formatTs(sharedEnums) });
       }