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

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

@@ -6,6 +6,8 @@ import {
   TYPE_RELATIONSHIP,
   isMetaObject,
   isReadOnlySource,
+  SOURCE_ROLE_PRIMARY,
+  SOURCE_ATTR_SCHEMA,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
   ORIGIN_SUBTYPE_COMPUTED,
@@ -49,7 +51,7 @@ import {
   resolveObjectRef,
   type AggregateFunction,
 } from "@metaobjectsdev/metadata";
-import { type MetaData, type MetaField, type MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
+import { type MetaData, type MetaField, type MetaRoot, type MetaSource, MetaObject } from "@metaobjectsdev/metadata";
 import { intValueMapOf } from "../enum-meta.js";
 import {
   columnNameFromField,
@@ -331,16 +333,58 @@ function resolveHop(
 function viewName(projection: MetaObject, ctx: ExtractContext): string {
   // The read-only source carries the physical view name. FR-016: physicalName
   // implements the four-step rule (kind-matching alias → legacy @table →
-  // source.name → entity-name fallback), so the call below correctly resolves
-  // @view / @materializedView / legacy @table for projection sources.
+  // source.name → entity-name fallback), so `viewSource.physicalName` below
+  // correctly resolves @view / @materializedView / legacy @table for projection
+  // sources.
   // ADR-0039: own — projection source classification (mirrors C# projection
-  // OwnSources / IsReadOnlyProjection): the view name comes from the projection's
-  // OWN read-only source, not one inherited via extends.
-  const viewSource = projection.ownChildren().find(isReadOnlySource);
+  // OwnSources / IsReadOnlyProjection): the view name comes from the object's
+  // OWN read-only source, not one inherited via extends. `ERR_PROJECTION_
+  // INHERITED_SOURCE` (subtype-rules.ts) already refuses a concrete projection
+  // that would otherwise inherit a source, so own-only never drops a legally
+  // reachable source here.
+  //
+  // This function serves TWO shapes — a plain projection, and a write-through
+  // ENTITY's replica view (extractViewSpec's `writeThrough` branch, #213/#214;
+  // the parameter name is historical) — which need DIFFERENT selection rules,
+  // hence "prefer role:primary, else the first read-only source" rather than
+  // "require role:primary":
+  //   - A plain projection: EVERY own source must be read-only-kind
+  //     (ERR_PROJECTION_SOURCE_WRITABLE), so if it has any sources at all,
+  //     exactly one is role:"primary" (ERR_SOURCE_NO_PRIMARY /
+  //     ERR_SOURCE_MULTIPLE_PRIMARY) and that one IS read-only — the primary
+  //     branch always fires when there is a source.
+  //   - A write-through entity: its role:"primary" source is the WRITABLE
+  //     table (never read-only), so the primary branch never fires; its
+  //     read-only companion (the replica view) is intentionally NOT primary.
+  //     The fallback (first read-only own source) is what names it.
+  //
+  // Selecting the role:"primary" read-only source PREFERENTIALLY over
+  // declaration order (rather than "first read-only source in file order") is
+  // what makes this agree with `resolveTableName()` (the resolver every §A6
+  // site defers to via `resolveObjectNames`): a plain projection declaring a
+  // role:"replica" source before its role:"primary" one would otherwise bind a
+  // different physical view depending on whether the names generator happened
+  // to be active in the run.
+  const readOnlySources = projection.ownChildren().filter(isReadOnlySource);
+  const viewSource =
+    readOnlySources.find((c) => c.role === SOURCE_ROLE_PRIMARY) ?? readOnlySources[0];
   const explicit = viewSource?.physicalName;
   // physicalName always returns a string; empty string means the source had
   // neither alias nor a name and the owning entity name was empty (impossible
   // for a real projection). Fall through to the helper anyway for safety.
+  //
+  // This fallback fires only when the object has NO own read-only source at
+  // all. It differs from `resolveTableName()`'s own no-source fallback
+  // (`v_<snake(name)>` here vs `pluralize(toSnakeCase(name))` there), but that
+  // difference is UNOBSERVABLE: whenever a sourceless object reaches this
+  // fallback, `resolveObjectNames()` also finds no primary source and returns
+  // `undefined` before ever calling `resolveTableName()` — so no §A6 site has
+  // a names constant to reference either way, and both the ON and OFF arms
+  // land on THIS function's literal on the identical no-source condition. A
+  // sourceless projection also fails `isProjection()` itself
+  // (projection-detector.ts requires a read-only-kind source), so codegen's
+  // dispatch never reaches `renderProjectionDecl`/this function for it in the
+  // first place — doubly unreachable.
   return explicit !== undefined && explicit !== ""
     ? explicit
     : viewNameFromProjection(projection.name, ctx.columnNamingStrategy);
@@ -363,6 +407,41 @@ export function projectionViewName(
   return viewName(projection, { columnNamingStrategy });
 }
 
+/**
+ * The `@schema` of the SAME source node {@link projectionViewName} names, or undefined.
+ *
+ * It re-uses that function's selection rule ("prefer role:primary read-only, else the first
+ * read-only own source") deliberately, rather than asking the object for its schema: for a
+ * write-through ENTITY the object's primary source is the WRITABLE table, so
+ * `resolveTableSchema` would hand back the table's schema and qualify the replica view with
+ * it. A view and the table it replicates need not live in the same schema, and a name paired
+ * with someone else's schema is worse than no schema at all — it is confidently wrong.
+ */
+export function projectionViewSchema(projection: MetaObject): string | undefined {
+  const schema = projectionViewSource(projection)?.attr(SOURCE_ATTR_SCHEMA);
+  return typeof schema === "string" && schema !== "" ? schema : undefined;
+}
+
+/**
+ * The source node {@link projectionViewName} names — the ONE selection, so the name, the
+ * schema and the role cannot be picked by three functions that agree until they do not.
+ *
+ * Hoisted out of `projectionViewSchema`, which used to be the only place the rule was
+ * written twice-removed from `viewName`. The third caller is what forced it: the names
+ * artifact keys its sources by ROLE, so a consumer reaching for a write-through entity's
+ * replica view has to know which role that view plays, and guessing `"replica"` would be
+ * exactly the second derivation this file exists to avoid.
+ */
+export function projectionViewSource(projection: MetaObject): MetaSource | undefined {
+  const readOnlySources = projection.ownChildren().filter(isReadOnlySource);
+  return readOnlySources.find((c) => c.role === SOURCE_ROLE_PRIMARY) ?? readOnlySources[0];
+}
+
+/** The ROLE of that source — the key its entry has in `<Entity>Names.sources`. */
+export function projectionViewRole(projection: MetaObject): string | undefined {
+  return projectionViewSource(projection)?.role;
+}
+
 /**
  * FR-024 (ADR-0029): the entity NAMED by a node's dotted extends ref — the
  * owner part of `<owner>.<child>...` resolved as an object. Mirrors the

package/src/reference/entity.ts

@@ -61,11 +61,14 @@ import {
   isWriteThrough,
   isAbstract,
   hasWritableRdbSource,
+  isTphSubtype,
   // engine composer — used for the delegated write-through variant:
   renderEntityFile,
   // engine plumbing:
   formatTs,
   entityOutputPath,
+  namesRef,
+  namesConstArg,
   GENERATED_HEADER,
 } from "@metaobjectsdev/codegen-ts";
 
@@ -84,6 +87,10 @@ function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntit
   }
   // Projection → read-only view declaration + read schema.
   if (isProjection(entity)) {
+    // §A6/§B2 — same `namesRef` pair renderDrizzleSchema builds, so the projection's view
+    // name + per-field dbCol reference the exact constant the names artifact exports
+    // (undefined when the artifact is not in this run). `namesRef`'s `{ resolved, symbol }`
+    // return is exactly the shape `ProjectionDeclOpts.names` wants.
     return renderProjectionDecl(entity, ctx.loadedRoot, {
       columnNamingStrategy: ctx.columnNamingStrategy,
       dialect: ctx.dialect,
@@ -92,10 +99,18 @@ function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntit
       allowlists,
       ctx,
       includeViewDecl: runtime,
+      names: namesRef(entity, ctx),
     });
   }
   // Value-only / contract target → interface + Zod, no Drizzle table.
-  if (!runtime || !hasWritableRdbSource(entity)) {
+  //
+  // A TPH subtype (FR-017) routes here too. It INHERITS the discriminator base's writable
+  // source.rdb through `extends`, so `hasWritableRdbSource` is true for it under the
+  // ADR-0039 resolving read — but the base owns the single shared table. Without the
+  // isTphSubtype clause this template fell through to the vanilla path and emitted a
+  // SECOND Drizzle table bound to the base's physical name, carrying only the subtype's
+  // own columns.
+  if (!runtime || !hasWritableRdbSource(entity) || isTphSubtype(entity)) {
     return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
   // #214 — a write-through entity read-view (writable table + a read-only replica view +
@@ -110,12 +125,16 @@ function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntit
   const enumAliases = renderEnumTypeAliases(entity, ctx);
   const tphBlock = renderTphDiscriminatorUnion(entity, ctx.loadedRoot);
   const tphBase = tphBlock !== null && isTphDiscriminatorBase(entity, ctx.loadedRoot);
+  // §A6/§B2 — same `namesRef` pair renderDrizzleSchema (and the projection branch above)
+  // build, so the descriptor's $table references the exact constant the names artifact
+  // exports (undefined when the artifact is not in this run).
+  const constantsNames = namesRef(entity, ctx);
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
     renderInferredTypes(entity, tphBase, ctx),
     ...(enumAliases !== null ? [enumAliases] : []),
     renderZodValidators(entity, ctx),
-    renderEntityConstants(entity, ctx.apiPrefix),
+    renderEntityConstants(entity, ctx.apiPrefix, namesConstArg(constantsNames)),
     ...(allowlists ? [renderFilterAllowlist(entity, undefined, ctx), renderSortAllowlist(entity)] : []),
     renderFilterType(entity),
     ...(tphBlock !== null ? [tphBlock] : []),

package/src/reference/names.ts

@@ -0,0 +1,125 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/names.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { namesFile } from "./codegen/generators/names.js";
+//
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
+// targets:       the emit step. Replace `renderNamesDecl` to change the artifact's SHAPE
+//                (e.g. flat `SUBSCRIBER_TABLE` constants instead of a nested object); keep
+//                `resolveObjectNames` so the names still come from the same resolver as the DDL.
+// use-when:      you want the physical database names (table/view + column names) for each
+//                object available as importable constants, so a hand-written consumer never
+//                has to embed a name as a string literal a second time.
+// emits:         <target>/<Entity>.names.ts per concrete object with a primary source
+//                (under outputLayout: "package", <target>/<pkg>/<Entity>.names.ts — beside
+//                the entity module it describes). An object with no primary source (#248)
+//                gets no names artifact — EXCEPT an abstract base that a sourced object
+//                extends, which gets a fragment (columns, no physical name) so its
+//                children extend it instead of restating every inherited column.
+// customize:     swap `renderNamesDecl` for your own shape; keep `resolveObjectNames` as the
+//                one resolver so the constant and the DDL it describes cannot disagree.
+// composes-with: entity.ts, routes.ts — both reference these constants instead of
+//                embedding the names a second time. queries.ts never embeds a physical
+//                name of its own: it reads/writes through the Drizzle table object
+//                entity.ts builds (columns keyed by FIELD name), so there is nothing in
+//                it to wire.
+//
+// The composition here is deliberately a SEPARATE generator, never a boolean on the entity
+// generator — a new artifact is a MINOR under docs/compatibility-policy.md and adds zero
+// bytes to existing files, where a flag would move every $table-carrying golden for the
+// same functionality.
+import {
+  crossEntitySpecifier,
+  entityOutputPath,
+  namesArtifactSuperOf,
+  renderNamesDecl,
+  resolveObjectNames,
+  type EmittedFile,
+  type GenContext,
+  type Generator,
+} from "@metaobjectsdev/codegen-ts";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+
+export function namesFile(): Generator {
+  return {
+    name: "names",
+    // §A6 — the marker the runner aggregates into ResolvedGenConfig.includeNames, so the
+    // entity generator can tell whether this artifact will exist. Exactly the mechanism
+    // routesFileHono already uses via emitsHonoRoutes/includeHonoRoutes.
+    emitsNames: true,
+    generate: (ctx: GenContext): EmittedFile[] => {
+      const layout = ctx.config.outputLayout ?? "flat";
+      const extStyle = ctx.config.extStyle ?? "js";
+      // The strategy lives on the RENDER CONTEXT, not on ResolvedGenConfig — `ctx.config`
+      // carries outDir/extStyle/dbImport/dialect and nothing about naming.
+      const strategy = ctx.renderContext?.columnNamingStrategy;
+
+      const pathOf = (obj: MetaObject): string =>
+        // entityOutputPath, not a bare filename: §A6 makes the entity module IMPORT these
+        // constants, so the artifact has to land in the same directory the entity module
+        // does. Under outputLayout: "package" a bare name puts it at the target ROOT while
+        // its entity sits at <pkg>/<Entity>.ts — an unresolvable import, and a hard
+        // conflicting-duplicate-path failure as soon as two packages declare a
+        // same-bare-named entity.
+        entityOutputPath(layout, obj.package, `${obj.name}.names.ts`);
+
+      const superSpecifierFor = (obj: MetaObject): string | undefined => {
+        const sup = namesArtifactSuperOf(obj);
+        return sup === undefined
+          ? undefined
+          : crossEntitySpecifier(layout, obj.package, sup.package, `${sup.name}.names`, extStyle);
+      };
+
+      const out: EmittedFile[] = [];
+      // Pass 1 — every matched object that participates in the database (#248).
+      // `emitted` tracks what pass 1 actually WROTE, not what it looked at: a matched
+      // abstract base emits nothing here, and seeding it as already-emitted is what would
+      // make pass 2 skip the very object it exists to produce.
+      const emitted = new Set<string>();
+      const participants = ctx.entities.filter(ctx.matches);
+      for (const entity of participants) {
+        const content = renderNamesDecl(entity, {
+          strategy, superSpecifier: superSpecifierFor(entity),
+        });
+        if (content === "") continue;   // no primary source ⇒ no names artifact (#248)
+        emitted.add(entity.resolutionKey());
+        out.push({ path: pathOf(entity), content });
+      }
+
+      // Pass 2 — the abstract bases those participants EXTEND. Each carries the columns it
+      // declares, so a child states them once rather than restating its parent's.
+      //
+      // Reached by walking UP from a participant, never by scanning for abstracts: that is
+      // what keeps #248 intact. A sourceless object nothing persistable extends — an
+      // `object.value`, say — is not reached, so it acquires no artifact and no phantom
+      // participation. Two children of one base both reach it and emit the same file at
+      // the same path with the same bytes; the runner collapses byte-identical duplicates
+      // (#266), so it is written once. `emitted` keeps that from even arising, and keeps
+      // the walk from re-rendering the same base once per child.
+      for (const entity of participants) {
+        if (resolveObjectNames(entity, strategy) === undefined) continue;
+        for (let sup = namesArtifactSuperOf(entity); sup !== undefined;
+             sup = namesArtifactSuperOf(sup)) {
+          const key = sup.resolutionKey();
+          if (emitted.has(key)) break;   // already emitted, and so is everything above it
+          emitted.add(key);
+          const content = renderNamesDecl(sup, {
+            strategy, superSpecifier: superSpecifierFor(sup),
+            // "Fragment" means "declares no source". Hardcoding `true` is right for the
+            // shape this pass was written for — an abstract base with columns and no table
+            // — and wrong for the one it also reaches: `meta gen --entities <Subtype>`
+            // walks up to a TPH BASE, which owns the shared table, and a fragment renders
+            // no source at all. The engine derives this itself now (`renderNamesDecl`
+            // consults the object), so the flag says only "this is an ancestor render".
+            fragment: true,
+          });
+          if (content === "") continue;
+          out.push({ path: pathOf(sup), content });
+        }
+      }
+      return out;
+    },
+  };
+}

package/src/reference/queries.ts

@@ -41,6 +41,7 @@ import {
   renderFindByIdFn,
   renderListFn,
   renderCreateFn,
+  renderInsertPreservingFn,
   renderUpdateFn,
   renderDeleteByIdFn,
   renderReverseFinderFns,
@@ -50,6 +51,7 @@ import {
   isWriteThrough,
   isTphSubtype,
   hasAnyRdbSource,
+  hasAutoSetFields,
   renderQueriesFile, // engine composer — used for the delegated variants
   formatTs,
   entityOutputPath,
@@ -77,20 +79,33 @@ function renderQueries(obj: MetaObject, ctx: RenderContext): string {
 
   // `db` is parameter-passed into every finder (ADR-0008). Emit the dialect-correct
   // Drizzle type alias so signatures typecheck without the consumer constructing one.
+  // Keep EVERY type argument as open as Drizzle's own constraint allows — a `Db` this
+  // alias cannot name is a helper nobody can call, and uncompilable generated code looks
+  // exactly like unused generated code from outside. Both the driver axis (base classes,
+  // not `NodePgDatabase` / `<"async">`) and the schema axis (`Record<string, unknown>`,
+  // Drizzle's own `TFullSchema extends …` bound, NOT its `Record<string, never>` default)
+  // have been re-pinned once already; do not narrow either again. A schema-carrying
+  // `drizzle(client, { schema })` must assign, and so must a schema-less `drizzle(client)`.
   const dbTypeImport =
     ctx.dialect === "postgres"
       ? `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`
       : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
   const dbTypeAlias =
     ctx.dialect === "postgres"
-      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`
-      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`;
+      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;`
+      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown, Record<string, unknown>>;`;
+
+  // #203 — an @autoSet entity additionally imports its preserving-shape schema and emits
+  // the `insertPreserving<Entity>` escape hatch after `create<Entity>`. OWNED: drop both
+  // halves together if you never insert rows carrying their own timestamps.
+  const autoSet = hasAutoSetFields(obj);
+  const preservingImport = autoSet ? `, ${entityName}InsertPreservingSchema` : "";
 
   const literalImports = code`
 ${dbTypeImport}
 ${dbTypeAlias}
 
-import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
+import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}InsertSchema${preservingImport}, ${entityName}UpdateSchema } from ${JSON.stringify(entityFileName)};
 `;
 
   const sections: Code[] = [
@@ -98,6 +113,7 @@ import { ${varName}, type ${entityName}, type ${entityName}Patch, ${entityName}I
     renderFindByIdFn(obj, ctx),
     renderListFn(obj, ctx),
     renderCreateFn(obj, ctx),
+    ...(autoSet ? [renderInsertPreservingFn(obj, ctx)] : []),
     renderUpdateFn(obj, ctx),
     renderDeleteByIdFn(obj, ctx),
   ];

package/src/reference/routes-hono.ts

@@ -19,7 +19,11 @@
 //                object and for TPH subtypes.
 // customize:     this generator is YOURS — edit it freely. For the emitted route
 //                composition, call `renderRoutesFileHono` (exported from the engine) and
-//                wrap its result, or replace the call entirely.
+//                wrap its result, or replace the call entirely. Decide per generator what
+//                you consume: wire only the generators whose output you actually import,
+//                and narrow this one with its `filter`. There is no `@emit*` metadata
+//                attribute — those were never registered vocabulary, so `meta verify`
+//                rejects them (ERR_UNKNOWN_ATTR).
 // composes-with: entity.ts (imports the table/schemas/allowlists), queries.ts.
 
 import { type MetaObject } from "@metaobjectsdev/metadata";
@@ -28,15 +32,26 @@ import {
   type Generator,
   type GeneratorFactory,
   renderRoutesFileHono,
+  resolveExpose,
+  type ExposeOption,
   isTphSubtype,
   hasAnyRdbSource,
   formatTs,
   entityOutputPath,
-  CODEGEN_ATTR_EMIT_ROUTES,
 } from "@metaobjectsdev/codegen-ts";
 
 export interface RoutesFileHonoOpts {
   filter?: (entity: MetaObject) => boolean;
+  /**
+   * Which CRUD verbs the emitted file mounts (#348). Verbs, or a per-entity function;
+   * absent means all five and emits byte-identical output.
+   *
+   *   routesFileHono({ expose: (e) => e.name === "AuditEntry" ? ["list", "get"] : undefined })
+   *
+   * A `filter` cannot express this — it decides whether the file emits AT ALL, so it can
+   * only remove the whole surface, not restrict it to a subset of verbs.
+   */
+  expose?: ExposeOption;
   target?: string;
 }
 
@@ -48,17 +63,12 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
   // without being named as held back, or get warned about while still emitting.
   // (Same shape as tanstack's grid generator, which factors it the same way.)
   const passesOtherGates = (e: MetaObject): boolean =>
-    // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
-    e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false
-    && hasAnyRdbSource(e)
-    && userFilter(e);
+    hasAnyRdbSource(e) && userFilter(e);
   const generator: Generator = {
     name: "routes-file-hono",
     // Marks this as the Hono routes generator so the runner can aggregate
     // `ctx.config.includeHonoRoutes` and api-docs auto-documents the Hono surface.
     emitsHonoRoutes: true,
-    // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
-    //
     // TPH subtypes are EXCLUDED, matching the Fastify generator. A TPH subtype shares
     // its base's table, so mounting vanilla CRUD for it produced routes with no
     // discriminator scoping at all: the list returned EVERY subtype's rows, and
@@ -93,7 +103,7 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
           entity.package,
           `${entity.name}.routes.hono.ts`,
         ),
-        content: await formatTs(renderRoutesFileHono(entity, ctx.renderContext)),
+        content: await formatTs(renderRoutesFileHono(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
       };
   });
   if (opts?.target) {

package/src/reference/routes.ts

@@ -12,14 +12,20 @@
 //                framework; see also the routes-hono template, whose deps-injected shape
 //                ports more easily to hosts that hand you a request.
 // use-when:      you want generated Fastify REST routes per entity. Drop it and hand-write routes
-//                if you need bespoke endpoints — or keep it and add handlers via <Entity>.extra.ts.
+//                if you need bespoke endpoints — or keep it and register extra handlers YOURSELF
+//                alongside the generated `register<Entity>Routes(app)` call. Nothing here
+//                discovers a sibling module: a `<Entity>.extra.ts` next to the output is a naming
+//                convention, not a plugin point, so its handlers only mount if your server calls them.
 // emits:         <target>/<Entity>.routes.ts — full CRUD for write-through entities, read-only
 //                (GET list + GET :id) for projections, polymorphic + per-subtype for TPH bases.
 //                Skipped for any sourceless object (incl. every object.value, source-less by
 //                value purity) and for TPH subtypes — no source.rdb means no table/allowlist
 //                for a routes file to import (#248 R2).
-// customize:     this generator (filter, output path, per-entity @emitRoutes opt-out, target) is
-//                YOURS — edit it freely. The route *composition* itself is richer than the others
+// customize:     this generator (filter, output path, target) is YOURS — edit it freely.
+//                Decide per generator what you consume: wire only the generators whose
+//                output you actually import, and narrow this one with its `filter`. There
+//                is no `@emit*` metadata attribute — those were never registered
+//                vocabulary, so `meta verify` rejects them (ERR_UNKNOWN_ATTR). The route *composition* itself is richer than the others
 //                (M:N junction traversal, TPH per-subtype route sets), so it stays in the engine via
 //                `renderRoutesFile`. To own the composition too, copy `renderRoutesFile`'s body out
 //                of the package source — it dispatches projection → mountReadOnlyCrudRoutes,
@@ -34,15 +40,26 @@ import {
   type Generator,
   type GeneratorFactory,
   renderRoutesFile,
+  resolveExpose,
+  type ExposeOption,
   isTphSubtype,
   hasAnyRdbSource,
   formatTs,
   entityOutputPath,
-  CODEGEN_ATTR_EMIT_ROUTES,
 } from "@metaobjectsdev/codegen-ts";
 
 export interface RoutesFileOpts {
   filter?: (entity: MetaObject) => boolean;
+  /**
+   * Which CRUD verbs the emitted file mounts (#348). Verbs, or a per-entity function;
+   * absent means all five and emits byte-identical output.
+   *
+   *   routesFile({ expose: (e) => e.name === "AuditEntry" ? ["list", "get"] : undefined })
+   *
+   * A `filter` cannot express this — it decides whether the file emits AT ALL, so it can
+   * only remove the whole surface, not restrict it to a subset of verbs.
+   */
+  expose?: ExposeOption;
   target?: string;
 }
 
@@ -50,21 +67,20 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
   const userFilter = opts?.filter ?? (() => true);
   const generator: Generator = {
     name: "routes-file",
-    // per-entity opt-out via `@emitRoutes: false`; TPH subtypes get no standalone routes
-    // file (their routes live in the discriminator base's); AND-composed with your filter.
+    // TPH subtypes get no standalone routes file (their routes live in the discriminator
+    // base's); AND-composed with your filter.
     // #248 R2: an object with no declared/inherited source.rdb (of ANY kind) isn't
     // backed by any store — routes against it would import Drizzle table/allowlist
     // exports the entity file never emits. Gated by hasAnyRdbSource.
     filter: (e: MetaObject) =>
-      // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
-      e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false && hasAnyRdbSource(e) && !isTphSubtype(e) && userFilter(e),
+      hasAnyRdbSource(e) && !isTphSubtype(e) && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("routes-file: renderContext is required (provided by runGen)");
       }
       return {
         path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.routes.ts`),
-        content: await formatTs(renderRoutesFile(entity, ctx.renderContext)),
+        content: await formatTs(renderRoutesFile(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
       };
     }),
   };

package/src/reference-templates.ts

@@ -13,7 +13,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** Basenames (no extension) of the copyable reference generators shipped in `src/reference/`. */
-export const REFERENCE_GENERATOR_NAMES = ["entity", "queries", "routes", "routes-hono", "barrel"] as const;
+export const REFERENCE_GENERATOR_NAMES = ["entity", "queries", "routes", "routes-hono", "barrel", "names"] as const;
 export type ReferenceGeneratorName = (typeof REFERENCE_GENERATOR_NAMES)[number];
 
 /** A directory is a reference root iff it holds the first template the reader was told to expect. */

package/src/render-context.ts

@@ -65,6 +65,16 @@ export interface RenderContext {
   emitAbstractShapes: boolean;
   /** Output layout mode: "flat" (default) — all files in outDir; "package" — sub-paths from entity metadata package. */
   outputLayout: OutputLayout;
+  /**
+   * §A6 — whether the run emits the `<Entity>Names` artifact (the runner aggregates the
+   * suite's `emitsNames` markers; `ctx.config.includeNames` carries the same fact for
+   * generators). A template may reference those constants ONLY when this is true: the
+   * names generator is opt-in under ADR-0034 scaffold-and-own, so an unconditional
+   * import would break every project that has not enabled it. Defaults to FALSE, which
+   * is what keeps output byte-identical for such a project — and for every bare-context
+   * caller (unit tests, generators invoked outside runGen).
+   */
+  includeNames: boolean;
   /**
    * Resolve an entity name to its Drizzle collection (table) variable name,
    * applying the project's pluralization config + per-entity overrides. Every
@@ -108,7 +118,7 @@ export interface RenderContext {
 }
 
 /** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). `collectionName` is built from `pluralizeCollections` + `collectionNameOverrides` (both default to always-pluralize). */
-export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "timestampMode" | "clientDirective" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "valueObjectNames" | "valueObjectEmittedName" | "resolveValueObjectName" | "selfTarget" | "entityModuleTarget" | "collectionName"> & {
+export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "timestampMode" | "clientDirective" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "includeNames" | "packageOf" | "valueObjectNames" | "valueObjectEmittedName" | "resolveValueObjectName" | "selfTarget" | "entityModuleTarget" | "collectionName"> & {
   extStyle?: ExtStyle;
   omImport?: string;
   columnNamingStrategy?: ColumnNamingStrategy;
@@ -117,6 +127,7 @@ export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "
   apiPrefix?: string;
   emitAbstractShapes?: boolean;
   outputLayout?: OutputLayout;
+  includeNames?: boolean;
   packageOf?: Map<string, string | undefined>;
   /** ADR-0044/#228 value-object emitted-name map (resolutionKey → emitted name).
    *  Defaults to an empty Map — bare names, byte-identical to pre-#228 output.
@@ -196,6 +207,7 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     apiPrefix: opts.apiPrefix ?? "",
     emitAbstractShapes: opts.emitAbstractShapes ?? true,
     outputLayout,
+    includeNames: opts.includeNames ?? false,
     packageOf: opts.packageOf ?? new Map(),
     valueObjectNames,
     valueObjectEmittedName: (obj: MetaData) => valueObjectNames.get(obj.resolutionKey()) ?? obj.name,

package/src/retired-codegen-attrs.ts

@@ -0,0 +1,52 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { RETIRED_CODEGEN_ATTRS } from "./constants.js";
+
+/**
+ * `@emitRoutes` / `@emitTanstack` / `@emitForm` / `@emitGrid` / `@emitAngular` were read
+ * off metadata by generator filters and were never registered metamodel vocabulary. Under
+ * the strict loader — which is what `meta verify` runs — every one of them is
+ * `ERR_UNKNOWN_ATTR`, while `meta gen` loads non-strict and honoured them. That is the
+ * defect: an adopter who authored the documented opt-out got working suppression AND a red
+ * `meta verify`, with nothing connecting the two.
+ *
+ * The reads are gone (see constants.ts for why registering them was refused rather than
+ * the other way round). But a project can be sitting on a WORKING `@emitRoutes: false`
+ * today, and deleting the read alone would start writing that suppressed file with no
+ * explanation — a silent behaviour change on upgrade, which is the one outcome not open
+ * to us. So the run says it.
+ *
+ * This follows the `layout.dataGrid` precedent (#287, data-grid-gate.ts) and the prompt
+ * generator gate beside it: tell the adopter at `meta gen` time rather than in a doc line
+ * that gets missed the same way the original one was. Warning only — the exit code is
+ * untouched, and `--dry-run` reports it too, since generators run before the write phase
+ * branches.
+ *
+ * It lives in the RUNNER, not in a generator, for two reasons. It is a model-level
+ * observation, so it must fire exactly ONCE per run rather than once per generator that
+ * happens to be wired; and the attribute is equally stale whether or not the generator it
+ * used to suppress is wired at all, so a generator-local check would go quiet in exactly
+ * the project that dropped the generator and kept the attribute.
+ *
+ * Self-extinguishing: removing the attribute from the metadata silences it forever. That
+ * is also the fix, since the same edit is what makes `meta verify` pass.
+ */
+export function warnRetiredCodegenAttrs(
+  entities: readonly MetaObject[],
+  warn: (msg: string) => void,
+): void {
+  for (const { name, replacement } of RETIRED_CODEGEN_ATTRS) {
+    // ADR-0039: resolving — an INHERITED flag suppressed emission exactly as an own one
+    // did, so an own-only read here would leave the inheriting adopter unwarned while
+    // their output silently changed. `hasAttr` rather than a value comparison: an
+    // `@emitForm: true` was a no-op that still fails `meta verify`, so it is just as
+    // stale as the `false` that did something.
+    const carriers = entities.filter((e) => e.hasAttr(name));
+    if (carriers.length === 0) continue;
+    warn(
+      `@${name} on ${carriers.map((e) => e.name).join(", ")} is no longer read by any ` +
+        `generator — it was never registered metamodel vocabulary, so \`meta verify\` ` +
+        `rejects it outright with ERR_UNKNOWN_ATTR. Decide per generator what you ` +
+        `consume: ${replacement}. Remove the attribute to silence this.`,
+    );
+  }
+}