@cosmicdrift/kumiko-framework 0.1.0 → 0.2.1

package/src/stack/table-helpers.ts

@@ -7,49 +7,56 @@ import { buildDrizzleTable, toTableName } from "../db/table-builder";
 import type { TestStack } from "./test-stack";
 
 /**
- * Syncs a Drizzle table to the database via drizzle-kit migration.
- * No manual SQL — Drizzle generates CREATE/ALTER TABLE statements.
+ * 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 `ensureEntityTable` for idempotent
- * boot paths.
+ * the table is already there. Use `unsafeEnsureEntityTable` for the
+ * idempotent boot-path variant.
  */
-export async function createEntityTable(
+export async function unsafeCreateEntityTable(
   db: ReturnType<typeof drizzle>,
   entity: import("../engine/types").EntityDefinition,
   entityName?: string,
 ): Promise<void> {
   const table = buildDrizzleTable(entityName ?? "entity", entity);
-  await pushTables(db, { [entityName ?? "entity"]: table });
+  await unsafePushTables(db, { [entityName ?? "entity"]: table });
 }
 
 /**
- * Idempotent variant of `createEntityTable`: checks whether the entity's
+ * 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
+ * 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
- * `createEntityTable` instead, since they rely on fresh DBs.
+ * `unsafeCreateEntityTable` instead, since they rely on fresh DBs.
  */
-export async function ensureEntityTable(
+export async function unsafeEnsureEntityTable(
   db: ReturnType<typeof drizzle>,
   entity: import("../engine/types").EntityDefinition,
   entityName?: string,
 ): Promise<boolean> {
   const resolvedName = entity.table ?? toTableName(entityName ?? "entity");
   if (await tableExists(db, `public.${resolvedName}`)) return false;
-  await createEntityTable(db, entity, entityName);
+  await unsafeCreateEntityTable(db, entity, entityName);
   return true;
 }
 
 /**
- * Pushes Drizzle table definitions to the database.
+ * 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(...)`.
  *
  * @param prevTables - Previous table definitions (for ALTER TABLE scenarios).
  *                     If omitted, assumes empty DB (CREATE TABLE).
  */
-export async function pushTables(
+export async function unsafePushTables(
   db: ReturnType<typeof drizzle>,
   tables: Record<string, unknown>,
   prevTables?: Record<string, unknown>,

package/src/stack/test-stack.ts

@@ -17,7 +17,7 @@ import { createTestDb } from "./db";
 import { createEventCollector, type EventCollector } from "./event-collector";
 import { createTestRedis, type TestRedis } from "./redis";
 import { createRequestHelper, type RequestHelper } from "./request-helper";
-import { pushTables } from "./table-helpers";
+import { unsafePushTables } from "./table-helpers";
 
 export type TestStack = {
   app: Hono;
@@ -89,7 +89,7 @@ export type TestStackOptions = {
    *  GlobalFeatureToggleRuntime.effectiveFeatures for real DB-backed
    *  toggles, or a plain `() => new Set<string>(registry.features.keys())`
    *  to force a specific snapshot in a unit-style setup. */
-  effectiveFeatures?: () => ReadonlySet<string>;
+  effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
   /** Pin the underlying Postgres DB name instead of the default
    *  `kumiko_test_<8chars>`. Forwarded to createTestDb. Primary use
    *  case: dev servers that want persistent storage across restarts —
@@ -161,7 +161,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // stays off tenant test DBs that never touch files.
   if (options.files) {
     const { fileRefsTable } = await import("../files");
-    await pushTables(testDb.db, { fileRefsTable });
+    await unsafePushTables(testDb.db, { fileRefsTable });
   }
 
   // Projection tables: the executor writes into them in the same TX as the
@@ -189,9 +189,18 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       seenTables.add(msp.table);
       projectionTables[`msp_${mspName}`] = msp.table;
     }
+    // Raw tables declared via r.rawTable(). Same auto-push rule — the
+    // table needs to exist before the first reader query runs. The
+    // bypass is in the registration site (r.rawTable's `unsafe` cousins
+    // would target the same DDL), not in setting up the test DB.
+    for (const [rawName, raw] of Object.entries(feature.rawTables)) {
+      if (seenTables.has(raw.table)) continue;
+      seenTables.add(raw.table);
+      projectionTables[`raw_${rawName}`] = raw.table;
+    }
   }
   if (Object.keys(projectionTables).length > 0) {
-    // pushTables emits raw CREATE TABLE — fine for ephemeral test DBs but
+    // unsafePushTables emits raw CREATE TABLE — fine for ephemeral test DBs but
     // collides on re-boot against a persistent DB whose projection tables
     // were created during a previous run. Filter out the ones that already
     // exist; drizzle-kit's diff machinery would otherwise emit CREATE for
@@ -205,7 +214,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       missing[key] = tbl;
     }
     if (Object.keys(missing).length > 0) {
-      await pushTables(testDb.db, missing);
+      await unsafePushTables(testDb.db, missing);
     }
   }
 

package/src/testing/__tests__/ensure-entity-table.integration.ts

@@ -1,11 +1,16 @@
 import { sql } from "drizzle-orm";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import type { EntityDefinition } from "../../engine/types";
-import { createEntityTable, createTestDb, ensureEntityTable, type TestDb } from "../../stack";
-
-// ensureEntityTable ist die idempotente Variante von createEntityTable —
+import {
+  createTestDb,
+  type TestDb,
+  unsafeCreateEntityTable,
+  unsafeEnsureEntityTable,
+} from "../../stack";
+
+// unsafeEnsureEntityTable ist die idempotente Variante von unsafeCreateEntityTable —
 // existiert wegen des dev-server-Boot-Pfads (persistente DB, Table von
-// letztem Run). createEntityTable bleibt strict, damit Tests ein
+// letztem Run). unsafeCreateEntityTable bleibt strict, damit Tests ein
 // falsches Schema nicht stillschweigend akzeptieren.
 
 const tenantEntity: EntityDefinition = {
@@ -25,9 +30,9 @@ afterAll(async () => {
   await db.cleanup();
 });
 
-describe("ensureEntityTable", () => {
+describe("unsafeEnsureEntityTable", () => {
   test("legt die Tabelle beim ersten Aufruf an (returnt true)", async () => {
-    const created = await ensureEntityTable(db.db, tenantEntity, "probe");
+    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`,
@@ -36,17 +41,17 @@ describe("ensureEntityTable", () => {
   });
 
   test("ist beim zweiten Aufruf ein No-Op (returnt false, kein Fehler)", async () => {
-    const created = await ensureEntityTable(db.db, tenantEntity, "probe");
+    const created = await unsafeEnsureEntityTable(db.db, tenantEntity, "probe");
     expect(created).toBe(false);
   });
 
-  test("createEntityTable bleibt strict — wirft bei existierender Tabelle", async () => {
-    // Gleiche Entity zweimal via createEntityTable → postgres 42P07
+  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 ensureEntityTable nicht versehentlich das strict-Verhalten
+    // dass unsafeEnsureEntityTable nicht versehentlich das strict-Verhalten
     // verändert.
-    await expect(createEntityTable(db.db, tenantEntity, "probe")).rejects.toSatisfy((err) => {
+    await expect(unsafeCreateEntityTable(db.db, tenantEntity, "probe")).rejects.toSatisfy((err) => {
       const cause = (err as { cause?: { code?: string } }).cause;
       return cause?.code === "42P07";
     });