@metaobjectsdev/codegen-ts 0.24.4 → 0.25.0

package/src/templates/output-parser.ts

@@ -15,11 +15,15 @@ import {
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_PROMPT,
   FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_OBJECT_REF,
   TEMPLATE_ATTR_RESPONSE_REF,
   RESPONSE_FORMAT_XML,
   resolveObjectRef,
 } from "@metaobjectsdev/metadata";
+import type { MetaField } from "@metaobjectsdev/metadata";
+import { enumValues, zodEnumExpr } from "../enum-meta.js";
+import { templateSymbolBase } from "../naming.js";
 import { responseShape } from "./find-inbound.js";
 import { isRequired } from "./fr010-field-mapping.js";
 import {
@@ -32,6 +36,29 @@ import {
 } from "./extract-delegate-emitter.js";
 import type { RenderContext } from "../render-context.js";
 
+/**
+ * Wire-shape validators per field subtype, for a JSON reply from a model.
+ *
+ * This map used to hold only the nine entries above `uuid`, so EVERY other subtype fell
+ * through the `?? "z.unknown()"` below — enum, uuid, date, time, timestamp, decimal,
+ * currency, uri and inet. `z.unknown()` accepts anything, including `null` on a `@required`
+ * field, so a declared response payload of eleven fields validated three of them. It
+ * mapped `class`, `short` and `byte` — the three subtypes this project CUT as
+ * non-functional registration-only stubs — while missing `currency` and `uuid`, which are
+ * exactly where a hallucinated value costs money or corrupts an identifier.
+ *
+ * The inversion is what makes it serious: validation was strongest on the payload we
+ * control and absent on the reply we do not, in the tier whose entire name is
+ * parser-on-receipt. The tolerant extractor in this same generated file reads the live
+ * metadata and DOES reject a non-member; so did Python's `FieldSpec.enum_field`. Only this
+ * strict path — the one called `parse<Name>`, documented `@throws on validation failure`,
+ * and the first one an adopter reaches for — threw the domain away.
+ *
+ * Temporal and numeric subtypes stay STRING-shaped on the wire deliberately: these
+ * validate raw JSON, where a timestamp is an ISO string and a decimal is a string to
+ * avoid float loss (the same reasoning as `zod-validators.ts`'s `z.coerce.date()` note).
+ * Coercion into native types is the caller's job, after the shape is known good.
+ */
 const SCALAR_ZOD: Record<string, string> = {
   string: "z.string()",
   class: "z.string()",
@@ -42,6 +69,17 @@ const SCALAR_ZOD: Record<string, string> = {
   double: "z.number()",
   float: "z.number()",
   boolean: "z.boolean()",
+  uuid: "z.string().uuid()",
+  date: "z.string()",
+  time: "z.string()",
+  timestamp: "z.string()",
+  // A decimal crosses the wire as a string precisely so it does not become a float;
+  // accepting a number here would re-admit the loss the subtype exists to prevent.
+  decimal: "z.string()",
+  // Integer minor units — the wire contract every port shares. Never a float.
+  currency: "z.number().int()",
+  uri: "z.string()",
+  inet: "z.string()",
 };
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
@@ -84,6 +122,12 @@ function fieldZod(field: MetaData, root: MetaData, seen: ReadonlySet<string>, de
       const inner = findObject(root, refName, field.parent?.package ?? field.parent?.fileDefaultPackage ?? "");
       base = inner ? renderObjectSchema(inner, root, new Set(seen).add(refName), depth + 1) : "z.unknown()";
     }
+  } else if (field.subType === FIELD_SUBTYPE_ENUM) {
+    // The members are declared, resolving (so an `extends`-inherited @values is seen),
+    // and already reachable — the send-side type in prompts.ts is built from them. The
+    // one closed domain in an untrusted reply is the one worth checking hardest.
+    const values = enumValues(field as MetaField);
+    base = values !== undefined && values.length > 0 ? zodEnumExpr(values) : "z.unknown()";
   } else {
     base = SCALAR_ZOD[field.subType] ?? "z.unknown()";
   }
@@ -137,11 +181,14 @@ export function renderOutputParser(root: MetaData, templateName: string, ctx?: R
   const { vo, ref: payloadRef } = shape;
 
   const schema = renderObjectSchema(vo, root, new Set([payloadRef]), 0);
-  const schemaName = `${templateName}Schema`;
-  const dataName = `${templateName}Data`;
-  const errorName = `${templateName}ValidationError`;
-  const parseName = `parse${templateName}`;
-  const safeParseName = `safeParse${templateName}`;
+  // One base for every symbol in this file, shared with promptRender()'s handle — the
+  // three template emitters used to spell the same node three ways (see naming.ts).
+  const base = templateSymbolBase(templateName);
+  const schemaName = `${base}Schema`;
+  const dataName = `${base}Data`;
+  const errorName = `${base}ValidationError`;
+  const parseName = `parse${base}`;
+  const safeParseName = `safeParse${base}`;
 
   // FR-010: emit the tolerant extract() API alongside the strict Zod parser.
   //
@@ -209,8 +256,8 @@ export function ${safeParseName}(
   // Unconditional since ADR-0052: a declared @responseRef IS the request for the
   // tolerant path, and @responseFormat is a closed json|xml set, so there is no
   // longer a third case to gate on.
-  const extractedName = `${templateName}Extracted`;
-  const extractLenientWithName = `extractLenient${templateName}WithLoader`;
+  const extractedName = `${templateSymbolBase(templateName)}Extracted`;
+  const extractLenientWithName = `extractLenient${templateSymbolBase(templateName)}WithLoader`;
   const payloadFqnConst = `${templateName.toUpperCase()}_PAYLOAD_NAME`;
   const formatEnum = format === RESPONSE_FORMAT_XML ? "Format.XML" : "Format.JSON";
 

package/src/templates/projection-decl.ts

@@ -10,17 +10,17 @@
 import { code, imp, joinCode, type Code } from "ts-poet";
 import {
   MetaField, MetaObject, type MetaRoot, isMetaObject,
-  FIELD_ATTR_OBJECT_REF, stripPackage,
+  FIELD_ATTR_OBJECT_REF, stripPackage, resolveColumnName, resolveTableSchema,
 } from "@metaobjectsdev/metadata";
 import { projectionViewName } from "../projection/extract-view-spec.js";
-import { columnNameFromField, toSnakeCase, pluralize } from "../naming.js";
 import { GENERATED_HEADER } from "../constants.js";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
 import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
 import { valueObjectModuleSpecifier } from "../import-path.js";
+import { physicalNameExpr, sourceSchemaExpr, type ObjectNames } from "../names.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
-import { inferViewKind, currencyMetaFor, labelFor } from "./field-meta.js";
+import { buildUiFieldDescriptor, resourcePath } from "./entity-ui-descriptor.js";
 import { renderExistingViewDecl, renderViewReadZodObject } from "./view-decl.js";
 import { primaryIdentityFieldNames } from "./zod-validators.js";
 
@@ -31,6 +31,11 @@ import { primaryIdentityFieldNames } from "./zod-validators.js";
 export interface ProjectionDeclOpts {
   readonly columnNamingStrategy: ColumnNamingStrategy;
   readonly dialect: "postgres" | "sqlite";
+  /**
+   * @deprecated Accepted and IGNORED — a projection's descriptor no longer carries the
+   * API base URL, same as an entity's. Kept on the options object because removing a
+   * field makes every caller still passing it fail TypeScript's excess-property check.
+   */
   readonly apiPrefix?: string;
   /** Drives the timestamp column TS type (Date vs string) in the view declaration. */
   readonly timestampMode?: "date" | "string";
@@ -53,24 +58,23 @@ export interface ProjectionDeclOpts {
    * e.g. a shared types package consumed by a web client that has no Drizzle.
    */
   readonly includeViewDecl?: boolean;
+  /**
+   * §A6 — the resolved names artifact for this projection plus the ts-poet symbol
+   * reference (`imp()`'d import of `<Projection>Names`), when the names generator is
+   * in the run. Built by the caller via `resolveObjectNames` + `imp(...)` — the same
+   * pair `drizzle-schema.ts` builds — so this file never resolves names itself; it
+   * only decides, per field, whether to reference the constant or fall back to the
+   * literal (a lookup MISS, never a divergence — `primaryRdbSource` already refused any
+   * object whose `@role: primary` sources disagree on a physical name). Threaded into `renderExistingViewDecl`
+   * too, since a projection's primary source IS the view its `sources.primary.view` names.
+   */
+  readonly names?: { readonly resolved: ObjectNames; readonly symbol: Code } | undefined;
 }
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Convert a PascalCase projection name to a kebab-pluralized URL path.
- *   "ProgramSummary"  → "/program-summaries"
- *   "CustomerSummary" → "/customer-summaries"
- *   "Box"             → "/boxes"
- *   "Wish"            → "/wishes"
- */
-function pathFromProjectionName(name: string): string {
-  const kebab = toSnakeCase(pluralize(name)).replace(/_/g, "-");
-  return `/${kebab}`;
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -92,7 +96,7 @@ export function renderProjectionDecl(
   root: MetaRoot,
   opts: ProjectionDeclOpts,
 ): string {
-  const { dialect, columnNamingStrategy, apiPrefix = "", timestampMode = "string", allowlists = true, ctx, includeViewDecl = true } = opts;
+  const { dialect, columnNamingStrategy, timestampMode = "string", allowlists = true, ctx, includeViewDecl = true, names } = opts;
 
   // ADR-0044/#228 — resolve a projection field's `@objectRef` to the value object's
   // EMITTED name + module TOGETHER (lock-step): bare when unique in the run,
@@ -137,29 +141,67 @@ export function renderProjectionDecl(
   // inherited fields are not duplicated.
   for (const f of projection.ownFields()) allFields.push(f);
 
-  const constFieldLines: string[] = allFields.map((f) => {
-    const dbCol = columnNameFromField(f.name, columnNamingStrategy);
-    const view = inferViewKind(f);
-    const label = labelFor(f);
-    const baseEntry = `name: ${JSON.stringify(f.name)}, label: ${JSON.stringify(label)}, view: ${JSON.stringify(view)}, dbCol: ${JSON.stringify(dbCol)}`;
-    const currencyMeta = currencyMetaFor(f);
-    if (currencyMeta !== null) {
-      return `  ${f.name}: { ${baseEntry}, currency: ${JSON.stringify(currencyMeta.currency)}, locale: ${JSON.stringify(currencyMeta.locale)} },`;
+  const constFieldLines: Code[] = allFields.map((f) => {
+    // §A4: resolveColumnName, NOT columnNameFromField — the latter takes a string and so
+    // cannot read @column, silently substituting the naming strategy's answer for a
+    // declared or inherited physical name. ADR-0039: resolving accessor, so a projection
+    // field inheriting @column through `extends` resolves it.
+    const dbCol = resolveColumnName(f, columnNamingStrategy);
+    // A6 — reference the constant whenever the artifact is in the run AND carries this
+    // field. A lookup MISS (a TPH subtype field the base's names artifact never saw) is
+    // normal, not a divergence — fall back to the literal, same as every other §A6 site.
+    const namesEntry = names?.resolved.fields[f.name];
+    const dbColExpr: Code =
+      names !== undefined && namesEntry !== undefined
+        ? code`${names.symbol}.fields.${f.name}.column`
+        : code`${JSON.stringify(dbCol)}`;
+    // #356 — a projection's descriptor is the same shape the entity descriptor emits,
+    // and now literally the SAME derivation: `buildUiFieldDescriptor` is what
+    // `renderEntityConstants` reads, so the view kind, the label and the currency meta
+    // cannot come out differently here. A projection is read-only, so the members that
+    // describe a FORM (htmlType / placeholder / helpText / rules) are not emitted — a
+    // subset of one descriptor rather than a second answer — and `dbCol`, which only a
+    // view-backed const carries, is added.
+    const ui = buildUiFieldDescriptor(f);
+    const baseEntry = code`name: ${JSON.stringify(ui.name)}, label: ${JSON.stringify(ui.label)}, view: ${JSON.stringify(ui.view)}, dbCol: ${dbColExpr}`;
+    if (ui.currency !== undefined) {
+      return code`  ${f.name}: { ${baseEntry}, currency: ${JSON.stringify(ui.currency.currency)}, locale: ${JSON.stringify(ui.currency.locale)} },`;
     }
-    return `  ${f.name}: { ${baseEntry} },`;
+    return code`  ${f.name}: { ${baseEntry} },`;
   });
 
   const projName = projection.name;
   const camelName = projName.charAt(0).toLowerCase() + projName.slice(1);
-  const path = pathFromProjectionName(projName);
+  // ONE derivation of `$path`, shared with the entity const and with every page that
+  // documents an endpoint — `resourcePath` owns the projection/entity split. The
+  // kebab-pluralized spelling this module used to compute for itself is what it still
+  // returns for a projection; the second copy is what let `agent/ui.md` and
+  // `api/AGENT-API.md` both print the snake-cased entity spelling for a view.
+  const path = resourcePath(projection);
+
+  // A6 Task 1 fix round — the descriptor's $view is a SECOND, independent embedding
+  // of the view's physical name (the Drizzle .existing() decl in view-decl.ts is the
+  // first, already converted). Same "is the artifact in this run" condition, no
+  // equality guard: `names.resolved.name` is always the PRIMARY source's physical
+  // name, while `viewName` is derived by `viewName()` in extract-view-spec.ts, which
+  // for a projection declaring a role:replica read-only source BEFORE its role:primary
+  // one used to return a different, declaration-order-dependent string. That is why
+  // both spellings here must come from the constant rather than from two resolvers.
+  const viewLine: Code = code`$view:      ${physicalNameExpr(names, viewName, projection)}`;
+  // @schema for the view binding below. postgres-only downstream (view-decl gates on dialect).
+  const projectionSchema = resolveTableSchema(projection);
 
   // The projection's primary-identity fields type non-null in the view decl +
   // read schema even without @required (a PK is never NULL; see ViewDeclOpts).
   const pkFieldNames: ReadonlySet<string> = new Set(primaryIdentityFieldNames(projection));
   const sections: Code[] = [
     ...(includeViewDecl
-      ? [renderExistingViewDecl(allFields, viewName, `${camelName}View`, {
-          dialect, columnNamingStrategy, timestampMode, voRef, pkFieldNames,
+      ? [renderExistingViewDecl(allFields, physicalNameExpr(names, viewName, projection), `${camelName}View`, {
+          dialect, columnNamingStrategy, timestampMode, voRef, pkFieldNames, names,
+          // A projection's own artifact names its own view, so the constant IS this view's
+          // schema — unlike the write-through replica case in entity-file.ts.
+          schema: projectionSchema === undefined ? undefined
+            : sourceSchemaExpr(names) ?? projectionSchema,
         })]
       : []),
     code`
@@ -173,10 +215,9 @@ export type ${projName} = ${z}.infer<typeof ${projName}Schema>;
     code`
 export const ${projName} = {
   $entity:    ${JSON.stringify(projName)},
-  $view:      ${JSON.stringify(viewName)},
+  ${viewLine},
   $path:      ${JSON.stringify(path)},
-  $apiPrefix: ${JSON.stringify(apiPrefix)},
-${constFieldLines.join("\n")}
+${joinCode(constFieldLines, { on: "\n" })}
 } as const;
 `,
     ...(allowlists

package/src/templates/queries-file.ts

@@ -35,16 +35,31 @@ import { hasAutoSetFields } from "./zod-validators.js";
  *     postgres.js, Neon, Vercel, pglite) — accepts whichever driver the consumer chose.
  *   - SQLite: `BaseSQLiteDatabase<"sync" | "async", …>` accepts BOTH sync (better-sqlite3)
  *     and async (libsql/Turso/D1) drivers; the generated queries `await` results, valid on either.
+ *
+ * EVERY type argument here must stay as OPEN as Drizzle's own constraint allows — a `Db`
+ * this alias cannot name is a helper the consumer cannot call, and generated code that
+ * does not compile is indistinguishable from generated code nobody imports. Two axes have
+ * now been re-pinned and re-widened in turn, so neither may be narrowed again:
+ *   - DRIVER: pinning `NodePgDatabase` / `<"async">` rejected postgres.js and
+ *     better-sqlite3. Fixed by dropping to the base classes above.
+ *   - SCHEMA (`TFullSchema`): the idiomatic setup is `drizzle(client, { schema })`, which
+ *     yields `PgDatabase<…, typeof schema>` / `BaseSQLiteDatabase<…, typeof schema>`.
+ *     Leaving this parameter at Drizzle's `Record<string, never>` DEFAULT — spelled out on
+ *     postgres, silently inherited on sqlite by supplying only two arguments — rejected
+ *     every such db with TS2345 ("Type '\"work_item\"' is not assignable to type 'never'").
+ *     `Record<string, unknown>` is verbatim Drizzle's own declared bound
+ *     (`TFullSchema extends Record<string, unknown>`), so it admits both a schema-carrying
+ *     and a schema-less db without reaching for `any`.
  */
 function dbTypeBlock(dialect: "postgres" | "sqlite"): { import: string; alias: string } {
   return dialect === "postgres"
     ? {
         import: `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`,
-        alias: `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`,
+        alias: `type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;`,
       }
     : {
         import: `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`,
-        alias: `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`,
+        alias: `type Db = BaseSQLiteDatabase<"sync" | "async", unknown, Record<string, unknown>>;`,
       };
 }
 

package/src/templates/render-helper.ts

@@ -52,6 +52,7 @@ import {
   type PayloadField,
   type VerifyError,
 } from "@metaobjectsdev/render";
+import { templateSymbolBase } from "../naming.js";
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 // ADR-0042: package-local — resolveObjectRef binds a bare @objectRef in `referrerPkg` first (else root-level), an FQN exactly.
@@ -175,7 +176,8 @@ export function renderRenderHelper(
 
   const fields = derivePayloadFieldTree(root, payloadRef, tmplPkg);
   const ft = fieldTreeLiteral(fields);
-  const fnName = `render${templateName}`;
+  // Same base as promptRender()'s handle and outputParser()'s symbols (naming.ts).
+  const fnName = `render${templateSymbolBase(templateName)}`;
   // @payloadRef may arrive package-qualified (FQN) once resolved — a bare
   // `::`-free name is required everywhere it's emitted as a TS identifier /
   // import specifier below (mirrors the same stripPackage() call every other

package/src/templates/requirement-test.ts

@@ -10,6 +10,11 @@
 // claims the capability works, so an empty green test asserts the opposite of the
 // claim — the original defect recreated in a new place.
 
+import {
+  REQUIREMENT_STATUSES,
+  REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES,
+  REQUIREMENT_STATUS_RETIRED,
+} from "@metaobjectsdev/metadata";
 import { GENERATED_HEADER } from "../constants.js";
 import type { RequirementView, ResolvedClaim } from "../requirement-walk.js";
 
@@ -27,21 +32,22 @@ export interface RequirementTestArgs {
  * Statuses whose stub is SKIPPED rather than failing.
  *
  * The rule is "does this entry claim the capability works right now?" — only `live`
- * and `partial` do. `planned` is intended-not-built; `abandoned` and `superseded`
- * describe a capability deliberately retired, whose `@implementedBy` is SUPPOSED to
- * dangle. Emitting a failing stub for any of the three reddens an application's suite
- * forever for something nobody intends to build, which is the noise an app silences
- * wholesale — taking the `live` stubs with it.
+ * and `partial` do. `planned` is intended-not-built; `retired` is built-then-
+ * deliberately-removed. Emitting a failing stub for either reddens an application's
+ * suite forever for something nobody intends to build, which is the noise an app
+ * silences wholesale — taking the `live` stubs with it.
  *
- * (FR-038 §4 proposes retiring `abandoned`/`superseded` from the vocabulary entirely.
- * Until that breaking cut lands they are legal `@status` values, so the renderer has
- * to handle them.)
+ * This set is derived from the LOADER's enum, not restated from it. It used to be a
+ * literal naming `abandoned` and `superseded`, and when 0.24.0 retired both and
+ * 0.24.2 put `retired` in their place, the set was left behind: it skipped two
+ * statuses the loader had begun REFUSING and failed on the one that replaced them,
+ * so every retired entry emitted a permanently red stub — the exact noise this set
+ * exists to prevent. Deriving it means the next status move cannot leave it behind:
+ * a status that is neither live nor partial is skipped by construction.
  */
-const SKIPPED_STATUSES: ReadonlySet<string> = new Set([
-  "planned",
-  "abandoned",
-  "superseded",
-]);
+const SKIPPED_STATUSES: ReadonlySet<string> = new Set(
+  REQUIREMENT_STATUSES.filter((s) => !REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES.includes(s)),
+);
 
 /**
  * Escape an author-supplied value for a double-quoted TS string literal.
@@ -112,17 +118,42 @@ export function renderRequirementTest(a: RequirementTestArgs): string {
   // A `live` or `partial` stub asserts FAILURE until someone writes the real
   // assertion over it. `expect.unreachable` names the requirement in the failure
   // message, so a red run says which claim is unproven rather than just "failed".
-  const body = skipped
-    ? `  // Intended, not built. Write the assertion when this becomes live.`
-    : `  expect.unreachable(\n` +
+  // The two skipped statuses mean OPPOSITE things, so they must not share a body.
+  // `planned` is intended-not-built and the instruction is to write the assertion when
+  // it becomes live. `retired` is built-then-deliberately-removed, and telling a reader
+  // to write it "when this becomes live" instructs them to revive the capability —
+  // inverting the one guardrail 0.24.2 restored `retired` for. The repo's own harness
+  // generator already branches here; the shipped renderer now does too.
+  let body: string;
+  if (!skipped) {
+    body =
+      `  expect.unreachable(\n` +
       `    "unimplemented requirement stub: ${testName} — " +\n` +
       `    "replace this with an assertion that fails when: ${forStringLiteral(a.counterexample)}",\n` +
       `  );`;
+  } else if (a.view.status === REQUIREMENT_STATUS_RETIRED) {
+    body =
+      `  // Retired: this capability was deliberately removed and must not be rebuilt.\n` +
+      `  // If you assert anything here, assert that it STAYS removed.`;
+  } else {
+    body = `  // Intended, not built. Write the assertion when this becomes live.`;
+  }
 
+  // The header states the CONDITION on the survival promise, not just the promise.
+  // It used to say the body "survives regeneration" flat, which is true of the body and
+  // false of the run: a stub is worthless until hand-edited, and the moment it is edited
+  // and pushed, every clone that did not generate it refuses the file and exits 1 —
+  // demonstrable by deleting the gitignored `.gen-state` bodies and re-running. Stating
+  // the machine-local half here is what keeps a reader from reading a red CI run as a
+  // broken promise. The remedy itself lives on the refusal, not in every stub.
   return (
     `// ${GENERATED_HEADER}.\n` +
-    `// The test IDENTITY is generated from the requirement; the BODY below is yours\n` +
-    `// and survives regeneration. Do not rename the test — the name is the link.\n` +
+    `// The test IDENTITY is generated from the requirement; the BODY below is yours.\n` +
+    `// Do not rename the test — the name is the link.\n` +
+    `// Your body is never overwritten: MERGED where .metaobjects/.gen-state/ holds this\n` +
+    `// file's snapshot body, REFUSED (run exits 1, body kept) where it does not. Those\n` +
+    `// bodies are gitignored, so a fresh clone or CI is always the second case — see\n` +
+    `// docs/features/own-your-codegen.md for the recovery.\n` +
     `import { test, expect } from "bun:test";\n` +
     `\n` +
     `/**\n` +

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

@@ -30,8 +30,19 @@ import { type RenderContext } from "../render-context.js";
 import { entityModuleSpecifier } from "../import-path.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
+import { type CrudVerb, exposeLine } from "../routes-expose.js";
 
-export function renderRoutesFileHono(entity: MetaObject, ctx: RenderContext): string {
+export function renderRoutesFileHono(
+  entity: MetaObject,
+  ctx: RenderContext,
+  // #348 — resolved by the generator from its `expose` option. undefined = all five verbs,
+  // emitting no `expose` key at all, so output stays byte-identical without it.
+  //
+  // Applies to the CRUD mount only. The projection branch above uses
+  // mountReadOnlyCrudRoutes, a different helper that is read-only by construction and
+  // takes no `expose` — there is no writable surface there to narrow.
+  expose?: readonly CrudVerb[],
+): string {
   const entityName = entity.name;
   const handlerName = `register${entityName}Routes`;
 
@@ -107,6 +118,7 @@ export function ${handlerName}(app: ${HonoSym}<any, any, any>, deps: { db: unkno
   const writeThrough = isWriteThrough(entity);
   const camelName = entityName.charAt(0).toLowerCase() + entityName.slice(1);
   const readViewLine = writeThrough ? `\n    readView: ${camelName}View,` : "";
+  const exposeLineHono = exposeLine(expose, "    ");
 
   const HonoSym = imp("t:Hono@hono");
   const mountCrudRoutesSym = imp("mountCrudRoutes@@metaobjectsdev/runtime-ts/hono");
@@ -142,7 +154,7 @@ export function ${handlerName}(app: ${HonoSym}<any, any, any>, deps: { db: unkno
     updateSchema: ${entityName}UpdateSchema,
     filterAllowlist: ${entityName}FilterAllowlist,
     sortAllowlist: ${entityName}SortAllowlist,
-    dialect: ${JSON.stringify(ctx.dialect)},
+    dialect: ${JSON.stringify(ctx.dialect)},${exposeLineHono}
   });
 }
 `;

package/src/templates/routes-file.ts

@@ -23,19 +23,28 @@ import {
 } from "@metaobjectsdev/metadata";
 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 { 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";
 
-export function renderRoutesFile(entity: MetaObject, ctx: RenderContext): string {
+export function renderRoutesFile(
+  entity: MetaObject,
+  ctx: RenderContext,
+  // #348 — resolved by the generator from its `expose` option. undefined = all five verbs,
+  // which emits no `expose` key at all and so keeps output byte-identical for projects
+  // that do not use it.
+  expose?: readonly CrudVerb[],
+): string {
   // FR-017 Tier 2 — a TPH discriminator base mounts polymorphic list/get at the
   // base path plus a full per-subtype CRUD route set scoped to each
   // discriminator value. (Subtype entities are filtered out of the routes
   // generator entirely — their routes live here.)
   if (isTphDiscriminatorBase(entity, ctx.loadedRoot)) {
-    return renderTphRoutesFile(entity, ctx);
+    return renderTphRoutesFile(entity, ctx, expose);
   }
 
   const entityName = entity.name;
@@ -134,6 +143,8 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   const viewImportLine = writeThrough ? `\n  ${camelName}View,` : "";
   const readViewLinePrefixed = writeThrough ? `\n      readView: ${camelName}View,` : "";
   const readViewLineFlat = writeThrough ? `\n    readView: ${camelName}View,` : "";
+  const exposeLinePrefixed = exposeLine(expose, "      ");
+  const exposeLineFlat = exposeLine(expose, "    ");
 
   const FastifyInstanceSym = imp("t:FastifyInstance@fastify");
   const mountCrudRoutesSym = imp("mountCrudRoutes@@metaobjectsdev/runtime-ts/drizzle-fastify");
@@ -184,7 +195,7 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
       updateSchema: ${entityName}UpdateSchema,
       filterAllowlist: ${entityName}FilterAllowlist,
       sortAllowlist: ${entityName}SortAllowlist,
-      dialect: ${JSON.stringify(ctx.dialect)},
+      dialect: ${JSON.stringify(ctx.dialect)},${exposeLinePrefixed}
     });
 ${m2mMountsPrefixed}  }, { prefix: ${JSON.stringify(ctx.apiPrefix)} });
 }
@@ -208,7 +219,7 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
     updateSchema: ${entityName}UpdateSchema,
     filterAllowlist: ${entityName}FilterAllowlist,
     sortAllowlist: ${entityName}SortAllowlist,
-    dialect: ${JSON.stringify(ctx.dialect)},
+    dialect: ${JSON.stringify(ctx.dialect)},${exposeLineFlat}
   });
 ${m2mMountsFlat}}
 `;
@@ -270,15 +281,17 @@ function renderM2mMount(
   const mountM2mRouteSym = imp("mountM2mRoute@@metaobjectsdev/runtime-ts/drizzle-fastify");
   const junction = ctx.loadedRoot.findObject(entry.junctionEntity);
   const target = ctx.loadedRoot.findObject(entry.targetEntity);
-  const sourceColumn = junction
-    ? resolveJunctionColumn(junction, entry.sourceJoinField!, ctx)
-    : entry.sourceJoinField!;
-  const targetColumn = junction
-    ? resolveJunctionColumn(junction, entry.targetJoinField!, ctx)
-    : entry.targetJoinField!;
-  const targetPkColumn = target
-    ? resolveJunctionColumn(target, ctx.pkMap.get(entry.targetEntity)?.fieldName ?? "id", ctx)
-    : "id";
+  // fromPackage = source.package: this routes file is SOURCE's own module, never the
+  // junction's or the target's — see resolveJunctionColumn's doc comment (B1).
+  const sourceColumn: Code = junction
+    ? resolveJunctionColumn(junction, entry.sourceJoinField!, ctx, source.package)
+    : code`${JSON.stringify(entry.sourceJoinField!)}`;
+  const targetColumn: Code = junction
+    ? resolveJunctionColumn(junction, entry.targetJoinField!, ctx, source.package)
+    : code`${JSON.stringify(entry.targetJoinField!)}`;
+  const targetPkColumn: Code = target
+    ? resolveJunctionColumn(target, ctx.pkMap.get(entry.targetEntity)?.fieldName ?? "id", ctx, source.package)
+    : code`${JSON.stringify("id")}`;
 
   return code`  ${mountM2mRouteSym}({
     fastify: ${fastifyVar},
@@ -287,19 +300,44 @@ function renderM2mMount(
     db,
     junctionTable: ${junctionVarSym},
     targetTable: ${targetVarSym},
-    sourceColumn: ${JSON.stringify(sourceColumn)},
-    targetColumn: ${JSON.stringify(targetColumn)},
-    targetPkColumn: ${JSON.stringify(targetPkColumn)},
+    sourceColumn: ${sourceColumn},
+    targetColumn: ${targetColumn},
+    targetPkColumn: ${targetPkColumn},
     symmetric: ${entry.symmetric ? "true" : "false"},
   });`;
 }
 
-/** Resolve a field's physical column name on an entity (defaults if missing). */
-function resolveJunctionColumn(entity: MetaObject, fieldName: string, ctx: RenderContext): string {
+/**
+ * Resolve a field's physical column name on an entity (defaults if missing), as a
+ * ts-poet Code fragment.
+ *
+ * §A6/§B2 — references `<Entity>Names.fields.<field>.column` whenever the names
+ * artifact is in this run AND carries the field (the same two-condition shape as every
+ * other §A6 site: is the artifact in the run, is the field in it — both PRESENCE
+ * guards). A literal otherwise.
+ *
+ * B1 — `entity` here is the JUNCTION or TARGET object, never the routes file's own
+ * SOURCE entity (see renderM2mMount) — so `fromPackage` MUST be the source entity's
+ * package, not `entity`'s own. A same-package caller cannot tell the two apart (they're
+ * equal), which is exactly how this went unnoticed until a package-layout M:N golden
+ * existed: a plain sibling specifier (assuming fromPackage === entity.package, the
+ * shape `namesRef`'s default deliberately does NOT special-case) silently produced a
+ * same-directory import for a names artifact that lives in a DIFFERENT directory,
+ * because the object whose file we're building and the object whose names we're
+ * importing are two different objects.
+ */
+function resolveJunctionColumn(
+  entity: MetaObject,
+  fieldName: string,
+  ctx: RenderContext,
+  fromPackage: string | undefined,
+): Code {
   // ADR-0039: resolving — a junction FK field may be inherited via extends.
   const field = entity.children().find((c) => c.type === TYPE_FIELD && c.name === fieldName);
-  if (!field) return fieldName;
-  return resolveColumnName(field, ctx.columnNamingStrategy);
+  if (!field) return code`${JSON.stringify(fieldName)}`;
+  const dbCol = resolveColumnName(field, ctx.columnNamingStrategy);
+  const names = namesRef(entity, ctx, fromPackage);
+  return columnExpr(names, field.name, dbCol);
 }
 
 /**
@@ -318,7 +356,11 @@ function resolveJunctionColumn(entity: MetaObject, fieldName: string, ctx: Rende
  * FR-017 design's `/auths/bridge` examples. Fastify resolves the static
  * `/auths/bridge` ahead of the parametric `/auths/:id`, so the two coexist.
  */
-function renderTphRoutesFile(base: MetaObject, ctx: RenderContext): string {
+function renderTphRoutesFile(
+  base: MetaObject,
+  ctx: RenderContext,
+  expose?: readonly CrudVerb[],
+): string {
   const baseName = base.name;
   const handlerName = routesHandlerName(baseName);
   // Single source of truth for the discriminator field + subtypes + route segments.
@@ -344,6 +386,10 @@ function renderTphRoutesFile(base: MetaObject, ctx: RenderContext): string {
   const fastifyRef = ctx.apiPrefix ? "instance" : "fastify";
   const dialectLit = JSON.stringify(ctx.dialect);
 
+  // The polymorphic mount is read-only BY CONSTRUCTION — the discriminated union has no
+  // single writable shape — so an author-supplied `expose` intersects with that fixed set
+  // rather than replacing it: it may narrow to just `list`, never widen to `create`.
+  const polymorphicExposeLine = exposeLine(intersectExpose([...TPH_POLYMORPHIC_VERBS], expose), "      ");
   const polymorphic = code`
     ${mountCrudRoutesSym}({
       fastify: ${fastifyRef},
@@ -354,8 +400,7 @@ function renderTphRoutesFile(base: MetaObject, ctx: RenderContext): string {
       updateSchema: ${baseUpdateSym},
       filterAllowlist: ${baseFilterSym},
       sortAllowlist: ${baseSortSym},
-      dialect: ${dialectLit},
-      expose: ["list", "get"],
+      dialect: ${dialectLit},${polymorphicExposeLine}
     });`;
 
   const subtypeMounts: Code[] = plan.subtypes.map(({ entity: sub, value, routeSegment: segment }) => {
@@ -386,7 +431,7 @@ function renderTphRoutesFile(base: MetaObject, ctx: RenderContext): string {
       filterAllowlist: ${subFilterSym},
       sortAllowlist: ${subSortSym},
       dialect: ${dialectLit},
-      discriminator: { column: ${JSON.stringify(discField)}, value: ${JSON.stringify(value)} },
+      discriminator: { column: ${JSON.stringify(discField)}, value: ${JSON.stringify(value)} },${exposeLine(expose, "      ")}
     });`;
   });