@metaobjectsdev/codegen-ts 0.24.4 → 0.25.0

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;
@@ -31,13 +45,17 @@ export interface RoutesFileHonoOpts {
  */
 export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts): Generator {
   const userFilter = opts?.filter ?? (() => true);
+  // Eligibility, minus the TPH question — stated ONCE so the emit set and the warn set
+  // below cannot drift apart. They differ only by `!isTphSubtype` vs `isTphSubtype`, and
+  // 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 =>
+    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
@@ -46,18 +64,11 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
     // these to a discriminator-aware renderer; the Hono runtime has no discriminator
     // support yet, so this fails CLOSED and the run says so (see the warning below)
     // rather than shipping an artifact that returns the wrong rows.
-    filter: (e: MetaObject) =>
-      e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false
-      && hasAnyRdbSource(e)
-      && !isTphSubtype(e)
-      && userFilter(e),
+    filter: (e: MetaObject) => passesOtherGates(e) && !isTphSubtype(e),
     generate: async (ctx) => {
       // One note per run naming every TPH subtype held back, so the gap is visible at
       // `meta gen` time rather than discovered as missing endpoints in production.
-      const skipped = ctx.entities.filter(
-        (e) => e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false
-          && hasAnyRdbSource(e) && isTphSubtype(e) && userFilter(e),
-      );
+      const skipped = ctx.entities.filter((e) => passesOtherGates(e) && isTphSubtype(e));
       if (skipped.length > 0) {
         ctx.warn(
           `no Hono routes emitted for the TPH subtype(s) ${skipped.map((e) => e.name).join(", ")} — ` +
@@ -79,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";

package/src/index.ts

@@ -37,8 +37,16 @@ export {
 } from "./generator-registry.js";
 export type { GeneratorRegistryEntry, GeneratorTier } from "./generator-registry.js";
 
-export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider, GeneratorSpec, DocsConfig, ResolvedDocsConfig, DocsSurface, ApiSurface } from "./metaobjects-config.js";
+export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider, GeneratorSpec, DocsConfig, ResolvedDocsConfig, DocsSurface, ApiSurface, VerifyConfig } from "./metaobjects-config.js";
 export { defineConfig, normalizeConfig, resolveGenerators, resolveDocsConfig } from "./metaobjects-config.js";
+// The dialect every generator falls back to when a config declares none. Exported because
+// `meta docs` must apply the SAME default `normalizeConfig` does — a command that resolved
+// the dialect differently would document a schema the toolchain does not produce.
+export { DEFAULT_DIALECT } from "./metaobjects-config.js";
+// The runner's own "does this model need a dialect?" guard. `meta docs` must ask it rather
+// than defaulting, because DEFAULT_DIALECT is inert and a DB project with no dialect is one
+// `meta gen` REFUSES — documenting it as sqlite states an answer the toolchain never gave.
+export { dbEmittingObjects, missingDialectMessage } from "./db-emitting.js";
 export { apiLabel } from "./generators/api-label.js";
 
 export type { ColumnSpec, DefaultExpr } from "./column-mapper.js";
@@ -70,7 +78,8 @@ export { decideAndWrite, GitMissingError } from "./overwrite-policy.js";
 export { contentHash, readGeneratedHash, listGeneratedPaths } from "./overwrite-policy.js";
 
 export { CodegenError } from "./errors.js";
-export { GENERATED_HEADER, EXTRA_SUFFIX, DEFAULT_OUT_DIR, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID, CODEGEN_ATTR_EMIT_FORM, CODEGEN_ATTR_EMIT_ROUTES } from "./constants.js";
+export { GENERATED_HEADER, DEFAULT_OUT_DIR, RETIRED_CODEGEN_ATTRS, type RetiredCodegenAttr } from "./constants.js";
+export { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 
 export { formatTs } from "./format.js";
 
@@ -90,14 +99,30 @@ export type { DocPageNode, DocPagePlacement } from "./docs-paths.js";
 export { isProjection, isWriteThrough } from "./projection/projection-detector.js";
 export { isAbstract, emitsInstanceArtifacts, emitsWriteArtifacts } from "./instance-artifacts.js";
 // The UI tier asks THESE — "is there an endpoint?" — never the storage predicates.
-export { servesReadApi, servesWriteApi } from "./api-surface.js";
+export { hasGeneratedForm, restPath, servesReadApi, servesWriteApi } from "./api-surface.js";
+// #356 — every emitter selects a field's view by the SURFACE it renders, never by
+// declaration position. An owned generator (FR-040) composing the render layer must
+// use this too, or it reinstates the order-dependence in its own copy.
+export { viewForContext, VIEW_CONTEXT_FORM, VIEW_CONTEXT_GRID } from "./view-context.js";
+// The shared per-field UI derivation. `valueObjectFor` is the predicate the React form
+// generator and the `agent/ui.md` docs page must both ask — it decides whether a field is
+// rendered as an input at all — and `humanize` is the one body behind every generated
+// label. Both are exported so the react tier reads them rather than keeping a copy.
+export { humanize, inferViewKind, labelFor, currencyMetaFor, valueObjectFor } from "./templates/field-meta.js";
 // The DB-free descriptor module the UI tier imports from (see entity-meta-file.ts).
 export { renderEntityMetaFile, entityMetaFileName, entityMetaSpecifier } from "./templates/entity-meta-file.js";
 // FR-017 TPH helpers — used by the per-framework codegen packages (tanstack,
 // react) to dispatch polymorphic/per-subtype emission and skip subtype files.
 export { isTphDiscriminatorBase, tphConcreteSubtypes, collectTphSubtypeFields, tphPlan, tphRouteSegment } from "./templates/tph-discriminator.js";
 export type { TphPlan, TphSubtypePlan } from "./templates/tph-discriminator.js";
-export { isTphSubtype, tphDiscriminatorPin } from "./templates/zod-validators.js";
+export { isTphSubtype, tphDiscriminatorBase, tphDiscriminatorPin } from "./templates/zod-validators.js";
+
+// The ONE sortability rule. It builds the server-side `<Entity>SortAllowlist` and the
+// client-side sort union, and it is public so a UI-tier generator (a data-grid column
+// emitter, say) marks a column sortable by ASKING the server's rule rather than
+// reimplementing its three branches out of tree. A hand-copied predicate is how the
+// grid came to offer headers the allowlist rejects (#352/#354).
+export { isSortableField, sortableFields } from "./templates/filter-shared.js";
 
 // ADR-0034 reference-template composition helpers. Promoted to the public engine
 // surface so a COPIED reference generator (src/reference/*.ts → consumer's
@@ -110,7 +135,7 @@ export { renderSharedEnumsFile, SHARED_ENUMS_BASENAME } from "./templates/enums-
 
 // ADR-0034 scaffold-and-own — reader for the copyable reference generators in
 // `src/reference/*.ts`. `meta init` uses this to copy them into the consumer's repo.
-export { resolveReferenceRoot, readReferenceTemplate, REFERENCE_GENERATOR_NAMES } from "./reference-templates.js";
+export { resolveReferenceRoot, readReferenceTemplate, REFERENCE_GENERATOR_NAMES, makeReferenceReader } from "./reference-templates.js";
 export type { ReferenceGeneratorName } from "./reference-templates.js";
 
 // ts-poet composition primitives, re-exported from THIS package's own ts-poet
@@ -160,8 +185,27 @@ export { renderFilterType } from "./templates/filter-type.js";
 export { renderFilterAllowlist, renderSortAllowlist } from "./templates/filter-allowlist.js";
 export { renderEntityConstants, resourcePath } from "./templates/entity-constants.js";
 export { renderQueriesFile } from "./templates/queries-file.js";
+// #348 — which CRUD verbs a generated routes file mounts. Public because an OWNED
+// routes generator (ADR-0034) composes the same render call and needs the same option.
+export { CRUD_VERBS, resolveExpose, intersectExpose, exposeLine } from "./routes-expose.js";
+export type { CrudVerb, ExposeOption } from "./routes-expose.js";
 export { renderRoutesFile } from "./templates/routes-file.js";
+export { renderRoutesFileHono } from "./templates/routes-file-hono.js";
 export { renderValueObjectFile } from "./templates/value-object-file.js";
+export { renderNamesDecl } from "./templates/names-decl.js";
+export type { NamesDeclOpts } from "./templates/names-decl.js";
+export {
+  resolveObjectNames,
+  resolveSuperFragmentNames,
+  namesArtifactSuperOf,
+  namesRef,
+  namesConstArg,
+  physicalNameExpr,
+  columnExpr,
+  type ObjectNames,
+  type FieldNames,
+  type SuperNames,
+} from "./names.js";
 export { renderProjectionDecl } from "./templates/projection-decl.js";
 export type { ProjectionDeclOpts } from "./templates/projection-decl.js";
 export { extractViewSpec } from "./projection/extract-view-spec.js";
@@ -210,6 +254,16 @@ export { buildTemplateDocData } from "./generators/template-doc-builder.js";
 // worse than the bug report this is meant to avoid.
 export { requirementTests } from "./generators/requirement-tests.js";
 export { requirementsFile } from "./generators/requirements-file.js";
+// The `agent` docs surface. `AgentSchemaInput` is exported because the CLI SUPPLIES it —
+// codegen-ts deliberately does not compute the physical schema (see agent-schema-input.ts).
+export { agentDocsFile } from "./generators/agent-docs-file.js";
+export type { AgentDocsFileOpts } from "./generators/agent-docs-file.js";
+export type {
+  AgentSchemaInput,
+  SchemaColumnLike,
+  SchemaTableLike,
+  SchemaViewLike,
+} from "./generators/agent-schema-input.js";
 export type { RequirementRow } from "./generators/requirements-view.js";
 // The projection itself, not just its type: it is the authority on WHICH doc slots a
 // requirement surface actually renders, and `meta verify`'s authoring lint tells an
@@ -251,3 +305,7 @@ export type {
   SweepOrphansArgs,
   SweepOrphansResult,
 } from "./orphan-sweep.js";
+
+// FR-040 §6.4 — the client-component directive for generated CLIENT artifacts.
+// Public so an OWNED generator applies it the same way the built-ins do.
+export { withClientDirective, CLIENT_DIRECTIVE } from "./client-directive.js";

package/src/metaobjects-config.ts

@@ -55,6 +55,14 @@ export interface ResolvedGenConfig {
    *  api-docs reads this to AUTO-DETECT whether to document the Hono CRUD surface
    *  (it otherwise mirrors the default Fastify-only suite). Undefined ⇒ false. */
   includeHonoRoutes?: boolean;
+  /** §A6 — whether the OPT-IN names generator (namesFile) is active in the run,
+   *  aggregated by the runner from the suite's `emitsNames` markers. A generator that
+   *  wants to REFERENCE `<Entity>Names` reads this to know the artifact will exist:
+   *  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.
+   *  Undefined ⇒ false. Templates read the same fact off `RenderContext.includeNames`,
+   *  which the runner sets from this same aggregation. */
+  includeNames?: boolean;
   /**
    * FR-019 / ADR-0026: the module specifier from which an externally-PROVIDED
    * shared enum (`@provided: true` on an abstract package-level `field.enum`) is
@@ -108,6 +116,34 @@ export interface MetaobjectsGenConfig extends Omit<ResolvedGenConfig, "dbImport"
    * (e.g. `{ AuditLog: "auditLog", LlmTierConfig: "llmTierConfig" }`).
    */
   collectionNameOverrides?: Record<string, string>;
+  /**
+   * Prepend a module-level client-component directive — `"use client";` — to every
+   * generated CLIENT artifact (forms, hooks, grid columns, grid hooks). Defaults to
+   * `false`. FR-040 §6.4.
+   *
+   * **Why this is config and not a metadata attribute.** It is a fact about the
+   * adopter's BUNDLER TOPOLOGY, not about the entity — the metamodel contains nothing
+   * that could derive it, and every non-TS port would carry a registration it can never
+   * dispatch on, which is the `source.rdb @role` mistake that retired four members in
+   * 0.21.0. It sits here beside `extStyle` and `columnNamingStrategy` for the same
+   * reason `pluralizeCollections` does: a per-port codegen concern (ADR-0001), so
+   * config, and no cross-port conformance cost.
+   *
+   * **Why it defaults to `false`.** The generated form and hook modules genuinely ARE
+   * client components, so the directive is a true statement about them — but it is only
+   * REQUIRED by frameworks that compile server and client from one tree (React Server
+   * Components). Elsewhere it is inert and provokes module-level-directive warnings in
+   * some bundlers, so defaulting it on would put noise in every generated UI file for
+   * the majority to save the minority one line. The asymmetry that would argue for
+   * defaulting on — a runtime error for RSC adopters versus a build warning for
+   * everyone else — is what FR-040 itself removed: before it, an RSC adopter had no
+   * seam at all; now it is this flag, or `meta eject form` and a one-line prepend.
+   *
+   * Flipping the default needs EVIDENCE, not a guess about majorities — the standard
+   * `extStyle` was held to in 0.20.1, where the default moved because the documented
+   * quickstart provably failed under a stock `tsc --init`.
+   */
+  clientDirective?: boolean;
   /**
    * Drizzle timestamp column mode. "string" (default) types timestamp columns as
    * ISO-8601 strings (matches the generated Zod + cross-port wire contract); "date"
@@ -143,6 +179,9 @@ export interface MetaobjectsGenConfig extends Omit<ResolvedGenConfig, "dbImport"
   emitAbstractShapes?: boolean;
   /** Docs-output config consumed by the `meta docs` door. See {@link DocsConfig}. */
   docs?: DocsConfig;
+  /** `meta verify` / `meta gen` advisory settings. Nothing here affects codegen.
+   *  See {@link VerifyConfig}. */
+  verify?: VerifyConfig;
   /** Named output destinations. Generators reference one via `target`. */
   targets?: Record<string, TargetConfig>;
   /** importBase for the default target (top-level outDir). */
@@ -186,13 +225,14 @@ export interface NormalizedMetaobjectsGenConfig
   pluralizeCollections: boolean;
   collectionNameOverrides: Record<string, string>;
   timestampMode: "date" | "string";
+  clientDirective: boolean;
   apiPrefix: string;
   emitAbstractShapes: boolean;
   outputLayout: OutputLayout;
   targets: Record<string, ResolvedTarget>;
 }
 
-export type DocsSurface = "model" | "api" | "requirements";
+export type DocsSurface = "model" | "api" | "requirements" | "agent";
 
 export interface ApiSurface {
   lang: string;
@@ -203,6 +243,33 @@ export interface ApiSurface {
 /** The single docs-output config: where ALL doc surfaces go, how pages are laid
  *  out, and which surfaces to emit. Read by the `meta docs` door (and, when the
  *  api surface fans out, by each port's docs command). */
+/**
+ * `meta verify` settings. Nothing here changes what codegen emits.
+ *
+ * This block existed once before, for `verify.testFiles`, and was removed in 0.24.0 with
+ * the `@verifiedBy` vocabulary it served. It returns for exactly the reason it was added:
+ * the advisory scans carry a list of conventions that is, unavoidably, a guess about
+ * someone else's repository. Built-in defaults for the layouts that demonstrably exist,
+ * PLUS a project-declared list, is the shape that survives being wrong.
+ */
+export interface VerifyConfig {
+  /**
+   * Path globs the "you hand-rolled what MetaObjects models" advisory skips entirely.
+   * Relative to the project root, forward-slash, `**` spans separators; a glob matching a
+   * directory prunes the whole subtree. ADDS to the built-in exclusions rather than
+   * replacing them.
+   *
+   *   verify: { antiPatternIgnore: ["db/changelog/**", "vendor/sql/**"] }
+   *
+   * Reach for this when the advisory reports a file you cannot act on — a vendored SQL
+   * archive, read-only reference DDL, a migration tool whose naming the built-ins do not
+   * recognise. It is deliberately narrower than `--no-antipatterns`: silencing the whole
+   * scan to quiet one directory is how a useful advisory gets switched off wholesale, the
+   * same failure `--no-requirement-lint` was carved out to avoid.
+   */
+  antiPatternIgnore?: string[];
+}
+
 export interface DocsConfig {
   outDir?: string;
   layout?: OutputLayout;
@@ -235,7 +302,15 @@ export function resolveDocsConfig(
     // files for a project declaring no `requirement.*` node — not an empty page. A
     // project without a ledger sees byte-identical output to before the surface
     // existed; see requirements-file.ts.
-    surfaces: cli.surfaces ?? block?.surfaces ?? ["model", "api", "requirements"],
+    //
+    // `agent` defaults ON for the same reason and under the same discipline: each of
+    // its three pages renders "" when its tier has nothing to describe, and an empty
+    // render emits no file. It is additionally gated on a loadable gen config, exactly
+    // as `api` is — physical names, the dialect and view dispatch all come from there,
+    // so without one there is nothing true to say. Turning it on by default is what
+    // makes the always-on agent-context pointer able to name the files: a pointer to a
+    // page an adopter has to opt into is a pointer at nothing.
+    surfaces: cli.surfaces ?? block?.surfaces ?? ["model", "api", "requirements", "agent"],
     apiSurfaces: cli.apiSurfaces ?? block?.apiSurfaces ?? [{ lang: "ts", subDir: "api" }],
   };
 }
@@ -322,6 +397,7 @@ export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobj
     // normalize to "string" on sqlite/D1 at this one choke point so the option
     // can never silently emit a non-compiling column + a disagreeing Zod schema.
     timestampMode: dialect === "sqlite" ? "string" : (config.timestampMode ?? "string"),
+    clientDirective: config.clientDirective ?? false,
     apiPrefix: config.apiPrefix ?? "",
     emitAbstractShapes: config.emitAbstractShapes ?? true,
     outputLayout: config.outputLayout ?? "flat",