@cosmicdrift/kumiko-samples 0.355.0 → 0.356.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.355.0",
+  "version": "0.356.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.355.0",
+  "version": "0.356.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>",

package/packages/bundled-features/src/compliance-profiles/handlers/set-profile.write.ts

@@ -11,6 +11,7 @@ import {
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import {
   tenantComplianceProfileEntity,
   tenantComplianceProfileTable,
@@ -26,24 +27,16 @@ const crud = createEventStoreExecutor(tenantComplianceProfileTable, tenantCompli
 // SELECTABLE_PROFILE_KEYS aus der framework/compliance-Liste.
 const profileKeySchema = z.enum(SELECTABLE_PROFILE_KEYS);
 
-// Tenant-Admin setzt Profile-Key + optional Override-JSON.
+// Upsert: the first call inserts, later calls update, so repeating the same values
+// is idempotent apart from the extra audit events.
 //
-// Upsert-Verhalten: erste Wahl insert, weitere update. Idempotent —
-// wer mit gleichen Werten zweimal aufruft, kriegt das gleiche Ergebnis
-// (modulo aktualisierte Audit-Events im Event-Store).
+// A SystemAdmin may target another tenant via `tenantIdOverride` (operator setup,
+// onboarding migrations); the dispatcher rejects the override for anyone else. The
+// executor then writes into the target tenant's stream via streamTenantId while
+// the operator stays the recorded actor.
 //
-// Cross-Tenant-Pfad: SystemAdmin kann via `tenantIdOverride` fuer einen
-// anderen Tenant schreiben (Plattform-Operator-Setup, Customer-
-// Onboarding-Migrationen). TenantAdmin's Override-Versuch → 403.
-// executorUser.tenantId muss = ziel-tenant sein damit der event-store-
-// Stream-Lookup nicht miss → version_conflict gibt (Memory:
-// feedback_event_store_tenant_consistency).
-//
-// Validation:
-//   - profileKey muss in SELECTABLE_PROFILE_KEYS sein (Zod-checked)
-//   - override (optional) muss valides JSON-Object sein
-//   - override Top-Level-Keys muessen in ALLOWED_OVERRIDE_KEYS sein
-//     — verhindert Tippfehler die deepMerge stillschweigend ignoriert
+// Override top-level keys are restricted to ALLOWED_OVERRIDE_KEYS because deepMerge
+// would silently ignore a typo.
 export const setProfileWrite = defineWriteHandler({
   name: "set-profile",
   schema: z.object({
@@ -57,9 +50,8 @@ export const setProfileWrite = defineWriteHandler({
   description:
     "Sets or replaces a tenant's compliance profile key plus an optional JSON override, for onboarding or a later region change; a system admin may target a different tenant through tenantIdOverride.",
   handler: async (event, ctx) => {
-    const tenantOverride = event.payload.tenantIdOverride;
-    const tenantId = (tenantOverride ?? event.user.tenantId) as TenantId; // @cast-boundary engine-payload
-    const executorUser = tenantOverride !== undefined ? { ...event.user, tenantId } : event.user;
+    const tenantId = (event.payload.tenantIdOverride ?? event.user.tenantId) as TenantId; // @cast-boundary engine-payload
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
 
     // Override-Validation: muss parseables JSON-Object sein UND dem
     // ComplianceProfileOverride-Schema entsprechen (S1.9 Z3 — strict-Zod
@@ -89,7 +81,7 @@ export const setProfileWrite = defineWriteHandler({
     }
 
     // Upsert: existierenden Eintrag suchen
-    const existing = (await fetchOne(ctx.db, tenantComplianceProfileTable, {
+    const existing = (await fetchOne(db, tenantComplianceProfileTable, {
       tenantId: tenantId,
     })) as { id: string; version: number } | null; // @cast-boundary db-runner
 
@@ -103,8 +95,9 @@ export const setProfileWrite = defineWriteHandler({
             override: event.payload.override ?? null,
           },
         },
-        executorUser,
-        ctx.db,
+        event.user,
+        db,
+        { streamTenantId },
       );
       if (!result.isSuccess) return result;
       return {
@@ -119,8 +112,9 @@ export const setProfileWrite = defineWriteHandler({
         override: event.payload.override ?? null,
         tenantId,
       },
-      executorUser,
-      ctx.db,
+      event.user,
+      db,
+      { streamTenantId },
     );
     if (!result.isSuccess) return result;
     return {

package/packages/bundled-features/src/custom-fields/handlers/define-system-field.write.ts

@@ -1,20 +1,15 @@
 import { SYSTEM_TENANT_ID, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { requireForTenant } from "../../shared/index.js";
 import { fieldDefinitionAggregateId } from "../aggregate-id.js";
 import { defineOrResurrectFieldDefinition } from "../lib/define-or-resurrect.js";
 import { buildFieldDefinitionColumns } from "../lib/field-definition-row.js";
 import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas.js";
 
-// define-system-field — SystemAdmin definiert eine system-weite Custom-Field-
-// Definition die für ALLE Tenants gilt. tenantId wird auf SYSTEM_TENANT_ID
-// gesetzt (NICHT vom Caller — SystemAdmin's event.user.tenantId würde sonst
-// auf den admin's eigenen platform-tenant zeigen).
-//
-// **Use-Case:** Vendor (cdgs) sagt "alle Hausverwaltungs-customers haben ab
-// heute ein `internalNumber`-Field". Tenant kann den Wert pro customer
-// setzen, aber die Definition nicht ändern oder löschen.
-//
-// **Same-scope-conflict** wie bei define-tenant-field via aggregate-version-
-// conflict (deterministische ID mit tenantId=SYSTEM_TENANT_ID).
+// A system-wide field definition applies to every tenant. tenantId is forced to
+// SYSTEM_TENANT_ID (never taken from the caller) and addressed via streamTenantId,
+// so the SystemAdmin stays the recorded actor. Tenants can set values for the field
+// but cannot change or delete the definition. A same-scope duplicate surfaces as an
+// aggregate version conflict, because the ID is derived from SYSTEM_TENANT_ID.
 export const defineSystemFieldHandler: WriteHandlerDef = {
   name: "define-system-field",
   schema: defineFieldPayloadSchema,
@@ -30,16 +25,14 @@ export const defineSystemFieldHandler: WriteHandlerDef = {
       payload.fieldKey,
     );
 
-    // Override event.user.tenantId to SYSTEM_TENANT_ID for the system-scope
-    // write. The framework's CrudExecutor writes the row with this tenantId
-    // — the row lives in the system-scope-stream.
-    const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
+    const { db, streamTenantId } = requireForTenant(ctx, SYSTEM_TENANT_ID);
 
     return defineOrResurrectFieldDefinition(
       aggregateId,
       buildFieldDefinitionColumns(payload),
-      systemUser,
-      ctx.db,
+      event.user,
+      db,
+      streamTenantId,
     );
   },
 };

package/packages/bundled-features/src/custom-fields/handlers/delete-system-field.write.ts

@@ -1,4 +1,5 @@
 import { SYSTEM_TENANT_ID, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { requireForTenant } from "../../shared/index.js";
 import { fieldDefinitionAggregateId } from "../aggregate-id.js";
 import { FIELD_DEFINITION_AGGREGATE_TYPE } from "../constants.js";
 import { fieldDefinitionExecutor } from "../executor.js";
@@ -26,8 +27,10 @@ export const deleteSystemFieldHandler: WriteHandlerDef = {
       payload.fieldKey,
     );
 
-    const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
-    const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, systemUser, ctx.db);
+    const { db, streamTenantId } = requireForTenant(ctx, SYSTEM_TENANT_ID);
+    const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, event.user, db, {
+      streamTenantId,
+    });
 
     // Cascade-cleanup-Event — host-entity-MSPs entfernen orphan values aus
     // ihrer customFields jsonb. Im selben TX = atomic.

package/packages/bundled-features/src/custom-fields/lib/define-or-resurrect.ts

@@ -1,3 +1,4 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionExecutor } from "../executor.js";
 import type { FieldDefinitionColumns } from "./field-definition-row.js";
 
@@ -27,13 +28,18 @@ export async function defineOrResurrectFieldDefinition(
   columns: FieldDefinitionColumns,
   user: DefineUser,
   db: DefineDb,
+  streamTenantId?: TenantId,
 ): Promise<WriteResult> {
   const active = await fieldDefinitionExecutor.detail({ id: aggregateId }, user, db);
   if (active) {
-    return fieldDefinitionExecutor.create({ id: aggregateId, ...columns }, user, db);
+    return fieldDefinitionExecutor.create({ id: aggregateId, ...columns }, user, db, {
+      streamTenantId,
+    });
   }
 
-  const restored = await fieldDefinitionExecutor.restore({ id: aggregateId }, user, db);
+  const restored = await fieldDefinitionExecutor.restore({ id: aggregateId }, user, db, {
+    streamTenantId,
+  });
   if (restored.isSuccess) {
     // restore() just un-deleted the row in this same tx; no concurrent writer
     // exists, so skip the optimistic-lock version match (we'd otherwise have to
@@ -43,10 +49,13 @@ export async function defineOrResurrectFieldDefinition(
     // readonly FieldDefinitionColumns isn't assignable to it.
     return fieldDefinitionExecutor.update({ id: aggregateId, changes: { ...columns } }, user, db, {
       skipOptimisticLock: true,
+      streamTenantId,
     });
   }
   if (restored.error.code === "not_found") {
-    return fieldDefinitionExecutor.create({ id: aggregateId, ...columns }, user, db);
+    return fieldDefinitionExecutor.create({ id: aggregateId, ...columns }, user, db, {
+      streamTenantId,
+    });
   }
   return restored;
 }

package/packages/bundled-features/src/managed-pages/handlers/set.write.ts

@@ -1,7 +1,8 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import { type PageRow, pageEntity, pagesTable } from "../table.js";
 
 const slugSchema = z
@@ -18,9 +19,6 @@ const langSchema = z
 
 const executor = createEventStoreExecutor(pagesTable, pageEntity, { entityName: "page" });
 
-const SET_PAGE_TENANT_OVERRIDE_REASON =
-  "SystemAdmin tenantIdOverride re-scopes the page write to the target tenant";
-
 // Upsert einer Page — eine Operation pro (tenantId, slug, lang). Tenant-
 // Scope default aus event.user; SystemAdmin kann via `tenantIdOverride`
 // für einen anderen Tenant schreiben (typisch SYSTEM_TENANT_ID für app-
@@ -43,29 +41,12 @@ export const setWrite = defineWriteHandler({
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
     "Creates or overwrites one managed page addressed by slug and language, keeping the existing published flag, description and OG image when the payload omits them; use it for content edits and publish toggles, and as SystemAdmin to write another tenant's pages.",
-  escapeHatch: {
-    grants: ["unsafeRaw"],
-    reason: SET_PAGE_TENANT_OVERRIDE_REASON,
-  },
   handler: async (event, ctx) => {
-    const db = ctx.db;
     const override = event.payload.tenantIdOverride;
-    const tenantId = override ?? event.user.tenantId;
-    // override: point the executor context at the target tenant, else getStreamVersion runs against user.tenantId → version_conflict.
-    const executorUser =
-      override !== undefined ? { ...event.user, tenantId: override as TenantId } : event.user; // @cast-boundary engine-bridge
-
+    const tenantId = (override ?? event.user.tenantId) as TenantId; // @cast-boundary engine-bridge
     // ctx.db is scoped to the executing user's tenant, wrong for a cross-tenant override
     // on both the existing-check and the executor's stream reads; re-scope to the target.
-    // Safe: the override branch is SystemAdmin-gated above.
-    const scopedDb =
-      override !== undefined
-        ? createTenantDb(
-            db.unsafeRaw(),
-            override as TenantId, // @cast-boundary engine-bridge
-            "tenant",
-          )
-        : db;
+    const { db: scopedDb, streamTenantId } = requireForTenant(ctx, tenantId);
     const existing = await fetchOne<PageRow>(scopedDb, pagesTable, {
       tenantId,
       slug: event.payload.slug,
@@ -89,8 +70,9 @@ export const setWrite = defineWriteHandler({
               event.payload.published !== undefined ? event.payload.published : existing.published,
           },
         },
-        executorUser,
+        event.user,
         scopedDb,
+        { streamTenantId },
       );
       if (!result.isSuccess) return result;
       return {
@@ -110,8 +92,9 @@ export const setWrite = defineWriteHandler({
         published: event.payload.published ?? false,
         tenantId,
       },
-      executorUser,
+      event.user,
       scopedDb,
+      { streamTenantId },
     );
     if (!result.isSuccess) return result;
     return {

package/packages/bundled-features/src/shared/index.ts

@@ -33,6 +33,7 @@ export {
   redactErrorText,
   redactUrls,
 } from "./redact.js";
+export { requireForTenant } from "./require-for-tenant.js";
 export {
   type RowBoundGrantResult,
   redeemRowBoundGrant,

package/packages/bundled-features/src/shared/require-for-tenant.ts

@@ -0,0 +1,18 @@
+import type {
+  HandlerContext,
+  TenantId,
+  TenantWriteTarget,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+
+// ctx.forTenant is absent for r.systemScope() handlers and without a db; a write handler that
+// needs a cross-tenant target must fail loudly instead of falling back to ctx.db.
+export function requireForTenant(
+  ctx: Pick<HandlerContext, "forTenant">,
+  targetTenantId: TenantId,
+): TenantWriteTarget {
+  if (!ctx.forTenant) {
+    throw new InternalError({ message: "ctx.forTenant is not available in this handler context" });
+  }
+  return ctx.forTenant(targetTenantId);
+}

package/packages/bundled-features/src/template-resolver/handlers/collection-set.write.ts

@@ -5,6 +5,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import {
   type CollectionEntryRow,
   collectionStore,
@@ -39,12 +40,11 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
         ? `Creates or overwrites the caller's own "${collection.id}" entry at a slug and locale, live on save with no draft stage; it always writes the acting user's entry, never another user's.`
         : `Creates or overwrites the tenant-wide "${collection.id}" entry at a slug and locale, live on save with no draft stage; the change is visible to everyone who may reach this shared collection.`,
     handler: async (event, ctx) => {
-      const db = ctx.db;
       const override = event.payload.tenantIdOverride;
       // @cast-boundary engine-payload — override is a zod-validated string, the
       // user's own tenantId is already TenantId-branded.
       const tenantId = (override ?? event.user.tenantId) as TenantId;
-      const executorUser = override !== undefined ? { ...event.user, tenantId } : event.user;
+      const { db, streamTenantId } = requireForTenant(ctx, tenantId);
       // Scoped to the acting user even under a tenant override: a SystemAdmin
       // writing into another tenant still writes their own entry, never
       // someone else's signature.
@@ -73,8 +73,9 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
               folder: event.payload.folder ?? null,
             },
           },
-          executorUser,
+          event.user,
           db,
+          { streamTenantId },
         );
         if (!result.isSuccess) return result;
         return {
@@ -96,8 +97,9 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
           ...store.createDefaults(tenantId),
           ...owner,
         },
-        executorUser,
+        event.user,
         db,
+        { streamTenantId },
       );
       if (!result.isSuccess) return result;
       return {

package/packages/bundled-features/src/template-resolver/handlers/set.write.ts

@@ -5,6 +5,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import { TEMPLATE_KINDS, TEXT_BLOCK_KIND } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 import { contentFormatSchema, executor, folderSchema, localeSchema, slugSchema } from "./shared.js";
@@ -48,15 +49,11 @@ export const setWrite = defineWriteHandler({
   description:
     "Creates or overwrites one content-tree resource addressed by slug, kind and locale, carrying a title and folder and going live on save with no draft stage; a SystemAdmin may target the system tenant, where shared legal and marketing copy lives.",
   handler: async (event, ctx) => {
-    const db = ctx.db;
     const override = event.payload.tenantIdOverride;
     // @cast-boundary engine-payload — override is a zod-validated string, the
     // user's own tenantId is already TenantId-branded.
     const tenantId = (override ?? event.user.tenantId) as TenantId;
-    // With an override the executor user has to move to the target tenant too,
-    // otherwise the event-store stream lookup runs against event.user.tenantId
-    // and reports a version conflict although the projection row exists.
-    const executorUser = override !== undefined ? { ...event.user, tenantId } : event.user;
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
 
     const kind = event.payload.kind ?? TEXT_BLOCK_KIND;
     const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
@@ -98,8 +95,9 @@ export const setWrite = defineWriteHandler({
             folder: fields.folder,
           },
         },
-        executorUser,
+        event.user,
         db,
+        { streamTenantId },
       );
       if (!result.isSuccess) return result;
       return {
@@ -108,7 +106,9 @@ export const setWrite = defineWriteHandler({
       };
     }
 
-    const result = await executor.create({ ...fields, tenantId }, executorUser, db);
+    const result = await executor.create({ ...fields, tenantId }, event.user, db, {
+      streamTenantId,
+    });
     if (!result.isSuccess) return result;
     return {
       isSuccess: true as const,

package/packages/bundled-features/src/template-resolver/handlers/upsert-system.write.ts

@@ -4,6 +4,7 @@ import {
   SYSTEM_TENANT_ID,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { requireForTenant } from "../../shared/index.js";
 import type { TemplateResourceRow } from "../table.js";
 import { templateResourcesTable } from "../table.js";
 import { executor, upsertPayloadSchema } from "./shared.js";
@@ -19,13 +20,10 @@ export const upsertSystemWrite = defineWriteHandler({
   description:
     "Creates or overwrites a system-default template under the system tenant with its full variable schema and linked resources, active straight away with no draft stage; SystemAdmin only, since tenants shadow these defaults through upsert-tenant instead.",
   handler: async (event, ctx) => {
-    const db = ctx.db;
     // @cast-boundary engine-payload — SYSTEM_TENANT_ID is a UUID literal,
     // asserted to the branded TenantId (parseTenantId equivalent).
     const tenantId = SYSTEM_TENANT_ID as TenantId;
-    // The executor user must carry SYSTEM_TENANT as tenantId, otherwise the
-    // event store looks up the stream under user.tenantId → conflict.
-    const executorUser = { ...event.user, tenantId };
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
 
     const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
       tenantId,
@@ -53,8 +51,9 @@ export const upsertSystemWrite = defineWriteHandler({
     if (existing) {
       const result = await executor.update(
         { id: existing.id, version: existing.version, changes: fields },
-        executorUser,
+        event.user,
         db,
+        { streamTenantId },
       );
       if (!result.isSuccess) return result;
       return {
@@ -63,7 +62,9 @@ export const upsertSystemWrite = defineWriteHandler({
       };
     }
 
-    const result = await executor.create({ ...fields, tenantId }, executorUser, db);
+    const result = await executor.create({ ...fields, tenantId }, event.user, db, {
+      streamTenantId,
+    });
     if (!result.isSuccess) return result;
     // @cast-boundary db-row — executor.create returnt Record-row aus
     // INSERT RETURNING; shape { id } ist garantiert weil PK in der

package/packages/bundled-features/src/template-resolver/handlers/upsert-tenant.write.ts

@@ -6,6 +6,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { AccessDeniedError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import type { TemplateResourceRow } from "../table.js";
 import { templateResourcesTable } from "../table.js";
 import { executor, upsertPayloadSchema } from "./shared.js";
@@ -25,7 +26,6 @@ export const upsertTenantWrite = defineWriteHandler({
   description:
     "Creates or overwrites a tenant-scoped template override with its variable schema, landing as a draft that only publish makes live; it refuses a system-tenant target, which is what upsert-system is for.",
   handler: async (event, ctx) => {
-    const db = ctx.db;
     const override = event.payload.tenantIdOverride;
     // upsertTenant erzeugt scope='tenant'. SYSTEM_TENANT_ID-Override würde
     // scope='tenant' unter SYSTEM_TENANT_ID schreiben → inkonsistenter Zustand
@@ -43,7 +43,7 @@ export const upsertTenantWrite = defineWriteHandler({
     // event.user.tenantId schon TenantId-branded; union als TenantId casten
     // ist legit (override ist UUID-Format-validiert in schema).
     const tenantId = (override ?? event.user.tenantId) as TenantId;
-    const executorUser = override !== undefined ? { ...event.user, tenantId } : event.user;
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
 
     const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
       tenantId,
@@ -70,8 +70,9 @@ export const upsertTenantWrite = defineWriteHandler({
     if (existing) {
       const result = await executor.update(
         { id: existing.id, version: existing.version, changes: fields },
-        executorUser,
+        event.user,
         db,
+        { streamTenantId },
       );
       if (!result.isSuccess) return result;
       return {
@@ -80,7 +81,9 @@ export const upsertTenantWrite = defineWriteHandler({
       };
     }
 
-    const result = await executor.create({ ...fields, tenantId }, executorUser, db);
+    const result = await executor.create({ ...fields, tenantId }, event.user, db, {
+      streamTenantId,
+    });
     if (!result.isSuccess) return result;
     // @cast-boundary db-row — executor.create returnt Record-row aus
     // INSERT RETURNING; shape { id } ist garantiert weil PK in der

package/packages/bundled-features/src/tenant/cancel-pending-invitation.ts

@@ -1,5 +1,5 @@
 import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
 import type { Redis } from "ioredis";
 // kumiko-lint-ignore cross-feature-import cancel needs invite-token-store for Redis cleanup
@@ -23,6 +23,7 @@ export async function cancelPendingInvitation(
   invitation: { readonly id: string; readonly version: number },
   actor: SessionUser,
   redis: Redis | undefined,
+  streamTenantId?: TenantId,
 ): Promise<WriteFailure | undefined> {
   const updateResult = await invitationExecutor.update(
     {
@@ -32,6 +33,7 @@ export async function cancelPendingInvitation(
     },
     actor,
     db,
+    { streamTenantId },
   );
   if (!updateResult.isSuccess) return updateResult;
 

package/packages/bundled-features/src/tenant/handlers/remove-member.write.ts

@@ -7,7 +7,9 @@ import {
 import {
   createSystemUser,
   defineWriteHandler,
+  parseTenantId,
   type SessionUser,
+  type TenantId,
   withResponseData,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -34,6 +36,7 @@ type PendingInvitationCancel = {
   readonly userId: string;
   readonly tenantId: string;
   readonly actor: SessionUser;
+  readonly streamTenantId: TenantId;
   readonly redis: Redis | undefined;
 };
 
@@ -51,7 +54,13 @@ async function cancelPendingInvitationsOfUser(
     { tenantId: options.tenantId, email, status: INVITATION_STATUS.pending },
   );
   for (const invitation of pendingInvitations) {
-    const failure = await cancelPendingInvitation(db, invitation, options.actor, options.redis);
+    const failure = await cancelPendingInvitation(
+      db,
+      invitation,
+      options.actor,
+      options.redis,
+      options.streamTenantId,
+    );
     if (failure) return failure;
   }
   return undefined;
@@ -79,11 +88,15 @@ export const removeMemberWrite = defineWriteHandler({
     const db = ctx.systemDb.acknowledgeCrossTenant(
       "SystemAdmin manages memberships across tenants",
     );
-    const existing = await fetchOne(db, tenantMembershipsTable, {
-      userId: event.payload.userId,
-      tenantId: event.payload.tenantId,
-    });
-    if (!existing) {
+    const streamTenantId = parseTenantId(event.payload.tenantId);
+    const existing =
+      streamTenantId === null
+        ? undefined
+        : await fetchOne(db, tenantMembershipsTable, {
+            userId: event.payload.userId,
+            tenantId: streamTenantId,
+          });
+    if (!existing || streamTenantId === null) {
       return writeFailure(
         new NotFoundError("membership", undefined, {
           i18nKey: "tenant.errors.membershipNotFound",
@@ -125,14 +138,15 @@ export const removeMemberWrite = defineWriteHandler({
       { id: (existing as DbRow)["id"] as string }, // @cast-boundary db-row
       event.user,
       db,
+      { streamTenantId },
     );
     if (!result.isSuccess) return result;
 
-    // Actor tenant = invitation tenant so the update hits the invitation's stream.
     const cancelFailure = await cancelPendingInvitationsOfUser(db, {
       userId: event.payload.userId,
       tenantId: event.payload.tenantId,
-      actor: { ...event.user, tenantId: event.payload.tenantId },
+      actor: event.user,
+      streamTenantId,
       redis: ctx.redis,
     });
     if (cancelFailure !== undefined) return cancelFailure;

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

@@ -6,8 +6,12 @@ import {
   createSystemUser,
   defineWriteHandler,
   findForbiddenRoleAssignment,
+  mayOverrideTenant,
   mergeAssignedRoles,
+  parseTenantId,
+  type SessionUser,
   SYSTEM_ROLE,
+  type TenantId,
   withResponseData,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -40,9 +44,14 @@ const REVOKE_ALL_SESSIONS_QN = "sessions:write:user-session:revoke-all-for-user"
 function resolveTargetTenantId(
   isSystem: boolean,
   payloadTenantId: string | undefined,
-  sessionTenantId: string | undefined,
-): string | undefined {
-  return isSystem ? (payloadTenantId ?? sessionTenantId) : sessionTenantId;
+  sessionTenantId: TenantId,
+): TenantId | undefined {
+  if (!isSystem || payloadTenantId === undefined) return sessionTenantId;
+  return parseTenantId(payloadTenantId) ?? undefined;
+}
+
+function foreignStreamTenant(user: SessionUser, targetTenantId: TenantId): TenantId | undefined {
+  return targetTenantId === user.tenantId ? undefined : targetTenantId;
 }
 
 // Editing your OWN roles keeps the current session: roles are re-derived per
@@ -50,7 +59,7 @@ function resolveTargetTenantId(
 // of that user and any foreign edit still revoke all.
 function revokeSessionsPayload(
   targetUserId: string,
-  targetTenantId: string,
+  targetTenantId: TenantId,
   actor: { readonly id: string; readonly sid?: string | undefined },
 ): { userId: string; tenantId: string; exceptSessionId?: string } {
   const payload = { userId: targetUserId, tenantId: targetTenantId };
@@ -82,7 +91,7 @@ export const updateMemberRolesWrite = defineWriteHandler({
     }
 
     const isSystemActor = event.user.roles.includes(SYSTEM_ROLE);
-    const isSystem = event.user.roles.includes("SystemAdmin") || isSystemActor;
+    const isSystem = mayOverrideTenant(event.user) || isSystemActor;
     const assignableAppRoles = assignableAppRolesOf(ctx.registry);
     const targetTenantId = resolveTargetTenantId(
       isSystem,
@@ -185,19 +194,18 @@ export const updateMemberRolesWrite = defineWriteHandler({
       );
     }
 
-    // Stream tenant follows the actor via streamTenantFor — use the
-    // membership tenant so SystemAdmin/cross-tenant and TenantAdmin paths
-    // hit the same stream seedTenantMembership/invite-accept wrote.
-    // Keep the real actor for audit metadata; only override tenantId so
-    // streamTenantFor writes into the membership tenant (#2401).
+    // The membership stream lives on the membership's tenant (where seedTenantMembership/
+    // invite-accept wrote it); a cross-tenant operator addresses it without becoming a member.
+    // Same-tenant writes run on a tenant-mode db, which refuses a stream override.
     const result = await executor.update(
       {
         id: row["id"] as string, // @cast-boundary db-row
         version: row["version"] as number, // @cast-boundary db-row
         changes: { roles: JSON.stringify(nextRoles) },
       },
-      { ...event.user, tenantId: targetTenantId },
+      event.user,
       db,
+      { streamTenantId: foreignStreamTenant(event.user, targetTenantId) },
     );
 
     return withResponseData(result, {

package/packages/bundled-features/src/tier-engine/handlers/set-tenant-tier.write.ts

@@ -1,11 +1,8 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import {
-  buildEntityTable,
-  createEventStoreExecutor,
-  createTenantDb,
-} from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import { tierAssignmentAggregateId } from "../aggregate-id.js";
 import { TierAssignmentSources } from "../constants.js";
 import { type TierAssignmentRow, tierAssignmentEntity } from "../entity.js";
@@ -14,13 +11,8 @@ import { type TierAssignmentRow, tierAssignmentEntity } from "../entity.js";
 // Billing. Cross-tenant, daher SystemAdmin-only (kein TenantAdmin: sonst
 // Gratis-Self-Upgrade).
 //
-// **Cross-tenant-Mechanik:** ein "system"-mode TenantDb auf den Ziel-Tenant legt
-// KEINEN Tenant-Filter an (tenant-db.ts:141 — mode==="system" überspringt ihn);
-// der executor-user wird ebenfalls auf den Ziel-Tenant gestellt, sonst landet das
-// Event im Stream des Admins (Memory feedback_event_store_tenant_consistency).
-// Das set.write-"override-user"-Muster trägt NICHT für beliebige Tenants — es
-// funktioniert nur für SYSTEM_TENANT_ID (immer im IN-Filter). Dies ist das
-// auto-default-Hook-Muster (feature.ts), generalisiert auf einen Request-Handler.
+// Cross-tenant mechanics: ctx.forTenant(tenantId) yields a tenant-mode db bound to the target plus
+// the streamTenantId, so the event lands in the target's stream with the operator as actor.
 //
 // `source: TierAssignmentSources.manual` marks the grant so the billing sync skips it.
 // Upsert: one aggregate per tenant (deterministic aggregate id).
@@ -38,8 +30,6 @@ const executor = createEventStoreExecutor(tierAssignmentTable, tierAssignmentEnt
   entityName: "tier-assignment",
 });
 
-const SET_TENANT_TIER_REASON = "SystemAdmin assigns the tier of the tenant named in the payload";
-
 export type SetTenantTierOptions = {
   /** Runs after the write commits so feature.ts can update the resolver cache
    *  and notify the other processes. Without a tierMap there is no resolver
@@ -68,10 +58,6 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
     }),
     access: { roles: ["SystemAdmin"] },
     agent: { risk: "high" },
-    escapeHatch: {
-      grants: ["unsafeRaw"],
-      reason: SET_TENANT_TIER_REASON,
-    },
     handler: async (event, ctx) => {
       // Without a commit sink (unit harness) there is no transaction to wait for.
       const afterCommit = (tenantId: TenantId, tier: string): void => {
@@ -80,9 +66,7 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
         else opts.onAssigned?.(tenantId, tier);
       };
       const tenantId = event.payload.tenantId as TenantId; // @cast-boundary engine-bridge
-      const rawDb = ctx.db.unsafeRaw();
-      const tdb = createTenantDb(rawDb, tenantId, "system");
-      const systemUser = { ...event.user, tenantId };
+      const { db: tdb, streamTenantId } = requireForTenant(ctx, tenantId);
       const tier = event.payload.tier;
 
       const existing = await fetchOne<TierAssignmentRow>(tdb, tierAssignmentTable, { tenantId });
@@ -94,8 +78,9 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
             version: existing.version,
             changes: { tier, source: TierAssignmentSources.manual },
           },
-          systemUser,
+          event.user,
           tdb,
+          { streamTenantId },
         );
         if (!result.isSuccess) return result;
         afterCommit(tenantId, tier);
@@ -109,8 +94,9 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
           source: TierAssignmentSources.manual,
           tenantId,
         },
-        systemUser,
+        event.user,
         tdb,
+        { streamTenantId },
       );
       if (!result.isSuccess) return result;
       afterCommit(tenantId, tier);