@cosmicdrift/kumiko-framework 0.16.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.16.0",
+  "version": "0.19.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>",
@@ -127,6 +127,10 @@
       "types": "./src/secrets/index.ts",
       "default": "./src/secrets/index.ts"
     },
+    "./schema-cli": {
+      "types": "./src/schema-cli.ts",
+      "default": "./src/schema-cli.ts"
+    },
     "./stack": {
       "types": "./src/stack/index.ts",
       "default": "./src/stack/index.ts"

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);