@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.388.0",
+  "version": "0.390.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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.388.0",
+  "version": "0.390.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -18,7 +18,9 @@
     "runtime": "runtime",
     "bunOnlyExports": [
       "./template-resolver/testing",
-      "./tenant-lifecycle/testing"
+      "./tenant-lifecycle/testing",
+      "./tenant/testing",
+      "./user/testing"
     ]
   },
   "exports": {
@@ -101,12 +103,14 @@
     "./user-profile/web": "./src/user-profile/web/index.ts",
     "./auth-email-password": "./src/auth-email-password/index.ts",
     "./auth-email-password/constants": "./src/auth-email-password/web/constants.ts",
+    "./auth-email-password/return-path": "./src/auth-email-password/web/return-path.ts",
     "./auth-email-password/email-templates": "./src/auth-email-password/email-templates.ts",
     "./auth-email-password/seeding": "./src/auth-email-password/seeding.ts",
     "./auth-email-password/testing": "./src/auth-email-password/testing.ts",
     "./auth-email-password/web": "./src/auth-email-password/web/index.ts",
     "./shared/single-use-token-store": "./src/shared/single-use-token-store.ts",
     "./shared/signed-token": "./src/shared/signed-token.ts",
+    "./shared/stream-tenant-backfill": "./src/shared/stream-tenant-backfill.ts",
     "./shared/row-bound-grant": "./src/shared/row-bound-grant.ts",
     "./shared/mail-template-body": "./src/shared/mail-template-body.ts",
     "./delivery": "./src/delivery/index.ts",
@@ -160,19 +164,19 @@
     "@cosmicdrift/kumiko-types": "workspace:*",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
-    "@tiptap/core": "3.31.3",
-    "@tiptap/extension-link": "3.31.3",
-    "@tiptap/extension-list": "3.31.3",
-    "@tiptap/extension-table": "3.31.3",
-    "@tiptap/html": "3.31.3",
-    "@tiptap/extensions": "3.31.3",
-    "@tiptap/pm": "3.31.3",
-    "@tiptap/react": "3.31.3",
-    "@tiptap/starter-kit": "3.31.3",
+    "@tiptap/core": "^3.31.3",
+    "@tiptap/extension-link": "^3.31.3",
+    "@tiptap/extension-list": "^3.31.3",
+    "@tiptap/extension-table": "^3.31.3",
+    "@tiptap/html": "^3.31.3",
+    "@tiptap/extensions": "^3.31.3",
+    "@tiptap/pm": "^3.31.3",
+    "@tiptap/react": "^3.31.3",
+    "@tiptap/starter-kit": "^3.31.3",
     "@types/mailparser": "^3.4.6",
     "@types/qrcode": "^1.5.5",
     "clsx": "^2.1.1",
-    "happy-dom": "^20.11.2",
+    "happy-dom": "^21.0.4",
     "hono": "^4.13.1",
     "imapflow": "^1.7.8",
     "ioredis": "^5.10.1",
@@ -180,7 +184,7 @@
     "lucide-react": "^1.14.0",
     "mailparser": "^3.9.32",
     "marked": "^18.0.3",
-    "nodemailer": "^10.0.13",
+    "nodemailer": "^10.2.1",
     "pdf-lib": "^1.17.1",
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
@@ -516,6 +520,10 @@
         "types": "./dist/auth-email-password/web/constants.d.ts",
         "default": "./dist/auth-email-password/web/constants.js"
       },
+      "./auth-email-password/return-path": {
+        "types": "./dist/auth-email-password/web/return-path.d.ts",
+        "default": "./dist/auth-email-password/web/return-path.js"
+      },
       "./auth-email-password/seeding": {
         "types": "./dist/auth-email-password/seeding.d.ts",
         "default": "./dist/auth-email-password/seeding.js"
@@ -536,6 +544,10 @@
         "types": "./dist/shared/signed-token.d.ts",
         "default": "./dist/shared/signed-token.js"
       },
+      "./shared/stream-tenant-backfill": {
+        "types": "./dist/shared/stream-tenant-backfill.d.ts",
+        "default": "./dist/shared/stream-tenant-backfill.js"
+      },
       "./shared/row-bound-grant": {
         "types": "./dist/shared/row-bound-grant.d.ts",
         "default": "./dist/shared/row-bound-grant.js"

package/packages/bundled-features/src/agent-tools/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Local agent tool errors carry a code",
+    "detail": "dispatchToolCall returns code invalid_tool_call for validation errors and unknown_tool for an unknown tool name, instead of a result without code. TOOL_CALL_ERROR_CODES names both."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/agent-tools/index.ts

@@ -9,7 +9,7 @@ export { buildAgentManifest } from "./agent-manifest.ts";
 export { AGENT_TOOLS_FEATURE_NAME, createAgentToolsFeature } from "./feature.ts";
 export { buildToolCatalog, OPEN_FORM_TOOL_NAME, toolNameForQn } from "./tool-catalog.ts";
 export type { ToolCallRequest, ToolCallResult, ToolDispatcher } from "./tool-dispatch.ts";
-export { dispatchToolCall } from "./tool-dispatch.ts";
+export { dispatchToolCall, TOOL_CALL_ERROR_CODES } from "./tool-dispatch.ts";
 export type {
   AgentManifest,
   AgentManifestEntity,

package/packages/bundled-features/src/agent-tools/tool-dispatch.ts

@@ -58,6 +58,21 @@ type ToolFailure = {
 
 type FailureClassifier = (failure: ToolFailure, cause: unknown) => ToolCallResult;
 
+export const TOOL_CALL_ERROR_CODES = {
+  invalidToolCall: "invalid_tool_call",
+  unknownTool: "unknown_tool",
+} as const;
+
+type ToolCallFailure = Extract<ToolCallResult, { readonly ok: false }>;
+
+function invalidToolCall(error: string): ToolCallFailure {
+  return { ok: false, error, code: TOOL_CALL_ERROR_CODES.invalidToolCall };
+}
+
+function unknownTool(error: string): ToolCallFailure {
+  return { ok: false, error, code: TOOL_CALL_ERROR_CODES.unknownTool };
+}
+
 const HTTP_TOO_MANY_REQUESTS = 429;
 const HTTP_SERVER_ERROR = 500;
 const UNEXPECTED_FAILURE_MESSAGE = "Tool failed unexpectedly";
@@ -108,7 +123,7 @@ type FilterOp = (typeof FILTER_OPS)[number];
 
 type PayloadResult =
   | { readonly ok: true; readonly value: Readonly<Record<string, unknown>> }
-  | { readonly ok: false; readonly error: string };
+  | ToolCallFailure;
 
 function isFilterOp(value: unknown): value is FilterOp {
   return isOneOf(FILTER_OPS, value);
@@ -120,7 +135,7 @@ function buildSearchPayload(
 ): PayloadResult {
   const query = toolInput["query"];
   if (typeof query !== "string" || query.length === 0) {
-    return { ok: false, error: `Tool "${toolName}" requires a non-empty string "query" argument` };
+    return invalidToolCall(`Tool "${toolName}" requires a non-empty string "query" argument`);
   }
   return { ok: true, value: { search: query, limit: SEARCH_RESULT_LIMIT } };
 }
@@ -132,7 +147,7 @@ function buildFindByPayload(
 ): PayloadResult {
   const value = toolInput[fieldName];
   if (value === undefined) {
-    return { ok: false, error: `Tool "${toolName}" requires a "${fieldName}" argument` };
+    return invalidToolCall(`Tool "${toolName}" requires a "${fieldName}" argument`);
   }
   return {
     ok: true,
@@ -156,10 +171,10 @@ function buildEntityListPayload(
   const search = input["search"];
   if (search !== undefined) {
     if (typeof search !== "string") {
-      return { ok: false, error: `"search" must be a string` };
+      return invalidToolCall(`"search" must be a string`);
     }
     if (list.searchableFields.length === 0) {
-      return { ok: false, error: "This entity has no searchable fields" };
+      return invalidToolCall("This entity has no searchable fields");
     }
     payload["search"] = search;
   }
@@ -167,18 +182,18 @@ function buildEntityListPayload(
   const filters = input["filters"];
   if (filters !== undefined) {
     if (!Array.isArray(filters)) {
-      return { ok: false, error: `"filters" must be an array` };
+      return invalidToolCall(`"filters" must be an array`);
     }
     const validated: Array<{ field: string; op: FilterOp; value: unknown }> = [];
     for (const entry of filters) {
       if (!isRecord(entry) || typeof entry["field"] !== "string" || !("value" in entry)) {
-        return { ok: false, error: `Each filter must be { field, op, value }` };
+        return invalidToolCall(`Each filter must be { field, op, value }`);
       }
       if (!list.filterableFields.includes(entry["field"])) {
-        return { ok: false, error: `Field "${entry["field"]}" is not filterable on this entity` };
+        return invalidToolCall(`Field "${entry["field"]}" is not filterable on this entity`);
       }
       if (!isFilterOp(entry["op"])) {
-        return { ok: false, error: `Unsupported filter operator "${String(entry["op"])}"` };
+        return invalidToolCall(`Unsupported filter operator "${String(entry["op"])}"`);
       }
       validated.push({ field: entry["field"], op: entry["op"], value: entry["value"] });
     }
@@ -250,7 +265,7 @@ async function dispatchServerQuery(
   if (descriptor.detail) {
     const id = input["id"];
     if (typeof id !== "string" || id.length === 0) {
-      return { ok: false, error: `This tool requires a non-empty string "id" argument` };
+      return invalidToolCall(`This tool requires a non-empty string "id" argument`);
     }
     const data = await dispatcher.query(descriptor.qn, { id }, user);
     return { ok: true, data };
@@ -285,16 +300,16 @@ async function dispatchServerWrite(
   if (descriptor.injectsVersion) {
     const id = input["id"];
     if (typeof id !== "string" || id.length === 0) {
-      return { ok: false, error: `This tool requires a non-empty string "id" argument` };
+      return invalidToolCall(`This tool requires a non-empty string "id" argument`);
     }
     if (!descriptor.detailQn) {
-      return { ok: false, error: "Tool is misconfigured: no detail handler to read version from" };
+      return invalidToolCall("Tool is misconfigured: no detail handler to read version from");
     }
     const current = await dispatcher.query(descriptor.detailQn, { id }, user);
     const version =
       isRecord(current) && typeof current["version"] === "number" ? current["version"] : undefined;
     if (version === undefined) {
-      return { ok: false, error: `Could not read the current "version" for id "${id}"` };
+      return invalidToolCall(`Could not read the current "version" for id "${id}"`);
     }
     payload = { ...input, version };
   }
@@ -336,10 +351,10 @@ function dispatchClientNavigate(
   const entity = input["entity"];
   if (typeof entity === "string") {
     const screenId = descriptor.entityScreens.get(entity);
-    if (!screenId) return { ok: false, error: `Unknown entity "${entity}" for navigation` };
+    if (!screenId) return invalidToolCall(`Unknown entity "${entity}" for navigation`);
     const id = input["id"];
     if (typeof id !== "string" || id.length === 0) {
-      return { ok: false, error: `Navigating to "${entity}" requires a non-empty string "id"` };
+      return invalidToolCall(`Navigating to "${entity}" requires a non-empty string "id"`);
     }
     return { ok: true, data: { kind: "navigate", screenId, params: { id } } };
   }
@@ -347,19 +362,19 @@ function dispatchClientNavigate(
   const screenId = input["screenId"];
   if (typeof screenId === "string") {
     if (!descriptor.screenIds.has(screenId)) {
-      return { ok: false, error: `Unknown screen "${screenId}"` };
+      return invalidToolCall(`Unknown screen "${screenId}"`);
     }
     const params = input["params"];
     if (params !== undefined) {
       if (!isRecord(params) || Object.values(params).some((value) => typeof value !== "string")) {
-        return { ok: false, error: `"params" must be an object of string values` };
+        return invalidToolCall(`"params" must be an object of string values`);
       }
       return { ok: true, data: { kind: "navigate", screenId, params } };
     }
     return { ok: true, data: { kind: "navigate", screenId, params: {} } };
   }
 
-  return { ok: false, error: `navigate requires either { entity, id } or { screenId }` };
+  return invalidToolCall(`navigate requires either { entity, id } or { screenId }`);
 }
 
 function dispatchClientOpenForm(
@@ -368,10 +383,10 @@ function dispatchClientOpenForm(
 ): ToolCallResult {
   const handlerQn = input["handlerQn"];
   if (typeof handlerQn !== "string") {
-    return { ok: false, error: `open_form requires a string "handlerQn" argument` };
+    return invalidToolCall(`open_form requires a string "handlerQn" argument`);
   }
   const screenId = descriptor.formScreens.get(handlerQn);
-  if (!screenId) return { ok: false, error: `No form screen mounted for handler "${handlerQn}"` };
+  if (!screenId) return invalidToolCall(`No form screen mounted for handler "${handlerQn}"`);
   return {
     ok: true,
     data: { kind: "open_form", screenId, handlerQn, prefill: input["prefill"] ?? {} },
@@ -385,14 +400,14 @@ function isStringArray(value: unknown): value is readonly string[] {
 function dispatchClientAskUser(input: Readonly<Record<string, unknown>>): ToolCallResult {
   const question = input["question"];
   if (typeof question !== "string" || question.length === 0) {
-    return { ok: false, error: `ask_user requires a non-empty string "question" argument` };
+    return invalidToolCall(`ask_user requires a non-empty string "question" argument`);
   }
   const options = input["options"];
   if (options === undefined) {
     return { ok: true, data: { kind: "ask_user", question } };
   }
   if (!isStringArray(options)) {
-    return { ok: false, error: `ask_user "options" argument must be an array of strings` };
+    return invalidToolCall(`ask_user "options" argument must be an array of strings`);
   }
   return { ok: true, data: { kind: "ask_user", question, options } };
 }
@@ -413,9 +428,10 @@ function dispatchClient(
 
 /** Executes one LLM-issued tool call. Never throws: every failure comes back as `{ ok: false }`
  *  so the agent loop can feed the error back to the model instead of crashing.
- *  Handler and dispatcher failures carry a `code` (429 adds `retryable`); client errors (< 500)
- *  keep their message, server failures (>= 500, unknown throws) are logged and returned as a
- *  generic message. Local validation errors (unknown tool, bad arguments) have no `code`.
+ *  Every failure carries a `code`: the handler's own code for handler and dispatcher failures
+ *  (429 adds `retryable`), `invalid_tool_call` for bad arguments and `unknown_tool` for a tool
+ *  that is not in the table. Client errors (< 500) keep their message, server failures (>= 500,
+ *  unknown throws) are logged and returned as a generic message.
  *  `request.user` must be the caller's real identity: server-kind tools run through the same
  *  permission-checked pipeline as an HTTP request. */
 export async function dispatchToolCall(request: ToolCallRequest): Promise<ToolCallResult> {
@@ -423,7 +439,7 @@ export async function dispatchToolCall(request: ToolCallRequest): Promise<ToolCa
   const classifyFailure = createFailureClassifier(toolName, request.log ?? fallbackLog);
   const descriptor = dispatchTable.get(toolName);
   if (!descriptor) {
-    return { ok: false, error: `Unknown tool "${toolName}"` };
+    return unknownTool(`Unknown tool "${toolName}"`);
   }
 
   try {

package/packages/bundled-features/src/audit/feature.ts

@@ -49,6 +49,7 @@ export function createAuditFeature(): FeatureDefinition {
   return defineFeature(
     "audit",
     (r) => {
+      r.adoptsBundledLists();
       r.describe(
         "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`, and reads the events of every tenant (system tenant excluded) through `audit:query:list-all-tenants` and the `audit-log-all-tenants` screen. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
       );
@@ -92,7 +93,7 @@ export function createAuditFeature(): FeatureDefinition {
           await runEscapeHatchRetention({
             db: ctx.db.unsafeRaw(),
             registry: ctx.registry,
-            configResolver: ctx.configResolver,
+            configResolver: ctx.services.configResolver,
             userId: SYSTEM_USER_ID,
           });
         },

package/packages/bundled-features/src/auth-email-password/auth-user-row.ts

@@ -1,4 +1,4 @@
-// Narrow cross-feature query results (ctx.queryAs → Promise<unknown>) into
+// Narrow cross-feature query results (ctx.dispatch.queryAs → Promise<unknown>) into
 // the shape the auth handlers actually read. Replaces a bare
 // `as AuthUserRow | null` at the system boundary — the coding standard
 // requires a TypeGuard in place of unchecked casts from unknown.

package/packages/bundled-features/src/auth-email-password/bootstrap.ts

@@ -19,6 +19,7 @@ import {
   type TenantId,
   type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { runInSystemRowLevelSecurityScope } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
 import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
@@ -293,7 +294,18 @@ function isMailingOutcome(outcome: BootstrapInviteOutcome): boolean {
   return outcome === "invited" || outcome === "resent";
 }
 
-export async function bootstrapTenants(
+// A one-shot operator process, not a tenant request: it looks up users, memberships and invitations across tenants.
+export function bootstrapTenants(
+  deps: BootstrapDeps,
+  plan: BootstrapPlan,
+): Promise<BootstrapReport> {
+  return runInSystemRowLevelSecurityScope(
+    "boot tenant bootstrap creates tenants and memberships before any tenant exists",
+    () => bootstrapTenantsInScope(deps, plan),
+  );
+}
+
+async function bootstrapTenantsInScope(
   deps: BootstrapDeps,
   plan: BootstrapPlan,
 ): Promise<BootstrapReport> {

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "isSafeReturnPath has its own light subpath",
+    "detail": "Importing @cosmicdrift/kumiko-bundled-features/auth-email-password/return-path gives isSafeReturnPath, readReturnToFromSearch, RETURN_TO_QUERY_PARAM and MAX_RETURN_PATH_LENGTH without loading the web barrel, for example in Astro pages that run without the Kumiko runtime."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Optional returnTo for password reset and signup",
+    "detail": "Password reset and signup accept an optional returnTo path. A safe value (same-origin path, no dot segments) is appended to the mailed link as a query parameter, the reset and signup-complete screens follow it, and the login screen forwards its next to the forgot-password and signup links. Invalid values are dropped silently and never block the mail. isSafeReturnPath and readReturnToFromSearch are exported from the web barrel. isSafeNextPath now uses the same check, so a next with a dot segment such as \"/a/../b\" is no longer followed."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "CurrentUser carries tenantId, logout clears remembered list state",
+    "detail": "The session CurrentUser has an optional tenantId used to scope remembered list state; logout removes all kumiko.list.* storage entries."
+  },
   {
     "version": "0.385.0",
     "type": "improvement",

package/packages/bundled-features/src/auth-email-password/feature.ts

@@ -105,7 +105,7 @@ export type EmailVerificationOptions = {
 // Brute-force protection on the login handler. Omit for the defaults
 // (5 failures → 15-minute lock). Set the dial knobs to override.
 //
-// Storage: Redis (keyed by userId). Without ctx.redis the handler skips
+// Storage: Redis (keyed by userId). Without ctx.services.redis the handler skips
 // lockout entirely — login still works, but brute-force protection falls
 // back to the IP-rate-limiter. Counter is monotonic: only a successful
 // login resets it, so after a lockout expires the next wrong password
@@ -149,7 +149,7 @@ export type AuthEmailPasswordOptions = {
 };
 
 // Auth feature — email+password login. Depends on the user feature for
-// identity lookups (via ctx.queryAs) and on the tenant feature for
+// identity lookups (via ctx.dispatch.queryAs) and on the tenant feature for
 // membership resolution. No direct imports of foreign tables.
 export function createAuthEmailPasswordFeature(
   opts: AuthEmailPasswordOptions = {},

package/packages/bundled-features/src/auth-email-password/handlers/change-password.write.ts

@@ -10,7 +10,7 @@ import { invalidCredentials } from "../errors.ts";
 import { passwordSchema } from "../password-policy.ts";
 
 // Change-password — authenticated. The user supplies their current password
-// (re-auth) and the new one. The new hash is written via ctx.writeAs(system)
+// (re-auth) and the new one. The new hash is written via ctx.dispatch.writeAs(system)
 // against the user feature's update handler; field-access on passwordHash
 // (privileged-only) lets the system identity through.
 export const changePasswordWrite = defineWriteHandler({
@@ -28,8 +28,8 @@ export const changePasswordWrite = defineWriteHandler({
   escapeHatch: {
     grants: ["systemIdentity"],
     reason:
-      "Reads the caller's own passwordHash (privileged-only field) via ctx.queryAs(SYSTEM, ...) " +
-      "and writes the new hash via ctx.writeAs(SYSTEM, user:update) — the caller's own " +
+      "Reads the caller's own passwordHash (privileged-only field) via ctx.dispatch.queryAs(SYSTEM, ...) " +
+      "and writes the new hash via ctx.dispatch.writeAs(SYSTEM, user:update) — the caller's own " +
       "identity can't reach either, field-access on passwordHash is privileged-only.",
   },
   // Payload carries the old and new password.
@@ -40,7 +40,7 @@ export const changePasswordWrite = defineWriteHandler({
     const systemUser = createSystemUser(event.user.tenantId);
 
     // Load self with passwordHash — only visible to the privileged caller.
-    const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+    const me = (await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
       id: event.user.id,
     })) as { id: number; passwordHash: string | null; version: number } | null; // @cast-boundary db-runner
 
@@ -56,14 +56,14 @@ export const changePasswordWrite = defineWriteHandler({
     const newHash = await hashPassword(event.payload.newPassword);
 
     // The user aggregate is systemStream: its event stream lives on
-    // SYSTEM_TENANT_ID deterministically. Previously scattered streams need the
-    // one-time backfillUserStreamTenants migration.
+    // SYSTEM_TENANT_ID deterministically. Previously scattered streams are moved by the
+    // boot-time stream-tenant backfill (runStreamTenantBackfillOnBoot).
     const writer = createSystemUser(SYSTEM_TENANT_ID);
 
     // Apply via user feature's update handler — writeAs(system) satisfies
     // the privileged-only write rule on passwordHash. Pass the current version
     // through so optimistic locking still applies end-to-end.
-    const writeRes = await ctx.writeAs(writer, UserHandlers.update, {
+    const writeRes = await ctx.dispatch.writeAs(writer, UserHandlers.update, {
       id: me.id,
       version: me.version,
       changes: { passwordHash: newHash },

package/packages/bundled-features/src/auth-email-password/handlers/confirm-account-unlock.write.ts

@@ -40,10 +40,10 @@ export function createConfirmAccountUnlockHandler(opts: ConfirmAccountUnlockOpti
           }),
         );
       }
-      if (!ctx.redis) {
+      if (!ctx.services.redis) {
         return writeFailure(
           new InternalError({
-            message: "account-unlock requires ctx.redis to clear lockout state",
+            message: "account-unlock requires ctx.services.redis to clear lockout state",
           }),
         );
       }
@@ -54,7 +54,7 @@ export function createConfirmAccountUnlockHandler(opts: ConfirmAccountUnlockOpti
       const verify = verifyUnlockToken(event.payload.token, opts.hmacSecret);
       if (!verify.ok) return invalidUnlockToken();
 
-      await clearLockoutState(ctx.redis, verify.userId);
+      await clearLockoutState(ctx.services.redis, verify.userId);
       return { isSuccess: true, data: { kind: "account-unlocked" as const } };
     },
   });

package/packages/bundled-features/src/auth-email-password/handlers/confirm-token-flow.ts

@@ -42,7 +42,7 @@ export type ConfirmTokenFlowSpec<TSuccessData> = {
   // other token flows — "reset" vs "verify" keeps cross-flow replay
   // impossible at both layers (HMAC-purpose AND burn-purpose).
   readonly purpose: string;
-  // Used verbatim in the 5xx body when ctx.redis is missing — the feature
+  // Used verbatim in the 5xx body when ctx.services.redis is missing — the feature
   // is misconfigured, not the caller's fault.
   readonly redisRequiredMessage: string;
   // Standard failure returned for every "token can't be consumed" path
@@ -74,10 +74,10 @@ export async function runConfirmTokenFlow<TSuccessData>(
     reason:
       "writes the confirming user's row via UserHandlers.update on the caller's handler context, using a SYSTEM_TENANT-scoped identity; the calling handler declares its own escapeHatch",
   });
-  if (!ctx.redis) {
+  if (!ctx.services.redis) {
     return writeFailure(new InternalError({ message: spec.redisRequiredMessage }));
   }
-  const redis: Redis = ctx.redis;
+  const redis: Redis = ctx.services.redis;
 
   const burn = await burnToken(redis, spec.purpose, userId, expiresAtMs);
   if (burn === "already-used") return spec.invalidToken();
@@ -99,7 +99,7 @@ export async function runConfirmTokenFlow<TSuccessData>(
     }
 
     const changes = await spec.buildChanges(me);
-    const writeRes = await ctx.writeAs(systemUser, UserHandlers.update, {
+    const writeRes = await ctx.dispatch.writeAs(systemUser, UserHandlers.update, {
       id: me.id,
       version: me.version,
       changes,
@@ -141,7 +141,7 @@ async function loadValidatedUser(
       "reads the confirming user's row via UserQueries.findForAuth on the caller's handler context, using a SYSTEM_TENANT-scoped identity; the calling handler declares its own escapeHatch",
   });
   const me = parseAuthUserRow(
-    await ctx.queryAs(systemUser, UserQueries.findForAuth, { id: userId }),
+    await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, { id: userId }),
   );
   if (!me || me.isDeleted || me.version === undefined || me.version < 1) return null;
   return { ...me, version: me.version };

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -133,16 +133,16 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
     agent: { expose: false },
     // kumiko-lint-ignore complexity-budget reuses login.write.ts's gate chain (lockout/password/email/status/membership/mfa) plus invite-specific branches (email match, already-member check, invitation update, unburn-on-failure) — splitting would scatter gate order across functions without reducing risk
     handler: async (event, ctx) => {
-      if (!ctx.redis) {
+      if (!ctx.services.redis) {
         return writeFailure(
-          new InternalError({ message: "invite-accept-with-login requires ctx.redis" }),
+          new InternalError({ message: "invite-accept-with-login requires ctx.services.redis" }),
         );
       }
 
-      const invitationId = await getInvitationIdForToken(ctx.redis, event.payload.token);
+      const invitationId = await getInvitationIdForToken(ctx.services.redis, event.payload.token);
       if (!invitationId) return invalidInviteToken();
 
-      const burn = await burnInviteToken(ctx.redis, event.payload.token);
+      const burn = await burnInviteToken(ctx.services.redis, event.payload.token);
       if (burn === "already-used") return invalidInviteToken();
 
       type InvitationRow = {
@@ -242,6 +242,8 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
           db: dbConn,
           tenantId: invitationTenantId,
           mode: "system",
+          reason:
+            "invitation tenant differs from the caller's tenant, the accept step updates the invitation row there",
         });
         const updateResult = await invitationExecutor.update(
           {
@@ -254,7 +256,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
         );
         if (!updateResult.isSuccess) return updateResult;
 
-        await deleteInviteToken(ctx.redis, { invitationId, token: event.payload.token });
+        await deleteInviteToken(ctx.services.redis, { invitationId, token: event.payload.token });
 
         // buildSessionRoles calls stripForbiddenMembershipRoles internally —
         // a reserved role on an existing membership must never reach the session.
@@ -296,8 +298,8 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
           },
         };
       } finally {
-        if (!committed && ctx.redis) {
-          await unburnInviteToken(ctx.redis, event.payload.token);
+        if (!committed && ctx.services.redis) {
+          await unburnInviteToken(ctx.services.redis, event.payload.token);
         }
       }
     },

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept.write.ts

@@ -94,16 +94,18 @@ export function createInviteAcceptHandler() {
     },
     // kumiko-lint-ignore complexity-budget invite branches (auth/anon/burn) stay in one handler
     handler: async (event, ctx) => {
-      if (!ctx.redis) {
+      if (!ctx.services.redis) {
         return writeFailure(
-          new InternalError({ message: "invite-accept requires ctx.redis for token consumption" }),
+          new InternalError({
+            message: "invite-accept requires ctx.services.redis for token consumption",
+          }),
         );
       }
 
-      const invitationId = await getInvitationIdForToken(ctx.redis, event.payload.token);
+      const invitationId = await getInvitationIdForToken(ctx.services.redis, event.payload.token);
       if (!invitationId) return invalidInviteToken();
 
-      const burn = await burnInviteToken(ctx.redis, event.payload.token);
+      const burn = await burnInviteToken(ctx.services.redis, event.payload.token);
       if (burn === "already-used") return invalidInviteToken();
 
       type InvitationRow = {
@@ -177,6 +179,8 @@ export function createInviteAcceptHandler() {
           db: dbConn,
           tenantId: invitationTenantId,
           mode: "system",
+          reason:
+            "invitation tenant differs from the caller's tenant, the accept step updates the invitation row there",
         });
         const updateResult = await invitationExecutor.update(
           {
@@ -189,7 +193,7 @@ export function createInviteAcceptHandler() {
         );
         if (!updateResult.isSuccess) return updateResult;
 
-        await deleteInviteToken(ctx.redis, { invitationId, token: event.payload.token });
+        await deleteInviteToken(ctx.services.redis, { invitationId, token: event.payload.token });
 
         committed = true;
         return {
@@ -202,8 +206,8 @@ export function createInviteAcceptHandler() {
           },
         };
       } finally {
-        if (!committed && ctx.redis) {
-          await unburnInviteToken(ctx.redis, event.payload.token);
+        if (!committed && ctx.services.redis) {
+          await unburnInviteToken(ctx.services.redis, event.payload.token);
         }
       }
     },