@cosmicdrift/kumiko-framework 0.199.2 → 0.200.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.199.2",
+  "version": "0.200.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -186,7 +186,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.199.2",
+    "@cosmicdrift/kumiko-types": "0.200.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +202,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.199.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.200.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/entity-handlers.ts

@@ -176,6 +176,19 @@ export function defineEntityWriteHandler(
   const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });
 
+  // r.systemScope() features (tenant, config, secrets, ...) hand their
+  // entity-convention handlers a fail-closed ctx.db — this generic layer
+  // has no per-call business reason to give assertTenantMatch, so it
+  // acknowledges cross-tenant access on the feature's behalf. This is
+  // behavior-preserving: ctx.db was already an unfiltered "system"-mode
+  // TenantDb for these handlers before the ctx.db cutover.
+  const dbFor = (ctx: HandlerContext): TenantDb =>
+    ctx.systemDb
+      ? ctx.systemDb.acknowledgeCrossTenant(
+          `entity convention handler for r.systemScope() feature (${name})`,
+        )
+      : ctx.db;
+
   let schema: ZodType;
   let handler: WriteHandlerDef["handler"];
 
@@ -184,7 +197,7 @@ export function defineEntityWriteHandler(
       schema = buildInsertSchema(entity);
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
-        return executor.create(event.payload as DbRow, event.user, ctx.db, {
+        return executor.create(event.payload as DbRow, event.user, dbFor(ctx), {
           preSave:
             runPreSave &&
             ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
@@ -205,7 +218,7 @@ export function defineEntityWriteHandler(
         // KEK-rotation, the user-data-rights #494 backfill) don't go through
         // this handler and keep today's always-re-encrypt behavior, which
         // they rely on to intentionally force a fresh event/ciphertext.
-        return executor.update(event.payload as UpdatePayload, event.user, ctx.db, {
+        return executor.update(event.payload as UpdatePayload, event.user, dbFor(ctx), {
           skipUnchanged: true,
           preSave:
             runPreSave &&
@@ -216,12 +229,12 @@ export function defineEntityWriteHandler(
     case "delete":
       schema = idSchema;
       handler = async (event, ctx) =>
-        executor.delete(event.payload as IdPayload, event.user, ctx.db); // @cast-boundary engine-payload
+        executor.delete(event.payload as IdPayload, event.user, dbFor(ctx)); // @cast-boundary engine-payload
       break;
     case "restore":
       schema = idSchema;
       handler = async (event, ctx) =>
-        executor.restore(event.payload as IdPayload, event.user, ctx.db); // @cast-boundary engine-payload
+        executor.restore(event.payload as IdPayload, event.user, dbFor(ctx)); // @cast-boundary engine-payload
       break;
     default:
       assertUnreachable(verb, "write verb");
@@ -271,24 +284,36 @@ export function defineEntityQueryHandler(
   let schema: ZodType;
   let handler: QueryHandlerDef["handler"];
 
-  // Tier 2.7e Server-Eagerload: wenn die entity reference-Felder hat,
-  // resolved der handler nach dem Haupt-Query die UUIDs gegen die
-  // referenced entities. Das `_refs`-Property landet auf jeder Row;
-  // Renderer-Side useReferenceLookup bleibt als Fallback bestehen
-  // (für Apps die manuell Custom-Handler schreiben ohne diesen
-  // Wrapper zu nutzen).
+  // Tier 2.7e server-eagerload: when the entity has reference fields, the
+  // handler resolves the UUIDs against the referenced entities after the
+  // main query. The `_refs` property lands on every row; the renderer-side
+  // useReferenceLookup stays as a fallback (for apps that write custom
+  // handlers by hand without this wrapper).
   const hasRefFields = collectReferenceFields(entity).length > 0;
 
-  // crossTenant: this ONE handler reads across every tenant (e.g. a
-  // SystemAdmin-only operator inspector) without making the whole feature
-  // r.systemScope() — that would drop tenant isolation from every OTHER
-  // handler the feature registers too. The executor's list()/detail() only
-  // add a tenant filter when db.mode === "tenant" (see event-store-executor
-  // .ts), so handing them a "system"-mode TenantDb built from the same raw
-  // connection is enough to skip it — access-control (who may call this
-  // handler at all) is unaffected, still gated by `options.access`.
-  const dbFor = (ctx: HandlerContext): TenantDb =>
-    options?.crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+  // Preference order:
+  //  1. ctx.systemDb — the feature declared r.systemScope() (whole-feature
+  //     cutover, dispatch-shared.ts), so ctx.db is fail-closed. This is
+  //     behavior-preserving: ctx.db was already an unfiltered "system"-mode
+  //     TenantDb for these handlers before that cutover.
+  //  2. options.crossTenant — this ONE handler reads across every tenant
+  //     (e.g. a SystemAdmin-only operator inspector) without making the
+  //     whole feature r.systemScope() — that would drop tenant isolation
+  //     from every OTHER handler the feature registers too. The executor's
+  //     list()/detail() only add a tenant filter when db.mode === "tenant"
+  //     (see event-store-executor.ts), so handing them a "system"-mode
+  //     TenantDb built from the same raw connection is enough to skip it —
+  //     access-control (who may call this handler at all) is unaffected,
+  //     still gated by `options.access`.
+  //  3. plain ctx.db — the common case, tenant-filtered.
+  const dbFor = (ctx: HandlerContext): TenantDb => {
+    if (ctx.systemDb) {
+      return ctx.systemDb.acknowledgeCrossTenant(
+        `entity convention handler for r.systemScope() feature (${entityName}:${verb})`,
+      );
+    }
+    return options?.crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+  };
 
   switch (verb) {
     case "list":

package/src/pipeline/__tests__/ctx-systemdb.integration.test.ts

@@ -13,13 +13,25 @@ const systemScopedFeature = defineFeature("ctxsystemdb-system", (r) => {
     "check",
     z.object({}),
     async (query, ctx) => {
-      if (!ctx.systemDb) return { present: false as const };
-      // assertTenantMatch returns the underlying TenantDb — proves systemDb
-      // is bound to the SAME internally-built TenantDb as ctx.db, not a
-      // separate instance (dispatch-shared.ts builds `as HandlerContext`,
-      // so a mis-wired property wouldn't be caught by tsc).
+      if (!ctx.systemDb)
+        return { present: false as const, tenantIdMatches: false, dbThrows: false };
+      // ctx.db is fail-closed for r.systemScope() handlers — dispatch-shared.ts
+      // builds `as HandlerContext`, so a mis-wired property wouldn't be caught
+      // by tsc. Prove it at runtime: assertTenantMatch must hand back a
+      // working, correctly-scoped TenantDb, and touching ctx.db itself must
+      // throw instead of silently returning an unfiltered db.
       const checked = ctx.systemDb.assertTenantMatch(query.user.tenantId);
-      return { present: true as const, boundToDb: checked === ctx.db };
+      let dbThrows = false;
+      try {
+        void ctx.db.tenantId;
+      } catch {
+        dbThrows = true;
+      }
+      return {
+        present: true as const,
+        tenantIdMatches: checked.tenantId === query.user.tenantId,
+        dbThrows,
+      };
     },
     { access: { roles: ["Admin"] } },
   );
@@ -29,7 +41,10 @@ const tenantScopedFeature = defineFeature("ctxsystemdb-tenant", (r) => {
   r.queryHandler(
     "check",
     z.object({}),
-    async (_query, ctx) => ({ present: ctx.systemDb !== undefined }),
+    async (query, ctx) => ({
+      present: ctx.systemDb !== undefined,
+      dbWorks: ctx.db.tenantId === query.user.tenantId,
+    }),
     { access: { roles: ["Admin"] } },
   );
 });
@@ -46,22 +61,24 @@ afterAll(async () => {
 });
 
 describe("ctx.systemDb", () => {
-  test("is present and bound to ctx.db for r.systemScope() handlers", async () => {
-    const result = await stack.http.queryOk<{ present: boolean; boundToDb: boolean }>(
-      "ctxsystemdb-system:query:check",
-      {},
-      admin,
-    );
+  test("is present for r.systemScope() handlers; ctx.db is fail-closed there", async () => {
+    const result = await stack.http.queryOk<{
+      present: boolean;
+      tenantIdMatches: boolean;
+      dbThrows: boolean;
+    }>("ctxsystemdb-system:query:check", {}, admin);
     expect(result.present).toBe(true);
-    expect(result.boundToDb).toBe(true);
+    expect(result.tenantIdMatches).toBe(true);
+    expect(result.dbThrows).toBe(true);
   });
 
-  test("is absent for non-system-scoped handlers", async () => {
-    const result = await stack.http.queryOk<{ present: boolean }>(
+  test("is absent for non-system-scoped handlers; ctx.db works normally there", async () => {
+    const result = await stack.http.queryOk<{ present: boolean; dbWorks: boolean }>(
       "ctxsystemdb-tenant:query:check",
       {},
       admin,
     );
     expect(result.present).toBe(false);
+    expect(result.dbWorks).toBe(true);
   });
 });

package/src/pipeline/cascade-handler.ts

@@ -17,13 +17,17 @@ export function createCascadeDeleteHook(
     priority: SystemHookPriorities.cascadeDelete,
     fn: async (payload, ctx) => {
       const entityName = payload.entityName;
-      if (!entityName || !ctx.db) {
+      const db = ctx.systemDb
+        ? ctx.systemDb.acknowledgeCrossTenant(
+            `cascade delete for r.systemScope() write handler (${entityName ?? "unknown"})`,
+          )
+        : ctx.db;
+      if (!entityName || !db) {
         ctx.log?.debug(
           `cascadeDelete: skipping — ${!entityName ? "no entityName" : "no db"} on payload ${payload.id}`,
         );
         return;
       }
-      const db = ctx.db;
 
       // Cascade applies to outgoing hasMany / manyToMany relations only —
       // the parent side of the link is where `onDelete` lives (see

package/src/pipeline/dispatch-shared.ts

@@ -3,7 +3,7 @@ import type { SseBroker } from "../api/sse-broker";
 import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import { runInSavepoint, selectMany } from "../db/query";
 import type { buildEntityTable } from "../db/table-builder";
-import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db";
+import { createTenantDb, createUncheckedSystemDb, type TenantDb } from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
@@ -155,6 +155,27 @@ async function appendDomainEvent(
   );
 }
 
+// r.systemScope() handlers must go through ctx.systemDb's guarded methods
+// (assertTenantMatch / acknowledgeCrossTenant) instead of plain ctx.db —
+// "system" mode has no tenant filter at all, so silent ctx.db use there is a
+// cross-tenant leak. HandlerContext.db has no way to become optional per
+// handler (isSystem is a runtime-only registry lookup, not a type-level
+// discriminant), so instead of omitting the key we hand back a Proxy that
+// throws on first touch, naming the handler and pointing at ctx.systemDb.
+function createSystemScopedDbGuard(handlerType: string): TenantDb {
+  return new Proxy({} as TenantDb, {
+    get(_target, prop) {
+      throw new InternalError({
+        message:
+          `Handler "${handlerType}" is r.systemScope()'d — ctx.db is unavailable ` +
+          `(it would be unfiltered across every tenant). Use ` +
+          `ctx.systemDb.assertTenantMatch(...) or ctx.systemDb.acknowledgeCrossTenant(...) ` +
+          `instead (attempted to read "${String(prop)}").`,
+      });
+    },
+  });
+}
+
 export async function buildHandlerContext(
   ctx: DispatchContext,
   type: string,
@@ -184,6 +205,10 @@ export async function buildHandlerContext(
   // the rest of the chain instead of burning DB-CPU for results no one reads.
   const db = dbSource ? buildTenantScopedDb(dbSource, reqCtx?.signal) : undefined;
   const systemDb = isSystem && db ? createUncheckedSystemDb(db) : undefined;
+  // Exposed as ctx.db below — the internal `db` above stays the real,
+  // working TenantDb for this function's own use (config/derivatives
+  // accessors, systemDb construction).
+  const exposedDb = isSystem && db ? createSystemScopedDbGuard(type) : db;
   // Unbound pool, tenant-scoped like `db` but never tx-bound — writes
   // through it survive a rollback of the handler's own transaction. No
   // AbortSignal here: a client disconnect must not abort a durability write
@@ -572,7 +597,7 @@ export async function buildHandlerContext(
   return {
     ...context,
     registry,
-    db,
+    db: exposedDb,
     dbOutsideTransaction,
     ...(systemDb && { systemDb }),
     log,

package/src/pipeline/dispatch-write.ts

@@ -350,10 +350,19 @@ async function executeWriteInner(
 
   const handlerContext = await buildHandlerContext(ctx, type, user, tx, afterCommitHooks);
 
-  // Auto transition guard: if entity has transitions and handler doesn't skip it
+  // Auto transition guard: if entity has transitions and handler doesn't skip it.
+  // Reads via the guard's own db handle — for r.systemScope() handlers
+  // handlerContext.db is fail-closed, so this reaches for
+  // systemDb.acknowledgeCrossTenant like any other framework-internal
+  // mechanism that touches a system-scoped handler's data.
+  const transitionGuardDb = handlerContext.systemDb
+    ? handlerContext.systemDb.acknowledgeCrossTenant(
+        `auto transition guard for r.systemScope() write handler (${type})`,
+      )
+    : handlerContext.db;
   if (entityName && !handler.unsafeSkipTransitionGuard) {
     const entity = registry.getEntity(entityName);
-    if (entity?.transitions && handlerContext.db) {
+    if (entity?.transitions && transitionGuardDb) {
       const parsedData = parsed.data as DbRow; // @cast-boundary engine-payload
       const changes = (parsedData["changes"] as DbRow) ?? parsedData; // @cast-boundary engine-payload
       const id = (parsedData["id"] as number) ?? undefined; // @cast-boundary engine-payload
@@ -373,8 +382,8 @@ async function executeWriteInner(
         // active (tests without a DB connection).
         const tableName = asEntityTableMeta(table)?.tableName ?? "";
         const rows = tx
-          ? await selectRowForUpdateById(handlerContext.db, tableName, id)
-          : await selectMany(handlerContext.db, table, { id });
+          ? await selectRowForUpdateById(transitionGuardDb, tableName, id)
+          : await selectMany(transitionGuardDb, table, { id });
         const row = rows[0];
 
         if (!row) continue;

package/src/pipeline/projections-runner.ts

@@ -26,7 +26,15 @@ import type { StoredEvent } from "../event-store";
 export async function runProjections(result: LifecycleResult, ctx: HandlerContext): Promise<void> {
   // skip: hand-crafted result with no event — nothing to project
   if (!result.event) return;
-  await runProjectionsForEvent(result.event, ctx.registry, ctx.db.raw);
+  // r.systemScope() handlers: ctx.db is fail-closed — custom projections are
+  // framework-wired, not per-handler opt-in, so this reaches for systemDb
+  // itself rather than pushing the concern onto every r.projection() author.
+  const tx = ctx.systemDb
+    ? ctx.systemDb.acknowledgeCrossTenant(
+        `inline projection apply for r.systemScope() write (${result.event.aggregateType})`,
+      ).raw
+    : ctx.db.raw;
+  await runProjectionsForEvent(result.event, ctx.registry, tx);
 }
 
 // Fire every projection whose source matches the event's aggregate type AND