@cosmicdrift/kumiko-framework 0.1.0 → 0.2.0

package/src/pipeline/projection-state.ts

@@ -2,7 +2,7 @@ import { sql } from "drizzle-orm";
 import type { DbConnection } from "../db/connection";
 import { bigint, index, instant, table as pgTable, text } from "../db/dialect";
 import { tableExists } from "../db/schema-inspection";
-import { pushTables } from "../stack";
+import { unsafePushTables } from "../stack";
 
 // Framework-level state for every registered projection. One row per qualified
 // projection name. Written by the rebuild machinery; read by the CLI + any
@@ -23,7 +23,7 @@ import { pushTables } from "../stack";
 // last_processed_event_id uses a raw DEFAULT 0 instead of .default(0n) because
 // drizzle-kit's JSON snapshot generator cannot serialise bigint literals —
 // `TypeError: Do not know how to serialize a BigInt` bubbles through
-// pushTables → generateMigration. `sql\`0\`` yields the same server-side
+// unsafePushTables → generateMigration. `sql\`0\`` yields the same server-side
 // default without ever putting a bigint in a generated-JSON path.
 export const projectionStateTable = pgTable(
   "kumiko_projections",
@@ -68,5 +68,5 @@ export const PROJECTION_STATUSES = [
 export async function createProjectionStateTable(db: DbConnection): Promise<void> {
   // skip: table already exists — bootstrap is called from multiple paths
   if (await tableExists(db, "public.kumiko_projections")) return;
-  await pushTables(db, { kumikoProjections: projectionStateTable });
+  await unsafePushTables(db, { kumikoProjections: projectionStateTable });
 }

package/src/stack/index.ts

@@ -15,13 +15,14 @@ export {
   type TestDb,
 } from "./db";
 export { createEventCollector, type EventCollector } from "./event-collector";
+export { pushEntityProjectionTables } from "./push-entity-projection-tables";
 export { createTestRedis, type TestRedis } from "./redis";
 export { createRequestHelper, type RequestHelper } from "./request-helper";
 export {
-  createEntityTable,
-  ensureEntityTable,
-  pushTables,
   resetEventStore,
+  unsafeCreateEntityTable,
+  unsafeEnsureEntityTable,
+  unsafePushTables,
 } from "./table-helpers";
 export { setupTestStack, type TestStack, type TestStackOptions } from "./test-stack";
 export {

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

@@ -0,0 +1,51 @@
+import { getTableName } from "drizzle-orm";
+import { tableExists } from "../db/schema-inspection";
+import type { Registry } from "../engine/types";
+import { unsafePushTables } from "./table-helpers";
+import type { TestStack } from "./test-stack";
+
+// biome-ignore lint/suspicious/noConsole: stack-internal status logging
+const logInfo = (msg: string): void => console.log(msg);
+
+/**
+ * Push all implicit-projection tables — one per `r.entity()` — that the
+ * registry knows about. setupTestStack already handles explicit
+ * projections, MSPs, and `r.rawTable()` declarations in its own loop;
+ * implicit projections are the missing piece for a fresh boot.
+ *
+ * Idempotent via `tableExists` so a persistent dev DB
+ * (`KUMIKO_DEV_DB_NAME`) reuses existing tables on reboot. One batched
+ * push at the end so drizzle-kit's `generateMigration` runs once over
+ * the whole missing set.
+ *
+ * Lives next to `setupTestStack` because both are stack-bootstrap
+ * helpers that legitimately speak the `unsafe*`-DDL layer; the
+ * Table-DDL Guard's stack/** allowlist is the single shared exemption
+ * site. Apps still declare data via `r.entity()` / `r.rawTable()` and
+ * never call this directly.
+ */
+export async function pushEntityProjectionTables(
+  stack: TestStack,
+  registry: Registry,
+): Promise<void> {
+  const seen = new Set<unknown>();
+  const missing: Record<string, unknown> = {};
+
+  for (const [projName, proj] of registry.getAllProjections()) {
+    if (!proj.isImplicit) continue;
+    if (seen.has(proj.table)) continue;
+    seen.add(proj.table);
+    // @cast-boundary drizzle-bridge — ProjectionTable + PgTable both round-trip
+    // through getTableName at runtime; the type system can't unify them.
+    const physical = getTableName(proj.table as Parameters<typeof getTableName>[0]);
+    if (await tableExists(stack.db, `public.${physical}`)) {
+      logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
+      continue;
+    }
+    missing[projName] = proj.table;
+  }
+
+  if (Object.keys(missing).length > 0) {
+    await unsafePushTables(stack.db, missing);
+  }
+}

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;
@@ -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";
     });