@cosmicdrift/kumiko-framework 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,57 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Marc Frost
+
+Licensed Work:        @cosmicdrift/kumiko-framework
+                      The Licensed Work is © 2026 Marc Frost.
+
+Additional Use Grant: 
+You may use the Licensed Work in production for any purpose, including 
+commercially, EXCEPT for the Restricted Use. 
+
+"Restricted Use" is defined as using the Licensed Work to provide a platform 
+or service to third parties that allows them to host, deploy, or run their 
+own applications built with the Licensed Work. This includes, but is not 
+limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
+platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
+managed offering of the Licensed Work.
+
+This restriction does not apply to the Licensor, any entity controlled by, 
+controlling, or under common control with the Licensor ("Affiliates"), or 
+contractors acting on their behalf. The Licensor remains free to use the 
+Licensed Work for any purpose, including for the operation of kumiko.so.
+
+Change Date:          2030-05-05
+Change License:       Apache License, Version 2.0
+
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, 
+redistribute, and make non-production use of the Licensed Work. The Licensor may 
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly 
+available distribution of the Licensed Work under this License, whichever comes 
+first, this License will convert to the Change License.
+
+This Business Source License governs use of the Licensed Work in all cases, except 
+as to any use that is explicitly granted in the Additional Use Grant above or 
+under the Change License after the Change Date.
+
+If your use of the Licensed Work does not comply with the requirements of this 
+License, you must cease use of the Licensed Work immediately.
+
+All copies of the Licensed Work, and all derivative works thereof, must include 
+this License.
+
+This License does not grant you any right, title, or interest in any trademark, 
+logo, or branding of the Licensor, except as required to comply with this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
+“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
+TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
+ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
     "directory": "packages/framework"
   },
   "bugs": {
-    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
   },
   "homepage": "https://kumiko.so",
   "keywords": [

package/src/__tests__/anonymous-access.integration.ts

@@ -15,7 +15,7 @@ import {
   defineFeature,
   type TenantId,
 } from "../engine";
-import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../stack";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../stack";
 
 const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
 const OTHER_TENANT_ID = "00000000-0000-4000-8000-000000000002" as TenantId;
@@ -104,8 +104,8 @@ describe("anonymous access — single-tenant default", () => {
       features: [shopFeature],
       anonymousAccess: { defaultTenantId: TENANT_ID },
     });
-    await createEntityTable(stack.db, productEntity);
-    await createEntityTable(stack.db, orderEntity);
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
   });
 
   afterAll(() => stack.cleanup());
@@ -216,8 +216,8 @@ describe("anonymous access — header-supplied tenant", () => {
         tenantExists: async (id: TenantId) => id === TENANT_ID || id === OTHER_TENANT_ID,
       },
     });
-    await createEntityTable(stack.db, productEntity);
-    await createEntityTable(stack.db, orderEntity);
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
   });
 
   afterAll(() => stack.cleanup());
@@ -309,8 +309,8 @@ describe("anonymous access — disabled by default", () => {
 
   beforeAll(async () => {
     stack = await setupTestStack({ features: [shopFeature] });
-    await createEntityTable(stack.db, productEntity);
-    await createEntityTable(stack.db, orderEntity);
+    await unsafeCreateEntityTable(stack.db, productEntity);
+    await unsafeCreateEntityTable(stack.db, orderEntity);
   });
 
   afterAll(() => stack.cleanup());

package/src/__tests__/error-contract.integration.ts

@@ -22,11 +22,11 @@ import {
   writeFailure,
 } from "../errors";
 import {
-  createEntityTable,
   createTestUser,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../stack";
 
 // --- Entity + handlers that deliberately raise each Kumiko error class ---
@@ -187,7 +187,7 @@ const guest = createTestUser({ id: 2, roles: ["Guest"] });
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [errorFeature] });
-  await createEntityTable(stack.db, itemEntity);
+  await unsafeCreateEntityTable(stack.db, itemEntity);
 });
 afterAll(async () => stack.cleanup());
 beforeEach(async () => {

package/src/__tests__/field-access.integration.ts

@@ -12,13 +12,13 @@ import {
   type SessionUser,
 } from "../engine";
 import {
-  createEntityTable,
   createTestDb,
   createTestRedis,
   createTestUser,
   type TestDb,
   type TestRedis,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../stack";
 
 // --- Entity with field-level access ---
@@ -52,7 +52,7 @@ beforeAll(async () => {
   testDb = await createTestDb();
   testRedis = await createTestRedis();
 
-  await createEntityTable(testDb.db, employeeEntity);
+  await unsafeCreateEntityTable(testDb.db, employeeEntity);
 
   const feature = defineFeature("employees", (r) => {
     r.entity("employee", employeeEntity);

package/src/__tests__/full-stack.integration.ts

@@ -5,11 +5,11 @@ import { defineFeature, type EntityId, type HandlerContext, type SaveContext } f
 import { UnprocessableError, writeFailure } from "../errors";
 import { eventsTable } from "../event-store";
 import {
-  createEntityTable,
   createTestUser,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../stack";
 import { expectErrorIncludes, sharedUserEntity, sharedUserTable } from "../testing";
 
@@ -203,7 +203,7 @@ const otherTenantAdmin = createTestUser({
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [userFeature] });
-  await createEntityTable(stack.db, userEntity, "user");
+  await unsafeCreateEntityTable(stack.db, userEntity, "user");
 });
 
 afterAll(async () => {

package/src/__tests__/ownership.integration.ts

@@ -15,12 +15,12 @@ import {
 } from "../engine";
 import type { SessionUser, TenantId } from "../engine/types";
 import {
-  createEntityTable,
   createTestUser,
   setupTestStack,
   type TestStack,
   TestUsers,
   testTenantId,
+  unsafeCreateEntityTable,
 } from "../stack";
 import { expectErrorIncludes } from "../testing";
 
@@ -123,7 +123,7 @@ let stack: TestStack;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [teamsFeature, contractsFeature] });
-  await createEntityTable(stack.db, contractEntity, "contract");
+  await unsafeCreateEntityTable(stack.db, contractEntity, "contract");
 });
 
 afterAll(async () => {

package/src/__tests__/raw-table.integration.ts

@@ -0,0 +1,128 @@
+// Integration test for r.rawTable() — proves the full boot path:
+// defineFeature declares a raw table → setupTestStack auto-pushes it →
+// INSERT/SELECT against the real DB roundtrip. Plan reference:
+// kumiko-platform/docs/plans/architecture/table-ddl-guard.md (Stufe 3).
+
+import { eq, sql } from "drizzle-orm";
+import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { defineFeature } from "../engine";
+import { setupTestStack, type TestStack, unsafePushTables } from "../stack";
+
+// External-system payload cache — the textbook r.rawTable() use case:
+// write-only by an integration handler, read-only by a query, never
+// event-sourced (the data isn't a domain fact, it's a side-effect
+// snapshot).
+const stripeWebhookCache = pgTable("rt_int_stripe_webhook_cache", {
+  eventId: text("event_id").primaryKey(),
+  payload: text("payload").notNull(),
+  receivedAt: timestamp("received_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+// A second physical table reachable through two distinct r.rawTable
+// registrations — pins the seenTables-by-reference dedupe at push time.
+// Two logical names, one CREATE.
+const sharedSyncCache = pgTable("rt_int_shared_sync_cache", {
+  syncId: text("sync_id").primaryKey(),
+  payload: text("payload").notNull(),
+});
+
+const webhookCacheFeature = defineFeature("webhook-cache", (r) => {
+  r.rawTable("stripe", stripeWebhookCache, {
+    reason: "external Stripe webhook payload cache — write-only by webhook handler",
+  });
+  r.rawTable("primary-sync", sharedSyncCache, {
+    reason: "shared sync-state cache, primary writer",
+  });
+  r.rawTable("secondary-sync", sharedSyncCache, {
+    reason: "same physical table, different logical role for read consumers",
+  });
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [webhookCacheFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("r.rawTable — DB roundtrip via setupTestStack", () => {
+  test("table is auto-pushed and accepts INSERT + SELECT", async () => {
+    const eventId = "evt_test_123";
+    const payload = JSON.stringify({ type: "invoice.paid", amount: 4200 });
+
+    await stack.db.insert(stripeWebhookCache).values({ eventId, payload });
+
+    const rows = await stack.db
+      .select()
+      .from(stripeWebhookCache)
+      .where(eq(stripeWebhookCache.eventId, eventId));
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.payload).toBe(payload);
+    expect(rows[0]?.receivedAt).toBeInstanceOf(Date);
+  });
+
+  test("registry exposes the raw table with its reason and featureName", () => {
+    const all = stack.registry.getAllRawTables();
+    const entry = all.get("stripe");
+    expect(entry).toBeDefined();
+    expect(entry?.featureName).toBe("webhook-cache");
+    expect(entry?.reason).toContain("Stripe webhook payload cache");
+    expect(entry?.table).toBe(stripeWebhookCache);
+  });
+
+  test("INSERT bypasses the event store — no kumiko_events row produced", async () => {
+    // Proves that the rawTable lives outside the event-sourcing graph:
+    // a write to it shouldn't append anything to kumiko_events. If a
+    // future regression accidentally routed raw-table writes through
+    // the executor, a row would show up here.
+    const before = await stack.db.execute<{ count: string }>(
+      sql`SELECT COUNT(*)::text AS count FROM kumiko_events`,
+    );
+    const beforeCount = Number(before[0]?.count ?? 0);
+
+    await stack.db.insert(stripeWebhookCache).values({
+      eventId: "evt_no_event_emitted",
+      payload: "{}",
+    });
+
+    const after = await stack.db.execute<{ count: string }>(
+      sql`SELECT COUNT(*)::text AS count FROM kumiko_events`,
+    );
+    const afterCount = Number(after[0]?.count ?? 0);
+
+    expect(afterCount).toBe(beforeCount);
+  });
+
+  test("two registrations sharing one PgTable result in one CREATE (dedupe by reference)", async () => {
+    // primary-sync + secondary-sync both target sharedSyncCache. If the
+    // setupTestStack dedupe (seenTables-by-table-reference) had silently
+    // broken, beforeAll's setupTestStack would have raised a 42P07 on
+    // the second push and never reached this test.
+    await stack.db.insert(sharedSyncCache).values({ syncId: "sync_1", payload: "{}" });
+    const rows = await stack.db
+      .select()
+      .from(sharedSyncCache)
+      .where(eq(sharedSyncCache.syncId, "sync_1"));
+    expect(rows).toHaveLength(1);
+    // Both registrations are visible in the registry — same physical
+    // target, different logical handles.
+    expect(stack.registry.getAllRawTables().get("primary-sync")?.table).toBe(sharedSyncCache);
+    expect(stack.registry.getAllRawTables().get("secondary-sync")?.table).toBe(sharedSyncCache);
+  });
+
+  test("a second push on the same rawTable would crash — proves tableExists-filter is load-bearing", async () => {
+    // The setupTestStack push is idempotent because it filters by
+    // tableExists before calling unsafePushTables (which is itself
+    // strict — that's the contract of the unsafe-prefix). Pin the
+    // failure mode of the unfiltered call: a direct second push on
+    // the same Drizzle schema raises the underlying PG error. This
+    // is the negative form of the idempotency contract — without the
+    // filter, a re-boot against a persistent dev DB would crash here.
+    await expect(unsafePushTables(stack.db, { idem: stripeWebhookCache })).rejects.toThrow();
+  });
+});

package/src/__tests__/reference-data.integration.ts

@@ -2,7 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { integer, table as pgTable, serial, text } from "../db/dialect";
 import { seedReferenceData } from "../db/reference-data";
 import type { ReferenceDataDef } from "../engine/types";
-import { createTestDb, pushTables, type TestDb } from "../stack";
+import { createTestDb, type TestDb, unsafePushTables } from "../stack";
 
 // --- Tables ---
 
@@ -25,7 +25,7 @@ let testDb: TestDb;
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await pushTables(testDb.db, { countryTable, statusTable });
+  await unsafePushTables(testDb.db, { countryTable, statusTable });
 });
 
 afterAll(async () => {

package/src/__tests__/transition-guard.integration.ts

@@ -9,7 +9,7 @@ import {
   createTextField,
   defineFeature,
 } from "../engine";
-import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../stack";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../stack";
 import { expectErrorIncludes } from "../testing";
 
 // Two entities, both with a field named `status`, but different transitions.
@@ -178,9 +178,9 @@ const admin = TestUsers.admin;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [feature] });
-  await createEntityTable(stack.db, invoiceEntity);
-  await createEntityTable(stack.db, orderEntity);
-  await createEntityTable(stack.db, ticketEntity);
+  await unsafeCreateEntityTable(stack.db, invoiceEntity);
+  await unsafeCreateEntityTable(stack.db, orderEntity);
+  await unsafeCreateEntityTable(stack.db, ticketEntity);
 });
 
 afterAll(async () => {

package/src/api/__tests__/batch.integration.ts

@@ -12,7 +12,7 @@ import {
   type SaveContext,
 } from "../../engine";
 import { UnprocessableError, writeFailure } from "../../errors";
-import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
 // Entity: a simple "item" with name + counter
 const itemEntity = createEntity({
@@ -151,8 +151,8 @@ const admin = TestUsers.admin;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [itemFeature] });
-  await createEntityTable(stack.db, itemEntity);
-  await createEntityTable(stack.db, auditEntity);
+  await unsafeCreateEntityTable(stack.db, itemEntity);
+  await unsafeCreateEntityTable(stack.db, auditEntity);
 });
 
 afterAll(async () => {

package/src/api/__tests__/dispatcher-live.integration.ts

@@ -5,7 +5,7 @@ import { generateToken } from "../../api/tokens";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { buildDrizzleTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
-import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { generateId } from "../../utils";
 
 // End-to-end: UI code would call `dispatcher.write("feat:write:item:create", ...)`.
@@ -97,7 +97,7 @@ async function buildFetch(): Promise<{
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [itemFeature] });
-  await createEntityTable(stack.db, itemEntity);
+  await unsafeCreateEntityTable(stack.db, itemEntity);
 });
 
 afterAll(async () => {

package/src/api/__tests__/nested-write.integration.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { buildDrizzleTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
-import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
 // Two entities in a 1:N relation. The relation is declared with
 // `nestedWrite: true`, which opts the framework into expanding
@@ -69,8 +69,8 @@ const admin = TestUsers.admin;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [nestedFeature] });
-  await createEntityTable(stack.db, projectEntity);
-  await createEntityTable(stack.db, taskEntity);
+  await unsafeCreateEntityTable(stack.db, projectEntity);
+  await unsafeCreateEntityTable(stack.db, taskEntity);
 });
 
 afterAll(async () => {

package/src/db/__tests__/drizzle-helpers.integration.ts

@@ -2,7 +2,7 @@ import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
-import { createEntityTable, testTenantId } from "../../stack";
+import { testTenantId, unsafeCreateEntityTable } from "../../stack";
 import { applyCursorQuery, encodeCursor } from "../cursor";
 import { buildDrizzleTable } from "../table-builder";
 
@@ -49,7 +49,7 @@ beforeAll(async () => {
   client = postgres(testUrl);
   db = drizzle(client);
 
-  await createEntityTable(db, entity);
+  await unsafeCreateEntityTable(db, entity);
 
   const rows = [
     {

package/src/db/__tests__/event-store-executor-list.integration.ts

@@ -8,7 +8,7 @@ import { sql } from "drizzle-orm";
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
 import { createEntity, createNumberField, createTextField } from "../../engine";
 import { createEventsTable } from "../../event-store";
-import { createEntityTable, createTestDb, type TestDb, TestUsers } from "../../stack";
+import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildDrizzleTable } from "../table-builder";
 import { createTenantDb, type TenantDb } from "../tenant-db";
@@ -28,7 +28,7 @@ const admin = TestUsers.admin;
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEntityTable(testDb.db, entity, "pagerItem");
+  await unsafeCreateEntityTable(testDb.db, entity, "pagerItem");
   await createEventsTable(testDb.db);
   tdb = createTenantDb(testDb.db, admin.tenantId);
 });

package/src/db/__tests__/event-store-executor.integration.ts

@@ -2,7 +2,13 @@ import { sql } from "drizzle-orm";
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
 import { createEventsTable } from "../../event-store";
-import { createEntityTable, createTestDb, type TestDb, TestUsers, testTenantId } from "../../stack";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildDrizzleTable } from "../table-builder";
 import { createTenantDb, type TenantDb } from "../tenant-db";
@@ -24,7 +30,7 @@ const adminUser = TestUsers.admin;
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEntityTable(testDb.db, entity, "esExecUser");
+  await unsafeCreateEntityTable(testDb.db, entity, "esExecUser");
   await createEventsTable(testDb.db);
   tdb = createTenantDb(testDb.db, adminUser.tenantId);
 });
@@ -119,7 +125,7 @@ describe("event-store-executor — sensitive fields", () => {
   });
 
   beforeAll(async () => {
-    await createEntityTable(testDb.db, sensitiveEntity, "esExecSensitive");
+    await unsafeCreateEntityTable(testDb.db, sensitiveEntity, "esExecSensitive");
   });
 
   beforeEach(async () => {

package/src/db/__tests__/implicit-projection-equivalence.integration.ts

@@ -22,7 +22,7 @@ import { createRegistry } from "../../engine/registry";
 import { createEventsTable } from "../../event-store";
 import { rebuildProjection } from "../../pipeline";
 import { createProjectionStateTable } from "../../pipeline/projection-state";
-import { createEntityTable, createTestDb, type TestDb, TestUsers } from "../../stack";
+import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildDrizzleTable } from "../table-builder";
 import { createTenantDb, type TenantDb } from "../tenant-db";
@@ -49,7 +49,7 @@ const adminUser = TestUsers.admin;
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEntityTable(testDb.db, userEntity, "user");
+  await unsafeCreateEntityTable(testDb.db, userEntity, "user");
   await createEventsTable(testDb.db);
   await createProjectionStateTable(testDb.db);
   tdb = createTenantDb(testDb.db, adminUser.tenantId);
@@ -244,7 +244,7 @@ const sensitiveDrizzleTable = buildDrizzleTable("sensitive-user", sensitiveEntit
 
 describe("implicit-projection / dokumentierte Sensitive-Drift", () => {
   beforeAll(async () => {
-    await createEntityTable(testDb.db, sensitiveEntity, "sensitive-user");
+    await unsafeCreateEntityTable(testDb.db, sensitiveEntity, "sensitive-user");
   });
 
   beforeEach(async () => {

package/src/db/__tests__/multi-row-insert.integration.ts

@@ -10,7 +10,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { buildDrizzleTable } from "../../db/table-builder";
 import { createEntity, createTextField } from "../../engine";
-import { createEntityTable, setupTestStack, type TestStack } from "../../stack";
+import { setupTestStack, type TestStack, unsafeCreateEntityTable } from "../../stack";
 
 const linkEntity = createEntity({
   table: "mri_links",
@@ -25,7 +25,7 @@ let stack: TestStack;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [] });
-  await createEntityTable(stack.db, linkEntity);
+  await unsafeCreateEntityTable(stack.db, linkEntity);
 });
 
 afterAll(async () => stack?.cleanup());
@@ -44,7 +44,7 @@ describe("instant() customType is forgiving with ISO strings", () => {
   const tsTable = buildDrizzleTable("ts-row", tsEntity);
 
   test("INSERT accepts an ISO string for an instant column (forgiving path)", async () => {
-    await createEntityTable(stack.db, tsEntity, "ts-row");
+    await unsafeCreateEntityTable(stack.db, tsEntity, "ts-row");
     // insertedAt is base-column, type instant. Pass an ISO string —
     // coercion in toDriver handles it. Without the fix, Drizzle-driver
     // would call .toString() on a string and produce a malformed driver

package/src/db/__tests__/schema-migration.integration.ts

@@ -9,7 +9,7 @@ import {
   defineFeature,
 } from "../../engine";
 import type { FeatureDefinition } from "../../engine/types";
-import { createTestDb, pushTables, type TestDb } from "../../stack";
+import { createTestDb, type TestDb, unsafePushTables } from "../../stack";
 import { buildDrizzleTable } from "../table-builder";
 
 /**
@@ -19,7 +19,7 @@ import { buildDrizzleTable } from "../table-builder";
  * Each test simulates:
  *   1. Developer defines/changes entities
  *   2. buildDrizzleTable creates Drizzle table objects
- *   3. Schema is applied to a real database via pushTables (drizzle-kit push)
+ *   3. Schema is applied to a real database via unsafePushTables (drizzle-kit push)
  *   4. We verify the DB state matches expectations
  */
 
@@ -41,7 +41,7 @@ async function applySchema(features: readonly FeatureDefinition[]): Promise<void
       tables[entityName] = buildDrizzleTable(entityName, entity);
     }
   }
-  await pushTables(testDb.db, tables);
+  await unsafePushTables(testDb.db, tables);
 }
 
 // Helper: read column info from information_schema
@@ -136,7 +136,7 @@ describe("schema migration workflows", () => {
       table: "wf2_users",
       fields: { email: createTextField() },
     });
-    await pushTables(testDb.db, { user: buildDrizzleTable("user", initialEntity) });
+    await unsafePushTables(testDb.db, { user: buildDrizzleTable("user", initialEntity) });
 
     // Developer adds a new field
     const updatedEntity = createEntity({
@@ -148,7 +148,7 @@ describe("schema migration workflows", () => {
     });
 
     // Push updated schema — drizzle-kit generates ALTER TABLE ADD COLUMN
-    await pushTables(
+    await unsafePushTables(
       testDb.db,
       { user: buildDrizzleTable("user", updatedEntity) },
       { user: buildDrizzleTable("user", initialEntity) },
@@ -167,7 +167,7 @@ describe("schema migration workflows", () => {
       fields: { name: createTextField() },
     });
     const initialTable = buildDrizzleTable("project", initialEntity);
-    await pushTables(testDb.db, { project: initialTable });
+    await unsafePushTables(testDb.db, { project: initialTable });
 
     // Insert a row first (to prove ADD COLUMN with default doesn't break existing rows)
     await testDb.db
@@ -180,7 +180,7 @@ describe("schema migration workflows", () => {
       fields: { name: createTextField(), isArchived: createBooleanField({ default: false }) },
     });
     const updatedTable = buildDrizzleTable("project", updatedEntity);
-    await pushTables(testDb.db, { project: updatedTable }, { project: initialTable });
+    await unsafePushTables(testDb.db, { project: updatedTable }, { project: initialTable });
 
     // Existing row should have the default value
     const rows = await testDb.db.select().from(updatedTable);
@@ -200,7 +200,7 @@ describe("schema migration workflows", () => {
       fields: { email: createTextField({ required: true }) },
     });
     const initialTable = buildDrizzleTable("user", initialEntity);
-    await pushTables(testDb.db, { user: initialTable });
+    await unsafePushTables(testDb.db, { user: initialTable });
 
     await testDb.db
       .insert(initialTable)
@@ -214,7 +214,7 @@ describe("schema migration workflows", () => {
       },
     });
     const updatedTable = buildDrizzleTable("user", updatedEntity);
-    await pushTables(testDb.db, { user: updatedTable }, { user: initialTable });
+    await unsafePushTables(testDb.db, { user: updatedTable }, { user: initialTable });
 
     const rows = await testDb.db.select().from(updatedTable);
     expect(rows[0]).toMatchObject({ email: "x@y.z", roles: "[]" });