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

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

@@ -6,7 +6,10 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { existsSync, readFileSync } from "node:fs";
 import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
-import { isMetaRoot, OBJECT_SUBTYPE_VALUE, FIELD_SUBTYPE_TIMESTAMP, FIELD_ATTR_FILTERABLE } from "@metaobjectsdev/metadata";
+import {
+  isMetaRoot, OBJECT_SUBTYPE_VALUE, FIELD_SUBTYPE_TIMESTAMP, FIELD_ATTR_FILTERABLE,
+  composeRegistry, coreProviders,
+} from "@metaobjectsdev/metadata";
 import { assignEmittedNames } from "./naming/collision-names.js";
 import { isAbstract } from "./instance-artifacts.js";
 import { dbEmittingObjects, missingDialectMessage } from "./db-emitting.js";
@@ -33,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. */
@@ -71,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>`).
@@ -106,6 +123,25 @@ export interface RunGenOpts {
    * they pass straight through.
    */
   scope?: (fqn: string) => boolean;
+  /**
+   * FR-023 §4.3 — the collection's own source files (`Collection.ownFiles`; never
+   * a dependency's snapshot artifact), threaded onto `GenContext.sourceFiles` for
+   * `sharedModelFile()`'s default `files` selection. The CLI's `gen` command
+   * always passes `genCollection.ownFiles`; a programmatic caller that never
+   * wires `sharedModelFile()` (or always passes that generator's own `files`
+   * 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 {
@@ -374,6 +410,23 @@ 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
+  // `sharedModelFile()`'s standalone re-load of a `files` subset sees the SAME
+  // vocabulary `opts.metadata` was originally loaded with.
+  const registry = composeRegistry([...coreProviders, ...(config.providers ?? [])]);
+
   // The compile break (`value` → `fetcher` on the provider) sends an adopter to the right
   // line; this names the value to put there, once, for the projects that had one.
   if (shouldNoteBaseUrlMove(config.apiPrefix, recordedEngine)) {
@@ -509,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
@@ -605,6 +672,12 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       entities: safeEntities,
       loadedRoot: root,
       matches: (e) => generator.filter?.(e) ?? true,
+      // FR-023 §11.1 item 2 — the SAME `scope` predicate that already narrowed
+      // `entities` above, re-exposed for a template that renders once over the
+      // WHOLE loaded root (the shared-enums module, so far the only one) rather
+      // than per matched entity, where `matches` never runs. Absent scope ⇒ no
+      // `select` at all, byte-identical to a project with no `scope` declared.
+      ...(scope !== undefined && { select: scope }),
       config: {
         outDir: selfTarget.outDir,
         extStyle: config.extStyle,
@@ -617,6 +690,9 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       },
       renderContext,
       ...(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/enums-file.ts

@@ -37,9 +37,20 @@ export const ${sharedEnumZodConstName(e.name)} = ${z}.enum([${members}]);
 /**
  * The full shared-enums module body, or null when the model has no materialized
  * shared enums (so the generator emits no file at all).
+ *
+ * `opts.select` (FR-023 §11.1 item 2) — the model-wide scope predicate over a
+ * CONSUMING entity's `resolutionKey()`: an enum extended only by entities
+ * `select` excludes is not materialized. This module renders once per run from
+ * the WHOLE loaded root (never per-generator-filtered — see #266), so it is the
+ * one shared-enums call site that must be threaded the scope predicate
+ * separately from `ctx.matches`. Omitted ⇒ every entity counts, byte-identical
+ * to a caller that never passes `opts` at all.
  */
-export function renderSharedEnumsFile(root: MetaRoot): string | null {
-  const enums = materializedSharedEnums(root);
+export function renderSharedEnumsFile(
+  root: MetaRoot,
+  opts?: { select?: (fqn: string) => boolean },
+): string | null {
+  const enums = materializedSharedEnums(root, opts?.select);
   if (enums.length === 0) return null;
 
   const body = joinCode(enums.map(renderOneSharedEnum), { on: "\n" }).toString();

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