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

package/src/generators/api-model.ts

@@ -35,7 +35,7 @@
 //                        (templates/routes-file-hono.ts) — the OPT-IN Hono variant
 //                        of the Fastify REST surface. Documented ONLY when the
 //                        adopter wires routesFileHono() (ctx.includeHonoRoutes), and
-//                        gated by the SAME @emitRoutes:false filter.
+//                        gated by the SAME source + TPH rules as the Fastify surface.
 //   • template.prompt (T5):
 //       - prompt       : render<Name> (payload, provider): string — the prompt
 //                        render handle promptRender() emits into a single
@@ -75,10 +75,17 @@
 //     / update<Sub>ById / delete<Sub>ById scoped to the shared table) and the
 //     subtype REST subpaths are NOT YET documented by this builder — that fuller
 //     TPH modeling is a tracked follow-up (under-documentation, allowed).
-//   • @emitRoutes:false entities → the routes generator filters them out
-//     (routes-file.ts: ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false), so they get
-//     NO REST symbols here. The queries + validator generators do NOT honor
-//     @emitRoutes, so data-access + validation symbols still apply.
+//
+// NOT modelled here (stated so the gap is known + intentional): a generator's own
+// `filter` option. `routesFile({ filter })` narrows what the routes generator emits,
+// and this builder reads the MODEL, not the wired generator set, so it cannot see
+// that narrowing and will over-document REST for a filtered-out entity. That is
+// under-documentation's opposite and it is a real limitation — but it is inherent to
+// a docs pass that runs off metadata, and it applies equally to every generator's
+// filter. (It used to be dodged for routes ALONE via an @emitRoutes:false metadata
+// read; that attribute was never registered vocabulary, so `meta verify` rejected the
+// very models this builder was reading it from. The read is gone — see
+// constants.ts.)
 
 import {
   type MetaRoot,
@@ -112,8 +119,7 @@ import { isTphSubtype } from "../templates/zod-validators.js";
 import { isTphDiscriminatorBase } from "../templates/tph-discriminator.js";
 import { isCallableEntity } from "../templates/callable-file.js";
 import { hasAnyRdbSource } from "../source-detect.js";
-import { CODEGEN_ATTR_EMIT_ROUTES } from "../constants.js";
-import { resourcePath } from "../templates/entity-constants.js";
+import { servedPath } from "../api-surface.js";
 import { isProjection } from "../projection/projection-detector.js";
 import { buildPkMap } from "../pk-resolver.js";
 import { buildRelationMap, type RelationEntry, type RelationMap } from "../relation-resolver.js";
@@ -263,6 +269,12 @@ export interface ApiModelContext {
    *  run didn't configure). The Fastify REST surface is always documented (it is
    *  the default-suite routes generator). Defaults to false. */
   includeHonoRoutes?: boolean;
+  /** The project's `apiPrefix`. Every generated route is mounted inside
+   *  `fastify.register(…, { prefix: apiPrefix })`, so it is part of the address a
+   *  documented endpoint is served at — a page that omits it is one path segment
+   *  short. Threaded explicitly rather than read off the RenderContext below,
+   *  which is a `{ pkMap }` shim and carries nothing else. Defaults to "". */
+  apiPrefix?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -275,13 +287,14 @@ export function buildApiModel(root: MetaRoot, ctx: ApiModelContext): ApiModel {
   // shim is sufficient (and avoids forcing callers to build a full context).
   const pkCtx = { pkMap } as RenderContext;
   const layout = ctx.outputLayout ?? "flat";
+  const apiPrefix = ctx.apiPrefix ?? "";
   const relationMap = ctx.relationMap ?? buildRelationMap(root);
   const includeHono = ctx.includeHonoRoutes ?? false;
 
   const units: ApiUnitDoc[] = [];
 
   for (const obj of root.objects()) {
-    units.push(buildEntityUnit(obj, pkCtx, root, layout, relationMap, includeHono));
+    units.push(buildEntityUnit(obj, pkCtx, root, layout, relationMap, includeHono, apiPrefix));
   }
 
   for (const tmpl of templateOutputs(root)) {
@@ -353,15 +366,6 @@ function isQueryable(obj: MetaObject): boolean {
   return hasAnyRdbSource(obj) && !isTphSubtype(obj);
 }
 
-/** Whether the routes generator emits REST routes for this entity. It filters
- *  out @emitRoutes:false (routes-file.ts:27), unlike the queries + validator
- *  generators which always emit. So REST symbols are gated separately from the
- *  other queryable kinds. */
-function emitsRoutes(obj: MetaObject): boolean {
-  // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
-  return obj.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false;
-}
-
 function buildEntityUnit(
   obj: MetaObject,
   ctx: RenderContext,
@@ -369,6 +373,7 @@ function buildEntityUnit(
   layout: OutputLayout,
   relationMap: RelationMap,
   includeHono: boolean,
+  apiPrefix: string,
 ): ApiUnitDoc {
   const name = obj.name;
   const symbols: ApiSymbol[] = [];
@@ -392,13 +397,15 @@ function buildEntityUnit(
   if (isQueryable(obj)) {
     symbols.push(...dataAccessSymbols(obj, ctx, root, layout));
     symbols.push(...validationSymbols(obj, entityMod));
-    // REST is additionally gated: @emitRoutes:false suppresses routes only.
-    if (emitsRoutes(obj)) {
-      symbols.push(...restSymbols(obj, layout));
-      // The OPT-IN Hono variant mounts the SAME CRUD verbs under the SAME
-      // @emitRoutes filter — documented only when the adopter wired it.
-      if (includeHono) symbols.push(...restHonoSymbols(obj, layout));
-    }
+    // REST needs no gate of its own: the routes generator's built-in filter is
+    // `hasAnyRdbSource && !isTphSubtype` — exactly isQueryable — so every queryable
+    // object gets routes. (Its `filter` option can narrow that further; this builder
+    // reads the model, not the wired generator set, and cannot see it. See the module
+    // header.)
+    symbols.push(...restSymbols(obj, layout, root, apiPrefix));
+    // The OPT-IN Hono variant mounts the SAME CRUD verbs under the same rules —
+    // documented only when the adopter wired it.
+    if (includeHono) symbols.push(...restHonoSymbols(obj, layout, apiPrefix));
   }
 
   // --- relation: the drizzle relations() export, when the resolver derives a
@@ -565,15 +572,35 @@ function validationSymbols(obj: MetaObject, entityMod: string): ApiSymbol[] {
  * generator does NOT emit one function per verb — it emits a single
  * `<name>Routes(fastify)` handler that mounts the standard CRUD verb set at the
  * entity's $path via mountCrudRoutes (or the read-only subset via
- * mountReadOnlyCrudRoutes for a projection). We reuse resourcePath() — the same
- * function entity-constants.ts uses to compute $path — so the documented paths
- * match the generated routes exactly. The verb→path mapping mirrors the runtime
- * mountCrudRoutes contract referenced in routes-file.ts's comments.
+ * mountReadOnlyCrudRoutes for a projection). The verb→path mapping mirrors the
+ * runtime mountCrudRoutes contract referenced in routes-file.ts's comments.
+ *
+ * THE DOCUMENTED PATH IS THE ADDRESS THE ROUTES ACTUALLY SERVE, which takes two
+ * things this comment used to claim it got from one. It said it reused
+ * `resourcePath()` — "the same function entity-constants.ts uses to compute
+ * $path" — and both halves of that had stopped being true:
+ *
+ *   • `$path` is `restPath()` now, not `resourcePath()`. A TPH subtype is mounted
+ *     at `<base>/<segment>`, so `resourcePath` named an address nothing serves —
+ *     the defect fixed for `$path` itself, still live here.
+ *   • Every mount sits inside `fastify.register(…, { prefix: apiPrefix })`, so a
+ *     project configuring "/api" was documented one path segment short.
+ *
+ * A TPH DISCRIMINATOR BASE serves only `TPH_POLYMORPHIC_VERBS` at its own path, and that
+ * set is imported rather than restated. `isProjection` alone was the read-only test, so a
+ * base — which is not a projection — was documented with POST/PATCH/DELETE against a mount
+ * `routes-file.ts` builds as `intersectExpose(TPH_POLYMORPHIC_VERBS, expose)`: three verbs
+ * that 404, published in the file an adopter is told to call generated code from, under the
+ * comment three lines above claiming these paths match the routes exactly. The per-subtype
+ * mounts at `<base path>/<segment>`, which is where writes actually live, remain a
+ * documented deferral (see the module header).
  */
-function restSymbols(obj: MetaObject, layout: OutputLayout): ApiSymbol[] {
+function restSymbols(
+  obj: MetaObject, layout: OutputLayout, root: MetaRoot, apiPrefix: string,
+): ApiSymbol[] {
   const name = obj.name;
-  const path = resourcePath(obj);
-  const readOnly = isProjection(obj);
+  const path = servedPath(obj, apiPrefix);
+  const readOnly = isProjection(obj) || isTphDiscriminatorBase(obj, root);
 
   // REST endpoints are not importable functions — to WIRE them an adopter
   // imports the entity's route registrar (`<entity>Routes`) from the routes
@@ -776,13 +803,15 @@ function callableArgsRef(obj: MetaObject, root: MetaRoot): string | undefined {
 /**
  * The OPT-IN Hono CRUD registrar `register<Entity>Routes(app, deps)` the
  * routesFileHono generator emits into `<Entity>.routes.hono.ts`. Parallels the
- * Fastify restSymbols (same verb set, same resourcePath, read-only for
+ * Fastify restSymbols (same verb set, same served address, read-only for
  * projections) but carries the Hono registrar name + import module. Documented
  * only when the adopter opts into the Hono variant (includeHonoRoutes).
  */
-function restHonoSymbols(obj: MetaObject, layout: OutputLayout): ApiSymbol[] {
+function restHonoSymbols(
+  obj: MetaObject, layout: OutputLayout, apiPrefix: string,
+): ApiSymbol[] {
   const name = obj.name;
-  const path = resourcePath(obj);
+  const path = servedPath(obj, apiPrefix);
   const readOnly = isProjection(obj);
 
   const honoMod = entityModulePath(layout, obj, `${name}.routes.hono`);

package/src/generators/callable-file.ts

@@ -33,7 +33,7 @@ export const callableFile = function callableFile(opts?: CallableFileOpts): Gene
           entity.package,
           `${entity.name}.callable.ts`,
         ),
-        content: await formatTs(renderCallableFile(entity)),
+        content: await formatTs(renderCallableFile(entity, ctx.renderContext)),
       };
     }),
   };

package/src/generators/docs-data-builder.ts

@@ -4,6 +4,7 @@
 // markdown structure now lives in templates/docs/entity-page.md.mustache.
 
 import {
+  type MetaData,
   type MetaObject,
   type MetaField,
   type MetaIdentity,
@@ -699,17 +700,60 @@ export function buildEntityDocData(
   //
   // ENTITY-GRAIN. Object coverage is entity-grain, so a claimed value/projection gets
   // nothing — surfacing one would imply a coverage rule the ledger does not have.
+  //
+  // "Entity-grain" is about which PAGE the row lands on, NOT about how deep the claim may
+  // point. A claim is authored at whatever grain the requirement is really about, and an L5
+  // one names a MEMBER — `acme::Subscriber.status` in the shipped showcase. `walkRequirements`
+  // resolves that to the FIELD node, so an identity test against `entity` missed it and the
+  // showcase's only claim produced no "Required by" at all. The claim belongs on the owning
+  // entity's page either way: that is where a reader looks, and the member is named in the row
+  // rather than being the reason the row disappears.
+  //
+  // Hence: match the claimed node OR any ANCESTOR of it up to and including this entity. The
+  // walk stops AT the entity, so a claim on some other object's member cannot reach this page
+  // by climbing past its own root.
+  const memberPathTo = (target: MetaData): string | undefined => {
+    const segments: string[] = [];
+    for (let n: MetaData | undefined = target; n !== undefined; n = n.parent) {
+      if (n === entity) return segments.length > 0 ? segments.reverse().join(".") : "";
+      segments.push(n.name);
+    }
+    return undefined;   // not under this entity at all
+  };
+  /** Dotted-path depth. "" is the entity itself — depth 0, not the 1 a naive split gives. */
+  const memberDepth = (path: string): number => (path === "" ? 0 : path.split(".").length);
   const claimedByMatches: UsedByDoc[] = [];
   if (entity.subType === OBJECT_SUBTYPE_ENTITY) {
     for (const walked of walkRequirements(root)) {
-      if (!walked.targets.some((t) => t.node === entity)) continue;
+      // The SHALLOWEST member path among this requirement's targets that lands on this
+      // entity: "" for an entity-grain claim, "status" for an L5 member claim. undefined
+      // when no target is under this entity.
+      let member: string | undefined;
+      let memberD = Number.POSITIVE_INFINITY;
+      for (const t of walked.targets) {
+        const path = memberPathTo(t.node);
+        if (path === undefined) continue;
+        const d = memberDepth(path);
+        // Shallowest by SEGMENT COUNT, not string length. `path.length` made "a.b" — two
+        // segments, three characters — beat "status", one segment and six, so the row
+        // named the deeper member. Ties break lexicographically so the page does not
+        // depend on the order the requirement walk happens to return targets in.
+        if (member === undefined || d < memberD || (d === memberD && path < member)) {
+          member = path;
+          memberD = d;
+        }
+      }
+      if (member === undefined) continue;
       const v = walked.view;
       const level = v.level === undefined ? "" : ` · **L${v.level}**`;
       const status = v.status === undefined ? "" : ` · status: \`${v.status}\``;
       const statement = walked.node.attr(REQUIREMENT_ATTR_STATEMENT);
       const said = typeof statement === "string" && statement.length > 0 ? ` — ${statement}` : "";
+      // A member-grain claim says WHICH member, so the row is actionable rather than
+      // merely present. An entity-grain claim renders exactly as before (byte-identical).
+      const on = member === "" ? "" : ` · on \`${member}\``;
       claimedByMatches.push({
-        bullet: `\`requirement.${v.subType} ${v.path}\`${level}${status}${said}`,
+        bullet: `\`requirement.${v.subType} ${v.path}\`${level}${status}${on}${said}`,
       });
     }
   }

package/src/generators/docs-data.ts

@@ -264,9 +264,13 @@ export interface EntityDocData {
    *  BYTE-IDENTICAL to its pre-feature output. That is the no-churn contract:
    *  a project with no ledger, or an entity nothing claims, must see no diff.
    *
-   *  ENTITY-GRAIN ONLY. Object coverage is entity-grain (`spec/capability-ledger.md`),
+   *  ENTITY PAGES ONLY. Object coverage is entity-grain (`spec/capability-ledger.md`),
    *  so a claimed `object.value` / `object.projection` gets nothing here — surfacing
-   *  one would imply a coverage rule the ledger does not actually have. */
+   *  one would imply a coverage rule the ledger does not actually have.
+   *
+   *  That governs which PAGE a row lands on, not how deep the CLAIM may point: an L5
+   *  claim names a member, resolves to the FIELD, and still renders on the owning
+   *  entity's page with the member named in the row (`· on \`status\``). */
   claimedBy?: UsedByDoc[];
   /** Present-and-non-empty flag for the claimedBy section. */
   hasClaimedBy?: boolean;

package/src/generators/index.ts

@@ -1,20 +1,22 @@
-// ADR-0034 scaffold-and-own — these built-in generator factories remain the engine's
-// internal composers, but importing them from `@metaobjectsdev/codegen-ts/generators`
-// into a consumer's `metaobjects.config.ts` is DEPRECATED. The recommended path is to
-// own copyable reference templates in your repo (`meta init` scaffolds them into
-// `codegen/generators/*.ts`) and import those locally. This package export will be
-// removed in a future major. See spec/decisions/ADR-0034-codegen-scaffold-and-own.md.
+// Built-in generator factories.
+//
+// ADR-0034 scaffold-and-own — `entityFile`, `queriesFile`, `routesFile` and `barrel` were
+// exported here and DEPRECATED; 1.0 REMOVED them (ADR-0035 A3, `docs/1.0-readiness.md` G2,
+// `docs/features/migrations/0.x-to-1.0.md` §11). Own a copy instead: `meta init` scaffolds
+// them into `codegen/generators/*.ts` and `meta eject <name>` copies one at any time. They
+// remain in this directory as the engine's internal composers and as the oracle the
+// byte-identity gate holds each reference template to — they are no longer public API.
+//
+// The factories BELOW are not deprecated and this subpath is their supported public home:
+// the prompt/output tier (`promptRender`, `outputParser`, `outputPrompt`, `extractor`,
+// `renderHelper`, `traceHelperFile`) is upstream-owned and has no ownable copy — the CLI's
+// own prompt-gate warning names this import path — and `routesFileHono` / `namesFile` /
+// `callableFile` are stock generators a consumer wires directly.
+// See spec/decisions/ADR-0034-codegen-scaffold-and-own.md.
 
-/** @deprecated ADR-0034 — own a copy instead: `import { entityFile } from "./codegen/generators/entity"` (scaffolded by `meta init`). */
-export { entityFile, type EntityFileOpts } from "./entity-file.js";
-/** @deprecated ADR-0034 — own a copy instead: `import { queriesFile } from "./codegen/generators/queries"` (scaffolded by `meta init`). */
-export { queriesFile, type QueriesFileOpts } from "./queries-file.js";
 export { callableFile, type CallableFileOpts } from "./callable-file.js";
-/** @deprecated ADR-0034 — own a copy instead: `import { routesFile } from "./codegen/generators/routes"` (scaffolded by `meta init`). */
-export { routesFile, type RoutesFileOpts } from "./routes-file.js";
 export { routesFileHono, type RoutesFileHonoOpts } from "./routes-file-hono.js";
-/** @deprecated ADR-0034 — own a copy instead: `import { barrel } from "./codegen/generators/barrel"` (scaffolded by `meta init`). */
-export { barrel, type BarrelOpts } from "./barrel.js";
+export { namesFile } from "./names-file.js";
 /** @deprecated ADR-0021 D1 — neutral artifact owned by `meta docs` (ADR-0020); not part of the recommended `meta gen` suite. */
 export { mermaidErDiagram, type MermaidErOptions } from "./mermaid-er.js";
 export { promptRender, type PromptRenderOpts } from "./prompt-render-file.js";
@@ -50,6 +52,15 @@ export { buildTemplateDocData } from "./template-doc-builder.js";
 // behaviour composes its own generator instead of filing an issue here.
 export { requirementTests } from "./requirement-tests.js";
 export { requirementsFile } from "./requirements-file.js";
+// The `agent` docs surface — internal engine of `meta docs --agent`, like docsFile()
+// and apiDocsFile(). Not a `meta gen` config generator.
+export { agentDocsFile, type AgentDocsFileOpts } from "./agent-docs-file.js";
+export type {
+  AgentSchemaInput,
+  SchemaColumnLike,
+  SchemaTableLike,
+  SchemaViewLike,
+} from "./agent-schema-input.js";
 export type { RequirementRow } from "./requirements-view.js";
 export type {
   RequirementTestsOpts,

package/src/generators/names-file.ts

@@ -0,0 +1,98 @@
+import type { Generator, GenContext, EmittedFile } from "../generator.js";
+import { entityOutputPath, crossEntitySpecifier } from "../import-path.js";
+import { renderNamesDecl } from "../templates/names-decl.js";
+import { namesArtifactSuperOf, resolveObjectNames } from "../names.js";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+
+/**
+ * §A1/§A2/§A6 — `<Entity>Names`: the physical database names for one object, as constants a
+ * hand-written consumer references instead of a string literal.
+ *
+ * This is the built-in twin of `src/reference/names.ts` (ADR-0034 scaffold-and-own —
+ * `meta init` copies the reference file into the adopter's repo; this one stays the
+ * engine's internal composer and the reference-byte-identical gate's other half). Same
+ * `generate` body; only the import paths differ (relative package-internal here, the
+ * public `@metaobjectsdev/codegen-ts` barrel there).
+ *
+ * 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.
+ */
+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);
+          // `fragment` says "this is an ancestor render", not which shape to render:
+          // `renderNamesDecl` derives that from the object itself, so a TPH base reached
+          // by this walk keeps the shared table it owns. Deciding it there rather than
+          // here is what makes the EJECTED copy of this generator correct too.
+          const content = renderNamesDecl(sup, {
+            strategy, superSpecifier: superSpecifierFor(sup), fragment: true,
+          });
+          if (content === "") continue;
+          out.push({ path: pathOf(sup), content });
+        }
+      }
+      return out;
+    },
+  };
+}

package/src/generators/requirements-markdown.ts

@@ -86,14 +86,48 @@ function renderOne(r: RequirementRow): string {
  * The generator keys on that to emit no file at all, which is in turn what lets the
  * surface default to on without changing output for any project lacking a ledger.
  */
-export function renderRequirementsMarkdown(rows: readonly RequirementRow[]): string {
+export interface RequirementsMarkdownOpts {
+  /**
+   * Render the ledger as a SECTION of a larger page rather than as the page.
+   *
+   * The `agent/requirements.md` surface carries this ledger under its own `## The ledger`
+   * heading, and an embedded copy that keeps its `# Requirements` title gives the page two
+   * H1s and reparents every entry as a sibling of the section that contains it — the
+   * document silently loses its outline. So the title is dropped and every heading moves
+   * down one level.
+   *
+   * A POST-HOC REGEX OVER THIS FUNCTION'S OUTPUT would do the same thing and would be the
+   * wrong shape: heading depth is this renderer's decision (it already caps at h6), and a
+   * caller rewriting it from outside would have to re-derive that cap and would drift from
+   * it the next time this file changes.
+   */
+  readonly embedded?: boolean;
+}
+
+export function renderRequirementsMarkdown(
+  rows: readonly RequirementRow[],
+  opts?: RequirementsMarkdownOpts,
+): string {
   if (rows.length === 0) return "";
 
+  const body = rows.map(renderOne);
+  if (opts?.embedded === true) {
+    return [
+      `${rows.length} declared requirement${rows.length === 1 ? "" : "s"}, in declaration order.`,
+      "",
+      // One extra `#` on every heading line, capped at h6 exactly as `heading()` caps.
+      ...body.map((entry) =>
+        entry.replace(/^(#{1,6}) /gm, (_m, hashes: string) =>
+          `${"#".repeat(Math.min(hashes.length + 1, 6))} `,
+        ),
+      ),
+    ].join("\n");
+  }
   return [
     "# Requirements",
     "",
     `${rows.length} declared requirement${rows.length === 1 ? "" : "s"}, in declaration order.`,
     "",
-    ...rows.map(renderOne),
+    ...body,
   ].join("\n");
 }

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

@@ -4,11 +4,21 @@ import { renderRoutesFileHono } from "../templates/routes-file-hono.js";
 import { hasAnyRdbSource } from "../source-detect.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
-import { CODEGEN_ATTR_EMIT_ROUTES } from "../constants.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
+import { resolveExpose, type ExposeOption } from "../routes-expose.js";
 
 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;
 }
 
@@ -22,8 +32,12 @@ export interface RoutesFileHonoOpts {
  * consumers running Hono can replace hand-written route registration with
  * this generator output one entity at a time.
  *
- * Per-entity opt-out via `@emitRoutes: false` is honored. If the user
- * supplies their own filter, both must pass (AND).
+ * If the user supplies their own filter, it AND-composes with the built-in gates.
+ *
+ * Decide per generator what you consume: wire only the generators whose output you
+ * actually import, and narrow this one with its `filter` option. There is no `@emit*`
+ * metadata attribute — those were never registered vocabulary, so `meta verify` rejects
+ * them (ERR_UNKNOWN_ATTR).
  *
  * #248 R2: an object with no declared/inherited source.rdb (of ANY kind) isn't
  * backed by any store — gated by `hasAnyRdbSource` (does NOT add TPH handling;
@@ -36,17 +50,12 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
   // written out twice a later edit to one silently makes an entity either stop emitting
   // without being named as held back, or get warned about while still emitting.
   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
@@ -81,7 +90,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/generators/routes-file.ts

@@ -5,16 +5,30 @@ import { isTphSubtype } from "../templates/zod-validators.js";
 import { hasAnyRdbSource } from "../source-detect.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
-import { CODEGEN_ATTR_EMIT_ROUTES } from "../constants.js";
+import { resolveExpose, type ExposeOption } from "../routes-expose.js";
 
 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;
 }
 
 /**
- * Per-entity opt-out via `@emitRoutes: false` is honored. If the user supplies
- * their own filter, both must pass (AND).
+ * If the user supplies their own filter, it AND-composes with the built-in gates.
+ *
+ * Decide per generator what you consume: wire only the generators whose output you
+ * actually import, and narrow this one with its `filter` option. There is no `@emit*`
+ * metadata attribute — those were never registered vocabulary, so `meta verify` rejects
+ * them (ERR_UNKNOWN_ATTR).
  *
  * #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
@@ -27,17 +41,16 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
   const userFilter = opts?.filter ?? (() => true);
   const generator: Generator = {
     name: "routes-file",
-    // Always set: AND-composes metadata opt-out with optional user filter.
+    // Always set: AND-composes the built-in gates with the optional user filter.
     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/generators/template-generator.ts

@@ -5,13 +5,27 @@
 // generators; just adds the "Mustache template" + "walk that yields a
 // data dict per output" primitives.
 //
-// Design line we adopted (from the design doc):
-//   Code → hand-coded generators (ts-poet, idiomatic per-port).
-//   Documents → templateGenerator (shared Mustache templates).
+// SUPERSEDED, and left here as a correction because the old line still circulates:
+// the original 2026-05-28 split was "Code → hand-coded generators, Documents →
+// templateGenerator", with code emission an explicit NON-GOAL for this primitive.
+// SP-1 (docs/superpowers/specs/2026-06-28-mustache-codegen-parity-design.md §2)
+// moved past it — its goal is a consumer authoring "a working code generator, on ANY
+// port, with NO generator code", and its worked outputPattern is
+// "{package}/{name}Service.java". Source, not a document.
 //
-// docsFile() is the first templateGenerator instance (rc.12). OpenAPI specs,
-// Mermaid diagrams, HTML doc sites, etc. follow as templates + a walk
-// function each.
+// The axis is NOT what kind of file comes out. It is: pick a template when the output
+// SHAPE is what you are iterating on, or when you want the same output across
+// languages (that is what the neutral data dict buys); pick a hand-coded generator
+// when the logic is gnarly or the run is hot. Tradeoff table:
+// docs/features/codegen-concepts.md §3.
+//
+// This matters most where a port has no choice: C# and Python expose closed built-in
+// generator registries, so the declarative spec is the ONLY consumer authoring path
+// there — and a documents-only reading of this primitive would tell those adopters
+// their port cannot emit a custom shape at all.
+//
+// docsFile() is the first templateGenerator instance (rc.12), which is why the
+// documents framing stuck; it is the first instance, not the boundary.
 
 import type { MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
 import { render, type Provider, type RenderFormat } from "@metaobjectsdev/render";