@cosmicdrift/kumiko-framework 0.1.0 → 0.2.1

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -9,6 +9,7 @@ import {
   type PreSaveHookFn,
   type SaveContext,
 } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
 import { buildEventId, createLifecycleHooks, type SystemHooks } from "../lifecycle-pipeline";
 
 function makeRegistry(hooks?: { preSave?: PreSaveHookFn[]; postSave?: PostSaveHookFn[] }) {
@@ -400,6 +401,105 @@ describe("runPostSave phase routing", () => {
   });
 });
 
+// =============================================================================
+// Sprint 8a: per-tenant entity-hook filter
+// =============================================================================
+//
+// Setup: Feature A owns the entity. Feature B registers an entity-hook
+// on A's entity (cross-feature pattern). lifecycle-pipeline must filter
+// B's hook based on the active tenant's effectiveFeatures-set.
+
+describe("Sprint 8a: per-tenant entity-hook filter", () => {
+  function setupTwoFeatures() {
+    const calls: Array<{ tenant: string }> = [];
+
+    const featureA = defineFeature("feat-a", (r) => {
+      r.entity("widget", createEntity({ table: "Widgets", fields: { name: createTextField() } }));
+      r.writeHandler(
+        "widget:create",
+        z.object({ name: z.string() }),
+        async () => ({ isSuccess: true as const, data: null }),
+        { access: { openToAll: true } },
+      );
+    });
+
+    const featureB = defineFeature("feat-b", (r) => {
+      r.entityHook("postSave", "widget", async (_result, ctx) => {
+        calls.push({ tenant: ctx._tenantId ?? "no-tenant" });
+      });
+    });
+
+    return { registry: createRegistry([featureA, featureB]), calls };
+  }
+
+  const tenantA = "00000000-0000-4000-8000-0000000000a1" as TenantId;
+  const tenantB = "00000000-0000-4000-8000-0000000000b2" as TenantId;
+
+  const baseSaveCtx: SaveContext = {
+    kind: "save",
+    id: 1,
+    data: { name: "x", tenantId: tenantA },
+    changes: { name: "x" },
+    previous: {},
+    isNew: true,
+    entityName: "widget",
+  };
+
+  test("Tenant A (feat-b enabled) → hook fires; Tenant B (feat-b disabled) → hook skipped", async () => {
+    const { registry, calls } = setupTwoFeatures();
+    const pipeline = createLifecycleHooks(registry);
+    const effectiveFeatures = (tenantId: TenantId) =>
+      tenantId === tenantA ? new Set(["feat-a", "feat-b"]) : new Set(["feat-a"]);
+
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {
+      _tenantId: tenantA,
+      effectiveFeatures,
+    });
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {
+      _tenantId: tenantB,
+      effectiveFeatures,
+    });
+
+    expect(calls).toEqual([{ tenant: tenantA }]);
+  });
+
+  test("ctx without _tenantId → hook fires (legacy back-compat: undefined = skip filter)", async () => {
+    // System-jobs / boot-time pipeline-calls have no user → no _tenantId.
+    // currentEffectiveFeatures returns undefined; registry filterByPhase
+    // treats undefined as "skip filter" → all hooks fire (back-compat).
+    const { registry, calls } = setupTwoFeatures();
+    const pipeline = createLifecycleHooks(registry);
+
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {});
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.tenant).toBe("no-tenant");
+  });
+
+  test("effectiveFeatures wird PRO call konsultiert (kein staler Cache zwischen runPostSave-aufrufen)", async () => {
+    // Pin: currentEffectiveFeatures-helper ruft effectiveFeatures jedes
+    // mal neu — keine pipeline-internal Memoization. Toggle-flips müssen
+    // sofort greifen, nicht erst nach pipeline-restart.
+    const { registry, calls } = setupTwoFeatures();
+    const pipeline = createLifecycleHooks(registry);
+    const enabled = new Set<string>(["feat-a", "feat-b"]);
+    const effectiveFeatures = (_tenantId: TenantId) => enabled;
+
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {
+      _tenantId: tenantA,
+      effectiveFeatures,
+    });
+    enabled.delete("feat-b");
+    await pipeline.runPostSave("feat-a:write:widget:create", baseSaveCtx, {
+      _tenantId: tenantA,
+      effectiveFeatures,
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.tenant).toBe(tenantA);
+  });
+});
+
 describe("buildEventId — dedup key construction", () => {
   test("includes handler, id, version and phase when payload is complete", () => {
     const payload = { id: 42, data: { version: 3 } };

package/src/pipeline/__tests__/load-aggregate-query.integration.ts

@@ -13,11 +13,11 @@ import { buildDrizzleTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import { append, loadAggregate as loadAggregateRaw } from "../../event-store";
 import {
-  createEntityTable,
   resetEventStore,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../../stack";
 
 // --- Fixture entity ---
@@ -131,7 +131,7 @@ const admin = TestUsers.admin;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [asOfFeature], systemHooks: [] });
-  await createEntityTable(stack.db, invoiceEntity, "asof-invoice");
+  await unsafeCreateEntityTable(stack.db, invoiceEntity, "asof-invoice");
 });
 
 afterAll(async () => {

package/src/pipeline/__tests__/msp-error-mode.integration.ts

@@ -15,11 +15,11 @@ import { createTenantDb, type TenantDb } from "../../db/tenant-db";
 import { defineFeature } from "../../engine";
 import { getConsumerState } from "../../pipeline";
 import {
-  createEntityTable,
   resetEventStore,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../../stack";
 import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
 
@@ -80,7 +80,7 @@ beforeAll(async () => {
     features: [z2Feature],
     systemHooks: [],
   });
-  await createEntityTable(stack.db, sharedWidgetEntity, "widget");
+  await unsafeCreateEntityTable(stack.db, sharedWidgetEntity, "widget");
   tdb = createTenantDb(stack.db, admin.tenantId);
 });
 

package/src/pipeline/__tests__/msp-multi-hop.integration.ts

@@ -17,11 +17,11 @@ import { buildDrizzleTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import { eventsTable } from "../../event-store";
 import {
-  createEntityTable,
   resetEventStore,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../../stack";
 
 // --- Feature ---
@@ -109,7 +109,7 @@ const admin = TestUsers.admin;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [mmhFeature], systemHooks: [] });
-  await createEntityTable(stack.db, orderEntity, "mmh-order");
+  await unsafeCreateEntityTable(stack.db, orderEntity, "mmh-order");
 });
 
 afterAll(async () => {

package/src/pipeline/__tests__/msp-rebuild.integration.ts

@@ -28,11 +28,11 @@ import {
   rebuildMultiStreamProjection,
 } from "../../pipeline";
 import {
-  createEntityTable,
   resetEventStore,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../../stack";
 
 // --- Fixtures: two aggregates feeding one MSP + two cornered MSPs ---
@@ -211,8 +211,8 @@ beforeAll(async () => {
     features: [feature],
     systemHooks: [],
   });
-  await createEntityTable(stack.db, invoiceEntity, "msp-reb-invoice");
-  await createEntityTable(stack.db, paymentEntity, "msp-reb-payment");
+  await unsafeCreateEntityTable(stack.db, invoiceEntity, "msp-reb-invoice");
+  await unsafeCreateEntityTable(stack.db, paymentEntity, "msp-reb-payment");
 });
 
 afterAll(async () => {

package/src/pipeline/__tests__/multi-stream-projection.integration.ts

@@ -14,12 +14,12 @@ import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { buildDrizzleTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import {
-  createEntityTable,
   createTestUser,
   resetEventStore,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../../stack";
 
 // --- Two aggregate types that feed one MSP ---
@@ -162,8 +162,8 @@ const admin = TestUsers.admin;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [mspFeature], systemHooks: [] });
-  await createEntityTable(stack.db, shipmentEntity, "msp-shipment");
-  await createEntityTable(stack.db, refundEntity, "msp-refund");
+  await unsafeCreateEntityTable(stack.db, shipmentEntity, "msp-shipment");
+  await unsafeCreateEntityTable(stack.db, refundEntity, "msp-refund");
 });
 
 afterAll(async () => {

package/src/pipeline/__tests__/perf-rebuild.integration.ts

@@ -24,7 +24,7 @@ import { createEntity, createRegistry, createTextField, defineFeature } from "..
 import type { ProjectionDefinition } from "../../engine/types";
 import { createEventsTable } from "../../event-store";
 import { createProjectionStateTable, rebuildProjection } from "../../pipeline";
-import { createTestDb, pushTables, type TestDb, TestUsers } from "../../stack";
+import { createTestDb, type TestDb, TestUsers, unsafePushTables } from "../../stack";
 import { generateId as uuid } from "../../utils";
 
 // Counter projection: every task.created bumps a counter, every
@@ -77,7 +77,7 @@ beforeAll(async () => {
   testDb = await createTestDb();
   await createEventsTable(testDb.db);
   await createProjectionStateTable(testDb.db);
-  await pushTables(testDb.db, { perf_rebuild_task_count: taskCountTable });
+  await unsafePushTables(testDb.db, { perf_rebuild_task_count: taskCountTable });
 });
 
 afterAll(async () => {

package/src/pipeline/__tests__/projection-rebuild.integration.ts

@@ -36,7 +36,13 @@ import {
   listProjectionsWithState,
   rebuildProjection,
 } from "../../pipeline";
-import { createEntityTable, createTestDb, pushTables, type TestDb, TestUsers } from "../../stack";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "../../stack";
 
 // --- Test fixtures ---
 
@@ -103,10 +109,10 @@ const executor = createEventStoreExecutor(itemTable, itemEntity, { entityName: "
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEntityTable(testDb.db, itemEntity, "rebuild-item");
+  await unsafeCreateEntityTable(testDb.db, itemEntity, "rebuild-item");
   await createEventsTable(testDb.db);
   await createProjectionStateTable(testDb.db);
-  await pushTables(testDb.db, { rebuildItemsPerGroup: itemsPerGroupTable });
+  await unsafePushTables(testDb.db, { rebuildItemsPerGroup: itemsPerGroupTable });
   tdb = createTenantDb(testDb.db, admin.tenantId);
 });
 

package/src/pipeline/__tests__/query-projection.integration.ts

@@ -15,11 +15,11 @@ import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { buildDrizzleTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import {
-  createEntityTable,
   resetEventStore,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
 } from "../../stack";
 
 const widgetEntity = createEntity({
@@ -121,7 +121,7 @@ const otherTenantAdmin = {
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [qpFeature], systemHooks: [] });
-  await createEntityTable(stack.db, widgetEntity, "qp-widget");
+  await unsafeCreateEntityTable(stack.db, widgetEntity, "qp-widget");
 });
 
 afterAll(async () => {

package/src/pipeline/dispatcher.ts

@@ -7,6 +7,7 @@ import { hasAccess } from "../engine/access";
 import { checkWriteFieldRoles, filterReadFields } from "../engine/field-access";
 import { parseQn, qn } from "../engine/qualified-name";
 import { defineTransitions, guardTransition } from "../engine/state-machine";
+import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
 import type {
   AggregateStreamHandle,
   AppContext,
@@ -25,6 +26,7 @@ import type {
   WriteResult,
 } from "../engine/types";
 import { HookPhases } from "../engine/types";
+import type { TenantId } from "../engine/types/identifiers";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
 // HTTP-layer stubs) — dispatch consumes these, grouping the type-surface
@@ -318,13 +320,26 @@ export type DispatcherOptions = {
   idempotency?: IdempotencyGuard;
   lifecycle?: LifecycleHooks;
   jobRunner?: JobRunnerRef;
-  // Resolves the current effective-feature set — the dispatcher uses it
-  // to gate calls to handlers of disabled features (403 feature_disabled)
+  // Resolves the effective-feature set per tenant — the dispatcher uses
+  // it to gate calls to handlers of disabled features (403 feature_disabled)
   // and to populate ctx.hasFeature. Absent = all features treated as
-  // always-on (no feature-toggles feature loaded). The resolver must be
-  // fast and synchronous per call; implementations cache a DB snapshot
-  // under the hood and refresh on toggle events.
-  effectiveFeatures?: () => ReadonlySet<string>;
+  // always-on (no feature-toggles or tier-engine feature loaded). The
+  // resolver must be fast and synchronous per call; implementations cache
+  // tenant-keyed sets and refresh on tier-assignment / toggle events.
+  //
+  // **System-context convention:** when called with SYSTEM_TENANT_ID, the
+  // resolver should return the union/superset of all tier-features. Two
+  // contexts call with this sentinel:
+  //   1. event-dispatcher async-pass (consumers tagged with feature X
+  //      should not silently skip events from a tenant where X is off —
+  //      events are immutable, async work runs through).
+  //   2. operator-tooling queries (e.g. feature-toggles:registered) where
+  //      a SystemAdmin needs to see platform-truth, not their own
+  //      tier-cut.
+  // Returning a non-superset for SYSTEM_TENANT_ID will cause silent
+  // event-skips and a confusing operator-UI — the framework cannot
+  // enforce this contract, but the recipe-test pins the convention.
+  effectiveFeatures?: EffectiveFeaturesResolver;
 };
 
 type HandlerType = string | HandlerRef;
@@ -729,11 +744,14 @@ export function createDispatcher(
       // dispatcher.resolveAuthClaims) cannot drift.
       resolveAuthClaims: (claimsUser: SessionUser) => resolveAuthClaimsFn(claimsUser),
 
-      // Feature-effective check for in-handler opt-in logic. When the
-      // feature-toggles feature isn't wired (no effectiveFeatures callback),
-      // always returns true — apps without toggles treat all features on.
+      // Feature-effective check for in-handler opt-in logic. Scope:
+      // **current user's tenant** — for cross-tenant lookups (rare,
+      // SysAdmin operations) read effectiveFeatures(otherTenantId) directly.
+      // When the feature-toggles or tier-engine feature isn't wired (no
+      // effectiveFeatures callback), always returns true — apps without
+      // tier-cuts treat all features on.
       hasFeature: (featureName: string): boolean =>
-        effectiveFeatures ? effectiveFeatures().has(featureName) : true,
+        effectiveFeatures ? effectiveFeatures(user.tenantId).has(featureName) : true,
     };
 
     // Registry is always the dispatcher's registry — injecting it here lets
@@ -771,6 +789,7 @@ export function createDispatcher(
       // event.user-Wert; Identity-Switches nutzen weiterhin queryAs/writeAs.
       user,
       _userId: user.id,
+      _tenantId: user.tenantId,
       _handlerType: type,
       ...bridge,
     } as HandlerContext;
@@ -860,6 +879,7 @@ export function createDispatcher(
   // pass-through in that common case.
   function checkFeatureEnabled(
     qualifiedHandler: string,
+    tenantId: TenantId,
   ): import("../errors").FeatureDisabledError | undefined {
     if (!effectiveFeatures) return undefined;
     const owner = registry.getHandlerFeature(qualifiedHandler);
@@ -867,13 +887,13 @@ export function createDispatcher(
     // happen for registry-built handlers, but guards against edge-case
     // runtime injections.
     if (!owner) return undefined;
-    const set = effectiveFeatures();
+    const set = effectiveFeatures(tenantId);
     if (set.has(owner)) return undefined;
     return new FeatureDisabledError(owner, qualifiedHandler);
   }
 
-  function ensureFeatureEnabled(qualifiedHandler: string): void {
-    const err = checkFeatureEnabled(qualifiedHandler);
+  function ensureFeatureEnabled(qualifiedHandler: string, tenantId: TenantId): void {
+    const err = checkFeatureEnabled(qualifiedHandler, tenantId);
     if (err) throw err;
   }
 
@@ -935,7 +955,7 @@ export function createDispatcher(
     // disabled feature must not consume the rate-limit quota — the call
     // never happened from the feature's perspective. Order is: lookup →
     // feature-gate → rate-limit → access → validation → handler.
-    ensureFeatureEnabled(type);
+    ensureFeatureEnabled(type, user.tenantId);
 
     // Rate-limit gate runs BEFORE access-check on purpose: anonymous /
     // unauthorized callers must hit the cap too (otherwise the limit
@@ -1173,7 +1193,7 @@ export function createDispatcher(
 
     // Feature-toggle gate: disabled handlers must short-circuit before any
     // rate-limit/access/validation work — see executeQueryInner comment.
-    const disabledErr = checkFeatureEnabled(type);
+    const disabledErr = checkFeatureEnabled(type, user.tenantId);
     if (disabledErr) return writeFailure(disabledErr);
 
     // Rate-limit gate before access (same reasoning as in executeQueryInner).

package/src/pipeline/event-consumer-state.ts

@@ -2,7 +2,7 @@ import { sql } from "drizzle-orm";
 import type { DbConnection } from "../db/connection";
 import { bigint, index, instant, integer, table as pgTable, primaryKey, text } from "../db/dialect";
 import { tableExists } from "../db/schema-inspection";
-import { pushTables } from "../stack";
+import { unsafePushTables } from "../stack";
 
 // Reserved sentinel used in the instance_id column for consumers whose
 // delivery is "shared" — i.e. one cursor across all dispatcher instances
@@ -104,5 +104,5 @@ export const CONSUMER_STATUSES = [
 export async function createEventConsumerStateTable(db: DbConnection): Promise<void> {
   // skip: table already exists — bootstrap is called from multiple paths
   if (await tableExists(db, "public.kumiko_event_consumers")) return;
-  await pushTables(db, { kumikoEventConsumers: eventConsumerStateTable });
+  await unsafePushTables(db, { kumikoEventConsumers: eventConsumerStateTable });
 }

package/src/pipeline/event-dispatcher.ts

@@ -2,6 +2,7 @@ import { and, asc, eq, gt, sql } from "drizzle-orm";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbTx, PgClient } from "../db/connection";
 import type { AppContext } from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import {
   EVENTS_PUBSUB_CHANNEL,
   eventsTable,
@@ -487,7 +488,15 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
     // Feature-toggle snapshot taken once per pass (not per consumer): all
     // consumers see the same disabled-set even if an operator flips a
     // toggle mid-pass, so "this event batch" decisions stay consistent.
-    const effective = context.effectiveFeatures?.();
+    //
+    // Sprint-8a tier-composition: per-tenant resolver per-pass-konsultiert
+    // mit SYSTEM_TENANT_ID. Async-events sind tier-agnostic — wenn ein
+    // Tenant downgrade'd, sollen seine queued events trotzdem verarbeitet
+    // werden (events sind immutable, projection ist eventually-consistent).
+    // Tier-cuts wirken request-time im sync-dispatcher + lifecycle-pipeline,
+    // nicht im async-replay. App-level resolver entscheidet was er bei
+    // SYSTEM_TENANT_ID returnt (typisch: union-of-all-tier-features).
+    const effective = context.effectiveFeatures?.(SYSTEM_TENANT_ID);
 
     // Seriell pro consumer. Parallelisierung wäre möglich (je eigene TX), aber
     // das einfache Modell reicht für v1 — jeder consumer hat geringe

package/src/pipeline/lifecycle-pipeline.ts

@@ -20,6 +20,24 @@ function resolveTracer(context: AppContext): Tracer {
   return context.tracer ?? getFallbackTracer();
 }
 
+/**
+ * Resolve effective-feature set for the active context's tenant.
+ *
+ * `_tenantId` wird vom dispatcher beim HandlerContext-Bau aus `user.tenantId`
+ * gespiegelt. Bei legacy-callsites ohne user (system-jobs, boot-time
+ * pipeline) ist es undefined — `effectiveFeatures(undefined)` wäre type-
+ * unsafe; wir return undefined und behandeln das als "all features on"
+ * (registry filterhooks akzeptieren undefined als "skip filter").
+ *
+ * Single source — die 4 lifecycle-hook-callsites (preSave, postSave,
+ * preDelete, postDelete) rufen alle hier durch, damit der tenant-
+ * scoping-Pfad nie inkonsistent ist.
+ */
+function currentEffectiveFeatures(context: AppContext): ReadonlySet<string> | undefined {
+  if (context._tenantId === undefined) return undefined;
+  return context.effectiveFeatures?.(context._tenantId);
+}
+
 export type SystemHookDef<TFn> = {
   readonly name: string;
   readonly priority: number;
@@ -250,7 +268,7 @@ export function createLifecycleHooks(
     async runPreSave(handlerName, changes, previous, isNew, context) {
       let currentChanges = changes;
       const hookContext = { ...context, previous, isNew };
-      const eff = context.effectiveFeatures?.();
+      const eff = currentEffectiveFeatures(context);
 
       for (const hook of registry.getPreSaveHooks(handlerName, eff)) {
         currentChanges = await hook(currentChanges, hookContext);
@@ -266,7 +284,7 @@ export function createLifecycleHooks(
     },
 
     async runPostSave(handlerName, result, context, phase = HookPhases.afterCommit) {
-      const eff = context.effectiveFeatures?.();
+      const eff = currentEffectiveFeatures(context);
       await runHookSet({
         handlerName,
         payload: result,
@@ -283,7 +301,7 @@ export function createLifecycleHooks(
     async runPreDelete(handlerName, payload, context) {
       // preDelete hooks run in-transaction and throw on failure (not best-effort).
       // They're used to check invariants before delete, so phase filter is "inTransaction".
-      const eff = context.effectiveFeatures?.();
+      const eff = currentEffectiveFeatures(context);
       for (const hook of registry.getPreDeleteHooks(handlerName, HookPhases.inTransaction, eff)) {
         await hook(payload, context);
       }
@@ -308,7 +326,7 @@ export function createLifecycleHooks(
     },
 
     async runPostDelete(handlerName, payload, context, phase = HookPhases.afterCommit) {
-      const eff = context.effectiveFeatures?.();
+      const eff = currentEffectiveFeatures(context);
       await runHookSet({
         handlerName,
         payload,

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);
+  }
+}