@cosmicdrift/kumiko-bundled-features 0.269.2 → 0.273.0

package/src/config/__tests__/reencrypt-job-tenant-checks.integration.test.ts

@@ -19,6 +19,7 @@ import {
   createTenantConfig,
   defineFeature,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { ESCAPE_HATCH_USED_SIGNAL } from "@cosmicdrift/kumiko-framework/pipeline";
 import {
   createEnvelopeCipher,
   createEnvMasterKeyProvider,
@@ -158,7 +159,7 @@ describe("config KEK-rotation job — multi-tenant scan + write checks (kumiko-f
     // No warn output — an over-restrictive systemDb binding would reject a
     // row via assertRowsTenant, landing it in `failed` with a warn log
     // instead of `migrated`.
-    expect(captured.warn).toEqual([]);
+    expect(captured.warn.filter((msg) => msg !== ESCAPE_HATCH_USED_SIGNAL)).toEqual([]);
 
     const completeLine = captured.info.find((line) =>
       line.includes("[config:reencrypt] complete:"),

package/src/config/__tests__/tz-resolution.integration.test.ts

@@ -38,7 +38,7 @@ const probeFeature = defineFeature("probe", (r) => {
       isSuccess: true,
       data: { tenant: ctx.tz.tenant, user: ctx.tz.user },
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/config/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "systemScope handlers get a default per-tenant+handler rate limit; the four read queries opt out (fw#2861).",
+    "detail": "`config` mounts under `r.systemScope()`, so `config:write:set`/`config:write:reset` without their own `rateLimit` now default to `{ per: \"tenant+handler\", limit: 600, windowSeconds: 60 }` once an app has a `RateLimitResolver` configured (framework change, see kumiko-framework changes.json 0.271.0). `config:query:cascade`, `config:query:values`, `config:query:schema` and `config:query:readiness` declare `rateLimit: { disabled: true, reason: \"...\" }` — each is a self-scoped read of the caller's own readable config, hit on every page load, and a per-tenant bucket would throttle the whole tenant's page loads instead of just that one handler's traffic."
+  },
   {
     "version": "0.165.0",
     "type": "breaking",

package/src/config/db/queries/__tests__/resolver.test.ts

@@ -1,27 +1,22 @@
 import { describe, expect, test } from "bun:test";
+import { createTenantDb, type DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { selectConfigRowsForKeys, selectConfigRowsForScope } from "../resolver";
 
-function closedConnectionError(): Error {
-  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
-}
-
 type FakeClient = {
   unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
   begin: () => never;
   calls: number;
 };
 
-function fakeClient(failures: Error[]): FakeClient {
-  const remaining = [...failures];
+function fakeClient(rowsPerCall: readonly (readonly Record<string, unknown>[])[]): FakeClient {
   const client: FakeClient = {
     calls: 0,
     unsafe: async () => {
+      const rows = rowsPerCall[client.calls] ?? [];
       client.calls++;
-      const err = remaining.shift();
-      if (err) throw err;
-      return [{ id: "r1", key: "k", value: "v", tenantId: "t1", userId: null }];
+      return rows;
     },
-    // begin() present => pool client => retry path
     begin: () => {
       throw new Error("not used in test");
     },
@@ -29,44 +24,54 @@ function fakeClient(failures: Error[]): FakeClient {
   return client;
 }
 
-describe("config db/queries/resolver — closed-connection retry (#1163)", () => {
-  test("selectConfigRowsForScope retries once and returns rows", async () => {
-    const db = fakeClient([closedConnectionError()]);
+describe("config db/queries/resolver — scope-bucket merge", () => {
+  test("selectConfigRowsForScope merges the scope bucket and the user bucket", async () => {
+    const db = fakeClient([
+      [{ id: "sys-1", key: "k1", value: "v-sys", tenantId: "system", userId: null }],
+      [{ id: "user-1", key: "k1", value: "v-user", tenantId: "t1", userId: "u1" }],
+    ]);
     const rows = await selectConfigRowsForScope(db as never, "system", "t1", "u1");
-    expect(rows).toHaveLength(1);
-    expect(rows[0]?.key).toBe("k");
     expect(db.calls).toBe(2);
+    expect(rows.map((r) => r.id).sort()).toEqual(["sys-1", "user-1"]);
   });
 
-  test("selectConfigRowsForKeys retries once and returns rows", async () => {
-    const db = fakeClient([closedConnectionError()]);
-    const rows = await selectConfigRowsForKeys(db as never, ["k"], "system", "t1", "u1");
-    expect(rows).toHaveLength(1);
+  test("selectConfigRowsForKeys merges the scope bucket and the user bucket", async () => {
+    const db = fakeClient([
+      [{ id: "sys-1", key: "k1", value: "v-sys", tenantId: "system", userId: null }],
+      [{ id: "user-1", key: "k1", value: "v-user", tenantId: "t1", userId: "u1" }],
+    ]);
+    const rows = await selectConfigRowsForKeys(db as never, ["k1"], "system", "t1", "u1");
     expect(db.calls).toBe(2);
+    expect(rows.map((r) => r.id).sort()).toEqual(["sys-1", "user-1"]);
   });
 
-  test("gives up after the single retry when the connection stays closed", async () => {
-    const db = fakeClient([closedConnectionError(), closedConnectionError()]);
-    await expect(selectConfigRowsForScope(db as never, "system", "t1", "u1")).rejects.toThrow(
-      "connection was closed",
-    );
-    expect(db.calls).toBe(2);
+  test("selectConfigRowsForKeys returns [] without querying when keys is empty", async () => {
+    const db = fakeClient([]);
+    const rows = await selectConfigRowsForKeys(db as never, [], "system", "t1", "u1");
+    expect(rows).toEqual([]);
+    expect(db.calls).toBe(0);
   });
+});
 
-  test("does not retry when the client has no begin()", async () => {
-    let calls = 0;
-    const db = {
-      unsafe: async () => {
-        calls++;
-        throw closedConnectionError();
+describe("config db/queries/resolver — tenant-mode TenantDb narrowing", () => {
+  test("selectConfigRowsForScope's tenantId array survives readWhere's narrowing", async () => {
+    const captured: { sql: string; values: readonly unknown[] }[] = [];
+    const recordingRunner = {
+      unsafe: async (sql: string, values: readonly unknown[]) => {
+        captured.push({ sql, values });
+        return [] as unknown[];
       },
-      savepoint: () => {
-        throw new Error("not used");
+      begin: async () => {
+        throw new Error("not used in test");
       },
-    };
-    await expect(selectConfigRowsForScope(db as never, "system", "t1", "u1")).rejects.toThrow(
-      "connection was closed",
-    );
-    expect(calls).toBe(1);
+    } as unknown as DbRunner;
+    const tdb = createTenantDb(recordingRunner, "t1");
+
+    await selectConfigRowsForScope(tdb, SYSTEM_TENANT_ID, "t1", "u1");
+
+    expect(captured).toHaveLength(2);
+    expect(captured[0]?.sql).toMatch(/tenant_id" IN /i);
+    expect(captured[0]?.values).toContain(SYSTEM_TENANT_ID);
+    expect(captured[0]?.values).toContain("t1");
   });
 });

package/src/config/db/queries/resolver.ts

@@ -1,6 +1,7 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { configValuesTable } from "../../table";
 
 export type ConfigRow = {
   readonly id: string;
@@ -10,21 +11,21 @@ export type ConfigRow = {
   readonly userId: string | null;
 };
 
+// Method-form so a tenant-mode TenantDb stays filtered.
 export async function selectConfigRowsForScope(
   db: DbRunner | TenantDb,
   systemTenantId: TenantId,
   tenantId: TenantId,
   userId: string,
 ): Promise<readonly ConfigRow[]> {
-  return unsafeReadRetrying<ConfigRow>(
-    db,
-    `SELECT id, key, value, tenant_id AS "tenantId", user_id AS "userId"
-     FROM read_config_values
-     WHERE (tenant_id = $1 AND user_id IS NULL)
-        OR (tenant_id = $2 AND user_id IS NULL)
-        OR (tenant_id = $2 AND user_id = $3)`,
-    [systemTenantId, tenantId, userId],
-  );
+  const [scopeRows, userRows] = await Promise.all([
+    selectMany<ConfigRow>(db, configValuesTable, {
+      tenantId: [systemTenantId, tenantId],
+      userId: null,
+    }),
+    selectMany<ConfigRow>(db, configValuesTable, { tenantId, userId }),
+  ]);
+  return [...scopeRows, ...userRows];
 }
 
 export async function selectConfigRowsForKeys(
@@ -34,16 +35,15 @@ export async function selectConfigRowsForKeys(
   tenantId: TenantId,
   userId: string,
 ): Promise<readonly ConfigRow[]> {
-  return unsafeReadRetrying<ConfigRow>(
-    db,
-    `SELECT id, key, value, tenant_id AS "tenantId", user_id AS "userId"
-     FROM read_config_values
-     WHERE key = ANY($1)
-       AND (
-         (tenant_id = $2 AND user_id IS NULL)
-         OR (tenant_id = $3 AND user_id IS NULL)
-         OR (tenant_id = $3 AND user_id = $4)
-       )`,
-    [[...keys], systemTenantId, tenantId, userId],
-  );
+  if (keys.length === 0) return [];
+  const keyFilter = { in: [...keys] };
+  const [scopeRows, userRows] = await Promise.all([
+    selectMany<ConfigRow>(db, configValuesTable, {
+      key: keyFilter,
+      tenantId: [systemTenantId, tenantId],
+      userId: null,
+    }),
+    selectMany<ConfigRow>(db, configValuesTable, { key: keyFilter, tenantId, userId }),
+  ]);
+  return [...scopeRows, ...userRows];
 }

package/src/config/handlers/cascade.query.ts

@@ -16,7 +16,19 @@ export const cascadeQuery = defineQueryHandler({
   schema: z.object({
     keys: z.array(z.string()).optional(),
   }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call cascade; hasConfigAccess filters the result to " +
+        "only the config keys the caller's roles may read, before any value is returned",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own readable config cascade, hit on every page load; " +
+      "per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
   handler: async (query, ctx) => {
     const db = requireSystemDb(ctx, "config:query:cascade", query.user.tenantId);
     const registry = ctx.registry;

package/src/config/handlers/readiness.query.ts

@@ -131,7 +131,19 @@ export const readinessQuery = defineQueryHandler({
     "Lists the required config keys that are still unset for the caller's tenant, each with its scope and type; use it to find out what is missing before a feature can run.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call readiness; collectMissingRequiredConfig filters " +
+        "candidate keys through hasConfigAccess so only keys the caller's roles may read are reported",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own tenant's config readiness, hit on every page load; " +
+      "per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
   handler: async (query, ctx) => {
     const db = requireSystemDb(ctx, "config:query:readiness", query.user.tenantId);
     const missing = await collectMissingRequiredConfig(

package/src/config/handlers/reencrypt.job.ts

@@ -38,6 +38,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipeline";
 import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import {
   type ChunkedMigrationStopReason,
@@ -107,6 +108,16 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     ? Date.now() + payload.maxDurationMs
     : Number.POSITIVE_INFINITY;
 
+  function reportEscapeHatchFor(tenantId: TenantId) {
+    return createEscapeHatchReporter({
+      handler: "config:job:reencrypt",
+      tenantId,
+      actor: "system",
+      sink: ctx._escapeHatchAuditSink,
+      log: ctx.log,
+    });
+  }
+
   const tdbCache = new Map<TenantId, TenantDb>();
   function tdbFor(tenantId: TenantId): TenantDb {
     let existing = tdbCache.get(tenantId);
@@ -121,7 +132,11 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   function sdbFor(tenantId: TenantId): UncheckedSystemDb {
     let existing = sdbCache.get(tenantId);
     if (!existing) {
-      existing = createUncheckedSystemDb(tdbFor(tenantId));
+      existing = createUncheckedSystemDb(
+        tdbFor(tenantId),
+        undefined,
+        reportEscapeHatchFor(tenantId),
+      );
       sdbCache.set(tenantId, existing);
     }
     return existing;
@@ -131,7 +146,11 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   // to acknowledge the cross-tenant scan below, never bound to a real
   // tenant's writes — sharing it with sdbFor(SYSTEM_TENANT_ID) would make a
   // write-path cache entry double as the scan's ack gate.
-  const scanDb = createUncheckedSystemDb(createTenantDb(db, SYSTEM_TENANT_ID, "system"));
+  const scanDb = createUncheckedSystemDb(
+    createTenantDb(db, SYSTEM_TENANT_ID, "system"),
+    undefined,
+    reportEscapeHatchFor(SYSTEM_TENANT_ID),
+  );
 
   type ConfigRow = {
     id: string;

package/src/config/handlers/reset.write.ts

@@ -26,7 +26,13 @@ export const resetWrite = defineWriteHandler({
     scope: scopeEnum.optional(),
   }),
   // Per-key access enforcement lives inside the handler via checkWriteAccess.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call reset; prepareConfigWrite enforces the per-key " +
+        "write access rule before any value is touched",
+    },
+  },
   handler: async (event, ctx) => {
     const db = requireSystemDb(ctx, "config:write:reset", event.user.tenantId);
 

package/src/config/handlers/schema.query.ts

@@ -8,7 +8,19 @@ export const schemaQuery = defineQueryHandler({
     "Returns the definitions of all config keys the caller may read (scope, type, default, bounds, required flag) without any values; use it to discover which settings exist and how they may be set.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call schema; hasConfigAccess filters the result to " +
+        "only the config key definitions the caller's roles may read",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own readable config schema, hit on every page load; " +
+      "per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
   handler: async (query, ctx) => {
     const registry = ctx.registry;
     const allKeys = registry.getAllConfigKeys();

package/src/config/handlers/set.write.ts

@@ -44,7 +44,13 @@ export const setWrite = defineWriteHandler({
     scope: scopeEnum.optional(),
   }),
   // Per-key access enforcement lives inside the handler via checkWriteAccess.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call set; prepareConfigWrite enforces the per-key " +
+        "write access rule before any value is stored",
+    },
+  },
   handler: async (event, ctx) => {
     const db = requireSystemDb(ctx, "config:write:set", event.user.tenantId);
 

package/src/config/handlers/values.query.ts

@@ -16,7 +16,19 @@ export const valuesQuery = defineQueryHandler({
     "Returns the effective value, scope and winning source for every config key the caller may read, with encrypted and secret-backed values masked; use it to inspect the current settings.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call values; hasConfigAccess filters the result to " +
+        "only the config keys the caller's roles may read, before any value is returned",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own readable config values, hit on every page load; " +
+      "per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
   handler: async (query, ctx) => {
     const db = requireSystemDb(ctx, "config:query:values", query.user.tenantId);
     const registry = ctx.registry;

package/src/data-retention/handlers/policy-for.query.ts

@@ -22,7 +22,14 @@ export const policyForQuery = defineQueryHandler({
   schema: z.object({
     entityName: z.string().min(1).max(100),
   }),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in tenant member (and other features calling cross-feature) may " +
+        "resolve the retention policy for an entity name in their own tenant; the result " +
+        "carries only policy metadata, no PII",
+    },
+  },
   description:
     "Resolves the effective retention policy for one entity name in the caller's tenant (keep-for duration plus delete or anonymize strategy) by layering the entity default, tenant preset and tenant override, so a forget flow or cleanup job knows how that data may be removed.",
   handler: async (query, ctx): Promise<EffectiveRetentionPolicy> => {

package/src/delivery/__tests__/delivery-pii-kms.integration.test.ts

@@ -65,7 +65,7 @@ const appFeature = defineFeature("app", (r) => {
         });
         return { isSuccess: true, data: { sent: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 
@@ -82,7 +82,7 @@ const appFeature = defineFeature("app", (r) => {
         });
         return { isSuccess: true, data: { sent: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 });

package/src/delivery/__tests__/delivery-screens.boot.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { access, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { access, isOpenToAllGranted, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
 import { DELIVERY_LOG_SCREEN_ID } from "../constants";
 import { createDeliveryFeature } from "../feature";
@@ -33,9 +33,7 @@ describe("delivery screens + handler access alignment", () => {
   test("access option leaves the preferences handler openToAll — that's per-user, not an admin surface", () => {
     const delivery = createDeliveryFeature({ access: access.systemAdmin });
     const preferencesAccess = delivery.queryHandlers["preferences"]?.access;
-    expect(
-      preferencesAccess && "openToAll" in preferencesAccess && preferencesAccess.openToAll,
-    ).toBe(true);
+    expect(preferencesAccess !== undefined && isOpenToAllGranted(preferencesAccess)).toBe(true);
   });
 
   test("boot-validates with a narrowed access option", () => {

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

@@ -101,7 +101,7 @@ const appFeature = defineFeature("app", (r) => {
 
         return { isSuccess: true, data: { assigned: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 
@@ -124,7 +124,7 @@ const appFeature = defineFeature("app", (r) => {
 
         return { isSuccess: true, data: { sent: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 
@@ -141,7 +141,7 @@ const appFeature = defineFeature("app", (r) => {
         title: z.string(),
         body: z.string(),
       }),
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       handler: async (event, ctx) => {
         const notify = ctx.notify as NotifyFn;
         await notify(event.payload.notificationType, {
@@ -173,7 +173,7 @@ const appFeature = defineFeature("app", (r) => {
 
         return { isSuccess: true, data: { sent: true } };
       },
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     }),
   );
 });
@@ -206,7 +206,7 @@ const ticketFeature = defineFeature("tickets", (r) => {
       status: z.string(),
     }),
     async (event, ctx) => ticketExecutor().create(event.payload, event.user, ctx.db),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   // Declarative: notify assignee when ticket is created with assigneeId
@@ -1293,6 +1293,40 @@ describe("flow 15: idempotency requires Redis", () => {
   });
 });
 
+// --- Flow 15b: escape-hatch audit attribution for tenant-broadcast resolveUserIdsForTenant ---
+
+describe("flow 15b: escape-hatch audit for tenant broadcast", () => {
+  test("recording sink receives an acknowledge-cross-tenant event attributed to tenantUserIdsQuery", async () => {
+    const recorded: import("@cosmicdrift/kumiko-framework/engine").EscapeHatchUseEvent[] = [];
+    const auditedService = createDeliveryService({
+      db,
+      registry: stack.registry,
+      channels: collectChannels(stack.registry),
+      tenantUserIdsQuery: TenantQueries.resolveUserIds,
+      escapeHatchAuditSink: async (event) => {
+        recorded.push(event);
+      },
+    });
+
+    // Distinct tenantId (not used by any earlier test in this file) — the
+    // module-level escape-hatch dedup window suppresses a repeat report for
+    // an identical (handler, kind, reason, tenantId, actor) tuple within 60s,
+    // which would otherwise make this assertion flaky depending on test order.
+    const auditTenantId = testTenantId(915501);
+
+    await auditedService.notify(
+      "app:notify:tenant-alert",
+      { to: { tenant: auditTenantId }, data: { title: "X", body: "X" } },
+      admin,
+      admin.tenantId,
+    );
+
+    const event = recorded.find((e) => e.kind === "acknowledge-cross-tenant");
+    expect(event?.handler).toBe(TenantQueries.resolveUserIds);
+    expect(event?.tenantId).toBe(auditTenantId);
+  });
+});
+
 // --- Flow 16: Unsubscribe race — ON CONFLICT makes repeated clicks safe ---
 
 describe("flow 16: repeated unsubscribe clicks are idempotent", () => {

package/src/delivery/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "systemScope handlers get a default per-tenant+handler rate limit; delivery:preferences opts out (fw#2861).",
+    "detail": "`delivery` mounts under `r.systemScope()`, so `delivery:write:set-preference`/`delivery:query:log` without their own `rateLimit` now default to `{ per: \"tenant+handler\", limit: 600, windowSeconds: 60 }` once an app has a `RateLimitResolver` configured (framework change, see kumiko-framework changes.json 0.271.0). `delivery:query:preferences` declares `rateLimit: { disabled: true, reason: \"...\" }` — it is a self-scoped read of the caller's own notification preference rows, hit on every page load, and a per-tenant bucket would throttle the whole tenant's page loads instead of just that one handler's traffic."
+  },
   {
     "version": "0.208.2",
     "type": "improvement",

package/src/delivery/delivery-service.ts

@@ -1,9 +1,16 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection, DbRow } from "@cosmicdrift/kumiko-framework/db";
 import { createTenantDb, createUncheckedSystemDb } from "@cosmicdrift/kumiko-framework/db";
-import type { NotifyPriority, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EscapeHatchAuditSink,
+  NotifyPriority,
+  Registry,
+  TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
 import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
+import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipeline";
 import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
@@ -43,6 +50,10 @@ export type DeliveryServiceOptions = {
   // the delivery.render → delivery.send jobs. When absent, queued channels fall
   // back to synchronous inline delivery (job-less setups, unit tests).
   readonly jobRunner?: JobRunner;
+  // Attributed escape-hatch audit for resolveUserIdsForTenant's ctx.systemDb —
+  // absent means an unattributed warn log (see fallbackEscapeHatchReporter).
+  readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly log?: Logger;
 };
 
 // Build channel list from registry extension usages
@@ -82,6 +93,8 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     isChannelKilled,
     idempotencyRedis,
     jobRunner,
+    escapeHatchAuditSink,
+    log,
   } = options;
   const idemRedis = idempotencyRedis ?? rateLimit?.redis;
 
@@ -157,7 +170,16 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       throw new Error(`Tenant broadcast query "${tenantUserIdsQuery}" not found in registry`);
     }
     const systemUser = createSystemUser(tenantId);
-    const tenantDb = createTenantDb(db, tenantId, "system");
+    const report = createEscapeHatchReporter({
+      handler: tenantUserIdsQuery,
+      tenantId,
+      actor: systemUser.id,
+      sink: escapeHatchAuditSink,
+      log,
+    });
+    const tenantDb = createTenantDb(db, tenantId, "system", undefined, undefined, undefined, {
+      report,
+    });
     // Hand-built context, not routed through the dispatcher — tenantUserIdsQuery is
     // typically an r.systemScope() handler, fail-closed on ctx.db, so this needs both.
     // @cast-boundary engine-payload — generic query-handler return for typed convention
@@ -166,7 +188,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       {
         db: tenantDb,
         dbOutsideTransaction: tenantDb,
-        systemDb: createUncheckedSystemDb(tenantDb),
+        systemDb: createUncheckedSystemDb(tenantDb, undefined, report),
         registry,
         ...bridgeStub(),
       },

package/src/delivery/handlers/preferences.query.ts

@@ -7,7 +7,19 @@ import { notificationPreferencesTable } from "../tables";
 export const preferencesQuery = defineQueryHandler({
   name: "preferences",
   schema: z.object({}),
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user reads only their own notification preference rows; the " +
+        "query filters notificationPreferencesTable by the caller's own tenantId and userId",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own notification preference rows, hit on every page " +
+      "load; per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
   description:
     "Returns the calling user's notification preference rows for their own tenant; use it to show which notification types and channels that user has enabled or muted.",
   handler: async (query, ctx) => {

package/src/delivery/handlers/set-preference.write.ts

@@ -11,7 +11,13 @@ export const setPreferenceWrite = defineWriteHandler({
     enabled: z.boolean(),
   }),
   // Every user manages their own preferences; tenant+user scoping is on the WHERE.
-  access: { openToAll: true },
+  access: {
+    openToAll: {
+      reason:
+        "each signed-in user changes only their own notification preferences; the " +
+        "write is scoped to the caller's own tenantId and userId via assertTenantMatch",
+    },
+  },
   description:
     "Enables or disables one notification type and channel combination for the calling user, where either side may be the wildcard * as a catch-all; use it when a user changes their own notification settings.",
   handler: async (event, ctx) => {