@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/pipeline/__tests__/escape-hatch-report.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test";
+import type { EscapeHatchUseEvent } from "../../engine/types";
+import type { Logger } from "../../logging/types";
+import { testTenantId } from "../../stack";
+import {
+  createEscapeHatchReportWindow,
+  ESCAPE_HATCH_USED_SIGNAL,
+  reportEscapeHatchUse,
+} from "../escape-hatch-report";
+
+const tenantId = testTenantId(1);
+
+function recordingLogger(): Logger & {
+  readonly warnCalls: Array<{ msg: string; data?: Record<string, unknown> }>;
+  readonly errorCalls: Array<{ msg: string; data?: Record<string, unknown> }>;
+} {
+  const warnCalls: Array<{ msg: string; data?: Record<string, unknown> }> = [];
+  const errorCalls: Array<{ msg: string; data?: Record<string, unknown> }> = [];
+  const logger: Logger & {
+    warnCalls: typeof warnCalls;
+    errorCalls: typeof errorCalls;
+  } = {
+    warnCalls,
+    errorCalls,
+    info() {},
+    debug() {},
+    warn(msg, data) {
+      warnCalls.push({ msg, data });
+    },
+    error(msg, data) {
+      errorCalls.push({ msg, data });
+    },
+    child() {
+      return logger;
+    },
+  };
+  return logger;
+}
+
+const baseEvent: EscapeHatchUseEvent = {
+  handler: 'write "widgets:write:create"',
+  kind: "unsafe-raw",
+  reason: "legacy migration read",
+  tenantId,
+  actor: "user-1",
+};
+
+describe("createEscapeHatchReportWindow", () => {
+  test("dedups an identical key within the window", () => {
+    const window = createEscapeHatchReportWindow({ windowMs: 1000 });
+    expect(window.shouldReport("k1", 0)).toBe(true);
+    expect(window.shouldReport("k1", 500)).toBe(false);
+    expect(window.shouldReport("k1", 999)).toBe(false);
+  });
+
+  test("reports again after the window expires", () => {
+    const window = createEscapeHatchReportWindow({ windowMs: 1000 });
+    expect(window.shouldReport("k1", 0)).toBe(true);
+    expect(window.shouldReport("k1", 1000)).toBe(true);
+  });
+
+  test("evicts the oldest entry beyond maxEntries", () => {
+    const window = createEscapeHatchReportWindow({ windowMs: 1000, maxEntries: 2 });
+    expect(window.shouldReport("k1", 0)).toBe(true);
+    expect(window.shouldReport("k2", 0)).toBe(true);
+    // k3 pushes the cache past its cap — k1 (oldest) is evicted to make room.
+    expect(window.shouldReport("k3", 0)).toBe(true);
+    // k1 was evicted, so it is treated as new and reports again.
+    expect(window.shouldReport("k1", 1)).toBe(true);
+    // k3 is still within its window and was not evicted.
+    expect(window.shouldReport("k3", 1)).toBe(false);
+  });
+});
+
+describe("reportEscapeHatchUse", () => {
+  test("sink present — calls the sink with the exact event and does not log.warn", () => {
+    const calls: EscapeHatchUseEvent[] = [];
+    const sink = async (event: EscapeHatchUseEvent) => {
+      calls.push(event);
+    };
+    const log = recordingLogger();
+
+    reportEscapeHatchUse(baseEvent, { sink, log });
+
+    expect(calls).toEqual([baseEvent]);
+    expect(log.warnCalls).toEqual([]);
+  });
+
+  test("no sink — log.warn called once with ESCAPE_HATCH_USED_SIGNAL and exact fields", () => {
+    const log = recordingLogger();
+
+    reportEscapeHatchUse(baseEvent, { log });
+
+    expect(log.warnCalls.length).toBe(1);
+    expect(log.warnCalls[0]?.msg).toBe(ESCAPE_HATCH_USED_SIGNAL);
+    expect(log.warnCalls[0]?.data).toEqual({
+      handler: baseEvent.handler,
+      kind: baseEvent.kind,
+      reason: baseEvent.reason,
+      tenantId: baseEvent.tenantId,
+      actor: baseEvent.actor,
+    });
+  });
+
+  test("no sink, event has a target — target fields are included", () => {
+    const log = recordingLogger();
+    const eventWithTarget: EscapeHatchUseEvent = {
+      ...baseEvent,
+      kind: "identity-switch",
+      target: { id: "user-2", tenantId },
+    };
+
+    reportEscapeHatchUse(eventWithTarget, { log });
+
+    expect(log.warnCalls[0]?.data).toEqual({
+      handler: eventWithTarget.handler,
+      kind: eventWithTarget.kind,
+      reason: eventWithTarget.reason,
+      tenantId: eventWithTarget.tenantId,
+      actor: eventWithTarget.actor,
+      targetId: "user-2",
+      targetTenantId: tenantId,
+    });
+  });
+
+  test("sink rejection — logs via log.error", async () => {
+    const log = recordingLogger();
+    const sink = async () => {
+      throw new Error("sink boom");
+    };
+
+    reportEscapeHatchUse(baseEvent, { sink, log });
+    // The sink runs async — let its rejection settle before asserting.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(log.errorCalls.length).toBe(1);
+    expect(log.errorCalls[0]?.msg).toBe(`${ESCAPE_HATCH_USED_SIGNAL}: audit sink failed`);
+    expect(log.errorCalls[0]?.data).toEqual({
+      handler: baseEvent.handler,
+      kind: baseEvent.kind,
+      reason: baseEvent.reason,
+      tenantId: baseEvent.tenantId,
+      actor: baseEvent.actor,
+      error: "sink boom",
+    });
+    expect(log.warnCalls).toEqual([]);
+  });
+});

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

@@ -24,7 +24,7 @@ function makeRegistry(hooks?: { preSave?: PreSaveHookFn[]; postSave?: PostSaveHo
     );
     // Dummy handler so hook targets resolve (boot validation requires it)
     r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
     if (hooks?.preSave) {
       for (const h of hooks.preSave) r.hook("preSave", "user", h);
@@ -296,7 +296,7 @@ describe("runPostSave phase routing", () => {
     const feature = defineFeature("phases", (r) => {
       r.entity("user", createEntity({ table: "Users", fields: {} }));
       r.writeHandler("user", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook(
         "postSave",
@@ -325,7 +325,7 @@ describe("runPostSave phase routing", () => {
     const feature = defineFeature("phases", (r) => {
       r.entity("user", createEntity({ table: "Users", fields: {} }));
       r.writeHandler("user", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook(
         "postSave",
@@ -351,7 +351,7 @@ describe("runPostSave phase routing", () => {
       const feature = defineFeature("phases", (r) => {
         r.entity("user", createEntity({ table: "Users", fields: {} }));
         r.writeHandler("user", z.object({}), async () => ({ isSuccess: true, data: null }), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.hook("postSave", "user", async () => {
           throw new Error("afterCommit-boom");
@@ -378,7 +378,7 @@ describe("runPostSave phase routing", () => {
     const feature = defineFeature("phases", (r) => {
       r.entity("user", createEntity({ table: "Users", fields: {} }));
       r.writeHandler("user", z.object({}), async () => ({ isSuccess: true, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const registry = createRegistry([feature]);
@@ -439,7 +439,7 @@ describe("Sprint 8a: per-tenant entity-hook filter", () => {
         "widget:create",
         z.object({ name: z.string() }),
         async () => ({ isSuccess: true as const, data: null }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
 
@@ -570,7 +570,7 @@ describe("runPreDelete", () => {
         }),
       );
       r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook("preDelete", "user", async () => {
         calls.push("handler");
@@ -606,7 +606,7 @@ describe("runPreDelete", () => {
         }),
       );
       r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook("preDelete", "user", async () => {
         throw new Error("blocked-delete");
@@ -652,7 +652,7 @@ describe("runPostDelete", () => {
         }),
       );
       r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook("postDelete", "user", async () => {
         calls.push("feature");
@@ -685,7 +685,7 @@ describe("runPostDelete", () => {
         }),
       );
       r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook(
         "postDelete",

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

@@ -133,7 +133,7 @@ const asOfFeature = defineFeature("asoftest", (r) => {
       }
       return state;
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

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

@@ -364,4 +364,32 @@ describe("rebuildMultiStreamProjection — guard rails", () => {
     expect(state?.status).toBe("dead");
     expect(state?.lastError).toMatch(/appendEvent/);
   });
+
+  test("aborts when the live table has RLS enabled — data survives (fw#2907)", async () => {
+    const erin = "00000000-0000-4000-8000-000000000e05";
+    await updateMany(
+      stack.db,
+      eventConsumerStateTable,
+      { status: "disabled", updatedAt: sql`now()` },
+      { name: SAGA_MSP },
+    );
+    await stack.http.writeOk("mspreb:write:invoice:bill", { customer: erin, cents: 20_00 }, admin);
+    await runFullDispatcher();
+
+    await asRawClient(stack.db).unsafe(
+      `ALTER TABLE "read_mspreb_balance" ENABLE ROW LEVEL SECURITY`,
+    );
+    try {
+      await expect(
+        rebuildMultiStreamProjection(BALANCE_MSP, { db: stack.db, registry: stack.registry }),
+      ).rejects.toThrow(/row level security/);
+
+      const [row] = await selectMany(stack.db, balanceTable, { customer: erin });
+      expect(row).toMatchObject({ invoicesCents: 20_00 });
+    } finally {
+      await asRawClient(stack.db).unsafe(
+        `ALTER TABLE "read_mspreb_balance" DISABLE ROW LEVEL SECURITY`,
+      );
+    }
+  });
 });

package/src/pipeline/__tests__/post-query-hook.integration.test.ts

@@ -58,7 +58,7 @@ const postQueryFeature = defineFeature("postquerytest", (r) => {
       ],
       nextCursor: null,
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   // Handler-keyed: fires only for widget:list
@@ -91,13 +91,13 @@ const duplicateRowHook: PostQueryHookFn = async ({ rows }) => ({ rows: [...rows,
 const singleObjectFeature = defineFeature("singleobjtest", (r) => {
   const gadget = r.entity("gadget", gadgetEntity);
   r.queryHandler("gadget:get", z.object({}), async () => ({ id: "g1", name: "Gadget" }), {
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
   r.hook("postQuery", { allOf: gadget }, dropRowHook);
 
   const gizmo = r.entity("gizmo", gizmoEntity);
   r.queryHandler("gizmo:get", z.object({}), async () => ({ id: "z1", name: "Gizmo" }), {
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
   r.hook("postQuery", { allOf: gizmo }, duplicateRowHook);
 });

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

@@ -938,3 +938,97 @@ describe("rebuildProjection — stale-registry column fence (#835)", () => {
     expect(await getCount(group)).toBe(1);
   });
 });
+
+describe("rebuildProjection — row level security guard (#2907)", () => {
+  test("aborts when the live table has RLS enabled — data and RLS survive", async () => {
+    const group = "00000000-0000-4000-8000-000000000051";
+    await appendCreatedEvent(group, "item1");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(1);
+
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" ENABLE ROW LEVEL SECURITY`);
+    try {
+      await expect(
+        rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry }),
+      ).rejects.toThrow(/read_rebuild_items_per_group.*has row level security/);
+
+      // Live table untouched: row count AND the RLS flag itself survive.
+      expect(await getCount(group)).toBe(1);
+      const [pgClass] = await raw.unsafe<{ relrowsecurity: boolean }>(
+        `SELECT relrowsecurity FROM pg_class WHERE relname = 'read_rebuild_items_per_group'`,
+      );
+      expect(pgClass?.relrowsecurity).toBe(true);
+
+      const state = await getProjectionState(testDb.db, qualifiedProjectionName);
+      expect(state?.status).toBe("failed");
+    } finally {
+      await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" DISABLE ROW LEVEL SECURITY`);
+    }
+
+    // RLS cleared again → rebuild works.
+    const result = await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(result.eventsProcessed).toBe(1);
+    expect(await getCount(group)).toBe(1);
+  });
+
+  test("aborts on a policy alone, without RLS enabled — policy count reported and survives", async () => {
+    const group = "00000000-0000-4000-8000-000000000052";
+    await appendCreatedEvent(group, "item1");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(
+      `CREATE POLICY rls_guard_probe ON "read_rebuild_items_per_group" USING (true)`,
+    );
+    try {
+      await expect(
+        rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry }),
+      ).rejects.toThrow(/policies: 1/);
+
+      const [policyCount] = await raw.unsafe<{ n: number }>(
+        `SELECT count(*)::int AS n FROM pg_policy p
+         JOIN pg_class c ON c.oid = p.polrelid
+         WHERE c.relname = 'read_rebuild_items_per_group'`,
+      );
+      expect(policyCount?.n).toBe(1);
+    } finally {
+      await raw.unsafe(`DROP POLICY IF EXISTS rls_guard_probe ON "read_rebuild_items_per_group"`);
+    }
+  });
+
+  test("aborts on FORCE ROW LEVEL SECURITY alone, without ENABLE", async () => {
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" FORCE ROW LEVEL SECURITY`);
+    try {
+      await expect(
+        rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry }),
+      ).rejects.toThrow(/row level security/);
+    } finally {
+      await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" NO FORCE ROW LEVEL SECURITY`);
+      await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" DISABLE ROW LEVEL SECURITY`);
+    }
+  });
+
+  test("swapShadowIntoLive rejects directly when RLS is enabled — live table survives", async () => {
+    const group = "00000000-0000-4000-8000-000000000053";
+    await appendCreatedEvent(group, "item1");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(1);
+
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" ENABLE ROW LEVEL SECURITY`);
+    try {
+      const db = testDb.db as DbConnection; // @cast-boundary test-harness (TestDb.db is intentionally unknown)
+      await expect(
+        db.begin(async (tx: DbTx) => {
+          await swapShadowIntoLive(tx, "read_rebuild_items_per_group");
+        }),
+      ).rejects.toThrow(/shadow swap:.*row level security/);
+
+      expect(await getCount(group)).toBe(1);
+    } finally {
+      await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" DISABLE ROW LEVEL SECURITY`);
+    }
+  });
+});

package/src/pipeline/__tests__/projections-runner-systemscope.integration.test.ts

@@ -0,0 +1,101 @@
+// Pins the in-transaction inline-projection path over real HTTP for an
+// r.systemScope() feature — the tenant-mode path is covered by domain-events-projections.integration.test.ts.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import {
+  integer as pgInteger,
+  table as pgTable,
+  text as pgText,
+  uuid as pgUuid,
+} from "../../db/dialect";
+import { insertOne, selectMany } from "../../db/query";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+} from "../../engine";
+import {
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "../../stack";
+
+const sysItemEntity = createEntity({
+  table: "read_sysproj_items",
+  fields: { label: createTextField({ personal: false, reason: "test_fixture", required: true }) },
+});
+
+// No tenant_id column — mirrors the "system-scoped projection" table in
+// query-projection.integration.test.ts, but fed by dispatch-write's
+// in-transaction runProjections (r.projection) rather than a query handler.
+const auditTable = pgTable("read_sysproj_item_audit", {
+  itemId: pgUuid("item_id").primaryKey(),
+  tenantId: pgUuid("tenant_id").notNull(),
+  label: pgText("label").notNull(),
+  hits: pgInteger("hits").notNull().default(1),
+});
+
+const sysProjFeature = defineFeature("sysproj", (r) => {
+  r.systemScope();
+  r.entity("sysproj-item", sysItemEntity);
+
+  r.projection({
+    name: "item-audit",
+    source: "sysproj-item",
+    table: auditTable,
+    apply: {
+      "sysproj-item.created": async (event, tx) => {
+        const p = event.payload as { label?: string };
+        await insertOne(tx, auditTable, {
+          itemId: event.aggregateId,
+          tenantId: event.tenantId,
+          label: p.label ?? "?",
+        });
+      },
+    },
+  });
+
+  r.writeHandler(
+    defineEntityCreateHandler("sysproj-item", sysItemEntity, {
+      access: { roles: ["SystemAdmin"] },
+    }),
+  );
+});
+
+let stack: TestStack;
+const systemAdmin = TestUsers.systemAdmin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [sysProjFeature], systemHooks: [] });
+  await unsafeCreateEntityTable(stack.db, sysItemEntity, "sysproj-item");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, ["read_sysproj_items", "read_sysproj_item_audit"]);
+});
+
+describe("inline r.projection fires in-transaction for an r.systemScope() feature", () => {
+  test("HTTP write lands both the entity row and the projection row", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "sysproj:write:sysproj-item:create",
+      { label: "widget-a" },
+      systemAdmin,
+    );
+
+    const auditRows = await selectMany<{ itemId: string; label: string; tenantId: string }>(
+      stack.db,
+      auditTable,
+      { itemId: created.id },
+    );
+    expect(auditRows).toHaveLength(1);
+    expect(auditRows[0]?.label).toBe("widget-a");
+    expect(auditRows[0]?.tenantId).toBe(systemAdmin.tenantId);
+  });
+});