@metaobjectsdev/codegen-ts 0.24.5 → 1.0.0-rc.1

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/requirement-test.ts

@@ -139,10 +139,21 @@ export function renderRequirementTest(a: RequirementTestArgs): string {
     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, "      ")}
     });`;
   });
 

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

@@ -23,6 +23,7 @@ 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 { namesRef, namesConstArg } from "../names.js";
 
 export function renderValueObjectFile(obj: MetaObject, apiPrefix = "", ctx?: RenderContext): string {
   const enumAliases = renderEnumTypeAliases(obj, ctx);
@@ -34,7 +35,20 @@ export function renderValueObjectFile(obj: MetaObject, apiPrefix = "", ctx?: Ren
   // FR-017 Tier 3: a TPH subtype also emits its field-metadata constants object
   // (the `<Sub>` const), so the React form generator can render per-field
   // labels / rules / inputs the same way it does for ordinary entities.
-  const tphConstants = tphSubtype ? renderEntityConstants(obj, apiPrefix) : null;
+  //
+  // §A6/§B2 — a TPH subtype declares no source.rdb of its own; it INHERITS the
+  // discriminator base's single shared table (`children()` is resolving — ADR-0039).
+  // `resolveObjectNames` therefore returns a DEFINED result for it (confirmed
+  // empirically: `name` is the BASE's physical table name, `fields` covers both the
+  // base's inherited columns and the subtype's own), and `namesFile()` really does emit
+  // a `<Sub>.names.ts` for it — this is not a case where the literal is correct and must
+  // stay. Same `namesRef` pair every other §A6 site builds; `ctx` is guaranteed present
+  // at every real call site (entity-file.ts and its reference/entity.ts mirror both
+  // always pass it) even though the parameter stays optional for a bare unit-test call.
+  const tphNames = tphSubtype && ctx !== undefined ? namesRef(obj, ctx) : undefined;
+  const tphConstants = tphSubtype
+    ? renderEntityConstants(obj, apiPrefix, namesConstArg(tphNames))
+    : null;
   // FR-017 Tier 3: per-subtype filter + sort allowlists, excluding the
   // discriminator (it's pinned by the per-subtype route path, so a client must
   // not filter on it). Included fields are the subtype's own + inherited base

package/src/templates/view-decl.ts

@@ -14,6 +14,7 @@ import {
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
 import { mapColumnType } from "../column-mapper.js";
 import { zodTypeFor } from "./field-meta.js";
+import { columnExpr, type ObjectNames } from "../names.js";
 
 export interface ViewDeclOpts {
   readonly dialect: "postgres" | "sqlite";
@@ -38,6 +39,31 @@ export interface ViewDeclOpts {
    * UpdateSchema, all of which already treat the PK as non-null.
    */
   readonly pkFieldNames: ReadonlySet<string>;
+  /**
+   * §A6 — the resolved names artifact supplying this declaration's COLUMN constants,
+   * plus the ts-poet symbol reference (`imp()`'d import of `<Object>Names`), when the
+   * names generator is in the run. Absent ⇒ every column stays a literal.
+   *
+   * Deliberately says nothing about the view's OWN physical name: the two answers come
+   * apart on a write-through entity, whose artifact holds the TABLE's name (its primary
+   * source) while this declaration binds the REPLICA view. Conflating them cost the
+   * write-through read model its column constants — it had to omit `names` entirely to
+   * stop the artifact's view name being emitted, and lost every
+   * `.fields.<f>.column` reference with it. The view's name is now the caller's to pass
+   * (see the `viewName` parameter), which is the only place that knows.
+   */
+  readonly names?: { readonly resolved: ObjectNames; readonly symbol: Code } | undefined;
+  /**
+   * The view's `@schema` — a bare name, or an EXPRESSION for it (a names constant).
+   *
+   * Passed in rather than derived from `names`, and for the same reason `viewName` is: a
+   * write-through entity's REPLICA view is a different source node from the one
+   * `<Entity>Names` resolves, so the artifact's `schema` there is the WRITE TABLE's and
+   * would be a confidently wrong answer. A caller whose artifact genuinely names this view
+   * passes the constant expression; the replica-view caller passes its own literal, which
+   * is consistent with that view's NAME already being a known literal for the same reason.
+   */
+  readonly schema?: string | Code | undefined;
 }
 
 /**
@@ -85,7 +111,10 @@ function viewColumnLine(f: MetaField, opts: ViewDeclOpts): Code {
       dollarType = code`.$type<Record<string, ${imp(`${vo.name}@${vo.module}`)}>>()`;
     }
   }
-  return code`  ${f.name}: ${colSym}(${JSON.stringify(spec.dbName)}${optsArg})${dollarType}${viewModifiers}`;
+  // A6 — reference the constant whenever the artifact is in the run AND carries this
+  // field. A lookup MISS is normal, not a divergence — see ViewDeclOpts.names.
+  const dbNameExpr = columnExpr(opts.names, f.name, spec.dbName);
+  return code`  ${f.name}: ${colSym}(${dbNameExpr}${optsArg})${dollarType}${viewModifiers}`;
 }
 
 /**
@@ -95,7 +124,13 @@ function viewColumnLine(f: MetaField, opts: ViewDeclOpts): Code {
  */
 export function renderExistingViewDecl(
   fields: readonly MetaField[],
-  viewName: string,
+  /**
+   * The view's own physical name: a plain string is emitted as a literal, a `Code` is
+   * emitted verbatim (a caller whose names artifact genuinely names THIS view passes
+   * `physicalNameExpr(names, viewName)`). See `ViewDeclOpts.names` for why this is not
+   * derived from that artifact here.
+   */
+  viewName: string | Code,
   viewVar: string,
   opts: ViewDeclOpts,
 ): Code {
@@ -103,11 +138,26 @@ export function renderExistingViewDecl(
   const viewModule = opts.dialect === "postgres" ? "drizzle-orm/pg-core" : "drizzle-orm/sqlite-core";
   const viewSym = imp(`${viewFn}@${viewModule}`);
   const viewColumnLines = fields.map((f) => viewColumnLine(f, opts));
+  const viewNameExpr = typeof viewName === "string" ? code`${JSON.stringify(viewName)}` : viewName;
+
+  // @schema — a view lands in a schema exactly as a table does, and migrate qualifies the
+  // `CREATE VIEW` it emits. Fixing the table binding and leaving this one would be the more
+  // dangerous half-job: the two would then disagree with each OTHER as well as with the
+  // database. Drizzle spells it with the same shape as the table case, `pgSchema(s).view(...)`
+  // — PgSchema carries `view` alongside `table`. sqlite is excluded for the same reason as
+  // there: no schema concept, and migrate refuses a non-default @schema on that dialect.
+  const viewSchemaExpr: Code | undefined =
+    opts.dialect !== "postgres" || opts.schema === undefined ? undefined
+    : typeof opts.schema === "string" ? code`${JSON.stringify(opts.schema)}`
+    : opts.schema;
+  const viewCall: Code = viewSchemaExpr === undefined
+    ? code`${viewSym}`
+    : code`${imp(`pgSchema@${viewModule}`)}(${viewSchemaExpr}).view`;
   return code`
 // View declaration — Drizzle uses this for typed SELECT queries.
 // The SQL view is created/managed by migrate-ts; .existing() tells Drizzle
 // not to attempt DDL for this declaration.
-export const ${viewVar} = ${viewSym}(${JSON.stringify(viewName)}, {
+export const ${viewVar} = ${viewCall}(${viewNameExpr}, {
 ${joinCode(viewColumnLines, { on: ",\n" })}
 }).existing();
 `;

package/src/templates/zod-validators.ts

@@ -51,19 +51,55 @@ import { isRequired } from "../column-mapper.js";
  * when the object is not a TPH subtype.
  */
 export function tphDiscriminatorPin(obj: MetaObject): { fieldName: string; value: string } | undefined {
-  // ADR-0039: own — super-resolution walk. A subtype declares its OWN
-  // @discriminatorValue (must not inherit one), and the base level is found by
-  // walking superResolved reading each level's OWN @discriminator.
+  // ADR-0039: own — a subtype declares its OWN @discriminatorValue (must not inherit
+  // one); the base level is found by the super-resolution walk in `tphDiscriminatorLevel`.
   const value = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
   if (typeof value !== "string" || value === "") return undefined;
+  const level = tphDiscriminatorLevel(obj);
+  if (level === undefined) return undefined;
+  return { fieldName: level.fieldName, value };
+}
 
-  // Walk the extends chain to find the root carrying @discriminator.
+/**
+ * The discriminator BASE an object extends — the nearest ancestor declaring
+ * `@discriminator` — or undefined when there is none.
+ *
+ * The base is NOT the topmost ancestor: a multi-level hierarchy can extend further up
+ * past the level that owns the discriminator, and a route path composed against the
+ * wrong level names an endpoint nothing mounts. One walk, read by `tphDiscriminatorPin`
+ * and by `restPath` (api-surface.ts), so the pin and the address agree on which object
+ * is the base.
+ */
+export function tphDiscriminatorBase(obj: MetaObject): MetaObject | undefined {
+  return tphDiscriminatorLevel(obj)?.base;
+}
+
+/**
+ * True when this object itself DECLARES `@discriminator` — the level of a TPH hierarchy
+ * that owns the discriminator, whether or not any concrete subtype extends it yet.
+ *
+ * ADR-0039: own — `@discriminator` identifies a hierarchy LEVEL, so it is read own: a
+ * subtype inheriting the attr through `extends` must not be mistaken for a base. This is
+ * the one predicate the form generator's filter (`hasGeneratedForm`) and the `agent/ui.md`
+ * page both ask, so "is this a discriminator base?" has one spelling.
+ */
+export function declaresTphDiscriminator(obj: MetaObject): boolean {
+  return typeof obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR) === "string";
+}
+
+/**
+ * The ONE super-resolution walk behind `tphDiscriminatorBase` and `tphDiscriminatorPin`:
+ * the nearest ancestor declaring a non-empty `@discriminator`, with the field name it
+ * declares. Returning both from one walk is what keeps the pin's field name and the
+ * base's identity from ever being read at two different levels.
+ */
+function tphDiscriminatorLevel(obj: MetaObject): { base: MetaObject; fieldName: string } | undefined {
   let cursor = obj.superResolved;
   while (cursor !== undefined) {
     // ADR-0039: own — super-resolution walk; read each level's OWN @discriminator.
     const fieldName = cursor.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
     if (typeof fieldName === "string" && fieldName !== "") {
-      return { fieldName, value };
+      return { base: cursor as MetaObject, fieldName };
     }
     cursor = cursor.superResolved;
   }