@cosmicdrift/kumiko-framework 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/api/routes.ts

@@ -9,6 +9,7 @@ import {
   ValidationError,
 } from "../errors";
 import type { Dispatcher } from "../pipeline/dispatcher";
+import { stringifyJson } from "../utils/safe-json";
 import { Routes } from "./api-constants";
 import { getUser } from "./auth-middleware";
 import { requestContext } from "./request-context";
@@ -25,7 +26,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       if (!result.isSuccess) {
         return writeErrorResponse(c, reraiseAsKumikoError(result.error));
       }
-      return c.json(result);
+      return jsonResponse(c, result);
     } catch (e) {
       return writeErrorResponse(c, toKumiko(e));
     }
@@ -66,7 +67,8 @@ export function createApiRoutes(dispatcher: Dispatcher) {
         // Keep failedIndex + results alongside the error envelope so callers
         // can tell which command in the batch failed and inspect the partial
         // results from the successful commands before the rollback.
-        return c.json(
+        return jsonResponse(
+          c,
           {
             isSuccess: false,
             error,
@@ -88,7 +90,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
 
     try {
       const result = await dispatcher.query(body.type, body.payload, user);
-      return c.json({ data: result });
+      return jsonResponse(c, { data: result });
     } catch (e) {
       return queryErrorResponse(c, toKumiko(e));
     }
@@ -109,6 +111,10 @@ export function createApiRoutes(dispatcher: Dispatcher) {
   return api;
 }
 
+function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode = 200) {
+  return c.body(stringifyJson(body), status, { "Content-Type": "application/json" });
+}
+
 function toKumiko(e: unknown): KumikoError {
   if (isKumikoError(e)) return e;
   if (e instanceof Error) return new InternalError({ cause: e });

package/src/bun-db/__tests__/query-guards.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { incrementCounter, selectMany } from "../query";
+
+const meta = {
+  source: "unmanaged" as const,
+  tableName: "read_items",
+  indexes: [],
+  columns: [
+    { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "count", pgType: "integer", notNull: true },
+  ],
+};
+
+// A db whose unsafe() blows up — proves the guard throws BEFORE any SQL runs.
+const explodingDb = {
+  unsafe: async () => {
+    throw new Error("unsafe must not be reached when a guard rejects");
+  },
+};
+
+describe("bun-db guards — limit injection", () => {
+  test("selectMany rejects a non-integer limit", async () => {
+    await expect(selectMany(explodingDb, meta, undefined, { limit: 1.5 })).rejects.toThrow(
+      "limit must be a non-negative integer",
+    );
+  });
+
+  test("selectMany rejects a negative limit", async () => {
+    await expect(selectMany(explodingDb, meta, undefined, { limit: -1 })).rejects.toThrow(
+      "limit must be a non-negative integer",
+    );
+  });
+});
+
+describe("bun-db guards — silent tenant-scope bypass", () => {
+  // A TenantDb-shaped handle: has .raw.unsafe + the scoped methods + tenantId.
+  const tenantDb = {
+    raw: { unsafe: async () => [] as unknown[] },
+    tenantId: "00000000-0000-4000-8000-000000000001",
+    selectMany: async () => [],
+    fetchOne: async () => undefined,
+    insertOne: async () => undefined,
+    updateMany: async () => [],
+    deleteMany: async () => {},
+  };
+
+  test("incrementCounter refuses a tenant-scoped db (would bypass the filter)", async () => {
+    await expect(
+      incrementCounter(tenantDb, meta, { tenantId: tenantDb.tenantId }, { count: 1 }),
+    ).rejects.toThrow("does not apply the tenant filter");
+  });
+});

package/src/bun-db/query.ts

@@ -107,6 +107,59 @@ export function asRawClient(db: unknown): RawClient {
   );
 }
 
+/**
+ * When handlers call `selectMany(ctx.db, …)` instead of `ctx.db.selectMany(…)`,
+ * unwrap via asRawClient would bypass TenantDb scoping. Duck-type TenantDb and
+ * delegate so reads/writes keep tenant filter + tenantId injection.
+ */
+type TenantDbDelegate = {
+  selectMany<TRow>(
+    table: TableLike,
+    where?: WhereObject,
+    options?: SelectOptions,
+  ): Promise<readonly TRow[]>;
+  fetchOne<TRow>(table: TableLike, where: WhereObject): Promise<TRow | undefined>;
+  insertOne<TRow>(table: TableLike, values: Record<string, unknown>): Promise<TRow | undefined>;
+  updateMany<TRow>(
+    table: TableLike,
+    set: Record<string, unknown>,
+    where: WhereObject,
+  ): Promise<readonly TRow[]>;
+  deleteMany(table: TableLike, where: WhereObject): Promise<void>;
+};
+
+function tenantDbDelegate(db: unknown): TenantDbDelegate | undefined {
+  if (typeof db !== "object" || db === null) return undefined;
+  const d = db as Record<string, unknown>;
+  const raw = d["raw"];
+  if (
+    raw &&
+    typeof (raw as Record<string, unknown>)["unsafe"] === "function" &&
+    typeof d["selectMany"] === "function" &&
+    typeof d["fetchOne"] === "function" &&
+    typeof d["insertOne"] === "function" &&
+    typeof d["updateMany"] === "function" &&
+    typeof d["deleteMany"] === "function" &&
+    "tenantId" in d
+  ) {
+    return db as TenantDbDelegate;
+  }
+  return undefined;
+}
+
+// Guard for helpers that do NOT delegate to TenantDb (upsert/increment/insertMany):
+// passing a TenantDb here would silently run unscoped against `.raw`, bypassing
+// the tenant filter. Fail loudly so the caller picks `ctx.db.<method>` (scoped)
+// or `ctx.db.raw` (explicit cross-tenant) on purpose.
+function assertNotTenantScoped(db: unknown, fnName: string): void {
+  if (tenantDbDelegate(db) !== undefined) {
+    throw new Error(
+      `${fnName}: received a tenant-scoped db but this helper does not apply the tenant filter. ` +
+        `Pass ctx.db.raw for an explicit cross-tenant op, or use a scoped TenantDb method.`,
+    );
+  }
+}
+
 export type AnyDb = BunDbRunner | unknown;
 
 // WhereValue: primitive für eq, array für IN, null für IS NULL, oder
@@ -154,6 +207,8 @@ export type TableInfo = {
   readonly columnOf: (field: string) => string;
   // pgType per column-name, for jsonb-cast detection
   readonly pgTypeOf: (column: string) => string | undefined;
+  // bigint/bigserial JS round-trip mode per DB column name
+  readonly bigintJsModeOf: (column: string) => "number" | "bigint" | undefined;
   // Inverse of columnOf — snake_case DB column → JS field-name (camelCase).
   // Used at the result boundary to rename row keys back to the API shape
   // that callers consume (`row.aggregateId` instead of `row.aggregate_id`).
@@ -174,8 +229,10 @@ export function extractTableInfo(table: TableLike): TableInfo {
     const colByField = new Map<string, string>();
     const fieldByCol = new Map<string, string>();
     const typeByCol = new Map<string, string>();
+    const bigintModeByCol = new Map<string, "number" | "bigint">();
     for (const c of meta.columns) {
       typeByCol.set(c.name, c.pgType);
+      if (c.bigintJsMode !== undefined) bigintModeByCol.set(c.name, c.bigintJsMode);
       // EntityTableMeta column names are snake_case. Map snake → snake AND
       // derive a camelCase JS field-name so result rows can be renamed back
       // to the API shape (`aggregate_id` → `aggregateId`).
@@ -188,6 +245,7 @@ export function extractTableInfo(table: TableLike): TableInfo {
       name: meta.tableName,
       columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
       pgTypeOf: (col) => typeByCol.get(col),
+      bigintJsModeOf: (col) => bigintModeByCol.get(col),
       fieldOf: (col) => fieldByCol.get(col) ?? snakeToCamel(col),
       hasColumn: (fieldOrColumn) => colByField.has(fieldOrColumn) || fieldByCol.has(fieldOrColumn),
     };
@@ -205,6 +263,17 @@ export function extractTableInfo(table: TableLike): TableInfo {
   const colByField = new Map<string, string>();
   const fieldByCol = new Map<string, string>();
   const typeByCol = new Map<string, string>();
+  const bigintModeByCol = new Map<string, "number" | "bigint">();
+  if (
+    table !== null &&
+    typeof table === "object" &&
+    "columns" in table &&
+    Array.isArray((table as EntityTableMeta).columns)
+  ) {
+    for (const c of (table as EntityTableMeta).columns) {
+      if (c.bigintJsMode !== undefined) bigintModeByCol.set(c.name, c.bigintJsMode);
+    }
+  }
   for (const [field, { name: colName, sqlType }] of cols) {
     colByField.set(field, colName);
     fieldByCol.set(colName, field);
@@ -214,6 +283,7 @@ export function extractTableInfo(table: TableLike): TableInfo {
     name,
     columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
     pgTypeOf: (col) => typeByCol.get(col),
+    bigintJsModeOf: (col) => bigintModeByCol.get(col),
     fieldOf: (col) => fieldByCol.get(col) ?? snakeToCamel(col),
     hasColumn: (fieldOrColumn) => colByField.has(fieldOrColumn) || fieldByCol.has(fieldOrColumn),
   };
@@ -241,6 +311,30 @@ function isTemporalInstant(v: unknown): boolean {
   );
 }
 
+// Postgres bigint → JS: safe integers become `number` (matches createBigIntField /
+// drizzle mode:"number"); values outside ±2^53 stay `bigint` (money cents, raw
+// unmanaged columns). Uses BigInt equality check so 9007199254740993n never
+// silently rounds to a safe integer.
+function coerceBigIntFromDriver(value: bigint | string): bigint | number {
+  let bi: bigint;
+  if (typeof value === "string") {
+    try {
+      bi = BigInt(value);
+    } catch {
+      return value as unknown as bigint;
+    }
+  } else {
+    bi = value;
+  }
+  const min = BigInt(Number.MIN_SAFE_INTEGER);
+  const max = BigInt(Number.MAX_SAFE_INTEGER);
+  if (bi >= min && bi <= max) {
+    const n = Number(bi);
+    if (BigInt(n) === bi) return n;
+  }
+  return bi;
+}
+
 function instantFromDriver(value: unknown): Temporal.Instant | null {
   if (value === null || value === undefined) return null;
   if (isTemporalInstant(value)) return value as Temporal.Instant;
@@ -278,16 +372,30 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
       if (t !== null) coerced = t;
     } else if (pgType === "jsonb" && typeof value === "string") {
       coerced = parseJsonSafe(value, value);
-    } else if ((pgType === "bigint" || pgType === "bigserial") && typeof value === "string") {
-      // postgres-js returns BIGINT as string to avoid JS-Number precision
-      // loss past 2^53. Framework contract: bigint columns surface as
-      // JS `bigint`. Drizzle's bigint customType did this conversion
-      // invisibly; the native dialect rebuild needs it explicit.
-      try {
-        coerced = BigInt(value);
-      } catch {
-        // leave as string on parse error
+    } else if (
+      (pgType === "bigint" || pgType === "bigserial") &&
+      (typeof value === "string" || typeof value === "bigint")
+    ) {
+      const jsMode = info.bigintJsModeOf(key);
+      if (jsMode === "number") {
+        coerced = coerceBigIntFromDriver(value);
+      } else if (typeof value === "string") {
+        try {
+          coerced = BigInt(value);
+        } catch {
+          // leave as string on parse error
+        }
+      } else {
+        coerced = value;
       }
+    } else if (
+      (pgType === "integer" || pgType === "int4" || pgType === "smallint" || pgType === "int2") &&
+      (typeof value === "bigint" || typeof value === "string")
+    ) {
+      // Bun.SQL / some drivers return int4 as bigint or numeric string.
+      // Drizzle coerced to number for numberField columns — match that.
+      const n = typeof value === "bigint" ? Number(value) : Number(value);
+      if (!Number.isNaN(n)) coerced = n;
     }
     const fieldName = info.fieldOf(key);
     if (fieldName !== key) changed = true;
@@ -304,8 +412,8 @@ function coerceRows<T extends Record<string, unknown>>(
   return rows.map((r) => coerceRow(r, info));
 }
 
-// Helper für jsonb-Werte: Bun.sql kann arrays/objects nicht direkt als
-// jsonb binden — wir JSON.stringify + ::jsonb cast.
+// Helper für jsonb-Werte: structured values binden als JS object/array mit
+// ::jsonb cast. JSON.stringify vor dem cast würde JSON-string-scalars erzeugen.
 // Plus Temporal.Instant → ISO string coercion for timestamptz columns.
 // SqlExpression (sql`now()`, sql`gen_random_uuid()`) wird als kind:"literal"
 // returned — Caller embedded das inline statt einen $N-placeholder zu setzen.
@@ -321,13 +429,21 @@ function prepareValue(value: unknown, pgType: string | undefined): PreparedValue
   if (isSqlExpression(value)) {
     return { kind: "literal", literal: value.text };
   }
-  if (
-    pgType === "jsonb" &&
-    value !== null &&
-    typeof value === "object" &&
-    !isTemporalInstant(value)
-  ) {
-    return { kind: "param", sql: "::jsonb", bound: JSON.stringify(value) };
+  if (pgType === "jsonb" && value !== null) {
+    if (typeof value === "boolean") {
+      return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
+    if (typeof value === "object" && !isTemporalInstant(value)) {
+      // Plain objects: bind directly — JSON.stringify + ::jsonb stores a JSON string scalar.
+      if (!Array.isArray(value)) {
+        return { kind: "param", sql: "::jsonb", bound: value };
+      }
+      // All-boolean arrays are inferred as boolean[] by postgres-js; route via text::jsonb.
+      if (value.length > 0 && value.every((entry) => typeof entry === "boolean")) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+      }
+      return { kind: "param", sql: "::jsonb", bound: value };
+    }
   }
   if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
     return { kind: "param", sql: "", bound: (value as Temporal.Instant).toString() };
@@ -365,6 +481,10 @@ function buildWhereClause(
         conditions.push(`${quoteIdent(col)} IN (${parts.join(", ")})`);
       }
     } else if (isWhereOperator(value)) {
+      if (value.ne === null && Object.keys(value).length === 1) {
+        conditions.push(`${quoteIdent(col)} IS NOT NULL`);
+        continue;
+      }
       const opMap: Record<string, string> = {
         gt: ">",
         gte: ">=",
@@ -422,6 +542,10 @@ export async function selectMany<TRow = any>(
   where?: WhereObject,
   options?: SelectOptions,
 ): Promise<readonly TRow[]> {
+  const scoped = tenantDbDelegate(db);
+  if (scoped) {
+    return scoped.selectMany<TRow>(table, where, options);
+  }
   const info = extractTableInfo(table);
   let sqlText = `SELECT * FROM ${quoteIdent(info.name)}`;
   let values: unknown[] = [];
@@ -440,6 +564,11 @@ export async function selectMany<TRow = any>(
     if (parts.length > 0) sqlText += ` ORDER BY ${parts.join(", ")}`;
   }
   if (options?.limit !== undefined) {
+    // Interpolated, not bound — guard against a non-integer slipping in via an
+    // `any`-typed call site and injecting SQL.
+    if (!Number.isInteger(options.limit) || options.limit < 0) {
+      throw new Error(`selectMany: limit must be a non-negative integer, got ${options.limit}`);
+    }
     sqlText += ` LIMIT ${options.limit}`;
   }
   const raw = (await asRawClient(db).unsafe(sqlText, values)) as readonly Record<string, unknown>[];
@@ -466,6 +595,7 @@ export async function insertMany<TRow = any>(
   rows: ReadonlyArray<Record<string, unknown>>,
 ): Promise<readonly TRow[]> {
   if (rows.length === 0) return [];
+  assertNotTenantScoped(db, "insertMany");
   const info = extractTableInfo(table);
   // Use the column-set from the first row; assume all rows share keys.
   const firstRow = rows[0];
@@ -502,6 +632,10 @@ export async function insertOne<TRow = any>(
   table: TableLike,
   values: Record<string, unknown>,
 ): Promise<TRow | undefined> {
+  const scoped = tenantDbDelegate(db);
+  if (scoped) {
+    return scoped.insertOne<TRow>(table, values);
+  }
   const info = extractTableInfo(table);
   const entries = Object.entries(values)
     .filter(([k]) => info.hasColumn(k))
@@ -537,6 +671,10 @@ export async function updateMany<TRow = any>(
   set: Record<string, unknown>,
   where: WhereObject,
 ): Promise<readonly TRow[]> {
+  const scoped = tenantDbDelegate(db);
+  if (scoped) {
+    return scoped.updateMany<TRow>(table, set, where);
+  }
   const info = extractTableInfo(table);
   const setEntries = Object.entries(set).map(([k, v]) => {
     const col = info.columnOf(k);
@@ -567,6 +705,10 @@ export async function updateMany<TRow = any>(
 }
 
 export async function deleteMany(db: AnyDb, table: TableLike, where: WhereObject): Promise<void> {
+  const scoped = tenantDbDelegate(db);
+  if (scoped) {
+    return scoped.deleteMany(table, where);
+  }
   const info = extractTableInfo(table);
   const w = buildWhereClause(info, where, 1);
   let sqlText = `DELETE FROM ${quoteIdent(info.name)}`;
@@ -675,6 +817,7 @@ export async function upsertOnConflict<TRow = any>(
   values: Record<string, unknown>,
   options: UpsertOnConflictOptions,
 ): Promise<TRow | undefined> {
+  assertNotTenantScoped(db, "upsertOnConflict");
   const info = extractTableInfo(table);
   const entries = insertEntries(info, values);
   const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);
@@ -747,6 +890,7 @@ export async function incrementCounter<TRow = any>(
   increments: Record<string, number>,
   options: IncrementCounterOptions = {},
 ): Promise<TRow | undefined> {
+  assertNotTenantScoped(db, "incrementCounter");
   const info = extractTableInfo(table);
   const entries = insertEntries(info, values);
   const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);

package/src/db/assert-exists-in.ts

@@ -4,6 +4,10 @@ import { NotFoundError } from "../errors";
 import type { DbConnection } from "./connection";
 import type { TenantDb } from "./tenant-db";
 
+function isTenantDb(db: DbConnection | TenantDb): db is TenantDb {
+  return typeof (db as TenantDb).fetchOne === "function" && "raw" in db;
+}
+
 /**
  * Generic constraint helper: asserts a value exists in a table.
  * Returns a ready-to-return NotFoundError when the row is missing, or null
@@ -32,7 +36,7 @@ export async function assertExistsIn(
   if (options.tenantId !== undefined) where["tenantId"] = options.tenantId;
   if (options.where) Object.assign(where, options.where);
 
-  const row = await fetchOne(db, entity, where);
+  const row = isTenantDb(db) ? await db.fetchOne(entity, where) : await fetchOne(db, entity, where);
 
   if (!row) {
     const entityName = options.entityName ?? String(options.field).replace(/Id$/, "");

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/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/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/event-store/__tests__/get-stream-version-perf.integration.test.ts

@@ -11,10 +11,11 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { insertMany } from "../../bun-db/query";
 import type { TenantId } from "../../engine/types";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { generateId as uuid } from "../../utils";
-import { append, createEventsTable, getStreamVersion } from "../index";
+import { createEventsTable, eventsTable, getStreamVersion } from "../index";
 
 let testDb: BunTestDb;
 const tenantId: TenantId = uuid();
@@ -31,17 +32,19 @@ afterAll(async () => {
 });
 
 async function seedStream(aggregateId: string, count: number): Promise<void> {
-  for (let v = 0; v < count; v++) {
-    await append(testDb.db, {
-      aggregateId,
-      aggregateType: "perfAgg",
-      tenantId,
-      expectedVersion: v,
-      type: "perfAgg.created",
-      payload: { seq: v },
-      metadata: { userId },
-    });
-  }
+  // Bulk-seed — 2000 sequential append() calls dominate runtime and flake
+  // under load. We measure getStreamVersion(), not append latency.
+  const rows = Array.from({ length: count }, (_, i) => ({
+    aggregateId,
+    aggregateType: "perfAgg",
+    tenantId,
+    version: i + 1,
+    type: "perfAgg.created",
+    payload: { seq: i },
+    metadata: { userId },
+    createdBy: userId,
+  }));
+  await insertMany(testDb.db, eventsTable, rows);
 }
 
 describe("event-store: getStreamVersion perf on hot streams", () => {

package/src/event-store/admin-api.ts

@@ -17,6 +17,7 @@ import {
   insertRawSubsequentEvent,
 } from "../db/queries/event-store-admin";
 import type { TenantId } from "../engine/types";
+import { stringifyJson } from "../utils/safe-json";
 import { VersionConflictError } from "./errors";
 import type { EventMetadata } from "./event-store";
 
@@ -68,8 +69,8 @@ function rawEventParams(event: RawEventToAppend, newVersion: number, eventVersio
     newVersion,
     type: event.type,
     eventVersion,
-    payloadJson: JSON.stringify(event.payload),
-    metadataJson: JSON.stringify(event.metadata),
+    payloadJson: stringifyJson(event.payload),
+    metadataJson: stringifyJson(event.metadata),
     createdAt: event.createdAt.toString(),
     createdBy: event.createdBy,
   };
@@ -129,8 +130,8 @@ export async function appendRawBatch(
       newVersion,
       e.type,
       eventVersion,
-      JSON.stringify(e.payload),
-      JSON.stringify(e.metadata),
+      stringifyJson(e.payload),
+      stringifyJson(e.metadata),
       e.createdAt.toString(),
       e.createdBy,
     );

package/src/event-store/event-store.ts

@@ -9,6 +9,7 @@ import {
 } from "../db/queries/event-store";
 import { insertOne, selectMany } from "../db/query";
 import type { TenantId } from "../engine/types";
+import { stringifyJson } from "../utils/safe-json";
 import { isStreamArchived } from "./archive";
 import { VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
@@ -173,8 +174,8 @@ async function insertSubsequentEvent(
     newVersion,
     type: event.type,
     eventVersion,
-    payloadJson: JSON.stringify(event.payload),
-    metadataJson: JSON.stringify(event.metadata),
+    payloadJson: stringifyJson(event.payload),
+    metadataJson: stringifyJson(event.metadata),
     createdBy: event.metadata.userId,
     expectedVersion: event.expectedVersion,
   });

package/src/event-store/snapshot.ts

@@ -17,6 +17,7 @@ import { selectMany } from "../db/query";
 import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
 import { unsafePushTables } from "../stack";
+import { stringifyJson } from "../utils/safe-json";
 import { isStreamArchived } from "./archive";
 import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
 
@@ -107,7 +108,7 @@ export async function saveSnapshot(db: DbRunner, args: SaveSnapshotArgs): Promis
     tenantId: args.tenantId,
     aggregateType: args.aggregateType,
     version: args.version,
-    stateJson: JSON.stringify(args.state),
+    stateJson: stringifyJson(args.state),
   });
 }
 

package/src/migrations/__tests__/kumiko-drift.integration.test.ts

@@ -0,0 +1,161 @@
+// Integration-Test für das drizzle-freie Boot-Gate (detectKumikoDrift /
+// assertKumikoSchemaCurrent). Production-Behavior: dieses Gate blockiert
+// Container-Starts — jeder False-Positive blockt Boot, jeder False-Negative
+// lässt Schema-Drift durch.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { buildEntityTableMeta } from "../../db/entity-table-meta";
+import { generateMigration, writeSnapshotJson } from "../../db/migrate-generator";
+import {
+  baselineMigrations,
+  loadMigrationsFromDir,
+  runMigrationsFromDir,
+} from "../../db/migrate-runner";
+import { asRawClient } from "../../db/query";
+import { createEntity, createTextField } from "../../engine";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { assertKumikoSchemaCurrent, detectKumikoDrift, SchemaDriftError } from "../kumiko-drift";
+
+let testDb: BunTestDb;
+let dir: string;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  dir = mkdtempSync(join(tmpdir(), "kumiko-mig-"));
+  // Isoliere: tracking-table + Test-Tabellen pro Test zurücksetzen.
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "_kumiko_migrations"`);
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "kdrift_widget"`);
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "kdrift_gen"`);
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function writeMigration(file: string, sql: string): void {
+  writeFileSync(join(dir, file), sql);
+}
+
+function writeSnapshot(tableNames: readonly string[]): void {
+  const tables = tableNames.map((tableName) => ({ tableName, columns: [] }));
+  writeFileSync(join(dir, ".snapshot.json"), JSON.stringify({ version: 1, tables }));
+}
+
+describe("kumiko-drift boot-gate", () => {
+  test("applied + table exists → ok", async () => {
+    writeMigration("0001_init.sql", `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdrift_widget"]);
+    await runMigrationsFromDir(testDb.db, dir);
+
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+    await expect(assertKumikoSchemaCurrent(testDb.db, dir)).resolves.toBeUndefined();
+  });
+
+  test("checked-in migration not applied → pending drift", async () => {
+    writeMigration("0001_init.sql", `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdrift_widget"]);
+    // NICHT applyen.
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(false);
+    expect(report.pending).toEqual(["0001_init"]);
+    await expect(assertKumikoSchemaCurrent(testDb.db, dir)).rejects.toBeInstanceOf(
+      SchemaDriftError,
+    );
+  });
+
+  test("applied migration edited afterwards → checksum mismatch", async () => {
+    writeMigration("0001_init.sql", `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdrift_widget"]);
+    await runMigrationsFromDir(testDb.db, dir);
+
+    // File nachträglich editieren (anderer Inhalt → andere checksum).
+    writeMigration(
+      "0001_init.sql",
+      `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY, "x" int);`,
+    );
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(false);
+    expect(report.checksumMismatches.map((m) => m.id)).toEqual(["0001_init"]);
+  });
+
+  test("snapshot table missing in DB → missingTables", async () => {
+    writeMigration("0001_init.sql", `SELECT 1;`); // applied, aber legt die Tabelle NICHT an
+    writeSnapshot(["kdrift_widget"]);
+    await runMigrationsFromDir(testDb.db, dir);
+
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(false);
+    expect(report.missingTables).toEqual(["kdrift_widget"]);
+  });
+
+  test("baseline marks migrations applied without running SQL", async () => {
+    // Tabelle existiert schon (wie eine adoptierte Prod-DB), Migration NICHT applyen.
+    await asRawClient(testDb.db).unsafe(`CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY)`);
+    writeMigration("0001_init.sql", `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdrift_widget"]);
+
+    const result = await baselineMigrations(testDb.db, loadMigrationsFromDir(dir));
+    expect(result.marked).toEqual(["0001_init"]);
+
+    // Danach drift-frei (applied via baseline, Tabelle existiert), und re-baseline ist no-op.
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+    const again = await baselineMigrations(testDb.db, loadMigrationsFromDir(dir));
+    expect(again.marked).toEqual([]);
+    expect(again.alreadyTracked).toEqual(["0001_init"]);
+  });
+});
+
+describe("kumiko-drift end-to-end (generate → apply → gate)", () => {
+  test("generate from entity metas → apply → gate ok (the local-verify proof)", async () => {
+    const entity = createEntity({
+      table: "kdrift_gen",
+      fields: { name: createTextField({ required: true }) },
+    });
+    const meta = buildEntityTableMeta("kdriftGen", entity);
+    const result = generateMigration({
+      metas: [meta],
+      prevSnapshot: null,
+      name: "init",
+      sequenceNumber: 1,
+    });
+
+    writeFileSync(join(dir, result.filename), result.sqlContent);
+    writeSnapshotJson(join(dir, ".snapshot.json"), result.snapshot);
+
+    await runMigrationsFromDir(testDb.db, dir);
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+  });
+
+  test("prod adoption via commented-out SQL: apply is a recorded no-op, gate ok when tables pre-exist", async () => {
+    // Prod-Szenario: Tabelle existiert schon (drizzle-Ära). Das Migration-File
+    // ist auskommentiert → apply legt nichts an, RECORDED aber den Eintrag in
+    // _kumiko_migrations. Gate: applied ✓ + Tabelle existiert ✓ → Boot läuft.
+    await asRawClient(testDb.db).unsafe(`CREATE TABLE "kdrift_gen" ("id" text PRIMARY KEY)`);
+    writeMigration(
+      "0001_init.sql",
+      `-- CREATE TABLE "kdrift_gen" ("id" text PRIMARY KEY);  -- commented for prod adoption`,
+    );
+    writeSnapshot(["kdrift_gen"]);
+
+    const applyResult = await runMigrationsFromDir(testDb.db, dir);
+    expect(applyResult.applied).toEqual(["0001_init"]); // recorded trotz no-op-SQL
+
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+  });
+});

package/src/migrations/index.ts

@@ -1,3 +1,14 @@
+// Drizzle-free gate (kumiko/migrations system) — the canonical boot-gate.
+// `SchemaDriftError` is re-exported from here; the legacy drizzle gate above
+// keeps its own internal error until Phase 3 removes schema-drift.ts.
+export {
+  assertKumikoSchemaCurrent,
+  type ChecksumMismatch,
+  detectKumikoDrift,
+  formatKumikoDriftReport,
+  type KumikoDriftReport,
+  SchemaDriftError,
+} from "./kumiko-drift";
 export {
   buildProjectionTableIndex,
   type ChangedTable,
@@ -22,7 +33,6 @@ export {
   loadLatestSnapshot,
   loadPreviousSnapshot,
   loadSnapshot,
-  SchemaDriftError,
   type Snapshot,
   type SnapshotTable,
 } from "./schema-drift";

package/src/migrations/kumiko-drift.ts

@@ -0,0 +1,122 @@
+// Drizzle-free schema-drift gate for the `kumiko/migrations` system.
+//
+// Replaces the drizzle-journal gate (schema-drift.ts). Validates two layers
+// against the checked-in artifacts:
+//
+//   1. Migrations applied: every `kumiko/migrations/*.sql` has a row in
+//      `_kumiko_migrations`. Applied-but-edited (checksum mismatch) is drift.
+//   2. Tables exist: every table in `kumiko/migrations/.snapshot.json` exists.
+//
+// Contract (unchanged from the legacy gate): boot VALIDATES only, never
+// applies. Apply is the deploy-step `kumiko schema apply` (runMigrationsFromDir).
+//
+// Layer 3 (column-diff against the snapshot's ColumnMeta — catches manual
+// ALTERs / stale defs) is a documented follow-up; see
+// docs/plans/migration-system-consolidation.md.
+
+import { join } from "node:path";
+import type { DbConnection } from "../db/connection";
+import { loadSnapshotJson } from "../db/migrate-generator";
+import { fetchAppliedMigrations, loadMigrationsFromDir } from "../db/migrate-runner";
+import { tableExists } from "../db/schema-inspection";
+
+const SNAPSHOT_FILENAME = ".snapshot.json";
+
+export type ChecksumMismatch = {
+  readonly id: string;
+  readonly expected: string; // checksum recorded in _kumiko_migrations
+  readonly actual: string; // checksum of the file on disk now
+};
+
+export type KumikoDriftReport = {
+  readonly ok: boolean;
+  readonly pending: readonly string[];
+  readonly checksumMismatches: readonly ChecksumMismatch[];
+  readonly missingTables: readonly string[];
+};
+
+export class SchemaDriftError extends Error {
+  readonly report: KumikoDriftReport;
+  constructor(message: string, report: KumikoDriftReport) {
+    super(message);
+    this.name = "SchemaDriftError";
+    this.report = report;
+  }
+}
+
+export async function detectKumikoDrift(
+  db: DbConnection,
+  migrationsDir: string,
+): Promise<KumikoDriftReport> {
+  const local = loadMigrationsFromDir(migrationsDir);
+  // Frische DB ohne je gelaufenes `kumiko schema apply` → tracking-table fehlt.
+  // Das ist kein Fehler, sondern "nichts applied" → alle local sind pending.
+  const trackingExists = await tableExists(db, "_kumiko_migrations");
+  const applied = trackingExists
+    ? new Map((await fetchAppliedMigrations(db)).map((a) => [a.id, a.checksum] as const))
+    : new Map<string, string>();
+
+  const pending: string[] = [];
+  const checksumMismatches: ChecksumMismatch[] = [];
+  for (const m of local) {
+    const appliedChecksum = applied.get(m.id);
+    if (appliedChecksum === undefined) {
+      pending.push(m.id);
+    } else if (appliedChecksum !== m.checksum) {
+      checksumMismatches.push({ id: m.id, expected: appliedChecksum, actual: m.checksum });
+    }
+  }
+
+  // Layer 2 — tables from the latest snapshot must exist. No snapshot (app
+  // hasn't generated one yet) → skip table-existence, the migrations-applied
+  // layer still gates.
+  const snapshot = loadSnapshotJson(join(migrationsDir, SNAPSHOT_FILENAME));
+  const missingTables: string[] = [];
+  if (snapshot) {
+    const checks = await Promise.all(
+      snapshot.tables.map((t) =>
+        tableExists(db, t.tableName).then((exists) => ({ name: t.tableName, exists })),
+      ),
+    );
+    for (const c of checks) if (!c.exists) missingTables.push(c.name);
+  }
+
+  return {
+    ok: pending.length === 0 && checksumMismatches.length === 0 && missingTables.length === 0,
+    pending,
+    checksumMismatches,
+    missingTables,
+  };
+}
+
+export function formatKumikoDriftReport(report: KumikoDriftReport): string {
+  if (report.ok) return "Schema is current.";
+  const lines: string[] = ["Schema drift detected:"];
+  if (report.pending.length > 0) {
+    lines.push(`  ${report.pending.length} unapplied migration(s):`);
+    for (const id of report.pending) lines.push(`    - ${id}`);
+  }
+  if (report.checksumMismatches.length > 0) {
+    lines.push(`  ${report.checksumMismatches.length} edited-after-apply migration(s):`);
+    for (const m of report.checksumMismatches) {
+      lines.push(`    - ${m.id}: db ${m.expected.slice(0, 12)}…, file ${m.actual.slice(0, 12)}…`);
+    }
+  }
+  if (report.missingTables.length > 0) {
+    lines.push(`  ${report.missingTables.length} missing table(s):`);
+    for (const t of report.missingTables) lines.push(`    - ${t}`);
+  }
+  lines.push("");
+  lines.push("Run 'kumiko schema apply' to bring the DB up-to-date.");
+  return lines.join("\n");
+}
+
+/** Throws SchemaDriftError with a human-readable message when the DB is not
+ *  current with the checked-in kumiko/migrations. */
+export async function assertKumikoSchemaCurrent(
+  db: DbConnection,
+  migrationsDir: string,
+): Promise<void> {
+  const report = await detectKumikoDrift(db, migrationsDir);
+  if (!report.ok) throw new SchemaDriftError(formatKumikoDriftReport(report), report);
+}

package/src/stack/request-helper.ts

@@ -4,6 +4,44 @@ import type { SessionUser } from "../engine/types";
 
 export type BatchCommand = { type: string; payload: unknown };
 
+type WireErrorBody = {
+  readonly code?: string;
+  readonly details?: {
+    readonly causeName?: string;
+    readonly causeMessage?: string;
+    readonly causeStack?: string;
+  };
+};
+
+function formatWriteFailure(type: string, body: unknown): string {
+  const parsed = body as {
+    isSuccess?: boolean;
+    error?: WireErrorBody | string;
+  };
+  const code =
+    (typeof parsed.error === "object" ? parsed.error?.code : undefined) ??
+    (typeof parsed.error === "string" ? parsed.error : "unknown");
+  const details =
+    typeof parsed.error === "object" && parsed.error?.details !== undefined
+      ? parsed.error.details
+      : undefined;
+  const causeMessage =
+    details && typeof details === "object" && "causeMessage" in details
+      ? String((details as { causeMessage?: unknown }).causeMessage ?? "")
+      : "";
+  const causeName =
+    details && typeof details === "object" && "causeName" in details
+      ? String((details as { causeName?: unknown }).causeName ?? "")
+      : "";
+  if (code === "internal_error" && (causeMessage || causeName)) {
+    return `Expected write "${type}" to succeed but got error: ${code} (${causeName}: ${causeMessage})`;
+  }
+  if (details !== undefined) {
+    return `Expected write "${type}" to succeed but got error: ${code} — ${JSON.stringify(details)}`;
+  }
+  return `Expected write "${type}" to succeed but got error: ${code}`;
+}
+
 export type RequestHelper = {
   write: (
     type: string,
@@ -123,10 +161,7 @@ export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
       // follow the error-contract shape { error: { code, i18nKey, ... } } with
       // a 4xx/5xx status — no isSuccess flag. Detect either.
       if (body.isSuccess !== true) {
-        const code =
-          (typeof body.error === "object" ? body.error?.code : undefined) ??
-          (typeof body.error === "string" ? body.error : "unknown");
-        throw new Error(`Expected write "${type}" to succeed but got error: ${code}`);
+        throw new Error(formatWriteFailure(type, body));
       }
       return body.data as T; // @cast-boundary engine-bridge
     },

package/src/stack/table-helpers.ts

@@ -107,7 +107,7 @@ export async function unsafePushTables(
         if (!prevIdxNames.has(idx.name)) {
           const kind = idx.unique ? "UNIQUE INDEX" : "INDEX";
           const colList = idx.columns.map((c) => `"${c}"`).join(", ");
-          await createIndexIfNotExists(db, kind, idx.name, meta.tableName, colList);
+          await createIndexIfNotExists(db, kind, idx.name, meta.tableName, colList, idx.whereSql);
         }
       }
     } else {

package/src/utils/index.ts

@@ -4,5 +4,5 @@ export { readPositiveIntEnv } from "./env-parse";
 export { generateId } from "./ids";
 export { isPlainObject } from "./is-plain-object";
 export { parseStringArrayJson } from "./parse-string-array-json";
-export { parseJsonOrThrow, parseJsonSafe } from "./safe-json";
+export { parseJsonOrThrow, parseJsonSafe, stringifyJson } from "./safe-json";
 export { parseRoles } from "./serialization";

package/src/utils/safe-json.ts

@@ -28,3 +28,22 @@ export function parseJsonOrThrow<T>(raw: string, context: string): T {
     throw new Error(`Invalid JSON in ${context}: ${msg}`);
   }
 }
+
+/** JSON.stringify that survives BigInt / Temporal values from DB rows. */
+export function stringifyJson(value: unknown): string {
+  return JSON.stringify(value, (_key, v) => {
+    if (typeof v === "bigint") {
+      const asNumber = Number(v);
+      if (
+        asNumber <= Number.MAX_SAFE_INTEGER &&
+        asNumber >= Number.MIN_SAFE_INTEGER &&
+        BigInt(asNumber) === v
+      ) {
+        return asNumber;
+      }
+      return v.toString();
+    }
+    if (v instanceof Temporal.Instant) return v.toString();
+    return v;
+  });
+}