@metaobjectsdev/codegen-ts 0.24.4 → 0.25.0

package/src/overwrite-policy.ts

@@ -610,10 +610,22 @@ export function decideAndWrite(
       return {
         path,
         status: "refused",
+        // The hint states WHAT HAPPENED, per file, and points at the recovery rather
+        // than restating it. The two remedies it used to name were both WRONG for the
+        // generator with the most at stake: `requirementTests()` emits a stub whose
+        // entire value is the body you write over it, and whose own header says "do not
+        // rename the test — the name is the link", so "move your edits into a
+        // non-generated file" asks for something the artifact forbids, and
+        // "--baseline=fresh to discard them" discards the only content the file has.
+        // The sequence that actually keeps an edit is three commands long and identical
+        // for every file in the run, so `runner.ts` prints it once; a doc pointer is
+        // what a direct `decideAndWrite` caller (a public export — no runner involved)
+        // gets instead, and it is never wrong.
         conflictHint: kase.hasRecord
-          ? "this file has been edited since it was generated — it was NOT " +
-            "overwritten. Move your edits into a non-generated file, or re-run " +
-            "with --baseline=fresh to discard them and adopt fresh output."
+          ? "this file has been edited since it was generated, and there is no " +
+            ".gen-state snapshot body on this machine to merge against — it was NOT " +
+            "overwritten, and your version is intact on disk. Recovery: " +
+            "docs/features/own-your-codegen.md."
           : "no record of generating this file, and its content differs from fresh " +
             "output — it was NOT overwritten. Move it aside, or re-run with " +
             "--baseline=fresh to overwrite it and adopt fresh output as the baseline.",

package/src/payload-codegen.ts

@@ -41,6 +41,7 @@ import {
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { enumValues } from "./enum-meta.js";
+import { templateSymbolBase } from "./naming.js";
 import { enumUnionAliasName, enumUnionString } from "./templates/inferred-types.js";
 import { assignEmittedNames } from "./naming/collision-names.js";
 
@@ -258,9 +259,9 @@ export function generatePayloadInterfacesBatch(
   return out.length === 0 ? "" : out.join("\n\n") + "\n";
 }
 
-function pascal(s: string): string {
-  return s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s;
-}
+// Delegates to the shared authority so this emitter cannot drift from the parser and
+// render-helper again (naming.ts / templateSymbolBase).
+const pascal = templateSymbolBase;
 
 /** Emit a typed render handle binding a template's @textRef + @format and typing its payload. */
 export function generateRenderHandle(root: MetaData, templateName: string): string {

package/src/projection/extract-view-spec.ts

@@ -6,6 +6,8 @@ import {
   TYPE_RELATIONSHIP,
   isMetaObject,
   isReadOnlySource,
+  SOURCE_ROLE_PRIMARY,
+  SOURCE_ATTR_SCHEMA,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
   ORIGIN_SUBTYPE_COMPUTED,
@@ -49,7 +51,7 @@ import {
   resolveObjectRef,
   type AggregateFunction,
 } from "@metaobjectsdev/metadata";
-import { type MetaData, type MetaField, type MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
+import { type MetaData, type MetaField, type MetaRoot, type MetaSource, MetaObject } from "@metaobjectsdev/metadata";
 import { intValueMapOf } from "../enum-meta.js";
 import {
   columnNameFromField,
@@ -331,16 +333,58 @@ function resolveHop(
 function viewName(projection: MetaObject, ctx: ExtractContext): string {
   // The read-only source carries the physical view name. FR-016: physicalName
   // implements the four-step rule (kind-matching alias → legacy @table →
-  // source.name → entity-name fallback), so the call below correctly resolves
-  // @view / @materializedView / legacy @table for projection sources.
+  // source.name → entity-name fallback), so `viewSource.physicalName` below
+  // correctly resolves @view / @materializedView / legacy @table for projection
+  // sources.
   // ADR-0039: own — projection source classification (mirrors C# projection
-  // OwnSources / IsReadOnlyProjection): the view name comes from the projection's
-  // OWN read-only source, not one inherited via extends.
-  const viewSource = projection.ownChildren().find(isReadOnlySource);
+  // OwnSources / IsReadOnlyProjection): the view name comes from the object's
+  // OWN read-only source, not one inherited via extends. `ERR_PROJECTION_
+  // INHERITED_SOURCE` (subtype-rules.ts) already refuses a concrete projection
+  // that would otherwise inherit a source, so own-only never drops a legally
+  // reachable source here.
+  //
+  // This function serves TWO shapes — a plain projection, and a write-through
+  // ENTITY's replica view (extractViewSpec's `writeThrough` branch, #213/#214;
+  // the parameter name is historical) — which need DIFFERENT selection rules,
+  // hence "prefer role:primary, else the first read-only source" rather than
+  // "require role:primary":
+  //   - A plain projection: EVERY own source must be read-only-kind
+  //     (ERR_PROJECTION_SOURCE_WRITABLE), so if it has any sources at all,
+  //     exactly one is role:"primary" (ERR_SOURCE_NO_PRIMARY /
+  //     ERR_SOURCE_MULTIPLE_PRIMARY) and that one IS read-only — the primary
+  //     branch always fires when there is a source.
+  //   - A write-through entity: its role:"primary" source is the WRITABLE
+  //     table (never read-only), so the primary branch never fires; its
+  //     read-only companion (the replica view) is intentionally NOT primary.
+  //     The fallback (first read-only own source) is what names it.
+  //
+  // Selecting the role:"primary" read-only source PREFERENTIALLY over
+  // declaration order (rather than "first read-only source in file order") is
+  // what makes this agree with `resolveTableName()` (the resolver every §A6
+  // site defers to via `resolveObjectNames`): a plain projection declaring a
+  // role:"replica" source before its role:"primary" one would otherwise bind a
+  // different physical view depending on whether the names generator happened
+  // to be active in the run.
+  const readOnlySources = projection.ownChildren().filter(isReadOnlySource);
+  const viewSource =
+    readOnlySources.find((c) => c.role === SOURCE_ROLE_PRIMARY) ?? readOnlySources[0];
   const explicit = viewSource?.physicalName;
   // physicalName always returns a string; empty string means the source had
   // neither alias nor a name and the owning entity name was empty (impossible
   // for a real projection). Fall through to the helper anyway for safety.
+  //
+  // This fallback fires only when the object has NO own read-only source at
+  // all. It differs from `resolveTableName()`'s own no-source fallback
+  // (`v_<snake(name)>` here vs `pluralize(toSnakeCase(name))` there), but that
+  // difference is UNOBSERVABLE: whenever a sourceless object reaches this
+  // fallback, `resolveObjectNames()` also finds no primary source and returns
+  // `undefined` before ever calling `resolveTableName()` — so no §A6 site has
+  // a names constant to reference either way, and both the ON and OFF arms
+  // land on THIS function's literal on the identical no-source condition. A
+  // sourceless projection also fails `isProjection()` itself
+  // (projection-detector.ts requires a read-only-kind source), so codegen's
+  // dispatch never reaches `renderProjectionDecl`/this function for it in the
+  // first place — doubly unreachable.
   return explicit !== undefined && explicit !== ""
     ? explicit
     : viewNameFromProjection(projection.name, ctx.columnNamingStrategy);
@@ -363,6 +407,41 @@ export function projectionViewName(
   return viewName(projection, { columnNamingStrategy });
 }
 
+/**
+ * The `@schema` of the SAME source node {@link projectionViewName} names, or undefined.
+ *
+ * It re-uses that function's selection rule ("prefer role:primary read-only, else the first
+ * read-only own source") deliberately, rather than asking the object for its schema: for a
+ * write-through ENTITY the object's primary source is the WRITABLE table, so
+ * `resolveTableSchema` would hand back the table's schema and qualify the replica view with
+ * it. A view and the table it replicates need not live in the same schema, and a name paired
+ * with someone else's schema is worse than no schema at all — it is confidently wrong.
+ */
+export function projectionViewSchema(projection: MetaObject): string | undefined {
+  const schema = projectionViewSource(projection)?.attr(SOURCE_ATTR_SCHEMA);
+  return typeof schema === "string" && schema !== "" ? schema : undefined;
+}
+
+/**
+ * The source node {@link projectionViewName} names — the ONE selection, so the name, the
+ * schema and the role cannot be picked by three functions that agree until they do not.
+ *
+ * Hoisted out of `projectionViewSchema`, which used to be the only place the rule was
+ * written twice-removed from `viewName`. The third caller is what forced it: the names
+ * artifact keys its sources by ROLE, so a consumer reaching for a write-through entity's
+ * replica view has to know which role that view plays, and guessing `"replica"` would be
+ * exactly the second derivation this file exists to avoid.
+ */
+export function projectionViewSource(projection: MetaObject): MetaSource | undefined {
+  const readOnlySources = projection.ownChildren().filter(isReadOnlySource);
+  return readOnlySources.find((c) => c.role === SOURCE_ROLE_PRIMARY) ?? readOnlySources[0];
+}
+
+/** The ROLE of that source — the key its entry has in `<Entity>Names.sources`. */
+export function projectionViewRole(projection: MetaObject): string | undefined {
+  return projectionViewSource(projection)?.role;
+}
+
 /**
  * FR-024 (ADR-0029): the entity NAMED by a node's dotted extends ref — the
  * owner part of `<owner>.<child>...` resolved as an object. Mirrors the

package/src/prompt-generator-gate.ts

@@ -0,0 +1,73 @@
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_ATTR_RESPONSE_REF } from "@metaobjectsdev/metadata";
+import type { Generator } from "./generator.js";
+
+/**
+ * Generators that turn a declared `template.*` into runnable prompt code. Names, not
+ * identities, because an adopter may wrap or re-export them (ADR-0034 scaffold-and-own
+ * makes owning a copy the encouraged path) and a wrapper keeps the name.
+ */
+const PROMPT_GENERATOR_NAMES: ReadonlySet<string> = new Set([
+  "prompt-render",
+  "output-parser",
+  "render-helper",
+  "output-prompt",
+]);
+
+/**
+ * A declared prompt with no prompt generator wired produced NOTHING and said NOTHING.
+ *
+ * `meta gen` emitted the payload value objects (they are `object.value` nodes, which the
+ * entity generator picks up) and stopped there: no `render<Name>()`, no parser, no
+ * response-format fragment. `meta verify` then reported "1 template(s) clean", which reads
+ * as confirmation that the prompt is fine. So the fourth pillar produced two type files and
+ * a green gate, and the adopter had neither a send side nor a receive side.
+ *
+ * The wiring IS documented — but only in the prompts skill's per-language reference
+ * fragment, which SKILL.md points at in its final line, while the skill body walks the
+ * entire declaration without once saying a generator is required. Found by declaring a
+ * `template.prompt` in a from-scratch app exactly as that skill teaches.
+ *
+ * This follows the `layout.dataGrid` precedent (#287, data-grid-gate.ts): tell the adopter
+ * at `meta gen` time rather than adding a doc line that gets missed the same way. It is a
+ * WARNING — the exit code is untouched — and it is **self-extinguishing**: wire any one
+ * prompt generator and it goes quiet forever, so a project that has made this choice
+ * deliberately is never nagged.
+ *
+ * It must live in the runner rather than in a generator, because the whole condition is
+ * that the generator which would speak up is not running.
+ */
+export function warnMissingPromptGenerators(
+  root: MetaData,
+  generators: readonly Generator[],
+  warn: (msg: string) => void,
+): void {
+  if (generators.some((g) => PROMPT_GENERATOR_NAMES.has(g.name))) return;
+
+  // ADR-0039: resolving children — a template may arrive through an overlay or extends.
+  const templates = root
+    .children()
+    .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_PROMPT);
+  if (templates.length === 0) return;
+
+  const names = templates.map((t) => t.name).join(", ");
+  // A @responseRef is what asks for the inbound tier (ADR-0052), so a responding prompt
+  // is missing strictly more than an outbound-only one. Name that, rather than making the
+  // adopter infer which half is absent.
+  const responding = templates.filter((t) => typeof t.attr(TEMPLATE_ATTR_RESPONSE_REF) === "string");
+  const receiveHalf =
+    responding.length > 0
+      ? ` ${responding.length === templates.length ? "All" : `${responding.length} of them`} ` +
+        `declare a @responseRef, so the parser and response-format fragment are missing too — ` +
+        `add outputParser().`
+      : "";
+
+  warn(
+    `${templates.length} declared template.prompt (${names}) generated no prompt code: ` +
+      `no prompt generator is wired, so there is no render function to send one and nothing ` +
+      `read a reply. Add promptRender() to \`generators\` in metaobjects.config.ts ` +
+      `(import it from "@metaobjectsdev/codegen-ts/generators").${receiveHalf} ` +
+      `The payload value objects were emitted regardless — those are object.value nodes, ` +
+      `which is why this looked like it had worked.`,
+  );
+}

package/src/reference/barrel.ts

@@ -6,6 +6,9 @@
 // shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
 // reach for `Bun.*` globals here; they are undefined and take the whole run down with
 // `Bun is not defined`. Use `node:` builtins instead.
+// targets:       nothing framework-specific — it re-exports whatever the other generators
+//                emitted. `extStyle` decides whether the re-export specifiers carry a
+//                `.js` extension.
 // use-when:      you want a single `index.ts` re-exporting every generated entity module.
 // emits:         <target>/index.ts with one `export * from "./<Entity>"` per entity, alphabetical.
 // customize:     the export form (star vs named), ordering, grouping by package, what to include/exclude.

package/src/reference/entity.ts

@@ -6,6 +6,13 @@
 // shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
 // reach for `Bun.*` globals here; they are undefined and take the whole run down with
 // `Bun is not defined`. Use `node:` builtins instead.
+// targets:       Drizzle ORM + Zod. The emitted module is a Drizzle table plus Zod
+//                insert/update schemas; the column mapping follows `dialect`. On the
+//                default (vanilla) path, replace the `renderDrizzleSchema` /
+//                `renderZodValidators` calls to target a different ORM or validator — the
+//                metadata walk that feeds them is ORM-neutral. (The `isWriteThrough`
+//                branch calls `renderEntityFile` instead — a narrow #214 read-view case,
+//                not the default.)
 // use-when:      ALWAYS — this is the entity-module generator. It owns the shape of each
 //                generated <Entity>.ts (the Drizzle table, Zod schemas, inferred types,
 //                constants, filter allowlists). Start here and adapt the assembly.
@@ -54,11 +61,14 @@ import {
   isWriteThrough,
   isAbstract,
   hasWritableRdbSource,
+  isTphSubtype,
   // engine composer — used for the delegated write-through variant:
   renderEntityFile,
   // engine plumbing:
   formatTs,
   entityOutputPath,
+  namesRef,
+  namesConstArg,
   GENERATED_HEADER,
 } from "@metaobjectsdev/codegen-ts";
 
@@ -77,6 +87,10 @@ function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntit
   }
   // Projection → read-only view declaration + read schema.
   if (isProjection(entity)) {
+    // §A6/§B2 — same `namesRef` pair renderDrizzleSchema builds, so the projection's view
+    // name + per-field dbCol reference the exact constant the names artifact exports
+    // (undefined when the artifact is not in this run). `namesRef`'s `{ resolved, symbol }`
+    // return is exactly the shape `ProjectionDeclOpts.names` wants.
     return renderProjectionDecl(entity, ctx.loadedRoot, {
       columnNamingStrategy: ctx.columnNamingStrategy,
       dialect: ctx.dialect,
@@ -85,10 +99,18 @@ function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntit
       allowlists,
       ctx,
       includeViewDecl: runtime,
+      names: namesRef(entity, ctx),
     });
   }
   // Value-only / contract target → interface + Zod, no Drizzle table.
-  if (!runtime || !hasWritableRdbSource(entity)) {
+  //
+  // A TPH subtype (FR-017) routes here too. It INHERITS the discriminator base's writable
+  // source.rdb through `extends`, so `hasWritableRdbSource` is true for it under the
+  // ADR-0039 resolving read — but the base owns the single shared table. Without the
+  // isTphSubtype clause this template fell through to the vanilla path and emitted a
+  // SECOND Drizzle table bound to the base's physical name, carrying only the subtype's
+  // own columns.
+  if (!runtime || !hasWritableRdbSource(entity) || isTphSubtype(entity)) {
     return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
   // #214 — a write-through entity read-view (writable table + a read-only replica view +
@@ -103,12 +125,16 @@ function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntit
   const enumAliases = renderEnumTypeAliases(entity, ctx);
   const tphBlock = renderTphDiscriminatorUnion(entity, ctx.loadedRoot);
   const tphBase = tphBlock !== null && isTphDiscriminatorBase(entity, ctx.loadedRoot);
+  // §A6/§B2 — same `namesRef` pair renderDrizzleSchema (and the projection branch above)
+  // build, so the descriptor's $table references the exact constant the names artifact
+  // exports (undefined when the artifact is not in this run).
+  const constantsNames = namesRef(entity, ctx);
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
     renderInferredTypes(entity, tphBase, ctx),
     ...(enumAliases !== null ? [enumAliases] : []),
     renderZodValidators(entity, ctx),
-    renderEntityConstants(entity, ctx.apiPrefix),
+    renderEntityConstants(entity, ctx.apiPrefix, namesConstArg(constantsNames)),
     ...(allowlists ? [renderFilterAllowlist(entity, undefined, ctx), renderSortAllowlist(entity)] : []),
     renderFilterType(entity),
     ...(tphBlock !== null ? [tphBlock] : []),

package/src/reference/names.ts

@@ -0,0 +1,125 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/names.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { namesFile } from "./codegen/generators/names.js";
+//
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
+// targets:       the emit step. Replace `renderNamesDecl` to change the artifact's SHAPE
+//                (e.g. flat `SUBSCRIBER_TABLE` constants instead of a nested object); keep
+//                `resolveObjectNames` so the names still come from the same resolver as the DDL.
+// use-when:      you want the physical database names (table/view + column names) for each
+//                object available as importable constants, so a hand-written consumer never
+//                has to embed a name as a string literal a second time.
+// emits:         <target>/<Entity>.names.ts per concrete object with a primary source
+//                (under outputLayout: "package", <target>/<pkg>/<Entity>.names.ts — beside
+//                the entity module it describes). An object with no primary source (#248)
+//                gets no names artifact — EXCEPT an abstract base that a sourced object
+//                extends, which gets a fragment (columns, no physical name) so its
+//                children extend it instead of restating every inherited column.
+// customize:     swap `renderNamesDecl` for your own shape; keep `resolveObjectNames` as the
+//                one resolver so the constant and the DDL it describes cannot disagree.
+// composes-with: entity.ts, routes.ts — both reference these constants instead of
+//                embedding the names a second time. queries.ts never embeds a physical
+//                name of its own: it reads/writes through the Drizzle table object
+//                entity.ts builds (columns keyed by FIELD name), so there is nothing in
+//                it to wire.
+//
+// The composition here is 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.
+import {
+  crossEntitySpecifier,
+  entityOutputPath,
+  namesArtifactSuperOf,
+  renderNamesDecl,
+  resolveObjectNames,
+  type EmittedFile,
+  type GenContext,
+  type Generator,
+} from "@metaobjectsdev/codegen-ts";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+
+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);
+          const content = renderNamesDecl(sup, {
+            strategy, superSpecifier: superSpecifierFor(sup),
+            // "Fragment" means "declares no source". Hardcoding `true` is right for the
+            // shape this pass was written for — an abstract base with columns and no table
+            // — and wrong for the one it also reaches: `meta gen --entities <Subtype>`
+            // walks up to a TPH BASE, which owns the shared table, and a fragment renders
+            // no source at all. The engine derives this itself now (`renderNamesDecl`
+            // consults the object), so the flag says only "this is an ancestor render".
+            fragment: true,
+          });
+          if (content === "") continue;
+          out.push({ path: pathOf(sup), content });
+        }
+      }
+      return out;
+    },
+  };
+}

package/src/reference/queries.ts

@@ -6,6 +6,11 @@
 // shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
 // reach for `Bun.*` globals here; they are undefined and take the whole run down with
 // `Bun is not defined`. Use `node:` builtins instead.
+// targets:       Drizzle. Emitted helpers take `db` as a PARAMETER rather than importing
+//                a module singleton, so they compose with any caller that already holds a
+//                connection — including a server-rendered component. Swap the
+//                `render<Verb>Fn` primitives (findById/list/create/update/deleteById) and
+//                the inline `Db` type block above them to emit for another query builder.
 // use-when:      you want generated typed CRUD finders (find<E>ById, list<E>s, create/update/delete)
 //                over Drizzle. Drop it if you hand-write your data access.
 // emits:         <target>/<Entity>.queries.ts per source-backed object (any source.rdb kind,
@@ -72,14 +77,21 @@ function renderQueries(obj: MetaObject, ctx: RenderContext): string {
 
   // `db` is parameter-passed into every finder (ADR-0008). Emit the dialect-correct
   // Drizzle type alias so signatures typecheck without the consumer constructing one.
+  // Keep EVERY type argument as open as Drizzle's own constraint allows — a `Db` this
+  // alias cannot name is a helper nobody can call, and uncompilable generated code looks
+  // exactly like unused generated code from outside. Both the driver axis (base classes,
+  // not `NodePgDatabase` / `<"async">`) and the schema axis (`Record<string, unknown>`,
+  // Drizzle's own `TFullSchema extends …` bound, NOT its `Record<string, never>` default)
+  // have been re-pinned once already; do not narrow either again. A schema-carrying
+  // `drizzle(client, { schema })` must assign, and so must a schema-less `drizzle(client)`.
   const dbTypeImport =
     ctx.dialect === "postgres"
       ? `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`
       : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
   const dbTypeAlias =
     ctx.dialect === "postgres"
-      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`
-      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`;
+      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;`
+      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown, Record<string, unknown>>;`;
 
   const literalImports = code`
 ${dbTypeImport}

package/src/reference/routes-hono.ts

@@ -0,0 +1,113 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/routes-hono.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { routesFileHono } from "./codegen/generators/routes-hono.js";
+//
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`.
+// targets:       Hono. The emitted file imports `mountCrudRoutes` from
+//                `@metaobjectsdev/runtime-ts/hono` and takes its persistence client as
+//                INJECTED DEPS (`register<Entity>Routes(app, { db })`) rather than a
+//                module-singleton import — which is what makes it portable to any host
+//                that can hand Hono a request. If your framework is not Hono, THIS is the
+//                file to retarget: swap the mount helper and the exported signature; the
+//                metadata walk above it is framework-neutral and stays as-is.
+// use-when:      you want generated Hono CRUD routes per entity.
+// emits:         <target>/<Entity>.routes.hono.ts — full CRUD for write-through entities,
+//                read-only (GET list + GET :id) for projections. Skipped for any sourceless
+//                object and for TPH subtypes.
+// customize:     this generator is YOURS — edit it freely. For the emitted route
+//                composition, call `renderRoutesFileHono` (exported from the engine) and
+//                wrap its result, or replace the call entirely. Decide per generator what
+//                you consume: wire only the generators whose output you actually import,
+//                and narrow this one with its `filter`. There is no `@emit*` metadata
+//                attribute — those were never registered vocabulary, so `meta verify`
+//                rejects them (ERR_UNKNOWN_ATTR).
+// composes-with: entity.ts (imports the table/schemas/allowlists), queries.ts.
+
+import { type MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type Generator,
+  type GeneratorFactory,
+  renderRoutesFileHono,
+  resolveExpose,
+  type ExposeOption,
+  isTphSubtype,
+  hasAnyRdbSource,
+  formatTs,
+  entityOutputPath,
+} from "@metaobjectsdev/codegen-ts";
+
+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;
+}
+
+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.
+  // (Same shape as tanstack's grid generator, which factors it the same way.)
+  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,
+    // 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
+    // get/patch/delete by id happily operated on rows belonging to a different
+    // subtype. Silently wrong data, which is worse than no route. Fastify dispatches
+    // 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) => 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) => 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(", ")} — ` +
+          "the Hono adapter has no discriminator scoping yet, so per-subtype CRUD would " +
+          "return and mutate OTHER subtypes' rows. Use routesFile() (Fastify), which " +
+          "dispatches TPH correctly, or hand-write the scoped routes.",
+        );
+      }
+      return emit(ctx);
+    },
+  };
+  const emit = perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("routes-file-hono: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(
+          ctx.config.outputLayout ?? "flat",
+          entity.package,
+          `${entity.name}.routes.hono.ts`,
+        ),
+        content: await formatTs(renderRoutesFileHono(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
+      };
+  });
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<RoutesFileHonoOpts>;