@cosmicdrift/kumiko-framework 0.15.0 → 0.18.0

package/src/db/dialect.ts

@@ -94,6 +94,7 @@ type ColumnFinal = {
   readonly unique: boolean;
   readonly identity: boolean;
   readonly defaultSql?: string;
+  readonly bigintJsMode?: "number" | "bigint";
 };
 
 export type ColumnBuilder<TValue = unknown> = {
@@ -112,7 +113,11 @@ export type ColumnBuilder<TValue = unknown> = {
   $onUpdate(fn: () => unknown): ColumnBuilder<TValue>;
 };
 
-function buildColumn(sqlName: string, pgType: PgType): ColumnBuilder<unknown> {
+function buildColumn(
+  sqlName: string,
+  pgType: PgType,
+  opts?: { bigintJsMode?: "number" | "bigint" },
+): ColumnBuilder<unknown> {
   let notNull = false;
   let primaryKey = false;
   let unique = false;
@@ -152,6 +157,7 @@ function buildColumn(sqlName: string, pgType: PgType): ColumnBuilder<unknown> {
         unique,
         identity,
         ...(defaultSql !== undefined && { defaultSql }),
+        ...(opts?.bigintJsMode !== undefined && { bigintJsMode: opts.bigintJsMode }),
       };
     },
     notNull() {
@@ -219,11 +225,9 @@ export function serial(name: string): ColumnBuilder<number> {
   return buildColumn(name, "serial") as ColumnBuilder<number>;
 }
 
-export function bigint(
-  name: string,
-  _opts?: { mode?: "bigint" | "number" },
-): ColumnBuilder<bigint> {
-  return buildColumn(name, "bigint") as ColumnBuilder<bigint>;
+export function bigint(name: string, opts?: { mode?: "bigint" | "number" }): ColumnBuilder<bigint> {
+  const jsMode = opts?.mode === "number" ? "number" : "bigint";
+  return buildColumn(name, "bigint", { bigintJsMode: jsMode }) as ColumnBuilder<bigint>;
 }
 
 export function bigserial(
@@ -407,6 +411,7 @@ export function table<TCols extends ColumnMap>(
       ...(final.primaryKey && { primaryKey: true }),
       ...(final.identity && { identity: true }),
       ...(final.defaultSql !== undefined && { defaultSql: final.defaultSql }),
+      ...(final.bigintJsMode !== undefined && { bigintJsMode: final.bigintJsMode }),
     };
     columnMetas.push(meta);
 

package/src/db/entity-table-meta.ts

@@ -51,6 +51,9 @@ export type ColumnMeta = {
   readonly defaultSql?: string;
   readonly primaryKey?: boolean;
   readonly identity?: boolean;
+  // bigint/bigserial only: JS round-trip mode. `number` = createBigIntField /
+  // drizzle mode:"number" (safe ≤2^53). `bigint` = money cents, raw unmanaged.
+  readonly bigintJsMode?: "number" | "bigint";
 };
 
 export type IndexMeta = {
@@ -199,6 +202,7 @@ function fieldToColumnMeta(
           name: snake,
           pgType: "bigint",
           notNull: field.required === true,
+          bigintJsMode: "number",
           ...(def !== undefined && { defaultSql: def }),
         },
       ];
@@ -211,7 +215,7 @@ function fieldToColumnMeta(
     case "money": {
       const cur = entity.defaultCurrency ?? "EUR";
       return [
-        { name: snake, pgType: "bigint", notNull: field.required === true },
+        { name: snake, pgType: "bigint", notNull: field.required === true, bigintJsMode: "bigint" },
         {
           name: `${snake}_currency`,
           pgType: "text",
@@ -329,23 +333,22 @@ export function buildEntityTableMeta(
     indexes.push({ name: `${tableName}_${snake}_idx`, columns: [snake] });
   }
 
-  // Explizit deklarierte indexes (EntityIndexDef). `def.where` ist heute
-  // ein drizzle SQL-AST — wir können daraus keinen zuverlässigen Raw-SQL-
-  // String rendern (queryChunks sind internal). Wenn ein where gesetzt
-  // ist, markieren wir den IndexMeta mit needsManualWhere=true; der DDL-
-  // Renderer emittiert das Statement dann als AUSKOMMENTIERT mit Warn-
-  // Hinweis. App-Author muss das im generierten SQL-File hand-editieren.
+  // Explizit deklarierte indexes (EntityIndexDef). `def.where` ist ein
+  // SqlExpression (`sql\`…\`` aus @cosmicdrift/kumiko-framework/db) —
+  // renderbar via `.text`. Unbekannte where-Shapes bleiben needsManualWhere.
   for (const def of (entity.indexes ?? []) as readonly EntityIndexDef[]) {
     const cols = def.columns.map(
       (fieldName) => fieldNameToSnake.get(fieldName) ?? toSnakeCase(fieldName),
     );
     const suffix = def.unique === true ? "unique" : "idx";
     const indexName = def.name ?? `${tableName}_${cols.join("_")}_${suffix}`;
+    const whereSql = sqlExpressionText(def.where);
     indexes.push({
       name: indexName,
       columns: cols,
       ...(def.unique === true && { unique: true }),
-      ...(def.where !== undefined && { needsManualWhere: true }),
+      ...(whereSql !== undefined && { whereSql }),
+      ...(def.where !== undefined && whereSql === undefined && { needsManualWhere: true }),
     });
   }
 
@@ -377,6 +380,18 @@ export type UnmanagedTableInput = {
   readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
 };
 
+function sqlExpressionText(where: unknown): string | undefined {
+  if (
+    typeof where === "object" &&
+    where !== null &&
+    (where as { kind?: unknown }).kind === "sql-expr" &&
+    typeof (where as { text?: unknown }).text === "string"
+  ) {
+    return (where as { text: string }).text;
+  }
+  return undefined;
+}
+
 export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMeta {
   return {
     tableName: input.tableName,

package/src/db/index.ts

@@ -51,6 +51,31 @@ export type {
 } from "./event-store-executor";
 export { createEventStoreExecutor, entityEventName } from "./event-store-executor";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp";
+export {
+  diffSnapshots,
+  type GenerateMigrationInput,
+  type GenerateMigrationOutput,
+  generateMigration,
+  loadSnapshotJson,
+  renderMigrationSql,
+  type SchemaDiff,
+  type Snapshot,
+  snapshotFromMetas,
+  writeSnapshotJson,
+} from "./migrate-generator";
+export {
+  type AppliedMigration,
+  type ApplyResult,
+  type BaselineResult,
+  baselineMigrations,
+  fetchAppliedMigrations,
+  loadMigrationsFromDir,
+  type Migration,
+  MigrationChecksumMismatchError,
+  runMigrations,
+  runMigrationsFromDir,
+  splitSqlStatements,
+} from "./migrate-runner";
 export { flattenMoney, rehydrateMoney } from "./money";
 export {
   constraintOf,

package/src/db/migrate-runner.ts

@@ -111,7 +111,9 @@ async function executeRaw(db: DbRunner, sqlText: string): Promise<void> {
   await rawClient(db).unsafe(sqlText);
 }
 
-async function fetchAppliedMigrations(db: DbConnection): Promise<readonly AppliedMigration[]> {
+export async function fetchAppliedMigrations(
+  db: DbConnection,
+): Promise<readonly AppliedMigration[]> {
   const result = await rawClient(db).unsafe(
     `SELECT id, checksum FROM "_kumiko_migrations" ORDER BY id`,
   );
@@ -204,3 +206,35 @@ export async function runMigrationsFromDir(db: DbConnection, dir: string): Promi
   const migrations = loadMigrationsFromDir(dir);
   return runMigrations(db, migrations);
 }
+
+export type BaselineResult = {
+  readonly marked: readonly string[];
+  readonly alreadyTracked: readonly string[];
+};
+
+// Marks migrations as applied in `_kumiko_migrations` WITHOUT executing their
+// SQL. For adopting an existing DB whose tables already exist — e.g. the
+// cutover from the legacy drizzle-kit system, where re-running 0001_init would
+// hit CREATE-TABLE conflicts. Idempotent: already-tracked ids are left as-is.
+export async function baselineMigrations(
+  db: DbConnection,
+  migrations: readonly Migration[],
+): Promise<BaselineResult> {
+  await executeRaw(db, MIGRATIONS_TABLE_DDL);
+  const applied = new Set((await fetchAppliedMigrations(db)).map((a) => a.id));
+  const marked: string[] = [];
+  const alreadyTracked: string[] = [];
+  const client = rawClient(db);
+  for (const m of migrations) {
+    if (applied.has(m.id)) {
+      alreadyTracked.push(m.id);
+      continue;
+    }
+    await client.unsafe(
+      `INSERT INTO "_kumiko_migrations" ("id", "checksum") VALUES ($1, $2) ON CONFLICT ("id") DO NOTHING`,
+      [m.id, m.checksum],
+    );
+    marked.push(m.id);
+  }
+  return { marked, alreadyTracked };
+}

package/src/db/money.ts

@@ -106,6 +106,11 @@ export function rehydrateMoney(
     let amount: number;
     if (typeof amountRaw === "number") {
       amount = amountRaw;
+    } else if (typeof amountRaw === "bigint") {
+      amount = Number(amountRaw);
+      if (Number.isNaN(amount)) {
+        throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a number`);
+      }
     } else if (typeof amountRaw === "string" && amountRaw !== "") {
       // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
       amount = Number(amountRaw);

package/src/db/queries/test-stack.ts

@@ -25,9 +25,11 @@ export async function createIndexIfNotExists(
   indexName: string,
   tableName: string,
   columnList: string,
+  whereSql?: string,
 ): Promise<void> {
+  const where = whereSql !== undefined ? ` WHERE ${whereSql}` : "";
   await asRawClient(db).unsafe(
-    `CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})`,
+    `CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})${where}`,
   );
 }
 

package/src/db/table-builder.ts

@@ -5,6 +5,10 @@ import type {
   FieldsMap,
 } from "../engine/types";
 import { assertUnreachable } from "../utils";
+import { toSnakeCase } from "../utils/case";
+
+export { toSnakeCase } from "../utils/case";
+
 import {
   bigint,
   boolean,
@@ -192,12 +196,8 @@ function fieldToColumns(
 }
 
 // Accepts both camelCase (`tenantMembership`) and kebab-case (`tenant-membership`)
-// entity / field names. Kebab is the canonical form for new multi-word entity
-// types (consistent across r.entity, event-types, table names) — camelCase is
-// kept working for already-shipped code.
-export function toSnakeCase(str: string): string {
-  return str.replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-}
+// entity / field names. Implementation lives in utils/case — re-exported here
+// for backwards-compatible imports from db/table-builder.
 
 /**
  * Derives a table name from an entity name:

package/src/engine/__tests__/duration-utils.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { addDuration } from "../steps/_duration-utils";
+
+describe("addDuration", () => {
+  test("adds ISO duration to base instant", () => {
+    const base = "2024-01-01T00:00:00Z";
+    const result = addDuration(base, "PT1H");
+    expect(result).toBe(Temporal.Instant.from(base).add({ hours: 1 }).toString());
+  });
+
+  test("throws on invalid duration", () => {
+    expect(() => addDuration("2024-01-01T00:00:00Z", "not-a-duration")).toThrow(
+      /Invalid ISO-8601 duration/,
+    );
+  });
+});

package/src/engine/__tests__/field-access.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { checkWriteFieldRoles, filterReadFields } from "../field-access";
+import type { EntityDefinition } from "../types";
+
+const entity: EntityDefinition = {
+  fields: {
+    title: { type: "text", access: { read: { editor: "all" }, write: { editor: "all" } } },
+    secret: { type: "text", access: { read: { admin: "all" }, write: { admin: "all" } } },
+  },
+};
+
+const editor = { id: "u1", tenantId: "t1", roles: ["editor"] as const };
+const admin = { id: "u2", tenantId: "t1", roles: ["admin"] as const };
+
+describe("filterReadFields", () => {
+  test("strips fields the user cannot read", () => {
+    const row = { id: 1, title: "Hello", secret: "hidden" };
+    const filtered = filterReadFields(entity, row, editor);
+    expect(filtered["title"]).toBe("Hello");
+    expect(filtered["secret"]).toBeUndefined();
+  });
+
+  test("keeps restricted fields for allowed roles", () => {
+    const row = { id: 1, title: "Hello", secret: "visible" };
+    const filtered = filterReadFields(entity, row, admin);
+    expect(filtered["secret"]).toBe("visible");
+  });
+});
+
+describe("checkWriteFieldRoles", () => {
+  test("returns denied field name when role missing", () => {
+    expect(checkWriteFieldRoles(entity, { secret: "x" }, editor)).toBe("secret");
+  });
+
+  test("returns null when all changed fields are allowed", () => {
+    expect(checkWriteFieldRoles(entity, { title: "x" }, editor)).toBeNull();
+  });
+});

package/src/engine/__tests__/no-return-guard.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { validateNoReturnSteps } from "../steps/_no-return-guard";
+import type { StepInstance } from "../types/step";
+
+describe("validateNoReturnSteps", () => {
+  test("passes when no return steps present", () => {
+    const steps = [{ kind: "noop" }] as unknown as readonly StepInstance[];
+    expect(() => validateNoReturnSteps(steps, "r.step.branch.onTrue")).not.toThrow();
+  });
+
+  test("throws when return step is nested", () => {
+    const steps = [{ kind: "return" }] as unknown as readonly StepInstance[];
+    expect(() => validateNoReturnSteps(steps, "r.step.forEach.do")).toThrow(
+      /not allowed inside r\.step\.forEach\.do/,
+    );
+  });
+});

package/src/engine/__tests__/unmanaged-table.test.ts

@@ -0,0 +1,98 @@
+// Unit tests for r.unmanagedTable() — the EntityTableMeta cousin of
+// r.rawTable. Same audit-trail contract, different storage shape (post-
+// drizzle migrate-runner). See define-feature.ts / DX-4.
+
+import { describe, expect, test } from "bun:test";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+
+const probeMeta = defineUnmanagedTable({
+  tableName: "ut_probe",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+});
+const probeMetaTwo = defineUnmanagedTable({
+  tableName: "ut_probe_two",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+});
+
+describe("r.unmanagedTable — declaration", () => {
+  test("rejects duplicate registrations within one feature", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "test" });
+        r.unmanagedTable(probeMeta, { reason: "test" });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects empty reason", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "" });
+      }),
+    ).toThrow(/options\.reason must be a non-empty string/);
+  });
+
+  test("rejects whitespace-only reason", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "   " });
+      }),
+    ).toThrow(/options\.reason must be a non-empty string/);
+  });
+
+  test("accepts valid registration and stores meta + reason", () => {
+    const feature = defineFeature("probe", (r) => {
+      r.unmanagedTable(probeMeta, {
+        reason: "read-side projection of an event-stream",
+      });
+    });
+    expect(feature.unmanagedTables).toHaveProperty("ut_probe");
+    expect(feature.unmanagedTables["ut_probe"]?.reason).toBe(
+      "read-side projection of an event-stream",
+    );
+    expect(feature.unmanagedTables["ut_probe"]?.meta).toBe(probeMeta);
+  });
+
+  test("two unmanaged tables on one feature register under their tableName", () => {
+    const feature = defineFeature("dual", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "one" });
+      r.unmanagedTable(probeMetaTwo, { reason: "two" });
+    });
+    expect(Object.keys(feature.unmanagedTables).sort()).toEqual(["ut_probe", "ut_probe_two"]);
+  });
+
+  test("absent unmanagedTables on a feature is ok", () => {
+    const feat = defineFeature("plain", () => {
+      // no r.unmanagedTable calls
+    });
+    expect(feat.unmanagedTables).toEqual({});
+  });
+});
+
+describe("createRegistry — unmanagedTable aggregation", () => {
+  test("rejects cross-feature tableName collisions at boot", () => {
+    // Two features can't share the same physical tableName — migrate-runner
+    // would race two CREATE TABLE statements. Boot-validator catches it.
+    const featA = defineFeature("a", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "first" });
+    });
+    const featB = defineFeature("b", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "second" });
+    });
+    expect(() => createRegistry([featA, featB])).toThrow(
+      /Unmanaged-table "ut_probe" registered by both feature "a" and "b"/,
+    );
+  });
+
+  test("two features with distinct tableNames register cleanly", () => {
+    const featA = defineFeature("a", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "first" });
+    });
+    const featB = defineFeature("b", (r) => {
+      r.unmanagedTable(probeMetaTwo, { reason: "second" });
+    });
+    expect(() => createRegistry([featA, featB])).not.toThrow();
+  });
+});

package/src/engine/define-feature.ts

@@ -1,4 +1,5 @@
 import type { ZodType, z } from "zod";
+import type { EntityTableMeta } from "../db/entity-table-meta";
 import { toTableName } from "../db/table-builder";
 import { LifecycleHookTypes } from "./constants";
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
@@ -61,6 +62,7 @@ import type {
   TreeActionDef,
   TreeActionsHandle,
   TreeChildrenSubscribe,
+  UnmanagedTableEntry,
   ValidationHookFn,
   WriteHandlerDef,
   WriteHandlerFn,
@@ -136,6 +138,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const projections: Record<string, ProjectionDefinition> = {};
   const multiStreamProjections: Record<string, MultiStreamProjectionDefinition> = {};
   const rawTables: Record<string, RawTableEntry> = {};
+  const unmanagedTables: Record<string, UnmanagedTableEntry> = {};
   const authClaimsHooks: AuthClaimsFn[] = [];
   const claimKeys: Record<string, ClaimKeyDefinition> = {};
   const screens: Record<string, ScreenDefinition> = {};
@@ -791,6 +794,38 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       };
     },
 
+    unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void {
+      // Name comes from the meta itself — apps already give the table a
+      // name when calling defineUnmanagedTable, no need to repeat it.
+      const tableName = meta.tableName;
+      if (!isKebabSegment(tableName.replace(/_/g, "-"))) {
+        // EntityTableMeta uses snake_case for tableName (matches Postgres
+        // convention); we just guard against truly broken input.
+        throw new Error(
+          `[Feature ${name}] Unmanaged-table name "${tableName}" must be a ` +
+            `valid identifier (lowercase letters, digits, underscores; start with a letter).`,
+        );
+      }
+      if (unmanagedTables[tableName]) {
+        throw new Error(
+          `[Feature ${name}] r.unmanagedTable("${tableName}") already registered. ` +
+            `Unmanaged-table names must be unique per feature.`,
+        );
+      }
+      if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
+        throw new Error(
+          `[Feature ${name}] r.unmanagedTable("${tableName}"): options.reason must be a ` +
+            `non-empty string. The reason justifies the audit-trail bypass — ` +
+            `if you can't write one, declare data via r.entity() instead.`,
+        );
+      }
+      unmanagedTables[tableName] = {
+        name: tableName,
+        meta,
+        reason: options.reason,
+      };
+    },
+
     claimKey<T extends ClaimKeyType>(
       shortName: string,
       options: { readonly type: T },
@@ -905,6 +940,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     workspaces,
     httpRoutes,
     rawTables,
+    unmanagedTables,
     ...(treeActions !== undefined && { treeActions }),
     ...(treeProvider !== undefined && { treeProvider }),
     ...(envSchema !== undefined && { envSchema }),

package/src/engine/feature-ast/extractors/shared.ts

@@ -1,5 +1,6 @@
 import type { CallExpression, Node } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
+import { isPlainObject } from "../../../utils/is-plain-object";
 import type { ParseError } from "../parse";
 
 export type ExtractOutput<TPattern> =
@@ -107,9 +108,7 @@ export function readDataLiteralNode(node: Node): unknown {
   }
 }
 
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+export { isPlainObject } from "../../../utils/is-plain-object";
 
 export function readPropertyKey(propAssign: import("ts-morph").PropertyAssignment): string {
   const nameNode = propAssign.getNameNode();

package/src/engine/index.ts

@@ -154,7 +154,7 @@ export { resolveConfigOrParam } from "./resolve-config-or-param";
 export { runsInLane } from "./run-in";
 export type { StepListOutcome } from "./run-pipeline";
 export { runPipeline, runStepList } from "./run-pipeline";
-export { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
+export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
 export {

package/src/engine/registry.ts

@@ -40,6 +40,7 @@ import type {
   TranslationKeys,
   TreeActionDef,
   TreeChildrenSubscribe,
+  UnmanagedTableDef,
   WorkspaceDefinition,
   WriteHandlerDef,
 } from "./types";
@@ -169,6 +170,10 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // enforced at ingest below (collisions would race two CREATE TABLE
   // statements at the same physical name and break boot).
   const rawTableMap = new Map<string, RawTableDef>();
+  // Unmanaged tables — declared via r.unmanagedTable() (EntityTableMeta).
+  // Cousin of rawTables: same uniqueness-by-tableName invariant, different
+  // storage shape (post-drizzle migrate-runner consumes EntityTableMeta).
+  const unmanagedTableMap = new Map<string, UnmanagedTableDef>();
   // Auth-claims hooks — tagged with featureName so the login resolver can
   // auto-prefix each hook's returned keys with "<feature>:".
   const authClaimsHooks: AuthClaimsHookDef[] = [];
@@ -543,6 +548,20 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       rawTableMap.set(rawName, { ...rawDef, featureName: feature.name });
     }
 
+    // Unmanaged tables — same cross-feature uniqueness invariant as rawTables.
+    // Two features registering the same physical tableName would race two
+    // CREATE TABLE statements via migrate-runner.
+    for (const [umName, umDef] of Object.entries(feature.unmanagedTables ?? {})) {
+      const existing = unmanagedTableMap.get(umName);
+      if (existing) {
+        throw new Error(
+          `Unmanaged-table "${umName}" registered by both feature "${existing.featureName}" and ` +
+            `"${feature.name}". Pick a feature-prefixed tableName to disambiguate.`,
+        );
+      }
+      unmanagedTableMap.set(umName, { ...umDef, featureName: feature.name });
+    }
+
     // Claim keys: aggregated by qualified name. Two features cannot collide
     // here (qualified by feature name), but we still guard for explicit
     // correctness — the only way to hit this is a hand-built FeatureDefinition

package/src/engine/schema-builder.ts

@@ -18,7 +18,7 @@ function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
   }
 }
 
-function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.ZodTypeAny {
+export function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.ZodTypeAny {
   switch (field.type) {
     case "text": {
       let schema = z.string();

package/src/engine/types/feature.ts

@@ -1,4 +1,5 @@
 import type { ZodType, z } from "zod";
+import type { EntityTableMeta } from "../../db/entity-table-meta";
 
 // PgTable historically came from drizzle-orm/pg-core; the native dialect
 // no longer carries drizzle internal class types. Every caller really
@@ -148,6 +149,23 @@ export type RawTableDef = RawTableEntry & {
   readonly featureName: string;
 };
 
+// --- Unmanaged tables (declared by features via r.unmanagedTable()) ---
+
+/** Per-feature unmanaged-table registration. `meta` is the
+ *  `EntityTableMeta` (framework-native shape used by `migrate-runner`).
+ *  The `reason` justifies the bypass at the registration site — same
+ *  contract as `r.rawTable`. */
+export type UnmanagedTableEntry = {
+  readonly name: string;
+  readonly meta: EntityTableMeta;
+  readonly reason: string;
+};
+
+/** Registry-aggregated unmanaged-table — adds the owning feature name. */
+export type UnmanagedTableDef = UnmanagedTableEntry & {
+  readonly featureName: string;
+};
+
 // --- Feature Definition (output of defineFeature) ---
 
 export type FeatureDefinition = {
@@ -274,6 +292,12 @@ export type FeatureDefinition = {
   // system. Keyed by feature-local short name. The registry attaches
   // featureName on aggregation, lifting RawTableEntry → RawTableDef.
   readonly rawTables: Readonly<Record<string, RawTableEntry>>;
+  // Unmanaged tables declared via r.unmanagedTable() — `EntityTableMeta`
+  // shape (post-drizzle), keyed by feature-local table-name. Cousin of
+  // rawTables: same bypass-justification contract, different storage
+  // shape. `kumiko schema generate` aggregates these alongside
+  // r.entity()-derived metas to build the full schema.
+  readonly unmanagedTables: Readonly<Record<string, UnmanagedTableEntry>>;
   // Optional Zod-schema for env-vars this feature reads at runtime.
   // Declared via `r.envSchema(z.object({...}))`. `composeEnvSchema` reads
   // this to build one app-wide schema for boot-validation + dry-run
@@ -582,6 +606,22 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // declare data via `r.entity()` instead.
   rawTable(name: string, table: PgTable, options: RawTableOptions): void;
 
+  // Declare an "unmanaged" framework-native table (post-drizzle).
+  // EntityTableMeta carries the same column-shape that r.entity() builds,
+  // minus the audit-trail + base-columns scaffolding — used for read-side
+  // projections of event-streams (delivery-attempts, job-run-logs) where
+  // r.entity()'s aggregate-lifecycle assumptions don't fit.
+  //
+  // The `meta` argument is the result of `defineUnmanagedTable(...)` from
+  // `@cosmicdrift/kumiko-framework/db`. Reason-justification + audit-trail
+  // contract identical to `r.rawTable`.
+  //
+  // Why this exists separate from `r.rawTable`: rawTable carries a Drizzle
+  // `PgTable` (legacy), unmanagedTable carries the new `EntityTableMeta`
+  // shape that `migrate-runner` consumes. After the full drizzle-cut they
+  // will likely merge; for now they coexist.
+  unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void;
+
   // Register the tree-actions schema for this feature — a map of
   // action-name → action-definition (with optional typed args). At-most-
   // one call per feature.

package/src/engine/types/index.ts

@@ -70,6 +70,8 @@ export type {
   SecretKeyDefinition,
   SecretKeyHandle,
   SecretOptions,
+  UnmanagedTableDef,
+  UnmanagedTableEntry,
 } from "./feature";
 export type {
   AnyFileFieldDef,