@cosmicdrift/kumiko-framework 0.1.0 → 0.2.0

package/src/db/__tests__/tenant-db.integration.ts

@@ -2,12 +2,12 @@ import { eq } from "drizzle-orm";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
 import {
-  createEntityTable,
   createTestDb,
-  pushTables,
   type TestDb,
   TestUsers,
   testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
 } from "../../stack";
 import { table as pgTable, serial, text, timestamp } from "../dialect";
 import { buildDrizzleTable } from "../table-builder";
@@ -41,8 +41,8 @@ const tenant2 = TestUsers.otherTenant; // tenantId: 2
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEntityTable(testDb.db, entity, "tenantDbItem");
-  await pushTables(testDb.db, { tdb_system_entries: systemTable });
+  await unsafeCreateEntityTable(testDb.db, entity, "tenantDbItem");
+  await unsafePushTables(testDb.db, { tdb_system_entries: systemTable });
 });
 
 afterAll(async () => {

package/src/db/__tests__/unique-violation-mapping.integration.ts

@@ -17,7 +17,7 @@ import { sql } from "drizzle-orm";
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
 import { createEntity, 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";
@@ -48,7 +48,7 @@ const admin = TestUsers.admin;
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEntityTable(testDb.db, userEntity, "unique-user");
+  await unsafeCreateEntityTable(testDb.db, userEntity, "unique-user");
   await createEventsTable(testDb.db);
   tdb = createTenantDb(testDb.db, admin.tenantId);
 });

package/src/db/schema-inspection.ts

@@ -13,7 +13,7 @@ import type { DbConnection, DbTx } from "./connection";
 // "already exists" error code.
 //
 //   if (await tableExists(db, "public.events")) return;
-//   await pushTables(db, { events: eventsTable });
+//   await unsafePushTables(db, { events: eventsTable });
 export async function tableExists(
   db: DbConnection | DbTx,
   fullyQualifiedName: string,

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

@@ -0,0 +1,149 @@
+// Unit tests for r.rawTable() — declaration-time validation + registry
+// aggregation. Full DB roundtrip (setupTestStack pushes the table → INSERT
+// / SELECT) lives in src/__tests__/raw-table.integration.ts.
+
+import { pgTable, text } from "drizzle-orm/pg-core";
+import { describe, expect, test } from "vitest";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+import type { ProjectionDefinition } from "../types";
+
+const probeTable = pgTable("rt_probe_table", {
+  id: text("id").primaryKey(),
+});
+const probeTableTwo = pgTable("rt_probe_table_two", {
+  id: text("id").primaryKey(),
+});
+
+describe("r.rawTable — declaration", () => {
+  test("rejects non-kebab-case names", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.rawTable("BadName", probeTable, { reason: "test" });
+      }),
+    ).toThrow(/must be kebab-case/);
+  });
+
+  test("rejects duplicate names within one feature", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.rawTable("cache", probeTable, { reason: "test" });
+        r.rawTable("cache", probeTableTwo, { reason: "test" });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects empty reason", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.rawTable("cache", probeTable, { reason: "" });
+      }),
+    ).toThrow(/options\.reason must be a non-empty string/);
+  });
+
+  test("rejects whitespace-only reason", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.rawTable("cache", probeTable, { reason: "   " });
+      }),
+    ).toThrow(/options\.reason must be a non-empty string/);
+  });
+
+  test("accepts valid registration and stores reason verbatim", () => {
+    const feature = defineFeature("probe", (r) => {
+      r.rawTable("cache", probeTable, {
+        reason: "external Stripe webhook cache, write-only by webhook handler",
+      });
+    });
+    expect(feature.rawTables).toHaveProperty("cache");
+    expect(feature.rawTables.cache?.reason).toBe(
+      "external Stripe webhook cache, write-only by webhook handler",
+    );
+    expect(feature.rawTables.cache?.table).toBe(probeTable);
+  });
+});
+
+describe("createRegistry — rawTable aggregation", () => {
+  test("aggregates raw tables across features and tags featureName", () => {
+    const featA = defineFeature("billing", (r) => {
+      r.rawTable("stripe-cache", probeTable, { reason: "external API cache" });
+    });
+    const featB = defineFeature("inventory", (r) => {
+      r.rawTable("legacy-import", probeTableTwo, { reason: "imported pre-ES" });
+    });
+
+    const registry = createRegistry([featA, featB]);
+    const all = registry.getAllRawTables();
+
+    expect(all.size).toBe(2);
+    expect(all.get("stripe-cache")?.featureName).toBe("billing");
+    expect(all.get("stripe-cache")?.reason).toBe("external API cache");
+    expect(all.get("legacy-import")?.featureName).toBe("inventory");
+  });
+
+  test("rejects cross-feature name collisions at boot", () => {
+    const featA = defineFeature("a", (r) => {
+      r.rawTable("shared", probeTable, { reason: "first" });
+    });
+    const featB = defineFeature("b", (r) => {
+      r.rawTable("shared", probeTableTwo, { reason: "second" });
+    });
+
+    expect(() => createRegistry([featA, featB])).toThrow(
+      /Raw-table "shared" registered by both feature "a" and "b"/,
+    );
+  });
+
+  test("absent rawTables block on a feature is ok (legacy / hand-built features)", () => {
+    const featNoRaw = defineFeature("no-raw", () => {
+      // no r.rawTable calls
+    });
+    const registry = createRegistry([featNoRaw]);
+    expect(registry.getAllRawTables().size).toBe(0);
+  });
+
+  test("two raw tables on the same PgTable register under both names", () => {
+    // Different logical names, identical physical target — legitimate
+    // when one role writes (primary cache) and a second role reads
+    // (alias view). Push-time dedupe keeps the boot to a single CREATE;
+    // the registry keeps both entries so callers can resolve either name.
+    const sharedT = pgTable("rt_shared_dedupe", {
+      id: text("id").primaryKey(),
+    });
+    const feat = defineFeature("dedupe", (r) => {
+      r.rawTable("primary", sharedT, { reason: "main writer" });
+      r.rawTable("alias", sharedT, { reason: "alias for read consumers" });
+    });
+    const registry = createRegistry([feat]);
+
+    expect(registry.getAllRawTables().size).toBe(2);
+    expect(registry.getAllRawTables().get("primary")?.table).toBe(sharedT);
+    expect(registry.getAllRawTables().get("alias")?.table).toBe(sharedT);
+  });
+
+  test("rejects rawTable that shares a PgTable with an explicit projection", () => {
+    // A r.rawTable() declaring the same physical table as a registered
+    // r.projection() is almost always an authoring bug — two owners on
+    // the same physical table, one event-sourced, one bypass. Boot
+    // throws so the failure points at the misconfiguration site.
+    const sharedT = pgTable("rt_collision_phys", {
+      id: text("id").primaryKey(),
+    });
+    const projection: ProjectionDefinition = {
+      name: "shared-summary",
+      source: "shared",
+      table: sharedT,
+      apply: {},
+    };
+    const featProj = defineFeature("proj-owner", (r) => {
+      r.projection(projection);
+    });
+    const featRaw = defineFeature("raw-owner", (r) => {
+      r.rawTable("collision", sharedT, { reason: "intentionally bad" });
+    });
+
+    expect(() => createRegistry([featProj, featRaw])).toThrow(
+      /shares a Drizzle PgTable with a registered projection/,
+    );
+  });
+});

package/src/engine/define-feature.ts

@@ -1,3 +1,4 @@
+import type { PgTable } from "drizzle-orm/pg-core";
 import type { ZodType, z } from "zod";
 import { toTableName } from "../db/table-builder";
 import { LifecycleHookTypes } from "./constants";
@@ -44,6 +45,8 @@ import type {
   QueryHandlerDef,
   QueryHandlerFn,
   RateLimitOption,
+  RawTableEntry,
+  RawTableOptions,
   ReferenceDataDef,
   RegistrarExtensionDef,
   RegistrarExtensionRegistration,
@@ -115,6 +118,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const secretKeys: Record<string, SecretKeyDefinition> = {};
   const projections: Record<string, ProjectionDefinition> = {};
   const multiStreamProjections: Record<string, MultiStreamProjectionDefinition> = {};
+  const rawTables: Record<string, RawTableEntry> = {};
   const authClaimsHooks: AuthClaimsFn[] = [];
   const claimKeys: Record<string, ClaimKeyDefinition> = {};
   const screens: Record<string, ScreenDefinition> = {};
@@ -625,6 +629,39 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       httpRoutes[key] = definition;
     },
 
+    rawTable(rawTableName: string, table: PgTable, 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)) {
+        throw new Error(
+          `[Feature ${name}] Raw-table name "${rawTableName}" must be kebab-case ` +
+            `(lowercase letters, digits, dashes; start with a letter). ` +
+            `Got "${rawTableName}" — try "${toKebab(rawTableName).replace(/_/g, "-")}".`,
+        );
+      }
+      if (rawTables[rawTableName]) {
+        throw new Error(
+          `[Feature ${name}] r.rawTable("${rawTableName}") already registered. ` +
+            `Raw-table names must be unique per feature.`,
+        );
+      }
+      // The `reason` is the marker that justifies the bypass — empty
+      // strings would defeat the audit trail. Reject early so the
+      // failure points at the feature file.
+      if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
+        throw new Error(
+          `[Feature ${name}] r.rawTable("${rawTableName}"): options.reason must be a ` +
+            `non-empty string. The reason is the marker that justifies the bypass — ` +
+            `if you can't write one, declare data via r.entity() instead.`,
+        );
+      }
+      rawTables[rawTableName] = {
+        name: rawTableName,
+        table,
+        reason: options.reason,
+      };
+    },
+
     claimKey<T extends ClaimKeyType>(
       shortName: string,
       options: { readonly type: T },
@@ -698,5 +735,6 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     navs,
     workspaces,
     httpRoutes,
+    rawTables,
   };
 }

package/src/engine/registry.ts

@@ -26,6 +26,7 @@ import type {
   PreSaveHookFn,
   ProjectionDefinition,
   QueryHandlerDef,
+  RawTableDef,
   ReferenceDataDef,
   RegistrarExtensionDef,
   RegistrarExtensionRegistration,
@@ -153,6 +154,12 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // qualified-MSP-name → owning-feature name. Used by the event-dispatcher
   // to pause consumers whose feature is globally disabled.
   const multiStreamProjectionFeatureMap = new Map<string, string>();
+  // Raw tables — declared via r.rawTable(). Bypass the projection registry,
+  // so they have no qualified-name namespace and no source-entity index.
+  // Keyed by the feature-local short name; cross-feature uniqueness is
+  // enforced at ingest below (collisions would race two CREATE TABLE
+  // statements at the same physical name and break boot).
+  const rawTableMap = new Map<string, RawTableDef>();
   // Auth-claims hooks — tagged with featureName so the login resolver can
   // auto-prefix each hook's returned keys with "<feature>:".
   const authClaimsHooks: AuthClaimsHookDef[] = [];
@@ -484,6 +491,22 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       multiStreamProjectionFeatureMap.set(qualified, feature.name);
     }
 
+    // Raw tables: aggregated by feature-local short name (unprefixed —
+    // these bypass the qualified-name namespace because they have no
+    // event-stream binding to disambiguate). Reject cross-feature
+    // duplicates at boot so the dev-server doesn't race two CREATE TABLE
+    // statements that target the same physical table name.
+    for (const [rawName, rawDef] of Object.entries(feature.rawTables)) {
+      const existing = rawTableMap.get(rawName);
+      if (existing) {
+        throw new Error(
+          `Raw-table "${rawName}" registered by both feature "${existing.featureName}" and ` +
+            `"${feature.name}". Pick a feature-prefixed name to disambiguate.`,
+        );
+      }
+      rawTableMap.set(rawName, { ...rawDef, featureName: feature.name });
+    }
+
     // Claim keys: aggregated by qualified name. Two features cannot collide
     // here (qualified by feature name), but we still guard for explicit
     // correctness — the only way to hit this is a hand-built FeatureDefinition
@@ -739,6 +762,25 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     }
   }
 
+  // Cross-cut: a r.rawTable() PgTable must not coincide with any
+  // registered projection's table. Silent dedupe via Set would mask a
+  // real authoring bug (two owners writing to the same physical table).
+  // Run after both passes so implicit projections are visible too.
+  const projectionTables = new Set<unknown>();
+  for (const proj of projectionMap.values()) projectionTables.add(proj.table);
+  for (const msp of multiStreamProjectionMap.values()) {
+    if (msp.table) projectionTables.add(msp.table);
+  }
+  for (const raw of rawTableMap.values()) {
+    if (projectionTables.has(raw.table)) {
+      throw new Error(
+        `r.rawTable "${raw.name}" (feature "${raw.featureName}") shares a Drizzle ` +
+          `PgTable with a registered projection. Pick one owner: r.entity() / ` +
+          `r.projection() for event-sourced reads, r.rawTable() for the bypass.`,
+      );
+    }
+  }
+
   for (const [entityName, rels] of relationMap) {
     const includes = new Map<string, readonly string[]>();
     for (const [relName, rel] of Object.entries(rels)) {
@@ -1234,6 +1276,10 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       return projectionMap;
     },
 
+    getAllRawTables(): ReadonlyMap<string, RawTableDef> {
+      return rawTableMap;
+    },
+
     getAllMultiStreamProjections(): ReadonlyMap<string, MultiStreamProjectionDefinition> {
       return multiStreamProjectionMap;
     },

package/src/engine/types/feature.ts

@@ -1,3 +1,4 @@
+import type { PgTable } from "drizzle-orm/pg-core";
 import type { ZodType, z } from "zod";
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "../define-handler";
 import type {
@@ -107,6 +108,36 @@ export type SecretKeyHandle = {
   readonly name: string;
 };
 
+// --- Raw tables (declared by features via r.rawTable()) ---
+
+/** Options accepted by `r.rawTable()`. The `reason` is required so the
+ *  bypass leaves an audit trail at the registration site — reviewers can
+ *  judge legitimacy without spelunking into history, and a future cleanup
+ *  pass can find candidates for migration to `r.entity()`. */
+export type RawTableOptions = {
+  /** Why this table needs to bypass the event-sourcing system. Examples:
+   *  "imported from pre-ES system, read-only", "external Stripe webhook
+   *  payload cache, write-only by webhook handler", "denormalised
+   *  projection of a non-Kumiko data source". */
+  readonly reason: string;
+};
+
+/** Per-feature raw-table registration. Carries the bypass-justification
+ *  reason but knows nothing about the owning feature — that's added when
+ *  the registry aggregates entries cross-feature into `RawTableDef`. */
+export type RawTableEntry = {
+  readonly name: string;
+  readonly table: PgTable;
+  readonly reason: string;
+};
+
+/** Registry-aggregated raw-table — the per-feature `RawTableEntry` plus
+ *  the owning feature name. This is what `Registry.getAllRawTables()`
+ *  exposes to readers (dev-server, ops UIs). */
+export type RawTableDef = RawTableEntry & {
+  readonly featureName: string;
+};
+
 // --- Feature Definition (output of defineFeature) ---
 
 export type FeatureDefinition = {
@@ -184,6 +215,10 @@ export type FeatureDefinition = {
   // den Hono-app (außerhalb /api/*). Pattern symmetrisch zu queryHandlers/
   // writeHandlers — Routes leben mit dem Feature, nicht im Bootstrap.
   readonly httpRoutes: Readonly<Record<string, HttpRouteDefinition>>;
+  // Raw tables declared via r.rawTable() — bypass the event-sourcing
+  // system. Keyed by feature-local short name. The registry attaches
+  // featureName on aggregation, lifting RawTableEntry → RawTableDef.
+  readonly rawTables: Readonly<Record<string, RawTableEntry>>;
 };
 
 // --- Feature Registrar (the "r" object in defineFeature) ---
@@ -407,6 +442,19 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // nicht im Bootstrap. Escape-hatch für nicht-feature-bound Routes
   // bleibt runProdApp.extraRoutes.
   httpRoute(definition: HttpRouteDefinition): void;
+
+  // Declare a raw Drizzle table that bypasses the event-sourcing system.
+  // Reserved for legacy-import, read-only caches, write-only webhook
+  // payload buffers, or any other case where the event-sourced flow
+  // doesn't fit. The dev-server iterates these alongside r.entity()
+  // projections at boot so the table exists before the first query.
+  // Apps still declare the table in `drizzle/schema.ts` so drizzle-kit
+  // tracks migrations and schema-drift detection works automatically.
+  //
+  // The required `reason` string is the marker that justifies the bypass —
+  // a non-empty string is the contract. If you can't write a reason,
+  // declare data via `r.entity()` instead.
+  rawTable(name: string, table: PgTable, options: RawTableOptions): void;
 };
 
 // --- Registry (created from features) ---
@@ -506,6 +554,13 @@ export type Registry = {
   getProjectionsForSource(entityName: string): readonly ProjectionDefinition[];
   getAllProjections(): ReadonlyMap<string, ProjectionDefinition>;
 
+  // All r.rawTable() registrations across all features, keyed by
+  // feature-local short name. The dev-server iterates this alongside
+  // implicit projections at boot. Cross-feature uniqueness is enforced
+  // at registry-build — duplicate names from different features fail
+  // the boot, so callers can rely on a flat keyspace.
+  getAllRawTables(): ReadonlyMap<string, RawTableDef>;
+
   // Multi-stream projections registered via r.multiStreamProjection().
   // Keyed by qualified name. The server wires each into the event-dispatcher
   // as its own EventConsumer with a dedicated cursor.

package/src/engine/types/index.ts

@@ -56,6 +56,9 @@ export type {
   FeatureMetricType,
   FeatureRegistrar,
   MetricOptions,
+  RawTableDef,
+  RawTableEntry,
+  RawTableOptions,
   Registry,
   SecretKeyDefinition,
   SecretKeyHandle,

package/src/event-store/__tests__/upcaster.integration.ts

@@ -18,7 +18,13 @@ import { createTenantDb, type TenantDb } from "../../db/tenant-db";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import type { StoredEvent } from "../../event-store";
 import { rebuildProjection } from "../../pipeline";
-import { createEntityTable, createTestDb, pushTables, type TestDb, TestUsers } from "../../stack";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "../../stack";
 import { append, createEventsTable } from "../index";
 import { upcastStoredEvent } from "../upcaster";
 
@@ -102,11 +108,11 @@ const orderExecutor = createEventStoreExecutor(orderTable, orderEntity, {
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEntityTable(testDb.db, orderEntity, "upcast-order");
+  await unsafeCreateEntityTable(testDb.db, orderEntity, "upcast-order");
   await createEventsTable(testDb.db);
   const { createProjectionStateTable } = await import("../../pipeline");
   await createProjectionStateTable(testDb.db);
-  await pushTables(testDb.db, { upcastOrderSummary: orderSummaryTable });
+  await unsafePushTables(testDb.db, { upcastOrderSummary: orderSummaryTable });
   tdb = createTenantDb(testDb.db, admin.tenantId);
 });
 
@@ -298,7 +304,7 @@ describe("upcaster: async (Marten AsyncOnlyEventUpcaster — DB-Lookups)", () =>
       customerId: pgText("customer_id").primaryKey(),
       segment: pgText("segment").notNull(),
     });
-    await pushTables(testDb.db, { upcastAsyncCustomerSegments: customerSegments });
+    await unsafePushTables(testDb.db, { upcastAsyncCustomerSegments: customerSegments });
     await testDb.db
       .insert(customerSegments)
       .values({ customerId: "c-async-1", segment: "PREMIUM" });
@@ -308,7 +314,7 @@ describe("upcaster: async (Marten AsyncOnlyEventUpcaster — DB-Lookups)", () =>
       customerId: pgText("customer_id").notNull(),
       segment: pgText("segment").notNull(),
     });
-    await pushTables(testDb.db, { upcastAsyncSummary: asyncSummary });
+    await unsafePushTables(testDb.db, { upcastAsyncSummary: asyncSummary });
 
     // Feature with async upcaster v1 → v2: enrich payload with segment from DB.
     const asyncFeature = defineFeature("upcastasync", (r) => {

package/src/event-store/archive.ts

@@ -3,7 +3,7 @@ import type { DbConnection, DbRunner } from "../db/connection";
 import { instant, table as pgTable, text, uniqueIndex, uuid } from "../db/dialect";
 import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
-import { pushTables } from "../stack";
+import { unsafePushTables } from "../stack";
 
 // Marten-aligned stream archival. Archived streams become read-only: fresh
 // appendEvent on an archived aggregate throws, and loadAggregate returns
@@ -31,7 +31,7 @@ export const archivedStreamsTable = pgTable(
 export async function createArchivedStreamsTable(db: DbConnection): Promise<void> {
   // skip: table already exists — idempotent boot + test-setup call
   if (await tableExists(db, "public.kumiko_archived_streams")) return;
-  await pushTables(db, { kumikoArchivedStreams: archivedStreamsTable });
+  await unsafePushTables(db, { kumikoArchivedStreams: archivedStreamsTable });
 }
 
 export type ArchiveStreamArgs = {

package/src/event-store/events-schema.ts

@@ -11,7 +11,7 @@ import {
   uniqueIndex,
   uuid,
 } from "../db/dialect";
-import { pushTables } from "../stack";
+import { unsafePushTables } from "../stack";
 import { createArchivedStreamsTable } from "./archive";
 import { createSnapshotsTable } from "./snapshot";
 
@@ -83,7 +83,7 @@ export async function createEventsTable(db: DbConnection): Promise<void> {
   // skip: events table already exists — createEventsTable is called from both
   // setupTestStack and explicit test-setups, the guard keeps it idempotent.
   if (!(await tableExists(db, "public.kumiko_events"))) {
-    await pushTables(db, { kumikoEvents: eventsTable });
+    await unsafePushTables(db, { kumikoEvents: eventsTable });
   }
   await createArchivedStreamsTable(db);
   await createSnapshotsTable(db);

package/src/event-store/snapshot.ts

@@ -12,7 +12,7 @@ import {
 } from "../db/dialect";
 import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
-import { pushTables } from "../stack";
+import { unsafePushTables } from "../stack";
 import { isStreamArchived } from "./archive";
 import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
 
@@ -73,7 +73,7 @@ export const snapshotsTable = pgTable(
 export async function createSnapshotsTable(db: DbConnection): Promise<void> {
   // skip: table already exists — idempotent boot + test-setup call
   if (await tableExists(db, "public.kumiko_snapshots")) return;
-  await pushTables(db, { kumikoSnapshots: snapshotsTable });
+  await unsafePushTables(db, { kumikoSnapshots: snapshotsTable });
 }
 
 export type Snapshot<TState extends Record<string, unknown> = Record<string, unknown>> = {

package/src/event-store/upcaster-dead-letter.ts

@@ -15,7 +15,7 @@
 import { bigint, index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
 import type { DbConnection, DbRunner } from "../db/connection";
 import { tableExists } from "../db/schema-inspection";
-import { pushTables } from "../stack";
+import { unsafePushTables } from "../stack";
 import type { StoredEvent } from "./event-store";
 
 export const upcasterDeadLetterTable = pgTable(
@@ -50,7 +50,7 @@ export const upcasterDeadLetterTable = pgTable(
 export async function createUpcasterDeadLetterTable(db: DbConnection): Promise<void> {
   // skip: table already exists — bootstrap called from multiple paths
   if (await tableExists(db, "public.kumiko_upcaster_dead_letters")) return;
-  await pushTables(db, { kumikoUpcasterDeadLetters: upcasterDeadLetterTable });
+  await unsafePushTables(db, { kumikoUpcasterDeadLetters: upcasterDeadLetterTable });
 }
 
 // Writes a dead-letter row. Called by upcastStoredEvent when errorPolicy

package/src/files/__tests__/file-field-column.integration.ts

@@ -10,7 +10,7 @@
 import { sql } from "drizzle-orm";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { createEntity, createFileField, createImageField } from "../../engine";
-import { createEntityTable, createTestDb, pushTables, type TestDb } from "../../stack";
+import { createTestDb, type TestDb, unsafeCreateEntityTable, unsafePushTables } from "../../stack";
 import { generateId } from "../../utils";
 import { fileRefsTable } from "../file-ref-table";
 
@@ -28,8 +28,8 @@ let testDb: TestDb;
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await pushTables(testDb.db, { fileRefsTable });
-  await createEntityTable(testDb.db, documentEntity);
+  await unsafePushTables(testDb.db, { fileRefsTable });
+  await unsafeCreateEntityTable(testDb.db, documentEntity);
 });
 
 afterAll(async () => {
@@ -40,7 +40,7 @@ describe("file-field entity-column type", () => {
   test("`file` and `image` fields generate UUID columns (not integer)", async () => {
     // Pull the actual column type from information_schema. This is the
     // load-bearing assertion: the type emitted by drizzle-kit during
-    // `createEntityTable` must be `uuid`. A regression to `integer` would
+    // `unsafeCreateEntityTable` must be `uuid`. A regression to `integer` would
     // fail here even if higher-level code happened to still work through
     // implicit casts.
     const rows = await testDb.db.execute<{ column_name: string; data_type: string }>(sql`

package/src/files/__tests__/file-field-pipeline.integration.ts

@@ -30,11 +30,11 @@ import {
   defineFeature,
 } from "../../engine";
 import {
-  createEntityTable,
   createTestUser,
   setupTestStack,
   type TestStack,
   testTenantId,
+  unsafeCreateEntityTable,
 } from "../../stack";
 import { createLocalProvider } from "../local-provider";
 
@@ -74,7 +74,7 @@ beforeAll(async () => {
     features: [documentFeature],
     files: { storageProvider: createLocalProvider(storagePath) },
   });
-  await createEntityTable(stack.db, documentEntity);
+  await unsafeCreateEntityTable(stack.db, documentEntity);
 });
 
 afterAll(async () => {