@cosmicdrift/kumiko-samples 0.338.0 → 0.340.0

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

@@ -29,7 +29,7 @@ export type UpdateUserLifecycleOptions = {
   readonly expect?: Readonly<Record<string, string | number | boolean | null>>;
 };
 
-// `conn` is ctx.db.unsafeRaw(reason) (regular handlers) or the open tx
+// `conn` is ctx.db.unsafeRaw() (regular handlers) or the open tx
 // (forget-cleanup sub-tx) — keeps the event append atomic with the write.
 //
 // Returns `{ applied: false }` instead of throwing only when `options.expect`

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

@@ -155,7 +155,7 @@ export interface RunForgetCleanupArgs {
 
   // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); attributes+audits any EXT_USER_DATA usage's declared
-  // escapeHatch when its delete hook calls ctx.db.unsafeRaw(reason).
+  // escapeHatch when its delete hook calls ctx.db.unsafeRaw().
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
 }

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

@@ -60,7 +60,7 @@ export interface RunUserExportArgs {
   readonly now: Instant;
   // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); attributes+audits any EXT_USER_DATA usage's declared
-  // escapeHatch when its export hook calls ctx.db.unsafeRaw(reason).
+  // escapeHatch when its export hook calls ctx.db.unsafeRaw().
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
 }

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

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "The resume job reads due runs through the job's TenantDb",
+    "detail": "`selectDueWorkflowRunPending` takes a `TenantDb` and returns `{ runId, stepIndex }` rows, so the tenant filter comes from the TenantDb instead of a hand-written `WHERE tenant_id`.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.339.0",
+    "type": "breaking",
+    "title": "workflow-run stream stores a reference to the trigger event instead of its payload",
+    "detail": "`workflow.run-started` now holds `triggerEventRef: { eventId, aggregateId, version }` and no `triggerPayload`; the wait, waitForEvent and retry step events no longer embed it either. `workflow_run_pending` gets a `trigger_event_ref` column and the event-subscriber stops writing `trigger_payload`. `resume-run` loads the trigger and the awaited event through `ctx.loadAggregate` and fails the run with `trigger_event_unavailable` or `awaited_event_unavailable` when one is gone.",
+    "migration": "Own code that reads `triggerPayload` from `workflow.run-started` must read `triggerEventRef` and load the event with `ctx.loadAggregate(ref.aggregateId)`. Apps generate the migration for the new `workflow_run_pending.trigger_event_ref` column with `kumiko schema generate`. The step events `workflow.step.waiting`, `workflow.step.waiting-for-event` and `workflow.retry.scheduled` no longer carry `triggerPayload`; a custom resume loop that read it must load the trigger event through the `triggerEventRef` on its own run-started event (see `samples/recipes/workflow-engine/src/postgres-resume-loop.ts`). Stored run-started events and pending rows keep their old copy; this release rewrites no events, and runs started before it resume from that copy."
+  },
   {
     "version": "0.337.0",
     "type": "fix",

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

@@ -1,8 +1,7 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { sql, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { workflowRunPendingTable } from "../../tables.js";
 
-export type DueRow = { readonly run_id: string; readonly step_index: number };
+export type DueRow = { readonly runId: string; readonly stepIndex: number };
 
 // Oldest first and capped, so a backlog after an outage drains over several
 // ticks instead of holding one tick's `concurrency: "skip"` slot for minutes.
@@ -12,13 +11,11 @@ export const DUE_RUNS_BATCH_SIZE = 100;
 // (ctx.tryAppendEvent 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.
-export async function selectDueWorkflowRunPending(
-  db: DbConnection,
-  tenantId: TenantId,
-): Promise<readonly DueRow[]> {
-  // kumiko-lint-ignore raw-sql tenant-scoped due-row pickup
-  return (await asRawClient(db).unsafe(
-    `SELECT run_id, step_index FROM workflow_run_pending WHERE tenant_id = $1 AND wake_at < now() ORDER BY wake_at ASC LIMIT ${DUE_RUNS_BATCH_SIZE}`,
-    [tenantId],
-  )) as readonly DueRow[];
+// `now()` stays the DB clock so job-host clock skew cannot mark rows due early.
+export function selectDueWorkflowRunPending(db: TenantDb): Promise<readonly DueRow[]> {
+  return db.selectMany<DueRow>(
+    workflowRunPendingTable,
+    { wakeAt: { lt: sql`now()` } },
+    { orderBy: { col: "wakeAt", direction: "asc" }, limit: DUE_RUNS_BATCH_SIZE },
+  );
 }

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

@@ -20,7 +20,7 @@
 // This subscriber never resumes a run itself (D3, workflow-resume-loop.md):
 // the MultiStreamApplyContext it runs in has no callFeature/runStepList
 // access, only unsafeAppendEvent/loadAggregate. It writes triggerEventType
-// + triggerPayload + wakeAt=now() onto the matching pending row(s); the
+// + triggerEventRef + wakeAt=now() onto the matching pending row(s); the
 // existing resume-due-runs job (Phase 2) picks the row up on its next
 // cron tick — the one resume path stays exactly the one Phase 2 built.
 
@@ -34,6 +34,7 @@ import type {
 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.js";
 import { workflowRunPendingTable } from "./tables.js";
 
 type CandidateRow = {
@@ -87,7 +88,11 @@ const wakeupApply: MultiStreamApplyFn = async (event, tx) => {
       workflowRunPendingTable,
       {
         triggerEventType: event.type,
-        triggerPayload: event.payload,
+        triggerEventRef: {
+          eventId: event.id,
+          aggregateId: event.aggregateId,
+          version: event.version,
+        } satisfies TriggerEventRef,
         wakeAt: getTemporal().Now.instant().toString(),
       },
       { tenantId: row.tenantId, runId: row.runId, stepIndex: row.stepIndex },

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

@@ -85,6 +85,11 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
             runId,
             workflow,
             triggerEvent,
+            triggerEventRef: {
+              eventId: event.id,
+              aggregateId: event.aggregateId,
+              version: event.version,
+            },
             ...(idempotencyKey && { idempotencyKey }),
             // @cast-boundary msp-to-handler-ctx — MultiStreamApplyContext only
             // exposes unsafeAppendEvent/loadAggregate, a subset of

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

@@ -24,7 +24,6 @@
 //
 // wait/retry/waitForEvent suspensions all resume automatically now.
 
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { selectDueWorkflowRunPending } from "./db/queries/due-runs.js";
 import { resumeRunHandler } from "./handlers/resume-run.write.js";
@@ -68,26 +67,20 @@ export const workflowRunnerFeature = defineFeature(FEATURE_NAME, (r) => {
         return;
       }
 
-      ctx.systemDb.assertTenantMatch(tenantId);
-      const dueRows = await selectDueWorkflowRunPending(
-        ctx.systemDb.unsafeRaw(
-          "due-row pickup needs FOR UPDATE SKIP LOCKED raw SQL; the query filters by this job's tenantId",
-        ) as DbConnection, // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
-        tenantId,
-      );
+      const dueRows = await selectDueWorkflowRunPending(ctx.systemDb.assertTenantMatch(tenantId));
 
       for (const row of dueRows) {
         try {
           await ctx.write("workflow-runner:write:resume-run", {
-            runId: row.run_id,
-            stepIndex: row.step_index,
+            runId: row.runId,
+            stepIndex: row.stepIndex,
           });
         } catch (error) {
           // 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(
-            `[workflow-runner:resume-due-runs] runId=${row.run_id} stepIndex=${row.step_index} dispatch failed: ${String(error)}`,
+            `[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

@@ -16,16 +16,19 @@
 //      otherwise (wait already wrote its effect; resume past it).
 //
 // The run's ORIGINAL trigger event (the one that started the whole run) is
-// always recovered from the run's own WORKFLOW_RUN_STARTED_TYPE event,
-// never from the pending row — that event always carries it (see
-// WorkflowRunStartedPayload in ./runner). The pending row's own
-// triggerEventType/triggerPayload columns are a DIFFERENT thing: for a
-// waitForEvent suspension they hold the AWAITED event the Phase 3b
+// always re-read from the event store via the triggerEventRef on the run's
+// own WORKFLOW_RUN_STARTED_TYPE event, never from the pending row (see
+// WorkflowRunStartedPayload in ./runner). Neither the run stream nor the
+// pending row holds a copy of a foreign payload, so an erased source event
+// shows up here in its shredded form, and an unloadable one (archived
+// stream) fails the run. The pending row's own
+// triggerEventType/triggerEventRef columns are a DIFFERENT thing: for a
+// waitForEvent suspension they point at the AWAITED event the Phase 3b
 // event-subscriber matched (NULL until then, and NULL forever on a
-// timeout-without-a-match). That payload becomes the resumed pipeline's
-// result for the skipped waitForEvent step itself (see resultKey on
-// steps/wait-for-event.ts) — pre-seeded into stepsAcc below so a
-// subsequent step's resolver can read `ctx.steps[awaits.someKey]`.
+// timeout-without-a-match). That event's payload becomes the resumed
+// pipeline's result for the skipped waitForEvent step itself (see
+// resultKey on steps/wait-for-event.ts) — pre-seeded into stepsAcc below so
+// a subsequent step's resolver can read `ctx.steps[awaits.someKey]`.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
@@ -53,9 +56,9 @@ import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import * as z from "zod";
 import {
   isResumableSuspension,
+  type TriggerEventRef,
   type WorkflowRunCompletedPayload,
   type WorkflowRunFailedPayload,
-  type WorkflowRunStartedPayload,
   WorkflowSuspensionUnsupportedError,
 } from "../runner.js";
 import { workflowRunPendingTable } from "../tables.js";
@@ -182,50 +185,218 @@ function isRunAlreadySettled(
   });
 }
 
-function recoverTriggerEvent(
-  runEvents: Awaited<ReturnType<HandlerContext["loadAggregate"]>>,
+type LoadedEvents = Awaited<ReturnType<HandlerContext["loadAggregate"]>>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isTriggerEventRef(value: unknown): value is TriggerEventRef {
+  return (
+    isRecord(value) &&
+    typeof value["eventId"] === "string" &&
+    typeof value["aggregateId"] === "string" &&
+    typeof value["version"] === "number"
+  );
+}
+
+// run-started events written before the reference existed carry a copy of the
+// trigger payload instead; they stay readable for runs still in flight.
+type TriggerSource =
+  | { readonly kind: "ref"; readonly eventType: string; readonly ref: TriggerEventRef }
+  | { readonly kind: "legacy-copy"; readonly eventType: string; readonly payload: unknown };
+
+function readTriggerSource(startedPayload: unknown): TriggerSource | null {
+  if (!isRecord(startedPayload) || typeof startedPayload["triggerEventType"] !== "string") {
+    return null;
+  }
+  const eventType = startedPayload["triggerEventType"];
+  const ref = startedPayload["triggerEventRef"];
+  if (isTriggerEventRef(ref)) {
+    return { kind: "ref", eventType, ref };
+  }
+  if ("triggerPayload" in startedPayload) {
+    return { kind: "legacy-copy", eventType, payload: startedPayload["triggerPayload"] };
+  }
+  return null;
+}
+
+async function loadReferencedEvent(ctx: HandlerContext, ref: TriggerEventRef) {
+  const events = await ctx.loadAggregate(ref.aggregateId);
+  return events.find((e) => e.id === ref.eventId);
+}
+
+type RecoveredTrigger =
+  | { readonly event: WriteEvent; readonly unavailable: false }
+  | { readonly event: null; readonly unavailable: true };
+
+async function recoverTriggerEvent(
+  ctx: HandlerContext,
+  runEvents: LoadedEvents,
   runId: string,
   user: WriteEvent["user"],
-): WriteEvent {
+): Promise<RecoveredTrigger> {
   const started = runEvents.find((e) => e.type === WORKFLOW_RUN_STARTED_TYPE);
   if (!started) {
     throw new InternalError({
       message: `workflow-runner:write:resume-run: run ${runId} has no ${WORKFLOW_RUN_STARTED_TYPE} event — cannot recover its trigger event.`,
     });
   }
-  const startedPayload = started.payload as WorkflowRunStartedPayload; // @cast-boundary event-store-payload
-  const triggerEvent: WriteEvent = {
-    type: startedPayload.triggerEventType,
-    payload: startedPayload.triggerPayload,
-    user,
+  const source = readTriggerSource(started.payload);
+  if (!source) {
+    throw new InternalError({
+      message: `workflow-runner:write:resume-run: run ${runId} has a malformed ${WORKFLOW_RUN_STARTED_TYPE} event — neither triggerEventRef nor a legacy triggerPayload.`,
+    });
+  }
+  if (source.kind === "legacy-copy") {
+    return {
+      event: { type: source.eventType, payload: source.payload, user },
+      unavailable: false,
+    };
+  }
+  const triggerEvent = await loadReferencedEvent(ctx, source.ref);
+  if (!triggerEvent) {
+    return { event: null, unavailable: true };
+  }
+  return {
+    event: { type: source.eventType, payload: triggerEvent.payload, user },
+    unavailable: false,
   };
-  return triggerEvent;
+}
+
+type PendingTriggerColumns = {
+  readonly triggerEventRef: unknown | null;
+  readonly triggerPayload: unknown | null;
+};
+
+type AwaitedPayload =
+  | { readonly unavailable: false; readonly payload: unknown }
+  | { readonly unavailable: true };
+
+// NULL ref + NULL payload = timeout without a match: the step result stays
+// undefined, same as before. A matched row whose event can no longer be loaded
+// is NOT folded into that case: a later step could not tell "nothing arrived"
+// from "arrived but gone" and would run on missing data, so the run fails
+// instead. Rows matched before the reference existed still carry the copy.
+async function loadAwaitedPayload(
+  ctx: HandlerContext,
+  pending: PendingTriggerColumns,
+): Promise<AwaitedPayload> {
+  if (!isTriggerEventRef(pending.triggerEventRef)) {
+    return { unavailable: false, payload: pending.triggerPayload ?? undefined };
+  }
+  const awaited = await loadReferencedEvent(ctx, pending.triggerEventRef);
+  return awaited ? { unavailable: false, payload: awaited.payload } : { unavailable: true };
 }
 
 // The suspended waitForEvent step itself is skipped on resume
 // (resumeFrom = stepIndex + 1) — its run() never re-executes, so its
 // resultKey (args.event, see steps/wait-for-event.ts) never gets
-// populated by the normal runStepList loop. Seed it here from the
-// pending row's own triggerPayload so a subsequent step's resolver
-// sees the matched event via `ctx.steps[awaits.someKey]`, same as any
-// other step result. NULL on a timeout-without-a-match — a later
-// resolver reading it just sees `undefined`, no special-casing needed.
+// populated by the normal runStepList loop. Seed it here from the awaited
+// event's payload so a subsequent step's resolver sees the matched event via
+// `ctx.steps[awaits.someKey]`, same as any other step result.
 function seedResumedStepResults(
-  pending: { suspensionEventType: string; triggerPayload: unknown | null },
+  suspensionEventType: string,
+  awaitedPayload: unknown,
   steps: readonly StepInstance[],
   stepIndex: number,
 ): Record<string, unknown> {
   const stepsAcc: Record<string, unknown> = {};
-  if (pending.suspensionEventType === WORKFLOW_WAITING_FOR_EVENT_TYPE) {
+  if (suspensionEventType === WORKFLOW_WAITING_FOR_EVENT_TYPE) {
     const suspendedStep = steps[stepIndex];
     const key = suspendedStep && getStep(suspendedStep.kind)?.resultKey?.(suspendedStep.args);
     if (key !== undefined) {
-      stepsAcc[key] = pending.triggerPayload;
+      stepsAcc[key] = awaitedPayload;
     }
   }
   return stepsAcc;
 }
 
+type ResumedPipelineInput = {
+  readonly workflow: WorkflowDefinition;
+  readonly workflowName: string;
+  readonly runId: string;
+  readonly stepIndex: number;
+  readonly resumeFrom: number;
+  readonly triggerEvent: WriteEvent;
+  readonly awaitedPayload: unknown;
+  readonly pending: {
+    readonly suspensionEventType: string;
+    readonly retryAttempt: number | null;
+    readonly definitionFingerprint: string | null;
+  };
+};
+
+async function runResumedPipeline(ctx: HandlerContext, input: ResumedPipelineInput) {
+  const {
+    workflow,
+    workflowName,
+    runId,
+    stepIndex,
+    resumeFrom,
+    triggerEvent,
+    awaitedPayload,
+    pending,
+  } = input;
+  try {
+    const steps = buildPipelineSteps(workflow.pipelineDef, triggerEvent);
+    const workflowCtx = {
+      runId,
+      workflowName,
+      stepIndex,
+      definitionFingerprint: pending.definitionFingerprint ?? undefined,
+      ...(pending.retryAttempt !== null && { retryAttempt: pending.retryAttempt + 1 }),
+    };
+
+    const stepsAcc = seedResumedStepResults(
+      pending.suspensionEventType,
+      awaitedPayload,
+      steps,
+      stepIndex,
+    );
+
+    const outcome = await runStepList(
+      steps,
+      triggerEvent,
+      ctx,
+      stepsAcc,
+      {},
+      workflowCtx,
+      resumeFrom,
+    );
+
+    if (outcome.kind === "suspended") {
+      if (!isResumableSuspension(steps, outcome.stepIndex)) {
+        throw new WorkflowSuspensionUnsupportedError(workflowName, outcome.stepIndex);
+      }
+      // Another suspension further down the pipeline — pending-projection.ts
+      // already materialised the new row; nothing more to do this pass.
+      return { isSuccess: true as const, data: { outcome: "suspended" as const } };
+    }
+
+    const completedPayload: WorkflowRunCompletedPayload = {
+      workflowName,
+      stepIndex: steps.length,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      type: WORKFLOW_RUN_COMPLETED_TYPE,
+      payload: completedPayload,
+    });
+    return { isSuccess: true as const, data: { outcome: "completed" as const } };
+  } catch (error) {
+    log.warn("workflow run failed", { runId, workflowName, stepIndex, error: String(error) });
+    const failedPayload: WorkflowRunFailedPayload = {
+      workflowName,
+      stepIndex,
+      error: describeWorkflowStepError(error),
+    };
+    await appendRunFailed(ctx, runId, failedPayload);
+    return { isSuccess: true as const, data: { outcome: "failed" as const } };
+  }
+}
+
 export const resumeRunHandler: WriteHandlerDef = {
   name: "resume-run",
   agent: { expose: false },
@@ -248,6 +419,7 @@ export const resumeRunHandler: WriteHandlerDef = {
       suspensionEventType: string;
       retryAttempt: number | null;
       definitionFingerprint: string | null;
+      triggerEventRef: unknown | null;
       triggerPayload: unknown | null;
     }>(db, workflowRunPendingTable, { runId, stepIndex, tenantId });
 
@@ -297,62 +469,44 @@ export const resumeRunHandler: WriteHandlerDef = {
       return { isSuccess: true, data: { outcome: "already-resumed" as const } };
     }
 
-    const triggerEvent = recoverTriggerEvent(runEvents, runId, event.user);
-
-    const resumeFrom =
-      pending.suspensionEventType === WORKFLOW_RETRY_SCHEDULED_TYPE ? stepIndex : stepIndex + 1;
-
-    try {
-      const steps = buildPipelineSteps(workflow.pipelineDef, triggerEvent);
-      const workflowCtx = {
-        runId,
+    const recovered = await recoverTriggerEvent(ctx, runEvents, runId, event.user);
+    if (recovered.unavailable) {
+      await appendRunFailed(ctx, runId, {
         workflowName,
         stepIndex,
-        definitionFingerprint: pending.definitionFingerprint ?? undefined,
-        ...(pending.retryAttempt !== null && { retryAttempt: pending.retryAttempt + 1 }),
-      };
-
-      const stepsAcc = seedResumedStepResults(pending, steps, stepIndex);
-
-      const outcome = await runStepList(
-        steps,
-        triggerEvent,
-        ctx,
-        stepsAcc,
-        {},
-        workflowCtx,
-        resumeFrom,
-      );
-
-      if (outcome.kind === "suspended") {
-        if (!isResumableSuspension(steps, outcome.stepIndex)) {
-          throw new WorkflowSuspensionUnsupportedError(workflowName, outcome.stepIndex);
-        }
-        // Another suspension further down the pipeline — pending-projection.ts
-        // already materialised the new row; nothing more to do this pass.
-        return { isSuccess: true, data: { outcome: "suspended" as const } };
-      }
-
-      const completedPayload: WorkflowRunCompletedPayload = {
-        workflowName,
-        stepIndex: steps.length,
-      };
-      await ctx.unsafeAppendEvent({
-        aggregateId: runId,
-        aggregateType: WORKFLOW_AGGREGATE_TYPE,
-        type: WORKFLOW_RUN_COMPLETED_TYPE,
-        payload: completedPayload,
+        error: `Trigger event of run ${runId} is no longer available — cannot resume.`,
+        reason: "trigger_event_unavailable",
       });
-      return { isSuccess: true, data: { outcome: "completed" as const } };
-    } catch (error) {
-      log.warn("workflow run failed", { runId, workflowName, stepIndex, error: String(error) });
-      const failedPayload: WorkflowRunFailedPayload = {
+      return { isSuccess: true, data: { outcome: "failed" as const } };
+    }
+    const triggerEvent = recovered.event;
+
+    const awaited =
+      pending.suspensionEventType === WORKFLOW_WAITING_FOR_EVENT_TYPE
+        ? await loadAwaitedPayload(ctx, pending)
+        : ({ unavailable: false, payload: undefined } as const);
+    if (awaited.unavailable) {
+      await appendRunFailed(ctx, runId, {
         workflowName,
         stepIndex,
-        error: describeWorkflowStepError(error),
-      };
-      await appendRunFailed(ctx, runId, failedPayload);
+        error: `Awaited event of run ${runId} is no longer available — cannot resume.`,
+        reason: "awaited_event_unavailable",
+      });
       return { isSuccess: true, data: { outcome: "failed" as const } };
     }
+
+    const resumeFrom =
+      pending.suspensionEventType === WORKFLOW_RETRY_SCHEDULED_TYPE ? stepIndex : stepIndex + 1;
+
+    return runResumedPipeline(ctx, {
+      workflow,
+      workflowName,
+      runId,
+      stepIndex,
+      resumeFrom,
+      triggerEvent,
+      awaitedPayload: awaited.payload,
+      pending,
+    });
   },
 };

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

@@ -84,6 +84,7 @@ async function upsertPending(tx: DbRunner, row: PendingRow): Promise<void> {
       // Phase 3's event-subscriber writes these when the awaited event
       // arrives — Phase 1 never touches them, insert or update.
       triggerEventType: null,
+      triggerEventRef: null,
       triggerPayload: null,
     },
     { conflictKeys: ["tenantId", "runId", "stepIndex"] },

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

@@ -35,10 +35,19 @@ export function isResumableSuspension(steps: readonly StepInstance[], stepIndex:
   return RESUMABLE_STEP_KINDS.has(steps[stepIndex]?.kind ?? "");
 }
 
+// Points at the trigger event in the event store. The run stream never holds a
+// copy of a foreign payload: erasing or archiving the source event must also
+// cover the workflow, so a resume re-reads the event through this reference.
+export type TriggerEventRef = {
+  readonly eventId: string;
+  readonly aggregateId: string;
+  readonly version: number;
+};
+
 export type WorkflowRunStartedPayload = {
   readonly workflowName: string;
   readonly triggerEventType: string;
-  readonly triggerPayload: unknown;
+  readonly triggerEventRef: TriggerEventRef;
   readonly definitionFingerprint: string;
   readonly idempotencyKey?: string;
 };
@@ -91,6 +100,7 @@ export async function startAndRunWorkflow(args: {
   readonly runId: string;
   readonly workflow: WorkflowDefinition;
   readonly triggerEvent: WriteEvent;
+  readonly triggerEventRef: TriggerEventRef;
   readonly idempotencyKey?: string;
   readonly handlerCtx: HandlerContext;
 }): Promise<{ readonly outcome: "completed" | "suspended" }> {
@@ -99,7 +109,7 @@ export async function startAndRunWorkflow(args: {
   const startedPayload: WorkflowRunStartedPayload = {
     workflowName: args.workflow.name,
     triggerEventType: args.triggerEvent.type,
-    triggerPayload: args.triggerEvent.payload,
+    triggerEventRef: args.triggerEventRef,
     definitionFingerprint: fingerprint,
     ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
   };

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

@@ -52,8 +52,14 @@ export const workflowRunPendingTable = pgTable(
     waitEventType: text("wait_event_type"),
     matchExpr: jsonb("match_expr"),
     // Written by the Phase 3 event-subscriber when the awaited event
-    // arrives — always NULL in Phase 1/2.
+    // arrives — always NULL in Phase 1/2. The row points at the awaited event
+    // ({ eventId, aggregateId, version }); resume-run re-reads it from the
+    // event store, so erasing the event also covers the workflow.
     triggerEventType: text("trigger_event_type"),
+    triggerEventRef: jsonb("trigger_event_ref"),
+    // Legacy copy of the awaited payload. No longer written; only rows
+    // matched before the reference existed still carry it, and resume-run
+    // falls back to it for those.
     triggerPayload: jsonb("trigger_payload"),
   },
   (t) => [
@@ -82,6 +88,7 @@ export const workflowRunPendingTableMeta: EntityTableMeta = defineUnmanagedTable
     { name: "wait_event_type", pgType: "text", notNull: false },
     { name: "match_expr", pgType: "jsonb", notNull: false },
     { name: "trigger_event_type", pgType: "text", notNull: false },
+    { name: "trigger_event_ref", pgType: "jsonb", notNull: false },
     { name: "trigger_payload", pgType: "jsonb", notNull: false },
   ],
   indexes: [

package/samples/apps/styleguide/src/features/widgets/i18n.ts

@@ -55,6 +55,11 @@ export const WIDGETS_I18N = {
     de: "Antwortzeit-Verlauf",
     en: "Response time history",
   },
+  "widgets:catalog:response-time-p95": { de: "p95: 180 ms", en: "p95: 180 ms" },
+  "widgets:catalog:response-time-p95-aria": {
+    de: "p95-Schwelle der letzten 24 Stunden",
+    en: "p95 threshold over the last 24 hours",
+  },
   "widgets:catalog:24h-ago": { de: "vor 24h", en: "24h ago" },
   "widgets:catalog:12h-ago": { de: "vor 12h", en: "12h ago" },
   "widgets:catalog:now": { de: "jetzt", en: "now" },

package/samples/apps/styleguide/src/features/widgets/web/Widgets.tsx

@@ -120,6 +120,17 @@ export function Widgets(): ReactNode {
             end: t("widgets:catalog:now"),
           }}
         />
+        <div className="mt-4">
+          <TimeseriesChart
+            points={RESPONSE_TIMES}
+            windowStartMs={0}
+            windowEndMs={24 * 60 * 60 * 1000}
+            ariaLabel={t("widgets:catalog:response-time-p95-aria")}
+            referenceLines={[
+              { value: 180, label: t("widgets:catalog:response-time-p95"), tone: "warn" },
+            ]}
+          />
+        </div>
       </SectionCard>
 
       <SectionCard