@cosmicdrift/kumiko-samples 0.352.0 → 0.354.0

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

@@ -1,5 +1,9 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { configuredPiiSubjectKms, type SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  configuredPiiSubjectKms,
+  type SubjectId,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import {
   createEventStoreExecutor,
   createTenantDb,
@@ -18,6 +22,7 @@ import {
   isTenantResourceExtensionHooks,
   type Registry,
   type TenantDataHookCtx,
+  type TenantDestroyHookResult,
   type TenantId,
   type TenantResourceExtensionName,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -26,6 +31,10 @@ import {
   createEscapeHatchReporter,
   UNATTRIBUTED_ACTOR,
 } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  purgeSearchDocumentsForSubject,
+  type SearchAdapter,
+} from "@cosmicdrift/kumiko-framework/search";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import {
   tenantEntity,
@@ -45,17 +54,26 @@ 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.
+  readonly searchAdapter?: SearchAdapter;
   // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); runTenantDataHooks uses them to attribute+audit any
   // 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" });
@@ -67,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(
@@ -106,25 +144,29 @@ 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,
   });
+  const tenantRecordSubject: SubjectId = { kind: "record", entity: "tenant", id: ctx.tenantId };
   const subjects: SubjectId[] = [
     { kind: "tenant", tenantId: ctx.tenantId },
+    tenantRecordSubject,
     ...memberships.map((m) => ({ kind: "user" as const, userId: m.userId })),
   ];
   for (const subject of subjects) {
@@ -133,15 +175,26 @@ async function eraseSubjectKeys(ctx: DestructionStageCtx): Promise<void> {
       eraseReason: "tenant-destroy stage subject-keys",
     });
   }
+  if (ctx.searchAdapter) {
+    await purgeSearchDocumentsForSubject(
+      ctx.db,
+      ctx.registry.features,
+      ctx.searchAdapter,
+      subjectIdToKey(tenantRecordSubject),
+      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");
@@ -180,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

@@ -8,7 +8,7 @@ import {
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import type { QueryHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
 // kumiko-lint-ignore cross-feature-import SystemAdmin user-list joins memberships for tenants column
-import { tenantMembershipsTable, tenantTable } from "../../tenant/index.js";
+import { decryptTenantNames, tenantMembershipsTable, tenantTable } from "../../tenant/index.js";
 import { userEntity } from "../schema/user.js";
 
 const baseList = defineEntityListHandler("user", userEntity, {
@@ -82,7 +82,10 @@ export async function attachTenantLabels(
   ];
   const tenants =
     tenantIds.length > 0
-      ? await selectMany<TenantRow>(db, tenantTable, { id: { in: tenantIds } })
+      ? await decryptTenantNames(
+          await selectMany<TenantRow>(db, tenantTable, { id: { in: tenantIds } }),
+          "user:list",
+        )
       : [];
   const byUser = labelsByUserId(memberships, tenantLabelById(tenants));
   return rows.map((row) => {
@@ -117,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/boot-checks.ts

@@ -24,6 +24,13 @@ export function validateGdprHookCompleteness(features: readonly FeatureDefinitio
       if (usage.extensionName !== EXT_USER_DATA) continue;
       const hasExport = typeof usage.options?.["export"] === "function";
       const hasDelete = typeof usage.options?.["delete"] === "function";
+      // The compile-time "at least one hook" type is bypassed by string-typed
+      // extension names and casts; without this an empty bag registers nothing.
+      if (!hasExport && !hasDelete) {
+        throw new Error(
+          `[kumiko:boot] Feature "${feature.name}" registers EXT_USER_DATA for entity "${usage.entityName}" with neither an export nor a delete hook — the entity silently stays out of the Art.15/17/20 pipeline. Register at least one hook.`,
+        );
+      }
       if (hasExport && !hasDelete) {
         throw new Error(
           `[kumiko:boot] Feature "${feature.name}" exports entity "${usage.entityName}" via EXT_USER_DATA but registers no delete hook — data is included in Art.20 exports but never erased on forget (Art.17 violation). Add a delete hook. If erasure is intentionally handled elsewhere (e.g. crypto-shredding key-erase, parent cascade), register a no-op delete: async () => {} with a comment explaining why.`,

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/deletion-token.ts

@@ -38,7 +38,7 @@ export function redeemDeletionToken(args: {
   readonly secret: string | undefined;
   readonly loadPendingRequestId: (userId: string) => Promise<string | null>;
   // Spends the anchor AND performs the actual lifecycle transition in one
-  // atomic step (#3024) — the caller (confirm-deletion-by-token) folds the
+  // atomic step — the caller (confirm-deletion-by-token) folds the
   // Active→DeletionRequested write itself in here via `updateUserLifecycle`'s
   // `expect: { status: Active, pendingDeletionRequestId }`, so a write issued
   // after `ok: true` can't lose its work to a crash while the grant is

package/packages/bundled-features/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -37,7 +37,7 @@ async function readPendingDeletionRequestId(
 
 // Anonymous apex flow step 2: verify-link target. Verifies the HMAC token,
 // extracts the userId, and flips the grace period through the shared logic —
-// in ONE atomic step with the anchor spend (#3024): commitDeletion carries
+// in ONE atomic step with the anchor spend: commitDeletion carries
 // the actual grace-period transition, so a crash after the spend can no
 // longer lose the write step.
 //
@@ -47,7 +47,7 @@ async function readPendingDeletionRequestId(
 // a cancel-deletion (status → Active, pendingDeletionRequestId → null), a
 // replayed token fails against the nulled/renewed requestId — no re-arm.
 //
-// Concurrency (#3024): two simultaneous confirms of the same token both read
+// Concurrency: two simultaneous confirms of the same token both read
 // the same requestId and both verify the HMAC — commitDeletion spends the
 // anchor AND writes the transition atomically (expect: status===Active &&
 // pendingDeletionRequestId===requestId), so exactly one wins. The loser gets

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/changes.json

@@ -1,4 +1,9 @@
 [
+  {
+    "version": "0.353.0",
+    "type": "fix",
+    "title": "workflow.run-failed carries the real stepIndex when a run suspends in an unsupported step"
+  },
   {
     "version": "0.340.0",
     "type": "improvement",

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

@@ -12,22 +12,87 @@
 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";
 import { registerEventWakeup } from "./event-subscriber.js";
-import { startAndRunWorkflow, type WorkflowRunFailedPayload } from "./runner.js";
+import {
+  startAndRunWorkflow,
+  type WorkflowRunFailedPayload,
+  WorkflowSuspensionUnsupportedError,
+} from "./runner.js";
 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
@@ -43,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({
@@ -56,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
@@ -69,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);
@@ -91,22 +155,24 @@ 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) {
+          // Failures outside the step loop (run-started append) have no step yet, so 0.
+          const stepIndex =
+            error instanceof WorkflowStepError ||
+            error instanceof WorkflowSuspensionUnsupportedError
+              ? error.stepIndex
+              : 0;
           log.warn("workflow run failed", {
             runId,
             workflowName: workflow.name,
-            stepIndex: 0,
+            stepIndex,
             error: String(error),
           });
           const failedPayload: WorkflowRunFailedPayload = {
             workflowName: workflow.name,
-            stepIndex: 0,
+            stepIndex,
             error: describeWorkflowStepError(error),
           };
           await ctx.unsafeAppendEvent({