@metaobjectsdev/codegen-ts 0.24.4 → 0.25.0

package/src/reference/routes.ts

@@ -6,15 +6,26 @@
 // 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:       Fastify. The emitted file imports `mountCrudRoutes` from
+//                `@metaobjectsdev/runtime-ts/drizzle-fastify` and binds a
+//                module-singleton `db`. THIS is the file to retarget for another HTTP
+//                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,
@@ -29,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;
 }
 
@@ -45,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,37 +13,77 @@ 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", "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 the reference root iff it holds the entity reference template. */
-function isReferenceRoot(dir: string): boolean {
-  return existsSync(join(dir, "entity.ts"));
+/** A directory is a reference root iff it holds the first template the reader was told to expect. */
+function isReferenceRoot(dir: string, sentinel: string): boolean {
+  return existsSync(join(dir, `${sentinel}.ts`));
 }
 
 /**
- * Resolve the `src/reference/` directory holding the copyable reference generators.
- * Works in dev (this module runs from `src/`, templates at `./reference/`) and in a
- * published install (this module runs from `dist/`, templates at `../src/reference/`,
- * since `src/` ships alongside `dist/`). Walks up checking both layouts at each level.
+ * FR-040 §4.1 — build a reference-template reader for ONE package. `moduleUrl` is the
+ * calling module's `import.meta.url`, so each package resolves its OWN `src/reference/`.
+ * `names[0]` is the sentinel that identifies the directory.
+ *
+ * Works in dev (module runs from `src/`, templates at `./reference/`) and in a published
+ * install (module runs from `dist/`, templates at `../src/reference/`, since `src/` ships
+ * alongside `dist/`). Walks up checking both layouts at each level.
  */
-export function resolveReferenceRoot(): string {
-  let dir = dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 8; i++) {
-    for (const candidate of [join(dir, "reference"), join(dir, "src", "reference")]) {
-      if (isReferenceRoot(candidate)) return candidate;
+export function makeReferenceReader(moduleUrl: string, names: readonly [string, ...string[]]) {
+  // A non-empty tuple type, so `names[0]` is `string` outright — this used to need a
+  // runtime empty-check plus a re-bound const, because `noUncheckedIndexedAccess`
+  // narrowing does not survive into the closures below. Every call site already passes
+  // an `as const` tuple or an array literal, so the type costs nothing and deletes both.
+  const sentinel: string = names[0];
+
+  function resolveReferenceRoot(): string {
+    let dir = dirname(fileURLToPath(moduleUrl));
+    for (let i = 0; i < 8; i++) {
+      for (const candidate of [join(dir, "reference"), join(dir, "src", "reference")]) {
+        if (isReferenceRoot(candidate, sentinel)) return candidate;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
     }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
+    throw new Error(
+      "reference templates not found — looked for `reference/` and `src/reference/` " +
+        `walking up from ${dir}.`,
+    );
   }
-  throw new Error(
-    "codegen-ts reference templates not found — looked for `reference/` and `src/reference/` " +
-      "walking up from the codegen-ts module.",
-  );
+
+  return {
+    resolveReferenceRoot,
+    /**
+     * Read one template by name. The name is checked against `names` FIRST: this is a
+     * public export, so `name` is an untrusted `string` at runtime (the per-package
+     * wrappers narrow to a literal union, but types are erased). Without the check it
+     * interpolates straight into a path, so any caller threading a CLI argument through
+     * reads whatever file the string points at. The allowlist is already a parameter —
+     * enforcing it here makes the guarantee structural instead of something every call
+     * site has to remember, and it is the reason `meta eject` needs no check of its own.
+     */
+    readReferenceTemplate: (name: string): string => {
+      if (!names.includes(name)) {
+        throw new Error(
+          `unknown reference template "${name}". Available: ${names.join(", ")}.`,
+        );
+      }
+      return readFileSync(join(resolveReferenceRoot(), `${name}.ts`), "utf8");
+    },
+  };
+}
+
+// This package's own reader — the back-compatible named exports `meta init` uses.
+const ownReader = makeReferenceReader(import.meta.url, REFERENCE_GENERATOR_NAMES);
+
+/** Resolve the `src/reference/` directory holding this package's reference generators. */
+export function resolveReferenceRoot(): string {
+  return ownReader.resolveReferenceRoot();
 }
 
 /** Read the raw source of one reference generator (e.g. `"entity"` → the text of `entity.ts`). */
 export function readReferenceTemplate(name: ReferenceGeneratorName): string {
-  return readFileSync(join(resolveReferenceRoot(), `${name}.ts`), "utf8");
+  return ownReader.readReferenceTemplate(name);
 }

package/src/render-context.ts

@@ -52,12 +52,29 @@ export interface RenderContext {
    * doc comment on `MetaobjectsGenConfig.timestampMode` in metaobjects-config.ts.
    */
   timestampMode: "date" | "string";
+  /**
+   * Prepend `"use client";` to generated CLIENT artifacts (forms, hooks, grid
+   * columns, grid hooks). Defaults to false. A bundler-topology fact the adopter
+   * declares — see `MetaobjectsGenConfig.clientDirective` for why it is config
+   * rather than metadata, and why the default is off. FR-040 §6.4.
+   */
+  clientDirective: boolean;
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix: string;
   /** Whether abstract entities emit their shape artifact (type-only interface / value-object file). Defaults to true. Instance/write artifacts are never emitted for abstract entities regardless. */
   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
@@ -101,14 +118,16 @@ 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" | "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;
   timestampMode?: "date" | "string";
+  clientDirective?: boolean;
   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.
@@ -184,9 +203,11 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     // a unit test or a generator invoked outside `runGen`, must get the same
     // safe-no-op guarantee). See MetaobjectsGenConfig.timestampMode's doc comment.
     timestampMode: opts.dialect === "sqlite" ? "string" : (opts.timestampMode ?? "string"),
+    clientDirective: opts.clientDirective ?? false,
     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.`,
+    );
+  }
+}

package/src/routes-expose.ts

@@ -0,0 +1,86 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+
+/**
+ * The five CRUD verbs a generated routes file can mount.
+ *
+ * Mirrors `CrudVerb` in `@metaobjectsdev/runtime-ts` — both the fastify and hono mount
+ * modules declare it identically. It is RESTATED rather than imported because codegen-ts
+ * does not depend on runtime-ts: codegen emits a call to that helper, it never links
+ * against it. Pinned against both runtime declarations by test/routes-expose.test.ts, so
+ * the two cannot drift the way the cell-renderer keys drifted from the view registry.
+ */
+export const CRUD_VERBS = ["list", "get", "create", "update", "delete"] as const;
+
+/**
+ * The verbs a TPH discriminator BASE serves at its own path.
+ *
+ * Read-only BY CONSTRUCTION: the discriminated union has no single writable shape, so the
+ * base mount can never carry `create`/`update`/`delete` — an author-supplied `expose`
+ * INTERSECTS with this set rather than replacing it, and may narrow to just `list`.
+ * Writes live on the per-subtype mounts at `<base path>/<segment>`.
+ *
+ * Named here because two places need it and a second literal would be a second answer:
+ * `routes-file.ts` emits the mount, and `api-model.ts` documents it. They disagreed —
+ * the api surface documented POST/PATCH/DELETE on a base path that serves none, under a
+ * comment claiming the documented paths "match the generated routes exactly".
+ */
+export const TPH_POLYMORPHIC_VERBS = ["list", "get"] as const;
+export type CrudVerb = (typeof CRUD_VERBS)[number];
+
+/**
+ * Which CRUD verbs a generated routes file mounts (#348).
+ *
+ * A `filter` cannot express this. `filter` decides whether the file emits AT ALL, per
+ * entity, so it can only remove the whole surface; restricting to a SUBSET of verbs is a
+ * different axis. That is why this is a generator option rather than the "narrow it with
+ * `filter`" remedy that answered the retired `@emit*` attributes — the same reasoning that
+ * made a TPH subtype's opt-IN grid `tphSubtypeGrids` rather than a filter.
+ *
+ * It is deliberately NOT metadata. Which verbs a deployment exposes is a property of the
+ * app, not of the model: the same entity is read-only in one service and writable in
+ * another, and an attribute would force one answer into the shared spine.
+ *
+ * Absent — or a function returning `undefined` for an entity — means all five, and emits
+ * output byte-identical to before this option existed.
+ */
+export type ExposeOption =
+  | readonly CrudVerb[]
+  | ((entity: MetaObject) => readonly CrudVerb[] | undefined);
+
+/** Resolve the option for one entity. `undefined` means "mount all five". */
+export function resolveExpose(
+  entity: MetaObject,
+  expose: ExposeOption | undefined,
+): readonly CrudVerb[] | undefined {
+  if (expose === undefined) return undefined;
+  return typeof expose === "function" ? expose(entity) : expose;
+}
+
+/**
+ * Narrow a mount whose verb set is already fixed by construction.
+ *
+ * A TPH polymorphic mount is read-only (`["list", "get"]`) because the discriminated union
+ * has no single writable shape. An author-supplied `expose` may narrow that further but
+ * must never widen it, so this INTERSECTS rather than replaces: mounting `create` on a
+ * surface that cannot serve it would emit a route that fails at runtime, and a wrong
+ * endpoint is worse than a missing one.
+ */
+export function intersectExpose(
+  fixed: readonly CrudVerb[],
+  requested: readonly CrudVerb[] | undefined,
+): readonly CrudVerb[] {
+  if (requested === undefined) return fixed;
+  const want = new Set<string>(requested);
+  return fixed.filter((v) => want.has(v));
+}
+
+/**
+ * The `expose: [...]` line for a mount call, or "" when every verb mounts.
+ *
+ * Emitting nothing rather than the full list keeps output byte-identical for every
+ * project that does not use the option.
+ */
+export function exposeLine(verbs: readonly CrudVerb[] | undefined, indent: string): string {
+  if (verbs === undefined) return "";
+  return `\n${indent}expose: [${verbs.map((v) => JSON.stringify(v)).join(", ")}],`;
+}

package/src/runner.ts

@@ -1,4 +1,6 @@
 import { join, relative, resolve, isAbsolute, dirname } from "node:path";
+import { warnMissingPromptGenerators } from "./prompt-generator-gate.js";
+import { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { existsSync, readFileSync } from "node:fs";
@@ -6,6 +8,7 @@ import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
 import { isMetaRoot, OBJECT_SUBTYPE_VALUE, FIELD_SUBTYPE_TIMESTAMP, FIELD_ATTR_FILTERABLE } from "@metaobjectsdev/metadata";
 import { assignEmittedNames } from "./naming/collision-names.js";
 import { isAbstract } from "./instance-artifacts.js";
+import { dbEmittingObjects, missingDialectMessage } from "./db-emitting.js";
 import { hasAnyRdbSource } from "./source-detect.js";
 import type { Generator, GenContext, EmittedFile } from "./generator.js";
 import type { MetaobjectsGenConfig } from "./metaobjects-config.js";
@@ -127,6 +130,50 @@ function engineVersion(): string | undefined {
   }
 }
 
+/** The release in which `$apiPrefix` left the generated entity descriptor. */
+const BASE_URL_MOVE_VERSION = "0.25.0";
+
+/** `N.N.N` only. Anything else — a prerelease tag, a sentinel — is deliberately unordered. */
+function orderable(v: string | undefined): [number, number, number] | undefined {
+  if (v === undefined) return undefined;
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v);
+  return m === null ? undefined : [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * True exactly on the FIRST gen after upgrading past the release that moved the API base
+ * URL out of the entity descriptor, and only for a project that actually had a prefix to
+ * move. Exported for test.
+ *
+ * Keyed on the #232 engine stamp rather than on `apiPrefix` alone so the note is
+ * self-extinguishing: whether the app passed `baseUrl` to its provider is runtime code
+ * `meta gen` cannot see, so a prefix-only trigger would nag for ever with no way to
+ * satisfy it — the cry-wolf failure that got the `timestampMode` warning deleted from
+ * this file (see `codegen-ts-tanstack/src/data-grid-gate.ts`).
+ *
+ * Silence is the default for an absent or unorderable recorded version. That is the
+ * OPPOSITE call to the 0.24.5 agent-context staleness nudge, and deliberately: there an
+ * unknown version meant "cannot prove it is fresh, so nudge"; here it means "no gen
+ * history, so nothing to migrate", and a false nag costs more than a missed one when the
+ * compile break already routes the adopter to the same line.
+ */
+export function shouldNoteBaseUrlMove(
+  apiPrefix: string,
+  recordedEngine: string | undefined,
+  moveVersion: string = BASE_URL_MOVE_VERSION,
+): boolean {
+  if (apiPrefix === "") return false;
+  const was = orderable(recordedEngine);
+  const move = orderable(moveVersion);
+  if (was === undefined || move === undefined) return false;
+  for (let i = 0; i < 3; i++) {
+    const a = was[i] as number;
+    const b = move[i] as number;
+    if (a !== b) return a < b;
+  }
+  return false;
+}
+
 export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   const warnings: string[] = [];
   const strategy = opts.mergeStrategy ?? "overwrite";
@@ -259,16 +306,9 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // projects — the error even told them their model "generates database code"
   // that in fact imported nothing. It is demanded below at the point of USE, by
   // the generator that reads it, which the runner names in the thrown message.
-  const dbEmittingObjects = safeEntities.filter(
-    (e) => !e.isAbstract && hasAnyRdbSource(e),
-  );
-  if (dbEmittingObjects.length > 0 && opts.config.dialect === undefined) {
-    const names = dbEmittingObjects.map((e) => e.name).join(", ");
-    throw new Error(
-      `codegen config is missing dialect — required because this model ` +
-        `generates database code for: ${names}. Set dialect in ` +
-        `metaobjects.config.ts. (A model of only value objects and/or sourceless projections may omit it.)`,
-    );
+  const dbEmitting = dbEmittingObjects(safeEntities);
+  if (dbEmitting.length > 0 && opts.config.dialect === undefined) {
+    throw new Error(missingDialectMessage(dbEmitting));
   }
 
   /** Did the AUTHOR declare a dbImport reachable by this target? Tracked, never
@@ -281,6 +321,19 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // 2. Resolve targets + entity-module target.
   const config = normalizeConfig(opts.config);
 
+  // The compile break (`value` → `fetcher` on the provider) sends an adopter to the right
+  // line; this names the value to put there, once, for the projects that had one.
+  if (shouldNoteBaseUrlMove(config.apiPrefix, recordedEngine)) {
+    warnings.push(
+      `apiPrefix ${JSON.stringify(config.apiPrefix)} no longer reaches the client — ` +
+        `generated hooks and services emit entity-relative paths. Supply it once at the ` +
+        `provider: <EntityFetcherProvider fetcher={...} baseUrl=${JSON.stringify(config.apiPrefix)}> ` +
+        `(Angular: provideEntityFetcher({ fetcher, baseUrl: ${JSON.stringify(config.apiPrefix)} })). ` +
+        `Server routes still mount under apiPrefix and are unaffected. ` +
+        `See docs/features/migrations/api-base-url-leaves-the-entity-descriptor.md`,
+    );
+  }
+
   // (Historical: a warning stood here for a @filterable timestamp under
   // timestampMode:"date", which used to throw at REQUEST time in runtime-ts's
   // filter parser. That limitation is fixed — the generated allowlist now carries
@@ -366,6 +419,36 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // CRUD surface it actually emits (rather than silently omitting it).
   const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
 
+  // §A6 — same auto-detection for the OPT-IN names generator. The entity tier may only
+  // REFERENCE `<Entity>Names` when something in this run actually emits it; the names
+  // generator is opt-in under ADR-0034 (meta gen runs the adopter's own copies), so an
+  // unconditional import would break every project that has not added it. Surfaced BOTH
+  // on ctx.config (the field reference/names.ts documents, and the shape a third-party
+  // generator reads) and on every RenderContext below (what the templates can actually
+  // see) — one aggregation, two consumers.
+  //
+  // Scoped BY TARGET, unlike includeHonoRoutes, because the two flags are read for
+  // different reasons: api-docs asks "is this surface in the run?", while a template
+  // referencing these constants emits a RELATIVE import at its own target's path. The
+  // names artifact is not a registered cross-target module (there is no importBase route
+  // to it), so `entityFile({ target: "db" })` beside a default-target `namesFile()` would
+  // otherwise emit `./<Entity>.names` from a directory that does not hold one.
+  const namesTargets = new Set(
+    config.generators.filter((g) => g.emitsNames === true).map((g) => targetOf(g).name),
+  );
+
+  // A declared template.prompt with no prompt generator wired emits nothing and, before
+  // this, said nothing — while `meta verify` reported the template "clean". See
+  // prompt-generator-gate.ts. Self-extinguishing; warning only.
+  warnMissingPromptGenerators(root, config.generators, (m) => warnings.push(m));
+
+  // A retired `@emit*` codegen flag still sitting in the metadata suppresses nothing now.
+  // Named here rather than left to be discovered as a file that reappeared. Scoped to
+  // the run's own entity set (the same set every generator sees), so `meta gen <entity>`
+  // reports on what it just generated rather than on objects it was told to skip.
+  // See retired-codegen-attrs.ts. Self-extinguishing; warning only.
+  warnRetiredCodegenAttrs(safeEntities, (m) => warnings.push(m));
+
   // 4. Run each generator with a per-target render context; collect with full path.
   const emitted: { fullPath: string; content: string; generatedBy: string }[] = [];
   // FR-038 §8 — generators that opted into orphan reconciliation, paired with the
@@ -411,9 +494,11 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       pluralizeCollections: config.pluralizeCollections,
       collectionNameOverrides: config.collectionNameOverrides,
       timestampMode: config.timestampMode,
+      clientDirective: config.clientDirective,
       apiPrefix: config.apiPrefix,
       emitAbstractShapes: config.emitAbstractShapes,
       outputLayout: selfTarget.outputLayout,
+      includeNames: namesTargets.has(selfTarget.name),
       pkMap,
       relationMap,
       packageOf,
@@ -433,6 +518,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         dialect: config.dialect,
         outputLayout: selfTarget.outputLayout,
         includeHonoRoutes,
+        includeNames: namesTargets.has(selfTarget.name),
       },
       renderContext,
       ...(projectRoot !== undefined && { projectRoot }),
@@ -463,7 +549,11 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       files = await generator.generate(ctx);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(`[${generator.name}] ${msg}`);
+      // `cause` preserves the original throw. Without it a `runGen` caller sees a
+      // plain Error carrying only the prefixed message, so it cannot tell a
+      // CodegenError (a metadata/config problem it can report) from a genuine bug
+      // in a generator, and every stack trace stops at this line.
+      throw new Error(`[${generator.name}] ${msg}`, { cause: err });
     }
 
     for (const file of files) {
@@ -537,6 +627,34 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         `Refused to overwrite ${w.path}: ${w.conflictHint ?? "content differs and could not be verified as generated."}`,
       );
     }
+
+    // The recovery, ONCE — for the same reason the no-manifest branch above aggregates:
+    // it is the same three commands whether one file refused or sixteen, and repeating
+    // it per file buries it.
+    //
+    // It is stated as a SEQUENCE rather than a menu because there is exactly one way to
+    // keep an edit here and it is not obvious: a three-way merge needs a base, the
+    // `.gen-state` bodies are gitignored, and this machine has none — so the base has to
+    // be manufactured first. `--baseline=fresh` writes fresh output AND seeds the missing
+    // snapshot; restoring the file from git then puts the edit back with a base now
+    // present, and the next run merges it. Verified end to end (refused → overwrite →
+    // merged, edit intact).
+    //
+    // Two remedies were removed from the per-file hint and are not restored here as
+    // universal advice. "Move the edit into a non-generated file" holds only where the
+    // edit CAN live elsewhere — a `requirementTests()` stub's body cannot, because the
+    // test name is the link to the requirement and the stub's own header forbids renaming
+    // it. "--baseline=fresh" alone is a discard, and is named as one.
+    warnings.push(
+      `To KEEP your version of the file(s) above, the edit must be committed first — ` +
+      `then: 'meta gen --baseline=fresh' (writes fresh output over them and seeds the ` +
+      `missing .gen-state snapshot), 'git checkout -- <paths>' to bring your version back, ` +
+      `then 'meta gen' again — the snapshot now exists, so the edit merges. ` +
+      `To DISCARD your version instead, '--baseline=fresh' on its own is the whole answer. ` +
+      `Moving the edit into a non-generated file works only where the edit can live outside ` +
+      `the generated one; a requirementTests() stub's body cannot, since the test name is ` +
+      `its link to the requirement.`,
+    );
   };
 
   const sweep = (dryRun: boolean): void => {