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

package/src/generators/docs-file.ts

@@ -0,0 +1,64 @@
+// docsFile() — emits `<Entity>.md` next to each generated entity module.
+//
+// Markdown is port-agnostic: the same metadata produces the same documentation
+// page regardless of dialect, output layout, or runtime target. The page covers
+// description / type / source / package preamble; storage table + identity +
+// relationships for table-backed entities; validation entry points; "used by"
+// template cross-references; and the generated-code surface (which sibling
+// files codegen produces). See `templates/docs-file.ts` for the body.
+
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderDocsFile } from "../templates/docs-file.js";
+import { entityOutputPath } from "../import-path.js";
+
+export interface DocsFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
+  const generator: Generator = {
+    name: "docs-file",
+    generate: perEntity((entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("docs-file: renderContext is required (provided by runGen)");
+      }
+      const rc = ctx.renderContext;
+      const generatorNames = readGeneratorNames(ctx);
+      return {
+        path: entityOutputPath(
+          ctx.config.outputLayout ?? "flat",
+          entity.package,
+          `${entity.name}.md`,
+        ),
+        content: renderDocsFile(entity, {
+          dialect: rc.dialect,
+          columnNamingStrategy: rc.columnNamingStrategy,
+          loadedRoot: rc.loadedRoot,
+          generatorNames,
+        }),
+      };
+    }),
+  };
+  if (opts?.filter) {
+    generator.filter = opts.filter;
+  }
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<DocsFileOpts>;
+
+/**
+ * `GenContext` does not currently carry the full generator list — that lives on
+ * the resolved config inside the runner. Rather than thread a new field through
+ * just to populate one optional markdown section, we always list every
+ * potential companion. The "Generated code" section becomes "files that may be
+ * generated alongside this one" — adopters cross-reference their own
+ * `metaobjects.config.ts` to confirm which they actually wired in. This matches
+ * the spec guidance "list them all and let the reader figure out which exist."
+ */
+function readGeneratorNames(_ctx: unknown): ReadonlySet<string> {
+  return new Set(["queries-file", "routes-file", "routes-file-hono"]);
+}

package/src/generators/entity-file.ts

@@ -7,9 +7,25 @@ import { entityOutputPath } from "../import-path.js";
 export interface EntityFileOpts {
   filter?: (entity: MetaObject) => boolean;
   target?: string;
+  /**
+   * Whether generated entity files include the Fastify-flavored
+   * `<Entity>FilterAllowlist` + `<Entity>SortAllowlist` blocks (and the
+   * `@metaobjectsdev/runtime-ts/drizzle-fastify` type-only imports they
+   * require). Default `true` for back-compat.
+   *
+   * Set to `false` for Worker/Lambda-style consumers that don't mount
+   * Fastify-style server routes — the generated entity file then has no
+   * `runtime-ts/drizzle-fastify` imports at all and `@metaobjectsdev/runtime-ts`
+   * can be omitted from the consumer's dependency tree.
+   *
+   * The client-side `<Entity>Filter` type is always emitted — it's a pure
+   * client-side type with no runtime-ts dependency.
+   */
+  allowlists?: boolean;
 }
 
 export const entityFile = function entityFile(opts?: EntityFileOpts): Generator {
+  const allowlists = opts?.allowlists ?? true;
   const generator: Generator = {
     name: "entity-file",
     emitsEntityModule: true,
@@ -19,7 +35,7 @@ export const entityFile = function entityFile(opts?: EntityFileOpts): Generator
       }
       return {
         path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
-        content: await formatTs(renderEntityFile(entity, ctx.renderContext)),
+        content: await formatTs(renderEntityFile(entity, ctx.renderContext, { allowlists })),
       };
     }),
   };

package/src/generators/index.ts

@@ -1,5 +1,9 @@
 export { entityFile, type EntityFileOpts } from "./entity-file.js";
 export { queriesFile, type QueriesFileOpts } from "./queries-file.js";
 export { routesFile, type RoutesFileOpts } from "./routes-file.js";
+export { routesFileHono, type RoutesFileHonoOpts } from "./routes-file-hono.js";
 export { barrel, type BarrelOpts } from "./barrel.js";
 export { mermaidErDiagram, type MermaidErOptions } from "./mermaid-er.js";
+export { promptRender, type PromptRenderOpts } from "./prompt-render-file.js";
+export { outputParser, type OutputParserOpts } from "./output-parser-file.js";
+export { docsFile, type DocsFileOpts } from "./docs-file.js";

package/src/generators/output-parser-file.ts

@@ -0,0 +1,50 @@
+// server/typescript/packages/codegen-ts/src/generators/output-parser-file.ts
+//
+// Stock generator that emits one <TemplateName>.output.ts file per declared
+// template.output node. Wraps renderOutputParser() from templates/output-parser.ts.
+//
+// Consumer wiring (metaobjects.config.ts):
+//   generators: [..., promptRender(), outputParser()]
+//
+// Custom output directory:
+//   generators: [..., outputParser({ outDir: "src/generated/outputs" })]
+
+import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
+import {
+  type EmittedFile,
+  type Generator,
+  type GeneratorFactory,
+  oncePerRun,
+} from "../generator.js";
+import { renderOutputParser } from "../templates/output-parser.js";
+
+export interface OutputParserOpts {
+  /** Output directory prefix relative to the target's outDir. Default: "" (root). */
+  outDir?: string;
+  /** Optional named output target (registry key). Defaults to "default". */
+  target?: string;
+}
+
+export const outputParser = function outputParser(opts?: OutputParserOpts): Generator {
+  const dirPrefix = opts?.outDir ? `${opts.outDir.replace(/\/$/, "")}/` : "";
+  const generator: Generator = {
+    name: "output-parser",
+    generate: oncePerRun((_entities, ctx) => {
+      const outputs = ctx.loadedRoot
+        .ownChildren()
+        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
+      const files: EmittedFile[] = [];
+      for (const t of outputs) {
+        files.push({
+          path: `${dirPrefix}${t.name}.output.ts`,
+          content: renderOutputParser(ctx.loadedRoot, t.name),
+        });
+      }
+      return files;
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<OutputParserOpts>;

package/src/generators/prompt-render-file.ts

@@ -0,0 +1,95 @@
+// Stock generator that wraps generatePayloadInterfaces() + generateRenderHandle()
+// from payload-codegen.ts into a Generator factory. Emits ONE file aggregating
+// typed payload interfaces (for object.value entities) and render handles (for
+// template.prompt nodes).
+//
+// Consumer wiring (metaobjects.config.ts):
+//   generators: [..., promptRender()]
+//
+// Custom output path:
+//   generators: [..., promptRender({ outFile: "src/render/generated/prompts.ts" })]
+
+import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, OBJECT_SUBTYPE_VALUE } from "@metaobjectsdev/metadata";
+import {
+  type Generator,
+  type GeneratorFactory,
+  oncePerRun,
+} from "../generator.js";
+import {
+  generatePayloadInterfacesBatch,
+  generateRenderHandle,
+} from "../payload-codegen.js";
+import { GENERATED_HEADER } from "../constants.js";
+
+export interface PromptRenderOpts {
+  /** Output file path relative to the target's outDir. Default: "prompts.ts". */
+  outFile?: string;
+  /** Optional named output target (registry key). Defaults to "default". */
+  target?: string;
+}
+
+// Hoisted into the emitted file once. generateRenderHandle() emits this line
+// per-handle (for the standalone scenario); we strip its per-handle copies.
+const RENDER_IMPORT = `import { render, type Provider } from "@metaobjectsdev/render";`;
+
+// Matches the `import type { ... } from "./payloads.js";` that generateRenderHandle
+// emits for the standalone two-file scenario. In the single-file output here the
+// payload interfaces are already defined above, so the import is dead.
+function isStandalonePayloadImport(line: string): boolean {
+  return line.startsWith("import type {") && line.includes('"./payloads.js"');
+}
+
+export const promptRender = function promptRender(opts?: PromptRenderOpts): Generator {
+  const outFile = opts?.outFile ?? "prompts.ts";
+  const generator: Generator = {
+    name: "prompt-render",
+    generate: oncePerRun((entities, ctx) => {
+      const payloads = entities.filter((e) => e.subType === OBJECT_SUBTYPE_VALUE);
+      const prompts = ctx.loadedRoot
+        .ownChildren()
+        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_PROMPT);
+
+      if (payloads.length === 0 && prompts.length === 0) {
+        return [];
+      }
+
+      const parts: string[] = [`// ${GENERATED_HEADER} — DO NOT EDIT.`];
+
+      // Hoist the @metaobjectsdev/render import once (only when prompts emit handles).
+      if (prompts.length > 0) {
+        parts.push(RENDER_IMPORT);
+      }
+
+      // Emit payload interfaces with a single shared dedupe set so a lens
+      // referenced by multiple payloads appears exactly once.
+      const payloadInterfaces = generatePayloadInterfacesBatch(
+        ctx.loadedRoot,
+        payloads.map((p) => p.name),
+      );
+      if (payloadInterfaces.length > 0) {
+        parts.push(payloadInterfaces);
+      }
+
+      // Append each render handle with its per-handle imports stripped — both
+      // the now-hoisted render/Provider import and the standalone payloads.js
+      // import. Also drop any leading blank lines left behind by the strip so
+      // the joined output doesn't accumulate double blank gaps between parts.
+      for (const t of prompts) {
+        const lines = generateRenderHandle(ctx.loadedRoot, t.name)
+          .split("\n")
+          .filter((line) => line !== RENDER_IMPORT && !isStandalonePayloadImport(line));
+        while (lines.length > 0 && lines[0]!.trim() === "") lines.shift();
+        parts.push(lines.join("\n"));
+      }
+
+      return [{
+        path: outFile,
+        content: parts.filter((s) => s.length > 0).map((s) => s.trimEnd()).join("\n\n") + "\n",
+      }];
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<PromptRenderOpts>;

package/src/generators/queries-file.ts

@@ -1,4 +1,4 @@
-import type { MetaObject } from "@metaobjectsdev/metadata";
+import { OBJECT_SUBTYPE_VALUE, type MetaObject } from "@metaobjectsdev/metadata";
 import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderQueriesFile } from "../templates/queries-file.js";
 import { formatTs } from "../format.js";
@@ -9,9 +9,21 @@ export interface QueriesFileOpts {
   target?: string;
 }
 
+// object.value records have no primary identity, so the rendered queries module
+// emits findById/updateById/deleteById against a non-existent column. Skipping
+// value subtypes is unconditional — the user-supplied filter (if any) is applied
+// on top via boolean AND.
+const skipValueTypes = (e: MetaObject): boolean => e.subType !== OBJECT_SUBTYPE_VALUE;
+
 export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generator {
+  const userFilter = opts?.filter;
+  const filter: (e: MetaObject) => boolean = userFilter
+    ? (e) => skipValueTypes(e) && userFilter(e)
+    : skipValueTypes;
+
   const generator: Generator = {
     name: "queries-file",
+    filter,
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("queries-file: renderContext is required (provided by runGen)");
@@ -22,9 +34,6 @@ export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generat
       };
     }),
   };
-  if (opts?.filter) {
-    generator.filter = opts.filter;
-  }
   if (opts?.target) {
     generator.target = opts.target;
   }

package/src/generators/routes-file-hono.ts

@@ -0,0 +1,48 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderRoutesFileHono } from "../templates/routes-file-hono.js";
+import { formatTs } from "../format.js";
+import { entityOutputPath } from "../import-path.js";
+
+export interface RoutesFileHonoOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/**
+ * Hono variant of routesFile() — emits `<Entity>.routes.hono.ts` mounting
+ * the same five CRUD verbs (GET list / GET :id / POST / PATCH+PUT / DELETE)
+ * against `@metaobjectsdev/runtime-ts/hono` rather than `…/drizzle-fastify`.
+ *
+ * Same cross-port wire contract (envelope shape, status codes, filter +
+ * sort + withCount semantics) as the Fastify flavor. Workers / Bun / Node
+ * consumers running Hono can replace hand-written route registration with
+ * this generator output one entity at a time.
+ *
+ * Per-entity opt-out via `@emitRoutes: false` is honored. If the user
+ * supplies their own filter, both must pass (AND).
+ */
+export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  const generator: Generator = {
+    name: "routes-file-hono",
+    filter: (e: MetaObject) => e.ownAttr("emitRoutes") !== false && userFilter(e),
+    generate: 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)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<RoutesFileHonoOpts>;

package/src/index.ts

@@ -9,7 +9,7 @@ export type { RunGenOpts, RunGenResult } from "./runner.js";
 export type { Generator, GenContext, EmittedFile, GeneratorFactory } from "./generator.js";
 export { perEntity, oncePerRun } from "./generator.js";
 
-export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy } from "./metaobjects-config.js";
+export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider } from "./metaobjects-config.js";
 export { defineConfig, normalizeConfig } from "./metaobjects-config.js";
 
 export type { ColumnSpec, DefaultExpr } from "./column-mapper.js";
@@ -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, type MetaDataTypeProvider } 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, MetaDataTypeProvider } from "@metaobjectsdev/metadata";
 export type { ExtStyle };
 export type { OutputLayout };
 export type { ResolvedTarget };
@@ -39,6 +41,13 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
   targets?: Record<string, TargetConfig>;
   /** importBase for the default target (top-level outDir). */
   importBase?: string;
+  /**
+   * Consumer-supplied {@link MetaDataTypeProvider}s. Threaded to `loadMemory`
+   * by the CLI's gen/migrate commands so a project can register its own
+   * subtypes/attrs (e.g. a `template.toolcall` subtype) without forking the
+   * loader. Composed AFTER the default core+forge bundle.
+   */
+  providers?: readonly MetaDataTypeProvider[];
 }
 
 /** MetaobjectsGenConfig after applying defaults. All fields required.
@@ -87,7 +96,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;
+}