@metaobjectsdev/codegen-ts 0.6.0 → 0.7.0-rc.2

package/src/index.ts

@@ -44,4 +44,4 @@ export { emitViewDdl } from "./projection/view-ddl-emit.js";
 export type { EmitOptions as ViewDdlEmitOptions } from "./projection/view-ddl-emit.js";
 export type { JoinNode, JoinTree, SelectColumn, SelectSpec, ViewSpec } from "./projection/view-spec.js";
 // Prompt construction (FR-004): typed payload + render-handle codegen.
-export { generatePayloadInterfaces, generateRenderHandle } from "./payload-codegen.js";
+export { generatePayloadInterfaces, generatePayloadInterfacesBatch, generateRenderHandle } from "./payload-codegen.js";

package/src/metaobjects-config.ts

@@ -1,9 +1,11 @@
+import { DEFAULT_COLUMN_NAMING_STRATEGY, type ColumnNamingStrategy } from "@metaobjectsdev/metadata";
 import type { Generator } from "./generator.js";
 import type { ExtStyle } from "./render-context.js";
 import type { OutputLayout, ResolvedTarget } from "./import-path.js";
 
 export type Dialect = "sqlite" | "postgres";
-export type ColumnNamingStrategy = "snake_case" | "literal" | "kebab-case";
+/** Re-exported from metadata so codegen-ts consumers see one canonical type. */
+export type { ColumnNamingStrategy } from "@metaobjectsdev/metadata";
 export type { ExtStyle };
 export type { OutputLayout };
 export type { ResolvedTarget };
@@ -87,7 +89,7 @@ export function resolveTargets(config: MetaobjectsGenConfig): Record<string, Res
 export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobjectsGenConfig {
   return {
     ...config,
-    columnNamingStrategy: config.columnNamingStrategy ?? "snake_case",
+    columnNamingStrategy: config.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY,
     apiPrefix: config.apiPrefix ?? "",
     outputLayout: config.outputLayout ?? "flat",
     targets: resolveTargets(config),

package/src/naming.ts

@@ -1,32 +1,19 @@
 // Naming helpers — case conversion + pluralization for codegen output.
-// All functions are pure.
+// All functions are pure. The strategy primitives (toSnakeCase, toKebabCase,
+// applyColumnNamingStrategy, pluralize, DEFAULT_COLUMN_NAMING_STRATEGY) are
+// re-exported from @metaobjectsdev/metadata so codegen + runtime + migrate
+// share a single source of truth for how field/table names lower to columns.
 
-import type { ColumnNamingStrategy } from "./metaobjects-config.js";
+import {
+  applyColumnNamingStrategy,
+  DEFAULT_COLUMN_NAMING_STRATEGY,
+  pluralize,
+  toKebabCase,
+  toSnakeCase,
+  type ColumnNamingStrategy,
+} from "@metaobjectsdev/metadata";
 
-/**
- * Convert PascalCase or camelCase to snake_case.
- * Treats consecutive capitals (e.g., "APIKey") as a single word: "api_key".
- */
-export function toSnakeCase(s: string): string {
-  return s
-    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
-    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
-    .toLowerCase();
-}
-
-/** Convert PascalCase or camelCase to kebab-case. */
-function toKebabCase(s: string): string {
-  return toSnakeCase(s).replace(/_/g, "-");
-}
-
-/** Apply a ColumnNamingStrategy to a name. */
-function applyStrategy(name: string, strategy: ColumnNamingStrategy): string {
-  switch (strategy) {
-    case "snake_case": return toSnakeCase(name);
-    case "literal":    return name;
-    case "kebab-case": return toKebabCase(name);
-  }
-}
+export { pluralize, toSnakeCase } from "@metaobjectsdev/metadata";
 
 /**
  * Convert snake_case to camelCase. Preserves already-camelCase input.
@@ -42,31 +29,20 @@ export function toPascalCase(s: string): string {
   return s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s;
 }
 
-/**
- * Simple English pluralization. Documented imperfection per design §13 #1:
- * irregular plurals (Person → Persons, not People) are not handled.
- * Users override via source[dbTable]@name in metadata.
- */
-export function pluralize(s: string): string {
-  if (/(s|x|z|ch|sh)$/i.test(s)) return s + "es";
-  if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + "ies";
-  return s + "s";
-}
-
 /** PascalCase entity → strategy-applied plural for DB table name. */
 export function tableNameFromEntity(
   entityName: string,
-  strategy: ColumnNamingStrategy = "snake_case",
+  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
 ): string {
-  return applyStrategy(pluralize(entityName), strategy);
+  return applyColumnNamingStrategy(pluralize(entityName), strategy);
 }
 
 /** camelCase or PascalCase field → strategy-applied DB column name. */
 export function columnNameFromField(
   fieldName: string,
-  strategy: ColumnNamingStrategy = "snake_case",
+  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
 ): string {
-  return applyStrategy(fieldName, strategy);
+  return applyColumnNamingStrategy(fieldName, strategy);
 }
 
 /**
@@ -78,14 +54,14 @@ export function viewNameFromProjection(
   projectionName: string,
   strategy: ColumnNamingStrategy,
 ): string {
-  switch (strategy) {
-    case "snake_case": return "v_" + toSnakeCase(projectionName);
-    case "literal":    return "v_" + projectionName;
-    case "kebab-case": return "v-" + toKebabCase(projectionName);
-  }
+  const sep = strategy === "kebab-case" ? "-" : "_";
+  return "v" + sep + applyColumnNamingStrategy(projectionName, strategy);
 }
 
 /** PascalCase entity → camelCase plural for the Drizzle table variable. */
 export function variableNameFromEntity(entityName: string): string {
   return pluralize(toCamelCase(entityName.charAt(0).toLowerCase() + entityName.slice(1)));
 }
+
+// Re-exported here for callers that import from codegen-ts's naming module.
+export { toKebabCase };

package/src/payload-codegen.ts

@@ -17,6 +17,7 @@ import {
   TYPE_TEMPLATE,
   FIELD_SUBTYPE_OBJECT,
   FIELD_ATTR_OBJECT_REF,
+  FIELD_ATTR_REQUIRED,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_FORMAT,
@@ -55,7 +56,13 @@ function fieldTsType(field: MetaData): { type: string; refVo?: string } {
     if (typeof ref === "string") result.refVo = ref;
     return result;
   }
-  return { type: SCALAR_TS[field.subType] ?? "unknown" };
+  const scalar = SCALAR_TS[field.subType] ?? "unknown";
+  return { type: field.isArray ? `${scalar}[]` : scalar };
+}
+
+/** True iff the field's @required is explicitly set to true. */
+function isFieldRequired(field: MetaData): boolean {
+  return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
 }
 
 function emitInterface(root: MetaData, voName: string, emitted: Set<string>, out: string[]): void {
@@ -67,7 +74,15 @@ function emitInterface(root: MetaData, voName: string, emitted: Set<string>, out
   const refs: string[] = [];
   for (const f of vo.children().filter((c) => c.type === TYPE_FIELD)) {
     const { type, refVo } = fieldTsType(f);
-    lines.push(`  ${f.name}: ${type};`);
+    // Required fields: `name: T;`
+    // Optional fields: `name?: T | null;` — the `| null` lets values from
+    // Drizzle entity rows (which return `null` for nullable columns) flow
+    // straight in. Without it, TS treats undefined-vs-null as a hard error
+    // at the entity → payload boundary.
+    const isRequired = isFieldRequired(f);
+    const tsType = isRequired ? type : `${type} | null`;
+    const optional = isRequired ? "" : "?";
+    lines.push(`  ${f.name}${optional}: ${tsType};`);
     if (refVo) refs.push(refVo);
   }
   lines.push("}");
@@ -82,6 +97,23 @@ export function generatePayloadInterfaces(root: MetaData, voName: string): strin
   return out.join("\n\n") + "\n";
 }
 
+/**
+ * Emit interfaces for several payloads at once, using a single shared dedupe
+ * set so nested types (e.g. lens projections referenced by multiple payloads)
+ * appear exactly once in the combined output.
+ *
+ * Returns the empty string when `voNames` is empty.
+ */
+export function generatePayloadInterfacesBatch(root: MetaData, voNames: readonly string[]): string {
+  if (voNames.length === 0) return "";
+  const out: string[] = [];
+  const emitted = new Set<string>();
+  for (const name of voNames) {
+    emitInterface(root, name, emitted, out);
+  }
+  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;
 }

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

@@ -348,7 +348,7 @@ function buildGroupBy(spec: SelectSpec): string[] {
  *                    and extends a writable entity).
  * @param root        The loader's MetaRoot — all top-level objects are
  *                    direct children of root (returned by `MetaDataLoader.load()`
- *                    / `FileMetaDataLoader.loadFiles()` as `result.root`).
+ *                    or `MetaDataLoader.fromDirectory()` as `result.root`).
  * @param ctx         Column naming strategy for SQL identifiers.
  */
 export function extractViewSpec(

package/src/source-detect.ts

@@ -0,0 +1,28 @@
+// Source-detect helpers — discriminate table-backed entities from value-only
+// objects (and other in-memory / transit shapes) by inspecting source.* children.
+//
+// Used by the entity-file composer to pick a streamlined "value-only" emission
+// path for metaobjects that declare no writable relational source. Pure
+// metadata-driven, not a typeId discriminator: any object subtype can opt out
+// of Drizzle table emission simply by omitting source.rdb.
+
+import { MetaSource } from "@metaobjectsdev/metadata";
+import { TYPE_SOURCE, SOURCE_SUBTYPE_RDB } from "@metaobjectsdev/metadata";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+
+/**
+ * True when the entity declares at least one writable source.rdb child.
+ * Discriminates table-backed entities (full Drizzle file: table + Insert/Update
+ * schemas + filter allowlists + constants) from value-only objects (TS
+ * interface + Zod schema only). Absence of source.rdb means in-memory /
+ * transit data — no migration, no ORM table to point at.
+ */
+export function hasWritableRdbSource(entity: MetaObject): boolean {
+  for (const child of entity.ownChildren()) {
+    if (child.type !== TYPE_SOURCE) continue;
+    if (child.subType !== SOURCE_SUBTYPE_RDB) continue;
+    if (!(child instanceof MetaSource)) continue;
+    if (child.isWritable()) return true;
+  }
+  return false;
+}

package/src/templates/drizzle-schema.ts

@@ -187,9 +187,17 @@ function buildCompositeKeyCallback(
   return code`${primaryKeySym}({ columns: [${columnRefs}] })`;
 }
 
-/** Build a JS-style object literal string (not JSON.stringify which uses quoted keys). */
+/** Build a JS-style object literal string (not JSON.stringify which uses quoted keys).
+ *  Array values get `as const` appended so Drizzle's text(...,{ enum: [...] })
+ *  narrows the inferred column type to a literal union instead of bare `string`. */
 function inlineObjectLiteral(obj: Record<string, unknown>): string {
-  const entries = Object.entries(obj).map(([k, v]) => `${k}: ${JSON.stringify(v)}`);
+  const entries = Object.entries(obj).map(([k, v]) => {
+    const lit = JSON.stringify(v);
+    if (Array.isArray(v)) {
+      return `${k}: ${lit} as const`;
+    }
+    return `${k}: ${lit}`;
+  });
   return `{ ${entries.join(", ")} }`;
 }
 
@@ -300,7 +308,23 @@ function renderColumn(
     ? `.$defaultFn(() => new Date().toISOString())`
     : "";
 
-  const columnLine = code`  ${field.name}: ${baseCall}${modifiersStr}${autoSetSuffix}${sqlDefaultSegment ?? ""}${fkRefSegment ?? ""}`;
+  // $type<E[]>() chain — emitted as Code (not a string modifier) so ts-poet can
+  // hoist the cross-module type import for objectRef variants. Positioned
+  // immediately after the baseCall so the chain reads `.text(...).$type<...>().notNull()...`
+  // which Drizzle accepts in any order but is conventional for "type narrowing
+  // first."
+  let dollarTypeSegment: Code | string = "";
+  if (spec.dollarTypeRef !== undefined) {
+    const ref = spec.dollarTypeRef;
+    if (ref.kind === "scalar") {
+      dollarTypeSegment = `.$type<${ref.tsType}[]>()`;
+    } else {
+      const refSym = imp(`${ref.name}@${ref.module}`);
+      dollarTypeSegment = code`.$type<${refSym}[]>()`;
+    }
+  }
+
+  const columnLine = code`  ${field.name}: ${baseCall}${dollarTypeSegment}${modifiersStr}${autoSetSuffix}${sqlDefaultSegment ?? ""}${fkRefSegment ?? ""}`;
   return spec.leadingComment !== undefined
     ? code`  // ${spec.leadingComment}\n${columnLine}`
     : columnLine;

package/src/templates/entity-file.ts

@@ -2,8 +2,9 @@
 // into one file with the @generated header. ts-poet deduplicates imports.
 //
 // Dispatch:
-//   isProjection(entity)  → renderProjectionDecl (read-only: view declaration + Zod + filter sections)
-//   vanilla / write-through entity → Drizzle table path
+//   isProjection(entity)               → renderProjectionDecl (read-only: view declaration + Zod + filter sections)
+//   !hasWritableRdbSource(entity)      → renderValueObjectFile (in-memory / transit shape: interface + Zod schema)
+//   vanilla / write-through entity     → Drizzle table path
 
 import { joinCode, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
@@ -17,8 +18,31 @@ import { renderFilterType } from "./filter-type.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { isProjection } from "../projection/projection-detector.js";
 import { renderProjectionDecl } from "./projection-decl.js";
+import { hasWritableRdbSource } from "../source-detect.js";
+import { renderValueObjectFile } from "./value-object-file.js";
+
+/**
+ * Render-time options for the entity-file composer.
+ *
+ * `allowlists` (default `true`) controls whether the Fastify-flavored
+ * `<Entity>FilterAllowlist` + `<Entity>SortAllowlist` blocks (plus their
+ * `runtime-ts/drizzle-fastify` type-only imports) are emitted. Workers/Lambda
+ * consumers that don't mount Fastify-style server routes can pass `false` and
+ * drop `@metaobjectsdev/runtime-ts` from their deps entirely. The client-side
+ * `<Entity>Filter` type is always emitted — consumers still want it for typed
+ * client calls regardless of how the server is wired.
+ */
+export interface RenderEntityFileOpts {
+  readonly allowlists?: boolean;
+}
+
+export function renderEntityFile(
+  entity: MetaObject,
+  ctx: RenderContext,
+  opts?: RenderEntityFileOpts,
+): string {
+  const allowlists = opts?.allowlists ?? true;
 
-export function renderEntityFile(entity: MetaObject, ctx: RenderContext): string {
   // --- Projection path (read-only: view-backed entity with no table source) ---
   // Projections intentionally get the z.enum() validator but NOT a named enum
   // type alias — emitting aliases here is a deliberate v1 scope decision.
@@ -30,6 +54,14 @@ export function renderEntityFile(entity: MetaObject, ctx: RenderContext): string
     });
   }
 
+  // --- Value-only path (no writable source.rdb: in-memory / transit shape) ---
+  // No Drizzle table, no migration footprint. Consumers that need to validate
+  // the shape (LLM tool_use input_schema, REST body parsing) use the Zod
+  // schema; consumers that need the type use the interface.
+  if (!hasWritableRdbSource(entity)) {
+    return renderValueObjectFile(entity);
+  }
+
   // --- Vanilla / write-through entity path ---
   const enumAliases = renderEnumTypeAliases(entity);
   const sections: Code[] = [
@@ -38,8 +70,7 @@ export function renderEntityFile(entity: MetaObject, ctx: RenderContext): string
     ...(enumAliases !== null ? [enumAliases] : []),
     renderZodValidators(entity),
     renderEntityConstants(entity, ctx.apiPrefix),
-    renderFilterAllowlist(entity),
-    renderSortAllowlist(entity),
+    ...(allowlists ? [renderFilterAllowlist(entity), renderSortAllowlist(entity)] : []),
     renderFilterType(entity),
   ];
 

package/src/templates/inferred-types.ts

@@ -1,9 +1,34 @@
 // Inferred types template — emits Drizzle's InferSelectModel / InferInsertModel type aliases,
 // plus named union types for field.enum fields.
+//
+// Also emits the structural TS interface for value-only objects (metaobjects
+// with no writable source.rdb). That path side-steps Drizzle entirely: the
+// interface is computed directly from the field tree, with `name?: T` for
+// optional fields (matching Zod's `.optional()` inference — `T | undefined` —
+// without the superfluous `| null` that Drizzle nullable columns introduce).
 
-import { code, imp, type Code } from "ts-poet";
-import type { MetaObject } from "@metaobjectsdev/metadata";
-import { FIELD_SUBTYPE_ENUM } from "@metaobjectsdev/metadata";
+import { code, imp, joinCode, type Code } from "ts-poet";
+import type { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import {
+  FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_STRING,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_CLASS,
+  FIELD_ATTR_REQUIRED,
+  FIELD_ATTR_OBJECT_REF,
+} from "@metaobjectsdev/metadata";
 import { variableNameFromEntity, toPascalCase } from "../naming.js";
 import { enumValues } from "../enum-meta.js";
 import { renderDocsFor } from "./jsdoc.js";
@@ -53,3 +78,92 @@ export function renderEnumTypeAliases(entity: MetaObject): Code | null {
 
   return lines.length > 0 ? code`${lines.join("\n")}` : null;
 }
+
+// ---------------------------------------------------------------------------
+// Value-object interface emitter
+// ---------------------------------------------------------------------------
+
+const SCALAR_TS_BY_SUBTYPE: Record<string, string> = {
+  [FIELD_SUBTYPE_STRING]: "string",
+  [FIELD_SUBTYPE_CLASS]: "string",
+  [FIELD_SUBTYPE_INT]: "number",
+  [FIELD_SUBTYPE_SHORT]: "number",
+  [FIELD_SUBTYPE_BYTE]: "number",
+  [FIELD_SUBTYPE_LONG]: "number",
+  [FIELD_SUBTYPE_DOUBLE]: "number",
+  [FIELD_SUBTYPE_FLOAT]: "number",
+  [FIELD_SUBTYPE_DECIMAL]: "number",
+  [FIELD_SUBTYPE_CURRENCY]: "number",
+  [FIELD_SUBTYPE_BOOLEAN]: "boolean",
+  [FIELD_SUBTYPE_DATE]: "string",
+  [FIELD_SUBTYPE_TIME]: "string",
+  [FIELD_SUBTYPE_TIMESTAMP]: "string",
+};
+
+/** Type-alias name for a field.enum, mirroring renderEnumTypeAliases. */
+function enumTypeAliasName(entity: MetaObject, field: MetaField): string {
+  const superField = field.resolveSuper();
+  return superField !== undefined
+    ? toPascalCase(superField.name)
+    : `${entity.name}${toPascalCase(field.name)}`;
+}
+
+/**
+ * One-line TS type expression for a field on a value-only object.
+ * Returns a `Code` so cross-module `field.object` refs can be hoisted via
+ * ts-poet `imp(...)` — matching how the Zod emitter hoists `<Ref>InsertSchema`.
+ */
+function valueObjectFieldType(entity: MetaObject, field: MetaField): Code {
+  // field.object: import the referenced TS interface from its sibling module
+  // so ts-poet hoists the import. Mirrors zod-validators.ts's `<Ref>InsertSchema`
+  // import strategy, just for the type alias instead of the schema constant.
+  if (field.subType === FIELD_SUBTYPE_OBJECT) {
+    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    if (typeof ref === "string" && ref.length > 0) {
+      const refImp = imp(`${ref}@./${ref}.js`);
+      return field.isArray ? code`${refImp}[]` : code`${refImp}`;
+    }
+    return field.isArray ? code`unknown[]` : code`unknown`;
+  }
+
+  // field.enum: use the same type-alias name as renderEnumTypeAliases emits.
+  if (field.subType === FIELD_SUBTYPE_ENUM) {
+    const values = enumValues(field);
+    if (values !== undefined) {
+      const alias = enumTypeAliasName(entity, field);
+      return field.isArray ? code`${alias}[]` : code`${alias}`;
+    }
+    return field.isArray ? code`string[]` : code`string`;
+  }
+
+  const scalar = SCALAR_TS_BY_SUBTYPE[field.subType] ?? "unknown";
+  return field.isArray ? code`${scalar}[]` : code`${scalar}`;
+}
+
+/**
+ * Emit a structural `interface <Name> { ... }` for a value-only object.
+ *
+ * Optional fields use `name?: T` (matching the Zod `.optional()` inference
+ * `T | undefined`) instead of `name?: T | null`. Value objects never round-
+ * trip through Drizzle nullable columns, so the null-bridge is unnecessary
+ * here — and forces consumers into a residual cast at the call site.
+ */
+export function renderValueObjectInterface(entity: MetaObject): Code {
+  const docs = renderDocsFor(entity);
+  const docsPrefix = docs ? `${docs}\n` : "";
+
+  const lines: Code[] = [];
+  for (const field of entity.fields()) {
+    const required = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+    const optional = required ? "" : "?";
+    const tsType = valueObjectFieldType(entity, field);
+    lines.push(code`  ${field.name}${optional}: ${tsType};`);
+  }
+
+  // joinCode with "\n" interpolates each Code segment on its own line and
+  // keeps the imp() registrations intact so ts-poet hoists the imports.
+  return code`${docsPrefix}export interface ${entity.name} {
+${joinCode(lines, { on: "\n" })}
+}
+`;
+}

package/src/templates/output-parser.ts

@@ -0,0 +1,143 @@
+// server/typescript/packages/codegen-ts/src/templates/output-parser.ts
+//
+// Per-template renderer for template.output codegen. Walks the @payloadRef's
+// value-object into a Zod schema and emits a dual-API parser (parse + safeParse)
+// alongside the schema. The emitted file is self-contained: it derives a
+// local data type via `z.infer<typeof Schema>` and exports it as
+// `<TemplateName>Data`. Consumers wiring `promptRender()` get a structurally
+// identical payload-VO interface in `prompts.ts`; either type can be used
+// interchangeably with parse results.
+
+import {
+  type MetaData,
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  TYPE_TEMPLATE,
+  TEMPLATE_SUBTYPE_OUTPUT,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_OBJECT_REF,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+} from "@metaobjectsdev/metadata";
+
+const SCALAR_ZOD: Record<string, string> = {
+  string: "z.string()",
+  class: "z.string()",
+  int: "z.number().int()",
+  short: "z.number().int()",
+  byte: "z.number().int()",
+  long: "z.number().int()",
+  double: "z.number()",
+  float: "z.number()",
+  boolean: "z.boolean()",
+};
+
+function findObject(root: MetaData, name: string): MetaData | undefined {
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+}
+
+function findTemplate(root: MetaData, name: string): MetaData | undefined {
+  return root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
+}
+
+/** Render the Zod expression for a single field; recurses on @objectRef. */
+function fieldZod(field: MetaData, root: MetaData, seen: ReadonlySet<string>, depth: number): string {
+  // isArray is a native (reserved) property on MetaData, not an attr.
+  const isArray = field.isArray === true;
+  let base: string;
+  if (field.subType === FIELD_SUBTYPE_OBJECT) {
+    const refName = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    if (typeof refName !== "string") {
+      base = "z.unknown()";
+    } else if (seen.has(refName)) {
+      // Cycle guard — emit unknown for self-references (rare; lazy schemas not in scope for v1).
+      base = "z.unknown()";
+    } else {
+      const inner = findObject(root, refName);
+      base = inner ? renderObjectSchema(inner, root, new Set(seen).add(refName), depth + 1) : "z.unknown()";
+    }
+  } else {
+    base = SCALAR_ZOD[field.subType] ?? "z.unknown()";
+  }
+  return isArray ? `z.array(${base})` : base;
+}
+
+/** Render a `z.object({ ... })` for an object.value node.
+ *  At depth 0 the schema starts at column 0 (consumer's `const Foo = z.object({`),
+ *  so fields sit at 2 spaces and the closing `})` at 0 spaces — matching the
+ *  surrounding `const NameSchema = ...` statement's indent. Nested schemas
+ *  step in two spaces per depth level. */
+function renderObjectSchema(vo: MetaData, root: MetaData, seen: ReadonlySet<string>, depth: number): string {
+  const fields = vo.children().filter((c) => c.type === TYPE_FIELD);
+  const fieldIndent = "  ".repeat(depth + 1);
+  const closeIndent = "  ".repeat(depth);
+  const lines = fields.map((f) => `${fieldIndent}${f.name}: ${fieldZod(f, root, seen, depth)},`);
+  return `z.object({\n${lines.join("\n")}\n${closeIndent}})`;
+}
+
+/**
+ * Render the full output-parser file for one `template.output` node.
+ * Throws if the template isn't found, isn't a template.output, or its
+ * @payloadRef doesn't resolve to an object.value.
+ */
+export function renderOutputParser(root: MetaData, templateName: string): 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}")`);
+  }
+  const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  if (typeof payloadRef !== "string") {
+    throw new Error(`template "${templateName}" missing @payloadRef`);
+  }
+  const vo = findObject(root, payloadRef);
+  if (!vo) {
+    throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
+  }
+
+  const schema = renderObjectSchema(vo, root, new Set([payloadRef]), 0);
+  const schemaName = `${templateName}Schema`;
+  const dataName = `${templateName}Data`;
+  const errorName = `${templateName}ValidationError`;
+  const parseName = `parse${templateName}`;
+  const safeParseName = `safeParse${templateName}`;
+
+  return `import { z } from "zod";
+
+const ${schemaName} = ${schema};
+
+export type ${dataName} = z.infer<typeof ${schemaName}>;
+export type ${errorName} = z.ZodError;
+
+/**
+ * Parse an LLM response into a typed ${dataName}.
+ * @throws ZodError on validation failure.
+ */
+export function ${parseName}(text: string): ${dataName} {
+  return ${schemaName}.parse(JSON.parse(text));
+}
+
+/**
+ * Parse an LLM response with explicit error handling (Result-style).
+ * Does not throw on validation failure.
+ */
+export function ${safeParseName}(
+  text: string,
+): { success: true; data: ${dataName} } | { success: false; error: ${errorName} } {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return {
+      success: false,
+      error: new z.ZodError([{ code: "custom", path: [], message: \`invalid JSON: \${(err as Error).message}\` }]),
+    };
+  }
+  const result = ${schemaName}.safeParse(parsed);
+  return result.success
+    ? { success: true, data: result.data }
+    : { success: false, error: result.error };
+}
+`;
+}

package/src/templates/projection-decl.ts

@@ -56,7 +56,7 @@ function pathFromProjectionName(name: string): string {
  *
  * @param projection  The projection entity (has a source[dbView] child).
  * @param root        The loader's root (all top-level objects as direct children,
- *                    from `MetaDataLoader.load()` / `FileMetaDataLoader.loadFiles()` as `result.root`).
+ *                    from `MetaDataLoader.load()` or `MetaDataLoader.fromDirectory()` as `result.root`).
  * @param opts        Column naming strategy + dialect.
  */
 export function renderProjectionDecl(

package/src/templates/queries-file.ts

@@ -4,7 +4,7 @@
 import { code, joinCode, type Code } from "ts-poet";
 import { MetaObject } from "@metaobjectsdev/metadata";
 import { type RenderContext } from "../render-context.js";
-import { entityModuleSpecifier, relativeModuleSpecifier } from "../import-path.js";
+import { entityModuleSpecifier } from "../import-path.js";
 import {
   renderFindByIdFn,
   renderListFn,
@@ -26,13 +26,27 @@ export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
     entityName,
     ctx.extStyle,
   );
-  const dbImportSpec = relativeModuleSpecifier(ctx.outputLayout, obj.package, ctx.dbImport);
   const varName = variableNameFromEntity(entityName);
 
-  // Literal imports (db + entity types) live in a code block so they sort
+  // The persistence-context `db` is parameter-passed into every generated CRUD
+  // helper (ADR-0008). Emit the dialect-correct Drizzle type alias so the
+  // signatures `findXxx(db: Db, ...)` typecheck without the consumer importing
+  // anything to construct one. Consumers pass any compatible Drizzle instance.
+  const dbTypeImport =
+    ctx.dialect === "postgres"
+      ? `import type { NodePgDatabase } from "drizzle-orm/node-postgres";`
+      : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
+  const dbTypeAlias =
+    ctx.dialect === "postgres"
+      ? `type Db = NodePgDatabase<Record<string, never>>;`
+      : `type Db = BaseSQLiteDatabase<"async", Record<string, never>>;`;
+
+  // Literal imports (Db type + entity types) live in a code block so they sort
   // alongside ts-poet's hoisted imp() imports at the top of the body.
   const literalImports = code`
-import { db } from ${JSON.stringify(dbImportSpec)};
+${dbTypeImport}
+${dbTypeAlias}
+
 import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON.stringify(entityFileName)};
 `;