@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/jobs/__tests__/job-multi-trigger.integration.test.ts

@@ -27,13 +27,13 @@ const orderFeature = defineFeature("multi", (r) => {
     "order:open",
     z.object({ id: z.string() }),
     async (event) => ({ isSuccess: true, data: { id: event.payload.id } }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.writeHandler(
     "order:cancel",
     z.object({ id: z.string() }),
     async (event) => ({ isSuccess: true, data: { id: event.payload.id } }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.job(
     "fanout",

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;
 }
@@ -119,7 +123,7 @@ const testFeature = defineFeature("test", (r) => {
     "capped-event",
     z.object({ n: z.number() }),
     async (event) => ({ isSuccess: true, data: { n: event.payload.n } }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   // Event-triggered twin — exercises handleEvent's maxPerTenant guard
   // (dispatch and handleEvent share isOverPerTenantLimit).
@@ -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/observability/__tests__/observability.integration.test.ts

@@ -33,7 +33,7 @@ const productFeature = defineFeature("product", (r) => {
       ctx.metrics.inc("tracked_total", { kind: event.payload.kind });
       return { isSuccess: true, data: { ok: true } };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 
@@ -44,7 +44,7 @@ const errorFeature = defineFeature("err", (r) => {
     async () => {
       throw new Error("boom from handler");
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 
@@ -90,7 +90,7 @@ const todoFeature = defineFeature("todo", (r) => {
         },
       };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.hook("postSave", "create", async (_save: SaveContext) => {
@@ -288,7 +288,7 @@ describe("Observability (integration) — Redis wrapper", () => {
         await ctx.redis.get("session:abc123:token");
         return { isSuccess: true, data: { ok: true } };
       },
-      { access: { openToAll: true } },
+      { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
     );
   });
 
@@ -352,7 +352,7 @@ describe("Observability (integration) — Pino trace bridge", () => {
         ctx.log?.info(event.payload.msg, { custom: "field" });
         return { isSuccess: true, data: { ok: true } };
       },
-      { access: { openToAll: true } },
+      { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
     );
   });
 
@@ -581,7 +581,7 @@ const consumerAFeature = defineFeature("consumer-a", (r) => {
       recordSharedCall(ctx);
       return { isSuccess: true, data: { ok: true } };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 
@@ -594,7 +594,7 @@ const consumerBFeature = defineFeature("consumer-b", (r) => {
       ctx.metricsFor("unregistered-lib").inc("never_total");
       return { isSuccess: true, data: { ok: true } };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/pipeline/__tests__/archive-stream.integration.test.ts

@@ -109,14 +109,14 @@ const archFeature = defineFeature("archtest", (r) => {
     "item:events",
     z.object({ id: z.uuid() }),
     async (query, ctx) => ctx.loadAggregate(query.payload.id),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.queryHandler(
     "item:is-archived",
     z.object({ id: z.uuid() }),
     async (query, ctx) => ctx.isStreamArchived(query.payload.id),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -33,7 +33,7 @@ const echoFeature = defineFeature("echo", (r) => {
       items: [],
       search: query.payload.search,
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.streamHandler(
@@ -137,7 +137,7 @@ describe("dispatcher.write", () => {
         z.object({ name: z.string() }),
         async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
         {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           rateLimit: { per: "ip+handler", limit: 3, windowSeconds: 60 },
         },
       );
@@ -168,7 +168,7 @@ describe("dispatcher.write", () => {
         z.object({ name: z.string() }),
         async (event) => ({ isSuccess: true, data: { name: event.payload.name } }),
         {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
         },
       );
@@ -428,7 +428,7 @@ describe("dispatcher.stream", () => {
             yield { i };
           }
         },
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     const dispatcher = createDispatcher(createRegistry([nestedFeature]), {
@@ -466,7 +466,7 @@ describe("dispatcher.stream", () => {
             throw new Error("close-boom");
           }
         },
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     const dispatcher = createDispatcher(createRegistry([closeFailFeature]), {
@@ -500,7 +500,7 @@ describe("dispatcher.stream", () => {
           yield { i: 0 };
           yield { i: 1 };
         },
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     const dispatcher = createDispatcher(createRegistry([feature]), {
@@ -536,7 +536,7 @@ describe("dispatcher.stream", () => {
           yield { i: 1 };
           yield { i: 2 };
         },
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     const dispatcher = createDispatcher(createRegistry([feature]), {
@@ -571,7 +571,7 @@ describe("dispatcher.query postQuery hooks", () => {
     // pass on entity-existence makes such a hook register silently + never run.
     const feature = defineFeature("dash", (r) => {
       r.queryHandler("dashboard", z.object({}), async () => ({ count: 1 }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook("postQuery", "dashboard", async ({ entityName, rows }) => {
         expect(entityName).toBeUndefined();
@@ -590,7 +590,7 @@ describe("dispatcher.query postQuery hooks", () => {
     // [...null]). The hook here returns the row unchanged so the shape survives.
     const feature = defineFeature("nullrows", (r) => {
       r.queryHandler("dashboard", z.object({}), async () => ({ rows: null, nextCursor: null }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook("postQuery", "dashboard", async ({ rows }) => ({ rows }));
     });
@@ -603,7 +603,7 @@ describe("dispatcher.query postQuery hooks", () => {
   test("single-object postQuery hook returning ≠1 row throws", async () => {
     const feature = defineFeature("multi", (r) => {
       r.queryHandler("dashboard", z.object({}), async () => ({ count: 1 }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.hook("postQuery", "dashboard", async ({ rows }) => ({ rows: [...rows, ...rows] }));
     });
@@ -708,7 +708,7 @@ describe("dispatcher feature-gate", () => {
         }),
       );
       r.queryHandler("widget:list", z.object({}).passthrough(), async () => ({ items: [] }), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.writeHandler(
         "widget:create",
@@ -728,7 +728,7 @@ describe("dispatcher feature-gate", () => {
             i++;
           }
         },
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
   }
@@ -900,7 +900,7 @@ describe("dispatcher feature-gate", () => {
         "check",
         z.object({}).passthrough(),
         async (_event, ctx) => ({ enabled: await ctx.hasFeature("toggled") }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     const registry = createRegistry([toggled(), probe]);
@@ -940,7 +940,7 @@ describe("dispatcher feature-gate", () => {
         "check",
         z.object({}).passthrough(),
         async (_event, ctx) => ({ enabled: await ctx.hasFeature("premium-companion") }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     const registry = createRegistry([probe]);
@@ -1027,7 +1027,7 @@ describe("dispatcher context.geoTzProvider (680/1)", () => {
             longitude: query.payload.longitude,
           }),
         }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
     const registry = createRegistry([geoFeature]);

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