@cosmicdrift/kumiko-bundled-features 0.199.2 → 0.200.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.199.2",
+  "version": "0.200.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>",
@@ -25,6 +25,7 @@
     "./admin-shell/web": "./src/admin-shell/web/index.ts",
     "./compliance-profiles": "./src/compliance-profiles/index.ts",
     "./compliance-profiles/web": "./src/compliance-profiles/web/index.ts",
+    "./compliance-profiles-ops": "./src/compliance-profiles-ops/index.ts",
     "./config": "./src/config/index.ts",
     "./crypto-shredding": "./src/crypto-shredding/index.ts",
     "./config/web": "./src/config/web/index.ts",
@@ -125,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.199.2",
-    "@cosmicdrift/kumiko-framework": "0.199.2",
-    "@cosmicdrift/kumiko-headless": "0.199.2",
-    "@cosmicdrift/kumiko-renderer": "0.199.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.199.2",
-    "@cosmicdrift/kumiko-types": "0.199.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.200.0",
+    "@cosmicdrift/kumiko-framework": "0.200.0",
+    "@cosmicdrift/kumiko-headless": "0.200.0",
+    "@cosmicdrift/kumiko-renderer": "0.200.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.200.0",
+    "@cosmicdrift/kumiko-types": "0.200.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",

package/src/compliance-profiles-ops/__tests__/ops.boot.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createConfigFeature } from "../../config/feature";
+import { createTenantFeature } from "../../tenant/feature";
+import { complianceProfilesOpsFeature } from "../index";
+
+describe("compliance-profiles-ops (#2089)", () => {
+  test("declares systemScope and requires compliance-profiles + tenant", () => {
+    expect(complianceProfilesOpsFeature.systemScope).toBe(true);
+    expect(complianceProfilesOpsFeature.requires).toContain("compliance-profiles");
+    expect(complianceProfilesOpsFeature.requires).toContain("tenant");
+  });
+
+  test("tenants-missing-profile is SystemAdmin-only", () => {
+    expect(
+      rolesOf(complianceProfilesOpsFeature.queryHandlers["tenants-missing-profile"]?.access),
+    ).toEqual(["SystemAdmin"]);
+  });
+
+  test("boot-validates alongside compliance-profiles + tenant + config", () => {
+    expect(() =>
+      validateBoot([
+        createConfigFeature(),
+        createTenantFeature(),
+        createComplianceProfilesFeature(),
+        complianceProfilesOpsFeature,
+      ]),
+    ).not.toThrow();
+  });
+
+  test("boot fails without tenant mounted (hard requires)", () => {
+    expect(() =>
+      validateBoot([
+        createConfigFeature(),
+        createComplianceProfilesFeature(),
+        complianceProfilesOpsFeature,
+      ]),
+    ).toThrow();
+  });
+});

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

@@ -0,0 +1,78 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { seedComplianceProfile } from "../../compliance-profiles/seeding";
+import { createConfigFeature } from "../../config/feature";
+import { TenantHandlers } from "../../tenant/constants";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { complianceProfilesOpsFeature } from "../index";
+
+const TENANTS_MISSING_PROFILE = "compliance-profiles-ops:query:tenants-missing-profile";
+
+let stack: TestStack;
+
+const opsAdmin = createTestUser({ id: 900, tenantId: testTenantId(900), roles: ["SystemAdmin"] });
+const tenantWithProfile = testTenantId(901);
+const tenantWithoutProfile = testTenantId(902);
+const disabledTenantWithoutProfile = testTenantId(903);
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      complianceProfilesOpsFeature,
+    ],
+  });
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+  await createEventsTable(stack.db);
+
+  for (const [id, key] of [
+    [tenantWithProfile, "with-profile"],
+    [tenantWithoutProfile, "without-profile"],
+    [disabledTenantWithoutProfile, "disabled-without-profile"],
+  ] as const) {
+    await stack.http.writeOk(TenantHandlers.create, { id, key, name: key }, opsAdmin);
+  }
+  await stack.http.writeOk(TenantHandlers.disable, { id: disabledTenantWithoutProfile }, opsAdmin);
+  await seedComplianceProfile(stack.db, { tenantId: tenantWithProfile, profileKey: "eu-dsgvo" });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("tenants-missing-profile (#2089)", () => {
+  test("SystemAdmin sees only the enabled tenant without a profile", async () => {
+    const result = await stack.http.queryOk<{
+      tenants: readonly { id: string; name: string }[];
+    }>(TENANTS_MISSING_PROFILE, {}, opsAdmin);
+
+    const ids = result.tenants.map((t) => t.id);
+    expect(ids).toContain(tenantWithoutProfile);
+    expect(ids).not.toContain(tenantWithProfile);
+    expect(ids).not.toContain(disabledTenantWithoutProfile);
+  });
+
+  test("TenantAdmin gets 403", async () => {
+    const tenantAdmin = createTestUser({
+      id: 904,
+      tenantId: tenantWithoutProfile,
+      roles: ["TenantAdmin"],
+    });
+    expect((await stack.http.query(TENANTS_MISSING_PROFILE, {}, tenantAdmin)).status).toBe(403);
+  });
+});

package/src/compliance-profiles-ops/handlers/tenants-missing-profile.query.ts

@@ -0,0 +1,54 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { defineQueryHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { tenantComplianceProfileTable } from "../../compliance-profiles";
+import { tenantTable } from "../../tenant";
+
+// SystemAdmin platform-wide counterpart to needs-profile (#2089).
+//
+// #2084 stopped needs-profile from nagging a TenantAdmin who can no longer
+// reach a picker narrowed to access.systemAdmin — correct, but it left no
+// one else able to notice: needs-profile stays TenantAdmin-only on purpose
+// (widening its call-access was explicitly rejected in #2084), so a
+// SystemAdmin who owns the platform-only picker has no way to see which
+// tenants still run on minimal-no-region. This query fills that gap
+// instead of touching needs-profile: every enabled tenant that has no row
+// in tenantComplianceProfile at all, tenant-wide rather than for the
+// caller's own tenant.
+export const tenantsMissingProfileQuery = defineQueryHandler({
+  name: "tenants-missing-profile",
+  schema: z.object({}),
+  access: { roles: [ROLES.SystemAdmin] },
+  handler: async (_query, ctx): Promise<TenantsMissingProfileResponse> => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "[compliance-profiles-ops] tenants-missing-profile requires ctx.systemDb — the " +
+          "compliance-profiles-ops feature must stay r.systemScope() (see feature.ts).",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "platform operator scans every tenant for a missing compliance-profile selection",
+    );
+
+    const tenants = await db.selectMany<{ id: TenantId; name: string }>(tenantTable, {
+      isEnabled: true,
+    });
+    const profileRows = await db.selectMany<{ tenantId: TenantId }>(
+      tenantComplianceProfileTable,
+      {},
+    );
+    const tenantIdsWithProfile = new Set(profileRows.map((row) => row.tenantId));
+
+    return {
+      tenants: tenants
+        .filter((tenant) => !tenantIdsWithProfile.has(tenant.id))
+        .map((tenant) => ({ id: tenant.id, name: tenant.name })),
+    };
+  },
+});
+
+interface TenantsMissingProfileResponse {
+  readonly tenants: readonly { readonly id: TenantId; readonly name: string }[];
+}

package/src/compliance-profiles-ops/index.ts

@@ -0,0 +1,34 @@
+// compliance-profiles-ops — platform-wide SystemAdmin visibility into
+// tenants missing a compliance-profile selection (#2089).
+//
+// needs-profile (compliance-profiles) tells a TenantAdmin they must pick a
+// profile, but stays TenantAdmin-only by design (#2084) — a SystemAdmin who
+// owns a picker narrowed to access.systemAdmin has no query at all. Kept as
+// a separate feature (mirrors folders-user-data/notes-history-user-data)
+// rather than folded into compliance-profiles: this is the one genuinely
+// cross-tenant capability in the picker's orbit, and it alone needs
+// r.systemScope() + a hard r.requires("tenant") — apps that only want the
+// per-tenant picker (the vast majority) stay unaffected.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { tenantsMissingProfileQuery } from "./handlers/tenants-missing-profile.query";
+
+export const complianceProfilesOpsFeature = defineFeature("compliance-profiles-ops", (r) => {
+  r.describe(
+    "Platform-wide SystemAdmin counterpart to `compliance-profiles`' `needs-profile` query (#2089): `tenants-missing-profile` lists every enabled tenant with no row in `tenantComplianceProfile` at all, tenant-wide instead of scoped to the caller's own tenant. Mount alongside `compliance-profiles` and `tenant` when an operator UI needs to see which tenants still silently run on `minimal-no-region`.",
+  );
+  r.uiHints({
+    displayLabel: "Compliance Profiles · Operator Visibility",
+    category: "compliance",
+    recommended: false,
+  });
+  r.systemScope();
+  r.requires("compliance-profiles");
+  r.requires("tenant");
+
+  const queries = {
+    tenantsMissingProfile: r.queryHandler(tenantsMissingProfileQuery),
+  };
+
+  return { queries };
+});

package/src/delivery/delivery-service.ts

@@ -1,6 +1,6 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection, DbRow } from "@cosmicdrift/kumiko-framework/db";
-import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createTenantDb, createUncheckedSystemDb } from "@cosmicdrift/kumiko-framework/db";
 import type { NotifyPriority, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
 import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
@@ -158,10 +158,18 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     }
     const systemUser = createSystemUser(tenantId);
     const tenantDb = createTenantDb(db, tenantId, "system");
+    // 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
     return (await handler.handler(
       { type: tenantUserIdsQuery, payload: { tenantId }, user: systemUser },
-      { db: tenantDb, dbOutsideTransaction: tenantDb, registry, ...bridgeStub() },
+      {
+        db: tenantDb,
+        dbOutsideTransaction: tenantDb,
+        systemDb: createUncheckedSystemDb(tenantDb),
+        registry,
+        ...bridgeStub(),
+      },
     )) as readonly string[];
   }
 

package/src/feature-toggles/__tests__/feature-toggles.integration.test.ts

@@ -16,6 +16,7 @@ import {
   type FeatureDefinition,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createEventDispatcher, type EventConsumer } from "@cosmicdrift/kumiko-framework/pipeline";
 import {
@@ -63,7 +64,17 @@ function widgetFeature(): FeatureDefinition {
     r.writeHandler(
       "widget:create",
       z.object({ name: z.string().min(1).max(100), active: z.boolean().optional() }),
-      async (event, ctx) => widgetCrud.create(event.payload, event.user, ctx.db),
+      async (event, ctx) => {
+        if (!ctx.systemDb) {
+          throw new InternalError({
+            message: "widget:create requires ctx.systemDb — is r.systemScope() still set?",
+          });
+        }
+        const db = ctx.systemDb.acknowledgeCrossTenant(
+          "widget catalog is system-wide in this test",
+        );
+        return widgetCrud.create(event.payload, event.user, db);
+      },
       { access: { roles: ["SystemAdmin"] } },
     );
   });
@@ -89,10 +100,13 @@ function widgetAuditFeature(): FeatureDefinition {
 
     r.hook("postSave", { allOf: "widget" }, async (result, ctx) => {
       if (result.kind !== "save" || !result.isNew) return;
-      if (!ctx.db) return;
+      if (!ctx.systemDb) return;
       const name = result.changes!["name"] as string | undefined;
       if (!name) return;
-      await seedRow(ctx.db, widgetAuditTable, {
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "widget audit sink is system-wide in this test",
+      );
+      await seedRow(db, widgetAuditTable, {
         id: generateId(),
         widgetName: name,
         version: 1,

package/src/step-dispatcher/__tests__/feature.boot.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { createStepDispatcherFeature } from "../feature";
+
+describe("step-dispatcher (fw#2068)", () => {
+  test("does not declare systemScope — no handler reads ctx.db/ctx.systemDb", () => {
+    expect(createStepDispatcherFeature().systemScope).toBeFalsy();
+  });
+
+  test("boot-validates standalone", () => {
+    expect(() => validateBoot([createStepDispatcherFeature()])).not.toThrow();
+  });
+});

package/src/step-dispatcher/feature.ts

@@ -37,7 +37,6 @@ export function createStepDispatcherFeature(): FeatureDefinition {
       category: "infrastructure",
       recommended: false,
     });
-    r.systemScope();
 
     r.multiStreamProjection({
       name: "step-dispatcher",

package/src/tenant/__tests__/multi-tenant.integration.test.ts

@@ -1,6 +1,10 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { buildServer, type JwtHelper } from "@cosmicdrift/kumiko-framework/api";
-import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createTenantDb,
+  createUncheckedSystemDb,
+  type DbConnection,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createRegistry,
   defineFeature,
@@ -80,6 +84,9 @@ beforeAll(async () => {
     getActiveTenantIds: async () => {
       const handler = registry.getQueryHandler(TenantQueries.activeTenantIds);
       if (!handler) return [];
+      // Hand-built context, not routed through the dispatcher — active-tenant-ids
+      // is an r.systemScope() handler, fail-closed on ctx.db, needs ctx.systemDb too.
+      const systemModeDb = createTenantDb(db, "00000000-0000-4000-8000-000000000000", "system");
       const result = await handler.handler(
         {
           type: TenantQueries.activeTenantIds,
@@ -91,12 +98,9 @@ beforeAll(async () => {
           },
         },
         {
-          db: createTenantDb(db, "00000000-0000-4000-8000-000000000000", "system"),
-          dbOutsideTransaction: createTenantDb(
-            db,
-            "00000000-0000-4000-8000-000000000000",
-            "system",
-          ),
+          db: systemModeDb,
+          dbOutsideTransaction: systemModeDb,
+          systemDb: createUncheckedSystemDb(systemModeDb),
           registry,
           ...bridgeStub(),
         },

package/src/tenant/handlers/active-tenant-ids.query.ts

@@ -4,6 +4,7 @@ import {
   SYSTEM_ROLE,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { tenantTable } from "../schema/tenant";
 
@@ -12,9 +13,16 @@ export const activeTenantIdsQuery = defineQueryHandler({
   schema: z.object({}),
   access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
   handler: async (_query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:activeTenantIds requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant("lists active tenant ids platform-wide");
     // tenants.id is a uuid string (TenantId), not a numeric surrogate.
     // Brand at the DB parse boundary — getActiveTenantIds consumers expect TenantId[].
-    const rows = await selectMany<{ id: TenantId }>(ctx.db, tenantTable, { isEnabled: true });
+    const rows = await selectMany<{ id: TenantId }>(db, tenantTable, { isEnabled: true });
     return rows.map((r) => r.id);
   },
 });

package/src/tenant/handlers/add-member.write.ts

@@ -1,7 +1,7 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { ConflictError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { ConflictError, InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { TenantErrors } from "../constants";
 import { findForbiddenMembershipRole, reservedMembershipRoleError } from "../membership-roles";
@@ -20,7 +20,15 @@ export const addMemberWrite = defineWriteHandler({
   }),
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
-    const db = ctx.db;
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:write:addMember requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "SystemAdmin manages memberships across tenants",
+    );
     const forbidden = findForbiddenMembershipRole(event.payload.roles);
     if (forbidden !== undefined) return writeFailure(reservedMembershipRoleError(forbidden));
     const existing = await fetchOne(db, tenantMembershipsTable, {

package/src/tenant/handlers/cancel-invitation.write.ts

@@ -1,21 +1,21 @@
-// Cancel-Handler für pending Invitations.
+// Cancel handler for pending invitations.
 //
-// Admin sieht eine pending Invitation und entscheidet sie zurückzu-
-// nehmen (User soll doch nicht beitreten, falsche Email getippt etc.).
-// Effekt:
-//   - DB-row.status → "cancelled"
-//   - Token aus Redis gelöscht (gemerkt im invite-token-store)
+// Admin sees a pending invitation and decides to withdraw it (user
+// shouldn't join after all, wrong email typed, etc.).
+// Effect:
+//   - DB row.status → "cancelled"
+//   - Token deleted from Redis (tracked in invite-token-store)
 //
-// Idempotent: cancellen einer schon-cancelled / accepted / expired
-// invitation = no-op + 200. Cancellen einer non-existent invitation
+// Idempotent: cancelling an already-cancelled / accepted / expired
+// invitation = no-op + 200. Cancelling a non-existent invitation
 // = invitation_not_found.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
-// kumiko-lint-ignore cross-feature-import cancel needs invite-token-store für Redis-cleanup
+// kumiko-lint-ignore cross-feature-import cancel needs invite-token-store for Redis cleanup
 import {
   deleteInviteToken,
   getTokenForInvitation,
@@ -39,9 +39,20 @@ export const cancelInvitationWrite = defineWriteHandler({
   schema: CancelInvitationSchema,
   access: { roles: access.admin },
   handler: async (event, ctx) => {
-    const invitation = await fetchOne(ctx.db.raw, tenantInvitationsTable, {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:write:cancel-invitation requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(event.user.tenantId);
+    const invitation = await fetchOne(db, tenantInvitationsTable, {
       id: event.payload.invitationId,
+      tenantId: event.user.tenantId,
     });
+    // The tenantId check below is redundant with the where-clause above but
+    // kept as defense in depth — this is a security-cutover diff, not the
+    // place to also drop an existing check.
     if (!invitation || invitation["tenantId"] !== event.user.tenantId) {
       return writeFailure(
         new NotFoundError("tenantInvitation", event.payload.invitationId, {
@@ -50,7 +61,7 @@ export const cancelInvitationWrite = defineWriteHandler({
       );
     }
 
-    // Idempotent: schon !pending → no-op success.
+    // Idempotent: already !pending → no-op success.
     if (invitation["status"] !== INVITATION_STATUS.pending) {
       return { isSuccess: true, data: { id: event.payload.invitationId, alreadyDone: true } };
     }
@@ -63,13 +74,13 @@ export const cancelInvitationWrite = defineWriteHandler({
         changes: { status: INVITATION_STATUS.cancelled },
       },
       event.user,
-      ctx.db,
+      db,
     );
     if (!updateResult.isSuccess) return updateResult;
 
-    // Token aus Redis löschen (falls noch da). Wenn Redis nicht
-    // verfügbar oder Token schon expired: kein Problem, DB-row ist
-    // die Single-Source für UI.
+    // Delete the token from Redis (if still there). If Redis is
+    // unavailable or the token already expired: not a problem, the DB
+    // row is the single source of truth for the UI.
     if (ctx.redis) {
       const token = await getTokenForInvitation(ctx.redis, event.payload.invitationId);
       if (token) {

package/src/tenant/handlers/create.write.ts

@@ -1,14 +1,15 @@
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { tenantEntity, tenantTable } from "../schema/tenant";
 
 const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
 
-// Optional `id`: SystemAdmin-only handler — legitimer Pfad für Seeds und
-// externe Provisionierung (SCIM, IdP-Sync, Migration aus bestehenden Systemen),
-// wo der Tenant mit einer vom Caller gewählten UUID angelegt werden muss.
-// Wenn nicht gesetzt, Postgres vergibt via gen_random_uuid() eine neue UUID.
+// Optional `id`: SystemAdmin-only handler — legitimate path for seeds and
+// external provisioning (SCIM, IdP sync, migration from existing systems),
+// where the tenant must be created with a caller-chosen UUID. When unset,
+// Postgres assigns a new UUID via gen_random_uuid().
 export const createWrite = defineWriteHandler({
   name: "create",
   schema: z.object({
@@ -16,10 +17,19 @@ export const createWrite = defineWriteHandler({
     key: z.string().min(1).max(50),
     name: z.string().min(1).max(200),
   }),
-  // "system" + "SystemAdmin" — symmetrisch zu update-member-roles.
-  // ops-tooling (seed-migrations + sample-recipes) nutzen System-User
-  // (roles=["system"]) als Executor; "SystemAdmin" bleibt der echte
-  // human-Operator-Pfad über die UI.
+  // "system" + "SystemAdmin" — symmetric to update-member-roles. Ops
+  // tooling (seed migrations + sample recipes) uses the system user
+  // (roles=["system"]) as the executor; "SystemAdmin" stays the real
+  // human-operator path via the UI.
   access: { roles: ["system", "SystemAdmin"] },
-  handler: async (event, ctx) => crud.create(event.payload, event.user, ctx.db),
+  handler: async (event, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:write:create requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant("creating a tenant is inherently cross-tenant");
+    return crud.create(event.payload, event.user, db);
+  },
 });

package/src/tenant/handlers/invitations.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, mapWithConcurrency } from "../../shared";
 import { INVITATION_STATUS, tenantInvitationsTable } from "../invitation-table";
@@ -23,7 +24,14 @@ export const invitationsQuery = defineQueryHandler({
   schema: z.object({}),
   access: { roles: access.admin },
   handler: async (query, ctx) => {
-    const rows = await selectMany<Record<string, unknown>>(ctx.db, tenantInvitationsTable, {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:invitations requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+    const rows = await selectMany<Record<string, unknown>>(db, tenantInvitationsTable, {
       tenantId: query.user.tenantId,
       status: INVITATION_STATUS.pending,
     });

package/src/tenant/handlers/list.query.ts

@@ -1,5 +1,6 @@
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { tenantEntity, tenantTable } from "../schema/tenant";
 
@@ -13,5 +14,14 @@ export const listQuery = defineQueryHandler({
     search: z.string().optional(),
   }),
   access: { roles: ["SystemAdmin"] },
-  handler: async (query, ctx) => crud.list(query.payload, query.user, ctx.db), // @wrapper-known semantic-alias
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:list requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant("SystemAdmin lists tenants platform-wide");
+    return crud.list(query.payload, query.user, db); // @wrapper-known semantic-alias
+  },
 });

package/src/tenant/handlers/me.query.ts

@@ -1,16 +1,24 @@
 import { fetchOne } 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 { tenantTable } from "../schema/tenant";
 
-// Direct query — query-handlers haben keinen tenant-crud-Handle. Direct-select
-// ist trivial: WHERE id = tenantId (beides UUID). Kein CRUD-Detour nötig.
+// Direct query — query handlers don't have a tenant-crud handle. A direct
+// select is trivial: WHERE id = tenantId (both UUID). No CRUD detour needed.
 export const meQuery = defineQueryHandler({
   name: "me",
   schema: z.object({}),
   access: { openToAll: true },
   handler: async (query, ctx) => {
-    const row = await fetchOne(ctx.db, tenantTable, { id: query.user.tenantId });
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:me requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+    const row = await fetchOne(db, tenantTable, { id: query.user.tenantId });
     return row ?? null;
   },
 });

package/src/tenant/handlers/members.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 { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
 import { decryptStoredPii, mapWithConcurrency } from "../../shared";
@@ -20,13 +21,20 @@ export const membersQuery = defineQueryHandler({
   schema: z.object({}),
   access: { roles: access.admin },
   handler: async (query, ctx) => {
-    const rows = await selectMany(ctx.db, tenantMembershipsTable, {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:members requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+    const rows = await selectMany(db, tenantMembershipsTable, {
       tenantId: query.user.tenantId,
     });
 
     const userIds = [...new Set(rows.map((row) => row["userId"]))];
     const users =
-      userIds.length > 0 ? await selectMany<UserRow>(ctx.db, userTable, { id: userIds }) : [];
+      userIds.length > 0 ? await selectMany<UserRow>(db, userTable, { id: userIds }) : [];
     const userById = new Map(users.map((u) => [String(u.id), u]));
 
     const decrypted = await mapWithConcurrency(users, KMS_POOL_CONCURRENCY, async (user) => {

package/src/tenant/handlers/memberships.query.ts

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler, SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
 import { tenantMembershipsTable } from "../membership-table";
@@ -12,14 +13,24 @@ export const membershipsQuery = defineQueryHandler({
   // directly by tenant admins managing memberships in the admin UI.
   access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
   handler: async (query, ctx) => {
-    const rows = await selectMany(ctx.db, tenantMembershipsTable, { userId: query.payload.userId });
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:memberships requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "resolves memberships for an arbitrary userId across all tenants",
+    );
+    const rows = await selectMany(db, tenantMembershipsTable, { userId: query.payload.userId });
     if (rows.length === 0) return [];
 
-    // tenantName/tenantKey machen Memberships im UI unterscheidbar (sonst nur
-    // das UUID-Präfix — Seed-Tenants mit 00000000-…-Präfix wären ununterscheidbar).
-    // Ein einzelner IN-Batch über alle tenantIds statt fetchOne pro Membership (#324).
+    // tenantName/tenantKey make memberships distinguishable in the UI
+    // (otherwise just the UUID prefix — seed tenants with a 00000000-…
+    // prefix would be indistinguishable). A single IN-batch over all
+    // tenantIds instead of fetchOne per membership (#324).
     type TenantRow = { id: unknown; name?: unknown; key?: unknown; isEnabled?: unknown };
-    const tenants = await selectMany<TenantRow>(ctx.db, tenantTable, {
+    const tenants = await selectMany<TenantRow>(db, tenantTable, {
       id: rows.map((row) => row["tenantId"]),
     });
     const tenantById = new Map<unknown, TenantRow>(tenants.map((t) => [t.id, t]));
@@ -27,11 +38,11 @@ export const membershipsQuery = defineQueryHandler({
     return rows
       .map((row) => {
         const tenant = tenantById.get(row["tenantId"]);
-        // Disabled Tenants (tenant:write:disable) zählen nicht als Membership:
-        // Login wählt sie nicht, /auth/tenants listet sie nicht, switch-tenant
-        // antwortet not_a_member. Nur das explizite false filtert — eine
-        // fehlende tenant-Row (Projektions-Drift) soll keinen Login-Lockout
-        // aller Member auslösen.
+        // Disabled tenants (tenant:write:disable) don't count as a
+        // membership: login doesn't pick them, /auth/tenants doesn't list
+        // them, switch-tenant answers not_a_member. Only the explicit
+        // false filters — a missing tenant row (projection drift) should
+        // not lock out every member's login.
         if (tenant !== undefined && tenant.isEnabled === false) return null;
         return {
           ...row,

package/src/tenant/handlers/remove-member.write.ts

@@ -5,7 +5,7 @@ import {
   defineWriteHandler,
   withResponseData,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { tenantMembershipEntity, tenantMembershipsTable } from "../membership-table";
 
@@ -23,7 +23,15 @@ export const removeMemberWrite = defineWriteHandler({
   schema: z.object({ userId: z.string(), tenantId: z.string() }),
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
-    const db = ctx.db;
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:write:removeMember requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "SystemAdmin manages memberships across tenants",
+    );
     const existing = await fetchOne(db, tenantMembershipsTable, {
       userId: event.payload.userId,
       tenantId: event.payload.tenantId,

package/src/tenant/handlers/resolve-user-ids.query.ts

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler, SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { tenantMembershipsTable } from "../membership-table";
 
@@ -14,17 +15,26 @@ export const resolveUserIdsQuery = defineQueryHandler({
   }),
   access: { roles: [SYSTEM_ROLE] },
   handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:resolveUserIds requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "cross-feature lookup by arbitrary tenantId/userId",
+    );
     const { tenantId, userId } = query.payload;
 
     if (tenantId !== undefined) {
-      const rows = await selectMany<{ userId: number }>(ctx.db, tenantMembershipsTable, {
+      const rows = await selectMany<{ userId: number }>(db, tenantMembershipsTable, {
         tenantId,
       });
       return rows.map((r) => r.userId);
     }
 
     if (userId !== undefined) {
-      const rows = await selectMany(ctx.db, tenantMembershipsTable, { userId });
+      const rows = await selectMany(db, tenantMembershipsTable, { userId });
       return rows.length > 0 ? [userId] : [];
     }
 

package/src/tenant/handlers/toggle-enabled.write.ts

@@ -1,5 +1,6 @@
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { tenantEntity, tenantTable } from "../schema/tenant";
 
@@ -8,14 +9,24 @@ const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "
 // Admin flip: last-writer-wins is fine. SystemAdmin is the only caller and
 // there's no meaningful concurrent-edit race on this single boolean.
 function createToggleTenantHandler(enable: boolean) {
+  const verbName = enable ? "enable" : "disable";
   return defineWriteHandler({
-    name: enable ? "enable" : "disable",
+    name: verbName,
     schema: z.object({ id: z.uuid() }),
     access: { roles: ["SystemAdmin"] },
-    handler: async (event, ctx) =>
-      crud.update({ id: event.payload.id, changes: { isEnabled: enable } }, event.user, ctx.db, {
+    handler: async (event, ctx) => {
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message: `tenant:write:${verbName} requires ctx.systemDb — is r.systemScope() still set on the tenant feature?`,
+        });
+      }
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "SystemAdmin enables/disables tenants platform-wide",
+      );
+      return crud.update({ id: event.payload.id, changes: { isEnabled: enable } }, event.user, db, {
         skipOptimisticLock: true,
-      }), // @wrapper-known semantic-alias
+      }); // @wrapper-known semantic-alias
+    },
   });
 }
 

package/src/tenant/handlers/update-member-roles.write.ts

@@ -5,7 +5,7 @@ import {
   defineWriteHandler,
   withResponseData,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { findForbiddenMembershipRole, reservedMembershipRoleError } from "../membership-roles";
 import { tenantMembershipEntity, tenantMembershipsTable } from "../membership-table";
@@ -26,13 +26,21 @@ export const updateMemberRolesWrite = defineWriteHandler({
     tenantId: z.string(),
     roles: z.array(z.string()).min(1),
   }),
-  // "system" + "SystemAdmin" — symmetrisch zu tenant:write:create. System-
-  // User (createSystemUser, roles=["system"]) braucht den Access für seed-
-  // migrations + andere ops-tooling-Pfade. SystemAdmin ist der echte
-  // human-Operator-Pfad über die UI.
+  // "system" + "SystemAdmin" — symmetric to tenant:write:create. The
+  // system user (createSystemUser, roles=["system"]) needs access for
+  // seed migrations and other ops-tooling paths. SystemAdmin is the real
+  // human-operator path via the UI.
   access: { roles: ["system", "SystemAdmin"] },
   handler: async (event, ctx) => {
-    const db = ctx.db;
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:write:updateMemberRoles requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "SystemAdmin manages memberships across tenants",
+    );
     const forbidden = findForbiddenMembershipRole(event.payload.roles);
     if (forbidden !== undefined) return writeFailure(reservedMembershipRoleError(forbidden));
     const existing = await fetchOne(db, tenantMembershipsTable, {

package/src/tier-engine/feature.ts

@@ -340,28 +340,28 @@ export function createTierEngineFeature<
           const newTenantId = data.id as TenantId; // @cast-boundary engine-payload
           const aggregateId = tierAssignmentAggregateId(newTenantId);
 
-          // skip: defensive — inTransaction phase hat ctx.db immer gesetzt,
-          // aber AppContext type macht's optional. Throw wäre overreach
-          // (lifecycle blocking), silent-skip ist defensive-soft.
-          if (!ctx.db) return;
-
-          // ctx.db ist im inTransaction-phase eine TenantDb (tenant-scoped
-          // proxy auf die echte TX). Für event-store-Pfade brauchen wir
-          // die rohe DbConnection — TenantDb exposes nur select/insert/
-          // update/delete, NICHT execute (event-store-append.ts:102 ruft
-          // db.execute(sql`SELECT pg_notify(...)`) → TypeError sonst).
-          // Pattern matched signup-confirm.write.ts:107 (.raw), nicht
-          // `as DbConnection` — das ist Type-Lie der erst beim ersten
-          // .execute()-Call crashed.
-          //
-          // AppContext.db ist union (DbConnection | TenantDb). Im
-          // inTransaction-phase garantiert TenantDb — der dispatcher
-          // wrapped vorher (siehe pipeline/dispatcher.ts createTenantDb-
-          // Aufruf). TypeGuard via `"raw" in ...` ist robuster als
-          // `as TenantDb` gegen future refactor.
-          // skip: defensive — sollte im inTransaction nie greifen.
-          if (!("raw" in ctx.db)) return;
-          const rawDb = ctx.db.raw as DbConnection; // @cast-boundary db-runner
+          // tenant is an r.systemScope() feature, so this cross-feature hook gets a
+          // fail-closed ctx.db — reach for ctx.systemDb instead (see entity-handlers.ts).
+          const db = ctx.systemDb
+            ? ctx.systemDb.acknowledgeCrossTenant(
+                `tier-engine auto-default-tier hook on r.systemScope() tenant write (${newTenantId})`,
+              )
+            : ctx.db;
+          // skip: defensive — inTransaction phase always sets db, but AppContext's
+          // type makes it optional. Throwing would be overreach (lifecycle
+          // blocking), silent-skip is defensive-soft.
+          if (!db) return;
+
+          // db is a TenantDb in the inTransaction phase (tenant-scoped proxy over
+          // the real tx). Event-store paths need the raw DbConnection — TenantDb
+          // only exposes select/insert/update/delete, not execute
+          // (event-store-append.ts:102 calls db.execute(sql`SELECT pg_notify(...)`)
+          // → TypeError otherwise). Pattern matches signup-confirm.write.ts:107
+          // (.raw), not `as DbConnection` — that's a type-lie that only crashes on
+          // the first .execute() call.
+          // skip: defensive — should never trip in the inTransaction phase.
+          if (!("raw" in db)) return;
+          const rawDb = db.raw as DbConnection; // @cast-boundary db-runner
 
           // Idempotency: stream-existence-check vor create. Pattern aus
           // seedTenant.ts. Bei re-replay (rebuild) nicht versionsbumpen.