@cosmicdrift/kumiko-samples 0.389.0 → 0.390.1

package/packages/bundled-features/src/user-data-rights/handlers/restrict-account.write.ts

@@ -12,7 +12,7 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle.ts";
 
 // POST /api/user/restrict — GDPR Art. 18 account freeze.
 // Flips status=Active → Restricted and revokes all live sessions
-// for the user via cross-feature ctx.writeAs(sessions.revokeAllForUser).
+// for the user via cross-feature ctx.dispatch.writeAs(sessions.revokeAllForUser).
 //
 // Write API behaviour:
 //   - Login is blocked: login.write.ts checks status=Restricted (Atom 3).
@@ -53,7 +53,7 @@ export const restrictAccountWrite = defineWriteHandler({
   },
   escapeHatch: {
     reason:
-      "Revokes all live sessions of the (possibly self-)restricted user via ctx.writeAs(SYSTEM, " +
+      "Revokes all live sessions of the (possibly self-)restricted user via ctx.dispatch.writeAs(SYSTEM, " +
       "sessions:write:user-session:revoke-all-for-user) — that handler's own access gate needs " +
       "privileged roles the acting caller doesn't necessarily have. It also checks the target " +
       "user's membership in the admin's tenant and appends the user lifecycle status change on " +
@@ -112,10 +112,10 @@ export const restrictAccountWrite = defineWriteHandler({
 
     // Cross-feature: all live sessions are revoked; otherwise the user could
     // continue writing with an existing JWT until token expiry.
-    // ctx.writeAs(systemUser, ...) gives the privileged handler the
+    // ctx.dispatch.writeAs(systemUser, ...) gives the privileged handler the
     // System user roles required by its access gate.
     const systemUser = createSystemUser(event.user.tenantId);
-    await ctx.writeAs(systemUser, "sessions:write:user-session:revoke-all-for-user", {
+    await ctx.dispatch.writeAs(systemUser, "sessions:write:user-session:revoke-all-for-user", {
       userId: targetUserId,
     });
 

package/packages/bundled-features/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -17,7 +17,11 @@ import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 import { resolveAppTenantModel } from "../lib/resolve-tenant-model.ts";
 import { makeTenantStorageProviderResolver } from "../lib/storage-provider-resolver.ts";
-import { runForgetCleanup, type SendDeletionExecutedEmailFn } from "../run-forget-cleanup.ts";
+import {
+  FORGET_CLEANUP_HANDLER_NAME,
+  runForgetCleanup,
+  type SendDeletionExecutedEmailFn,
+} from "../run-forget-cleanup.ts";
 
 export type RunForgetCleanupOptions = {
   readonly sendDeletionExecutedEmail?: SendDeletionExecutedEmailFn;
@@ -56,7 +60,7 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
       const forgetDb = runner as DbConnection; // @cast-boundary db-runner — DbRunner narrows to DbConnection, config reads tolerate the outer tx
       const tenantModel = await resolveAppTenantModel({
         registry: ctx.registry,
-        configResolver: ctx.configResolver,
+        configResolver: ctx.services.configResolver,
         db: forgetDb,
         userId: ctx.user.id,
       });
@@ -65,14 +69,16 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
         registry: ctx.registry,
         now: T.Now.instant(),
         tenantModel,
-        ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+        ...(ctx.services.searchAdapter !== undefined && {
+          searchAdapter: ctx.services.searchAdapter,
+        }),
         buildStorageProvider: makeTenantStorageProviderResolver({
           registry: ctx.registry,
-          configResolver: ctx.configResolver,
-          secrets: ctx.secrets,
+          configResolver: ctx.services.configResolver,
+          secrets: ctx.services.secrets,
           db: forgetDb,
           userId: ctx.user.id,
-          handlerName: "user-data-rights:run-forget-cleanup",
+          handlerName: FORGET_CLEANUP_HANDLER_NAME,
         }),
         ...(opts.sendDeletionExecutedEmail && {
           sendDeletionExecutedEmail: opts.sendDeletionExecutedEmail,

package/packages/bundled-features/src/user-data-rights/index.ts

@@ -35,5 +35,7 @@ export {
   TENANT_MODEL_CONFIG_KEY,
   USER_DATA_RIGHTS_FEATURE,
   UserDataRightsHandlers,
+  UserDataRightsJobs,
   UserDataRightsQueries,
+  UserDataRightsScreens,
 } from "./web/constants.ts";

package/packages/bundled-features/src/user-data-rights/lib/mail-transport-resolver.ts

@@ -31,7 +31,7 @@ export function makeTenantMailTransportResolver(
   return async (tenantId) => {
     if (!ctx.configResolver) {
       throw new Error(
-        `${ctx.handlerName}: ctx.configResolver missing — cannot resolve the mail transport for tenant ${tenantId}`,
+        `${ctx.handlerName}: ctx.services.configResolver missing — cannot resolve the mail transport for tenant ${tenantId}`,
       );
     }
     const config = createConfigAccessor(

package/packages/bundled-features/src/user-data-rights/lib/storage-provider-resolver.ts

@@ -30,7 +30,7 @@ export function makeTenantStorageProviderResolver(
   return async (tenantId) => {
     if (!ctx.configResolver) {
       throw new InternalError({
-        message: `[${ctx.handlerName}] ctx.configResolver missing — cannot resolve the file provider for tenant ${tenantId}`,
+        message: `[${ctx.handlerName}] ctx.services.configResolver missing — cannot resolve the file provider for tenant ${tenantId}`,
       });
     }
     const config = createConfigAccessor(

package/packages/bundled-features/src/user-data-rights/lib/update-user-lifecycle.ts

@@ -62,7 +62,12 @@ export async function updateUserLifecycle(
   // (restrict/lift-restriction/grace-period/cancel/forget) that holds no row
   // version to pass as `payload.version`, which update() requires otherwise.
   // Callers needing a guard use `options.expect` instead.
-  const tenantDb = createTenantDb({ db: conn, tenantId: SYSTEM_TENANT_ID, mode: "system" });
+  const tenantDb = createTenantDb({
+    db: conn,
+    tenantId: SYSTEM_TENANT_ID,
+    mode: "system",
+    reason: "User is tenant-agnostic, lifecycle transitions run in the system tenant",
+  });
   const result = await userExecutor.update(
     { id: userId, changes },
     createSystemUser(SYSTEM_TENANT_ID),

package/packages/bundled-features/src/user-data-rights/run-export-jobs.ts

@@ -54,7 +54,7 @@ import { generateDownloadToken } from "./token-helpers.ts";
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
 // Gauge short name (feature.ts registers it via r.metric + resolves ctx.meter
-// into a MetricsHandle — jobs get no bound ctx.metrics, see feature.ts).
+// into a MetricsHandle — jobs get no bound ctx.obs.metrics, see feature.ts).
 // No "_seconds"/"_total" suffix: validateMetricName rejects both on a gauge.
 // Unit lives in the r.metric() `unit: "seconds"` declaration instead.
 export const EXPORT_CLEANUP_BACKLOG_AGE_METRIC = "export_cleanup_backlog_age";
@@ -727,7 +727,13 @@ function reportCleanupLastRun(metrics: MetricsHandle | undefined, now: Instant):
 // `requestedFromTenantId` preserves stream identity and keeps the stream counter consistent.
 // @wrapper-known semantic-alias
 function systemTenantDb(db: DbConnection, tenantId: TenantId) {
-  return createTenantDb({ db, tenantId, mode: "system" });
+  return createTenantDb({
+    db,
+    tenantId,
+    mode: "system",
+    reason:
+      "export jobs run per user across tenants, requestedFromTenantId keeps the stream identity",
+  });
 }
 
 function buildExportStorageKey(job: JobRow): string {

package/packages/bundled-features/src/user-data-rights/run-forget-cleanup.ts

@@ -56,6 +56,7 @@ import {
   type UserDataDeleteStrategy,
   type UserDataStorageProvider,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { runInSystemRowLevelSecurityScope } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import {
   createEscapeHatchReporter,
   UNATTRIBUTED_ACTOR,
@@ -243,13 +244,23 @@ const HOOK_ORDER_DEFAULT = EXT_USER_DATA_ORDER.DEFAULT;
 // console.warn so a crafted reason can't forge extra log lines, and cap the
 // length against a log-flood. The unsanitized reason still lands in the
 // returned `incomplete` entry untouched.
+// Secret-read audit discriminator, not a QN; the value must stay stable for the audit trail.
+export const FORGET_CLEANUP_HANDLER_NAME = "user-data-rights:run-forget-cleanup" as const;
+
 export function sanitizeReasonForLog(reason: string): string {
   return reason.replace(/[\r\n]+/g, " ").slice(0, 500);
 }
 
-export async function runForgetCleanup(
-  args: RunForgetCleanupArgs,
-): Promise<RunForgetCleanupResult> {
+// Cross-tenant by design: the due-user and membership reads on the given runner and raw hook
+// statements must see every tenant, whatever RLS scope the caller (job, operator handler) runs in.
+export function runForgetCleanup(args: RunForgetCleanupArgs): Promise<RunForgetCleanupResult> {
+  return runInSystemRowLevelSecurityScope(
+    "forget cleanup anonymizes users across all tenants",
+    () => forgetDueUsers(args),
+  );
+}
+
+async function forgetDueUsers(args: RunForgetCleanupArgs): Promise<RunForgetCleanupResult> {
   const { db, registry, now, sendDeletionExecutedEmail, buildStorageProvider } = args;
   const kms = args.kms ?? configuredPiiSubjectKms();
   const appTenantModel: TenantUserModel = args.tenantModel ?? "multi-user";

package/packages/bundled-features/src/user-data-rights/run-user-export.ts

@@ -43,6 +43,7 @@ import {
   type UserDataExportHook,
   type UserDataExportSnippet,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { runInSystemRowLevelSecurityScope } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import {
   createEscapeHatchReporter,
   UNATTRIBUTED_ACTOR,
@@ -163,7 +164,16 @@ function buildHookDb(
  * **Operator signal:** if bundle.json exceeds 100 MB in the ZIP, trigger
  * telemetry and evaluate a schema refactor.
  */
-export async function runUserExport(args: RunUserExportArgs): Promise<UserExportBundle> {
+// Cross-tenant by design: the membership read on the given runner and raw hook statements
+// must see every tenant of the user, whatever RLS scope the caller runs in.
+export function runUserExport(args: RunUserExportArgs): Promise<UserExportBundle> {
+  return runInSystemRowLevelSecurityScope(
+    "user data export collects the subject's rows from all tenants",
+    () => exportUserData(args),
+  );
+}
+
+async function exportUserData(args: RunUserExportArgs): Promise<UserExportBundle> {
   const { db, registry, userId, now } = args;
 
   const memberships = await selectMany<{ tenantId: TenantId }>(db, tenantMembershipsTable, {

package/packages/bundled-features/src/user-data-rights/web/constants.ts

@@ -38,6 +38,16 @@ export const UserDataRightsQueries = {
 // `overrides.set(TENANT_MODEL_CONFIG_KEY, "single-user")`.
 export const TENANT_MODEL_CONFIG_KEY = "user-data-rights:config:tenant-model" as const;
 
+export const UserDataRightsJobs = {
+  runExportJobs: "user-data-rights:job:run-export-jobs",
+  runForgetCleanup: "user-data-rights:job:run-forget-cleanup",
+} as const;
+
+export const UserDataRightsScreens = {
+  exportJobList: "user-data-rights:screen:export-job-list",
+  downloadAttemptList: "user-data-rights:screen:download-attempt-list",
+} as const;
+
 export const UserDataRightsHandlers = {
   requestExport: "user-data-rights:write:request-export",
   requestDeletion: "user-data-rights:write:request-deletion",

package/packages/bundled-features/src/user-data-rights/web/index.ts

@@ -7,7 +7,12 @@
 export { type UserDataRightsClientOptions, userDataRightsClient } from "./client-plugin.tsx";
 export type { ConfirmAccountDeletionScreenProps } from "./confirm-deletion-screen.tsx";
 export { ConfirmAccountDeletionScreen } from "./confirm-deletion-screen.tsx";
-export { UserDataRightsHandlers, UserDataRightsQueries } from "./constants.ts";
+export {
+  UserDataRightsHandlers,
+  UserDataRightsJobs,
+  UserDataRightsQueries,
+  UserDataRightsScreens,
+} from "./constants.ts";
 export { defaultTranslations } from "./default-translations.ts";
 export { formatDate } from "./privacy-center-screen.tsx";
 export { makePublicDeletionGate, type PublicDeletionRoutes } from "./public-deletion-gate.tsx";

package/packages/bundled-features/src/user-profile/handlers/change-email.write.ts

@@ -24,7 +24,7 @@ function invalidCredentials() {
 
 // Change-email — authenticated, self-only. The user confirms with their
 // current password (re-authentication as with change-password); the new
-// address is written through the user-update handler via ctx.writeAs(system)
+// address is written through the user-update handler via ctx.dispatch.writeAs(system)
 // because `email` is field-level privileged and would otherwise be silently
 // stripped during self-updates. emailVerified is set to false — the app then
 // triggers the verification flow (request-email-verification is public; the
@@ -45,8 +45,8 @@ export const changeEmailWrite = defineWriteHandler({
   escapeHatch: {
     grants: ["systemIdentity"],
     reason:
-      "Reads the caller's own passwordHash via ctx.queryAs(SYSTEM, user:findForAuth), checks " +
-      "email uniqueness the same way, and writes the new email via ctx.writeAs(SYSTEM, " +
+      "Reads the caller's own passwordHash via ctx.dispatch.queryAs(SYSTEM, user:findForAuth), checks " +
+      "email uniqueness the same way, and writes the new email via ctx.dispatch.writeAs(SYSTEM, " +
       "user:update) — field-access on passwordHash/email is privileged-only.",
   },
   // Payload carries the current password.
@@ -56,7 +56,7 @@ export const changeEmailWrite = defineWriteHandler({
   handler: async (event, ctx) => {
     const systemUser = createSystemUser(event.user.tenantId);
 
-    const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+    const me = (await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
       id: event.user.id,
     })) as { id: string; email: string; passwordHash: string | null; version: number } | null; // @cast-boundary db-runner
 
@@ -79,7 +79,9 @@ export const changeEmailWrite = defineWriteHandler({
       );
     }
 
-    const existing = await ctx.queryAs(systemUser, UserQueries.findForAuth, { email: newEmail });
+    const existing = await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
+      email: newEmail,
+    });
     if (existing !== null) {
       return writeFailure(
         new UnprocessableError(UserErrors.emailAlreadyExists, {
@@ -93,7 +95,7 @@ export const changeEmailWrite = defineWriteHandler({
     // backfillUserStreamTenants.
     const writer = createSystemUser(SYSTEM_TENANT_ID);
 
-    const writeRes = await ctx.writeAs(writer, UserHandlers.update, {
+    const writeRes = await ctx.dispatch.writeAs(writer, UserHandlers.update, {
       id: me.id,
       version: me.version,
       changes: { email: newEmail, emailVerified: false },

package/packages/bundled-features/src/waitlist/handlers/export-purge.write.ts

@@ -21,7 +21,7 @@ const PurgeSchema = z.object({ confirmCount: z.number().int().min(0) }).strict()
 const ExportSchema = z.object({}).strict();
 
 async function appendAudit(ctx: HandlerContext, type: string, count: number): Promise<void> {
-  await ctx.unsafeAppendEvent({
+  await ctx.events.unsafeAppend({
     aggregateId: generateId(),
     aggregateType: WAITLIST_AUDIT_AGGREGATE_TYPE,
     type,

package/packages/bundled-features/src/waitlist/handlers/invite.write.ts

@@ -111,7 +111,7 @@ async function ensureOwnTenant(
 
   const newTenantId = parseTenantId(crypto.randomUUID());
   if (!newTenantId) throw new InternalError({ message: "waitlist:invite: tenant id mint failed" });
-  const created = await ctx.writeAs(createSystemUser(newTenantId), TenantHandlers.create, {
+  const created = await ctx.dispatch.writeAs(createSystemUser(newTenantId), TenantHandlers.create, {
     id: newTenantId,
     key,
     name: entry.company ?? entry.name,
@@ -167,7 +167,7 @@ export function createInviteHandler(invite: WaitlistInviteOptions = DEFAULT_INVI
       // inviteCreate is admin-only (no system role); the system variant with an
       // empty globalRoles list is the only in-process path, and a waitlist
       // invite must never grant a global role.
-      const invited = await ctx.writeAs(
+      const invited = await ctx.dispatch.writeAs(
         createSystemUser(target.tenantId),
         AuthHandlers.systemInviteCreate,
         {

package/packages/bundled-features/src/waitlist/handlers/reject.write.ts

@@ -64,7 +64,7 @@ async function revokeInvitation(
       db,
       { id, version },
       createSystemUser(tenantId),
-      ctx.redis,
+      ctx.services.redis,
     );
     if (cancelled) return cancelled;
   }

package/packages/bundled-features/src/waitlist/handlers/submit.write.ts

@@ -83,7 +83,7 @@ async function hasOpenEntryForEmail(email: string, ctx: HandlerContext): Promise
 // resolver does not extend the lock. Postgres aborts the whole transaction after a failed
 // statement, even one whose JS error is caught here, so the resolver gets a ctx whose
 // systemDb is bound to its own savepoint: a failing statement rolls back only that.
-// Statements through any other ctx handle (ctx.query, ctx.write) stay in the handler transaction.
+// Statements through any other ctx handle (ctx.dispatch.query, ctx.dispatch.write) stay in the handler transaction.
 async function resolveAdminRecipient(
   opts: WaitlistOptions,
   ctx: HandlerContext,
@@ -93,12 +93,17 @@ async function resolveAdminRecipient(
   try {
     return await runInSavepointIfSupported(systemDb.unsafeRaw(SUBMIT_LOCK_REASON), async (sp) => {
       const savepointSystemDb = createSystemDbView(
-        createTenantDb({ db: sp, tenantId, mode: "system" }),
+        createTenantDb({
+          db: sp,
+          tenantId,
+          mode: "system",
+          reason: "waitlist entries are system-tenant rows submitted by an anonymous guest",
+        }),
       );
       return (await opts.notifyRecipient?.({ ...ctx, systemDb: savepointSystemDb })) || null;
     });
   } catch (err) {
-    ctx.log?.warn("[waitlist:submit] admin notice recipient resolution failed", {
+    ctx.obs.log?.warn("[waitlist:submit] admin notice recipient resolution failed", {
       error: err instanceof Error ? err.message : String(err),
     });
     return null;
@@ -116,7 +121,7 @@ async function sendBestEffort(
     }
     await send(ctx.notify);
   } catch (err) {
-    ctx.log?.warn(`[waitlist:submit] ${label} mail failed`, {
+    ctx.obs.log?.warn(`[waitlist:submit] ${label} mail failed`, {
       error: err instanceof Error ? err.message : String(err),
     });
   }

package/packages/bundled-features/src/waitlist/legacy-migrate.ts

@@ -271,7 +271,12 @@ export async function migrateLegacyWaitlist(
       continue;
     }
     await transaction(db, async (tx) => {
-      const tenantDb = createTenantDb({ db: tx, tenantId: SYSTEM_TENANT_ID, mode: "system" });
+      const tenantDb = createTenantDb({
+        db: tx,
+        tenantId: SYSTEM_TENANT_ID,
+        mode: "system",
+        reason: "legacy waitlist import writes system-tenant rows",
+      });
       const outcome = await importWaitlistEntry(tenantDb, entry, { dryRun: options.dryRun });
       if (outcome === "created") created += 1;
       else skipped += 1;

package/packages/bundled-features/src/waitlist/link-on-signup.ts

@@ -69,7 +69,13 @@ export const linkWaitlistOnSignup: MultiStreamApplyFn = async (event, tx) => {
   // skip: another membership came first.
   if (first && first.id !== event.aggregateId) return;
 
-  const db = createTenantDb({ db: tx, tenantId: SYSTEM_TENANT_ID, mode: "system" });
+  const db = createTenantDb({
+    db: tx,
+    tenantId: SYSTEM_TENANT_ID,
+    mode: "system",
+    reason:
+      "linking a signup to its waitlist entry updates system-tenant rows from a membership event",
+  });
   const user = await fetchOne<{ email?: unknown }>(tx, userTable, { id: membership.userId });
   // skip: user row unreadable (erased or not projected yet).
   if (typeof user?.email !== "string") return;

package/packages/bundled-features/src/workflow-runner/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "fix",
+    "title": "Woken workflow runs are due on the next resume tick",
+    "detail": "The event subscriber stamped wakeAt with the app clock, while the resume job selects due rows with the database clock. With an app clock ahead of the database, a woken row was not due yet and waited for a later tick. wakeAt is now set with the database clock, like the due-runs query."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/workflow-runner/db/queries/due-runs.ts

@@ -8,7 +8,7 @@ export type DueRow = { readonly runId: string; readonly stepIndex: number };
 export const DUE_RUNS_BATCH_SIZE = 100;
 
 // Dedup happens solely via resume-run's VersionConflictError-checked claim
-// (ctx.tryAppendEvent on WORKFLOW_RESUMED) — a second dispatch for the same
+// (ctx.events.tryAppend on WORKFLOW_RESUMED) — a second dispatch for the same
 // row loses that race and no-ops. No row locks: in an autocommit statement
 // they would be released right after the SELECT and guard nothing.
 // `now()` stays the DB clock so job-host clock skew cannot mark rows due early.

package/packages/bundled-features/src/workflow-runner/event-subscriber.ts

@@ -23,7 +23,7 @@
 // existing resume-due-runs job picks the row up on its next
 // cron tick — the resume path remains unchanged.
 
-import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany, sql, updateMany } from "@cosmicdrift/kumiko-framework/db";
 import type {
   FeatureRegistrar,
   MultiStreamApplyFn,
@@ -32,7 +32,6 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { evaluateEventMatch } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import type { TriggerEventRef } from "./runner.ts";
 import { workflowRunPendingTable } from "./tables.ts";
 
@@ -92,7 +91,9 @@ const wakeupApply: MultiStreamApplyFn = async (event, tx) => {
           aggregateId: event.aggregateId,
           version: event.version,
         } satisfies TriggerEventRef,
-        wakeAt: getTemporal().Now.instant().toString(),
+        // DB clock, like the due comparison in due-runs.ts: an app-clock stamp ahead of the
+        // database clock would leave the row not-yet-due for the next resume tick.
+        wakeAt: sql`now()`,
       },
       { tenantId: row.tenantId, runId: row.runId, stepIndex: row.stepIndex },
     );

package/packages/bundled-features/src/workflow-runner/event-trigger.ts

@@ -144,7 +144,8 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
               version: event.version,
             },
             ...(idempotencyKey && { idempotencyKey }),
-            handlerCtx: ctx,
+            // The MSP context is still flat; the runner reads the namespaced shape.
+            handlerCtx: { events: { unsafeAppend: ctx.unsafeAppendEvent } },
           });
         } catch (error) {
           // Failures outside the step loop (run-started append) have no step yet, so 0.

package/packages/bundled-features/src/workflow-runner/feature.ts

@@ -76,7 +76,7 @@ export function createWorkflowRunnerFeature() {
 
           for (const row of dueRows) {
             try {
-              await ctx.write("workflow-runner:write:resume-run", {
+              await ctx.dispatch.write("workflow-runner:write:resume-run", {
                 runId: row.runId,
                 stepIndex: row.stepIndex,
               });
@@ -84,7 +84,7 @@ export function createWorkflowRunnerFeature() {
               // skip: one row's dispatch failing (infra hiccup, not a business
               // outcome — resume-run itself never throws for expected cases)
               // must not stop the rest of this tenant's due rows from resuming.
-              ctx.log.warn(
+              ctx.obs.log.warn(
                 `[workflow-runner:resume-due-runs] runId=${row.runId} stepIndex=${row.stepIndex} dispatch failed: ${String(error)}`,
               );
             }

package/packages/bundled-features/src/workflow-runner/handlers/resume-run.write.ts

@@ -7,7 +7,7 @@
 //   1. Fingerprint check FIRST — before claiming, before any pipeline
 //      work. A changed workflow definition fails loud (WORKFLOW_RUN_FAILED,
 //      reason "workflow_definition_changed"), never a silent skip.
-//   2. Claim via a savepoint-scoped WORKFLOW_RESUMED append (ctx.tryAppendEvent,
+//   2. Claim via a savepoint-scoped WORKFLOW_RESUMED append (ctx.events.tryAppend,
 //      not unsafeAppendEvent — a losing VersionConflict must not poison this
 //      handler's own transaction). A losing claim means another worker beat
 //      us to this row; silent no-op.
@@ -78,7 +78,7 @@ async function appendRunFailed(
   runId: string,
   failedPayload: WorkflowRunFailedPayload,
 ): Promise<void> {
-  await ctx.unsafeAppendEvent({
+  await ctx.events.unsafeAppend({
     aggregateId: runId,
     aggregateType: WORKFLOW_AGGREGATE_TYPE,
     type: WORKFLOW_RUN_FAILED_TYPE,
@@ -176,7 +176,7 @@ function readResumedPayload(payload: unknown): {
 // mistake attempt 1's WORKFLOW_RESUMED for attempt 2's and skip the second
 // retry entirely.
 function isRunAlreadySettled(
-  runEvents: Awaited<ReturnType<HandlerContext["loadAggregate"]>>,
+  runEvents: Awaited<ReturnType<HandlerContext["events"]["load"]>>,
   stepIndex: number,
   expectedRetryAttempt: number | undefined,
 ): boolean {
@@ -192,7 +192,7 @@ function isRunAlreadySettled(
   });
 }
 
-type LoadedEvents = Awaited<ReturnType<HandlerContext["loadAggregate"]>>;
+type LoadedEvents = Awaited<ReturnType<HandlerContext["events"]["load"]>>;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
@@ -229,7 +229,7 @@ function readTriggerSource(startedPayload: unknown): TriggerSource | null {
 }
 
 async function loadReferencedEvent(ctx: HandlerContext, ref: TriggerEventRef) {
-  const events = await ctx.loadAggregate(ref.aggregateId, { atVersion: ref.version });
+  const events = await ctx.events.load(ref.aggregateId, { atVersion: ref.version });
   return events.find((e) => e.id === ref.eventId);
 }
 
@@ -385,7 +385,7 @@ async function runResumedPipeline(ctx: HandlerContext, input: ResumedPipelineInp
       workflowName,
       stepIndex: steps.length,
     };
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
       aggregateId: runId,
       aggregateType: WORKFLOW_AGGREGATE_TYPE,
       type: WORKFLOW_RUN_COMPLETED_TYPE,
@@ -448,7 +448,7 @@ export const resumeRunHandler: WriteHandlerDef = {
     }
 
     const { workflowName } = pending;
-    const runEvents = await ctx.loadAggregate(runId);
+    const runEvents = await ctx.events.load(runId);
 
     // Before the workflow resolution: a racing tick on an already-settled run
     // must not append run-failed after run-completed when the definition has
@@ -469,7 +469,7 @@ export const resumeRunHandler: WriteHandlerDef = {
     }
     const workflow = resolved.workflow;
 
-    const claim = await ctx.tryAppendEvent({
+    const claim = await ctx.events.tryAppend({
       aggregateId: runId,
       aggregateType: WORKFLOW_AGGREGATE_TYPE,
       type: WORKFLOW_RESUMED_TYPE,

package/packages/bundled-features/src/workflow-runner/runner.ts

@@ -75,7 +75,9 @@ export type WorkflowRunFailedPayload = {
   readonly reason?: string;
 };
 
-export type WorkflowRunContext = Pick<HandlerContext, "unsafeAppendEvent">;
+export type WorkflowRunContext = {
+  readonly events: Pick<HandlerContext["events"], "unsafeAppend">;
+};
 
 export class WorkflowSuspensionUnsupportedError extends Error {
   constructor(
@@ -116,7 +118,7 @@ export async function startAndRunWorkflow(args: {
     ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
   };
 
-  await args.handlerCtx.unsafeAppendEvent({
+  await args.handlerCtx.events.unsafeAppend({
     aggregateId: args.runId,
     aggregateType: WORKFLOW_AGGREGATE_TYPE,
     type: WORKFLOW_RUN_STARTED_TYPE,
@@ -127,7 +129,7 @@ export async function startAndRunWorkflow(args: {
 
   // @cast-boundary msp-to-handler-ctx — event-trigger hands over the narrower
   // MultiStreamApplyContext (no query/write/writeAs). The step vocabulary this
-  // runner drives (wait, compute, return) only ever calls unsafeAppendEvent.
+  // runner drives (wait, compute, return) only ever calls events.unsafeAppend.
   const stepCtx = args.handlerCtx as unknown as HandlerContext;
   const outcome = await runStepList(
     steps,
@@ -158,7 +160,7 @@ export async function startAndRunWorkflow(args: {
     stepIndex: steps.length,
   };
 
-  await args.handlerCtx.unsafeAppendEvent({
+  await args.handlerCtx.events.unsafeAppend({
     aggregateId: args.runId,
     aggregateType: WORKFLOW_AGGREGATE_TYPE,
     type: WORKFLOW_RUN_COMPLETED_TYPE,

package/samples/apps/cap-billing-demo/package.json

@@ -10,7 +10,7 @@
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-dev-server": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*",
-    "zod": "^4.4.3",
+    "zod": "^4.6.7",
     "@cosmicdrift/kumiko-locale-de": "workspace:*"
   },
   "devDependencies": {