@cosmicdrift/kumiko-bundled-features 0.198.0 → 0.199.0

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

@@ -15,15 +15,28 @@
 // so each rotation appends a normal `.updated` event whose payload carries
 // the NEW envelope: after a full run even a from-scratch rebuild only
 // ever sees the current-KEK envelope.
+//
+// systemScope() fail-closed pattern (framework#2056): the initial scan is
+// intentionally cross-tenant (system-wide key rotation), acknowledged via
+// UncheckedSystemDb.acknowledgeCrossTenant(). Rows are bucketed by tenant,
+// and assertRowsTenant() re-verifies each row against its bucket's tenant
+// right before the write — both checks are built locally from the exported
+// createUncheckedSystemDb().
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createEventStoreExecutor,
   createTenantDb,
+  createUncheckedSystemDb,
   type DbConnection,
   type TenantDb,
+  type UncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
-import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type JobHandlerFn,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import {
@@ -104,6 +117,22 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     return existing;
   }
 
+  const sdbCache = new Map<TenantId, UncheckedSystemDb>();
+  function sdbFor(tenantId: TenantId): UncheckedSystemDb {
+    let existing = sdbCache.get(tenantId);
+    if (!existing) {
+      existing = createUncheckedSystemDb(tdbFor(tenantId));
+      sdbCache.set(tenantId, existing);
+    }
+    return existing;
+  }
+
+  // Standalone from sdbCache/tdbCache on purpose: this one is only ever used
+  // 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"));
+
   type ConfigRow = {
     id: string;
     key: string;
@@ -115,27 +144,51 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
   let alreadyCurrent = 0;
   const targetVersion = provider.currentVersion();
 
+  type BucketedRow = { tenantId: TenantId; row: ConfigRow };
+
   // ponytail: one full candidate scan — config rows are operator-scale
   // (tenants × encrypted keys), cursor pagination when that ever changes.
-  // Served to the shared loop in slices so its deadline/signal/failure
-  // checks run between chunks, not only once.
-  let pending: ConfigRow[] | undefined;
-  async function nextBatch(): Promise<readonly ConfigRow[]> {
-    if (pending === undefined) {
-      pending =
-        encryptedKeys.length === 0
-          ? []
-          : [
-              ...(await selectMany<ConfigRow>(db, configValuesTable, {
-                key: { in: encryptedKeys },
-              })),
-            ];
+  // Bucketed by tenant so each row keeps its bucket's tenant attached
+  // (assertRowsTenant below re-checks that against the row's own field
+  // right before the write) and the shared loop's deadline/signal/failure
+  // checks still run between chunks, not only once.
+  let buckets: Map<TenantId, ConfigRow[]> | undefined;
+  async function loadBuckets(): Promise<Map<TenantId, ConfigRow[]>> {
+    if (buckets) return buckets;
+    const grouped = new Map<TenantId, ConfigRow[]>();
+    if (encryptedKeys.length > 0) {
+      const scanned = await scanDb
+        .acknowledgeCrossTenant("system-wide key rotation")
+        .selectMany<ConfigRow>(configValuesTable, { key: { in: encryptedKeys } });
+      for (const row of scanned) {
+        const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+        const bucket = grouped.get(tenantId);
+        if (bucket) bucket.push(row);
+        else grouped.set(tenantId, [row]);
+      }
+    }
+    buckets = grouped;
+    return buckets;
+  }
+
+  async function nextBatch(): Promise<readonly BucketedRow[]> {
+    const grouped = await loadBuckets();
+    for (const [tenantId, rows] of grouped) {
+      if (rows.length === 0) {
+        grouped.delete(tenantId);
+        continue;
+      }
+      const slice = rows.splice(0, SCAN_SLICE_SIZE);
+      if (rows.length === 0) grouped.delete(tenantId);
+      return slice.map((row) => ({ tenantId, row }));
     }
-    const slice = pending;
-    return slice.splice(0, SCAN_SLICE_SIZE);
+    return [];
   }
 
-  async function migrateRow(row: ConfigRow): Promise<"migrated" | "skipped" | "failed"> {
+  async function migrateRow({
+    tenantId,
+    row,
+  }: BucketedRow): Promise<"migrated" | "skipped" | "failed"> {
     if (row.value === null || row.value === undefined) return "skipped";
     const classification = classifyStoredEnvelope(row.value, targetVersion);
     if (classification === "current") {
@@ -154,7 +207,12 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
       return "failed";
     }
 
-    const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+    // Re-verify the row's own tenantId against the bucket it was scanned
+    // into, right before the write (framework#2072) — a mismatch here
+    // fails this row only (via onRowError below), it does not abort the
+    // whole job.
+    sdbFor(tenantId).assertRowsTenant([row], "tenantId");
+
     const plaintext = await cipher.decrypt(row.value, { tenantId });
     const reencrypted = await cipher.encrypt(plaintext, { tenantId });
 
@@ -177,13 +235,13 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     return "migrated";
   }
 
-  const outcome = await runChunkedMigration<ConfigRow>({
+  const outcome = await runChunkedMigration<BucketedRow>({
     nextBatch,
     migrateRow,
     maxFailures,
     deadlineAt: deadline,
     signal: ctx.signal,
-    onRowError: (row, err) => {
+    onRowError: ({ row }, err) => {
       ctx.log?.warn?.(`[config:reencrypt] failed to re-encrypt row ${row.id}`, { err });
     },
   });

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

@@ -6,7 +6,7 @@ import {
   isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
-import { requireConfigResolver } from "../feature";
+import { requireConfigResolver, requireSystemDb } from "../feature";
 import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
 import { hasConfigAccess } from "../write-helpers";
 
@@ -16,7 +16,7 @@ export const valuesQuery = defineQueryHandler({
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const db = ctx.db;
+    const db = requireSystemDb(ctx, "config:query:values", query.user.tenantId);
     const registry = ctx.registry;
     const resolver = requireConfigResolver(ctx, "config:query:values");
 

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

@@ -9,7 +9,7 @@ import {
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
-import { DELIVERY_LOG_SCREEN_ID, DeliveryQueries } from "../constants";
+import { DELIVERY_LOG_SCREEN_ID, DeliveryHandlers, DeliveryQueries } from "../constants";
 import { createDeliveryFeature } from "../feature";
 import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
 
@@ -104,3 +104,46 @@ describe("delivery log tenant isolation", () => {
     expect(res.rows.some((r) => r.tenantId === tenantB)).toBe(false);
   });
 });
+
+describe("delivery preferences tenant isolation", () => {
+  // A userId is not tenant-unique — the same person can be a member of
+  // several tenants (tenant:write:add-member takes {userId, tenantId}).
+  // delivery runs in system-scope, so the preferences query handler must
+  // filter by tenantId too — otherwise setting a preference in tenant A
+  // leaks into (or gets read from) tenant B for the same userId.
+  test("user only sees their own tenant's preference for a shared userId", async () => {
+    const tenantA = testTenantId(31);
+    const tenantB = testTenantId(32);
+    const sharedUser = 41;
+    const userInTenantA = createTestUser({ id: sharedUser, roles: ["User"], tenantId: tenantA });
+    const userInTenantB = createTestUser({ id: sharedUser, roles: ["User"], tenantId: tenantB });
+    expect(userInTenantA.id).toBe(userInTenantB.id);
+
+    await stack.http.writeOk(
+      DeliveryHandlers.setPreference,
+      { notificationType: "welcome", channel: "email", enabled: false },
+      userInTenantA,
+    );
+    await stack.http.writeOk(
+      DeliveryHandlers.setPreference,
+      { notificationType: "welcome", channel: "push", enabled: false },
+      userInTenantB,
+    );
+
+    const resA = await stack.http.queryOk<{ rows: readonly { channel: string }[] }>(
+      DeliveryQueries.preferences,
+      {},
+      userInTenantA,
+    );
+    expect(resA.rows.length).toBeGreaterThan(0);
+    expect(resA.rows.every((r) => r.channel === "email")).toBe(true);
+
+    const resB = await stack.http.queryOk<{ rows: readonly { channel: string }[] }>(
+      DeliveryQueries.preferences,
+      {},
+      userInTenantB,
+    );
+    expect(resB.rows.length).toBeGreaterThan(0);
+    expect(resB.rows.every((r) => r.channel === "push")).toBe(true);
+  });
+});

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

@@ -1,7 +1,12 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+  createUncheckedSystemDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
   createTextField,
@@ -10,6 +15,7 @@ import {
   type JobContext,
   type NotifyFn,
   qn,
+  type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import {
@@ -17,6 +23,7 @@ import {
   setupTestStack,
   type TestStack,
   TestUsers,
+  testTenantId,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { z } from "zod";
@@ -40,7 +47,7 @@ import { tenantEntity } from "../../tenant/schema/tenant";
 import { DeliveryHandlers, DeliveryJobs, DeliveryQueries } from "../constants";
 import { collectChannels, createDeliveryService } from "../delivery-service";
 import { createDeliveryFeature } from "../feature";
-import { deliveryRenderJob } from "../jobs";
+import { deliveryRenderJob, deliverySendJob } from "../jobs";
 import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
 import { createDeliveryTestContext } from "../testing";
 import type { DeliveryService } from "../types";
@@ -1502,6 +1509,14 @@ describe("flow 17: async render→send pipeline", () => {
     expect(emailRows.some((r) => r["status"] === "sent")).toBe(true);
   });
 
+  // Mirrors what job-runner.ts's handleJob really builds for a
+  // r.systemScope()'d job (framework#2105) — a real TenantDb wrapped by
+  // createUncheckedSystemDb, not a mock, so requireTenantScopedDeps'
+  // assertTenantMatch() call exercises the actual production code path.
+  function makeSystemDb(tenantId: TenantId) {
+    return createUncheckedSystemDb(createTenantDb(db, tenantId, "system"));
+  }
+
   test("delivery.render on a channel without a render step records failed and does not dispatch send", async () => {
     const { runner, dispatched } = makeStubRunner();
     const attemptId = "00000000-0000-4000-8000-0000000000aa";
@@ -1518,7 +1533,12 @@ describe("flow 17: async render→send pipeline", () => {
           message: { notificationType: "app:notify:render-isolation", title: "X" },
         },
         // @cast-boundary test-seam — job throws before touching systemUser/log/write/queryAs
-        { db, registry: stack.registry, jobRunner: runner } as unknown as JobContext,
+        {
+          db,
+          registry: stack.registry,
+          jobRunner: runner,
+          systemDb: makeSystemDb(admin.tenantId),
+        } as unknown as JobContext,
       ),
     ).rejects.toThrow(/no render step/);
 
@@ -1529,6 +1549,77 @@ describe("flow 17: async render→send pipeline", () => {
     });
     expect(rows.some((r) => r["status"] === "failed")).toBe(true);
   });
+
+  // The regression this diff exists to prevent: a payload.tenantId that
+  // doesn't match the systemDb's own tenant must be rejected, not silently
+  // used to read/write another tenant's stream (what ctx.db without
+  // assertTenantMatch would have allowed).
+  test("job handlers throw when payload.tenantId doesn't match ctx.systemDb's tenant", async () => {
+    const { runner, dispatched } = makeStubRunner();
+    const foreignTenantId = testTenantId(999);
+    const attemptId = "00000000-0000-4000-8000-0000000000cc";
+    // @cast-boundary test-seam — mirrors job-runner.ts's real systemDb shape
+    const ctxWithMismatchedSystemDb = {
+      db,
+      registry: stack.registry,
+      jobRunner: runner,
+      systemDb: makeSystemDb(admin.tenantId),
+    } as unknown as JobContext;
+
+    await expect(
+      deliveryRenderJob(
+        {
+          channelName: "email",
+          address: testEmail(asyncRecipient),
+          tenantId: foreignTenantId,
+          recipientId: String(asyncRecipient),
+          notificationType: "app:notify:cross-tenant",
+          deliveryAttemptId: attemptId,
+          priority: "normal",
+          message: { notificationType: "app:notify:cross-tenant", title: "X" },
+        },
+        ctxWithMismatchedSystemDb,
+      ),
+    ).rejects.toThrow(/tenant self-check failed/);
+
+    expect(dispatched).toHaveLength(0);
+    const rows = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:cross-tenant",
+    });
+    expect(rows).toHaveLength(0);
+  });
+
+  // Unreachable via real dispatch (job-runner.ts only omits systemDb for jobs
+  // whose feature is NOT r.systemScope()'d, and delivery always is) — this
+  // exercises requireTenantScopedDeps' own defensive guard directly, the
+  // same way the missing-render-step case above exercises resolveChannel's.
+  test("job handlers throw when ctx.systemDb is missing on a system-scoped job", async () => {
+    const { runner } = makeStubRunner();
+    const attemptId = "00000000-0000-4000-8000-0000000000bb";
+    const payload = {
+      channelName: "email",
+      address: testEmail(asyncRecipient),
+      tenantId: admin.tenantId,
+      recipientId: String(asyncRecipient),
+      notificationType: "app:notify:missing-systemdb",
+      deliveryAttemptId: attemptId,
+      priority: "normal" as const,
+      message: { notificationType: "app:notify:missing-systemdb", title: "X" },
+    };
+    // @cast-boundary test-seam — no systemDb, unlike what job-runner.ts actually wires
+    const ctxWithoutSystemDb = {
+      db,
+      registry: stack.registry,
+      jobRunner: runner,
+    } as unknown as JobContext;
+
+    await expect(deliveryRenderJob(payload, ctxWithoutSystemDb)).rejects.toThrow(
+      /ctx\.systemDb missing/,
+    );
+    await expect(deliverySendJob(payload, ctxWithoutSystemDb)).rejects.toThrow(
+      /ctx\.systemDb missing/,
+    );
+  });
 });
 
 // --- Flow 18: priority maps onto the BullMQ job priority ---

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

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { decryptStoredPii } from "../../shared";
 import { deliveryAttemptsTable } from "../tables";
@@ -11,11 +12,16 @@ export const logQuery = defineQueryHandler({
   }),
   access: { roles: access.admin },
   handler: async (query, ctx) => {
-    // delivery runs in system-scope (feature.ts r.systemScope()), so ctx.db is
-    // NOT auto-tenant-filtered — filter explicitly or a tenant admin reads every
-    // tenant's attempts (with decrypted recipient PII below).
+    if (!ctx.systemDb) {
+      throw new InternalError({ message: "delivery log handler requires ctx.systemDb" });
+    }
+    // delivery is r.systemScope()'d, so the TenantDb is system-mode (reads
+    // unfiltered). assertTenantMatch is a self-check on the caller's own
+    // tenantId, not a query filter — it returns that same unfiltered db, so
+    // the explicit `where` below still does the actual tenant scoping.
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
     const rows = await selectMany(
-      ctx.db,
+      db,
       deliveryAttemptsTable,
       { tenantId: query.user.tenantId },
       {

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

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { notificationPreferencesTable } from "../tables";
 
@@ -8,7 +9,19 @@ export const preferencesQuery = defineQueryHandler({
   schema: z.object({}),
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const rows = await selectMany(ctx.db, notificationPreferencesTable, { userId: query.user.id });
+    // delivery runs in system-scope, so ctx.db is not auto-tenant-filtered —
+    // userId alone is not tenant-unique, so a userId-only filter here leaked preferences cross-tenant.
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "preferences: ctx.systemDb missing on a system-scoped handler",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+
+    const rows = await selectMany(db, notificationPreferencesTable, {
+      tenantId: query.user.tenantId,
+      userId: query.user.id,
+    });
 
     return { rows };
   },

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

@@ -1,4 +1,5 @@
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { upsertPreference } from "../upsert-preference";
 
@@ -15,7 +16,17 @@ export const setPreferenceWrite = defineWriteHandler({
     const { notificationType, channel, enabled } = event.payload;
     const { id: userId, tenantId } = event.user;
 
-    const result = await upsertPreference(ctx.db, event.user, {
+    // delivery runs in system-scope (feature.ts r.systemScope()) — ctx.systemDb
+    // is guaranteed there. No client-supplied userId exists on this payload;
+    // assertTenantMatch is the enforcement path that keeps it that way.
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "setPreference: ctx.systemDb missing on a system-scoped handler",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(tenantId);
+
+    const result = await upsertPreference(db, event.user, {
       tenantId,
       userId,
       notificationType,

package/src/delivery/jobs.ts

@@ -7,11 +7,12 @@
 
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type {
-  AppContext,
+  JobContext,
   JobHandlerFn,
   Registry,
   TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import { z } from "zod";
 import { appendAttemptEvent } from "./attempt-log";
@@ -44,13 +45,22 @@ const sendJobPayloadSchema = renderJobPayloadSchema.extend({
 
 type RenderJobPayload = z.infer<typeof renderJobPayloadSchema>;
 
-function requireDeps(ctx: AppContext): { db: DbConnection; registry: Registry } {
+function requireTenantScopedDeps(
+  ctx: JobContext,
+  tenantId: TenantId,
+): { db: DbConnection; registry: Registry } {
   const registry = ctx.registry;
   if (!registry) throw new Error("delivery job: missing registry in job context");
-  // Job context provides the raw system connection (not tenant-scoped); the
-  // append + projection layer scopes per event payload.
-  const db = ctx.db as DbConnection; // @cast-boundary engine-bridge — job ctx db is the system connection
-  if (!db) throw new Error("delivery job: missing db in job context");
+  // delivery is r.systemScope()'d (feature.ts), so JobContext.systemDb is
+  // guaranteed here. assertTenantMatch(tenantId).raw hands appendAttemptEvent/
+  // buildChannelContext the underlying DbConnection — safe because both
+  // filter by the same tenantId themselves (see JobContext.systemDb doc).
+  if (!ctx.systemDb) {
+    throw new InternalError({
+      message: "delivery job: ctx.systemDb missing on a system-scoped job",
+    });
+  }
+  const db = ctx.systemDb.assertTenantMatch(tenantId).raw as DbConnection; // @cast-boundary db-operator — TenantDb.raw is DbRunner, jobs never run inside a DbTx
   return { db, registry };
 }
 
@@ -96,9 +106,9 @@ function messageOf(err: unknown): string {
 // the send step is never reached, so a stuck render can't half-send.
 export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
   const p = renderJobPayloadSchema.parse(payload);
-  const { db, registry } = requireDeps(ctx);
-  const channel = resolveChannel(registry, p.channelName);
   const tenantId = p.tenantId as TenantId; // @cast-boundary engine-payload — stream tenant
+  const { db, registry } = requireTenantScopedDeps(ctx, tenantId);
+  const channel = resolveChannel(registry, p.channelName);
   const channelCtx = buildChannelContext(db, registry, undefined, tenantId);
 
   try {
@@ -128,9 +138,9 @@ export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
 // the same already-rendered HTML — no re-render needed.
 export const deliverySendJob: JobHandlerFn = async (payload, ctx) => {
   const p = sendJobPayloadSchema.parse(payload);
-  const { db, registry } = requireDeps(ctx);
-  const channel = resolveChannel(registry, p.channelName);
   const tenantId = p.tenantId as TenantId; // @cast-boundary engine-payload — stream tenant
+  const { db, registry } = requireTenantScopedDeps(ctx, tenantId);
+  const channel = resolveChannel(registry, p.channelName);
   const channelCtx = buildChannelContext(db, registry, undefined, tenantId);
 
   try {

package/src/feature-toggles/__tests__/acknowledge-cross-tenant.test.ts

@@ -0,0 +1,23 @@
+// framework#2076: set.write / registered.query / list.query all read/write
+// globalFeatureStateTable via ctx.systemDb.acknowledgeCrossTenant(...) instead
+// of ctx.db directly. That only resolves correctly as long as the
+// feature-toggles feature stays r.systemScope() (feature.ts) — buildHandlerContext
+// only populates ctx.systemDb for system-scoped handlers (dispatch-shared.ts).
+// This test pins that coupling so a future refactor that drops r.systemScope()
+// fails loudly here instead of surfacing as "undefined.acknowledgeCrossTenant"
+// deep inside a handler.
+
+import { describe, expect, test } from "bun:test";
+import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { FeatureToggleHandlers, FeatureToggleQueries } from "../constants";
+import { createFeatureTogglesFeature } from "../feature";
+
+describe("feature-toggles handlers stay r.systemScope()-coupled", () => {
+  const registry = createRegistry([createFeatureTogglesFeature()]);
+
+  test("set/list/registered are all system-scoped", () => {
+    expect(registry.isHandlerSystemScoped(FeatureToggleHandlers.set)).toBe(true);
+    expect(registry.isHandlerSystemScoped(FeatureToggleQueries.list)).toBe(true);
+    expect(registry.isHandlerSystemScoped(FeatureToggleQueries.registered)).toBe(true);
+  });
+});

package/src/feature-toggles/constants.ts

@@ -10,6 +10,12 @@ export const FEATURE_TOGGLE_SET_EVENT_NAME = "feature-toggles:event:toggle-set";
 // "feature-toggles" in its aggregate_type column.
 export const FEATURE_TOGGLE_AGGREGATE_TYPE = "feature-toggles";
 
+// Shared acknowledgeCrossTenant() reason across all three handlers that read
+// or write globalFeatureStateTable — one string so the three call sites
+// can't drift (framework#2076).
+export const FEATURE_TOGGLE_CROSS_TENANT_REASON =
+  "global feature-toggle state, no tenant scope by design";
+
 // Error reasons surfaced from feature-toggle handlers. Scoped to the
 // feature's namespace per the framework's reason-convention.
 export const FeatureToggleErrors = {

package/src/feature-toggles/handlers/list.query.ts

@@ -1,6 +1,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { FEATURE_TOGGLE_CROSS_TENANT_REASON } from "../constants";
 import { globalFeatureStateTable } from "../global-feature-state-table";
 
 // List every row in the global_feature_state table — i.e. every feature
@@ -12,6 +13,16 @@ export const listQuery = defineQueryHandler({
   schema: z.object({}),
   access: { roles: ["SystemAdmin"] },
   handler: async (_event, ctx) => {
+    // ctx.systemDb is populated for r.systemScope() handlers only (feature.ts
+    // declares it) — guarded instead of asserted, see set.write.ts Guard 0.5.
+    if (!ctx.systemDb) {
+      throw new Error(
+        "[feature-toggles] list-query requires ctx.systemDb — the feature-toggles " +
+          "feature must stay r.systemScope() (see feature.ts).",
+      );
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(FEATURE_TOGGLE_CROSS_TENANT_REASON);
+
     type Row = {
       featureName: string;
       enabled: boolean;
@@ -19,7 +30,7 @@ export const listQuery = defineQueryHandler({
       updatedAt: Temporal.Instant;
       updatedBy: string;
     };
-    const rows = await selectMany<Row>(ctx.db.raw, globalFeatureStateTable);
+    const rows = await selectMany<Row>(db.raw, globalFeatureStateTable);
     return {
       items: rows.map((r) => ({
         featureName: r.featureName,

package/src/feature-toggles/handlers/registered.query.ts

@@ -1,6 +1,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { FEATURE_TOGGLE_CROSS_TENANT_REASON } from "../constants";
 import { globalFeatureStateTable } from "../global-feature-state-table";
 
 // Inventory of every registered feature, annotated with toggle metadata
@@ -16,8 +17,18 @@ export const registeredQuery = defineQueryHandler({
   schema: z.object({}),
   access: { roles: ["SystemAdmin"] },
   handler: async (_event, ctx) => {
+    // ctx.systemDb is populated for r.systemScope() handlers only (feature.ts
+    // declares it) — guarded instead of asserted, see set.write.ts Guard 0.5.
+    if (!ctx.systemDb) {
+      throw new Error(
+        "[feature-toggles] registered-query requires ctx.systemDb — the feature-toggles " +
+          "feature must stay r.systemScope() (see feature.ts).",
+      );
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(FEATURE_TOGGLE_CROSS_TENANT_REASON);
+
     type OverrideRow = { featureName: string; enabled: boolean };
-    const overrideRows = await selectMany<OverrideRow>(ctx.db.raw, globalFeatureStateTable);
+    const overrideRows = await selectMany<OverrideRow>(db.raw, globalFeatureStateTable);
     const overrides = new Map(overrideRows.map((r) => [r.featureName, r.enabled]));
 
     // SystemAdmin operator-tooling: das listing soll die PLATTFORM-truth