@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

package/src/engine/__tests__/steps-unsafe-projection-delete.test.ts

@@ -1,21 +1,23 @@
-import type { SQL } from "drizzle-orm";
-import { pgTable, text, uuid } from "drizzle-orm/pg-core";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import { table, text, uuid } from "../../db/dialect";
 import { getStep } from "../define-step";
 import { buildUnsafeProjectionDeleteStep } from "../steps/unsafe-projection-delete";
 import type { PipelineCtx } from "../types/step";
 
-const testTable = pgTable("test_projection", {
+const testTable = table("test_projection", {
   id: uuid("id").primaryKey().defaultRandom(),
   tenantId: uuid("tenant_id").notNull(),
   label: text("label"),
 });
 
-const mockDb = { delete: vi.fn() };
-const mockDeleteBuilder = { where: vi.fn() };
+// bun-db path: step calls deleteMany(ctx.db.raw, table, where) which lands on
+// asRawClient(ctx.db.raw).unsafe(sqlText, params).
+const unsafeMock = mock(async (_sqlText: string, _params: unknown[]): Promise<unknown[]> => []);
+const rawDb = { unsafe: unsafeMock, begin: mock() };
+const ctxDb = { raw: rawDb };
 
 const mockCtx = {
-  db: mockDb,
+  db: ctxDb,
   event: { type: "test", payload: {} },
   steps: {},
   scope: {},
@@ -25,16 +27,16 @@ describe("buildUnsafeProjectionDeleteStep", () => {
   it("returns a StepInstance with kind unsafeProjectionDelete", () => {
     const step = buildUnsafeProjectionDeleteStep({
       table: testTable,
-      where: () => undefined as unknown as SQL,
+      where: () => ({}),
     });
     expect(step.kind).toBe("unsafeProjectionDelete");
     expect(step.args).toMatchObject({ table: testTable });
   });
 
-  it("accepts a static SQL where clause", () => {
+  it("accepts a static where clause", () => {
     const step = buildUnsafeProjectionDeleteStep({
       table: testTable,
-      where: undefined as unknown as SQL,
+      where: { id: "x" },
     });
     expect(step.args).toHaveProperty("table");
   });
@@ -42,28 +44,31 @@ describe("buildUnsafeProjectionDeleteStep", () => {
 
 describe("unsafeProjectionDelete run", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
-    mockDb.delete.mockReturnValue(mockDeleteBuilder);
+    mock.clearAllMocks();
   });
 
-  it("calls db.delete().where() with the resolved where clause", async () => {
+  it("issues DELETE ... WHERE ... with the resolved where clause", async () => {
     const stepDef = getStep("unsafeProjectionDelete");
     expect(stepDef).toBeDefined();
 
-    const whereClause = "fake sql" as unknown as SQL;
-    await stepDef!.run({ table: testTable, where: whereClause }, mockCtx);
+    await stepDef!.run({ table: testTable, where: { id: "abc" } }, mockCtx);
 
-    expect(mockDb.delete).toHaveBeenCalledOnce();
-    expect(mockDeleteBuilder.where).toHaveBeenCalledWith(whereClause);
+    expect(unsafeMock).toHaveBeenCalledTimes(1);
+    const [sqlText, params] = unsafeMock.mock.calls[0]!;
+    expect(sqlText).toMatch(/DELETE FROM "test_projection"/);
+    expect(sqlText).toMatch(/"id" = \$1/);
+    expect(params).toEqual(["abc"]);
   });
 
   it("resolves a function where-clause before calling delete", async () => {
     const stepDef = getStep("unsafeProjectionDelete");
 
-    const whereFn = vi.fn(() => "dynamic where" as unknown as SQL);
+    const whereFn = mock(() => ({ tenantId: "t1" }));
     await stepDef!.run({ table: testTable, where: whereFn }, mockCtx);
 
     expect(whereFn).toHaveBeenCalledWith(mockCtx);
-    expect(mockDeleteBuilder.where).toHaveBeenCalledWith("dynamic where");
+    expect(unsafeMock).toHaveBeenCalledTimes(1);
+    const [, params] = unsafeMock.mock.calls[0]!;
+    expect(params).toEqual(["t1"]);
   });
 });

package/src/engine/__tests__/steps-unsafe-projection-upsert.test.ts

@@ -1,22 +1,26 @@
-import { pgTable, text, uuid } from "drizzle-orm/pg-core";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import { table, text, uuid } from "../../db/dialect";
 import { getStep } from "../define-step";
 import { buildUnsafeProjectionUpsertStep } from "../steps/unsafe-projection-upsert";
 import type { PipelineCtx } from "../types/step";
 
-const testTable = pgTable("test_projection", {
+const testTable = table("test_projection", {
   id: uuid("id").primaryKey().defaultRandom(),
   tenantId: uuid("tenant_id").notNull(),
   externalId: text("external_id").notNull().unique(),
   label: text("label"),
 });
 
-const mockConflictBuilder = { onConflictDoUpdate: vi.fn() };
-const mockValuesBuilder = { values: vi.fn(() => mockConflictBuilder) };
-const mockDb = { insert: vi.fn(() => mockValuesBuilder) };
+// New bun-db path: step uses asRawClient(ctx.db.raw).unsafe(sqlText, params).
+// Capture the raw SQL string + params per call instead of the old
+// insert/values/onConflictDoUpdate chain.
+const unsafeMock = mock(async (_sqlText: string, _params: unknown[]) => []);
+const beginMock = mock(async (fn: (tx: unknown) => Promise<unknown>) => fn({}));
+const rawDb = { unsafe: unsafeMock, begin: beginMock };
+const ctxDb = { raw: rawDb };
 
 const mockCtx = {
-  db: mockDb,
+  db: ctxDb,
   event: { type: "test", payload: {} },
   steps: {},
   scope: {},
@@ -46,7 +50,7 @@ describe("buildUnsafeProjectionUpsertStep", () => {
   });
 
   it("accepts a function row resolver", () => {
-    const resolver = vi.fn(() => ({ tenantId: "t1", externalId: "e1" }));
+    const resolver = mock(() => ({ tenantId: "t1", externalId: "e1" }));
     const step = buildUnsafeProjectionUpsertStep({
       table: testTable,
       on: ["externalId"],
@@ -67,7 +71,7 @@ describe("buildUnsafeProjectionUpsertStep", () => {
 
 describe("unsafeProjectionUpsert run", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    mock.clearAllMocks();
   });
 
   it("throws when a conflict-key column does not exist on the table", async () => {
@@ -92,14 +96,19 @@ describe("unsafeProjectionUpsert run", () => {
 
     await stepDef!.run({ table: testTable, on: ["externalId"], row }, mockCtx);
 
-    expect(mockDb.insert).toHaveBeenCalledOnce();
-    expect(mockConflictBuilder.onConflictDoUpdate).toHaveBeenCalledOnce();
-
-    const conflictArgs = mockConflictBuilder.onConflictDoUpdate.mock.calls[0]![0]!;
-    expect(conflictArgs.set).toEqual({ tenantId: "t1", label: "hello" });
+    expect(unsafeMock).toHaveBeenCalledTimes(1);
+    const [sqlText, params] = unsafeMock.mock.calls[0]!;
+    expect(sqlText).toMatch(/INSERT INTO "test_projection"/);
+    expect(sqlText).toMatch(/ON CONFLICT \("external_id"\) DO UPDATE SET/);
+    // SET clause excludes the conflict-key column ("external_id") but
+    // includes the other columns (tenant_id, label).
+    expect(sqlText).toMatch(/"tenant_id" = \$/);
+    expect(sqlText).toMatch(/"label" = \$/);
+    expect(sqlText).not.toMatch(/"external_id" = \$\d+,/);
+    expect(params).toEqual(["t1", "e1", "hello", "t1", "hello"]);
   });
 
-  it("calls insert().onConflictDoUpdate with the resolved row and conflict targets", async () => {
+  it("calls INSERT ... ON CONFLICT DO UPDATE with the resolved row + conflict targets", async () => {
     const stepDef = getStep("unsafeProjectionUpsert");
 
     await stepDef!.run(
@@ -111,7 +120,9 @@ describe("unsafeProjectionUpsert run", () => {
       mockCtx,
     );
 
-    expect(mockDb.insert).toHaveBeenCalled();
-    expect(mockConflictBuilder.onConflictDoUpdate).toHaveBeenCalled();
+    expect(unsafeMock).toHaveBeenCalled();
+    const [sqlText] = unsafeMock.mock.calls[0]!;
+    expect(sqlText).toMatch(/INSERT INTO "test_projection"/);
+    expect(sqlText).toMatch(/ON CONFLICT \("external_id"\) DO UPDATE/);
   });
 });

package/src/engine/__tests__/steps-webhook-send.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, mock } from "bun:test";
 import { getStep } from "../define-step";
 import {
   STEP_DISPATCH_AGGREGATE_TYPE,
@@ -7,7 +7,7 @@ import {
 import { buildWebhookSendStep } from "../steps/webhook-send";
 import type { PipelineCtx } from "../types/step";
 
-const mockUnsafeAppendEvent = vi.fn();
+const mockUnsafeAppendEvent = mock();
 
 const mockCtx = {
   unsafeAppendEvent: mockUnsafeAppendEvent,
@@ -50,7 +50,7 @@ describe("buildWebhookSendStep", () => {
 
 describe("webhook.send run", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    mock.clearAllMocks();
   });
 
   it("appends a step.dispatch-requested system event with the webhook spec", async () => {
@@ -67,7 +67,7 @@ describe("webhook.send run", () => {
       mockCtx,
     );
 
-    expect(mockUnsafeAppendEvent).toHaveBeenCalledOnce();
+    expect(mockUnsafeAppendEvent).toHaveBeenCalledTimes(1);
     const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
 
     expect(eventArg.aggregateType).toBe(STEP_DISPATCH_AGGREGATE_TYPE);
@@ -79,8 +79,8 @@ describe("webhook.send run", () => {
 
   it("resolves function-based url and body resolvers", async () => {
     const stepDef = getStep("webhook.send");
-    const urlFn = vi.fn(() => "https://hooks.example/dynamic");
-    const bodyFn = vi.fn(() => ({ key: "value" }));
+    const urlFn = mock(() => "https://hooks.example/dynamic");
+    const bodyFn = mock(() => ({ key: "value" }));
 
     await stepDef!.run(
       {

package/src/engine/__tests__/steps-workflow.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, mock } from "bun:test";
 import { getStep } from "../define-step";
 import {
   SUSPEND_SENTINEL,
@@ -11,7 +11,7 @@ import { buildWaitStep } from "../steps/wait";
 import { buildWaitForEventStep } from "../steps/wait-for-event";
 import type { PipelineCtx } from "../types/step";
 
-const mockUnsafeAppendEvent = vi.fn();
+const mockUnsafeAppendEvent = mock();
 
 const workflowCtx = {
   unsafeAppendEvent: mockUnsafeAppendEvent,
@@ -46,7 +46,7 @@ describe("buildWaitStep", () => {
 
 describe("workflow.wait run", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    mock.clearAllMocks();
   });
 
   it("throws when used outside defineWorkflow (no ctx.workflow)", async () => {
@@ -64,7 +64,7 @@ describe("workflow.wait run", () => {
     const result = await stepDef!.run({ for: "PT1H" }, workflowCtx);
 
     expect(result).toBe(SUSPEND_SENTINEL);
-    expect(mockUnsafeAppendEvent).toHaveBeenCalledOnce();
+    expect(mockUnsafeAppendEvent).toHaveBeenCalledTimes(1);
     const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
     expect(eventArg.aggregateType).toBe(WORKFLOW_AGGREGATE_TYPE);
     expect(eventArg.type).toBe(WORKFLOW_WAITING_TYPE);
@@ -108,7 +108,7 @@ describe("buildWaitForEventStep", () => {
 
 describe("workflow.waitForEvent run", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    mock.clearAllMocks();
   });
 
   it("throws when used outside defineWorkflow", async () => {
@@ -129,7 +129,7 @@ describe("workflow.waitForEvent run", () => {
     );
 
     expect(result).toBe(SUSPEND_SENTINEL);
-    expect(mockUnsafeAppendEvent).toHaveBeenCalledOnce();
+    expect(mockUnsafeAppendEvent).toHaveBeenCalledTimes(1);
     const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
     expect(eventArg.aggregateType).toBe(WORKFLOW_AGGREGATE_TYPE);
     expect(eventArg.type).toBe(WORKFLOW_WAITING_FOR_EVENT_TYPE);
@@ -162,7 +162,7 @@ describe("buildRetryStep", () => {
 
 describe("workflow.retry run", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    mock.clearAllMocks();
   });
 
   it("throws when used outside defineWorkflow", async () => {

package/src/engine/__tests__/system-user.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { hasAccess } from "../access";
 import { createApp } from "../create-app";
 import { defineFeature } from "../define-feature";

package/src/engine/__tests__/unmanaged-table.test.ts

@@ -0,0 +1,98 @@
+// Unit tests for r.unmanagedTable() — the EntityTableMeta cousin of
+// r.rawTable. Same audit-trail contract, different storage shape (post-
+// drizzle migrate-runner). See define-feature.ts / DX-4.
+
+import { describe, expect, test } from "bun:test";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+
+const probeMeta = defineUnmanagedTable({
+  tableName: "ut_probe",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+});
+const probeMetaTwo = defineUnmanagedTable({
+  tableName: "ut_probe_two",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+});
+
+describe("r.unmanagedTable — declaration", () => {
+  test("rejects duplicate registrations within one feature", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "test" });
+        r.unmanagedTable(probeMeta, { reason: "test" });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects empty reason", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "" });
+      }),
+    ).toThrow(/options\.reason must be a non-empty string/);
+  });
+
+  test("rejects whitespace-only reason", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "   " });
+      }),
+    ).toThrow(/options\.reason must be a non-empty string/);
+  });
+
+  test("accepts valid registration and stores meta + reason", () => {
+    const feature = defineFeature("probe", (r) => {
+      r.unmanagedTable(probeMeta, {
+        reason: "read-side projection of an event-stream",
+      });
+    });
+    expect(feature.unmanagedTables).toHaveProperty("ut_probe");
+    expect(feature.unmanagedTables["ut_probe"]?.reason).toBe(
+      "read-side projection of an event-stream",
+    );
+    expect(feature.unmanagedTables["ut_probe"]?.meta).toBe(probeMeta);
+  });
+
+  test("two unmanaged tables on one feature register under their tableName", () => {
+    const feature = defineFeature("dual", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "one" });
+      r.unmanagedTable(probeMetaTwo, { reason: "two" });
+    });
+    expect(Object.keys(feature.unmanagedTables).sort()).toEqual(["ut_probe", "ut_probe_two"]);
+  });
+
+  test("absent unmanagedTables on a feature is ok", () => {
+    const feat = defineFeature("plain", () => {
+      // no r.unmanagedTable calls
+    });
+    expect(feat.unmanagedTables).toEqual({});
+  });
+});
+
+describe("createRegistry — unmanagedTable aggregation", () => {
+  test("rejects cross-feature tableName collisions at boot", () => {
+    // Two features can't share the same physical tableName — migrate-runner
+    // would race two CREATE TABLE statements. Boot-validator catches it.
+    const featA = defineFeature("a", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "first" });
+    });
+    const featB = defineFeature("b", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "second" });
+    });
+    expect(() => createRegistry([featA, featB])).toThrow(
+      /Unmanaged-table "ut_probe" registered by both feature "a" and "b"/,
+    );
+  });
+
+  test("two features with distinct tableNames register cleanly", () => {
+    const featA = defineFeature("a", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "first" });
+    });
+    const featB = defineFeature("b", (r) => {
+      r.unmanagedTable(probeMetaTwo, { reason: "second" });
+    });
+    expect(() => createRegistry([featA, featB])).not.toThrow();
+  });
+});

package/src/engine/__tests__/validate-projection-allowlist.test.ts

@@ -3,11 +3,10 @@
 // is included here, plus the self-registration via defineStep({ subPaths })
 // gate (Followup #15).
 
+import { describe, expect, it } from "bun:test";
 import { randomUUID } from "node:crypto";
-import { eq } from "drizzle-orm";
-import { pgTable, text, uuid } from "drizzle-orm/pg-core";
-import { describe, expect, it } from "vitest";
 import { z } from "zod";
+import { table as pgTable, text, uuid } from "../../db/dialect";
 import { defineFeature } from "../define-feature";
 import { defineWriteHandler } from "../define-handler";
 import { defineStep } from "../define-step";
@@ -117,7 +116,7 @@ describe("validateProjectionAllowlist", () => {
           perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.unsafeProjectionDelete({
               table: widgetsTable,
-              where: () => eq(widgetsTable.id, "anything"),
+              where: () => ({ id: "anything" }),
             }),
             r.step.return({ isSuccess: true as const, data: { ok: true } }),
           ]),
@@ -140,7 +139,7 @@ describe("validateProjectionAllowlist", () => {
           perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.unsafeProjectionDelete({
               table: demoLogTable,
-              where: () => eq(demoLogTable.id, "anything"),
+              where: () => ({ id: "anything" }),
             }),
             r.step.return({ isSuccess: true as const, data: { ok: true } }),
           ]),

package/src/engine/__tests__/validation-hooks.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 "../index";
 import type { ValidationError } from "../validation";
 import { runValidation } from "../validation";

package/src/engine/__tests__/visual-tree-patterns.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { buildTarget, createRegistry, defineFeature } from "../index";
 import type { TreeChildrenSubscribe, TreeNode } from "../types/tree-node";
 

package/src/engine/boot-validator/entity-handler.ts

@@ -177,7 +177,7 @@ export function validateLocatedTimestamps(feature: FeatureDefinition): void {
 // in der multi-Variante). Catched at boot, lange bevor drizzle-kit beim
 // generate-Run zickt.
 //
-// `tenantId` als einzige Spalte ist redundant — buildDrizzleTable legt
+// `tenantId` als einzige Spalte ist redundant — buildEntityTable legt
 // den Index sowieso automatisch an. Wir lassen die Composite-Form erlaubt
 // (`["tenantId", "key"]` ist sinnvoll), nur die rein-tenantId-Single-
 // column-Form blockieren wir.
@@ -225,13 +225,13 @@ export function validateEntityIndexes(feature: FeatureDefinition): void {
         }
       }
       // UNIQUE-constraint auf tenantId ist semantisch (1:1 tenant→entity)
-      // und NICHT redundant — buildDrizzleTable's auto-Index ist nur ein
+      // und NICHT redundant — buildEntityTable's auto-Index ist nur ein
       // Performance-Hint, kein constraint. Nur die rein-tenantId-Single-
       // column-non-unique-Form blockieren.
       if (def.columns.length === 1 && def.columns[0] === "tenantId" && !def.unique) {
         throw new Error(
           `${where}: single-column index on "tenantId" is redundant — ` +
-            `buildDrizzleTable always creates one automatically. Remove this entry.`,
+            `buildEntityTable always creates one automatically. Remove this entry.`,
         );
       }
     }

package/src/engine/boot-validator/ownership.ts

@@ -16,7 +16,7 @@ export function validateOwnershipRules(
   for (const [entityName, entity] of Object.entries(feature.entities)) {
     const columnNames = new Set<string>(Object.keys(entity.fields));
     // Framework-managed columns that rules are allowed to reference too.
-    // These are the base columns buildDrizzleTable adds unconditionally.
+    // These are the base columns buildEntityTable adds unconditionally.
     const frameworkColumns = ["id", "tenantId", "version", "insertedAt", "modifiedAt"];
     for (const col of frameworkColumns) columnNames.add(col);
 

package/src/engine/define-feature.ts

@@ -1,5 +1,5 @@
-import type { PgTable } from "drizzle-orm/pg-core";
 import type { ZodType, z } from "zod";
+import type { EntityTableMeta } from "../db/entity-table-meta";
 import { toTableName } from "../db/table-builder";
 import { LifecycleHookTypes } from "./constants";
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
@@ -62,6 +62,7 @@ import type {
   TreeActionDef,
   TreeActionsHandle,
   TreeChildrenSubscribe,
+  UnmanagedTableEntry,
   ValidationHookFn,
   WriteHandlerDef,
   WriteHandlerFn,
@@ -137,6 +138,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const projections: Record<string, ProjectionDefinition> = {};
   const multiStreamProjections: Record<string, MultiStreamProjectionDefinition> = {};
   const rawTables: Record<string, RawTableEntry> = {};
+  const unmanagedTables: Record<string, UnmanagedTableEntry> = {};
   const authClaimsHooks: AuthClaimsFn[] = [];
   const claimKeys: Record<string, ClaimKeyDefinition> = {};
   const screens: Record<string, ScreenDefinition> = {};
@@ -759,7 +761,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       httpRoutes[key] = definition;
     },
 
-    rawTable(rawTableName: string, table: PgTable, options: RawTableOptions): void {
+    rawTable(rawTableName: string, table: unknown, options: RawTableOptions): void {
       // Same kebab guard as r.projection / r.screen / r.nav so authoring-time
       // mistakes surface at the feature file, not deep in registry boot.
       if (!isKebabSegment(rawTableName)) {
@@ -792,6 +794,38 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       };
     },
 
+    unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void {
+      // Name comes from the meta itself — apps already give the table a
+      // name when calling defineUnmanagedTable, no need to repeat it.
+      const tableName = meta.tableName;
+      if (!isKebabSegment(tableName.replace(/_/g, "-"))) {
+        // EntityTableMeta uses snake_case for tableName (matches Postgres
+        // convention); we just guard against truly broken input.
+        throw new Error(
+          `[Feature ${name}] Unmanaged-table name "${tableName}" must be a ` +
+            `valid identifier (lowercase letters, digits, underscores; start with a letter).`,
+        );
+      }
+      if (unmanagedTables[tableName]) {
+        throw new Error(
+          `[Feature ${name}] r.unmanagedTable("${tableName}") already registered. ` +
+            `Unmanaged-table names must be unique per feature.`,
+        );
+      }
+      if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
+        throw new Error(
+          `[Feature ${name}] r.unmanagedTable("${tableName}"): options.reason must be a ` +
+            `non-empty string. The reason justifies the audit-trail bypass — ` +
+            `if you can't write one, declare data via r.entity() instead.`,
+        );
+      }
+      unmanagedTables[tableName] = {
+        name: tableName,
+        meta,
+        reason: options.reason,
+      };
+    },
+
     claimKey<T extends ClaimKeyType>(
       shortName: string,
       options: { readonly type: T },
@@ -906,6 +940,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     workspaces,
     httpRoutes,
     rawTables,
+    unmanagedTables,
     ...(treeActions !== undefined && { treeActions }),
     ...(treeProvider !== undefined && { treeProvider }),
     ...(envSchema !== undefined && { envSchema }),

package/src/engine/entity-handlers.ts

@@ -7,7 +7,7 @@ import {
   enrichWithReferences,
 } from "../db/eagerload";
 import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-store-executor";
-import { buildDrizzleTable } from "../db/table-builder";
+import { buildEntityTable } from "../db/table-builder";
 import { assertUnreachable } from "../utils";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
 import type { AccessRule, EntityDefinition, QueryHandlerDef, WriteHandlerDef } from "./types";
@@ -133,7 +133,7 @@ export function defineEntityWriteHandler(
     );
   }
 
-  const table = buildDrizzleTable(entityName, entity);
+  const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });
 
   let schema: ZodType;
@@ -182,7 +182,7 @@ export function defineEntityQueryHandler(
 ): QueryHandlerDef {
   const { entityName, verb } = parseHandlerName(name, QUERY_VERBS);
 
-  const table = buildDrizzleTable(entityName, entity);
+  const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });
 
   let schema: ZodType;
@@ -319,14 +319,14 @@ type AnyTable = TableColumns<any>;
 //
 //   const { table, executor } = createEntityExecutor("counter", counterEntity);
 //
-// Keep using the explicit buildDrizzleTable / createEventStoreExecutor duo
+// Keep using the explicit buildEntityTable / createEventStoreExecutor duo
 // when you need search-adapter / entity-cache options on the executor — this
 // helper covers the zero-config case.
 export function createEntityExecutor(
   entityName: string,
   entity: EntityDefinition,
 ): { readonly table: AnyTable; readonly executor: EventStoreExecutor } {
-  const table = buildDrizzleTable(entityName, entity);
+  const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });
   return { table, executor };
 }

package/src/engine/factories.ts

@@ -25,7 +25,7 @@ import type {
 
 // Generic über `R extends true | false` (statt `boolean`) damit
 // `createTextField({ required: true })` literal `required: true` im
-// Return-Type behält. `boolean` würde widenen — DrizzleTable<E>'s
+// Return-Type behält. `boolean` würde widenen — EntityTable<E>'s
 // Mapped-Type könnte dann nicht zwischen `required: true` und
 // `required: false` dispatchen, jede Column würde zu nullable
 // degradieren. Default `R = false` matcht den runtime-default. Pattern

package/src/engine/feature-ast/__tests__/canonical-form.test.ts

@@ -16,8 +16,8 @@
 // `// kumiko-feature-version: 1` — sodass künftige Format-Bumps
 // gezielt migriert werden können (separater Migrator pro Version).
 
+import { describe, expect, test } from "bun:test";
 import { Project } from "ts-morph";
-import { describe, expect, test } from "vitest";
 import { parseSourceFile } from "../parse";
 
 const CANONICAL_FEATURE = `

package/src/engine/feature-ast/__tests__/parse-happy-path.test.ts

@@ -7,8 +7,8 @@
 // That is fine for framework-internal code, but the AI Builder must
 // NEVER produce code with ParseErrors. This test pins the contract.
 
+import { describe, expect, test } from "bun:test";
 import { Project } from "ts-morph";
-import { describe, expect, test } from "vitest";
 import { parseSourceFile } from "../parse";
 
 const INLINE_FEATURE = `

package/src/engine/feature-ast/__tests__/parse-real-features.test.ts

@@ -23,8 +23,8 @@
 // generated features and Designer-authored features will follow the
 // inline contract by construction.
 
+import { describe, expect, test } from "bun:test";
 import { resolve } from "node:path";
-import { describe, expect, test } from "vitest";
 import { parseFeatureFile } from "../parse";
 import type { FeaturePattern } from "../patterns";
 
@@ -119,7 +119,7 @@ describe("parseFeatureFile against real Kumiko features", () => {
       for (const error of result.errors) {
         expect(error.methodName).toMatch(/^[a-zA-Z]+$/);
         expect(error.reason.length).toBeGreaterThan(10);
-        expect(error.source.file).toContain(feature.path.split("/").pop());
+        expect(error.source.file as string).toContain(feature.path.split("/").pop()!);
         expect(error.source.start.line).toBeGreaterThan(0);
         expect(error.source.raw).toContain("r.");
       }

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -10,8 +10,8 @@
 // and surfaced as UnknownPattern with the correct methodName, so the
 // Designer/AI know the call exists.
 
+import { describe, expect, test } from "bun:test";
 import { Project } from "ts-morph";
-import { describe, expect, test } from "vitest";
 import { parseSourceFile } from "../parse";
 
 function createProject() {