Merge: api-docs real-output fixes — copy-paste-compilable imports, Hono coverage, + a generator bugfix

From a second staff agentic-AI review that ran the REAL generation and tsc-compiled
a consumer from AGENT-API.md (value jumped ~3->7; the prior blockers are real-closed):
- api-docs renders ./-prefixed import specifiers so a consumer copied from the doc
  COMPILES (was bare specifiers -> TS2307); a new gate tsc-compiles a CRUD consumer
  from AGENT-API.md against the real generated code.
- api-docs auto-documents Hono routes when routesFileHono() is in the suite (new
  emitsHonoRoutes flag aggregated by the runner).
- Generator bugfix: extractor/render-helper imported the payload VO from a
  non-existent ./payloads.js -> now import each VO from its real entity module; a
  new gate tsc-compiles the generated extractor/render files. This uncovered + fixed
  a second latent bug (the mapper emitted ?? null against a T|undefined interface ->
  TS2322; now ?? undefined). Engine-layer extract-conformance unaffected (the change
  is in generated TS glue below the cross-port contract; corpus 22/22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/codegen-ts/src/generator.ts

@@ -47,6 +47,12 @@ export interface Generator {
   /** Marks the generator that produces entity modules — the runner uses its
    *  target as the entity-module target for cross-target import resolution. */
   emitsEntityModule?: boolean;
+  /** Marks the OPT-IN Hono routes generator (routesFileHono). The runner
+   *  aggregates this across the active suite into `ctx.config.includeHonoRoutes`,
+   *  so a generator that documents the API surface (api-docs) can AUTO-DETECT
+   *  that Hono routes are actually being emitted and document them — rather than
+   *  silently omitting the Hono CRUD registrars whenever the variant is wired. */
+  emitsHonoRoutes?: boolean;
 }
 
 export type GeneratorFactory<TOpts = void> = TOpts extends void

server/typescript/packages/codegen-ts/src/generators/api-doc-render.ts

@@ -29,6 +29,40 @@ const AGENT_REF = "api/agent-api.md";
 
 const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
 
+// ---------------------------------------------------------------------------
+// Relative-import RENDER prefix.
+//
+// An `ApiSymbol.importPath` is the generated module's path RELATIVE TO the
+// codegen output dir (flat → `Product.queries`; package → the package-folded
+// `acme/shop/Product.queries`). It is the DATA the accuracy gate verifies
+// against the emitted file, so it stays a bare module path.
+//
+// The generated files import each OTHER with `./`-prefixed RELATIVE specifiers
+// (`from "./Product"`), so a copy-paste consumer co-located in the generated
+// output dir must do the same — a BARE specifier (`from "Product.queries"`)
+// only resolves with a non-default `baseUrl` and otherwise fails TS2307. The
+// renderers therefore `./`-prefix the importPath in every rendered `from "…"`
+// (the human page, the agent group headers, AND the example import blocks),
+// without touching the underlying importPath data. A consumer importing from
+// elsewhere adjusts the prefix (stated once in the page's import note).
+// ---------------------------------------------------------------------------
+
+/** The `./`-prefixed RELATIVE specifier for a documented module path (the form a
+ *  co-located consumer copy-pastes). Already-relative paths pass through. */
+function relSpecifier(importPath: string): string {
+  return importPath.startsWith("./") || importPath.startsWith("../")
+    ? importPath
+    : `./${importPath}`;
+}
+
+/** Rewrite the `from "<module>"` tail of an example `import { … } from "<module>";`
+ *  line to the `./`-prefixed relative specifier — the example imports are
+ *  pre-composed in the ApiModel (reusing each symbol's bare importPath), so the
+ *  `./` prefix is applied at render time alongside the section/header imports. */
+function relImportLine(line: string): string {
+  return line.replace(/(\bfrom\s+")([^"]+)(")/, (_m, pre, mod, post) => `${pre}${relSpecifier(mod)}${post}`);
+}
+
 // The human-facing section ORDER + HEADING per ApiSymbolKind. A unit's page
 // renders only the kinds it actually carries, always in this canonical order
 // (so two runs over the same model are byte-stable regardless of symbol order).
@@ -221,7 +255,7 @@ function importLineFor(s: ApiSymbol): string {
   // registrar named on the symbol instead of the "METHOD /path" name.
   const isRouteKind = s.kind === "rest" || s.kind === "rest-hono";
   const imported = isRouteKind ? s.registrar ?? s.name : s.name;
-  return `import { ${imported} } from "${s.importPath}"`;
+  return `import { ${imported} } from "${relSpecifier(s.importPath)}"`;
 }
 
 /** Group a unit's symbols into ordered sections (one per present kind), each a
@@ -253,7 +287,9 @@ function entityPageVM(unit: ApiUnitDoc): EntityPageVM {
  *  string. Undefined when the unit has no runnable example. */
 function unitExampleBlock(example: UnitExample | undefined): string | undefined {
   if (example === undefined) return undefined;
-  const lines = [...example.imports];
+  // The example imports are pre-composed in the ApiModel from the symbols' bare
+  // importPaths; `./`-prefix each at render time so the copy-paste block resolves.
+  const lines = example.imports.map(relImportLine);
   if (example.imports.length > 0 && example.body.length > 0) lines.push("");
   lines.push(...example.body);
   return lines.join("\n");
@@ -469,7 +505,7 @@ function agentGroups(unit: ApiUnitDoc): AgentGroupVM[] {
   return order.map((mod) => {
     const g = byModule.get(mod)!;
     return {
-      importHeader: `import { ${g.names.join(", ")} } from "${mod}"`,
+      importHeader: `import { ${g.names.join(", ")} } from "${relSpecifier(mod)}"`,
       symbols: g.symbols,
     };
   });

server/typescript/packages/codegen-ts/src/generators/api-docs-file.ts

@@ -64,9 +64,15 @@ export const apiDocsFile = function apiDocsFile(opts?: ApiDocsFileOpts): Generat
       // ONE ApiModel feeds every form (Task-1 builder; Task-2 renderers). The
       // pkMap is reused from the run's renderContext when present (the real gen
       // run always provides it) and derived otherwise.
+      // Auto-detect: document the OPT-IN Hono CRUD surface iff the Hono routes
+      // generator is actually in the run. The runner aggregates each generator's
+      // `emitsHonoRoutes` marker into ctx.config.includeHonoRoutes, so api-docs
+      // "just works" — it documents Hono exactly when `routesFileHono` is wired,
+      // and omits it (Fastify-only) otherwise. No explicit opt needed.
       const model = buildApiModel(ctx.loadedRoot, {
         loadedRoot: ctx.loadedRoot,
         outputLayout: layout,
+        includeHonoRoutes: ctx.config.includeHonoRoutes ?? false,
         ...(ctx.renderContext?.pkMap !== undefined && { pkMap: ctx.renderContext.pkMap }),
       });
 

server/typescript/packages/codegen-ts/src/generators/extractor-file.ts

@@ -5,7 +5,8 @@
 //
 // The emitted extractor sits over the output-parser's nested-capable extract and turns dirty LLM
 // text into the strict typed payload graph. It imports from the sibling <Name>.output.ts (the
-// output-parser) and ./payloads.ts, so run it alongside outputParser() + a payload generator.
+// output-parser) and from each payload value-object's own entity module (<VO>.ts, emitted by
+// entityFile), so run it alongside outputParser() + entityFile().
 //
 // Consumer wiring (metaobjects.config.ts):
 //   generators: [..., outputParser(), extractor()]

server/typescript/packages/codegen-ts/src/generators/routes-file-hono.ts

@@ -27,6 +27,9 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
   const userFilter = opts?.filter ?? (() => true);
   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,
     filter: (e: MetaObject) => e.ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {

server/typescript/packages/codegen-ts/src/metaobjects-config.ts

@@ -42,6 +42,11 @@ 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;
 }
 
 export interface MetaobjectsGenConfig extends ResolvedGenConfig {

server/typescript/packages/codegen-ts/src/runner.ts

@@ -143,6 +143,11 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     root.objects().map((o) => [o.name, o.package]),
   );
 
+  // Auto-detect: is the OPT-IN Hono routes generator in the active suite? If so,
+  // surface it on every generator's ctx.config so api-docs documents the Hono
+  // CRUD surface it actually emits (rather than silently omitting it).
+  const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
+
   // 4. Run each generator with a per-target render context; collect with full path.
   const emitted: { fullPath: string; content: string; generatedBy: string }[] = [];
   for (const generator of config.generators) {
@@ -173,6 +178,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         dbImport: selfTarget.dbImport,
         dialect: config.dialect,
         outputLayout: selfTarget.outputLayout,
+        includeHonoRoutes,
       },
       renderContext,
       ...(projectRoot !== undefined && { projectRoot }),

server/typescript/packages/codegen-ts/src/templates/extractor.ts

@@ -64,9 +64,9 @@ function isObjectField(field: MetaData): boolean {
 
 /**
  * The union-alias type name for a `field.enum` with effective `@values`, or undefined when the
- * field is not a value-constrained enum. Reuses `enumUnionAliasName` — the SAME naming the payload
- * emitter (`payload-codegen.ts`) types the field as — so the cast target resolves to the exact
- * alias exported from `payloads.ts`. `ownerName` is the owning value-object's interface name.
+ * field is not a value-constrained enum. Reuses `enumUnionAliasName` — the SAME naming the entity
+ * inferred-types emitter types the field as — so the cast target resolves to the exact alias
+ * exported from the owning VO's entity module. `ownerName` is the owning value-object's interface name.
  */
 function enumAlias(field: MetaData, ownerName: string): string | undefined {
   if (field.subType !== FIELD_SUBTYPE_ENUM) return undefined;
@@ -76,11 +76,12 @@ function enumAlias(field: MetaData, ownerName: string): string | undefined {
 }
 
 /**
- * True iff the field is required IN THE STRICT PAYLOAD TYPE. This MUST match
- * payload-codegen.ts's `isFieldRequired` predicate EXACTLY (boolean `true` only) — the payload
- * interface decides `T` vs `T | null` by that predicate, and the mapper's optionality assumption
- * (`m.f!` vs `m.f ?? null`) has to agree with the type it is constructing. A `@required:"true"`
- * string field is therefore `T | null` in the payload AND optional here (no skew).
+ * True iff the field is required IN THE STRICT PAYLOAD TYPE. The strict payload IS the VO's own
+ * generated entity-module interface (`renderValueObjectInterface`), which types a required field
+ * `f: T` and an optional one `f?: T` (i.e. `T | undefined` — NOT `T | null`). So the mapper's
+ * optionality assumption (`m.f!` vs `m.f ?? undefined`) has to agree with THAT interface, and an
+ * absent optional maps to `undefined`, never `null`. This predicate matches the interface's
+ * required test (boolean `true` only) so the two never skew.
  */
 function isFieldRequired(field: MetaData): boolean {
   return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
@@ -93,8 +94,10 @@ function mapperName(vo: MetaData): string {
 
 /**
  * The mapper-body initializer expression for one field, reading mirror member `m.<name>` and
- * mapping it onto the strict payload's exact optionality (required → `m.f!`; optional → `m.f ?? null`).
- * Nested single/array objects recurse into their toStrict<Type> mapper, guarding null when optional.
+ * mapping it onto the strict payload's exact optionality (required → `m.f!`; optional → `m.f ?? undefined`).
+ * The strict payload is the VO's generated entity-module interface, whose optional fields are
+ * `f?: T` (= `T | undefined`, never `T | null`), so an absent optional maps to `undefined`.
+ * Nested single/array objects recurse into their toStrict<Type> mapper, guarding when optional.
  */
 function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
   const name = field.name;
@@ -104,25 +107,25 @@ function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
     const target = refVo(field, root);
     if (target === undefined) {
       // Unresolved @objectRef — the payload type would be `unknown`; pass through as-is.
-      return required ? `m.${name}!` : `m.${name} ?? null`;
+      return required ? `m.${name}!` : `m.${name} ?? undefined`;
     }
     const fn = mapperName(target);
     if (isArray(field)) {
       // Required array-of-objects: each element mapped; element nulls dropped at the type level
       // via the non-null assertion (extract never yields null elements for a present array).
       if (required) return `m.${name}!.map((e) => ${fn}(e!))`;
-      return `m.${name} ? m.${name}!.map((e) => ${fn}(e!)) : null`;
+      return `m.${name} ? m.${name}!.map((e) => ${fn}(e!)) : undefined`;
     }
     // Single nested object.
     if (required) return `${fn}(m.${name}!)`;
-    return `m.${name} ? ${fn}(m.${name}) : null`;
+    return `m.${name} ? ${fn}(m.${name}) : undefined`;
   }
 
   // Scalar ARRAY (e.g. `field.string` with isArray): the mirror types it `(T | null)[] | null`
-  // but the strict payload types it `T[]` (required) / `T[] | null` (optional). A bare `m.f!`
+  // but the strict payload types it `T[]` (required) / `T[]?` (optional). A bare `m.f!`
   // would leave the element type `T | null`, a `tsc --strict` TS2322 error. Filter out null
   // elements so the element type narrows to non-null (consistent with the lost-element DROP policy
-  // already used for required arrays-of-objects above).
+  // already used for required arrays-of-objects above). An absent optional array maps to `undefined`.
   //
   // ENUM arrays: the mirror element is a plain `string`, but the strict payload types it as the
   // closed `<Alias>[]` union. The null-filter alone narrows to `string[]`, not `<Alias>[]` — a
@@ -136,23 +139,23 @@ function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
       return alias !== undefined ? `(${filtered}) as ${alias}[]` : filtered;
     }
     const filtered = `m.${name}.filter((x): x is NonNullable<typeof x> => x != null)`;
-    const guarded = `m.${name} == null ? null : ${filtered}`;
+    const guarded = `m.${name} == null ? undefined : ${filtered}`;
     return alias !== undefined
-      ? `m.${name} == null ? null : (${filtered}) as ${alias}[]`
+      ? `m.${name} == null ? undefined : (${filtered}) as ${alias}[]`
       : guarded;
   }
 
   // Scalar / enum (single): the strict payload's optionality decides the shape.
-  // Required → non-null assertion; optional → `?? null` (matches the payload's `f?: T | null`).
+  // Required → non-null assertion; optional → `?? undefined` (matches the entity-module `f?: T`).
   //
   // ENUM scalar: the mirror member is a plain `string`, but the strict payload types it as the
   // closed `<Alias>` union — assigning `string` into `<Alias>` is a `tsc --strict` TS2322 error.
   // So the value is CAST to `<Alias>`. Sound for the same reason as enum arrays above: the engine
   // already validated membership (or extract throws on a lost required field).
   if (alias !== undefined) {
-    return required ? `m.${name}! as ${alias}` : `(m.${name} ?? null) as ${alias} | null`;
+    return required ? `m.${name}! as ${alias}` : `(m.${name} ?? undefined) as ${alias} | undefined`;
   }
-  return required ? `m.${name}!` : `m.${name} ?? null`;
+  return required ? `m.${name}!` : `m.${name} ?? undefined`;
 }
 
 /**
@@ -202,32 +205,52 @@ function emitMapper(
 }
 
 /**
- * Collect the strict payload-interface names reachable from `vo` (for the type-only import),
- * PLUS every enum union-alias reachable from those VOs. Both are exported from `payloads.ts`
- * (the alias is hoisted above the interface there), so the extractor's `as <Alias>` casts need
- * the alias names imported alongside the interface names. Deduped, in discovery order.
+ * One payload-type import group: the strict types (VO interface + its own enum
+ * union-aliases) imported from a single VO entity module.
  */
-function reachablePayloadTypes(vo: MetaData, root: MetaData): string[] {
-  const order: string[] = [];
-  const seen = new Set<string>();
+interface PayloadImportGroup {
+  /** The VO whose entity module exports these types (`./<module>.js`). */
+  module: string;
+  /** The strict type names exported by that module, in discovery order. */
+  types: string[];
+}
+
+/**
+ * Group the strict payload types reachable from `vo` BY THE ENTITY MODULE THAT EXPORTS THEM.
+ *
+ * Each value-object gets its own generated entity module (`entityFile()` emits `<VO>.ts` exporting
+ * `export interface <VO>`), and `renderEnumTypeAliases` hoists every `field.enum` union-alias INTO
+ * the OWNING VO's module (`export type <Owner><Field> = ...` co-located with the interface). So a
+ * VO's interface AND the aliases for its own enum fields are imported from `./<VO>.js` — NOT from a
+ * single `payloads.ts` (which no generator emits). Deduped, in discovery order, one group per VO.
+ */
+function reachablePayloadGroups(vo: MetaData, root: MetaData): PayloadImportGroup[] {
+  const groups: PayloadImportGroup[] = [];
+  const seenVo = new Set<string>();
+  const seenAlias = new Set<string>();
   const visit = (cur: MetaData) => {
-    if (seen.has(cur.name)) return;
-    seen.add(cur.name);
-    order.push(cur.name);
+    if (seenVo.has(cur.name)) return;
+    seenVo.add(cur.name);
+    // The VO interface + its OWN enum aliases share the VO's entity module.
+    const types: string[] = [cur.name];
     for (const f of fields(cur)) {
       const alias = enumAlias(f, cur.name);
-      if (alias !== undefined && !seen.has(alias)) {
-        seen.add(alias);
-        order.push(alias);
+      if (alias !== undefined && !seenAlias.has(alias)) {
+        seenAlias.add(alias);
+        types.push(alias);
       }
+    }
+    groups.push({ module: cur.name, types });
+    // Recurse into nested object refs (their interfaces live in their own modules).
+    for (const f of fields(cur)) {
       if (isObjectField(f)) {
         const target = refVo(f, root);
         if (target !== undefined) visit(target);
       }
     }
   };
   visit(vo);
-  return order;
+  return groups;
 }
 
 /** Collect the mirror-interface names reachable from `vo` (root mirror + nested VO mirrors). */
@@ -286,10 +309,16 @@ export function renderExtractor(root: MetaData, templateName: string): string {
   const extractName = `extract${templateName}`;
   const rootMapper = mapperName(vo);
 
-  const payloadTypes = reachablePayloadTypes(vo, root);
+  const payloadGroups = reachablePayloadGroups(vo, root);
   const mirrorTypes = reachableMirrorTypes(vo, root, rootMirror);
   const mappers = emitMappers(vo, root, rootMirror);
 
+  // One type-only import per VO entity module (the VO interface + its own enum
+  // union-aliases co-located there). NOT a single non-existent `./payloads.js`.
+  const payloadImports = payloadGroups
+    .map((g) => `import type { ${g.types.join(", ")} } from "./${g.module}.js";`)
+    .join("\n");
+
   const lostMsg =
     `${extractName}: lost required field(s): `;
 
@@ -301,7 +330,7 @@ export function renderExtractor(root: MetaData, templateName: string): string {
     `// mapping the all-nullable mirror onto the strict payload. No registry / binding / factory.\n` +
     `\n` +
     `import {\n  ${extractLenientWithName},\n  type ${mirrorTypes.join(",\n  type ")},\n} from "./${templateName}.output.js";\n` +
-    `import type { ${payloadTypes.join(", ")} } from "./payloads.js";\n` +
+    `${payloadImports}\n` +
     `import type { MetaRoot } from "@metaobjectsdev/metadata";\n` +
     `import type { ExtractionResult } from "@metaobjectsdev/render";\n` +
     `\n` +

server/typescript/packages/codegen-ts/src/templates/render-helper.ts

@@ -192,7 +192,7 @@ export function renderRenderHelper(
 
     return `import { render } from "@metaobjectsdev/render";
 import type { Provider, EmailDocument } from "@metaobjectsdev/render";
-import type { ${payloadRef} } from "./payloads.js";
+import type { ${payloadRef} } from "./${payloadRef}.js";
 
 /**
  * Render the ${templateName} email (subject + html body${typeof textBodyRef === "string" ? " + text body" : ""}) from a
@@ -230,7 +230,7 @@ export function ${fnName}(payload: ${payloadRef}, provider: Provider): EmailDocu
 
   return `import { render } from "@metaobjectsdev/render";
 import type { Provider } from "@metaobjectsdev/render";
-import type { ${payloadRef} } from "./payloads.js";
+import type { ${payloadRef} } from "./${payloadRef}.js";
 
 /**
  * Render the ${templateName} document from a typed ${payloadRef} payload. Wraps the