@cosmicdrift/kumiko-framework 0.14.0 → 0.15.0

package/src/api/__tests__/{batch.integration.ts → batch.integration.test.ts}

@@ -1,7 +1,8 @@
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { buildDrizzleTable } from "../../db/table-builder";
+import { asRawClient, insertOne, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
 import {
   createEntity,
   createNumberField,
@@ -23,7 +24,7 @@ const itemEntity = createEntity({
   },
 });
 
-const itemTable = buildDrizzleTable("item", itemEntity);
+const itemTable = buildEntityTable("item", itemEntity);
 
 // Second entity used by an inTransaction hook to prove that hook DB writes
 // roll back with the main transaction.
@@ -34,7 +35,7 @@ const auditEntity = createEntity({
     itemId: createTextField({ required: true }),
   },
 });
-const auditTable = buildDrizzleTable("audit", auditEntity);
+const auditTable = buildEntityTable("audit", auditEntity);
 
 // Hook invocation logs — reset per test. Captures which phase each hook saw.
 const inTxHookLog: Array<{ id: EntityId; name: string }> = [];
@@ -92,10 +93,7 @@ const itemFeature = defineFeature("batch", (r) => {
     item,
     async (result, ctx) => {
       if (!ctx.db) return;
-      await ctx.db
-        .insert(auditTable)
-        .values({ action: "item_saved", itemId: result.id })
-        .returning();
+      await ctx.db.insertOne(auditTable, { action: "item_saved", itemId: result.id });
     },
     { phase: HookPhases.inTransaction },
   );
@@ -166,8 +164,8 @@ beforeEach(async () => {
   afterCommitShouldThrow = false;
   parallelismWindows.length = 0;
   stack.events.reset();
-  await stack.db.delete(itemTable);
-  await stack.db.delete(auditTable);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${itemTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${auditTable.tableName}"`);
 });
 
 describe("POST /api/batch", () => {
@@ -213,16 +211,18 @@ describe("POST /api/batch", () => {
     expect(afterCommitHookLog.map((h) => h.name)).toEqual(["alpha", "beta", "gamma"]);
 
     // Rows actually persisted
-    const rows = await stack.db.select().from(itemTable);
+    const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(3);
   });
 
   test("mid-batch failure: all writes roll back, afterCommit hooks do NOT fire", async () => {
     // Seed with one existing item so we can verify the batch didn't persist anything
-    await stack.db
-      .insert(itemTable)
-      .values({ name: "seed", counter: 0, tenantId: "00000000-0000-4000-8000-000000000001" });
-    const seedCount = (await stack.db.select().from(itemTable)).length;
+    await insertOne(stack.db, itemTable, {
+      name: "seed",
+      counter: 0,
+      tenantId: "00000000-0000-4000-8000-000000000001",
+    });
+    const seedCount = (await selectMany(stack.db, itemTable)).length;
 
     const res = await stack.http.batch(
       [
@@ -252,7 +252,7 @@ describe("POST /api/batch", () => {
     expect(afterCommitHookLog).toEqual([]);
 
     // DB: only the seed row remains, the batch's first successful write rolled back
-    const rows = await stack.db.select().from(itemTable);
+    const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(seedCount);
     expect((rows[0] as { name: string }).name).toBe("seed");
   });
@@ -264,13 +264,13 @@ describe("POST /api/batch", () => {
       admin,
     );
     expect((await okRes.json()).isSuccess).toBe(true);
-    const auditAfterOk = await stack.db.select().from(auditTable);
+    const auditAfterOk = await selectMany(stack.db, auditTable);
     expect(auditAfterOk).toHaveLength(1);
     expect((auditAfterOk[0] as { action: string }).action).toBe("item_saved");
 
     // Reset — new batch fails mid-way. Both entity rows AND audit rows must roll back.
-    await stack.db.delete(itemTable);
-    await stack.db.delete(auditTable);
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${itemTable.tableName}"`);
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${auditTable.tableName}"`);
 
     const failRes = await stack.http.batch(
       [
@@ -283,8 +283,8 @@ describe("POST /api/batch", () => {
 
     // Both tables are empty — the inTransaction audit hook's write rolled back
     // together with the item row.
-    const itemsAfterFail = await stack.db.select().from(itemTable);
-    const auditAfterFail = await stack.db.select().from(auditTable);
+    const itemsAfterFail = await selectMany(stack.db, itemTable);
+    const auditAfterFail = await selectMany(stack.db, auditTable);
     expect(itemsAfterFail).toHaveLength(0);
     expect(auditAfterFail).toHaveLength(0);
   });
@@ -328,7 +328,7 @@ describe("POST /api/batch", () => {
     expect(body.isSuccess).toBe(true);
 
     // DB row persisted (tx committed)
-    const rows = await stack.db.select().from(itemTable);
+    const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(1);
 
     // The hook AFTER the throwing one still ran — errors don't cascade
@@ -344,7 +344,7 @@ describe("POST /api/batch", () => {
     expect(firstBody.isSuccess).toBe(true);
     expect(firstBody.results).toHaveLength(1);
 
-    const rowsAfterFirst = await stack.db.select().from(itemTable);
+    const rowsAfterFirst = await selectMany(stack.db, itemTable);
     expect(rowsAfterFirst).toHaveLength(1);
 
     // Hook logs reflect one execution
@@ -359,7 +359,7 @@ describe("POST /api/batch", () => {
     expect(secondBody.results).toEqual(firstBody.results);
 
     // DB still has only one row (no double-insert)
-    const rowsAfterSecond = await stack.db.select().from(itemTable);
+    const rowsAfterSecond = await selectMany(stack.db, itemTable);
     expect(rowsAfterSecond).toHaveLength(1);
 
     // Hooks didn't fire a second time
@@ -376,8 +376,8 @@ describe("POST /api/write (single write runs in its own transaction)", () => {
 
     // Both the item row AND the audit row exist — proves the single write
     // went through a transaction and the inTx hook shared it.
-    const items = await stack.db.select().from(itemTable);
-    const audits = await stack.db.select().from(auditTable);
+    const items = await selectMany(stack.db, itemTable);
+    const audits = await selectMany(stack.db, auditTable);
     expect(items).toHaveLength(1);
     expect(audits).toHaveLength(1);
   });
@@ -385,8 +385,8 @@ describe("POST /api/write (single write runs in its own transaction)", () => {
   test("handler throw rolls back inTransaction hook writes too", async () => {
     // First a successful write so there's something to compare against
     await stack.http.write("batch:write:item:create", { name: "survivor" }, admin);
-    const beforeItems = await stack.db.select().from(itemTable);
-    const beforeAudits = await stack.db.select().from(auditTable);
+    const beforeItems = await selectMany(stack.db, itemTable);
+    const beforeAudits = await selectMany(stack.db, auditTable);
     expect(beforeItems).toHaveLength(1);
     expect(beforeAudits).toHaveLength(1);
 
@@ -395,8 +395,8 @@ describe("POST /api/write (single write runs in its own transaction)", () => {
     const body = await res.json();
     expect(body.isSuccess).toBe(false);
 
-    const afterItems = await stack.db.select().from(itemTable);
-    const afterAudits = await stack.db.select().from(auditTable);
+    const afterItems = await selectMany(stack.db, itemTable);
+    const afterAudits = await selectMany(stack.db, auditTable);
     // Counts unchanged — no partial commit
     expect(afterItems).toHaveLength(beforeItems.length);
     expect(afterAudits).toHaveLength(beforeAudits.length);

package/src/api/__tests__/body-limit.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import { buildServer } from "../server";

package/src/api/__tests__/csrf-middleware.test.ts

@@ -2,8 +2,8 @@
 // layers authMiddleware → csrfMiddleware → handler. Covers the paths that
 // matter in production: cookie + state-changing, cookie + safe, bearer.
 
+import { describe, expect, test } from "bun:test";
 import { Hono } from "hono";
-import { describe, expect, test } from "vitest";
 import { TestUsers } from "../../stack";
 import {
   AUTH_COOKIE_NAME,

package/src/api/__tests__/{dispatcher-live.integration.ts → dispatcher-live.integration.test.ts}

@@ -1,9 +1,10 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
 import { z } from "zod";
 import { generateToken } from "../../api/tokens";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { buildDrizzleTable } from "../../db/table-builder";
+import { asRawClient, insertOne, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { generateId } from "../../utils";
@@ -23,7 +24,7 @@ const itemEntity = createEntity({
   table: "dispatcher_live_items",
   fields: { name: createTextField({ required: true }) },
 });
-const itemTable = buildDrizzleTable("item", itemEntity);
+const itemTable = buildEntityTable("item", itemEntity);
 
 const itemFeature = defineFeature("dlive", (r) => {
   r.entity("item", itemEntity);
@@ -42,7 +43,7 @@ const itemFeature = defineFeature("dlive", (r) => {
     "item:list",
     z.object({}).optional(),
     async (_event, ctx) => {
-      return ctx.db.select().from(itemTable);
+      return selectMany(ctx.db, itemTable);
     },
     { access: { roles: ["Admin"] } },
   );
@@ -105,7 +106,7 @@ afterAll(async () => {
 });
 
 beforeEach(async () => {
-  await stack.db.delete(itemTable);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${itemTable.tableName}"`);
 });
 
 describe("dispatcher-live (integration) — full path against Kumiko server", () => {
@@ -123,7 +124,7 @@ describe("dispatcher-live (integration) — full path against Kumiko server", ()
     expect(result.isSuccess).toBe(true);
 
     // Prove the server actually persisted.
-    const rows = await stack.db.select().from(itemTable);
+    const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(1);
     expect(rows[0]?.["name"]).toBe("hello-live");
   });
@@ -158,7 +159,7 @@ describe("dispatcher-live (integration) — full path against Kumiko server", ()
 
   test("query: dispatches GET-style-POST (Kumiko uses POST for query too), returns data", async () => {
     // Seed a row first.
-    await stack.db.insert(itemTable).values({
+    await insertOne(stack.db, itemTable, {
       id: generateId(),
       tenantId: admin.tenantId,
       name: "seed",
@@ -188,7 +189,7 @@ describe("dispatcher-live (integration) — full path against Kumiko server", ()
 
     expect(result.isSuccess).toBe(true);
 
-    const rows = await stack.db.select().from(itemTable);
+    const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(3);
     const names = rows.map((r) => r["name"]).sort();
     expect(names).toEqual(["a", "b", "c"]);
@@ -210,7 +211,7 @@ describe("dispatcher-live (integration) — full path against Kumiko server", ()
     }
 
     // DB must be empty — prior success within a failed batch rolls back.
-    const rows = await stack.db.select().from(itemTable);
+    const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(0);
   });
 });

package/src/api/__tests__/metrics-endpoint.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import {
   createNoopProvider,

package/src/api/__tests__/{nested-write.integration.ts → nested-write.integration.test.ts}

@@ -1,8 +1,8 @@
-import { eq } from "drizzle-orm";
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { buildDrizzleTable } from "../../db/table-builder";
+import { asRawClient, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
@@ -14,7 +14,7 @@ const projectEntity = createEntity({
   table: "nested_projects",
   fields: { name: createTextField({ required: true }) },
 });
-const projectTable = buildDrizzleTable("project", projectEntity);
+const projectTable = buildEntityTable("project", projectEntity);
 
 const taskEntity = createEntity({
   table: "nested_tasks",
@@ -23,7 +23,7 @@ const taskEntity = createEntity({
     title: createTextField({ required: true }),
   },
 });
-const taskTable = buildDrizzleTable("task", taskEntity);
+const taskTable = buildEntityTable("task", taskEntity);
 
 const nestedFeature = defineFeature("nested", (r) => {
   r.entity("project", projectEntity);
@@ -78,8 +78,8 @@ afterAll(async () => {
 });
 
 beforeEach(async () => {
-  await stack.db.delete(taskTable);
-  await stack.db.delete(projectTable);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${taskTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${projectTable.tableName}"`);
 });
 
 describe("POST /api/write — nested-write (Welle M1)", () => {
@@ -111,11 +111,8 @@ describe("POST /api/write — nested-write (Welle M1)", () => {
     expect(parent.tasks[1].title).toBe("t2");
 
     // DB reflects both writes.
-    const dbProjects = await stack.db.select().from(projectTable);
-    const dbTasks = await stack.db
-      .select()
-      .from(taskTable)
-      .where(eq(taskTable["projectId"], parent.id));
+    const dbProjects = await selectMany(stack.db, projectTable);
+    const dbTasks = await selectMany(stack.db, taskTable, { projectId: parent.id });
     expect(dbProjects).toHaveLength(1);
     expect(dbTasks).toHaveLength(2);
   });
@@ -137,8 +134,8 @@ describe("POST /api/write — nested-write (Welle M1)", () => {
     expect(body.isSuccess).toBe(false);
 
     // DB empty — prior sub-task and parent both rolled back.
-    const dbProjects = await stack.db.select().from(projectTable);
-    const dbTasks = await stack.db.select().from(taskTable);
+    const dbProjects = await selectMany(stack.db, projectTable);
+    const dbTasks = await selectMany(stack.db, taskTable);
     expect(dbProjects).toHaveLength(0);
     expect(dbTasks).toHaveLength(0);
   });
@@ -182,7 +179,7 @@ describe("POST /api/write — nested-write (Welle M1)", () => {
 
     // Parent did not persist — the pre-flight check runs before the parent
     // write, so the TX never opened on a malformed nested key.
-    const dbProjects = await stack.db.select().from(projectTable);
+    const dbProjects = await selectMany(stack.db, projectTable);
     expect(dbProjects).toHaveLength(0);
   });
 
@@ -207,7 +204,7 @@ describe("POST /api/write — nested-write (Welle M1)", () => {
     expect(body.error.details.fields[0].path).toMatch(/tasks\.0\.projectId/);
 
     // DB empty.
-    const dbProjects = await stack.db.select().from(projectTable);
+    const dbProjects = await selectMany(stack.db, projectTable);
     expect(dbProjects).toHaveLength(0);
   });
 });

package/src/api/__tests__/readiness.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { createReadinessProbe, type ReadinessCheck } from "../readiness";
 
 function okCheck(name: string, delayMs = 0): ReadinessCheck {

package/src/api/__tests__/request-id-middleware.test.ts

@@ -1,5 +1,5 @@
+import { describe, expect, test } from "bun:test";
 import { Hono } from "hono";
-import { describe, expect, test } from "vitest";
 import { requestContext } from "../request-context";
 import { requestIdMiddleware } from "../request-id-middleware";
 

package/src/api/__tests__/sse-broker.test.ts

@@ -1,12 +1,12 @@
-import { describe, expect, test, vi } from "vitest";
+import { describe, expect, mock, test } from "bun:test";
 import { createSseBroker, type SseEvent } from "../sse-broker";
 
 describe("SSE broker", () => {
   test("adds client and tracks count", () => {
     const broker = createSseBroker();
-    broker.addClient("ch1", vi.fn(), vi.fn());
-    broker.addClient("ch1", vi.fn(), vi.fn());
-    broker.addClient("ch2", vi.fn(), vi.fn());
+    broker.addClient("ch1", mock(), mock());
+    broker.addClient("ch1", mock(), mock());
+    broker.addClient("ch2", mock(), mock());
 
     expect(broker.getClientCount("ch1")).toBe(2);
     expect(broker.getClientCount("ch2")).toBe(1);
@@ -15,13 +15,13 @@ describe("SSE broker", () => {
 
   test("pushToChannel sends to all clients on channel", () => {
     const broker = createSseBroker();
-    const send1 = vi.fn();
-    const send2 = vi.fn();
-    const sendOther = vi.fn();
+    const send1 = mock();
+    const send2 = mock();
+    const sendOther = mock();
 
-    broker.addClient("users", send1, vi.fn());
-    broker.addClient("users", send2, vi.fn());
-    broker.addClient("other", sendOther, vi.fn());
+    broker.addClient("users", send1, mock());
+    broker.addClient("users", send2, mock());
+    broker.addClient("other", sendOther, mock());
 
     const event: SseEvent = { type: "user.created", data: { id: 1 } };
     broker.pushToChannel("users", event);
@@ -33,9 +33,9 @@ describe("SSE broker", () => {
 
   test("removeClient stops delivery", () => {
     const broker = createSseBroker();
-    const send = vi.fn();
+    const send = mock();
 
-    const clientId = broker.addClient("ch", send, vi.fn());
+    const clientId = broker.addClient("ch", send, mock());
     broker.removeClient("ch", clientId);
 
     broker.pushToChannel("ch", { type: "test", data: {} });

package/src/api/__tests__/sse-route.test.ts

@@ -1,5 +1,5 @@
+import { describe, expect, test } from "bun:test";
 import { Hono } from "hono";
-import { describe, expect, test } from "vitest";
 import { TestUsers } from "../../stack";
 import { authMiddleware } from "../auth-middleware";
 import { createJwtHelper } from "../jwt";

package/src/api/readiness.ts

@@ -11,9 +11,9 @@
 //   - Checks run in parallel — the probe is called on every kubelet/ALB poll,
 //     so total latency must stay ≈ slowest check, not sum.
 
-import { sql } from "drizzle-orm";
 import type Redis from "ioredis";
 import type { DbConnection } from "../db/connection";
+import { pingDatabase } from "../db/queries/raw-sql";
 import { getAllConsumerProgress } from "../pipeline/event-dispatcher";
 
 export type ReadinessCheck = {
@@ -90,7 +90,7 @@ export function dbPingCheck(db: DbConnection): ReadinessCheck {
   return {
     name: "db",
     run: async () => {
-      await db.execute(sql`SELECT 1`);
+      await pingDatabase(db);
     },
   };
 }

package/src/auth/__tests__/roles.test.ts

@@ -1,6 +1,6 @@
 // Snapshot-Tests fuer ROLES — faengt stille Drift ab.
 
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { ROLES } from "../roles";
 
 describe("ROLES constants", () => {
@@ -18,7 +18,7 @@ describe("ROLES constants", () => {
 
   test("ROLES-Werte sind identisch zu den Keys (keine Drift im Mapping)", () => {
     for (const [key, value] of Object.entries(ROLES)) {
-      expect(value).toBe(key);
+      expect(value as string).toBe(key);
     }
   });
 });

package/src/bun-db/__tests__/PATTERN.md

@@ -0,0 +1,73 @@
+# Pattern: Provider-agnostische DB-Integration-Tests
+
+## Architektur
+
+```
+db/api.ts                    createConnection() — liest DB_PROVIDER env
+db/postgres-provider.ts      postgres-js Factory (default, stabil)
+db/bun-provider.ts           Bun.SQL Factory (DB_PROVIDER=bun, experimentell)
+stack/db.ts                  createTestDb() — provider-agnostisch via createConnection
+stack/test-stack.ts          setupTestStack() — provider-agnostisch via createTestDb
+bun-db/__tests__/bun-test-stack.ts  Alias: setupBunTestStack → setupTestStack
+bun-db/__tests__/bun-test-db.ts     Alias: createBunTestDb → createTestDb
+```
+
+## Snippet: Integration-Test
+
+```typescript
+import { setupTestStack, type TestStack } from "../stack";
+import { defineFeature } from "../engine";
+
+const feature = defineFeature("example", (r) => { /* ... */ });
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+test("works", async () => {
+  // stack.db    → provider-agnostic (asRawClient für .unsafe/.begin)
+  // stack.http  → RequestHelper (writeOk, queryOk, raw)
+  // stack.redis → TestRedis
+  // stack.events → EventCollector
+});
+```
+
+Nur DB (ohne HTTP/Stack):
+
+```typescript
+import { createTestDb, type TestDb } from "../stack";
+import { asRawClient } from "../bun-db/query";
+
+let td: TestDb;
+beforeAll(async () => { td = await createTestDb(); });
+afterAll(async () => { await td.cleanup(); });
+test("works", async () => {
+  await asRawClient(td.db).unsafe("SELECT 1");
+});
+```
+
+## Switching Driver
+
+```bash
+# Default: postgres-js
+bun test ./src/**/*.integration.ts
+
+# Bun.SQL (experimentell)
+DB_PROVIDER=bun bun test ./src/**/*.integration.ts
+```
+
+## Bekannte Issues
+
+- **Bun.SQL Extended-Query-Protocol Bug**: PostgresError "bind message has 11 result
+  formats but query has 1 columns" bei sequentiellen Queries mit unterschiedlicher
+  Spaltenzahl innerhalb derselben Transaction. Nur bei `DB_PROVIDER=bun`.
+- **Temporal-Polyfill**: `createTestDb()` ruft jetzt `ensureTemporalPolyfill()` auf.
+- **TenantDb.insertOne**: Immer `tdb.insertOne(table, ...)` verwenden (Methode),
+  NICHT `insertOne(tdb, table, ...)` (standalone aus bun-db/query — bypassed
+  tenant-injection via asRawClient).

package/src/bun-db/__tests__/_helpers.ts

@@ -0,0 +1,103 @@
+// Helpers für bun-db SQL-Layer-Integration-Tests.
+// Provider-agnostic via createConnection (DB_PROVIDER env).
+//
+// Pattern: pro Test eine eigene Tabelle mit unique-Name (random-Suffix),
+// damit concurrency=8 tests sich nicht in die Quere kommen. CREATE TABLE
+// im before, DROP TABLE im after (auch bei test-fail damit Test-DB clean
+// bleibt). KEINE TEMP TABLES — die wären connection-bound und pools
+// reused connections, was tests in zwei verschiedenen Pool-Slots
+// in verschiedene "TEMP-Welten" stecken würde.
+//
+// Schema-Tabellen bestehen aus einer id (uuid) + den getesteten Spalten.
+
+import { randomUUID } from "node:crypto";
+import { createConnection } from "../../db/api";
+import type { ColumnMeta, EntityTableMeta } from "../../db/entity-table-meta";
+
+const DATABASE_URL =
+  process.env["TEST_DATABASE_URL"] ??
+  process.env["DATABASE_URL"] ??
+  "postgresql://kumiko:kumiko@localhost:15432/kumiko_test";
+
+let dbInstance: { db: unknown; close: () => Promise<void> } | undefined;
+
+export async function getDb(): Promise<unknown> {
+  return ensureDb();
+}
+export async function ensureDb(): Promise<unknown> {
+  if (!dbInstance) {
+    dbInstance = await createConnection(DATABASE_URL, { maxConnections: 4 });
+  }
+  return dbInstance.db;
+}
+
+export async function closeDb(): Promise<void> {
+  if (dbInstance) {
+    await dbInstance.close();
+    dbInstance = undefined;
+  }
+}
+
+// Erzeugt einen pseudo-zufälligen Tabellen-Namen. snake-case, lower,
+// nur a-z0-9_, max 50 chars (Postgres-Identifier-Limit ist 63).
+export function uniqueTableName(prefix = "sqltest"): string {
+  const suffix = randomUUID().replace(/-/g, "").slice(0, 12);
+  return `${prefix}_${suffix}`;
+}
+
+// EntityTableMeta-Helper. id (uuid primary key) wird IMMER gesetzt; der
+// Caller liefert nur die zusätzlichen Test-Spalten.
+export function makeTableMeta(
+  tableName: string,
+  extraColumns: readonly ColumnMeta[],
+): EntityTableMeta {
+  return {
+    tableName,
+    source: "unmanaged",
+    indexes: [],
+    columns: [
+      {
+        name: "id",
+        pgType: "uuid",
+        notNull: true,
+        primaryKey: true,
+        defaultSql: "gen_random_uuid()",
+      },
+      ...extraColumns,
+    ],
+  };
+}
+
+// CREATE TABLE-Statement aus EntityTableMeta. Minimaler DDL-Renderer —
+// kein Index-Support, kein Komplex-Default. Genug für die Test-Matrix.
+export function renderCreateTable(meta: EntityTableMeta): string {
+  const cols = meta.columns
+    .map((c) => {
+      const parts = [`"${c.name}"`, c.pgType];
+      if (c.notNull) parts.push("NOT NULL");
+      if (c.defaultSql) parts.push(`DEFAULT ${c.defaultSql}`);
+      if (c.primaryKey) parts.push("PRIMARY KEY");
+      return parts.join(" ");
+    })
+    .join(", ");
+  return `CREATE TABLE "${meta.tableName}" (${cols})`;
+}
+
+// Test-Wrapper: Tabelle anlegen, fn aufrufen, Tabelle droppen.
+// fn bekommt {db, meta} — alle SQL-Operationen laufen direkt darauf.
+export async function withTable<T>(
+  columns: readonly ColumnMeta[],
+  fn: (ctx: { db: unknown; meta: EntityTableMeta }) => Promise<T>,
+  prefix?: string,
+): Promise<T> {
+  const db = await getDb();
+  const tableName = uniqueTableName(prefix);
+  const meta = makeTableMeta(tableName, columns);
+  const { asRawClient } = await import("../query");
+  await asRawClient(db).unsafe(renderCreateTable(meta));
+  try {
+    return await fn({ db, meta });
+  } finally {
+    await asRawClient(db).unsafe(`DROP TABLE IF EXISTS "${tableName}"`);
+  }
+}