@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

package/src/stack/db.ts

@@ -1,5 +1,10 @@
-import { drizzle } from "drizzle-orm/postgres-js";
-import postgres from "postgres";
+// Test-DB Factory: CREATE DATABASE → connect → createEventsTable.
+// Provider-agnostic via createConnection (DB_PROVIDER env).
+// postgres-js = default. DB_PROVIDER=bun = Bun.SQL (experimentell).
+
+import { createConnection } from "../db/api";
+import { createDatabase, databaseExists, dropDatabaseIfExists } from "../db/queries/test-stack";
+import { ensureTemporalPolyfill } from "../time/polyfill";
 import { generateId } from "../utils";
 
 function requireEnv(name: string): string {
@@ -13,88 +18,60 @@ function requireEnv(name: string): string {
 }
 
 export type TestDb = {
-  db: ReturnType<typeof drizzle>;
-  client: ReturnType<typeof postgres>;
+  db: unknown;
+  client: unknown;
   dbName: string;
   cleanup: () => Promise<void>;
 };
 
 export type CreateTestDbOptions = {
-  /** Override TEST_DATABASE_URL. Rare — mostly for tests that want a
-   *  non-default Postgres (e.g. a read-replica probe). */
   readonly baseUrl?: string;
-  /** Use a specific DB name instead of the default
-   *  `kumiko_test_<8chars>`. Combined with `persistent: true`, lets a
-   *  dev server keep state across restarts. Must be a legal Postgres
-   *  identifier — the caller is responsible for matching the usual
-   *  [a-z_0-9]+ shape. */
   readonly dbName?: string;
-  /** When true, cleanup() is a no-op and the DB survives. Also
-   *  changes CREATE DATABASE to IF-NOT-EXISTS semantics so restarts
-   *  reuse the same storage. Default false (test contract: fresh DB
-   *  per call, dropped on cleanup). */
   readonly persistent?: boolean;
 };
 
 /**
- * Accepts a baseUrl string (legacy shorthand used by most tests) OR an
- * options object. The string form is kept because thousands of tests
- * call `createTestDb()` with no args; only dev-server and niche tests
- * need the options form.
+ * Provider-agnostische Test-DB. createConnection liest DB_PROVIDER.
+ * Für Bun.SQL: DB_PROVIDER=bun setzen (experimentell — siehe db/bun-provider.ts).
  */
 export async function createTestDb(arg?: string | CreateTestDbOptions): Promise<TestDb> {
+  await ensureTemporalPolyfill();
   const opts: CreateTestDbOptions = typeof arg === "string" ? { baseUrl: arg } : (arg ?? {});
   const url = opts.baseUrl ?? requireEnv("TEST_DATABASE_URL");
-  // slice(-8) — the last 8 hex chars of a UUIDv7 are pure random (the
-  // front 48 bits are a timestamp, which would collide across workers
-  // that start within the same millisecond).
   const dbName = opts.dbName ?? `kumiko_test_${generateId().slice(-8)}`;
   const adminUrl = url.replace(/\/[^/]+$/, "/postgres");
 
-  const adminClient = postgres(adminUrl);
+  const admin = await createConnection(adminUrl, { maxConnections: 1 });
   try {
     if (opts.persistent) {
-      // Postgres has no CREATE DATABASE IF NOT EXISTS; emulate with a
-      // catalog probe so restarts are idempotent.
-      const existing = await adminClient<{ exists: boolean }[]>`
-        SELECT EXISTS (SELECT 1 FROM pg_database WHERE datname = ${dbName}) AS exists
-      `;
-      if (!existing[0]?.exists) {
-        await adminClient.unsafe(`CREATE DATABASE "${dbName}"`);
+      if (!(await databaseExists(admin.db, dbName))) {
+        await createDatabase(admin.db, dbName);
       }
     } else {
-      await adminClient.unsafe(`CREATE DATABASE "${dbName}"`);
+      await createDatabase(admin.db, dbName);
     }
   } finally {
-    await adminClient.end();
+    await admin.close();
   }
 
   const testUrl = url.replace(/\/[^/]+$/, `/${dbName}`);
-  const client = postgres(testUrl);
-  const db = drizzle(client);
+  const conn = await createConnection(testUrl);
 
-  // Every ES-entity writes events; auto-create the events table so tests that
-  // go straight to createTestDb (not setupTestStack) also work out of the box.
-  // In persistent mode this is idempotent: createEventsTable emits IF NOT
-  // EXISTS so a second boot is a no-op.
   const { createEventsTable } = await import("../event-store");
-  await createEventsTable(db);
+  await createEventsTable(conn.db);
 
   return {
-    db,
-    client,
+    db: conn.db,
+    client: conn.client,
     dbName,
     cleanup: async () => {
-      await client.end();
-      // Persistent mode: dev-server owns the DB lifecycle — don't drop
-      // on process exit. `yarn kumiko clean-test-dbs` is the escape
-      // hatch when you really want to start over.
+      await conn.close();
       if (!opts.persistent) {
-        const admin = postgres(adminUrl);
+        const admin2 = await createConnection(adminUrl, { maxConnections: 1 });
         try {
-          await admin.unsafe(`DROP DATABASE IF EXISTS "${dbName}"`);
+          await dropDatabaseIfExists(admin2.db, dbName);
         } finally {
-          await admin.end();
+          await admin2.close();
         }
       }
     },

package/src/stack/push-entity-projection-tables.ts

@@ -1,4 +1,3 @@
-import { getTableName } from "drizzle-orm";
 import { tableExists } from "../db/schema-inspection";
 import type { Registry } from "../engine/types";
 import { unsafePushTables } from "./table-helpers";
@@ -35,9 +34,8 @@ export async function pushEntityProjectionTables(
     if (!proj.isImplicit) continue;
     if (seen.has(proj.table)) continue;
     seen.add(proj.table);
-    // @cast-boundary drizzle-bridge — ProjectionTable + PgTable both round-trip
-    // through getTableName at runtime; the type system can't unify them.
-    const physical = getTableName(proj.table as Parameters<typeof getTableName>[0]);
+    const tableRec = proj.table as unknown as Record<symbol, unknown>;
+    const physical = tableRec[Symbol.for("kumiko:schema:Name")] as string;
     if (await tableExists(stack.db, `public.${physical}`)) {
       logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
       continue;

package/src/stack/table-helpers.ts

@@ -1,42 +1,46 @@
-import { generateDrizzleJson, generateMigration } from "drizzle-kit/api";
-import { getTableName, sql } from "drizzle-orm";
-import type { PgTable } from "drizzle-orm/pg-core";
-import type { drizzle } from "drizzle-orm/postgres-js";
+import type { DbConnection } from "../db/connection";
+import { pgTypeToSqlType } from "../db/dialect";
+import type { ColumnMeta, EntityTableMeta } from "../db/entity-table-meta";
+import {
+  alterTableAddColumn,
+  createIndexIfNotExists,
+  executeDdlStatement,
+  truncateTablesRestartIdentity,
+} from "../db/queries/test-stack";
+import { renderTableDdl } from "../db/render-ddl";
 import { tableExists } from "../db/schema-inspection";
-import { buildDrizzleTable, toTableName } from "../db/table-builder";
-import type { TestStack } from "./test-stack";
+import { buildEntityTable, toTableName } from "../db/table-builder";
+import type { EventDispatcher } from "../pipeline";
+
+const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
+function tableNameOf(table: unknown): string {
+  if (typeof table !== "object" || table === null) {
+    throw new Error("table-helpers: table is not a SchemaTable object");
+  }
+  const rec = table as Record<string | symbol, unknown>;
+  if (typeof rec[KUMIKO_NAME_SYMBOL] === "string") return rec[KUMIKO_NAME_SYMBOL] as string;
+  if (typeof (rec as { tableName?: unknown }).tableName === "string") {
+    return (rec as { tableName: string }).tableName;
+  }
+  throw new Error("table-helpers: table has no name");
+}
 
 /**
- * Bypass: creates a Drizzle table directly, without registering it as
- * a projection of the event-sourcing engine. Apps should declare data
- * via `r.entity(...)` and get tables, migrations, snapshots and audit
- * for free — this helper is reserved for framework-internal meta-tables
- * (event-store, snapshots, projection-state) and test setup.
- *
- * Strict: raises a postgres `relation already exists` (42P07) error if
- * the table is already there. Use `unsafeEnsureEntityTable` for the
- * idempotent boot-path variant.
+ * Bypass: creates an entity-table directly without going through the
+ * full registry. Reserved for framework-internal meta-tables and
+ * test setup — apps declare data via `r.entity(...)`.
  */
 export async function unsafeCreateEntityTable(
-  db: ReturnType<typeof drizzle>,
+  db: DbConnection,
   entity: import("../engine/types").EntityDefinition,
   entityName?: string,
 ): Promise<void> {
-  const table = buildDrizzleTable(entityName ?? "entity", entity);
+  const table = buildEntityTable(entityName ?? "entity", entity);
   await unsafePushTables(db, { [entityName ?? "entity"]: table });
 }
 
-/**
- * Bypass (idempotent): same caveat as `unsafeCreateEntityTable` —
- * apps declare data via `r.entity(...)`. Checks whether the entity's
- * table already exists and skips creation if so. Schema-drift is *not*
- * detected: if the table is there but has the wrong columns, that's
- * the caller's problem (the dev-server contract is "drop the DB by
- * hand when you change the schema"). Tests should use
- * `unsafeCreateEntityTable` instead, since they rely on fresh DBs.
- */
 export async function unsafeEnsureEntityTable(
-  db: ReturnType<typeof drizzle>,
+  db: DbConnection,
   entity: import("../engine/types").EntityDefinition,
   entityName?: string,
 ): Promise<boolean> {
@@ -46,54 +50,88 @@ export async function unsafeEnsureEntityTable(
   return true;
 }
 
+// Tables produced by the native dialect already carry EntityTableMeta-shape
+// (source/columns/indexes). renderTableDdl converts that to CREATE TABLE +
+// CREATE INDEX statements executed via db/queries/test-stack.
+function tableToMeta(table: unknown): EntityTableMeta {
+  if (
+    typeof table === "object" &&
+    table !== null &&
+    "tableName" in table &&
+    "columns" in table &&
+    "indexes" in table &&
+    "source" in table
+  ) {
+    return table as EntityTableMeta;
+  }
+  throw new Error("unsafePushTables: argument is not a SchemaTable / EntityTableMeta");
+}
+
 /**
- * Bypass: pushes Drizzle table definitions to the database directly.
- * Uses drizzle-kit's generateDrizzleJson + generateMigration to produce SQL,
- * then executes it. Same SQL that `drizzle-kit push` would generate.
- * Reserved for framework-internal meta-tables (event-store, projections,
- * consumer-state) and test setup — apps declare data via `r.entity(...)`.
+ * Bypass: pushes table definitions to the database directly. Produces
+ * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl
+ * and executes them via db/queries/test-stack. Idempotent re-runs are safe.
  *
- * @param prevTables - Previous table definitions (for ALTER TABLE scenarios).
- *                     If omitted, assumes empty DB (CREATE TABLE).
+ * Reserved for framework-internal meta-tables + test setup. App-defined
+ * entities go through `kumiko schema apply` (committed SQL files).
  */
 export async function unsafePushTables(
-  db: ReturnType<typeof drizzle>,
+  db: DbConnection,
   tables: Record<string, unknown>,
   prevTables?: Record<string, unknown>,
 ): Promise<void> {
-  const prevJson = generateDrizzleJson(prevTables ?? {});
-  const targetJson = generateDrizzleJson(tables);
-  const statements = await generateMigration(prevJson, targetJson);
-  for (const stmt of statements) {
-    await db.execute(sql.raw(stmt));
+  const prevMetas = new Map<string, EntityTableMeta>();
+  if (prevTables) {
+    for (const [key, table] of Object.entries(prevTables)) {
+      const meta = tableToMeta(table);
+      prevMetas.set(key, meta);
+    }
+  }
+
+  for (const [key, table] of Object.entries(tables)) {
+    const meta = tableToMeta(table);
+    const prev = prevMetas.get(key);
+
+    if (prev) {
+      const prevCols = new Set(prev.columns.map((c) => c.name));
+      for (const col of meta.columns) {
+        if (!prevCols.has(col.name)) {
+          const type = renderColumnType(col);
+          const notNull = col.notNull && !col.primaryKey ? " NOT NULL" : "";
+          const defaultClause = col.defaultSql !== undefined ? ` DEFAULT ${col.defaultSql}` : "";
+          await alterTableAddColumn(db, meta.tableName, col.name, type, defaultClause, notNull);
+        }
+      }
+      const prevIdxNames = new Set(prev.indexes.map((i) => i.name));
+      for (const idx of meta.indexes) {
+        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);
+        }
+      }
+    } else {
+      const statements = renderTableDdl(meta);
+      for (const stmt of statements) {
+        await executeDdlStatement(db, stmt);
+      }
+    }
   }
 }
 
+function renderColumnType(col: ColumnMeta): string {
+  return pgTypeToSqlType(col.pgType);
+}
+
 /**
  * Wipes event store + framework-state + the given feature read-models in
  * one TRUNCATE, then re-registers the event-consumer state rows. Used in
  * test beforeEach-hooks to return the stack to a clean slate without
  * rebuilding it.
- *
- * Fixed list of framework tables (kumiko_events, kumiko_event_consumers,
- * kumiko_archived_streams, kumiko_snapshots, kumiko_projections) is always
- * included — any event-sourced test setup needs those cleared. The
- * `extraTables` arg covers the feature's own read-model tables that would
- * otherwise accumulate rows across tests.
- *
- * Accepts either a Drizzle PgTable (for locally-defined tables: getTableName
- * extracts the SQL name) or a plain string (for SQL names whose Drizzle
- * reference lives in another module and importing it for the TRUNCATE
- * alone would be overkill). Both round-trip to the same TRUNCATE list.
- *
- * Pre-existing code duplicates this block 30+ times, each with its own
- * list of extras. The helper collapses that to a one-liner per test and
- * lets a future change to the framework-table set (e.g. adding a new
- * consumer-state table) ripple through without touching every suite.
  */
 export async function resetEventStore(
-  stack: TestStack,
-  extraTables: readonly (PgTable | string)[] = [],
+  stack: { db: unknown; eventDispatcher?: EventDispatcher },
+  extraTables: readonly (unknown | string)[] = [],
 ): Promise<void> {
   const frameworkTables = [
     "kumiko_events",
@@ -102,9 +140,8 @@ export async function resetEventStore(
     "kumiko_snapshots",
     "kumiko_projections",
   ];
-  const extraNames = extraTables.map((t) => (typeof t === "string" ? t : getTableName(t)));
-  const allTables = [...frameworkTables, ...extraNames];
-  await stack.db.execute(sql.raw(`TRUNCATE ${allTables.join(", ")} RESTART IDENTITY CASCADE`));
+  const extraNames = extraTables.map((t) => (typeof t === "string" ? t : tableNameOf(t)));
+  await truncateTablesRestartIdentity(stack.db, [...frameworkTables, ...extraNames]);
   if (stack.eventDispatcher) {
     await stack.eventDispatcher.ensureRegistered();
   }

package/src/stack/test-stack.ts

@@ -3,7 +3,8 @@ import type { AuthRoutesConfig } from "../api/auth-routes";
 import type { JwtHelper } from "../api/jwt";
 import { buildServer } from "../api/server";
 import { createSseBroker } from "../api/sse-broker";
-import type { DbConnection } from "../db/connection";
+import type { PgClient } from "../db/connection";
+import { extractTableInfo } from "../db/query";
 import { createRegistry } from "../engine/registry";
 import type { FeatureDefinition, Registry, TenantId } from "../engine/types";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store";
@@ -23,9 +24,8 @@ export type TestStack = {
   app: Hono;
   jwt: JwtHelper;
   registry: Registry;
-  /** Drizzle connection — the test DB's lifecycle (name, raw pg client,
-   *  drop) lives inside setupTestStack and is released via stack.cleanup(). */
-  db: DbConnection;
+  // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
+  db: any;
   redis: TestRedis;
   search: SearchAdapter;
   events: EventCollector;
@@ -58,7 +58,8 @@ export type TestStackOptions = {
     | Record<string, unknown>
     | ((deps: {
         registry: Registry;
-        db: import("../db/connection").DbConnection;
+        // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
+        db: any;
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => Record<string, unknown>);
@@ -110,7 +111,8 @@ export type TestStackOptions = {
     | import("../api/server").ServerOptions["anonymousAccess"]
     | ((deps: {
         registry: Registry;
-        db: import("../db/connection").DbConnection;
+        // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection
+        db: any;
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => import("../api/server").ServerOptions["anonymousAccess"]);
@@ -206,10 +208,9 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // exist; drizzle-kit's diff machinery would otherwise emit CREATE for
     // them again.
     const { tableExists } = await import("../db/schema-inspection");
-    const { getTableName } = await import("drizzle-orm");
     const missing: Record<string, unknown> = {};
     for (const [key, tbl] of Object.entries(projectionTables)) {
-      const physical = getTableName(tbl as Parameters<typeof getTableName>[0]); // @cast-boundary drizzle-bridge
+      const physical = extractTableInfo(tbl).name;
       if (await tableExists(testDb.db, `public.${physical}`)) continue;
       missing[key] = tbl;
     }
@@ -294,7 +295,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // post-commit latency (Sprint E.4).
     eventDispatcher: {
       pollIntervalMs: 50,
-      pgClient: testDb.client,
+      pgClient: testDb.client as PgClient | undefined,
       systemConsumers: {
         sse: enabledHooks.includes("sse"),
         search: enabledHooks.includes("search"),

package/src/testing/__tests__/db-cleanup.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { clearTables } from "../db-cleanup";
+
+describe("db-cleanup", () => {
+  test("clearTables issues DELETE without WHERE per table via deleteMany", async () => {
+    const sqlLog: string[] = [];
+    const mockDb = {
+      unsafe: async (sql: string) => {
+        sqlLog.push(sql);
+        return [];
+      },
+    };
+
+    await clearTables(mockDb, ["read_users", "kumiko_events"]);
+
+    expect(sqlLog).toHaveLength(2);
+    expect(sqlLog[0]).toBe('DELETE FROM "read_users"');
+    expect(sqlLog[1]).toBe('DELETE FROM "kumiko_events"');
+  });
+
+  test("clearTables accepts EntityTableMeta-shaped tables", async () => {
+    const sqlLog: string[] = [];
+    const mockDb = {
+      unsafe: async (sql: string) => {
+        sqlLog.push(sql);
+        return [];
+      },
+    };
+
+    const userTable = {
+      source: "managed" as const,
+      tableName: "read_users",
+      columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true }],
+      indexes: [],
+    };
+
+    await clearTables(mockDb, [userTable]);
+    expect(sqlLog[0]).toBe('DELETE FROM "read_users"');
+  });
+});

package/src/testing/__tests__/e2e-generator.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import {
   createBooleanField,

package/src/testing/__tests__/{ensure-entity-table.integration.ts → ensure-entity-table.integration.test.ts}

@@ -1,5 +1,5 @@
-import { sql } from "drizzle-orm";
-import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../db/query";
 import type { EntityDefinition } from "../../engine/types";
 import {
   createTestDb,
@@ -34,8 +34,8 @@ describe("unsafeEnsureEntityTable", () => {
   test("legt die Tabelle beim ersten Aufruf an (returnt true)", async () => {
     const created = await unsafeEnsureEntityTable(db.db, tenantEntity, "probe");
     expect(created).toBe(true);
-    const rows = await db.db.execute<{ exists: boolean }>(
-      sql`SELECT to_regclass('public.ensure_entity_table_probe') IS NOT NULL AS exists`,
+    const rows = await asRawClient(db.db).unsafe<{ exists: boolean }>(
+      `SELECT to_regclass('public.ensure_entity_table_probe') IS NOT NULL AS exists`,
     );
     expect(rows[0]?.exists).toBe(true);
   });
@@ -45,15 +45,8 @@ describe("unsafeEnsureEntityTable", () => {
     expect(created).toBe(false);
   });
 
-  test("unsafeCreateEntityTable bleibt strict — wirft bei existierender Tabelle", async () => {
-    // Gleiche Entity zweimal via unsafeCreateEntityTable → postgres 42P07
-    // (relation already exists). Drizzle wrappt den PG-Error in
-    // DrizzleQueryError; der echte Code steckt in .cause. Sicherstellt,
-    // dass unsafeEnsureEntityTable nicht versehentlich das strict-Verhalten
-    // verändert.
-    await expect(unsafeCreateEntityTable(db.db, tenantEntity, "probe")).rejects.toSatisfy((err) => {
-      const cause = (err as { cause?: { code?: string } }).cause;
-      return cause?.code === "42P07";
-    });
+  test("unsafeCreateEntityTable ist idempotent — zweiter Push wirft nicht (CREATE IF NOT EXISTS)", async () => {
+    // CREATE TABLE IF NOT EXISTS — idempotent by design.
+    await expect(unsafeCreateEntityTable(db.db, tenantEntity, "probe")).resolves.toBeUndefined();
   });
 });

package/src/testing/db-cleanup.ts

@@ -0,0 +1,44 @@
+/**
+ * Integration-test DB cleanup — replaces copy-pasted `DELETE FROM …` in
+ * beforeEach hooks. All table clears go through typed `deleteMany` (empty
+ * where = full table wipe). Raw SQL stays out of test files.
+ */
+import { type AnyDb, deleteMany } from "../db/query";
+
+const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
+const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
+
+/** EntityTableMeta, drizzle pgTable, or plain table name string. */
+export type ClearableTable = string | { readonly tableName?: string } | unknown;
+
+function tableFromName(name: string): unknown {
+  return {
+    [KUMIKO_NAME_SYMBOL]: name,
+    [KUMIKO_COLUMNS_SYMBOL]: {},
+  };
+}
+
+function resolveClearableTable(table: ClearableTable): unknown {
+  if (typeof table === "string") return tableFromName(table);
+  if (
+    typeof table === "object" &&
+    table !== null &&
+    "tableName" in table &&
+    typeof (table as { tableName?: unknown }).tableName === "string"
+  ) {
+    return table;
+  }
+  return table;
+}
+
+/** Delete all rows from each table (order preserved — FK-sensitive callers order explicitly). */
+export async function clearTables(db: AnyDb, tables: readonly ClearableTable[]): Promise<void> {
+  for (const table of tables) {
+    await deleteMany(db, resolveClearableTable(table), {});
+  }
+}
+
+/** Alias — same as clearTables, reads better in beforeEach. */
+export async function resetTestTables(db: AnyDb, tables: readonly ClearableTable[]): Promise<void> {
+  await clearTables(db, tables);
+}

package/src/testing/expect-error.ts

@@ -1,4 +1,4 @@
-import { expect } from "vitest";
+import { expect } from "bun:test";
 import type { WriteErrorInfo } from "../errors";
 
 // Vitest's toContain doesn't operate on plain objects, so after the move from

package/src/testing/index.ts

@@ -5,6 +5,7 @@
 
 export { rolesOf } from "./access-assertions";
 export { expectError, expectSuccess } from "./assertions";
+export { type ClearableTable, clearTables, resetTestTables } from "./db-cleanup";
 export {
   type E2EGeneratorOptions,
   type E2ETestSpec,
@@ -21,6 +22,7 @@ export {
   type ParsedSetCookie,
 } from "./http-cookies";
 export { createLateBoundHolder, type LateBoundHolder } from "./late-bound";
+export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper";
 export {
   createMutableMasterKeyProvider,
   type MutableMasterKeyProvider,

package/src/testing/multipart-helper.ts

@@ -0,0 +1,94 @@
+// Workarounds for Bun v1.3.x bun:test limitations with multipart/form-data.
+//
+// Two bugs combine to break file upload tests in bun:test:
+//
+// 1. Content-Type omission: both app.request({body: formData}) and
+//    fetch(url, {body: formData}) stringify FormData via .toString() instead
+//    of serializing it as multipart, so no Content-Type header is set.
+//    Fix: serialize FormData manually via buildMultipartBody().
+//
+// 2. Cross-realm instanceof: Hono's multipart parser creates Blob objects from
+//    a different JS realm than the test globals. In bun:test this means
+//    `parsedValue instanceof File` is always false even when the value has all
+//    File properties. Fix: patchFilInstanceofForBunTest().
+//
+// Both fixes are test-only — production code and real HTTP clients are unaffected.
+
+/**
+ * Serializes a FormData instance to multipart/form-data bytes.
+ *
+ * Returns the encoded body and the Content-Type header value (including the
+ * generated boundary). Pass both directly to app.request or fetch.
+ */
+export async function buildMultipartBody(
+  fd: FormData,
+): Promise<{ body: BodyInit; contentType: string }> {
+  const boundary = `KumikoBnd${Date.now()}${Math.random().toString(36).slice(2, 8)}`;
+  const enc = new TextEncoder();
+  const parts: Uint8Array[] = [];
+
+  for (const [name, value] of fd.entries()) {
+    const v = value as unknown as {
+      name?: string;
+      type?: string;
+      arrayBuffer?: () => Promise<ArrayBuffer>;
+    };
+    if (typeof v === "object" && v !== null && typeof v.arrayBuffer === "function") {
+      parts.push(
+        enc.encode(
+          `--${boundary}\r\nContent-Disposition: form-data; name="${name}"; filename="${v.name ?? "blob"}"\r\nContent-Type: ${v.type || "application/octet-stream"}\r\n\r\n`,
+        ),
+      );
+      parts.push(new Uint8Array(await v.arrayBuffer()));
+      parts.push(enc.encode("\r\n"));
+    } else {
+      parts.push(
+        enc.encode(
+          `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${String(value)}\r\n`,
+        ),
+      );
+    }
+  }
+  parts.push(enc.encode(`--${boundary}--\r\n`));
+
+  const total = parts.reduce((s, p) => s + p.length, 0);
+  const buf = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    buf.set(p, off);
+    off += p.length;
+  }
+  return {
+    body: buf as unknown as BodyInit,
+    contentType: `multipart/form-data; boundary=${boundary}`,
+  };
+}
+
+/**
+ * Patches File[Symbol.hasInstance] so that cross-realm Blob objects returned
+ * by Hono's parseBody() pass `instanceof File` checks in bun:test.
+ *
+ * In bun:test the multipart parser runs in a different JS realm than the test
+ * globals, so the Blob/File constructors differ. The patch replaces the
+ * prototype-chain check with a duck-type check: an object with string `.name`,
+ * number `.size`, and function `.arrayBuffer` is treated as a File.
+ *
+ * Safe to call multiple times (idempotent via the `_patched` marker).
+ */
+export function patchFileInstanceofForBunTest(): void {
+  // skip: idempotent re-patch — already installed, nothing to do
+  if ((File as unknown as { _kumikoPatched?: boolean })._kumikoPatched) return;
+  Object.defineProperty(File, Symbol.hasInstance, {
+    value(instance: unknown): boolean {
+      if (typeof instance !== "object" || instance === null) return false;
+      const f = instance as Record<string, unknown>;
+      return (
+        typeof f["name"] === "string" &&
+        typeof f["size"] === "number" &&
+        typeof f["arrayBuffer"] === "function"
+      );
+    },
+    configurable: true,
+  });
+  (File as unknown as { _kumikoPatched?: boolean })._kumikoPatched = true;
+}