@cosmicdrift/kumiko-bundled-features 0.198.0 → 0.199.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.198.0",
+  "version": "0.199.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -125,12 +125,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.198.0",
-    "@cosmicdrift/kumiko-framework": "0.198.0",
-    "@cosmicdrift/kumiko-headless": "0.198.0",
-    "@cosmicdrift/kumiko-renderer": "0.198.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.198.0",
-    "@cosmicdrift/kumiko-types": "0.198.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.199.0",
+    "@cosmicdrift/kumiko-framework": "0.199.0",
+    "@cosmicdrift/kumiko-headless": "0.199.0",
+    "@cosmicdrift/kumiko-renderer": "0.199.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.199.0",
+    "@cosmicdrift/kumiko-types": "0.199.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",

package/src/compliance-profiles/__tests__/compliance-profiles.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { access } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
@@ -306,3 +307,89 @@ describe("compliance-profiles :: needs-profile (S1.5 — Onboarding-Banner)", ()
     expect(result.status).toBe(403);
   });
 });
+
+describe("compliance-profiles :: needs-profile mit access.systemAdmin-Narrowing (#2063)", () => {
+  let narrowedStack: TestStack;
+  let narrowedDb: DbConnection;
+
+  beforeAll(async () => {
+    const narrowedFeature = createComplianceProfilesFeature({ access: access.systemAdmin });
+    narrowedStack = await setupTestStack({ features: [narrowedFeature] });
+    narrowedDb = narrowedStack.db;
+    await unsafeCreateEntityTable(narrowedDb, tenantComplianceProfileEntity);
+    await createEventsTable(narrowedDb);
+  });
+
+  afterAll(async () => {
+    await narrowedStack.cleanup();
+  });
+
+  // TenantAdmin can no longer reach the picker screen (access.systemAdmin
+  // excludes TenantAdmin) — needsSelection must stop pointing them at a
+  // screen they can't open.
+  test("TenantAdmin ohne Picker-Zugriff → needsSelection bleibt false, reason=picker_not_accessible_for_role", async () => {
+    const excludedTenantAdmin = createIsolatedTenantAdmin(200);
+    const result = await narrowedStack.http.queryOk<{
+      needsSelection: boolean;
+      currentProfile: string | null;
+      reason?: string;
+    }>(NEEDS_PROFILE, {}, excludedTenantAdmin);
+    expect(result.needsSelection).toBe(false);
+    expect(result.currentProfile).toBeNull();
+    expect(result.reason).toBe("picker_not_accessible_for_role");
+  });
+
+  // A user holding both roles can still reach the picker via SystemAdmin —
+  // the gate must intersect the caller's actual roles, not just check
+  // whether TenantAdmin (the query's fixed call-access role) is among the
+  // feature's configured picker roles.
+  test("TenantAdmin+SystemAdmin dual-role → needsSelection bleibt true (Picker via SystemAdmin erreichbar)", async () => {
+    const dualRoleUser = createTestUser({
+      id: 204,
+      tenantId: testTenantId(204),
+      roles: ["TenantAdmin", "SystemAdmin"],
+    });
+    const result = await narrowedStack.http.queryOk<{
+      needsSelection: boolean;
+      currentProfile: string | null;
+      reason?: string;
+    }>(NEEDS_PROFILE, {}, dualRoleUser);
+    expect(result.needsSelection).toBe(true);
+    expect(result.reason).toBe("no_profile_selected");
+  });
+
+  // The needs-profile call access itself stays TenantAdmin-only — the
+  // `access` option is not passed 1:1 to the query dispatcher (otherwise
+  // SystemAdmin could now call an endpoint only TenantAdmin used to be
+  // allowed to call — a widening #2063 does not ask for).
+  test("SystemAdmin darf needs-profile weiterhin nicht aufrufen (Call-Access unveraendert)", async () => {
+    const systemAdmin = createTestUser({
+      id: 201,
+      tenantId: testTenantId(201),
+      roles: ["SystemAdmin"],
+    });
+    const result = await narrowedStack.http.query(NEEDS_PROFILE, {}, systemAdmin);
+    expect(result.status).toBe(403);
+  });
+
+  test("TenantAdmin mit bereits gesetztem Profile → needsSelection bleibt false, kein reason-Sonderfall", async () => {
+    const setupAdmin = createIsolatedTenantAdmin(202);
+    // set-profile is also narrowed to access.systemAdmin — set up via
+    // SystemAdmin to create the profile row for the read test.
+    const systemAdminSetup = createTestUser({
+      id: 203,
+      tenantId: setupAdmin.tenantId,
+      roles: ["SystemAdmin"],
+    });
+    await narrowedStack.http.writeOk(SET_PROFILE, { profileKey: "eu-dsgvo" }, systemAdminSetup);
+
+    const result = await narrowedStack.http.queryOk<{
+      needsSelection: boolean;
+      currentProfile: string | null;
+      reason?: string;
+    }>(NEEDS_PROFILE, {}, setupAdmin);
+    expect(result.needsSelection).toBe(false);
+    expect(result.currentProfile).toBe("eu-dsgvo");
+    expect(result.reason).toBeUndefined();
+  });
+});

package/src/compliance-profiles/feature.ts

@@ -6,7 +6,7 @@ import {
 import { COMPLIANCE_PROFILE_SCREEN_ID } from "./constants";
 import { forTenantQuery } from "./handlers/for-tenant.query";
 import { listProfilesQuery } from "./handlers/list-profiles.query";
-import { needsProfileQuery } from "./handlers/needs-profile.query";
+import { createNeedsProfileQuery } from "./handlers/needs-profile.query";
 import { setProfileWrite } from "./handlers/set-profile.write";
 import { subProcessorsQuery } from "./handlers/sub-processors.query";
 import { COMPLIANCE_PROFILES_I18N } from "./i18n";
@@ -70,7 +70,7 @@ export function createComplianceProfilesFeature(
       forTenant: r.queryHandler(forTenantQuery),
       listProfiles: r.queryHandler(listProfilesQuery),
       subProcessors: r.queryHandler(subProcessorsQuery),
-      needsProfile: r.queryHandler(needsProfileQuery),
+      needsProfile: r.queryHandler(createNeedsProfileQuery(resolvedAccess)),
     };
 
     r.screen({

package/src/compliance-profiles/handlers/needs-profile.query.ts

@@ -5,49 +5,69 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { tenantComplianceProfileTable } from "../schema/profile-selection";
 
-// Onboarding-Banner-Trigger fuer Tenant-Admin.
+// Onboarding banner trigger for tenant admin.
 //
-// Sprint 1.5 — minimaler API-Endpoint, UI-Banner kommt in einem
-// spaeteren UI-Sprint. Reine Read-Query: gibt es einen Eintrag in
-// tenantComplianceProfile fuer den aktuellen Tenant?
+// Sprint 1.5 — minimal API endpoint, the UI banner comes in a later UI
+// sprint. Pure read query: does an entry exist in tenantComplianceProfile
+// for the current tenant?
 //
-// Wenn nein → Tenant-Admin muss Profile waehlen (Pflicht beim
-// Onboarding). Bis zur Wahl laeuft minimal-no-region mit warning,
-// das in der Tenant-Dashboard-Banner sichtbar gemacht werden soll.
+// If not → tenant admin must pick a profile (mandatory during onboarding).
+// Until picked, minimal-no-region runs with a warning that should surface
+// in the tenant dashboard banner.
 //
-// Access: TenantAdmin only — der Banner ist nur fuer Tenant-Admins
-// relevant, nicht fuer normale Member.
-export const needsProfileQuery = defineQueryHandler({
-  name: "needs-profile",
-  schema: z.object({}),
-  access: { roles: [ROLES.TenantAdmin] },
-  handler: async (query, ctx): Promise<NeedsProfileResponse> => {
-    const row = (await fetchOne(ctx.db, tenantComplianceProfileTable, {
-      tenantId: query.user.tenantId,
-    })) as { profileKey: ComplianceProfileKey } | null; // @cast-boundary db-runner
+// Access: TenantAdmin only — the banner is only relevant to tenant admins,
+// not regular members. Stays hard-coded to TenantAdmin (not the `access`
+// option of createComplianceProfilesFeature) — passing the option through
+// would widen call access by default to all three access.admin roles
+// (including SystemAdmin). Instead the handler takes `pickerReachableRoles`
+// and deliberately resolves the #2063 special case: if the *caller's*
+// roles no longer intersect the picker's `access` option, the query stops
+// reporting needsSelection — otherwise a tenant admin would be told to
+// open a screen they can't reach.
+export function createNeedsProfileQuery(pickerReachableRoles: readonly string[]) {
+  return defineQueryHandler({
+    name: "needs-profile",
+    schema: z.object({}),
+    access: { roles: [ROLES.TenantAdmin] },
+    handler: async (query, ctx): Promise<NeedsProfileResponse> => {
+      const row = (await fetchOne(ctx.db, tenantComplianceProfileTable, {
+        tenantId: query.user.tenantId,
+      })) as { profileKey: ComplianceProfileKey } | null; // @cast-boundary db-runner
+
+      if (row) {
+        // S1.7 X1: minimal-no-region is no longer settable via set-profile
+        // (Zod). If Sprint 2 ships a seedComplianceProfile helper that
+        // reintroduces the migration edge case, a defensive path belongs
+        // here again — until then, every existing entry is a deliberately
+        // chosen production profile.
+        return {
+          needsSelection: false,
+          currentProfile: row.profileKey,
+        };
+      }
+
+      const callerCanReachPicker = query.user.roles.some((role) =>
+        pickerReachableRoles.includes(role),
+      );
+      if (!callerCanReachPicker) {
+        return {
+          needsSelection: false,
+          currentProfile: null,
+          reason: "picker_not_accessible_for_role",
+        };
+      }
 
-    if (!row) {
       return {
         needsSelection: true,
         currentProfile: null,
         reason: "no_profile_selected",
       };
-    }
-
-    // S1.7 X1: minimal-no-region ist via set-profile (Zod) nicht mehr
-    // setzbar. Wenn Sprint 2 einen seedComplianceProfile-Helper liefert
-    // der den Migration-Edge-Case einführt, kommt hier wieder ein
-    // defensiver Pfad rein — bis dahin: jeder existierende Eintrag ist
-    // ein bewusst gewähltes Production-Profile.
-    return {
-      needsSelection: false,
-      currentProfile: row.profileKey,
-    };
-  },
-});
+    },
+  });
+}
 
 interface NeedsProfileResponse {
   readonly needsSelection: boolean;
   readonly currentProfile: ComplianceProfileKey | null;
-  readonly reason?: "no_profile_selected";
+  readonly reason?: "no_profile_selected" | "picker_not_accessible_for_role";
 }

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

@@ -0,0 +1,185 @@
+// Regression guard for kumiko-framework#2072: the KEK-rotation job's
+// systemScope() fail-closed checks — createUncheckedSystemDb().
+// acknowledgeCrossTenant() gating the initial cross-tenant scan,
+// assertRowsTenant() re-verifying each per-tenant slice before it's served
+// to the write loop — must not block legitimate multi-tenant rotation. A
+// systemDb accidentally bound to the wrong tenant (e.g. always
+// SYSTEM_TENANT_ID instead of the scanned row's own tenant) would make
+// every non-system-tenant row fail closed via assertRowsTenant, landing in
+// `failed` (not thrown — chunked-entity-migration.ts routes migrateRow
+// throws through onRowError) rather than `migrated`.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createSystemUser,
+  createTenantConfig,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEnvelopeCipher,
+  createEnvMasterKeyProvider,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createMutableMasterKeyProvider } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../feature";
+import { reencryptJob } from "../handlers/reencrypt.job";
+import { createConfigResolver } from "../resolver";
+import { configValueEntity, configValuesTable } from "../table";
+
+const KEY = "tenant-check-rot:config:secret-pass";
+const TENANT_A = testTenantId(201);
+const TENANT_B = testTenantId(202);
+
+const v1Key = randomBytes(32).toString("base64");
+const v2Key = randomBytes(32).toString("base64");
+const mutableProvider = createMutableMasterKeyProvider(
+  createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_V1: v1Key,
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+    },
+  }),
+);
+const cipher = createEnvelopeCipher(mutableProvider, {});
+const resolver = createConfigResolver({ cipher });
+
+const keyDef = createTenantConfig("text", {
+  encrypted: true,
+  read: access.admin,
+  write: access.admin,
+});
+
+const tenantCheckFeature = defineFeature("tenant-check-rot", (r) => {
+  r.requires("config");
+  r.config({ keys: { "secret-pass": keyDef } });
+});
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+let stack: TestStack;
+
+async function seedRow(tenantId: string, plaintext: string): Promise<void> {
+  const envelope = await cipher.encrypt(JSON.stringify(plaintext), { tenantId });
+  const systemUser = createSystemUser(tenantId);
+  const tdb = createTenantDb(stack.db, tenantId, "system");
+  const result = await executor.create(
+    { key: KEY, value: envelope, tenantId, userId: null },
+    systemUser,
+    tdb,
+  );
+  if (!result.isSuccess) throw new Error(`seed failed: ${result.error.code}`);
+}
+
+type RawConfigRow = { value: string; tenantId: string };
+
+async function readRawValues(): Promise<readonly RawConfigRow[]> {
+  return await selectMany<RawConfigRow>(stack.db, configValuesTable, { key: KEY });
+}
+
+type CapturedLog = { info: string[]; warn: string[] };
+
+type TestJobLog = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: () => void;
+  debug: () => void;
+  child: () => TestJobLog;
+};
+
+function capturingLog(captured: CapturedLog): TestJobLog {
+  const log: TestJobLog = {
+    info: (msg) => captured.info.push(msg),
+    warn: (msg) => captured.warn.push(msg),
+    error: () => {},
+    debug: () => {},
+    child: () => log,
+  };
+  return log;
+}
+
+function jobCtx(captured: CapturedLog): Parameters<typeof reencryptJob>[1] {
+  return {
+    db: stack.db,
+    registry: stack.registry,
+    masterKeyProvider: mutableProvider,
+    configEncryption: cipher,
+    log: capturingLog(captured),
+  } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/configEncryption/log
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createConfigFeature(), tenantCheckFeature],
+    masterKeyProvider: mutableProvider,
+    extraContext: { configResolver: resolver, configEncryption: cipher },
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+  await seedRow(TENANT_A, "tenant-a-secret");
+  await seedRow(TENANT_B, "tenant-b-secret");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("config KEK-rotation job — multi-tenant scan + write checks (kumiko-framework#2072)", () => {
+  test("acknowledgeCrossTenant scan + per-tenant assertRowsTenant checks still rotate every tenant's row", async () => {
+    const beforeRows = await readRawValues();
+    expect(beforeRows).toHaveLength(2);
+    for (const row of beforeRows) {
+      expect(JSON.parse(row.value).kekVersion).toBe(1);
+    }
+
+    // "ops added a new master key version and flipped CURRENT=2".
+    mutableProvider.replace(
+      createEnvMasterKeyProvider({
+        env: {
+          KUMIKO_SECRETS_MASTER_KEY_V1: v1Key,
+          KUMIKO_SECRETS_MASTER_KEY_V2: v2Key,
+          KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+        },
+      }),
+    );
+
+    const captured: CapturedLog = { info: [], warn: [] };
+    await reencryptJob({}, jobCtx(captured));
+
+    // 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([]);
+
+    const completeLine = captured.info.find((line) =>
+      line.includes("[config:reencrypt] complete:"),
+    );
+    if (!completeLine) throw new Error("job did not log a completion summary");
+    const result = JSON.parse(completeLine.slice(completeLine.indexOf("{"))) as {
+      migrated: number;
+      failed: number;
+      alreadyCurrent: number;
+    };
+    expect(result.migrated).toBe(2);
+    expect(result.failed).toBe(0);
+    expect(result.alreadyCurrent).toBe(0);
+
+    const afterRows = await readRawValues();
+    expect(afterRows).toHaveLength(2);
+    for (const row of afterRows) {
+      expect(JSON.parse(row.value).kekVersion).toBe(2);
+    }
+
+    expect(await resolver.get(KEY, keyDef, TENANT_A, "u1", stack.db)).toBe("tenant-a-secret");
+    expect(await resolver.get(KEY, keyDef, TENANT_B, "u1", stack.db)).toBe("tenant-b-secret");
+  });
+});

package/src/config/__tests__/require-system-db.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createUncheckedSystemDb } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { requireSystemDb } from "../feature";
+
+// Minimal TenantDb stub — only .tenantId is read by assertTenantMatch /
+// createUncheckedSystemDb; the real db-query methods are never called by
+// requireSystemDb itself.
+function fakeTenantDb(tenantId: TenantId): TenantDb {
+  return { tenantId, mode: "system" } as unknown as TenantDb;
+}
+
+// Minimal HandlerContext stub — only .db / .systemDb are read by requireSystemDb.
+function contextStub(db: TenantDb, withSystemDb: boolean): HandlerContext {
+  return {
+    db,
+    systemDb: withSystemDb ? createUncheckedSystemDb(db) : undefined,
+    // biome-ignore lint/suspicious/noExplicitAny: rest of HandlerContext isn't touched by requireSystemDb.
+  } as any;
+}
+
+const TENANT_A = "tenant-a" as TenantId;
+const TENANT_B = "tenant-b" as TenantId;
+
+describe("requireSystemDb", () => {
+  test("throws InternalError when ctx.systemDb is missing", () => {
+    const ctx = contextStub(fakeTenantDb(TENANT_A), false);
+    expect(() => requireSystemDb(ctx, "config:query:test", TENANT_A)).toThrow(
+      /ctx\.systemDb missing/,
+    );
+  });
+
+  test("returns the underlying TenantDb when tenantId matches", () => {
+    const db = fakeTenantDb(TENANT_A);
+    const ctx = contextStub(db, true);
+    expect(requireSystemDb(ctx, "config:query:test", TENANT_A)).toBe(db);
+  });
+
+  test("fails closed with AccessDeniedError when tenantId does not match ctx.db's own tenant", () => {
+    const db = fakeTenantDb(TENANT_A);
+    const ctx = contextStub(db, true);
+    expect(() => requireSystemDb(ctx, "config:query:test", TENANT_B)).toThrow(AccessDeniedError);
+  });
+});

package/src/config/feature.ts

@@ -120,6 +120,34 @@ export function requireConfigResolver(ctx: HandlerContext, handlerName: string):
   return ctx.configResolver;
 }
 
+// Config declares r.systemScope() (raw ctx.db is unfiltered across tenants
+// in that mode), so config's own query handlers must go through ctx.systemDb's
+// explicit self-check instead of touching ctx.db directly. Only valid for
+// handlers dispatched as config:query:* — those always run under config's
+// own system-scoped context, so ctx.systemDb is never actually missing here;
+// the throw documents that invariant instead of silently degrading.
+// buildProviderSelectionGate / collectMissingRequiredConfig (readiness.query.ts)
+// are shared with the separate, plain tenant-scoped readiness feature, so they
+// take the already-scoped db as an explicit parameter instead of resolving it
+// themselves — each call site (config's own handler here, readiness's
+// status.query.ts) makes its own scope decision instead of this function
+// guessing from ctx.systemDb's presence.
+export function requireSystemDb(
+  ctx: HandlerContext,
+  handlerName: string,
+  tenantId: TenantId,
+): TenantDb {
+  if (!ctx.systemDb) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.systemDb missing — only present for r.systemScope() handlers; ` +
+        `the config feature declares r.systemScope() in feature.ts, so this points at a ` +
+        `pipeline wiring bug rather than a missing feature declaration.`,
+    });
+  }
+  return ctx.systemDb.assertTenantMatch(tenantId);
+}
+
 // Mirror of requireConfigResolver for the encryption round-trip side.
 // Only keys declared `encrypted: true` need this — the setter calls it
 // lazily so apps that never wire encryption still boot (and only crash

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

@@ -5,7 +5,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 cascadeQuery = defineQueryHandler({
   }),
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const db = ctx.db;
+    const db = requireSystemDb(ctx, "config:query:cascade", query.user.tenantId);
     const registry = ctx.registry;
     const resolver = requireConfigResolver(ctx, "config:query:cascade");
 

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

@@ -1,3 +1,4 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigKeyType,
   type ConfigScope,
@@ -7,7 +8,7 @@ import {
   toKebab,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
-import { requireConfigResolver } from "../feature";
+import { requireConfigResolver, requireSystemDb } from "../feature";
 import { hasConfigAccess } from "../write-helpers";
 
 export type ReadinessMissingKey = {
@@ -32,18 +33,23 @@ export type RequiredKeyGate = (qualifiedName: string) => boolean;
 // Builds the per-tenant gate from r.extensionSelector declarations: resolve
 // each selector through the config cascade, mark every provider-feature
 // registered under that point as counted/uncounted. Features without a
-// selector-gated registration always count.
+// selector-gated registration always count. `db` is the caller's own scoped
+// handle — config's own handlers pass requireSystemDb's result, the plain
+// tenant-scoped readiness feature passes its own ctx.db. This function makes
+// no scope decision itself; see readiness/handlers/status.query.ts and
+// config/handlers/readiness.query.ts's own handler for the two call sites.
 export async function buildProviderSelectionGate(
   ctx: HandlerContext,
   callerQn: string,
   user: SessionUser,
+  db: TenantDb,
 ): Promise<RequiredKeyGate> {
   const resolver = requireConfigResolver(ctx, callerQn);
   const countsByFeature = new Map<string, boolean>();
   for (const [extensionName, selectorKey] of ctx.registry.getAllExtensionSelectors()) {
     const keyDef = ctx.registry.getConfigKey(selectorKey);
     if (!keyDef) continue; // registry-build already failed this; defensive
-    const value = await resolver.get(selectorKey, keyDef, user.tenantId, user.id, ctx.db);
+    const value = await resolver.get(selectorKey, keyDef, user.tenantId, user.id, db);
     const selected = typeof value === "string" ? value.trim() : "";
     for (const usage of ctx.registry.getExtensionUsages(extensionName)) {
       if (usage.featureName === undefined) continue;
@@ -65,6 +71,7 @@ export async function collectMissingRequiredConfig(
   ctx: HandlerContext,
   callerQn: string,
   user: SessionUser,
+  db: TenantDb,
   gate?: RequiredKeyGate,
   options?: {
     /** Verdict-Pfade (Rollup, selbst role-gated) MÜSSEN ungefiltert zählen:
@@ -75,7 +82,7 @@ export async function collectMissingRequiredConfig(
   },
 ): Promise<ReadinessMissingKey[]> {
   const resolver = requireConfigResolver(ctx, callerQn);
-  const effectiveGate = gate ?? (await buildProviderSelectionGate(ctx, callerQn, user));
+  const effectiveGate = gate ?? (await buildProviderSelectionGate(ctx, callerQn, user, db));
   // Kandidaten erst sammeln, dann EIN Batch-Resolve — die sequentielle
   // resolver.get-Schleife war ein N+1 über alle required Keys (272/1).
   type KeyDef =
@@ -98,7 +105,7 @@ export async function collectMissingRequiredConfig(
     candidates,
     user.tenantId,
     user.id,
-    ctx.db,
+    db,
     ctx.secrets,
   );
   for (const [qualifiedKey, keyDef] of candidates) {
@@ -124,7 +131,13 @@ export const readinessQuery = defineQueryHandler({
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const missing = await collectMissingRequiredConfig(ctx, "config:query:readiness", query.user);
+    const db = requireSystemDb(ctx, "config:query:readiness", query.user.tenantId);
+    const missing = await collectMissingRequiredConfig(
+      ctx,
+      "config:query:readiness",
+      query.user,
+      db,
+    );
     return { missing };
   },
 });