@metaobjectsdev/codegen-ts 0.23.1 → 0.24.0

package/src/runner.ts

@@ -14,13 +14,19 @@ import type { ResolvedTarget } from "./import-path.js";
 import { buildPkMap } from "./pk-resolver.js";
 import { buildRelationMap } from "./relation-resolver.js";
 import { makeRenderContext } from "./render-context.js";
+import { sweepOrphans, type OrphanJob } from "./orphan-sweep.js";
+import { refusedOrphanMessage } from "./reconcile-orphans.js";
 import {
   decideAndWrite,
+  previewWriteStatus,
+  hasHashManifest,
+  listGeneratedPaths,
   loadEngineVersion,
   saveEngineVersion,
   type WriteResult,
   type MergeStrategy,
   type BaselineMode,
+  type DecideAndWriteOpts,
 } from "./overwrite-policy.js";
 
 /** JS-identifier-shape only. Prevents filesystem traversal when metadata comes
@@ -60,6 +66,41 @@ export interface RunGenOpts {
    * `--dry-run`, and watching it reappear.
    */
   dryRun?: boolean;
+  /**
+   * Output scope — an object is generated only when this predicate returns true
+   * for its fully-qualified name (`obj.resolutionKey()`, `<package>::<name>`).
+   * Intersects with `entityFilter`: both must pass. Absent ⇒ every object is
+   * in scope (byte-identical to a project with no `scope` declared).
+   *
+   * The collection metadata always loads in FULL regardless of this predicate —
+   * scope filters OUTPUT, never input (design §4.3). So an in-scope object may
+   * reference an out-of-scope one (an FK target, a relationship `@objectRef`, a
+   * projection's base) and resolve perfectly at load time, while the code
+   * emitted FOR the in-scope object still imports/names a symbol that was never
+   * generated. This is left silent by design, not auto-widened: the adopter
+   * declared the scope precisely because something else (another consumer,
+   * another codegen run) owns those objects, and the reference is real. Warning
+   * on it correctly would require walking every reference kind (identity.reference,
+   * every relationship.* @objectRef, projection extends bases, field.object
+   * @objectRef) FQN-resolved against the SAME scope — genuinely new machinery,
+   * not a fit for the existing `warnings: string[]` channel at this seam. If an
+   * adopter hits it, the failure is a plain compiler error in the generated
+   * code (an unresolved import) — loud, at build time, not silent at runtime.
+   *
+   * Deliberately a PLAIN PREDICATE, not the `include`/`exclude` pattern strings
+   * `@metaobjectsdev/sdk`'s `scope.ts` compiles. `codegen-ts` must not depend on
+   * `@metaobjectsdev/sdk` — the dependency runs the other way (`cli` depends on
+   * both) — so it cannot import `matchesScope`/`CompiledScope` itself. The
+   * design's "package patterns, never a predicate function" rule (§4.3 of the
+   * metadata-source-resolution design doc) governs CONFIG SURFACES that must
+   * port identically to a `pom.xml` / `metaobjects.config.yaml` in every
+   * language port; it says nothing about internal plumbing between two
+   * TypeScript packages in this one repo. Do not "fix" this into a config
+   * shape — `cli`'s `gen`/`verify` commands are the only callers, and a
+   * `Collection` already exposes exactly this predicate as `inScope`, which
+   * they pass straight through.
+   */
+  scope?: (fqn: string) => boolean;
 }
 
 export interface RunGenResult {
@@ -112,6 +153,12 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // since the last gen, note it (generated output may legitimately differ). Purely
   // informational — the version file is separate from `.hashes.json` and never
   // affects the merge. Only fires when a prior stamp exists AND differs.
+  // Captured BEFORE any write, because the first write creates the manifest — read
+  // it afterwards and every project looks migrated.
+  const hadHashManifest = hasHashManifest(genStateDir);
+  const relativeForDisplay = (p: string): string =>
+    projectRoot !== undefined ? relative(projectRoot, p) : p;
+
   const hasPersistentGenState = opts.projectRoot !== undefined || opts.genStateDir !== undefined;
   const installedEngine = hasPersistentGenState ? engineVersion() : undefined;
   const recordedEngine = hasPersistentGenState ? loadEngineVersion(genStateDir) : undefined;
@@ -136,16 +183,46 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   }
   const root = opts.metadata;
 
-  // 1. Resolve entities (filter + safety check).
+  // 1. Resolve entities (entityFilter + scope + safety check). This is the
+  // single choke point for entity selection — scope INTERSECTS entityFilter
+  // (an object must pass both), matched against the object's
+  // fully-qualified name (resolutionKey(), never the bare name — two
+  // packages may declare the same short name).
   const allObjects = root.objects();
   const entityFilter = opts.entityFilter;
-  const filtered = entityFilter
+  const afterEntityFilter = entityFilter
     ? allObjects.filter((o) => entityFilter.includes(o.name))
     : allObjects;
+  const scope = opts.scope;
+  const filtered = scope
+    ? afterEntityFilter.filter((o) => scope(o.resolutionKey()))
+    : afterEntityFilter;
   if (filtered.length === 0) {
-    const reason = opts.entityFilter
-      ? "no object children match the provided entityFilter"
-      : "root has no object children";
+    // Name the REAL cause. When `scope` is absent, this is byte-identical to
+    // the pre-scope two-way branch (kept as its own arm, rather than folded
+    // into the scope-aware logic below, so an unscoped project's warning text
+    // — including its quirky edge case: an empty root with entityFilter set
+    // still blames entityFilter — is untouched). Only when `scope` is
+    // present does a THIRD reason become reachable: "root has no object
+    // children" for a scoped-out model, or "...entityFilter" for a scope
+    // that admitted everything entityFilter then excluded, are both false
+    // statements that send the reader to the wrong file.
+    let reason: string;
+    if (scope === undefined) {
+      // Byte-identical to the pre-scope branch, quirk included: an EMPTY root
+      // with an entityFilter set still blames the filter. Wrong, and untouched
+      // — changing what an unscoped project reads is a behaviour change, and
+      // this is a shape change.
+      reason = entityFilter
+        ? "no object children match the provided entityFilter"
+        : "root has no object children";
+    } else if (allObjects.length === 0) {
+      reason = "root has no object children";
+    } else if (afterEntityFilter.length === 0) {
+      reason = "no object children match the provided entityFilter";
+    } else {
+      reason = "no object children match the configured scope";
+    }
     warnings.push(`No entities to generate — ${reason}.`);
     return { files: [], warnings, conflicts: [] };
   }
@@ -218,16 +295,25 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   const entityGen = config.generators.find((g) => g.emitsEntityModule);
   const entityModuleTarget = entityGen ? targetOf(entityGen) : targets[DEFAULT_TARGET_NAME]!;
 
-  const needsCrossTarget = config.generators.some(
-    (g) => (g.target ?? DEFAULT_TARGET_NAME) !== entityModuleTarget.name,
-  );
-  if (needsCrossTarget && entityModuleTarget.importBase === undefined) {
-    throw new Error(
-      `Target "${entityModuleTarget.name}" holds the entity modules that other ` +
-      `targets import, but has no importBase. Set importBase on it (e.g. ` +
-      `"@your-pkg/database/generated").`,
-    );
-  }
+  // NO eager importBase check here, deliberately.
+  //
+  // There used to be one: "any generator on a non-entity target ⇒ the entity
+  // target must have importBase". It asked the wrong question — target placement,
+  // not whether anything actually imports across targets — so it convicted every
+  // multi-target project whose second target imports nothing, and the only way
+  // out was to set a value that is provably inert. An adopter hit this with a
+  // requirement-test target that imports no entity modules at all.
+  //
+  // `crossTargetEntityPath` (import-path.ts) is the SOLE consumer of importBase
+  // and already throws when it is missing, naming the resolution that needed it —
+  // and every cross-target entry point (`entityModuleSpecifier`,
+  // `barrelModuleSpecifier`) routes through it. That throw happens inside phase 4,
+  // before the write phase, and the runner tags it with the generator name, so
+  // the diagnostic is strictly better than the one removed here.
+  //
+  // The trade, stated: a generator whose cross-target import is CONDITIONAL now
+  // fails when a model change first makes it real, rather than at config time.
+  // That is the correct moment — it is also the only moment the answer is known.
 
   // 3. Build shared render state once.
   const pkMap = buildPkMap(root);
@@ -272,6 +358,10 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
 
   // 4. Run each generator with a per-target render context; collect with full path.
   const emitted: { fullPath: string; content: string; generatedBy: string }[] = [];
+  // FR-038 §8 — generators that opted into orphan reconciliation, paired with the
+  // directory their policy's relative paths are measured from. Collected here
+  // because `writeOutDir` is resolved per generator inside this loop.
+  const orphanJobs: OrphanJob[] = [];
   for (const generator of config.generators) {
     // ADR-0025: `meta docs` is the single docs door. A `meta gen` config that
     // still lists a deprecated doc generator is warned + skipped, not run — the
@@ -294,6 +384,13 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     const writeOutDir = projectRoot !== undefined && !isAbsolute(selfTarget.outDir)
       ? resolve(projectRoot, selfTarget.outDir)
       : selfTarget.outDir;
+    if (generator.orphanPolicy !== undefined) {
+      orphanJobs.push({
+        generatorName: generator.name,
+        writeOutDir,
+        policy: generator.orphanPolicy,
+      });
+    }
     const renderContext = makeRenderContext({
       dialect: config.dialect,
       loadedRoot: root,
@@ -367,17 +464,156 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   const writes: WriteResult[] = [];
   const conflicts: WriteResult[] = [];
 
+  // FR-038 §8 — reconcile files a previous run generated that this run does not.
+  //
+  // Gated on a real `projectRoot` for a load-bearing reason, not caution: without
+  // one, `decideAndWrite` keys each snapshot by a hash of its absolute path
+  // instead of a project-relative path, so gen-state holds no path to resolve and
+  // reconciliation has nothing to reason about. That gate is also what keeps
+  // `verify --codegen` inert — it runs against a throwaway root whose gen-state is
+  // empty — and what keeps programmatic/test callers from ever deleting a file.
+  // Refusals are reported ONE of two ways, and which one matters more than the
+  // wording. A project with no manifest at all predates the manifest being
+  // committed: every refusal in it has the SAME single cause and the same one-line
+  // fix, so N per-file warnings would be a wall that buries the instruction — the
+  // hostile-first-contact outcome that gets a tool switched off. A project that DOES
+  // have a manifest is refusing because specific files were edited, and there the
+  // per-file naming is the actionable part.
+  //
+  // Self-extinguishing: once the manifest is committed, the aggregate never fires
+  // again.
+  const MAX_NAMED = 5;
+  const reportRefusals = (): void => {
+    const refused = writes.filter((w) => w.status === "refused");
+    if (refused.length === 0) return;
+
+    if (!hadHashManifest) {
+      const names = refused.slice(0, MAX_NAMED).map((w) => relativeForDisplay(w.path));
+      const more = refused.length > MAX_NAMED ? `, and ${refused.length - MAX_NAMED} more` : "";
+      warnings.push(
+        `Refused to overwrite ${refused.length} existing file(s), and this project has ` +
+        `no codegen hash manifest — so 'meta gen' cannot tell your edits from its own ` +
+        `stale output, and it will not guess. This is the expected first run for a ` +
+        `project created before the manifest was committed. ` +
+        `ONE-TIME FIX: commit '.metaobjects/.gen-state/.hashes.json' (un-ignore it in ` +
+        `.metaobjects/.gitignore with '.gen-state/*' + '!.gen-state/.hashes.json'), ` +
+        `then re-run. To adopt fresh output and DISCARD any hand edits in these files ` +
+        `instead, re-run with --baseline=fresh. Files: ${names.join(", ")}${more}.`,
+      );
+      return;
+    }
+
+    for (const w of refused) {
+      warnings.push(
+        `Refused to overwrite ${w.path}: ${w.conflictHint ?? "content differs and could not be verified as generated."}`,
+      );
+    }
+  };
+
+  const sweep = (dryRun: boolean): void => {
+    if (projectRoot === undefined || orphanJobs.length === 0) return;
+
+    // NEVER reconcile a PARTIAL run. `meta gen <entity>` narrows the object set, so
+    // `emitted` is a subset of the full output BY CONSTRUCTION — every path belonging
+    // to an unselected entity looks exactly like an orphan, and the untouched ones get
+    // deleted. The shipped `requirementTests()` escapes only by accident (it walks
+    // `ctx.loadedRoot` and ignores `ctx.matches`); any app generator that honours
+    // `ctx.matches` — the documented, encouraged composition — would wipe every
+    // non-selected entity's output on a routine filtered run.
+    //
+    // The runner is the ONLY layer that knows the run was partial: a generator sees a
+    // narrowed entity list and cannot tell it from a model that genuinely has one
+    // entity. So the guard has to live here.
+    if (opts.entityFilter !== undefined && opts.entityFilter.length > 0) {
+      // Say it only when something was ACTUALLY withheld. With no previously-generated
+      // path outside this run's own output there are no orphan candidates at all, so
+      // the sweep provably no-ops and there is nothing to report. `meta gen <entity>`
+      // is a routine command; warning on every one of them teaches the reader to skim
+      // the message, which is how the real one gets skimmed too.
+      //
+      // Note the manifest is NOT empty here even on a first run — the writes above have
+      // already recorded this run's own paths in it — so the emitted set has to come
+      // out before counting. Computing the candidate set is safe on a filtered run;
+      // what must never happen is ACTING on it.
+      //
+      // A non-empty candidate set is the FLOOR, not proof that a specific file would
+      // have been removed: whether one falls inside an opting-in generator's namespace
+      // is the reconcile's answer, and running that is the thing being skipped.
+      const emittedRel = new Set(emitted.map((f) => relative(projectRoot, f.fullPath)));
+      const withheld = listGeneratedPaths(genStateDir).filter((p) => !emittedRel.has(p));
+      if (withheld.length > 0) {
+        warnings.push(
+          `Skipped orphan cleanup: this run generated only ${opts.entityFilter.join(", ")}, ` +
+          `so it cannot tell a file belonging to an unselected entity from one that is no ` +
+          `longer generated. Run 'meta gen' with no entity filter to reconcile deletions.`,
+        );
+      }
+      return;
+    }
+    const result = sweepOrphans({
+      genStateDir,
+      projectRoot,
+      emittedRelPaths: emitted.map((f) => relative(projectRoot, f.fullPath)),
+      jobs: orphanJobs,
+      dryRun,
+    });
+    // Both kinds are the same file outcome — gone. What differs is what it cost,
+    // which is what the warning below is for.
+    for (const relPath of [...result.removed, ...result.forced]) {
+      writes.push({ path: join(projectRoot, relPath), status: "removed" });
+    }
+    if (result.refused.length > 0) {
+      // Grouped by the generator that refused, so each message names a generator the
+      // project actually registered. `orphanPolicy` is generic and apps are encouraged
+      // to compose their own, so one blanket message naming `requirement-tests` would
+      // be wrong for precisely the users the seam exists for.
+      const byGenerator = new Map<string, string[]>();
+      for (const relPath of result.refused) {
+        const owner = result.refusedBy.get(relPath) ?? "orphan cleanup";
+        const list = byGenerator.get(owner);
+        if (list === undefined) byGenerator.set(owner, [relPath]);
+        else list.push(relPath);
+      }
+      for (const [owner, paths] of byGenerator) {
+        warnings.push(refusedOrphanMessage(paths, owner));
+      }
+    }
+    if (result.forced.length > 0) {
+      warnings.push(
+        `Deleted ${result.forced.length} hand-edited generated file(s) because a ` +
+        `generator's orphanPolicy sets force: ${result.forced.join(", ")}. ` +
+        `Hand-written content in them is gone — recover from version control.`,
+      );
+    }
+  };
+
   // --dry-run: report what WOULD be written and touch nothing — no output files
   // and no .gen-state/ snapshot (writing the snapshot would silently re-baseline
   // the merge base, so a later real run could skip a genuinely-needed write).
   if (opts.dryRun === true) {
     for (const file of emitted) {
-      // Report the outcome faithfully rather than a placeholder: a path that does
-      // not exist yet would be created ("new"), one that does would be rewritten.
-      // Merge/conflict outcomes can't be known without doing the merge, so this
-      // deliberately reports the coarser truth instead of guessing.
-      writes.push({ path: file.fullPath, status: existsSync(file.fullPath) ? "overwrite" : "new" });
+      // Ask the same policy the real run asks, in a read-only mode. This used to be
+      // `existsSync(...) ? "overwrite" : "new"`, which previewed a hand-edited file
+      // as "overwrite" while the real run refused it — the one case the preview most
+      // needs to be right about. A merge outcome is still coarse (see
+      // previewWriteStatus), because clean-vs-conflicted is unknowable without merging.
+      const policyOpts: DecideAndWriteOpts = {
+        strategy,
+        genStateDir,
+        baseline,
+      };
+      if (projectRoot !== undefined) {
+        policyOpts.outputRelPath = relative(projectRoot, file.fullPath);
+      }
+      writes.push({
+        path: file.fullPath,
+        status: previewWriteStatus(file.fullPath, file.content, policyOpts),
+      });
     }
+    reportRefusals();
+    // A preview that hides a pending deletion is worse than no preview at all, so
+    // the sweep still runs — in decide-and-report mode, touching nothing.
+    sweep(true);
     return { files: writes, warnings, conflicts };
   }
 
@@ -386,7 +622,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     // distinct entries (e.g. `database/Post.ts` vs `web/Post.queries.ts`).
     // Without an explicit projectRoot we let decideAndWrite derive a stable
     // hash-of-path key — fine for ephemeral test runs.
-    const policyOpts: import("./overwrite-policy.js").DecideAndWriteOpts = {
+    const policyOpts: DecideAndWriteOpts = {
       strategy,
       genStateDir,
       baseline,
@@ -403,14 +639,17 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         `'meta gen' to advance the canonical state.`,
       );
     }
-    if (result.status === "refused") {
-      warnings.push(
-        `Refused to overwrite ${file.fullPath}: file exists without @generated header. ` +
-        `Move to a different outDir, delete the file, or add the header to opt in.`,
-      );
-    }
+    // Refusals are reported together after the loop (see reportRefusals) so a
+    // whole-project cause can be stated once instead of once per file.
   }
 
+  reportRefusals();
+
+  // Sweep AFTER the writes: writing is the primary job, and a deletion that runs
+  // first would be unrecoverable if a later write threw. Ordering cannot change
+  // the decision — a path this run emitted is never an orphan either way.
+  sweep(false);
+
   // #232 — stamp the engine version that produced this snapshot, so the NEXT gen can
   // detect an engine change. Written after a successful run only.
   if (installedEngine !== undefined) saveEngineVersion(genStateDir, installedEngine);

package/src/templates/drizzle-schema.ts

@@ -13,7 +13,7 @@ import {
 } from "@metaobjectsdev/metadata";
 import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
 import { crossEntitySpecifier, valueObjectModuleSpecifier } from "../import-path.js";
-import { mapColumnType, type ColumnSpec } from "../column-mapper.js";
+import { mapColumnType, type ColumnSpec, type EnumIntCustomType } from "../column-mapper.js";
 import { tableNameFromEntity, columnNameFromField } from "../naming.js";
 import { renderRelationsBlock } from "./relations-block.js";
 import { renderDocsFor } from "./jsdoc.js";
@@ -66,6 +66,9 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   const columnLines: Code[] = [];
   // Collect CHECK constraints for enum columns; emitted as table-level check() callbacks.
   const checkConstraints: Array<{ name: string; expr: string }> = [];
+  // Int-backed field.enum customType helpers, emitted ahead of the table. Keyed by
+  // const name so a shared enum used by two fields of the SAME entity emits once.
+  const enumIntTypes = new Map<string, EnumIntCustomType>();
   for (const child of obj.fields()) {
     // #213 — a derived (origin-bearing) field is read-only, materialized on the
     // read (view) side, NOT a column on the entity's write table (FR-024 §7).
@@ -78,6 +81,9 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     // Compute the column spec once per field and reuse it for both the column
     // line and the CHECK collection.
     const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy, ctx.timestampMode);
+    if (spec.enumIntCustomType !== undefined) {
+      enumIntTypes.set(spec.enumIntCustomType.fnConstName, spec.enumIntCustomType);
+    }
     const fieldDocs = renderDocsFor(child);
     const columnLine = renderColumn(spec, child, ctx, isPk, pkGeneration, fkInfo, isComposite, isUnique, obj.package, obj.name);
     columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
@@ -103,6 +109,9 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     // #213 — a TPH subtype's derived field is read-only too; never a table column.
     if (child.isDerived()) continue;
     const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy, ctx.timestampMode);
+    if (spec.enumIntCustomType !== undefined) {
+      enumIntTypes.set(spec.enumIntCustomType.fnConstName, spec.enumIntCustomType);
+    }
     const fieldDocs = renderDocsFor(child);
     const columnLine = renderColumn(
       spec, child, ctx, false, undefined, fkMap.get(child.name), isComposite, false, obj.package, obj.name, true,
@@ -177,11 +186,60 @@ ${joinCode(columnLines, { on: ",\n", trim: false })}
   // Emit the relations() block (returns null if no relations).
   const relationsBlock = renderRelationsBlock(obj, ctx);
 
-  if (relationsBlock === null) {
-    return tableBlock;
-  }
+  // Int-backed enum codecs are declared BEFORE the table that references them.
+  // Sorted by const name so output is deterministic regardless of field order.
+  const enumIntBlocks = [...enumIntTypes.values()]
+    .sort((a, b) => a.fnConstName.localeCompare(b.fnConstName))
+    .map((t) => renderEnumIntCustomType(t, importModule));
 
-  return joinCode([tableBlock, relationsBlock], { on: "\n" });
+  const blocks: Code[] = [...enumIntBlocks, tableBlock];
+  if (relationsBlock !== null) blocks.push(relationsBlock);
+  return blocks.length === 1 ? blocks[0]! : joinCode(blocks, { on: "\n" });
+}
+
+/**
+ * Render an int-backed `field.enum`'s Drizzle `customType` helper plus its two
+ * lookup maps.
+ *
+ * The codec lives HERE, in the column definition, so nothing downstream needs to
+ * know about it: `db.insert().values()` encodes on bind, a selected row decodes on
+ * read, and a filter comparison encodes because Drizzle binds through the column
+ * type. That is why this shape was chosen over a Zod write-transform plus a
+ * generated read-decode — TS's generated queries return raw Drizzle rows and have
+ * no decode seam, so the query-layer approach meant inventing one and wrapping
+ * every generated read. It is also the direct analogue of what the other four
+ * ports already do (EF Core `HasConversion`, OMDB `JdbcFieldCodec`, Exposed
+ * `customEnumeration`, Python `ObjectManager` coercion).
+ *
+ * `fromDriver` throws on an unmapped integer rather than returning undefined: a
+ * value outside the map means the DB holds data the model says is impossible
+ * (a hand-written INSERT, or a member removed without a migration), and silently
+ * yielding `undefined` for a non-nullable field would surface far from the cause.
+ */
+function renderEnumIntCustomType(t: EnumIntCustomType, importModule: string): Code {
+  const customTypeSym = imp(`customType@${importModule}`);
+  const union = t.members.map((m) => JSON.stringify(m)).join(" | ");
+  const toEntries = t.members
+    .map((m) => `${JSON.stringify(m)}: ${t.intByMember[m]}`)
+    .join(", ");
+  const fromEntries = t.members
+    .map((m) => `${t.intByMember[m]}: ${JSON.stringify(m)}`)
+    .join(", ");
+  return code`
+const ${t.toIntConstName} = { ${toEntries} } as const satisfies Record<${union}, number>;
+const ${t.fromIntConstName}: Record<number, ${union}> = { ${fromEntries} };
+const ${t.fnConstName} = ${customTypeSym}<{ data: ${union}; driverData: number }>({
+  dataType: () => ${JSON.stringify(t.dataType)},
+  toDriver: (value) => ${t.toIntConstName}[value],
+  fromDriver: (value) => {
+    const member = ${t.fromIntConstName}[value];
+    if (member === undefined) {
+      throw new Error(\`unmapped ${t.fnConstName} value: \${value}\`);
+    }
+    return member;
+  },
+});
+`;
 }
 
 interface FkInfo {
@@ -266,7 +324,13 @@ function renderColumn(
   // and suppress any DB default (other-subtype rows must stay NULL here).
   forceNullable: boolean = false,
 ): Code {
-  const fnSym = imp(`${spec.fnName}@${spec.importModule}`);
+  // An int-backed field.enum's column function is a LOCAL generated const (the
+  // customType helper emitted into this same file), so it must not be imported
+  // from drizzle-orm/*-core like a built-in column type would be.
+  const fnSym =
+    spec.enumIntCustomType !== undefined
+      ? spec.enumIntCustomType.fnConstName
+      : imp(`${spec.fnName}@${spec.importModule}`);
 
   const dbNameLit = JSON.stringify(spec.dbName);
   let baseCall: Code;

package/src/templates/extractor.ts

@@ -24,15 +24,15 @@ import {
   type MetaData,
   type MetaField,
   TYPE_TEMPLATE,
-  TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_SUBTYPE_PROMPT,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_OBJECT_REF,
   FIELD_ATTR_REQUIRED,
-  TEMPLATE_ATTR_PAYLOAD_REF,
-  TEMPLATE_ATTR_FORMAT,
+  TEMPLATE_ATTR_RESPONSE_REF,
   resolveObjectRef,
 } from "@metaobjectsdev/metadata";
+import { responseShape } from "./find-inbound.js";
 import { fields, isArray } from "./fr010-field-mapping.js";
 import { mirrorName } from "./extract-delegate-emitter.js";
 import { enumUnionAliasName } from "./inferred-types.js";
@@ -288,36 +288,31 @@ function reachableMirrorTypes(vo: MetaData, root: MetaData, rootMirror: string,
 }
 
 /**
- * Render the full `<TemplateName>.extractor.ts` for one `template.output` node.
- * Throws if the template isn't found / isn't a template.output / its @payloadRef doesn't resolve,
- * or if the target format is not json/xml (the extract tier requires the extract<Name> API, which
- * only the json/xml output-parsers emit).
+ * Render the full `<PromptName>.extractor.ts` for one responding `template.prompt`.
+ * Throws if the template isn't found / isn't a template.prompt / its @responseRef
+ * doesn't resolve. ADR-0052: no format gate remains — @responseFormat is a closed
+ * json|xml set, so every responding prompt has an extract<Name> API to sit over.
  */
 export function renderExtractor(root: MetaData, templateName: string, ctx?: RenderContext): string {
   const tmpl = findTemplate(root, templateName);
   if (!tmpl) {
     throw new Error(`template "${templateName}" not found in metadata root`);
   }
-  if (tmpl.subType !== TEMPLATE_SUBTYPE_OUTPUT) {
-    throw new Error(`template "${templateName}" is not a template.output (got subtype "${tmpl.subType}")`);
+  if (tmpl.subType !== TEMPLATE_SUBTYPE_PROMPT) {
+    throw new Error(`template "${templateName}" is not a template.prompt (got subtype "${tmpl.subType}")`);
   }
-  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
-  const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
-  if (typeof payloadRef !== "string") {
-    throw new Error(`template "${templateName}" missing @payloadRef`);
-  }
-  // ADR-0042: a bare @payloadRef resolves in the template's package.
-  const vo = findObject(root, payloadRef, tmpl.package ?? tmpl.fileDefaultPackage ?? "");
-  if (!vo) {
-    throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
-  }
-  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
-  const format = ((tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
-  if (format !== "json" && format !== "xml") {
+  // ADR-0052: the extract tier reads a REPLY, so it binds @responseRef.
+  const shape = responseShape(root, tmpl);
+  if (!shape) {
+    // ADR-0039: resolving — @responseRef may be inherited via extends.
+    const declared = tmpl.attr(TEMPLATE_ATTR_RESPONSE_REF);
     throw new Error(
-      `template "${templateName}" @format "${format}" has no extract API to extract over (json/xml only)`,
+      typeof declared === "string"
+        ? `template "${templateName}" @responseRef "${declared}" not found in metadata root`
+        : `template "${templateName}" missing @responseRef`,
     );
   }
+  const { vo } = shape;
 
   // ADR-0044/#228: the strict payload TYPE name is the entity-domain EMITTED name (Task 3's
   // `valueObjectEmittedName`) — the SAME name entityFile() declared the interface under, so a
@@ -349,7 +344,7 @@ export function renderExtractor(root: MetaData, templateName: string, ctx?: Rend
     `// arrays-of-objects populated) in one call, by delegating to the nested-capable extract and\n` +
     `// 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 {\n  ${extractLenientWithName},\n  type ${mirrorTypes.join(",\n  type ")},\n} from "./${templateName}.response.js";\n` +
     `${payloadImports}\n` +
     `import type { MetaRoot } from "@metaobjectsdev/metadata";\n` +
     `import type { ExtractionResult } from "@metaobjectsdev/render";\n` +

package/src/templates/filter-allowlist.ts

@@ -13,7 +13,7 @@ import {
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_CURRENCY,
-  opsForSubType,
+  opsForField,
 } from "@metaobjectsdev/metadata";
 import { sortableFields } from "./filter-shared.js";
 import type { RenderContext } from "../render-context.js";
@@ -72,7 +72,9 @@ export const ${entity.name}FilterAllowlist = {} as const satisfies FilterAllowli
   }
   const rows = fields
     .map((f) => {
-      const ops = opsForSubType(f.subType).map((o) => JSON.stringify(o)).join(", ");
+      // opsForField, not opsForSubType — an int-backed field.enum (@intValueMap)
+      // stores as an integer, so `like` (a substring match) is not in its band.
+      const ops = opsForField(f).map((o) => JSON.stringify(o)).join(", ");
       const sub = filterSubTypeFor(f.subType);
       // Only field.timestamp is governed by timestampMode — Drizzle types
       // field.date / field.time as strings under every dialect.

package/src/templates/filter-type.ts

@@ -11,7 +11,7 @@ import {
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
-  opsForSubType,
+  opsForField,
 } from "@metaobjectsdev/metadata";
 import { isSortableField } from "./filter-shared.js";
 
@@ -34,7 +34,11 @@ function tsNameFor(fieldSubType: string): string {
 }
 
 function renderFieldUnion(field: MetaField): string {
-  const ops = opsForSubType(field.subType);
+  // opsForField, not opsForSubType — an int-backed field.enum (@intValueMap) stores
+  // as an integer, so `like` is not in its band. The client type and the server
+  // allowlist MUST agree: offering `like` here that the allowlist 400s is a
+  // client/server mismatch of exactly the kind filter-shared.ts exists to prevent.
+  const ops = opsForField(field);
   const tsName = tsNameFor(field.subType);
   const opEntries = ops.map((op) => {
     if (op === "in") return `in?: ${tsName}[]`;