@cosmicdrift/kumiko-samples 0.389.0 → 0.390.0

package/packages/bundled-features/src/tenant/testing.ts

@@ -4,4 +4,81 @@
 // stable contract here; test-specific options do not belong in this module,
 // because they could break development boots when a lockout-test option is added.
 
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
+import {
+  deleteRowViaEventStore,
+  updateRowViaEventStore,
+} from "@cosmicdrift/kumiko-testing/helpers";
+import { tenantInvitationEntity, tenantInvitationsTable } from "./invitation-table.ts";
+import { tenantMembershipEntity, tenantMembershipsTable } from "./membership-table.ts";
+import { tenantEntity, tenantTable } from "./schema/tenant.ts";
+
 export * from "./seeding.ts";
+
+const membershipTarget = {
+  table: tenantMembershipsTable,
+  entity: tenantMembershipEntity,
+  entityName: "tenant-membership",
+} as const;
+
+const tenantTarget = { table: tenantTable, entity: tenantEntity, entityName: "tenant" } as const;
+
+type MembershipKey = { readonly userId: string; readonly tenantId: TenantId };
+
+// The membership stream lives on the membership's own tenant, so actor and stream tenant both use it.
+export function setMembershipRolesViaEventStore(
+  db: DbConnection,
+  params: MembershipKey & { readonly roles: readonly string[] },
+): Promise<void> {
+  const { userId, tenantId, roles } = params;
+  return updateRowViaEventStore(
+    db,
+    membershipTarget,
+    { userId, tenantId },
+    { roles: JSON.stringify(roles) },
+    { tenantId, streamTenantId: tenantId },
+  );
+}
+
+export function deleteMembershipViaEventStore(db: DbConnection, key: MembershipKey): Promise<void> {
+  return deleteRowViaEventStore(
+    db,
+    membershipTarget,
+    { userId: key.userId, tenantId: key.tenantId },
+    { tenantId: key.tenantId, streamTenantId: key.tenantId },
+  );
+}
+
+// Tenant streams live on the creator's tenant, which is the seed SystemAdmin's for every tenant a test creates.
+export function updateTenantViaEventStore(
+  db: DbConnection,
+  tenantId: TenantId,
+  changes: Readonly<Record<string, unknown>>,
+  actorTenantId: TenantId = TestUsers.systemAdmin.tenantId,
+): Promise<void> {
+  return updateRowViaEventStore(db, tenantTarget, { id: tenantId }, changes, {
+    tenantId: actorTenantId,
+  });
+}
+
+// Invitation streams live on the inviting tenant.
+export function updateInvitationViaEventStore(
+  db: DbConnection,
+  email: string,
+  changes: Readonly<Record<string, unknown>>,
+  tenantId: TenantId,
+): Promise<void> {
+  return updateRowViaEventStore(
+    db,
+    {
+      table: tenantInvitationsTable,
+      entity: tenantInvitationEntity,
+      entityName: "tenant-invitation",
+    },
+    { email },
+    changes,
+    { tenantId },
+  );
+}

package/packages/bundled-features/src/tenant-handover/events.ts

@@ -8,7 +8,7 @@ import * as z from "zod";
 //
 // _SHORT — r.defineEvent(short, schema) in feature.ts, framework prefixes it
 //          to the QN below.
-// _QN    — ctx.unsafeAppendEvent({ type })'s `type` field.
+// _QN    — ctx.events.unsafeAppend({ type })'s `type` field.
 export const TENANT_HANDOVER_CLAIMED_EVENT_SHORT = "claimed" as const;
 export const TENANT_HANDOVER_CLAIMED_EVENT_QN = "tenant-handover:event:claimed" as const;
 export const TENANT_HANDOVER_CLAIM_AGGREGATE_TYPE = "tenant-handover-claim" as const;

package/packages/bundled-features/src/tenant-handover/handlers/claim.write.ts

@@ -92,7 +92,7 @@ export function createClaimTenantHandoverHandler(opts: ClaimTenantHandoverOption
           // Own aggregate, decoupled from the transferred root's stream (see
           // events.ts) — a fresh id needs no predecessor version and can't
           // conflict with a concurrent write on the entity it describes.
-          await ctx.unsafeAppendEvent({
+          await ctx.events.unsafeAppend({
             aggregateId: generateId(),
             aggregateType: TENANT_HANDOVER_CLAIM_AGGREGATE_TYPE,
             type: TENANT_HANDOVER_CLAIMED_EVENT_QN,

package/packages/bundled-features/src/tenant-lifecycle/feature.ts

@@ -150,11 +150,11 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
           db: ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
           registry: ctx.registry,
           now,
-          log: (message) => ctx.log?.warn(message),
-          fileProviderResolver: ctx._fileProviderResolver,
-          searchAdapter: ctx.searchAdapter,
-          escapeHatchAuditSink: ctx._escapeHatchAuditSink,
-          escapeHatchAuditLog: ctx.log,
+          log: (message) => ctx.obs.log?.warn(message),
+          fileProviderResolver: ctx.services._fileProviderResolver,
+          searchAdapter: ctx.services.searchAdapter,
+          escapeHatchAuditSink: ctx.services._escapeHatchAuditSink,
+          escapeHatchAuditLog: ctx.obs.log,
           actor: ctx.systemUser.id,
         });
       },

package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts

@@ -1,10 +1,11 @@
 import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { appendDomainEventCore } from "@cosmicdrift/kumiko-framework/pipeline";
 import * as z from "zod";
 import { isWithinGracePeriod } from "../../shared/index.ts";
 import { type TenantLifecycleStatus, tenantEntity, tenantTable } from "../../tenant/index.ts";
-import { DESTRUCTION_CANCELLED_EVENT_QN } from "../constants.ts";
+import { DESTRUCTION_CANCELLED_EVENT_QN, TENANT_LIFECYCLE_FEATURE } from "../constants.ts";
 import { invalidateTenantLifecycleGate } from "../lifecycle-gate.ts";
 
 const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
@@ -15,7 +16,7 @@ type TenantLifecycleRow = {
 };
 
 const CANCEL_DESTRUCTION_TENANT_ROW_REASON =
-  "reads the caller's tenant row, whose tenant_id is the creating tenant, not the row's own id";
+  "reads the caller's tenant row (a global row on the system tenant) and appends to the tenant stream on the system tenant";
 
 export const cancelDestructionWrite = defineWriteHandler({
   name: "cancel-destruction",
@@ -29,7 +30,8 @@ export const cancelDestructionWrite = defineWriteHandler({
   },
   handler: async (event, ctx) => {
     const tenantId = event.user.tenantId;
-    const row = await fetchOne<TenantLifecycleRow>(ctx.db.unsafeRaw(), tenantTable, {
+    const runner = ctx.db.unsafeRaw();
+    const row = await fetchOne<TenantLifecycleRow>(runner, tenantTable, {
       id: tenantId,
     });
     if (!row) {
@@ -64,12 +66,22 @@ export const cancelDestructionWrite = defineWriteHandler({
     if (!update.isSuccess) return update;
     invalidateTenantLifecycleGate(tenantId);
 
-    await ctx.unsafeAppendEvent({
-      aggregateId: tenantId,
-      aggregateType: "tenant",
-      type: DESTRUCTION_CANCELLED_EVENT_QN,
-      payload: { cancelledBy: event.user.id },
-    });
+    await appendDomainEventCore(
+      {
+        registry: ctx.registry,
+        db: runner,
+        tenantId: SYSTEM_TENANT_ID,
+        userId: String(event.user.id),
+        callSiteLabel: "tenant-lifecycle cancel-destruction",
+        callerFeature: TENANT_LIFECYCLE_FEATURE,
+      },
+      {
+        aggregateId: tenantId,
+        aggregateType: "tenant",
+        type: DESTRUCTION_CANCELLED_EVENT_QN,
+        payload: { cancelledBy: event.user.id },
+      },
+    );
 
     const gracePeriodEnd: string | null = null;
     return {

package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts

@@ -1,12 +1,13 @@
 import { addDurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
 import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { appendDomainEventCore } from "@cosmicdrift/kumiko-framework/pipeline";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 import { resolveProfileForTenant } from "../../compliance-profiles/index.ts";
 import { type TenantLifecycleStatus, tenantEntity, tenantTable } from "../../tenant/index.ts";
-import { DESTRUCTION_REQUESTED_EVENT_QN } from "../constants.ts";
+import { DESTRUCTION_REQUESTED_EVENT_QN, TENANT_LIFECYCLE_FEATURE } from "../constants.ts";
 import { revokeTenantSessions } from "../lib/revoke-tenant-sessions.ts";
 import { invalidateTenantLifecycleGate } from "../lifecycle-gate.ts";
 
@@ -18,7 +19,7 @@ type TenantLifecycleRow = {
 };
 
 const REQUEST_DESTRUCTION_TENANT_ROW_REASON =
-  "reads the caller's tenant row, whose tenant_id is the creating tenant, its compliance profile, and revokes its sessions via DbRunner helpers";
+  "reads the caller's tenant row (a global row on the system tenant), its compliance profile, appends to the tenant stream on the system tenant and revokes its sessions via DbRunner helpers";
 
 export const requestDestructionWrite = defineWriteHandler({
   name: "request-destruction",
@@ -67,15 +68,25 @@ export const requestDestructionWrite = defineWriteHandler({
     if (!update.isSuccess) return update;
     invalidateTenantLifecycleGate(tenantId);
 
-    await ctx.unsafeAppendEvent({
-      aggregateId: tenantId,
-      aggregateType: "tenant",
-      type: DESTRUCTION_REQUESTED_EVENT_QN,
-      payload: {
-        requestedBy: event.user.id,
-        gracePeriodEnd: gracePeriodEnd.toString(),
+    await appendDomainEventCore(
+      {
+        registry: ctx.registry,
+        db: runner,
+        tenantId: SYSTEM_TENANT_ID,
+        userId: String(event.user.id),
+        callSiteLabel: "tenant-lifecycle request-destruction",
+        callerFeature: TENANT_LIFECYCLE_FEATURE,
+      },
+      {
+        aggregateId: tenantId,
+        aggregateType: "tenant",
+        type: DESTRUCTION_REQUESTED_EVENT_QN,
+        payload: {
+          requestedBy: event.user.id,
+          gracePeriodEnd: gracePeriodEnd.toString(),
+        },
       },
-    });
+    );
 
     if (await ctx.hasFeature("sessions")) {
       await revokeTenantSessions(runner, tenantId);

package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -10,6 +10,7 @@ import {
   createSystemUser,
   type EscapeHatchAuditSink,
   type Registry,
+  SYSTEM_TENANT_ID,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -133,7 +134,7 @@ async function appendTenantStageEvent(
   await append(db, {
     aggregateId: tenantId,
     aggregateType: TENANT_AGGREGATE_TYPE,
-    tenantId,
+    tenantId: SYSTEM_TENANT_ID,
     expectedVersion,
     type,
     payload,
@@ -153,14 +154,14 @@ async function appendTenantStageEventIdempotent(
   alreadyRecorded: boolean,
 ): Promise<number> {
   if (alreadyRecorded) {
-    const events = await loadAggregate(db, tenantId, tenantId);
+    const events = await loadAggregate(db, tenantId, SYSTEM_TENANT_ID);
     return lastEventVersion(events);
   }
   try {
     await appendTenantStageEvent(db, tenantId, type, payload, expectedVersion);
   } catch (err) {
     if (!(err instanceof VersionConflictError)) throw err;
-    const events = await loadAggregate(db, tenantId, tenantId);
+    const events = await loadAggregate(db, tenantId, SYSTEM_TENANT_ID);
     const stage = String(payload["stage"] ?? "");
     if (stageOutcomeRecorded(events, stage, TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT)) {
       // skip: idempotent retry — stage already recorded before version conflict
@@ -168,13 +169,18 @@ async function appendTenantStageEventIdempotent(
     }
     throw err;
   }
-  const events = await loadAggregate(db, tenantId, tenantId);
+  const events = await loadAggregate(db, tenantId, SYSTEM_TENANT_ID);
   return lastEventVersion(events);
 }
 
 async function markTenantDestroyFailed(db: DbRunner, tenantId: TenantId): Promise<void> {
   const user = createSystemUser(tenantId);
-  const scopedDb = createTenantDb({ db, tenantId, mode: "system" });
+  const scopedDb = createTenantDb({
+    db,
+    tenantId,
+    mode: "system",
+    reason: "tenant destruction updates the tenant being destroyed, outside its request scope",
+  });
   await tenantCrud.update(
     {
       id: tenantId,
@@ -200,7 +206,7 @@ async function haltPipelineOnAbandon(args: {
   // stage's own run() may have appended to this same aggregate (e.g.
   // tombstoneTenantRow's tenantCrud.update) before throwing, so any version
   // captured earlier in the pipeline is stale and would VersionConflict here.
-  const eventsBeforeAbandon = await loadAggregate(args.db, args.tenantId, args.tenantId);
+  const eventsBeforeAbandon = await loadAggregate(args.db, args.tenantId, SYSTEM_TENANT_ID);
   await appendTenantStageEvent(
     args.db,
     args.tenantId,
@@ -208,7 +214,7 @@ async function haltPipelineOnAbandon(args: {
     { stage: args.stage, attempts: args.attempts, error: args.error },
     lastEventVersion(eventsBeforeAbandon),
   );
-  const eventsAfterAbandon = await loadAggregate(args.db, args.tenantId, args.tenantId);
+  const eventsAfterAbandon = await loadAggregate(args.db, args.tenantId, SYSTEM_TENANT_ID);
   const versionAfterAbandon = lastEventVersion(eventsAfterAbandon);
   await appendTenantStageEvent(
     args.db,
@@ -229,7 +235,7 @@ async function maybeAppendDestructionCompleted(
     // skip: pipeline still has pending stages
     return;
   }
-  const events = await loadAggregate(db, tenantId, tenantId);
+  const events = await loadAggregate(db, tenantId, SYSTEM_TENANT_ID);
   if (events.some((event) => event.type === TENANT_DESTRUCTION_COMPLETED_EVENT_QN)) {
     // skip: idempotent — completion event already recorded
     return;
@@ -293,7 +299,7 @@ export async function runNextDestructionStage(args: {
   readonly actor?: string;
   readonly deadlineAt?: number;
 }): Promise<StageTickResult> {
-  const events = await loadAggregate(args.db, args.tenantId, args.tenantId);
+  const events = await loadAggregate(args.db, args.tenantId, SYSTEM_TENANT_ID);
   const { completed, abandoned, attemptsByStage } = replayStageState(events);
 
   if (abandoned.size > 0) {
@@ -339,7 +345,7 @@ export async function runNextDestructionStage(args: {
     // tombstoneTenantRow updates the tenant row on the same stream) — reload
     // the version fresh instead of trusting the pre-run `version`, or this
     // append throws VersionConflictError on every stage whose run() writes.
-    const eventsAfterRun = await loadAggregate(args.db, args.tenantId, args.tenantId);
+    const eventsAfterRun = await loadAggregate(args.db, args.tenantId, SYSTEM_TENANT_ID);
     // A tick that neither finishes nor processes anything would otherwise loop
     // forever, because progressed events do not count as attempts.
     if (!outcome.done && outcome.processed === 0) {
@@ -429,10 +435,15 @@ export async function runTenantDestructionSweep(args: {
   let triggered = 0;
   for (const row of due) {
     const tenantId = row.id;
-    const events = await loadAggregate(args.db, tenantId, tenantId);
+    const events = await loadAggregate(args.db, tenantId, SYSTEM_TENANT_ID);
     const version = lastEventVersion(events);
     const user = createSystemUser(tenantId);
-    const scopedDb = createTenantDb({ db: args.db, tenantId, mode: "system" });
+    const scopedDb = createTenantDb({
+      db: args.db,
+      tenantId,
+      mode: "system",
+      reason: "tenant destruction updates the tenant being destroyed, outside its request scope",
+    });
     // Version-guarded (no skipOptimisticLock): a concurrent cancel-destruction
     // between the `due` select above and this write also appends to the same
     // tenant stream, so an unguarded overwrite here would silently revert the

package/packages/bundled-features/src/tenant-lifecycle/stages.ts

@@ -57,8 +57,7 @@ export type DestructionStageCtx = {
   // "destroyTenant" hooks) — undefined when no file-provider is wired,
   // which those hooks must treat as "nothing to clean up", not an error.
   readonly fileProviderResolver?: FileProviderResolver;
-  // Derived search docs of the tenant record (its name) live in the writer's
-  // index, not the destroyed tenant's, so the subject-keys stage purges them.
+  // The tenant record's derived search docs (its name) sit in the SYSTEM bucket; the subject-keys stage purges them.
   readonly searchAdapter?: SearchAdapter;
   // Sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); runTenantDataHooks uses them to attribute+audit any
@@ -241,7 +240,12 @@ async function purgeTenantCache(ctx: DestructionStageCtx): Promise<StageRunOutco
 async function tombstoneTenantRow(ctx: DestructionStageCtx): Promise<StageRunOutcome> {
   const now = getTemporal().Now.instant();
   const user = createSystemUser(ctx.tenantId);
-  const db = createTenantDb({ db: ctx.db, tenantId: ctx.tenantId, mode: "system" });
+  const db = createTenantDb({
+    db: ctx.db,
+    tenantId: ctx.tenantId,
+    mode: "system",
+    reason: "destruction stage tombstones the row of the tenant being destroyed",
+  });
   // Per-row forget() through the executor, not a bulk deleteMany: memberships
   // are an ES-managed projection (add/remove/update-roles all go through
   // tenantMembershipCrud), so a store table write here is eventless — a future

package/packages/bundled-features/src/tenant-lifecycle/testing.ts

@@ -1,12 +1,12 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { append, loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
 import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
-import { updateRows } from "@cosmicdrift/kumiko-testing/helpers";
+import { updateRowViaEventStore } from "@cosmicdrift/kumiko-testing/helpers";
 import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";
-import { tenantTable } from "../tenant/index.ts";
+import { tenantEntity, tenantTable } from "../tenant/index.ts";
 import { TENANT_AGGREGATE_TYPE, TENANT_DESTRUCTION_STARTED_EVENT_QN } from "./constants.ts";
 import { runTenantDestructionSweep } from "./run-tenant-destroy.ts";
 
@@ -14,17 +14,18 @@ import { runTenantDestructionSweep } from "./run-tenant-destroy.ts";
 // features wired) by seeding the same "destroying" state it would produce.
 export async function seedDestroyingTenant(db: DbConnection, tenantId: TenantId): Promise<void> {
   const now = getTemporal().Now.instant();
-  await updateRows(
+  await updateRowViaEventStore(
     db,
-    tenantTable,
-    { status: "destroying", destroyStartedAt: now },
+    { table: tenantTable, entity: tenantEntity, entityName: "tenant" },
     { id: tenantId },
+    { status: "destroying", destroyStartedAt: now },
+    { tenantId: SYSTEM_TENANT_ID },
   );
   await append(db, {
     aggregateId: tenantId,
     aggregateType: TENANT_AGGREGATE_TYPE,
-    tenantId,
-    expectedVersion: (await loadAggregate(db, tenantId, tenantId)).at(-1)?.version ?? 0,
+    tenantId: SYSTEM_TENANT_ID,
+    expectedVersion: (await loadAggregate(db, tenantId, SYSTEM_TENANT_ID)).at(-1)?.version ?? 0,
     type: TENANT_DESTRUCTION_STARTED_EVENT_QN,
     payload: { startedAt: now.toString() },
     metadata: { userId: "system", requestId: "test:destruction-started" },

package/packages/bundled-features/src/tier-engine/entity.ts

@@ -21,7 +21,7 @@ import { type TierAssignmentSource, TierAssignmentSources } from "./web/constant
 // **Intentionally omitted from the entity**
 //   - tenantId: added automatically as a base column.
 //   - validFrom/validTo: redundant for event sourcing (events carry timestamps
-//     natively; time travel uses `ctx.loadAggregate({ asOf })`).
+//     natively; time travel uses `ctx.events.load({ asOf })`).
 //   - addOns: represented by a separate `tier-add-on` entity (1:n relation),
 //     allowing event-sourced Add/Remove events with clear audit granularity
 //     instead of replacing a JSON array.

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -95,7 +95,7 @@ const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEn
 const log = createFallbackLogger("tier-engine");
 
 // Event-store executor for direct writes from the auto-default-tier hook.
-// Like tenant/seeding.ts, the hook receives AppContext (not ctx.write), but it
+// Like tenant/seeding.ts, the hook receives AppContext (not ctx.dispatch.write), but it
 // must write atomically with tenant creation in the same transaction. Call the
 // executor directly rather than going through the dispatcher.
 const tierAssignmentExecutor = createEventStoreExecutor(tierAssignmentTable, tierAssignmentEntity, {
@@ -406,7 +406,7 @@ export function createTierEngineFeature<
 
       // Auto-default-tier-on-tenant-signup: the hook fires inTransaction (atomic
       // with the tenant-create rollback) and writes the tier-assignment via the
-      // direct executor (not ctx.write — the hook has an AppContext). Same
+      // direct executor (not ctx.dispatch.write — the hook has an AppContext). Same
       // pattern as seedTenant in tenant/seeding.ts.
       //
       // **Idempotency:** deterministic aggregate id derived from tenantId. A
@@ -468,7 +468,12 @@ export function createTierEngineFeature<
               tenantId: newTenantId,
               roles: ["SystemAdmin"],
             };
-            const tdb = createTenantDb({ db: rawDb, tenantId: newTenantId, mode: "system" });
+            const tdb = createTenantDb({
+              db: rawDb,
+              tenantId: newTenantId,
+              mode: "system",
+              reason: "tier assignment for a newly created tenant is written in that tenant",
+            });
 
             await tierAssignmentExecutor.create(
               { id: aggregateId, tier: defaultTier, source: TierAssignmentSources.default },

package/packages/bundled-features/src/tier-engine/handlers/active-tier.query.ts

@@ -3,11 +3,11 @@ import * as z from "zod";
 
 // get-active-tier — returns the current tier assignment for the calling tenant.
 //
-// Wraps `ctx.queryProjection` for the most common engine query: which tier is
+// Wraps `ctx.dispatch.queryProjection` for the most common engine query: which tier is
 // currently active. Returns null when no tier is assigned; the caller (composeApp)
 // maps null to the default tier.
 //
-// **Tenant scope:** `ctx.queryProjection` automatically filters by tenantId.
+// **Tenant scope:** `ctx.dispatch.queryProjection` automatically filters by tenantId.
 // By convention, each platform tenant has exactly one tier-assignment row.
 export const getActiveTierQuery: QueryHandlerDef = {
   name: "get-active-tier",
@@ -16,7 +16,7 @@ export const getActiveTierQuery: QueryHandlerDef = {
   schema: z.object({}),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   handler: async (_query, ctx) => {
-    const rows = await ctx.queryProjection<Record<string, unknown>>(
+    const rows = await ctx.dispatch.queryProjection<Record<string, unknown>>(
       "tier-engine:projection:tier-assignment-entity",
     );
     return rows[0] ?? null;

package/packages/bundled-features/src/tier-engine/handlers/get-tenant-tier.query.ts

@@ -24,7 +24,13 @@ export const getTenantTierQuery = defineQueryHandler({
   },
   handler: async (query, ctx) => {
     const tenantId = query.payload.tenantId as TenantId; // @cast-boundary engine-bridge
-    const tdb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+    const tdb = createTenantDb({
+      db: ctx.db.unsafeRaw(),
+      tenantId,
+      mode: "system",
+      reason:
+        "tier lookup reads the assignment of the queried tenant, the escape hatch is declared on the handler",
+    });
     const row = await fetchOne<TierAssignmentRow>(tdb, tierAssignmentTable, { tenantId });
     return row ?? null;
   },

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

@@ -14,7 +14,7 @@ import { type TierAssignmentSource, TierAssignmentSources } from "../web/constan
 // billing. This is cross-tenant, so it is restricted to SystemAdmin (not
 // TenantAdmin, which would allow free self-upgrades).
 //
-// Cross-tenant mechanics: ctx.forTenant(tenantId) yields a tenant-mode db bound to the target plus
+// Cross-tenant mechanics: ctx.tenants.writeTarget(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` defaults to manual and marks the grant so the billing sync skips it; passing
@@ -25,7 +25,7 @@ import { type TierAssignmentSource, TierAssignmentSources } from "../web/constan
 // `tier-assignment:postSave` entity hook, and a per-handler postSave would not
 // fire either because this handler returns no lifecycle result (kind "save").
 // Without an explicit update the feature gate would stay on the old tier, so
-// `opts.onAssigned(tenantId, tier)` runs after commit (ctx.scheduleAfterCommit).
+// `opts.onAssigned(tenantId, tier)` runs after commit (ctx.lifecycle.afterCommit).
 // feature.ts uses it to update its cache and notify the other processes; in
 // storage-only mode without a tierMap it is a no-op.
 
@@ -70,7 +70,7 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
       // Without a commit sink (unit harness) there is no transaction to wait for.
       const afterCommit = (tenantId: TenantId, tier: string): void => {
         const notify = async (): Promise<void> => opts.onAssigned?.(tenantId, tier);
-        if (ctx.scheduleAfterCommit) ctx.scheduleAfterCommit(notify);
+        if (ctx.lifecycle.afterCommit) ctx.lifecycle.afterCommit(notify);
         else opts.onAssigned?.(tenantId, tier);
       };
       const tenantId = event.payload.tenantId as TenantId; // @cast-boundary engine-bridge