@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

package/src/errors/i18n/en.yaml

@@ -109,6 +109,19 @@ identity_switch_denied:
     (or on the `r.hook(...)` call, if the switch happens inside a hook), or
     move the logic into an `r.systemScope()` feature or a job.
 
+unsafe_all_tenants_denied:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: a handler or hook called
+    `ctx.queryProjection(qualifiedName, { unsafeAllTenants: true })` without
+    being an `r.systemScope()` handler or declaring `escapeHatch: { reason }`.
+
+    Declare `escapeHatch: { reason: "..." }` on the write, query or stream
+    handler (or on the `r.hook(...)` call, if the read happens inside a
+    hook), or move the logic into an `r.systemScope()` feature.
+
 member_resolution_denied:
   endUser: |
     This action isn't allowed.

package/src/errors/reasons.ts

@@ -48,6 +48,10 @@ export const FrameworkReasons = {
   // claims, origin or extra roles) without r.systemScope() or escapeHatch.
   identitySwitchDenied: "identity_switch_denied",
 
+  // AccessDeniedError: a handler/hook called ctx.queryProjection(..., { unsafeAllTenants: true })
+  // without an r.systemScope() feature or a declared escapeHatch.
+  unsafeAllTenantsDenied: "unsafe_all_tenants_denied",
+
   // AccessDeniedError: ctx.queryAsMember's userId is not an active member of
   // ctx's tenant. Deliberately generic — a caller can't probe which check failed.
   memberResolutionDenied: "member_resolution_denied",

package/src/i18n/required-surface-keys.ts

@@ -196,7 +196,9 @@ export function requiredKeysFromScreen(
       const form = screen as ActionFormScreenDefinition;
       pushKey(out, form.submitLabel);
       for (const fieldName of Object.keys(form.fields)) {
-        out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
+        const override = form.fieldLabels?.[fieldName];
+        if (override !== undefined) pushKey(out, override);
+        else out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
       }
       for (const section of form.layout.sections) {
         if (isExtensionEditSection(section)) {
@@ -207,7 +209,9 @@ export function requiredKeysFromScreen(
         pushKey(out, section.title);
         for (const f of section.fields) {
           const fieldName = editFieldName(f);
-          out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
+          const override = form.fieldLabels?.[fieldName];
+          if (override !== undefined) pushKey(out, override);
+          else out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
         }
       }
       break;

package/src/jobs/__tests__/job-systemdb.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { tenantDbRunner } from "../../db/tenant-db-runner";
 import { createRegistry, defineFeature, type Registry } from "../../engine";
 import { createTestRedis, type TestRedis, testTenantId } from "../../stack";
 import { waitFor } from "../../testing";
@@ -12,9 +13,9 @@ import { createJobRunner, type JobRunner } from "../job-runner";
 type JobRunResult = {
   readonly name: "system" | "tenant" | "system-per-tenant";
   readonly present: boolean;
-  // assertTenantMatch() must return a TenantDb whose `.raw` is the SAME
-  // underlying DbConnection ctx.db carries — proves systemDb is bound to
-  // the job's own tenant-scoped db, not a separate instance.
+  // assertTenantMatch() must return a TenantDb bound (via tenantDbRunner) to
+  // the SAME underlying DbConnection ctx.db carries — proves systemDb is
+  // bound to the job's own tenant-scoped db, not a separate instance.
   readonly boundToRawDb: boolean | undefined;
   // A foreign tenantId must throw fail-closed (AccessDeniedError), same as
   // the HandlerContext.systemDb self-check.
@@ -48,7 +49,7 @@ const systemScopedFeature = defineFeature("jobsystemdb-system", (r) => {
     results.push({
       name: "system",
       present: true,
-      boundToRawDb: checked.raw === ctx.db,
+      boundToRawDb: tenantDbRunner(checked) === ctx.db,
       foreignTenantThrew,
     });
   });

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -31,6 +31,10 @@ let redisUrl: string;
 // Track which jobs ran and when
 const jobLog: Array<{ name: string; payload: Record<string, unknown>; timestamp: number }> = [];
 
+// Counts eventRetrySucceeds' own attempts — throws once on attempt 1, then
+// succeeds, so a real retry must have happened for the job to ever reach 2.
+let eventRetryAttemptCount = 0;
+
 function clearLog() {
   jobLog.length = 0;
 }
@@ -140,6 +144,25 @@ const testFeature = defineFeature("test", (r) => {
     },
   );
 
+  r.writeHandler(
+    "retry-event-trigger",
+    z.object({ n: z.number() }),
+    async (event) => ({ isSuccess: true, data: { n: event.payload.n } }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+  // Event-triggered job with retries — proves handleEvent passes
+  // retries/backoff to the queue the same way dispatch() does (fw
+  // job-runner retries regression, solon).
+  r.job(
+    "eventRetrySucceeds",
+    { trigger: { on: "test:write:retry-event-trigger" }, retries: 2 },
+    async (payload) => {
+      eventRetryAttemptCount += 1;
+      jobLog.push({ name: "test:job:event-retry-succeeds", payload, timestamp: Date.now() });
+      if (eventRetryAttemptCount === 1) throw new Error("fails on first attempt");
+    },
+  );
+
   // Job that fails
   r.job("failingJob", { trigger: { manual: true }, retries: 1 }, async () => {
     throw new Error("intentional failure");
@@ -1197,6 +1220,24 @@ describe("handleEvent maxPerTenant", () => {
   });
 });
 
+describe("handleEvent retries", () => {
+  test("an event-triggered job with retries retries on failure and eventually succeeds", async () => {
+    clearLog();
+    eventRetryAttemptCount = 0;
+    await withRunner(async (runner) => {
+      const user = { ...TestUsers.admin, tenantId: "retry-tenant-evt" };
+      await runner.handleEvent("test:write:retry-event-trigger", { n: 1 }, user);
+      // Without retries/backoff reaching the queue, the job fails on
+      // attempt 1 and BullMQ never retries — this would time out.
+      await waitFor(() => {
+        const entries = jobLog.filter((e) => e.name === "test:job:event-retry-succeeds");
+        expect(entries.length).toBe(2);
+      });
+    });
+    expect(eventRetryAttemptCount).toBe(2);
+  });
+});
+
 // --- Registry ---
 
 describe("job registry", () => {

package/src/jobs/job-runner.ts

@@ -9,6 +9,7 @@ import {
   type AppContext,
   type DispatchWriteRef,
   type JobContext,
+  type JobDefinition,
   type JobRunIn,
   type MemberReader,
   type Registry,
@@ -27,6 +28,7 @@ import {
   type Tracer,
 } from "../observability";
 import { createDistributedLock, type DistributedLock } from "../pipeline/distributed-lock";
+import { createEscapeHatchReporter } from "../pipeline/escape-hatch-report";
 import { RedisKeys } from "../pipeline/redis-keys";
 import { bridgeStub } from "../testing/handler-context";
 
@@ -251,6 +253,16 @@ function timeoutReject(
   };
 }
 
+// Shared by dispatch() and handleEvent() — an event-triggered job must retry
+// on failure the same way a directly-dispatched one does; a duplicated
+// inline computation in handleEvent previously dropped both options.
+function buildRetryBullOpts(jobDef: JobDefinition): Record<string, unknown> {
+  const opts: Record<string, unknown> = {};
+  if (jobDef.retries !== undefined) opts["attempts"] = jobDef.retries + 1;
+  if (jobDef.backoff) opts["backoff"] = { type: jobDef.backoff };
+  return opts;
+}
+
 export function createJobRunner(options: JobRunnerOptions): JobRunner {
   const { registry, context, redisUrl, consumerLane } = options;
   const queueNamePrefix = options.queueNamePrefix ?? DEFAULT_QUEUE_NAME_PREFIX;
@@ -282,12 +294,19 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     return async () => {
       const systemUser = createSystemUser(SYSTEM_TENANT_ID);
       const systemModeDb = createTenantDb(db, SYSTEM_TENANT_ID, "system");
+      const reportEscapeHatch = createEscapeHatchReporter({
+        handler: ACTIVE_TENANT_IDS_QUERY_NAME,
+        tenantId: SYSTEM_TENANT_ID,
+        actor: systemUser.id,
+        sink: context._escapeHatchAuditSink,
+        log: context.log,
+      });
       const result = await handler.handler(
         { type: ACTIVE_TENANT_IDS_QUERY_NAME, payload: {}, user: systemUser },
         {
           db: systemModeDb,
           dbOutsideTransaction: systemModeDb,
-          systemDb: createUncheckedSystemDb(systemModeDb),
+          systemDb: createUncheckedSystemDb(systemModeDb, undefined, reportEscapeHatch),
           registry,
           ...bridgeStub(),
         },
@@ -533,7 +552,19 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     const tenantScopedDb = configDb ? createTenantDb(configDb, tenantId, "system") : undefined;
     const isSystemJob = registry.isJobSystemScoped(jobName);
     const systemDb =
-      isSystemJob && tenantScopedDb ? createUncheckedSystemDb(tenantScopedDb) : undefined;
+      isSystemJob && tenantScopedDb
+        ? createUncheckedSystemDb(
+            tenantScopedDb,
+            undefined,
+            createEscapeHatchReporter({
+              handler: jobName,
+              tenantId,
+              actor: jobSystemUser.id,
+              sink: context._escapeHatchAuditSink,
+              log: context.log,
+            }),
+          )
+        : undefined;
     const config =
       context._configAccessorFactory && tenantScopedDb
         ? context._configAccessorFactory({
@@ -883,8 +914,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
           break;
       }
 
-      if (jobDef.retries !== undefined) bullOpts["attempts"] = jobDef.retries + 1;
-      if (jobDef.backoff) bullOpts["backoff"] = { type: jobDef.backoff };
+      Object.assign(bullOpts, buildRetryBullOpts(jobDef));
       if (jobDef.timeout) bullOpts["timeout"] = jobDef.timeout;
       if (meta?.priority !== undefined) bullOpts["priority"] = meta.priority;
 
@@ -948,7 +978,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         }
         // Route to the job's declared lane, not a fixed queue — that's
         // the whole reason both queues are held.
-        await queues[laneForJob(jobDef)].add(name, data);
+        await queues[laneForJob(jobDef)].add(name, data, buildRetryBullOpts(jobDef));
       }
     },
     attachDispatcher(ref: DispatchWriteRef): void {

package/src/pipeline/__tests__/escape-hatch-audit.integration.test.ts

@@ -0,0 +1,254 @@
+// fw#2861 — every escape-hatch use reports through AppContext._escapeHatchAuditSink
+// (or warn-logs when no sink is wired). Real HTTP calls + setupTestStack — never
+// createTestDispatcher. Modelled on unsafe-raw-escape-hatch.integration.test.ts and
+// system-identity-switch.integration.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
+import { executeRawQuery } from "../../db/queries/raw-sql";
+import { createSystemUser, defineFeature } from "../../engine";
+import type { EscapeHatchUseEvent } from "../../engine/types";
+import type { Logger } from "../../logging/types";
+import { createTestUser, setupTestStack, type TestStack } from "../../stack";
+import { ESCAPE_HATCH_USED_SIGNAL } from "../escape-hatch-report";
+
+const globalStoreTable = defineUnmanagedTable({
+  tableName: "store_fw2861_escape_hatch_audit_items",
+  tenancy: "global",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "note", pgType: "text", notNull: true },
+  ],
+});
+
+const UNSAFE_RAW_REASON = "fw#2861 integration test — declared unsafeRaw write";
+const GLOBAL_WRITE_REASON = "fw#2861 integration test — declared cross-tenant write";
+const IDENTITY_SWITCH_REASON = "fw#2861 integration test — needs SYSTEM to look itself up";
+const ACKNOWLEDGE_REASON = "fw#2861 integration test — system-wide scan";
+
+const probeFeature = defineFeature("escape-hatch-audit-probe", (r) => {
+  r.storeTable(globalStoreTable, {
+    reason: "fw#2861 integration test — cross-tenant store table for db.global()",
+  });
+
+  r.queryHandler(
+    "whoami",
+    z.object({}),
+    async (query) => ({ id: query.user.id, tenantId: query.user.tenantId }),
+    { access: { roles: ["system", "User"] } },
+  );
+
+  r.writeHandler(
+    "unsafe-raw-write",
+    z.object({}),
+    async (_event, ctx) => {
+      const runner = ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
+      return { isSuccess: true as const, data: { one: rows[0]?.one } };
+    },
+    { access: { roles: ["User"] }, escapeHatch: { reason: UNSAFE_RAW_REASON } },
+  );
+
+  r.writeHandler(
+    "global-write",
+    z.object({}),
+    async (_event, ctx) => {
+      const row = await ctx.db.global(globalStoreTable).insertOne<{ id: string }>({
+        note: "hi",
+      });
+      return { isSuccess: true as const, data: row };
+    },
+    { access: { roles: ["User"] }, escapeHatch: { reason: GLOBAL_WRITE_REASON } },
+  );
+
+  r.writeHandler(
+    "identity-switch-write",
+    z.object({}),
+    async (event, ctx) =>
+      ctx
+        .queryAs(createSystemUser(event.user.tenantId), "escape-hatch-audit-probe:query:whoami", {})
+        .then((data) => ({ isSuccess: true as const, data })),
+    { access: { roles: ["User"] }, escapeHatch: { reason: IDENTITY_SWITCH_REASON } },
+  );
+
+  r.writeHandler(
+    "identity-switch-self-write",
+    z.object({}),
+    async (event, ctx) =>
+      ctx
+        .queryAs(event.user, "escape-hatch-audit-probe:query:whoami", {})
+        .then((data) => ({ isSuccess: true as const, data })),
+    { access: { roles: ["User"] }, escapeHatch: { reason: IDENTITY_SWITCH_REASON } },
+  );
+});
+
+const systemScopeProbeFeature = defineFeature("escape-hatch-audit-probe-system", (r) => {
+  r.systemScope();
+
+  r.queryHandler(
+    "acknowledge-cross-tenant-query",
+    z.object({}),
+    async (_query, ctx) => {
+      if (!ctx.systemDb) throw new Error("expected ctx.systemDb on a systemScope() handler");
+      const db = ctx.systemDb.acknowledgeCrossTenant(ACKNOWLEDGE_REASON);
+      return { tenantId: db.tenantId };
+    },
+    { access: { roles: ["User"] } },
+  );
+});
+
+const user = createTestUser({
+  id: 93,
+  tenantId: "11111111-0000-4000-8000-000000000093",
+  roles: ["User"],
+});
+
+function recordingSink(events: EscapeHatchUseEvent[]) {
+  return async (event: EscapeHatchUseEvent) => {
+    events.push(event);
+  };
+}
+
+describe("escape-hatch uses report through AppContext._escapeHatchAuditSink", () => {
+  let stack: TestStack;
+  const events: EscapeHatchUseEvent[] = [];
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [probeFeature, systemScopeProbeFeature],
+      extraContext: { _escapeHatchAuditSink: recordingSink(events) },
+    });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("unsafeRaw reports exactly one unsafe-raw event with handler/kind/reason/tenantId/actor, deduped on a repeat call within the window", async () => {
+    events.length = 0;
+    await stack.http.writeOk("escape-hatch-audit-probe:write:unsafe-raw-write", {}, user);
+    // Identical (handler, kind, reason, tenantId, actor) — the 60s dedup window
+    // must suppress this second report.
+    await stack.http.writeOk("escape-hatch-audit-probe:write:unsafe-raw-write", {}, user);
+
+    const matches = events.filter((e) => e.kind === "unsafe-raw");
+    expect(matches).toEqual([
+      {
+        handler: "escape-hatch-audit-probe:write:unsafe-raw-write",
+        kind: "unsafe-raw",
+        reason: UNSAFE_RAW_REASON,
+        tenantId: user.tenantId,
+        actor: user.id,
+      },
+    ]);
+  });
+
+  test("db.global() write reports exactly one global-write event with the escapeHatch's reason", async () => {
+    events.length = 0;
+    await stack.http.writeOk("escape-hatch-audit-probe:write:global-write", {}, user);
+
+    const matches = events.filter((e) => e.kind === "global-write");
+    expect(matches).toEqual([
+      {
+        handler: "escape-hatch-audit-probe:write:global-write",
+        kind: "global-write",
+        reason: GLOBAL_WRITE_REASON,
+        tenantId: user.tenantId,
+        actor: user.id,
+      },
+    ]);
+  });
+
+  test("ctx.systemDb.acknowledgeCrossTenant reports exactly one acknowledge-cross-tenant event", async () => {
+    events.length = 0;
+    await stack.http.queryOk(
+      "escape-hatch-audit-probe-system:query:acknowledge-cross-tenant-query",
+      {},
+      user,
+    );
+
+    const matches = events.filter((e) => e.kind === "acknowledge-cross-tenant");
+    expect(matches).toEqual([
+      {
+        handler: "escape-hatch-audit-probe-system:query:acknowledge-cross-tenant-query",
+        kind: "acknowledge-cross-tenant",
+        reason: ACKNOWLEDGE_REASON,
+        tenantId: user.tenantId,
+        actor: user.id,
+      },
+    ]);
+  });
+
+  test("a granted SYSTEM identity switch reports exactly one identity-switch event with the target", async () => {
+    events.length = 0;
+    await stack.http.writeOk("escape-hatch-audit-probe:write:identity-switch-write", {}, user);
+
+    const matches = events.filter((e) => e.kind === "identity-switch");
+    expect(matches).toEqual([
+      {
+        handler: "escape-hatch-audit-probe:write:identity-switch-write",
+        kind: "identity-switch",
+        reason: IDENTITY_SWITCH_REASON,
+        tenantId: user.tenantId,
+        actor: user.id,
+        target: { id: createSystemUser(user.tenantId).id, tenantId: user.tenantId },
+      },
+    ]);
+  });
+
+  test("self-delegation with a grant reports no identity-switch event", async () => {
+    events.length = 0;
+    await stack.http.writeOk("escape-hatch-audit-probe:write:identity-switch-self-write", {}, user);
+
+    expect(events.filter((e) => e.kind === "identity-switch")).toEqual([]);
+  });
+});
+
+describe("escape-hatch uses without a sink fall back to a structured warn log", () => {
+  let stack: TestStack;
+  const warnCalls: Array<{ msg: string; data?: Record<string, unknown> }> = [];
+
+  beforeAll(async () => {
+    const log: Logger = {
+      info() {},
+      debug() {},
+      warn(msg, data) {
+        warnCalls.push({ msg, data });
+      },
+      error() {},
+      child() {
+        return log;
+      },
+    };
+    stack = await setupTestStack({
+      features: [probeFeature, systemScopeProbeFeature],
+      extraContext: { log },
+    });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("unsafeRaw without a sink warn-logs security:escape-hatch-used", async () => {
+    warnCalls.length = 0;
+    await stack.http.writeOk("escape-hatch-audit-probe:write:unsafe-raw-write", {}, user);
+
+    const matches = warnCalls.filter((c) => c.msg === ESCAPE_HATCH_USED_SIGNAL);
+    expect(matches).toHaveLength(1);
+    expect(matches[0]?.data).toEqual({
+      handler: "escape-hatch-audit-probe:write:unsafe-raw-write",
+      kind: "unsafe-raw",
+      reason: UNSAFE_RAW_REASON,
+      tenantId: user.tenantId,
+      actor: user.id,
+    });
+  });
+});

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__/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`,
+      );
+    }
+  });
 });