@cosmicdrift/kumiko-bundled-features 0.198.0 → 0.199.0

package/src/feature-toggles/handlers/set.write.ts

@@ -9,6 +9,7 @@ import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 import {
   FEATURE_TOGGLE_AGGREGATE_TYPE,
+  FEATURE_TOGGLE_CROSS_TENANT_REASON,
   FEATURE_TOGGLE_SET_EVENT_NAME,
   FeatureToggleErrors,
 } from "../constants";
@@ -53,6 +54,20 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
         );
       }
 
+      // Guard 0.5: feature-toggles is r.systemScope() (feature.ts), so
+      // ctx.systemDb is always populated by buildHandlerContext for this
+      // handler — the `?` on the type is a HandlerContext-wide optionality,
+      // not a real runtime possibility here. Guard anyway instead of a
+      // non-null assertion: an app that ever un-declares r.systemScope()
+      // gets an actionable error instead of a silent `undefined.acknowledgeCrossTenant`.
+      if (!ctx.systemDb) {
+        throw new Error(
+          "[feature-toggles] set-handler requires ctx.systemDb — the feature-toggles " +
+            "feature must stay r.systemScope() (see feature.ts).",
+        );
+      }
+      const db = ctx.systemDb.acknowledgeCrossTenant(FEATURE_TOGGLE_CROSS_TENANT_REASON);
+
       // Guard 1: featureName must be a registered feature. Otherwise we'd
       // pile up orphan rows from typos that the gate would silently apply
       // (if someone ever added a feature with that name later).
@@ -90,7 +105,7 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
         updatedBy: string;
       };
       const [existing] = await selectMany<StateRow>(
-        ctx.db,
+        db,
         globalFeatureStateTable,
         { featureName },
         { limit: 1 },
@@ -100,7 +115,7 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
 
       if (!existing) {
         // First-time override: insert.
-        await insertOne(ctx.db, globalFeatureStateTable, {
+        await insertOne(db, globalFeatureStateTable, {
           featureName,
           enabled,
           version: 1,
@@ -111,7 +126,7 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
         // Upsert with optimistic lock. Two operators flipping the same
         // toggle simultaneously is rare but possible — the version-WHERE
         // ensures only one wins; the loser sees VersionConflictError.
-        const updated = await ctx.db.updateMany(
+        const updated = await db.updateMany(
           globalFeatureStateTable,
           {
             enabled,

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

@@ -15,6 +15,7 @@ import {
   type TestDb,
   type TestRedis,
   TestUsers,
+  testTenantId,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { sleep } from "@cosmicdrift/kumiko-framework/testing";
@@ -35,6 +36,14 @@ let jobRunner: JobRunner;
 
 const systemAdmin = TestUsers.systemAdmin;
 const normalUser = createTestUser({ id: 2, roles: ["User"] });
+// jobs is platform-wide, cross-tenant-by-design monitoring (fw#2077) — this
+// SystemAdmin lives under a different tenant than `systemAdmin` above, so
+// scenario 6 can prove list/details/retry see runs across tenant boundaries.
+const otherTenantSystemAdmin = createTestUser({
+  id: 20,
+  tenantId: testTenantId(2),
+  roles: ["SystemAdmin"],
+});
 const JWT_SECRET = "jobs-feature-test-secret-minimum-32-chars!!";
 
 // Track job executions
@@ -321,6 +330,54 @@ describe("scenario 5: retry failed job", () => {
   });
 });
 
+// --- Scenario 6: cross-tenant visibility (ctx.systemDb.acknowledgeCrossTenant) ---
+
+describe("scenario 6: cross-tenant job monitoring", () => {
+  test("SystemAdmin from a different tenant sees runs triggered under another tenant", async () => {
+    const triggerResult = await write(systemAdmin, JobHandlers.trigger, {
+      jobName: "app:job:sync-data",
+      payload: { source: "cross-tenant-check" },
+    });
+    expect(triggerResult.isSuccess).toBe(true);
+    const bullJobId = triggerResult.data.bullJobId;
+    await sleep(1000);
+
+    const listResult = await query(otherTenantSystemAdmin, JobQueries.list, {
+      jobName: "app:job:sync-data",
+    });
+    const run = listResult.data.rows.find(
+      (r: Record<string, unknown>) => r["bullJobId"] === bullJobId,
+    );
+    expect(run).toBeDefined();
+
+    const detailResult = await query(otherTenantSystemAdmin, JobQueries.details, {
+      runId: run.id,
+    });
+    expect(detailResult.data).not.toBeNull();
+    expect(detailResult.data.id).toBe(run.id);
+  });
+
+  test("SystemAdmin from a different tenant can retry a failed run triggered under another tenant", async () => {
+    const triggerResult = await write(systemAdmin, JobHandlers.trigger, {
+      jobName: "app:job:failing-import",
+    });
+    expect(triggerResult.isSuccess).toBe(true);
+    await sleep(1500);
+
+    const listResult = await query(otherTenantSystemAdmin, JobQueries.list, {
+      jobName: "app:job:failing-import",
+      status: "failed",
+    });
+    const failedRunId = listResult.data.rows[0].id;
+
+    const retryResult = await write(otherTenantSystemAdmin, JobHandlers.retry, {
+      runId: failedRunId,
+    });
+    expect(retryResult.isSuccess).toBe(true);
+    expect(retryResult.data.retriedFromRunId).toBe(failedRunId);
+  });
+});
+
 // --- Access control ---
 
 describe("access control", () => {

package/src/jobs/__tests__/projection-rebuild-job.integration.test.ts

@@ -153,9 +153,18 @@ describe("projection-rebuild job (jobs feature composed)", () => {
     for (let i = 0; i < 40 && (await getCount()) !== 2; i++) await sleep(200);
     expect(await getCount()).toBe(2);
 
-    const runs = await selectMany<{ jobName: string; status: string }>(db, jobRunsTable, {
-      jobName: PROJECTION_REBUILD_JOB,
-    });
+    // getCount()==2 only proves rebuildProjection's own writes landed — the
+    // run-completed event (job-run-logger's onJobComplete) is a separate
+    // async append that starts only after the handler returns, so it can
+    // still be in flight here. Poll status too instead of racing it.
+    let runs: readonly { jobName: string; status: string }[] = [];
+    for (let i = 0; i < 40; i++) {
+      runs = await selectMany<{ jobName: string; status: string }>(db, jobRunsTable, {
+        jobName: PROJECTION_REBUILD_JOB,
+      });
+      if (runs.some((r) => r.status === "completed")) break;
+      await sleep(200);
+    }
     expect(runs.length).toBeGreaterThanOrEqual(1);
     expect(runs.some((r) => r.status === "completed")).toBe(true);
   }, 30000);

package/src/jobs/__tests__/reindex-entity-job.integration.test.ts

@@ -11,6 +11,7 @@ import {
   buildEntityTable,
   createEventStoreExecutor,
   createTenantDb,
+  createUncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
@@ -18,6 +19,7 @@ import {
   defineFeature,
   type JobContext,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   setupTestStack,
@@ -97,6 +99,7 @@ describe("reindexEntityJob", () => {
       registry: stack.registry,
       searchAdapter: stack.search,
       systemUser: admin,
+      systemDb: createUncheckedSystemDb(createTenantDb(stack.db, admin.tenantId, "system")),
       log: noopLogger,
       triggeredBy: null,
       ...bridgeStub(),
@@ -137,6 +140,7 @@ describe("reindexEntityJob", () => {
       registry: stack.registry,
       searchAdapter: stack.search,
       systemUser: admin,
+      systemDb: createUncheckedSystemDb(createTenantDb(stack.db, admin.tenantId, "system")),
       log: noopLogger,
       triggeredBy: null,
       ...bridgeStub(),
@@ -172,4 +176,39 @@ describe("reindexEntityJob", () => {
       ),
     ).rejects.toThrow(/searchAdapter/);
   });
+
+  test("throws when ctx.systemDb is missing", async () => {
+    await expect(
+      reindexEntityJob(
+        { entity: "widget" },
+        // @cast-boundary test-seam — deliberately no systemDb: proves the missing-systemDb throw
+        {
+          db: stack.db,
+          registry: stack.registry,
+          searchAdapter: stack.search,
+          systemUser: admin,
+        } as unknown as JobContext,
+      ),
+    ).rejects.toThrow(/systemDb/);
+  });
+
+  // Honest scope: in production job-runner.ts derives both ctx.systemDb's
+  // tenantId and ctx.systemUser from the same per-dispatch value, so this
+  // mismatch can't occur live — it only proves the self-check is wired to
+  // the tenant that was actually resolved, catching future drift between
+  // the two, not a real cross-tenant hole.
+  test("fails closed when ctx.systemDb is scoped to a different tenant than ctx.systemUser", async () => {
+    const otherTenantId = TestUsers.otherTenant.tenantId;
+    const ctx: JobContext = {
+      db: stack.db,
+      registry: stack.registry,
+      searchAdapter: stack.search,
+      systemUser: admin,
+      systemDb: createUncheckedSystemDb(createTenantDb(stack.db, otherTenantId, "system")),
+      log: noopLogger,
+      triggeredBy: null,
+      ...bridgeStub(),
+    };
+    await expect(reindexEntityJob({ entity: "widget" }, ctx)).rejects.toThrow(AccessDeniedError);
+  });
 });

package/src/jobs/handlers/detail.query.ts

@@ -1,5 +1,6 @@
 import { fetchOne, 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 { decryptStoredPii } from "../../shared";
 import { jobRunLogsTable, jobRunsTable } from "../job-run-table";
@@ -13,7 +14,12 @@ export const detailQuery = defineQueryHandler({
   schema: z.object({ runId: z.uuid() }),
   access: { roles: ["SystemAdmin"] },
   handler: async (query, ctx) => {
-    const db = ctx.db;
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "jobs:query:details requires ctx.systemDb (feature must declare r.systemScope())",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant("cross-tenant job monitoring");
 
     const row = await fetchOne(db, jobRunsTable, { id: query.payload.runId });
 

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

@@ -1,5 +1,6 @@
 import { selectMany, type WhereObject } 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 { decryptStoredPii } from "../../shared";
 import { jobRunsTable } from "../job-run-table";
@@ -18,10 +19,16 @@ export const listQuery = defineQueryHandler({
   }),
   access: { roles: ["SystemAdmin"] },
   handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "jobs:query:list requires ctx.systemDb (feature must declare r.systemScope())",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant("cross-tenant job monitoring");
     const where: WhereObject = {};
     if (query.payload.jobName) where["jobName"] = query.payload.jobName;
     if (query.payload.status) where["status"] = query.payload.status;
-    const rows = await selectMany(ctx.db, jobRunsTable, where, {
+    const rows = await selectMany(db, jobRunsTable, where, {
       orderBy: { col: "id", direction: "desc" },
       limit: query.payload.limit ?? 50,
     });

package/src/jobs/handlers/projection-rebuild.job.ts

@@ -15,10 +15,10 @@ export const projectionRebuildPayloadSchema = z.object({
 
 export const projectionRebuildJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
   const { projection, skipApplyErrors } = projectionRebuildPayloadSchema.parse(rawPayload);
-  if (!ctx.db) {
+  if (!ctx.systemDb) {
     throw new InternalError({
       message:
-        "[jobs:projection-rebuild] ctx.db missing — job context requires a database connection.",
+        "[jobs:projection-rebuild] ctx.systemDb missing — is r.systemScope() still set on the jobs feature?",
     });
   }
   if (!ctx.registry) {
@@ -27,7 +27,10 @@ export const projectionRebuildJob: JobHandlerFn = async (rawPayload, ctx): Promi
         "[jobs:projection-rebuild] ctx.registry missing — job context requires the registry.",
     });
   }
-  const db = ctx.db as DbConnection; // @cast-boundary db-operator
+  // Global rebuild by design (streams every tenant's events, not just one) —
+  // acknowledgeCrossTenant documents that instead of the previous implicit
+  // ctx.db cast. .raw is the same DbConnection ctx.db carried before.
+  const db = ctx.systemDb.acknowledgeCrossTenant("global projection rebuild").raw as DbConnection; // @cast-boundary db-operator
   const result = await rebuildProjection(projection, {
     db,
     registry: ctx.registry,

package/src/jobs/handlers/reindex-entity.job.ts

@@ -4,7 +4,6 @@
 // just cron: one `jobs:write:trigger` call with { entity } re-runs once per
 // active tenant.
 
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { JobHandlerFn } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { reindexEntity } from "@cosmicdrift/kumiko-framework/search";
@@ -16,11 +15,6 @@ export const reindexEntityPayloadSchema = z.object({
 
 export const reindexEntityJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
   const { entity } = reindexEntityPayloadSchema.parse(rawPayload);
-  if (!ctx.db) {
-    throw new InternalError({
-      message: "[jobs:reindex-entity] ctx.db missing — job context requires a database connection.",
-    });
-  }
   if (!ctx.registry) {
     throw new InternalError({
       message: "[jobs:reindex-entity] ctx.registry missing — job context requires the registry.",
@@ -33,14 +27,24 @@ export const reindexEntityJob: JobHandlerFn = async (rawPayload, ctx): Promise<v
     });
   }
   // perTenant fan-out — the job-runner enqueues one child run per active
-  // tenant with _tenantId set; a run without one (e.g. misconfigured
-  // manual dispatch outside the fan-out) has nothing scoped to reindex.
-  const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+  // tenant with ctx.systemUser scoped to it; a run without one (e.g.
+  // misconfigured manual dispatch outside the fan-out) has nothing scoped
+  // to reindex. ctx._tenantId is never populated per-dispatch (only
+  // ctx.systemUser is), so it is not a valid fallback here.
+  const tenantId = ctx.systemUser?.tenantId;
   if (tenantId === undefined) {
     // skip: fired without a perTenant fan-out tenant — nothing scoped to reindex
     return;
   }
-  const db = ctx.db as DbConnection; // @cast-boundary db-operator
+  if (!ctx.systemDb) {
+    throw new InternalError({
+      message:
+        "[jobs:reindex-entity] ctx.systemDb missing — the owning feature must declare r.systemScope().",
+    });
+  }
+  // .raw bypasses tenant filtering, safe here only because reindexEntity
+  // filters `WHERE tenant_id = $1` itself with this same tenantId.
+  const db = ctx.systemDb.assertTenantMatch(tenantId).raw;
   const result = await reindexEntity(db, ctx.registry, ctx.searchAdapter, entity, tenantId);
   ctx.log?.info?.(
     `[jobs:reindex-entity] tenant=${tenantId} reindexed ${entity}: ${result.indexedRows}/${result.scannedRows} rows indexed` +

package/src/jobs/handlers/retry.write.ts

@@ -1,6 +1,7 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import {
+  InternalError,
   NotFoundError,
   UnprocessableError,
   writeFailure,
@@ -24,7 +25,12 @@ export const retryWrite = defineWriteHandler({
   schema: z.object({ runId: z.uuid() }),
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
-    const db = ctx.db;
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "jobs:write:retry requires ctx.systemDb (feature must declare r.systemScope())",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant("cross-tenant job monitoring");
     // @cast-boundary engine-payload — JobRunner attached by app-boot via ctx-extension
     const jobRunner = ctx["jobRunner"] as JobRunner;
 

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

@@ -19,7 +19,7 @@ export const statusQuery = defineQueryHandler({
   handler: async (query, ctx) => {
     // One gate for both halves: required keys/secrets of provider-features
     // count only while their provider is the selected one (r.extensionSelector).
-    const gate = await buildProviderSelectionGate(ctx, ReadinessQueries.status, query.user);
+    const gate = await buildProviderSelectionGate(ctx, ReadinessQueries.status, query.user, ctx.db);
     // skipAccessFilter: das Verdict muss ALLE required Keys zählen — der
     // Handler selbst ist TenantAdmin-gated, der Per-Key-Filter wäre hier
     // eine ready:true-Lüge für SystemAdmin-gated Keys (277/1).
@@ -27,6 +27,7 @@ export const statusQuery = defineQueryHandler({
       ctx,
       ReadinessQueries.status,
       query.user,
+      ctx.db,
       gate,
       { skipAccessFilter: true },
     );

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

@@ -1,6 +1,11 @@
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  AccessDeniedError,
+  InternalError,
+  NotFoundError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { tenantEntity, tenantTable } from "../schema/tenant";
 
@@ -18,11 +23,31 @@ export const updateWrite = defineWriteHandler({
   }),
   access: { roles: ["Admin", "SystemAdmin"] },
   handler: async (event, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:write:update requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+
     // "Admin" is tenant-scoped and must not touch another tenant's row —
     // SystemAdmin is the platform-wide role and stays cross-tenant by design.
-    if (!event.user.roles.includes("SystemAdmin") && event.payload.id !== event.user.tenantId) {
-      return writeFailure(new NotFoundError("tenant", event.payload.id));
+    if (event.user.roles.includes("SystemAdmin")) {
+      const db = ctx.systemDb.acknowledgeCrossTenant("SystemAdmin is platform-wide by design");
+      return crud.update(event.payload, event.user, db);
+    }
+
+    let db: TenantDb;
+    try {
+      db = ctx.systemDb.assertTenantMatch(event.payload.id);
+    } catch (err) {
+      // Kept as tenant_not_found (not the underlying access_denied) so a
+      // cross-tenant Admin can't use the error to enumerate tenant existence.
+      if (err instanceof AccessDeniedError) {
+        return writeFailure(new NotFoundError("tenant", event.payload.id));
+      }
+      throw err;
     }
-    return crud.update(event.payload, event.user, ctx.db);
+    return crud.update(event.payload, event.user, db);
   },
 });

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

@@ -1,10 +1,12 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
   TestUsers,
+  testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { expectErrorIncludes, resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
@@ -151,6 +153,25 @@ describe("scenario 2b: find-for-auth is system-only", () => {
     expect(body).toContain("access_denied");
     expect(body).not.toContain("must-never-leave-the-server");
   });
+
+  // The "system" role reaches find-for-auth from any tenant — user rows are
+  // tenant-agnostic identity records, not scoped to the caller's own tenant.
+  test("system caller from a different tenant still resolves the user", async () => {
+    const created = await seedUser({
+      email: "cross-tenant@example.com",
+      displayName: "CrossTenant",
+      passwordHash: "cross-tenant-hash",
+    });
+
+    const foreignSystemCaller = createSystemUser(testTenantId(99));
+    const result = await stack.http.queryOk<{ id: number } | null>(
+      UserQueries.findForAuth,
+      { email: "cross-tenant@example.com" },
+      foreignSystemCaller,
+    );
+
+    expect(result).toMatchObject({ id: created.id });
+  });
 });
 
 // --- Scenario 3: user edits own profile, email/passwordHash are system-locked ---

package/src/user/handlers/create.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 { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { z } from "zod";
 import { UserErrors } from "../constants";
@@ -35,7 +35,14 @@ export const createWrite = defineWriteHandler({
   }),
   access: { roles: ["system", "SystemAdmin"] },
   handler: async (event, ctx) => {
-    const existing = await fetchOne<{ id: string }>(ctx.db, userTable, {
+    if (!ctx.systemDb) {
+      throw new InternalError({ message: "user:create requires r.systemScope()" });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "user rows are tenant-agnostic identity records; uniqueness check and create need no tenant filter",
+    );
+
+    const existing = await fetchOne<{ id: string }>(db, userTable, {
       email: event.payload.email,
     });
 
@@ -49,6 +56,6 @@ export const createWrite = defineWriteHandler({
       );
     }
 
-    return crud.create(event.payload, event.user, ctx.db);
+    return crud.create(event.payload, event.user, db);
   },
 });

package/src/user/handlers/find-for-auth.query.ts

@@ -1,5 +1,6 @@
 import { fetchOne } 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 { userTable } from "../schema/user";
 
@@ -33,6 +34,13 @@ export const findForAuthQuery = defineQueryHandler({
         ? { email: query.payload.email }
         : { id: query.payload.id as string }; // @cast-boundary engine-payload
 
-    return (await fetchOne(ctx.db, userTable, where)) ?? null;
+    if (!ctx.systemDb) {
+      throw new InternalError({ message: "user:find-for-auth requires r.systemScope()" });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "identity resolution for auth is intentionally cross-tenant",
+    );
+
+    return (await fetchOne(db, userTable, where)) ?? null;
   },
 });

package/src/user/handlers/me.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 { userEntity, userTable } from "../schema/user";
 
@@ -11,5 +12,13 @@ export const meQuery = defineQueryHandler({
   name: "user:me",
   schema: z.object({}),
   access: { openToAll: true },
-  handler: async (query, ctx) => crud.detail({ id: query.user.id }, query.user, ctx.db), // @wrapper-known semantic-alias
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({ message: "user:me requires r.systemScope()" });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "user rows are tenant-agnostic identity records; self-lookup by id needs no tenant filter",
+    );
+    return crud.detail({ id: query.user.id }, query.user, db); // @wrapper-known semantic-alias
+  },
 });

package/src/user/handlers/update.write.ts

@@ -1,6 +1,10 @@
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineWriteHandler, hasAccess } from "@cosmicdrift/kumiko-framework/engine";
-import { AccessDeniedError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  AccessDeniedError,
+  InternalError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { z } from "zod";
 import { UserErrors } from "../constants";
@@ -51,6 +55,12 @@ export const updateWrite = defineWriteHandler({
         }),
       );
     }
-    return crud.update(event.payload, event.user, ctx.db);
+    if (!ctx.systemDb) {
+      throw new InternalError({ message: "user:update requires r.systemScope()" });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "user rows are tenant-agnostic identity records; self/admin update needs no tenant filter",
+    );
+    return crud.update(event.payload, event.user, db);
   },
 });