@cosmicdrift/kumiko-samples 0.353.0 → 0.354.0

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

@@ -22,6 +22,7 @@ import {
   isTenantResourceExtensionHooks,
   type Registry,
   type TenantDataHookCtx,
+  type TenantDestroyHookResult,
   type TenantId,
   type TenantResourceExtensionName,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -61,12 +62,18 @@ export type DestructionStageCtx = {
   // EXT_TENANT_DATA usage's declared escapeHatch.
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
+  // Epoch ms the stage must hand back by returning { done: false }.
+  readonly deadlineAt: number;
 };
 
+export type StageRunOutcome = { readonly done: boolean; readonly processed: number };
+
+const STAGE_DONE: StageRunOutcome = { done: true, processed: 0 };
+
 export type DestructionStage = {
   readonly name: TenantDestructionStageName;
   readonly maxAttempts: number;
-  readonly run: (ctx: DestructionStageCtx) => Promise<void>;
+  readonly run: (ctx: DestructionStageCtx) => Promise<StageRunOutcome>;
 };
 
 const tenantCrud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
@@ -78,24 +85,44 @@ const tenantMembershipCrud = createEventStoreExecutor(
   },
 );
 
+// Every hook still runs each tick (they are idempotent), so a later hook is not
+// starved by an earlier one that keeps reporting done:false.
+function newOutcomeAccumulator(): {
+  add: (result: TenantDestroyHookResult | void) => void;
+  outcome: () => StageRunOutcome;
+} {
+  let allDone = true;
+  let processed = 0;
+  return {
+    add: (result) => {
+      if (result?.done === false) allDone = false;
+      processed += result?.processed ?? 0;
+    },
+    outcome: () => ({ done: allDone, processed }),
+  };
+}
+
 async function runExtensionDestroyHooks(
   registry: Registry,
   extensionName: TenantResourceExtensionName,
   ctx: DestructionStageCtx,
-): Promise<void> {
+): Promise<StageRunOutcome> {
   const usages = registry.getExtensionUsages(extensionName);
+  const total = newOutcomeAccumulator();
   for (const usage of usages) {
     if (!isTenantResourceExtensionHooks(usage.options)) {
       throw new Error(
         `${extensionName} registration for "${usage.entityName}" has no destroy function`,
       );
     }
-    await usage.options.destroyTenant(ctx.tenantId, ctx);
+    total.add(await usage.options.destroyTenant(ctx.tenantId, ctx));
   }
+  return total.outcome();
 }
 
-async function runTenantDataHooks(ctx: DestructionStageCtx): Promise<void> {
+async function runTenantDataHooks(ctx: DestructionStageCtx): Promise<StageRunOutcome> {
   const usages = ctx.registry.getExtensionUsages(EXT_TENANT_DATA);
+  const total = newOutcomeAccumulator();
   for (const usage of usages) {
     if (!isTenantDataExtensionHooks(usage.options)) {
       throw new Error(
@@ -117,19 +144,21 @@ async function runTenantDataHooks(ctx: DestructionStageCtx): Promise<void> {
       }),
       registry: ctx.registry,
       tenantId: ctx.tenantId,
+      deadlineAt: ctx.deadlineAt,
       fileProviderResolver: ctx.fileProviderResolver,
       log: ctx.log,
     };
-    await destroy(hookCtx);
+    total.add(await destroy(hookCtx));
   }
+  return total.outcome();
 }
 
-async function eraseSubjectKeys(ctx: DestructionStageCtx): Promise<void> {
+async function eraseSubjectKeys(ctx: DestructionStageCtx): Promise<StageRunOutcome> {
   const kms = configuredPiiSubjectKms();
   if (!kms) {
     ctx.log?.("[tenant-lifecycle] subject-keys stage skipped: no KMS adapter configured");
     // skip: KMS optional — apps without crypto-shredding still run other destroy stages
-    return;
+    return STAGE_DONE;
   }
   const memberships = await selectMany<{ userId: string }>(ctx.db, tenantMembershipsTable, {
     tenantId: ctx.tenantId,
@@ -155,15 +184,17 @@ async function eraseSubjectKeys(ctx: DestructionStageCtx): Promise<void> {
       tenantRecordSubject,
     );
   }
+  return STAGE_DONE;
 }
 
-async function purgeTenantCache(ctx: DestructionStageCtx): Promise<void> {
+async function purgeTenantCache(ctx: DestructionStageCtx): Promise<StageRunOutcome> {
   // ponytail: Redis SCAN+DEL is wired when ctx carries a redis client; until
   // then this stage is a documented no-op (no cache layer in test stack).
   ctx.log?.("[tenant-lifecycle] cache stage: no redis client in ctx — skipped");
+  return STAGE_DONE;
 }
 
-async function tombstoneTenantRow(ctx: DestructionStageCtx): Promise<void> {
+async function tombstoneTenantRow(ctx: DestructionStageCtx): Promise<StageRunOutcome> {
   const now = getTemporal().Now.instant();
   const user = createSystemUser(ctx.tenantId);
   const db = createTenantDb(ctx.db, ctx.tenantId, "system");
@@ -202,6 +233,7 @@ async function tombstoneTenantRow(ctx: DestructionStageCtx): Promise<void> {
     { skipOptimisticLock: true },
   );
   invalidateTenantLifecycleGate(ctx.tenantId);
+  return STAGE_DONE;
 }
 
 export const DESTRUCTION_STAGES: readonly DestructionStage[] = [

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

@@ -0,0 +1,58 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import 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 type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { tenantTable } from "../tenant/index.js";
+import { TENANT_AGGREGATE_TYPE, TENANT_DESTRUCTION_STARTED_EVENT_QN } from "./constants.js";
+import { runTenantDestructionSweep } from "./run-tenant-destroy.js";
+
+// Sidesteps the `request-destruction` write handler (needs user/auth/sessions
+// 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(
+    db,
+    tenantTable,
+    { status: "destroying", destroyStartedAt: now },
+    { id: tenantId },
+  );
+  await append(db, {
+    aggregateId: tenantId,
+    aggregateType: TENANT_AGGREGATE_TYPE,
+    tenantId,
+    expectedVersion: (await loadAggregate(db, tenantId, tenantId)).at(-1)?.version ?? 0,
+    type: TENANT_DESTRUCTION_STARTED_EVENT_QN,
+    payload: { startedAt: now.toString() },
+    metadata: { userId: "system", requestId: "test:destruction-started" },
+  });
+}
+
+export async function driveDestructionToCompletion(
+  stack: TestStack,
+  db: DbConnection,
+  tenantId: TenantId,
+  searchAdapter?: SearchAdapter,
+): Promise<string> {
+  const farFuture = getTemporal()
+    .Now.instant()
+    .add({ hours: 24 * 3650 });
+  let status = "";
+  for (let i = 0; i < 20; i++) {
+    await runTenantDestructionSweep({
+      db: stack.db,
+      registry: stack.registry,
+      now: farFuture,
+      searchAdapter,
+    });
+    const rows = await selectMany(db, tenantTable, { id: tenantId });
+    status = String(rows[0]?.["status"]);
+    if (status === "destroyed" || status === "destroyFailed") break;
+  }
+  return status;
+}
+
+export { runTenantDestructionSweep };

package/packages/bundled-features/src/tier-engine/changes.json

@@ -1,4 +1,9 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "tier-engine:write:set-tenant-tier resolves agent risk high"
+  },
   {
     "version": "0.352.0",
     "type": "improvement",

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

@@ -67,6 +67,7 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
         .refine((t) => !opts.validTiers || opts.validTiers.has(t), { message: "unknown tier" }),
     }),
     access: { roles: ["SystemAdmin"] },
+    agent: { risk: "high" },
     escapeHatch: {
       grants: ["unsafeRaw"],
       reason: SET_TENANT_TIER_REASON,

package/packages/bundled-features/src/user/changes.json

@@ -1,4 +1,19 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "user:write:user:update resolves agent risk high"
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "user:query:user:list skips the tenants label when the tenant feature is not mounted"
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "user:query:user:detail skips the tenants label when the tenant feature is not mounted"
+  },
   {
     "version": "0.340.0",
     "type": "improvement",

package/packages/bundled-features/src/user/handlers/detail.query.ts

@@ -25,6 +25,7 @@ export const detailQuery = {
   ) => {
     const result = await baseDetail.handler?.(query, ctx);
     if (result === null || typeof result !== "object") return result;
+    if (!ctx.registry.features.has("tenant")) return result;
     const [enriched] = await attachTenantLabels(
       [result as Record<string, unknown>],
       dbForList(ctx),

package/packages/bundled-features/src/user/handlers/list.query.ts

@@ -120,6 +120,9 @@ export const listQuery: QueryHandlerDef = {
       return result;
     }
     const envelope = result as { rows: readonly Record<string, unknown>[] };
+    // Without the tenant feature there are no membership tables to join; with
+    // it, a failing lookup must surface instead of rendering a silent empty column.
+    if (!ctx.registry.features.has("tenant")) return result;
     const rows = await attachTenantLabels(envelope.rows, dbForList(ctx));
     return { ...envelope, rows };
   },

package/packages/bundled-features/src/user/handlers/update.write.ts

@@ -59,6 +59,7 @@ export const updateWrite = defineWriteHandler({
   },
   description:
     "Changes a user's display name, locale, timezone, email, verification flag, last active tenant or global roles against the version the caller read; callers may edit themselves, while editing someone else or granting roles needs a privileged actor.",
+  agent: { risk: "high" },
   escapeHatch: {
     reason: SYSTEM_ADMIN_DEMOTION_COUNT_REASON,
   },

package/packages/bundled-features/src/user/seeding.ts

@@ -125,6 +125,40 @@ export async function reconcileSeededUserEmailVerified(
   }
 }
 
+// Re-writes `email` through the executor so the PII write pipeline recomputes
+// `email_bidx`. Repairs rows whose blind index is NULL or stale (written before
+// the key existed, key rotated, subject-key erased), which would otherwise stay
+// invisible to every `fetchOne(userTable, { email })` lookup.
+export async function rewriteSeededUserEmail(
+  db: DbConnection,
+  existingRow: Record<string, unknown>,
+  email: string,
+  by: SessionUser,
+): Promise<void> {
+  const id = existingRow["id"];
+  if (typeof id !== "string") {
+    throw new Error("rewriteSeededUserEmail: existing user row has no string id");
+  }
+  const tdb = createTenantDb(db, by.tenantId, "system");
+  const result = await userExecutor.update(
+    { id, version: existingRow["version"] as number, changes: { email } },
+    by,
+    tdb,
+  );
+  // version_conflict: a concurrent write already changed the row — fine for a seed helper.
+  // unique_violation: a duplicate row already holds the blind index; the repair
+  // has to wait for a manual duplicate cleanup.
+  if (
+    !result.isSuccess &&
+    result.error.code !== "version_conflict" &&
+    result.error.code !== "unique_violation"
+  ) {
+    throw new Error(
+      `rewriteSeededUserEmail failed: ${result.error.code} — ${JSON.stringify(result.error.details ?? {})}`,
+    );
+  }
+}
+
 // Extrahiert die `id`-Spalte aus dem executor.create-Result. Der
 // Executor liefert ein Record<string, unknown> (die Projection-Row), in
 // das die DB die Aggregat-id reinschreibt — wir prüfen runtime statt

package/packages/bundled-features/src/user-data-rights/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "Row-bound grants (deletion token, tenant handover) refuse a colon in anchor or subject",
+    "migration": "signRowBoundGrant now throws when the anchor or subject contains \":\", and redeem returns FAILED for such a token. Use colon-free ids (uuids) for anchor and subject; a purpose may still contain a colon."
+  },
   {
     "version": "0.338.0",
     "type": "fix",

package/packages/bundled-features/src/user-data-rights/handlers/request-deletion.write.ts

@@ -51,6 +51,7 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
       },
     },
     escapeHatch: {
+      grants: ["systemIdentity", "unsafeRaw"],
       reason:
         "resolveGracePeriod reads the tenant compliance profile via ctx.queryAs(SYSTEM, " +
         "...) to compute the grace period end — the calling user's own identity has no read " +

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

@@ -1,3 +1,4 @@
+export { TENANT_MODEL_CONFIG_KEY } from "./constants.js";
 export { createUserDataRightsFeature, type UserDataRightsOptions } from "./feature.js";
 export type { SendDeletionVerificationEmailFn } from "./handlers/request-deletion-by-email.write.js";
 export {

package/packages/bundled-features/src/user-data-rights/schema/download-attempt.ts

@@ -35,16 +35,24 @@ export const downloadAttemptEntity = createEntity({
     jobId: createTextField({ personal: false, reason: "technical_reference" }),
     // User-ID wenn auth-Pfad (job). NULL bei anonymous (token-Pfad).
     attemptedByUserId: createTextField({ personal: false, reason: "pseudonymous_fk" }),
-    // Same reasoning as download-token.ts's lastUsedFromIp/lastUsedUserAgent
-    // (sibling entity, same feature): DPO brute-force-audit data belongs to
-    // the tenant operator, not the (often anonymous) requester. Also avoids
-    // a real hazard on this buildEntityTable-managed entity: attemptedByUserId
-    // is null-by-design for the anonymous token path, so a subject annotation
-    // (`personal: { of: "attemptedByUserId" }`) would throw
-    // SubjectResolutionError on every such row once a KMS is configured
+    // No subject annotation on this buildEntityTable-managed entity:
+    // attemptedByUserId is null-by-design for the anonymous token path, so
+    // `personal: { of: "attemptedByUserId" }` would throw SubjectResolutionError
+    // on every such row once a KMS is configured
     // (crypto/subject-resolver.ts resolveUserOwnedSubject).
-    ip: createTextField({ maxLength: 64, personal: false, reason: "is_business_data" }),
-    userAgent: createTextField({ maxLength: 256, personal: false, reason: "is_business_data" }),
+    // The job path knows the requester and an IP is personal data, so this is a
+    // deliberate waiver, not business data: a user forget does not shred these
+    // values, the 90d hardDelete below is what removes them.
+    ip: createTextField({
+      maxLength: 64,
+      personal: false,
+      reason: "security_audit_retention_bounded",
+    }),
+    userAgent: createTextField({
+      maxLength: 256,
+      personal: false,
+      reason: "security_audit_retention_bounded",
+    }),
     attemptedAt: createTimestampField({ required: true }),
   },
   // 90d hardDelete: unbounded growth = disk-bomb genau gegen das System

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

@@ -1,5 +1,4 @@
 import {
-  access,
   createSystemUser,
   defineWriteHandler,
   SYSTEM_TENANT_ID,
@@ -36,8 +35,15 @@ export const changeEmailWrite = defineWriteHandler({
     currentPassword: z.string().min(1),
     newEmail: z.email(),
   }),
-  access: { roles: access.authenticated },
+  access: {
+    openToAll: {
+      reason:
+        "self-service for any signed-in user, including tenant members whose only role is " +
+        "TenantAdmin; the handler only touches event.user.id and re-checks the caller's password",
+    },
+  },
   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, " +

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

@@ -12,13 +12,20 @@
 import type {
   FeatureRegistrar,
   MultiStreamProjectionDefinition,
+  StepInstance,
   WorkflowDefinition,
   WriteEvent,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
+  buildPipelineSteps,
+  createSystemUser,
   describeWorkflowStepError,
+  getStep,
+  SYSTEM_TENANT_ID,
+  type TenantId,
   WORKFLOW_AGGREGATE_TYPE,
   WORKFLOW_RUN_FAILED_TYPE,
+  WorkflowStepError,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { workflowRunAggregateId } from "./aggregate-id.js";
@@ -32,6 +39,60 @@ import { registerWorkflow } from "./workflow-registry.js";
 
 const log = createFallbackLogger("workflow-runner");
 
+// The MSP apply context only offers unsafeAppendEvent/loadAggregate; these steps reach for
+// ctx.db/write/writeAs and would crash on the first run instead of at registration.
+const STEP_KINDS_NEEDING_HANDLER_CONTEXT: ReadonlySet<string> = new Set([
+  "aggregate.create",
+  "aggregate.update",
+  "callFeature",
+  "read.findOne",
+  "read.findMany",
+  "unsafeProjectionUpsert",
+  "unsafeProjectionDelete",
+]);
+
+function* walkStepInstances(steps: readonly StepInstance[]): Generator<StepInstance, void, void> {
+  for (const step of steps) {
+    yield step;
+    const { args } = step;
+    if (typeof args !== "object" || args === null) continue;
+    for (const path of getStep(step.kind)?.subPaths ?? []) {
+      const nested: unknown = path in args ? Reflect.get(args, path) : undefined;
+      if (Array.isArray(nested)) yield* walkStepInstances(nested);
+    }
+  }
+}
+
+export function assertEventTriggerStepsSupported(workflow: WorkflowDefinition): void {
+  let steps: readonly StepInstance[];
+  try {
+    // Same contract as the boot validator for handler pipelines: the closure must build its
+    // step list from the step builder alone, so an empty event is enough to enumerate kinds.
+    steps = buildPipelineSteps(workflow.pipelineDef, {
+      type: "workflow-registration-probe",
+      payload: {},
+      user: createSystemUser(SYSTEM_TENANT_ID as TenantId),
+    });
+  } catch (error) {
+    throw new Error(
+      `Workflow "${workflow.name}" pipeline closure threw at registration: ${String(error)}. ` +
+        "Build the step list without reading event payload fields; read them inside step resolvers.",
+      { cause: error },
+    );
+  }
+  for (const step of walkStepInstances(steps)) {
+    if (getStep(step.kind) === undefined) {
+      throw new Error(`Workflow "${workflow.name}" uses unknown step kind "${step.kind}"`);
+    }
+    if (STEP_KINDS_NEEDING_HANDLER_CONTEXT.has(step.kind)) {
+      throw new Error(
+        `Workflow "${workflow.name}" is event-triggered but uses step "${step.kind}", which needs a ` +
+          "handler context (db/write) the event-trigger projection does not provide.",
+      );
+    }
+  }
+}
+
 export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefinition): void {
   // Populate the workflow-registry unconditionally, before the event-trigger
   // guard below — resume-run (framework#2513 Phase 2) looks workflows up by
@@ -47,6 +108,8 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
   // need a scheduler, not an MSP, so there is nothing to register here.
   if (workflow.trigger.kind !== "event") return;
 
+  assertEventTriggerStepsSupported(workflow);
+
   const eventType = workflow.trigger.eventType;
 
   r.multiStreamProjection({
@@ -60,12 +123,6 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
         // closure does not carry that narrowing, and re-narrowing here keeps
         // `trigger.filter` below typed without a cast.
         if (workflow.trigger.kind !== "event") return;
-        if (workflow.trigger.filter) {
-          const matches = workflow.trigger.filter(event as never);
-          // skip: the workflow's own trigger filter rejected this event — not
-          // this run's concern, so no run is started and nothing is recorded.
-          if (!matches) return;
-        }
 
         // @cast-boundary msp-to-write-event — the MSP delivers a StoredEvent
         // (event-store shape); the workflow runner expects a WriteEvent
@@ -73,6 +130,9 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
         // overlap exactly — the missing `.user` field is acceptable because
         // workflow triggers run system-level, not user-scoped.
         const triggerEvent = event as unknown as WriteEvent;
+        // skip: the workflow's own trigger filter rejected this event — not this run's
+        // concern, so no run is started and nothing is recorded.
+        if (workflow.trigger.filter && !workflow.trigger.filter(triggerEvent)) return;
         let idempotencyKey: string | undefined;
         if (typeof workflow.idempotencyKey === "function") {
           idempotencyKey = workflow.idempotencyKey(triggerEvent);
@@ -95,17 +155,15 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
               version: event.version,
             },
             ...(idempotencyKey && { idempotencyKey }),
-            // @cast-boundary msp-to-handler-ctx — MultiStreamApplyContext only
-            // exposes unsafeAppendEvent/loadAggregate, a subset of
-            // HandlerContext. The step vocabulary this runner drives (wait,
-            // compute, return) only ever calls unsafeAppendEvent on it.
-            handlerCtx: ctx as never,
+            handlerCtx: ctx,
           });
         } catch (error) {
-          // Only the suspension error knows its step; a throw inside a step
-          // carries no index, so it still reports 0.
+          // Failures outside the step loop (run-started append) have no step yet, so 0.
           const stepIndex =
-            error instanceof WorkflowSuspensionUnsupportedError ? error.stepIndex : 0;
+            error instanceof WorkflowStepError ||
+            error instanceof WorkflowSuspensionUnsupportedError
+              ? error.stepIndex
+              : 0;
           log.warn("workflow run failed", {
             runId,
             workflowName: workflow.name,

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

@@ -48,6 +48,7 @@ import {
   WORKFLOW_RUN_STARTED_TYPE,
   WORKFLOW_WAITING_FOR_EVENT_TYPE,
   type WorkflowDefinition,
+  WorkflowStepError,
   type WriteEvent,
   type WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -392,9 +393,13 @@ async function runResumedPipeline(ctx: HandlerContext, input: ResumedPipelineInp
     return { isSuccess: true as const, data: { outcome: "completed" as const } };
   } catch (error) {
     log.warn("workflow run failed", { runId, workflowName, stepIndex, error: String(error) });
+    // The input stepIndex is the suspended step; the failure happened at the step the resumed pass reached.
     const failedPayload: WorkflowRunFailedPayload = {
       workflowName,
-      stepIndex,
+      stepIndex:
+        error instanceof WorkflowStepError || error instanceof WorkflowSuspensionUnsupportedError
+          ? error.stepIndex
+          : stepIndex,
       error: describeWorkflowStepError(error),
     };
     await appendRunFailed(ctx, runId, failedPayload);

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

@@ -75,6 +75,8 @@ export type WorkflowRunFailedPayload = {
   readonly reason?: string;
 };
 
+export type WorkflowRunContext = Pick<HandlerContext, "unsafeAppendEvent">;
+
 export class WorkflowSuspensionUnsupportedError extends Error {
   constructor(
     readonly workflowName: string,
@@ -102,7 +104,7 @@ export async function startAndRunWorkflow(args: {
   readonly triggerEvent: WriteEvent;
   readonly triggerEventRef: TriggerEventRef;
   readonly idempotencyKey?: string;
-  readonly handlerCtx: HandlerContext;
+  readonly handlerCtx: WorkflowRunContext;
 }): Promise<{ readonly outcome: "completed" | "suspended" }> {
   const fingerprint = computeDefinitionFingerprint(args.workflow);
 
@@ -123,10 +125,14 @@ export async function startAndRunWorkflow(args: {
 
   const steps = buildPipelineSteps(args.workflow.pipelineDef, args.triggerEvent);
 
+  // @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.
+  const stepCtx = args.handlerCtx as unknown as HandlerContext;
   const outcome = await runStepList(
     steps,
     args.triggerEvent,
-    args.handlerCtx,
+    stepCtx,
     {},
     {},
     {

package/samples/apps/showcase/src/features/items/feature.ts

@@ -8,6 +8,7 @@
 // hängt hier die Handler dran und ruft r.screen/r.nav.
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import { itemsTranslations } from "./i18n";
 import {
   itemActiveScreen,
@@ -29,7 +30,7 @@ const open = {
 
 // The boot validator checks server-registered keys, while the client bundle is
 // locale-first — flip it rather than maintaining the same strings twice.
-function keyFirst(byLocale: typeof itemsTranslations): Record<string, Record<string, string>> {
+function keyFirst(byLocale: TranslationsByLocale): Record<string, Record<string, string>> {
   const out: Record<string, Record<string, string>> = {};
   for (const [locale, entries] of Object.entries(byLocale)) {
     for (const [key, value] of Object.entries(entries)) {