@cosmicdrift/kumiko-framework 0.15.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.15.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/auth-routes.ts

@@ -6,6 +6,7 @@ import { createSystemUser } from "../engine/system-user";
 import { type SessionUser, SYSTEM_TENANT_ID, type TenantId } from "../engine/types";
 import { NotFoundError } from "../errors";
 import type { Dispatcher } from "../pipeline/dispatcher";
+import { parseStringArrayJson } from "../utils/parse-string-array-json";
 import { Routes } from "./api-constants";
 import {
   AUTH_COOKIE_NAME,
@@ -819,11 +820,7 @@ export function createAuthRoutes(
         )) as { roles?: string | null } | null;
         const raw = userRow?.roles;
         if (typeof raw === "string" && raw.length > 0) {
-          // @cast-boundary db-row — userTable.roles is JSON-encoded string[] per AuthUserRow contract
-          const parsed = JSON.parse(raw) as unknown;
-          if (Array.isArray(parsed) && parsed.every((r) => typeof r === "string")) {
-            globalRoles = parsed;
-          }
+          globalRoles = parseStringArrayJson(raw);
         }
       } catch (e) {
         // Non-fatal: globale Rollen kann nicht aufgelöst werden → switch

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

@@ -22,6 +22,7 @@
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
+import { parseJsonSafe } from "../utils/safe-json";
 
 // Idempotent snake_case → camelCase. `env.camelCase` always lowercases first
 // (designed for SHOUT_CASE input) — for already-camelCase keys (mock rows
@@ -106,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
@@ -153,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`).
@@ -173,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`).
@@ -187,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),
     };
@@ -204,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);
@@ -213,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),
   };
@@ -240,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;
@@ -276,21 +371,31 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
       const t = instantFromDriver(value);
       if (t !== null) coerced = t;
     } else if (pgType === "jsonb" && typeof value === "string") {
-      try {
-        coerced = JSON.parse(value);
-      } catch {
-        // leave as string on parse error — caller decides
-      }
-    } 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
+      coerced = parseJsonSafe(value, value);
+    } 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;
@@ -307,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.
@@ -324,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() };
@@ -368,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: ">=",
@@ -425,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[] = [];
@@ -443,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>[];
@@ -469,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];
@@ -505,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))
@@ -540,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);
@@ -570,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)}`;
@@ -678,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);
@@ -750,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/compliance/profiles.ts

@@ -33,6 +33,7 @@
 //
 // Siehe docs/plans/datenschutz/compliance-profiles.md.
 
+import { isPlainObject } from "../utils/is-plain-object";
 import type { BundleTier } from "./sub-processors";
 
 // --- Profile-Schema ---
@@ -302,10 +303,6 @@ export type ComplianceProfileOverride = DeepReadonly<DeepPartial<ComplianceProfi
 
 type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
 
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
 // Pfade die als ganzes Atom ersetzt werden (NICHT rekursiv gemergt).
 // Notwendig fuer Diskriminierte-Union-Types wo das Patch ein Schwester-
 // Property statt einer Override sein kann — z.B. retention von

package/src/db/__tests__/cursor.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { decodeCursor, encodeCursor } from "../cursor";
+
+describe("encodeCursor / decodeCursor", () => {
+  test("round-trips string ids", () => {
+    const id = "0194a1b2-c3d4-7890-abcd-ef1234567890";
+    expect(decodeCursor(encodeCursor(id))).toBe(id);
+  });
+
+  test("round-trips numeric ids", () => {
+    expect(decodeCursor(encodeCursor(42))).toBe("42");
+  });
+
+  test("decodeCursor throws on empty payload", () => {
+    expect(() => decodeCursor(encodeCursor(""))).toThrow(/Invalid cursor/);
+  });
+});

package/src/db/__tests__/migrate-generator.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import type { EntityTableMeta } from "../entity-table-meta";
+import {
+  diffSnapshots,
+  generateMigration,
+  renderMigrationSql,
+  snapshotFromMetas,
+} from "../migrate-generator";
+
+function meta(
+  tableName: string,
+  extraColumn?: EntityTableMeta["columns"][number],
+): EntityTableMeta {
+  return {
+    tableName,
+    source: "unmanaged",
+    indexes: [],
+    columns: [
+      { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+      ...(extraColumn ? [extraColumn] : []),
+    ],
+  };
+}
+
+describe("snapshotFromMetas", () => {
+  test("sorts tables by name for stable snapshots", () => {
+    const snap = snapshotFromMetas([meta("zebras"), meta("apples")]);
+    expect(snap.tables.map((t) => t.tableName)).toEqual(["apples", "zebras"]);
+    expect(snap.version).toBe(1);
+  });
+});
+
+describe("diffSnapshots", () => {
+  test("null prev → all tables are new", () => {
+    const next = snapshotFromMetas([meta("tasks")]);
+    const diff = diffSnapshots(null, next);
+    expect(diff.newTables.map((t) => t.tableName)).toEqual(["tasks"]);
+    expect(diff.droppedTables).toEqual([]);
+  });
+
+  test("detects dropped table and new column", () => {
+    const prev = snapshotFromMetas([meta("tasks"), meta("legacy")]);
+    const next = snapshotFromMetas([
+      meta("tasks", { name: "title", pgType: "text", notNull: true }),
+    ]);
+    const diff = diffSnapshots(prev, next);
+    expect(diff.droppedTables).toEqual(["legacy"]);
+    expect(diff.changedTables[0]?.newColumns.map((c) => c.name)).toEqual(["title"]);
+  });
+});
+
+describe("renderMigrationSql / generateMigration", () => {
+  test("emits CREATE TABLE for new tables", () => {
+    const diff = diffSnapshots(null, snapshotFromMetas([meta("tasks")]));
+    const sql = renderMigrationSql(diff, { name: "init", sequenceNumber: 1 });
+    expect(sql).toContain('CREATE TABLE IF NOT EXISTS "tasks"');
+    expect(sql).toContain("Migration 0001_init");
+  });
+
+  test("generateMigration bundles snapshot + sql", () => {
+    const out = generateMigration({
+      metas: [meta("tasks")],
+      prevSnapshot: null,
+      name: "init",
+      sequenceNumber: 1,
+    });
+    expect(out.snapshot.tables).toHaveLength(1);
+    expect(out.sqlContent).toContain("0001_init");
+    expect(out.filename).toBe("0001_init.sql");
+  });
+});

package/src/db/__tests__/migrate-runner.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+import { splitSqlStatements } from "../migrate-runner";
+
+describe("splitSqlStatements", () => {
+  test("splits on semicolons and strips line comments", () => {
+    const sql = `
+      CREATE TABLE "a" (id uuid); -- inline comment
+      CREATE TABLE "b" (id uuid);
+    `;
+    expect(splitSqlStatements(sql)).toEqual([
+      'CREATE TABLE "a" (id uuid);',
+      'CREATE TABLE "b" (id uuid);',
+    ]);
+  });
+
+  test("filters empty segments", () => {
+    expect(splitSqlStatements("-- only comments\n; ;")).toEqual([]);
+  });
+});

package/src/db/__tests__/pg-error.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation } from "../pg-error";
+
+describe("extractPgError", () => {
+  test("reads code from top-level postgres-js error", () => {
+    const info = extractPgError({ code: "23505", constraint_name: "users_email_uq" });
+    expect(info).toEqual({ code: "23505", constraint_name: "users_email_uq" });
+  });
+
+  test("unwraps DrizzleQueryError.cause", () => {
+    const info = extractPgError({
+      message: "wrapper",
+      cause: { code: "23505", constraint_name: "uq" },
+    });
+    expect(info?.code).toBe("23505");
+  });
+
+  test("returns null for non-objects", () => {
+    expect(extractPgError("nope")).toBeNull();
+  });
+});
+
+describe("isUniqueViolation", () => {
+  test("true for SQLSTATE 23505", () => {
+    expect(isUniqueViolation({ code: "23505" })).toBe(true);
+  });
+
+  test("false otherwise", () => {
+    expect(isUniqueViolation({ code: "23503" })).toBe(false);
+  });
+});
+
+describe("isTableAlreadyExists", () => {
+  test("true for SQLSTATE 42P07", () => {
+    expect(isTableAlreadyExists({ code: "42P07" })).toBe(true);
+  });
+});
+
+describe("constraintOf", () => {
+  test("returns constraint_name when present", () => {
+    expect(constraintOf({ constraint_name: "users_email_uq" })).toBe("users_email_uq");
+  });
+});

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$/, "");