@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/generators/trace-helper-file.ts

@@ -0,0 +1,301 @@
+// server/typescript/packages/codegen-ts/src/generators/trace-helper-file.ts
+//
+// Stock generator that emits one <Entity>.trace.ts helper file for each concrete
+// entity that (a) extends LlmCallBase (directly or transitively) and (b) nests a
+// template.prompt with @payloadRef and/or @responseRef.
+//
+// The emitted helper exports an async function `record<Entity>(om, responseMo, input)`
+// that EXTRACTS the typed response VO itself and persists ONE row = base envelope +
+// raw I/O (via buildLlmCallRow) PLUS the typed voRequest/voResponse columns. The
+// helper is typed against the generated payload interfaces (request + response VOs)
+// so call-sites get compile-time checks.
+//
+// NOTE: ObjectManager does not expose its loaded metadata root, so the caller must
+// pass the resolved `responseMo: MetaObject` explicitly.  The generated helper
+// documents this in its JSDoc.
+//
+// Consumer wiring (metaobjects.config.ts):
+//   generators: [..., entityFile(), queriesFile(), traceHelperFile(), barrel()]
+
+import {
+  TYPE_OBJECT,
+  TYPE_TEMPLATE,
+  TEMPLATE_SUBTYPE_PROMPT,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_RESPONSE_REF,
+  TEMPLATE_ATTR_FORMAT,
+  TEMPLATE_ATTR_TEXT_REF,
+} from "@metaobjectsdev/metadata";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import {
+  type EmittedFile,
+  type Generator,
+  type GeneratorFactory,
+  perEntity,
+} from "../generator.js";
+import { generatePayloadInterfacesBatch } from "../payload-codegen.js";
+import { GENERATED_HEADER } from "../constants.js";
+import { tphDiscriminatorPin } from "../templates/zod-validators.js";
+
+/** Short name of the shipped abstract base every trace entity extends. */
+const LLM_CALL_BASE = "LlmCallBase";
+
+export interface TraceHelperOpts {
+  /** Output directory prefix relative to the target's outDir. Default: "" (root). */
+  outDir?: string;
+  /** Optional named output target (registry key). Defaults to "default". */
+  target?: string;
+}
+
+/** Walk the super chain looking for a node named LLM_CALL_BASE. */
+function extendsBase(obj: MetaObject): boolean {
+  let cur = obj.superResolved;
+  while (cur !== undefined) {
+    if (cur.name === LLM_CALL_BASE) return true;
+    cur = cur.superResolved;
+  }
+  return false;
+}
+
+/** Capitalise the first character. */
+function pascal(s: string): string {
+  return s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s;
+}
+
+export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts): Generator {
+  const dirPrefix = opts?.outDir ? `${opts.outDir.replace(/\/$/, "")}/` : "";
+  const generator: Generator = {
+    name: "trace-helper",
+    generate: perEntity((entity, ctx) => {
+      // Only concrete entities derived from LlmCallBase.
+      if (entity.isAbstract) return [];
+      if (!extendsBase(entity)) return [];
+
+      // Find the nested template.prompt.
+      const prompt = entity.ownChildren().find(
+        (c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_PROMPT,
+      );
+      if (prompt === undefined) return [];
+
+      const payloadRef = prompt.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+      const responseRef = prompt.ownAttr(TEMPLATE_ATTR_RESPONSE_REF);
+
+      // @responseRef types the result; @payloadRef types the request. Both gate
+      // the helper: the entity must declare voRequest/voResponse field.object
+      // columns (authored) for these writes to land, and the prompt's refs name
+      // the VOs to render/extract into.
+      if (typeof responseRef !== "string") return [];
+      if (typeof payloadRef !== "string") return [];
+
+      const entityName = entity.name;
+      const fnName = `record${pascal(entityName)}`;
+
+      // STI: a trace entity that is a TPH subtype stamps its declared
+      // discriminator value as callType and drops callType from the caller input
+      // (industry-standard STI — the discriminator is framework-managed).
+      const tphPin = tphDiscriminatorPin(entity);
+      const sti = tphPin !== undefined;
+      const callTypeValue = sti ? tphPin.value : entityName;
+
+      // Emitted record<Entity> fragments. The caller never supplies the derived
+      // status/errorDetail (the helper computes them from extraction), and an STI
+      // subtype additionally drops the framework-managed callType discriminator.
+      const recordInputOmit = sti
+        ? `"llmRequest" | "status" | "errorDetail" | "callType"`
+        : `"llmRequest" | "status" | "errorDetail"`;
+      // The object spread passed to buildLlmCallRow: STI subtypes stamp their
+      // discriminator value, all helpers fold in the derived status/errorDetail.
+      const recordBuildArg = sti
+        ? `{ ...input, callType: ${JSON.stringify(callTypeValue)}, status, errorDetail }`
+        : `{ ...input, status, errorDetail }`;
+
+      // Derive the parse format from the prompt's @format attr.
+      // "xml" → Format.XML; absent or any other value → Format.JSON.
+      const promptFormat = prompt.ownAttr(TEMPLATE_ATTR_FORMAT);
+      const formatLiteral = typeof promptFormat === "string" && promptFormat.toLowerCase() === "xml"
+        ? "Format.XML"
+        : "Format.JSON";
+
+      // Collect VO names for interface emission (dedupe via batch emitter).
+      // Both refs are guaranteed strings by the guards above.
+      const interfaces = generatePayloadInterfacesBatch(ctx.loadedRoot, [payloadRef, responseRef]);
+
+      const requestType = payloadRef;
+
+      // A renderable prompt (carries @textRef) gets an additional call<Entity> helper
+      // that renders the prompt text, calls the LLM, then parses + persists a trace row.
+      const textRef = prompt.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+      const renderable = typeof textRef === "string";
+      // Same @format attr, two intentionally different shapes: extract() takes the
+      // Format enum (formatLiteral, above → Format.XML/Format.JSON), render() takes the
+      // raw format string (renderFormat, here → e.g. "json"/"xml", default "text").
+      const renderFormat = typeof promptFormat === "string" ? promptFormat : "text";
+
+      // Build the import block — all imports MUST stay at the top of the emitted file.
+      // `extract` + `render` both live in @metaobjectsdev/render: import them together
+      // (one de-duplicated statement) when the prompt is renderable, else import only
+      // `extract`.
+      const importLines: string[] = [
+        `import type { ObjectManager } from "@metaobjectsdev/runtime-ts";`,
+        `import {`,
+        `  LlmCallDbRecorder,`,
+        `  buildLlmCallRow,`,
+        `  persistLlmCallRow,`,
+        `  extractSchemaFor,`,
+        `  Format,`,
+        `  type LlmCallInput,`,
+        `  type LlmCallRow,`,
+        `} from "@metaobjectsdev/runtime-ts";`,
+        renderable
+          ? `import { extract, render, type Provider } from "@metaobjectsdev/render";`
+          : `import { extract } from "@metaobjectsdev/render";`,
+        `import type { MetaObject } from "@metaobjectsdev/metadata";`,
+      ];
+      if (renderable) {
+        importLines.push(
+          `import {`,
+          `  runLlmCall,`,
+          `  type RunLlmCallInput,`,
+          `  type RunLlmCallDeps,`,
+          `  type LlmClient,`,
+          `  type LlmRequest,`,
+          `  type CostFn,`,
+          `  type Clock,`,
+          `  type IdGen,`,
+          `} from "@metaobjectsdev/ai-runtime";`,
+        );
+      }
+
+      const lines: string[] = [
+        `// ${GENERATED_HEADER} — DO NOT EDIT.`,
+        ``,
+        ...importLines,
+        ``,
+        `// ---- Payload interfaces (inlined) ------------------------------------------`,
+        ``,
+        interfaces.trimEnd(),
+        ``,
+        `// ---- Typed result -----------------------------------------------------------`,
+        ``,
+        `export interface ${entityName}TraceResult {`,
+        `  status: "ok" | "error";`,
+        `  errorDetail: string | null;`,
+        `  /** Parsed response VO, or null when extraction reported a lost-required field. */`,
+        `  /** Note: voResponse is the plain extracted record typed as the response shape (structural, not an instance). */`,
+        `  voResponse: ${responseRef} | null;`,
+        `}`,
+        ``,
+        `// ---- Record helper ----------------------------------------------------------`,
+        ``,
+        `/**`,
+        ` * Record a single ${entityName} LLM call: extract the response VO and persist a`,
+        ` * trace row via ObjectManager regardless of whether extraction succeeded.`,
+        ` *`,
+        ` * @param om         - ObjectManager wired to the application database.`,
+        ` * @param responseMo - MetaObject for \`${responseRef}\` (resolve via the loaded`,
+        ` *                     metadata root: \`root.findObject("${responseRef}")\`).`,
+        ` *                     Passed explicitly because ObjectManager does not expose`,
+        ` *                     its loaded metadata root.`,
+        ` * @param input      - LLM call inputs; type \`llmRequest\` as \`${requestType}\`.`,
+        ` * @param opts       - Optional \`redact\` hook applied to the row before persist`,
+        ` *                     (scrub PII/secrets on the typed path, same as the generic`,
+        ` *                     recordLlmCall/callLlm helpers).`,
+        ` */`,
+        `export async function ${fnName}(`,
+        `  om: ObjectManager,`,
+        `  responseMo: MetaObject,`,
+        `  input: Omit<LlmCallInput, ${recordInputOmit}> & { llmRequest: ${requestType} },`,
+        `  opts?: { redact?: (row: LlmCallRow) => LlmCallRow },`,
+        `): Promise<${entityName}TraceResult> {`,
+        `  const schema = extractSchemaFor(responseMo, ${formatLiteral});`,
+        `  const outcome = extract(input.llmResponseText, schema);`,
+        `  const failed = outcome.report.hasLostRequired();`,
+        `  const status = failed ? ("error" as const) : ("ok" as const);`,
+        '  const errorDetail = failed ? `lost required: ${outcome.report.lostRequired().join(", ")}` : null;',
+        `  const base = buildLlmCallRow(${recordBuildArg});`,
+        `  const row = { ...base, voRequest: input.llmRequest, voResponse: failed ? null : outcome.data };`,
+        `  await persistLlmCallRow(new LlmCallDbRecorder(om, "${entityName}"), row, opts?.redact ? { redact: opts.redact } : undefined);`,
+        `  return { status, errorDetail, voResponse: failed ? null : (outcome.data as ${responseRef}) };`,
+        `}`,
+        ``,
+      ];
+
+      if (renderable) {
+        const callFn = `call${pascal(entityName)}`;
+        lines.push(
+          ``,
+          `// ---- Call helper (GENERATE -> CALL -> record) -------------------------------`,
+          ``,
+          `export interface ${entityName}CallDeps {`,
+          `  om: ObjectManager;`,
+          `  responseMo: MetaObject;`,
+          `  client: LlmClient;`,
+          `  /** Prompt-TEXT resolver for render() (NOT the LLM client). */`,
+          `  provider: Provider;`,
+          `  model: string;`,
+          `  system?: string;`,
+          `  params?: Record<string, unknown>;`,
+          `  cost?: CostFn;`,
+          `  clock?: Clock;`,
+          `  ids?: IdGen;`,
+          `  traceId?: string;`,
+          `  parentSpanId?: string;`,
+          `  sessionId?: string;`,
+          `  /** Optional row-redaction hook applied before persist (scrub PII/secrets). */`,
+          `  redact?: (row: LlmCallRow) => LlmCallRow;`,
+          `}`,
+          ``,
+          `/**`,
+          ` * Render the ${entityName} prompt, call the LLM, then parse + persist a trace`,
+          ` * row (finally-style: a call/parse failure still writes a row).`,
+          ` */`,
+          `export async function ${callFn}(`,
+          `  payload: ${requestType},`,
+          `  deps: ${entityName}CallDeps,`,
+          `): Promise<${entityName}TraceResult> {`,
+          `  const prompt = render({ ref: ${JSON.stringify(textRef)}, payload, format: ${JSON.stringify(renderFormat)}, provider: deps.provider });`,
+          // Build request/input/deps conditionally so that an absent optional (T |
+          // undefined) is never assigned to an optional T? property — required for
+          // exactOptionalPropertyTypes-strict consumer projects.
+          `  const request: LlmRequest = { prompt, model: deps.model };`,
+          `  if (deps.system !== undefined) request.system = deps.system;`,
+          `  if (deps.params !== undefined) request.params = deps.params;`,
+          `  const runInput: RunLlmCallInput = { callType: ${JSON.stringify(callTypeValue)}, request };`,
+          `  if (deps.traceId !== undefined) runInput.traceId = deps.traceId;`,
+          `  if (deps.parentSpanId !== undefined) runInput.parentSpanId = deps.parentSpanId;`,
+          `  if (deps.sessionId !== undefined) runInput.sessionId = deps.sessionId;`,
+          `  const runDeps: RunLlmCallDeps = { client: deps.client };`,
+          `  if (deps.cost !== undefined) runDeps.cost = deps.cost;`,
+          `  if (deps.clock !== undefined) runDeps.clock = deps.clock;`,
+          `  if (deps.ids !== undefined) runDeps.ids = deps.ids;`,
+          `  const { input: recInput, completion } = await runLlmCall(runInput, runDeps);`,
+          `  let voResponse: ${responseRef} | null = null;`,
+          `  let status = recInput.status;`,
+          `  let errorDetail = recInput.errorDetail;`,
+          `  if (completion !== undefined) {`,
+          `    const outcome = extract(completion.body, extractSchemaFor(deps.responseMo, ${formatLiteral}));`,
+          `    if (outcome.report.hasLostRequired()) {`,
+          `      status = "error";`,
+          '      errorDetail = `lost required: ${outcome.report.lostRequired().join(", ")}`;',
+          `    } else {`,
+          `      voResponse = outcome.data as ${responseRef};`,
+          `    }`,
+          `  }`,
+          `  const row = { ...buildLlmCallRow({ ...recInput, status, errorDetail }), voRequest: payload, voResponse };`,
+          `  await persistLlmCallRow(new LlmCallDbRecorder(deps.om, ${JSON.stringify(entityName)}), row, deps.redact ? { redact: deps.redact } : undefined);`,
+          `  return { status, errorDetail, voResponse };`,
+          `}`,
+        );
+      }
+
+      return [{
+        path: `${dirPrefix}${entityName}.trace.ts`,
+        content: lines.join("\n"),
+      }];
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<TraceHelperOpts>;

package/src/index.ts

@@ -9,8 +9,17 @@ export type { RunGenOpts, RunGenResult } from "./runner.js";
 export type { Generator, GenContext, EmittedFile, GeneratorFactory } from "./generator.js";
 export { perEntity, oncePerRun } from "./generator.js";
 
-export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider } from "./metaobjects-config.js";
-export { defineConfig, normalizeConfig } from "./metaobjects-config.js";
+// ADR-0021 D3 — stable-name generator registry + discoverability surface.
+export {
+  generatorRegistry,
+  listGenerators,
+  getGenerator,
+} 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 { defineConfig, normalizeConfig, resolveGenerators, resolveDocsConfig } from "./metaobjects-config.js";
+export { apiLabel } from "./generators/api-label.js";
 
 export type { ColumnSpec, DefaultExpr } from "./column-mapper.js";
 export { mapColumnType } from "./column-mapper.js";
@@ -34,7 +43,7 @@ export type {
 export { decideAndWrite, GitMissingError } from "./overwrite-policy.js";
 
 export { CodegenError } from "./errors.js";
-export { GENERATED_HEADER, EXTRA_SUFFIX, DEFAULT_OUT_DIR } from "./constants.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 { formatTs } from "./format.js";
 
@@ -42,9 +51,49 @@ export { pluralize, columnNameFromField, tableNameFromEntity, viewNameFromProjec
 
 export { packageToPath, entityOutputPath, crossEntitySpecifier, barrelEntrySpecifier, relativeModuleSpecifier, entityModuleSpecifier, siblingSpecifier, barrelModuleSpecifier } from "./import-path.js";
 export type { OutputLayout, ResolvedTarget } from "./import-path.js";
+export {
+  docPageOutputPath,
+  docPageHref,
+  docPageNode,
+  effectivePackage,
+  assertNoDuplicateDocPaths,
+} from "./docs-paths.js";
+export type { DocPageNode, DocPagePlacement } from "./docs-paths.js";
 
 export { isProjection, isWriteThrough } from "./projection/projection-detector.js";
 export { isAbstract, emitsInstanceArtifacts, emitsWriteArtifacts } from "./instance-artifacts.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";
+
+// Built-in template render functions — the composition seam for adopters who
+// want to call a built-in template, then post-process / append to its output
+// from their own Generator (added to `generators: [...]`) WITHOUT forking the
+// template. Mirrors the `renderZodValidators` export. Each is also reachable via
+// a dedicated subpath (e.g. `@metaobjectsdev/codegen-ts/templates/entity-file`).
+export { renderEntityFile } from "./templates/entity-file.js";
+export type { RenderEntityFileOpts } from "./templates/entity-file.js";
+export { renderZodValidators } from "./templates/zod-validators.js";
+export { renderDrizzleSchema } from "./templates/drizzle-schema.js";
+export {
+  renderInferredTypes,
+  renderEnumTypeAliases,
+  renderValueObjectInterface,
+  enumUnionAliasName,
+  enumUnionString,
+} from "./templates/inferred-types.js";
+export { renderBarrel } from "./templates/barrel.js";
+export type { BarrelEntry } from "./templates/barrel.js";
+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";
+export { renderRoutesFile } from "./templates/routes-file.js";
+export { renderValueObjectFile } from "./templates/value-object-file.js";
+export { renderProjectionDecl } from "./templates/projection-decl.js";
+export type { ProjectionDeclOpts } from "./templates/projection-decl.js";
 export { extractViewSpec } from "./projection/extract-view-spec.js";
 export type { ExtractContext } from "./projection/extract-view-spec.js";
 export { emitViewDdl } from "./projection/view-ddl-emit.js";
@@ -74,6 +123,8 @@ export type {
   IdentityDoc,
   RelationshipDoc,
   UsedByDoc,
-  GeneratedFileDoc,
+  ConstraintRow,
 } from "./generators/docs-data.js";
 export { buildEntityDocData } from "./generators/docs-data-builder.js";
+export type { TemplateDocData, TemplateOutputPart } from "./generators/template-doc-data.js";
+export { buildTemplateDocData } from "./generators/template-doc-builder.js";

package/src/metaobjects-config.ts

@@ -2,6 +2,19 @@ import { DEFAULT_COLUMN_NAMING_STRATEGY, type ColumnNamingStrategy, type MetaDat
 import type { Generator } from "./generator.js";
 import type { ExtStyle } from "./render-context.js";
 import type { OutputLayout, ResolvedTarget } from "./import-path.js";
+import { generatorRegistry } from "./generator-registry.js";
+
+/**
+ * A config `generators` entry. Either a typed generator (the primary, fully
+ * typed form — `entityFile()`) OR a STABLE-NAME STRING resolved via the
+ * {@link generatorRegistry} (e.g. `"entity"`). The string form is the
+ * cross-port-consistent selection mechanism (matches C#/Python
+ * `--generators entity,routes`); it always uses the generator's DEFAULT
+ * options. Adopters needing options use the factory form.
+ *
+ * ADR-0021 #1 (TS parity).
+ */
+export type GeneratorSpec = Generator | string;
 
 export type Dialect = "sqlite" | "postgres";
 /** Re-exported from metadata so codegen-ts consumers see one canonical type. */
@@ -29,10 +42,30 @@ export interface ResolvedGenConfig {
   dialect: Dialect;
   /** "flat" (default) — all files in outDir; "package" — files placed in a sub-path derived from each entity's metadata package. */
   outputLayout?: OutputLayout;
+  /** Whether the OPT-IN Hono routes generator (routesFileHono) is active in the
+   *  run — aggregated by the runner from the suite's `emitsHonoRoutes` markers.
+   *  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;
+  /**
+   * FR-019 / ADR-0026: the module specifier from which an externally-PROVIDED
+   * shared enum (`@provided: true` on an abstract package-level `field.enum`) is
+   * imported. metaobjects emits NO type for a provided enum — consuming entity
+   * files `import { <EnumName> } from "<providedEnumModule>"`. The per-port
+   * namespace/module is codegen config, never a metadata attr (ADR-0001). A model
+   * that references a provided enum without this set is a codegen-time error.
+   */
+  providedEnumModule?: string;
 }
 
 export interface MetaobjectsGenConfig extends ResolvedGenConfig {
-  generators: Generator[];
+  /**
+   * Generators to run. Each entry is either a typed generator factory result
+   * (`entityFile()`) or a stable-name string (`"entity"`) resolved via the
+   * registry. Mixed arrays are allowed (`["entity", routesFile()]`). String
+   * entries use the generator's default options. ADR-0021 #1.
+   */
+  generators: GeneratorSpec[];
   /** How field names map to DB column names when @dbColumn is omitted. Defaults to "snake_case". */
   columnNamingStrategy?: ColumnNamingStrategy;
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
@@ -46,6 +79,8 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
    * governs the shape, mirroring the cross-port `emitAbstractShapes` option.
    */
   emitAbstractShapes?: boolean;
+  /** Docs-output config consumed by the `meta docs` door. See {@link DocsConfig}. */
+  docs?: DocsConfig;
   /** Named output destinations. Generators reference one via `target`. */
   targets?: Record<string, TargetConfig>;
   /** importBase for the default target (top-level outDir). */
@@ -63,7 +98,9 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
  *  `targets` is Omitted from the base so it can narrow from the user-facing
  *  TargetConfig to the fully-resolved ResolvedTarget (incompatible under
  *  exactOptionalPropertyTypes otherwise). */
-export interface NormalizedMetaobjectsGenConfig extends Omit<MetaobjectsGenConfig, "targets"> {
+export interface NormalizedMetaobjectsGenConfig extends Omit<MetaobjectsGenConfig, "targets" | "generators"> {
+  /** Fully resolved — every string spec has been mapped to its factory result. */
+  generators: Generator[];
   columnNamingStrategy: ColumnNamingStrategy;
   apiPrefix: string;
   emitAbstractShapes: boolean;
@@ -71,6 +108,50 @@ export interface NormalizedMetaobjectsGenConfig extends Omit<MetaobjectsGenConfi
   targets: Record<string, ResolvedTarget>;
 }
 
+export type DocsSurface = "model" | "api";
+
+export interface ApiSurface {
+  lang: string;
+  subDir: string;
+  baseUrl?: string;
+}
+
+/** 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). */
+export interface DocsConfig {
+  outDir?: string;
+  layout?: OutputLayout;
+  baseUrl?: string;
+  surfaces?: DocsSurface[];
+  apiSurfaces?: ApiSurface[];
+}
+
+export interface ResolvedDocsConfig {
+  outDir: string;
+  layout: OutputLayout;
+  baseUrl: string;
+  surfaces: DocsSurface[];
+  apiSurfaces: ApiSurface[];
+}
+
+/** Merge the config `docs:` block with CLI overrides over documented defaults.
+ *  `fallbackLayout` is the project's `outputLayout` so docs default to the same
+ *  page placement as codegen when `docs.layout` is unset. */
+export function resolveDocsConfig(
+  block: DocsConfig | undefined,
+  cli: Partial<ResolvedDocsConfig>,
+  fallbackLayout: OutputLayout,
+): ResolvedDocsConfig {
+  return {
+    outDir: cli.outDir ?? block?.outDir ?? "./docs",
+    layout: cli.layout ?? block?.layout ?? fallbackLayout,
+    baseUrl: cli.baseUrl ?? block?.baseUrl ?? "",
+    surfaces: cli.surfaces ?? block?.surfaces ?? ["model", "api"],
+    apiSurfaces: cli.apiSurfaces ?? block?.apiSurfaces ?? [{ lang: "ts", subDir: "api" }],
+  };
+}
+
 /** Identity passthrough; exists for IDE type-inference + autocomplete. */
 export function defineConfig(config: MetaobjectsGenConfig): MetaobjectsGenConfig {
   return config;
@@ -102,10 +183,44 @@ export function resolveTargets(config: MetaobjectsGenConfig): Record<string, Res
   return out;
 }
 
+/**
+ * Materialize the config `generators` array: pass typed generators through
+ * untouched and resolve each stable-name string via the {@link generatorRegistry}
+ * to its factory result (default options). ADR-0021 #1.
+ *
+ * Errors:
+ *  - a NEUTRAL name (`docs`, `mermaid-er`) is owned by `meta docs` (ADR-0021 D1)
+ *    and is not selectable in the gen suite.
+ *  - an UNKNOWN name throws listing the available NATIVE names.
+ */
+export function resolveGenerators(specs: readonly GeneratorSpec[]): Generator[] {
+  return specs.map((spec) => {
+    if (typeof spec !== "string") return spec;
+    const entry = generatorRegistry[spec];
+    if (entry === undefined) {
+      const native = Object.values(generatorRegistry)
+        .filter((e) => e.tier === "native")
+        .map((e) => e.name)
+        .sort();
+      throw new Error(
+        `unknown generator "${spec}". Available native generators: ${native.join(", ")}.`,
+      );
+    }
+    if (entry.tier !== "native") {
+      throw new Error(
+        `generator "${spec}" is neutral (owned by 'meta docs'); ` +
+        `not selectable in the gen suite.`,
+      );
+    }
+    return entry.factory();
+  });
+}
+
 /** Apply defaults to a MetaobjectsGenConfig, returning a NormalizedMetaobjectsGenConfig. */
 export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobjectsGenConfig {
   return {
     ...config,
+    generators: resolveGenerators(config.generators),
     columnNamingStrategy: config.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY,
     apiPrefix: config.apiPrefix ?? "",
     emitAbstractShapes: config.emitAbstractShapes ?? true,

package/src/naming.ts

@@ -63,5 +63,53 @@ export function variableNameFromEntity(entityName: string): string {
   return pluralize(toCamelCase(entityName.charAt(0).toLowerCase() + entityName.slice(1)));
 }
 
+// ---------------------------------------------------------------------------
+// Generated CRUD-helper symbol names (single source of truth).
+//
+// The queries generator (templates/queries.ts) emits one exported async function
+// per CRUD verb whose NAME is derived purely from the entity name. These helpers
+// are the canonical spelling of those names so anything that needs to REFER to a
+// generated symbol (e.g. the api-docs ApiModel builder) derives the exact same
+// string the generator emits — no drift, no invented names. The queries template
+// itself uses these so the two can never disagree.
+// ---------------------------------------------------------------------------
+
+/** Generated read-by-PK helper name: `find<Entity>ById`. */
+export function findByIdFnName(entityName: string): string {
+  return `find${entityName}ById`;
+}
+
+/** Generated list helper name: `list<Plural>` (PascalCase plural). */
+export function listFnName(entityName: string): string {
+  return `list${pluralize(entityName)}`;
+}
+
+/** Generated create helper name: `create<Entity>`. */
+export function createFnName(entityName: string): string {
+  return `create${entityName}`;
+}
+
+/** Generated update helper name: `update<Entity>`. */
+export function updateFnName(entityName: string): string {
+  return `update${entityName}`;
+}
+
+/** Generated delete-by-PK helper name: `delete<Entity>ById`. */
+export function deleteByIdFnName(entityName: string): string {
+  return `delete${entityName}ById`;
+}
+
+/**
+ * Generated Fastify route-registrar name: camelCase `<entity>Routes`. The routes
+ * generator (templates/routes-file.ts) emits a single exported
+ * `export async function <entity>Routes(fastify)` that mounts the entity's CRUD
+ * verb set — this is the symbol an adopter imports to wire the endpoints. Kept
+ * here as the single source of truth so the routes template and the api-docs
+ * ApiModel builder derive the exact same spelling (no drift).
+ */
+export function routesHandlerName(entityName: string): string {
+  return `${entityName.charAt(0).toLowerCase()}${entityName.slice(1)}Routes`;
+}
+
 // Re-exported here for callers that import from codegen-ts's naming module.
 export { toKebabCase };

package/src/payload-codegen.ts

@@ -23,6 +23,8 @@ import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_FORMAT,
+  refMatchesObject,
+  stripPackage,
 } from "@metaobjectsdev/metadata";
 import { enumValues } from "./enum-meta.js";
 import { enumUnionAliasName, enumUnionString } from "./templates/inferred-types.js";
@@ -45,7 +47,9 @@ const SCALAR_TS: Record<string, string> = {
 };
 
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  // FR-032 — @payloadRef/@responseRef are FQN after the desugar/sweep; match on
+  // the effective FQN resolution key (with bare back-compat).
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
 /**
@@ -168,14 +172,21 @@ export function generateRenderHandle(root: MetaData, templateName: string): stri
   const tmpl = root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === templateName);
   if (!tmpl) throw new Error(`template "${templateName}" not found`);
   const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  // FR-032 — @payloadRef is an FQN after the desugar/sweep; the generated TS
+  // TYPE NAME is the resolved value-object's bare name (an FQN like
+  // `acme::ai::Payload` is not a valid TS identifier). Fall back to the last
+  // `::`-segment when the VO is not in this root (defensive).
+  const payloadType =
+    (typeof payloadRef === "string" ? findObject(root, payloadRef)?.name : undefined) ??
+    (typeof payloadRef === "string" ? stripPackage(payloadRef) : String(payloadRef));
   const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
   const format = (tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
   const fn = `render${pascal(templateName)}`;
   return [
     `import { render, type Provider } from "@metaobjectsdev/render";`,
-    `import type { ${payloadRef} } from "./payloads.js";`,
+    `import type { ${payloadType} } from "./payloads.js";`,
     ``,
-    `export function ${fn}(payload: ${payloadRef}, provider: Provider): string {`,
+    `export function ${fn}(payload: ${payloadType}, provider: Provider): string {`,
     `  return render({ ref: ${JSON.stringify(textRef)}, payload, format: ${JSON.stringify(format)}, provider });`,
     `}`,
     ``,