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

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;
 }
 

package/src/reference/queries.ts

@@ -56,6 +56,7 @@ import {
   formatTs,
   entityOutputPath,
   GENERATED_HEADER,
+  sidecarLine,
 } from "@metaobjectsdev/codegen-ts";
 
 // --- composition (OWNED for the common case) ---
@@ -128,8 +129,7 @@ import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}I
   const body = joinCode(sections, { on: "\n" }).toString();
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
-    `// Source metadata: ${entityName} (${obj.fqn()})\n` +
-    `// Customize via ${entityName}.extra.ts in this directory (additional queries, custom logic).\n`;
+    `// Source metadata: ${entityName} (${obj.fqn()})\n${sidecarLine(`${entityName}.extra.ts`)}`;
   return header + body;
 }
 

package/src/relation-resolver.ts

@@ -10,9 +10,11 @@ import {
   RELATIONSHIP_ATTR_CARDINALITY,
   RELATIONSHIP_ATTR_OBJECT_REF,
   RELATIONSHIP_ATTR_THROUGH,
+  RELATIONSHIP_ATTR_SOURCE_REF_FIELD,
   CARDINALITY_ONE,
   CARDINALITY_MANY,
   deriveM2MFields,
+  resolveRelationshipReference,
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { variableNameFromEntity } from "./naming.js";
@@ -89,16 +91,20 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
       if (!targetEntityRaw) continue;
       const targetEntity = stripPackage(targetEntityRaw);
 
-      // Find an identity.reference on `obj` whose @references targets this relationship's target.
-      // Compare against package-stripped names since both relationship @objectRef and
-      // identity.reference @references may carry package-qualified entity names.
-      const refs = obj.referenceIdentities();
-      const matching = refs.find((r) => stripPackage(r.targetEntity ?? "") === targetEntity);
+      // #368: an entity may hold more than one identity.reference onto the same
+      // target, so the target alone does not identify the FK. Resolve through the
+      // shared ladder (unique candidate -> @sourceRefField -> name pairing); the
+      // loader has already refused anything it cannot resolve, so a miss here
+      // means an unloadable model reached codegen — skip rather than guess.
+      // ADR-0039: resolving — @sourceRefField may be inherited via extends.
+      const declaredRefField = child.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD) as string | undefined;
+      const matching = resolveRelationshipReference(
+        obj, child.name, targetEntity, declaredRefField,
+      );
       if (!matching) continue;
 
-      const fkFields = matching.fields;
-      if (fkFields.length === 0) continue;
-      const fkField = fkFields[0]!;
+      const fkField = matching.fields[0];
+      if (!fkField) continue;
 
       ensure(obj.name).push({
         name: child.name,

package/src/routes-expose.ts

@@ -84,3 +84,60 @@ export function exposeLine(verbs: readonly CrudVerb[] | undefined, indent: strin
   if (verbs === undefined) return "";
   return `\n${indent}expose: [${verbs.map((v) => JSON.stringify(v)).join(", ")}],`;
 }
+
+/**
+ * The auth-seam paragraph in a generated routes handler's JSDoc.
+ *
+ * Stock CRUD is unauthenticated, and until #367 the only thing a generated routes file
+ * said about that was a header line pointing at `<Entity>.extra.ts` "(e.g., auth)" — a
+ * sibling module nothing imports. An agent building a real API read it, went looking for
+ * the seam, found none, and deleted `routesFile()` from its config rather than mount five
+ * open endpoints over a password-hash table. The seam it needed already existed in both
+ * frameworks; nothing told it where.
+ *
+ * Both recipes are gated by `runtime-ts/test/route-auth-seam.test.ts` against the real
+ * mount helpers, because a recipe in generated output that does not work is the defect
+ * this replaces, not a smaller version of it. Hono's trailing wildcard is load-bearing
+ * and counter-intuitive: `"/users/*"` matches the collection path `/users` itself, so one
+ * `app.use` covers list, get and every write.
+ *
+ * The closing sentence is the part an adopter most needs and no knob can supply: a
+ * row-ownership rule ("only the owner may read this row") is not expressible in a mount,
+ * so the honest move is to hand-write those verbs and narrow the generated file with
+ * `expose` — not to mount them and hope.
+ */
+export function authSeamJsDoc(opts: {
+  framework: "fastify" | "hono";
+  /** The emitted handler's name, so the worked example is callable as written. */
+  handlerName: string;
+  /** Hono only: the source expression for this file's mount path, e.g. "`/api${User.$path}`". */
+  mountPathExpr?: string;
+  /** False for a read-only mount, which `expose` cannot narrow further. */
+  narrowable: boolean;
+}): string {
+  const recipe =
+    opts.framework === "fastify"
+      ? ` *     app.register(async (s) => {\n` +
+        ` *       s.addHook("preHandler", requireAuth);\n` +
+        ` *       await ${opts.handlerName}(s);\n` +
+        ` *     });`
+      : ` *     app.use(${opts.mountPathExpr}, requireAuth);   // matches the collection path too\n` +
+        ` *     ${opts.handlerName}(app, { db });`;
+  const guarded =
+    opts.framework === "fastify"
+      ? `Register this inside a scope that\n` +
+        ` * carries your hook and every verb below is guarded — routes outside that scope\n` +
+        ` * are not:`
+      : `Guard the mount path with\n` + ` * middleware before calling this:`;
+  // Name the generator that actually emitted this file — `routesFile` does not exist in
+  // a Hono project's config, and a recipe naming the wrong symbol is the same defect
+  // one size smaller.
+  const generatorName = opts.framework === "fastify" ? "routesFile" : "routesFileHono";
+  const narrowNote = opts.narrowable
+    ? `\n *\n * A row-ownership rule ("only the owner may read this row") is not expressible in a\n` +
+      ` * mount. Hand-write those verbs and narrow this file with\n` +
+      ` * ${generatorName}({ expose: ["list", "get"] }) rather than mounting them open.`
+    : `\n *\n * A row-ownership rule ("only the owner may read this row") is not expressible in a\n` +
+      ` * mount. Hand-write those reads rather than exposing this one open.`;
+  return ` *\n * Auth: these endpoints are unauthenticated. ${guarded}\n *\n${recipe}${narrowNote}`;
+}

package/src/runner.ts

@@ -36,6 +36,11 @@ import {
   type BaselineMode,
   type DecideAndWriteOpts,
 } from "./overwrite-policy.js";
+import {
+  warnUnsatisfiedRequires, warnMixedApiFrameworks, warnLibrarySelectionMismatch,
+} from "./catalog-gates.js";
+import { libraryManifests, splitLayerToken } from "@metaobjectsdev/metadata/library";
+import { generatorRegistry, type GeneratorRegistryEntry } from "./generator-registry.js";
 
 /** JS-identifier-shape only. Prevents filesystem traversal when metadata comes
  *  from untrusted sources (e.g. MCP). Mirrors the guard in legacy generate.ts. */
@@ -74,6 +79,15 @@ export interface RunGenOpts {
    * `--dry-run`, and watching it reappear.
    */
   dryRun?: boolean;
+  /**
+   * The catalog the `requires` / api-framework gates check against.
+   *
+   * Injected because the COMPOSITION lives in the CLI: `codegen-ts` cannot import its
+   * own dependents, so it cannot see the react and tanstack registry slices. Defaults
+   * to this package's own slice, which keeps a programmatic embedder that never
+   * composes correct — it simply has nothing to say about client-tier generators.
+   */
+  catalog?: Record<string, GeneratorRegistryEntry>;
   /**
    * Output scope — an object is generated only when this predicate returns true
    * for its fully-qualified name (`obj.resolutionKey()`, `<package>::<name>`).
@@ -118,6 +132,16 @@ export interface RunGenOpts {
    * option explicitly) can omit this with no behavior change elsewhere.
    */
   sourceFiles?: readonly string[];
+  /**
+   * FR-043 §6 — the project's shipped-library selection TOKENS (`Collection.libraries`,
+   * e.g. `["ai", "ai/db"]`), resolved to manifests and threaded onto
+   * `GenContext.libraries`, and read by the post-selection audit.
+   *
+   * Omitted means the caller never said; `[]` means it looked and this project opted
+   * into none. The two differ for a generator keying on a library anchor — see
+   * `GenContext.libraries`.
+   */
+  libraries?: readonly string[];
 }
 
 export interface RunGenResult {
@@ -386,6 +410,16 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // 2. Resolve targets + entity-module target.
   const config = normalizeConfig(opts.config);
 
+  // FR-043 §6 — the opted-in manifests, resolved once per run. A token names its
+  // library whether or not it carries a layer, and an unknown name contributes nothing
+  // (the config reader is what refuses a typo, by name — see `knownLibraryTokens`).
+  const selectedManifests =
+    opts.libraries === undefined
+      ? undefined
+      : [...new Set(opts.libraries.map((t) => splitLayerToken(t)[0]))]
+          .map((name) => libraryManifests()[name])
+          .filter((m): m is NonNullable<typeof m> => m !== undefined);
+
   // FR-023 §4.3 — the run's composed registry, threaded onto every GenContext.
   // Mirrors sdk's `loadMemory` exactly (`defaultLoadMemoryProviders` = core
   // providers, then the project's own `config.providers` appended) so
@@ -528,6 +562,20 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   warnMissingPromptGenerators(root, config.generators, (m) => warnings.push(m));
   warnUnmarkedUiGenerators(config.generators, (m) => warnings.push(m));
 
+  // Codegen is opt-in, so `meta gen` is the post-selection audit: the two ways a legal
+  // selection still surprises you. Warnings only — see catalog-gates.ts.
+  const catalog = opts.catalog ?? generatorRegistry;
+  warnUnsatisfiedRequires(config.generators, catalog, (m) => warnings.push(m));
+  warnMixedApiFrameworks(config.generators, catalog, (m) => warnings.push(m));
+  // FR-043 §6 — only when the caller actually told us what was selected. A programmatic
+  // caller that never threads `libraries` gets no library warnings at all, rather than
+  // "you opted into nothing", which would be a claim we cannot support.
+  if (opts.libraries !== undefined) {
+    warnLibrarySelectionMismatch(
+      config.generators, catalog, libraryManifests(), opts.libraries, (m) => warnings.push(m),
+    );
+  }
+
   // <Entity>Names is opt-in on TypeScript and an existing project gets no signal that
   // it exists. Fires ONCE, on the first gen after crossing the release that made it the
   // doctrine — see shouldNoteNamesArtifactAbsent for why it is keyed on the engine stamp
@@ -644,6 +692,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       ...(projectRoot !== undefined && { projectRoot }),
       registry,
       ...(opts.sourceFiles !== undefined && { sourceFiles: opts.sourceFiles }),
+      ...(selectedManifests !== undefined && { libraries: selectedManifests }),
       warn: (msg) => warnings.push(`[${generator.name}] ${msg}`),
     };
 

package/src/templates/entity-file.ts

@@ -17,7 +17,7 @@ import { renderEntityConstants } from "./entity-constants.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
 import { renderTphDiscriminatorUnion, isTphDiscriminatorBase } from "./tph-discriminator.js";
-import { GENERATED_HEADER } from "../constants.js";
+import { GENERATED_HEADER, sidecarLine } from "../constants.js";
 import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
 import { renderProjectionDecl } from "./projection-decl.js";
 import {
@@ -224,6 +224,6 @@ ${docsPrefix}export type ${entity.name} = ${z}.infer<typeof ${entity.name}Schema
   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`;
+    sidecarLine(`${entity.name}.extra.ts`);
   return header + body;
 }

package/src/templates/queries-file.ts

@@ -22,7 +22,7 @@ import {
   getPkFields,
 } from "./queries.js";
 import { pluralize, findByIdFnName, listFnName, createFnName, insertPreservingFnName, updateFnName } from "../naming.js";
-import { GENERATED_HEADER } from "../constants.js";
+import { GENERATED_HEADER, sidecarLine } from "../constants.js";
 import { isTphDiscriminatorBase, tphConcreteSubtypes } from "./tph-discriminator.js";
 import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
 import { hasAutoSetFields } from "./zod-validators.js";
@@ -147,7 +147,7 @@ import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}I
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
     `// Source metadata: ${entityName} (${obj.fqn()})\n` +
-    `// Customize via ${entityName}.extra.ts in this directory (additional queries, custom logic).\n`;
+    sidecarLine(`${entityName}.extra.ts`);
   return header + body;
 }
 
@@ -196,7 +196,7 @@ export async function ${listFnName(entityName)}(db: Db, opts?: { limit?: number;
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
     `// Source metadata: ${entityName} (${obj.fqn()}) — projection (read-only)\n` +
-    `// Customize via ${entityName}.extra.ts in this directory (additional queries, custom logic).\n`;
+    sidecarLine(`${entityName}.extra.ts`);
   return header + body;
 }
 
@@ -286,7 +286,7 @@ export async function ${updateFnName(entityName)}(db: Db, ${pkField}: ${pkType},
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
     `// Source metadata: ${entityName} (${obj.fqn()}) — write-through entity read-view (reads → view, writes → table)\n` +
-    `// Customize via ${entityName}.extra.ts in this directory (additional queries, custom logic).\n`;
+    sidecarLine(`${entityName}.extra.ts`);
   return header + body;
 }
 
@@ -396,6 +396,6 @@ ${dbTypeAlias}
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
     `// Source metadata: ${baseName} (${base.fqn()}) — TPH discriminator base\n` +
-    `// Customize via ${baseName}.extra.ts in this directory (additional queries, custom logic).\n`;
+    sidecarLine(`${baseName}.extra.ts`);
   return header + body;
 }

package/src/templates/routes-file-hono.ts

@@ -28,9 +28,9 @@ import { code, imp } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import { type RenderContext } from "../render-context.js";
 import { entityModuleSpecifier } from "../import-path.js";
-import { GENERATED_HEADER } from "../constants.js";
+import { GENERATED_HEADER, sidecarLine } from "../constants.js";
 import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
-import { type CrudVerb, exposeLine } from "../routes-expose.js";
+import { authSeamJsDoc, type CrudVerb, exposeLine } from "../routes-expose.js";
 import { effectivePackage } from "../docs-paths.js";
 
 export function renderRoutesFileHono(
@@ -58,12 +58,17 @@ export function renderRoutesFileHono(
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
     `// Source metadata: ${entityName} (${entity.fqn()})\n` +
-    `// Customize via ${entityName}.extra.ts in this directory (e.g., auth, additional handlers).\n`;
+    sidecarLine(`${entityName}.extra.ts`);
 
   // Path composition: apiPrefix is a literal string in the URL.
   const pathExpr = ctx.apiPrefix
     ? `\`${ctx.apiPrefix}\${${entityName}.$path}\``
     : `${entityName}.$path`;
+  // The same path with Hono's trailing wildcard, for the auth recipe in the JSDoc.
+  // `"/users/*"` matches `/users` itself, so one app.use covers list, get and writes.
+  const authPathExpr = ctx.apiPrefix
+    ? `\`${ctx.apiPrefix}\${${entityName}.$path}/*\``
+    : `\`\${${entityName}.$path}/*\``;
 
   // --- Projection path: read-only routes (GET list + GET :id) ---
   if (isProjection(entity)) {
@@ -89,6 +94,7 @@ import {
  * Exposes GET list + GET :id only. POST/PATCH/DELETE return 405.
  * Customize: register this as-is, or import individual route helpers from
  * @metaobjectsdev/runtime-ts/hono.
+${authSeamJsDoc({ framework: "hono", handlerName, mountPathExpr: authPathExpr, narrowable: false })}
  */
 // biome-ignore lint/suspicious/noExplicitAny: consumer-defined Hono bindings/variables
 export function ${handlerName}(app: ${HonoSym}<any, any, any>, deps: { db: unknown }): void {
@@ -143,6 +149,7 @@ import {
  * helpers (mountListRoute, mountGetRoute, ...) from
  * @metaobjectsdev/runtime-ts/hono and mix with your own handlers
  * (auth, side effects, etc.).
+${authSeamJsDoc({ framework: "hono", handlerName, mountPathExpr: authPathExpr, narrowable: true })}
  */
 // biome-ignore lint/suspicious/noExplicitAny: consumer-defined Hono bindings/variables
 export function ${handlerName}(app: ${HonoSym}<any, any, any>, deps: { db: unknown }): void {

package/src/templates/routes-file.ts

@@ -24,12 +24,12 @@ import {
 import { type RenderContext } from "../render-context.js";
 import { crossEntitySpecifier, entityModuleSpecifier, relativeModuleSpecifier } from "../import-path.js";
 import { namesRef, columnExpr } from "../names.js";
-import { GENERATED_HEADER } from "../constants.js";
+import { GENERATED_HEADER, sidecarLine } from "../constants.js";
 import { routesHandlerName } from "../naming.js";
 import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
 import type { RelationEntry } from "../relation-resolver.js";
 import { isTphDiscriminatorBase, tphPlan } from "./tph-discriminator.js";
-import { type CrudVerb, exposeLine, intersectExpose, TPH_POLYMORPHIC_VERBS } from "../routes-expose.js";
+import { authSeamJsDoc, type CrudVerb, exposeLine, intersectExpose, TPH_POLYMORPHIC_VERBS } from "../routes-expose.js";
 import { effectivePackage } from "../docs-paths.js";
 
 export function renderRoutesFile(
@@ -65,7 +65,7 @@ export function renderRoutesFile(
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
     `// Source metadata: ${entityName} (${entity.fqn()})\n` +
-    `// Customize via ${entityName}.extra.ts in this directory (e.g., auth, additional handlers).\n`;
+    sidecarLine(`${entityName}.extra.ts`);
 
   // --- Projection path: read-only routes (GET list + GET :id) ---
   if (isProjection(entity)) {
@@ -74,6 +74,13 @@ export function renderRoutesFile(
     const mountReadOnlyCrudRoutesSym = imp(
       "mountReadOnlyCrudRoutes@@metaobjectsdev/runtime-ts/drizzle-fastify",
     );
+    // A projection mount is read-only by construction, so `expose` cannot narrow it —
+    // the paragraph drops the narrowing advice and keeps the auth seam.
+    const readOnlyAuthJsDoc = authSeamJsDoc({
+      framework: "fastify",
+      handlerName,
+      narrowable: false,
+    });
 
     const literalImports = code`
 import { db } from ${JSON.stringify(dbImportSpec)};
@@ -93,6 +100,7 @@ import {
  * Exposes GET list + GET :id only. POST/PATCH/DELETE return 405.
  * Customize: register this as-is, or import individual route helpers from
  * @metaobjectsdev/runtime-ts/drizzle-fastify.
+${readOnlyAuthJsDoc}
  */
 export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   await fastify.register(async (instance) => {
@@ -115,6 +123,7 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
  * Exposes GET list + GET :id only. POST/PATCH/DELETE return 405.
  * Customize: register this as-is, or import individual route helpers from
  * @metaobjectsdev/runtime-ts/drizzle-fastify.
+${readOnlyAuthJsDoc}
  */
 export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   ${mountReadOnlyCrudRoutesSym}({
@@ -147,6 +156,7 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   const readViewLineFlat = writeThrough ? `\n    readView: ${camelName}View,` : "";
   const exposeLinePrefixed = exposeLine(expose, "      ");
   const exposeLineFlat = exposeLine(expose, "    ");
+  const crudAuthJsDoc = authSeamJsDoc({ framework: "fastify", handlerName, narrowable: true });
 
   const FastifyInstanceSym = imp("t:FastifyInstance@fastify");
   const mountCrudRoutesSym = imp("mountCrudRoutes@@metaobjectsdev/runtime-ts/drizzle-fastify");
@@ -185,6 +195,7 @@ import {
  * helpers (mountListRoute, mountGetRoute, ...) from
  * @metaobjectsdev/runtime-ts/drizzle-fastify and mix with your own handlers
  * (auth, side effects, etc.).
+${crudAuthJsDoc}
  */
 export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   await fastify.register(async (instance) => {
@@ -210,6 +221,7 @@ ${m2mMountsPrefixed}  }, { prefix: ${JSON.stringify(ctx.apiPrefix)} });
  * helpers (mountListRoute, mountGetRoute, ...) from
  * @metaobjectsdev/runtime-ts/drizzle-fastify and mix with your own handlers
  * (auth, side effects, etc.).
+${crudAuthJsDoc}
  */
 export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   ${mountCrudRoutesSym}({
@@ -444,6 +456,9 @@ function renderTphRoutesFile(
   });
 
   const mounts = joinCode([polymorphic, ...subtypeMounts], { on: "\n" });
+  // The base path is read-only by construction (TPH_POLYMORPHIC_VERBS), but the
+  // per-subtype mounts below it are full CRUD — so `expose` does narrow this file.
+  const tphAuthJsDoc = authSeamJsDoc({ framework: "fastify", handlerName, narrowable: true });
 
   const fn = ctx.apiPrefix
     ? code`
@@ -452,6 +467,7 @@ function renderTphRoutesFile(
  *
  * GET ${baseName}.$path (+ /:id) lists/gets the discriminated union; each
  * /${baseName}.$path/<subtype> path is a full per-subtype CRUD set.
+${tphAuthJsDoc}
  */
 export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   await fastify.register(async (instance) => {
@@ -465,6 +481,7 @@ ${mounts}
  *
  * GET ${baseName}.$path (+ /:id) lists/gets the discriminated union; each
  * /${baseName}.$path/<subtype> path is a full per-subtype CRUD set.
+${tphAuthJsDoc}
  */
 export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
 ${mounts}
@@ -474,6 +491,6 @@ ${mounts}
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
     `// Source metadata: ${baseName} (${base.fqn()}) — TPH discriminator base\n` +
-    `// Customize via ${baseName}.extra.ts in this directory (e.g., auth, additional handlers).\n`;
+    sidecarLine(`${baseName}.extra.ts`);
   return header + fn.toString();
 }

package/src/templates/value-object-file.ts

@@ -22,7 +22,7 @@ import {
 import { renderEntityConstants } from "./entity-constants.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
-import { GENERATED_HEADER } from "../constants.js";
+import { GENERATED_HEADER, sidecarLine } from "../constants.js";
 import { namesRef, namesConstArg } from "../names.js";
 
 export function renderValueObjectFile(obj: MetaObject, apiPrefix = "", ctx?: RenderContext): string {
@@ -84,6 +84,6 @@ export function renderValueObjectFile(obj: MetaObject, apiPrefix = "", ctx?: Ren
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
     `// Source metadata: ${obj.name} (${obj.fqn()})\n` +
-    `// Customize via ${emittedName}.extra.ts in this directory.\n`;
+    sidecarLine(`${emittedName}.extra.ts`);
   return header + body;
 }