@pikku/core 0.12.69 → 0.12.71

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -3,7 +3,6 @@ import { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSl
 import { wireQueueWorker } from '../queue/queue-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-import { createHttpScenarioActors } from '../../services/http-scenario-actors.js';
 const resolveWorkflowMeta = (name) => {
     const rootMeta = pikkuState(null, 'workflows', 'meta');
     if (rootMeta[name]) {
@@ -29,7 +28,6 @@ const resolveWorkflowMeta = (name) => {
     return null;
 };
 const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
-import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
 import { PikkuError, addError, isExpectedError, } from '../../errors/error-handler.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
@@ -173,15 +171,45 @@ const WORKFLOW_END_STATES = new Set([
     'suspended',
 ]);
 /**
- * Abstract workflow state service
- * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
- * Combines orchestration and step execution
+ * States a run never leaves. `suspended` is deliberately absent: a suspended
+ * run stops a poll loop but can still be resumed, so anything the process holds
+ * for it has to survive.
  */
+const WORKFLOW_TERMINAL_STATES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+]);
+/** First wait when polling a run, before the backoff starts widening it. */
+const WORKFLOW_POLL_MIN_MS = 10;
+/** How much each successive wait grows, up to the caller's ceiling. */
+const WORKFLOW_POLL_FACTOR = 1.6;
+/**
+ * Ceiling for the wait on an inline sub-workflow. Lower than a top-level run's
+ * default, because the parent step is blocked on it and every wait here is
+ * added latency in the middle of a workflow rather than at its edge.
+ */
+const WORKFLOW_CHILD_POLL_MAX_MS = 500;
 export class PikkuWorkflowService {
-    inlineRuns = new Set();
-    // User-flow actors per run: live authenticated clients (cookie jars) are
-    // process-local by nature, so they ride this map, never the persisted wire.
-    runActors = new Map();
+    runExtension;
+    runContexts = new Map();
+    contextFor(runId) {
+        let context = this.runContexts.get(runId);
+        if (!context) {
+            context = { inline: false };
+            this.runContexts.set(runId, context);
+        }
+        return context;
+    }
+    /** Drop a run's context once nothing is holding it open. */
+    releaseContext(runId) {
+        const context = this.runContexts.get(runId);
+        if (!context)
+            return;
+        if (context.inline || context.replay)
+            return;
+        this.runContexts.delete(runId);
+    }
     get logger() {
         return getSingletonServices()?.logger;
     }
@@ -199,20 +227,33 @@ export class PikkuWorkflowService {
             this.wireQueueWorkers();
         }
     }
-    async safeMirror(fn) {
-        if (!this.mirror)
-            return;
-        try {
-            await fn();
-        }
-        catch (err) {
+    /**
+     * Perform a state write, then shadow it to the mirror.
+     *
+     * The mirror is an observability sink, never a second source of truth, and
+     * both halves of that follow from this one shape: it is only ever told about
+     * a write that already landed, and a mirror that is down or throwing cannot
+     * fail — or even be seen by — the workflow it is watching.
+     *
+     * @param write - the authoritative write; its result is what the caller gets
+     * @param mirror - shadows the write, given the live mirror and what was written
+     */
+    async mirrored(write, mirror) {
+        const written = await write();
+        if (this.mirror) {
             try {
-                this.logger?.warn?.(`[pikku] WorkflowRunMirror write failed: ${err?.message ?? err}`);
+                await mirror(this.mirror, written);
             }
-            catch {
-                // logger unavailable (e.g. singleton services not initialized) — swallow
+            catch (err) {
+                try {
+                    this.logger?.warn?.(`[pikku] WorkflowRunMirror write failed: ${err?.message ?? err}`);
+                }
+                catch {
+                    // logger unavailable (e.g. singleton services not initialized) — swallow
+                }
             }
         }
+        return written;
     }
     /**
      * Wire the queue-based orchestrator/step/sleeper workers.
@@ -310,19 +351,23 @@ export class PikkuWorkflowService {
      * Check if a run is executing inline (without queues)
      */
     isInline(runId) {
-        return this.inlineRuns.has(runId);
+        return this.runContexts.get(runId)?.inline === true;
     }
     /**
      * Register a run as inline (for graph-runner to use)
      */
     registerInlineRun(runId) {
-        this.inlineRuns.add(runId);
+        this.contextFor(runId).inline = true;
     }
     /**
      * Unregister a run from inline tracking
      */
     unregisterInlineRun(runId) {
-        this.inlineRuns.delete(runId);
+        const context = this.runContexts.get(runId);
+        if (!context)
+            return;
+        context.inline = false;
+        this.releaseContext(runId);
     }
     async registerWorkflowVersions() {
         const allMeta = pikkuState(null, 'workflows', 'meta');
@@ -333,9 +378,7 @@ export class PikkuWorkflowService {
         }
     }
     async createRun(workflowName, input, inline, graphHash, wire, options) {
-        const runId = await this.createRunImpl(workflowName, input, inline, graphHash, wire, options);
-        await this.safeMirror(() => this.mirror.createRun(runId, workflowName, input, inline, graphHash, wire, options));
-        return runId;
+        return this.mirrored(() => this.createRunImpl(workflowName, input, inline, graphHash, wire, options), (mirror, runId) => mirror.createRun(runId, workflowName, input, inline, graphHash, wire, options));
     }
     /**
      * Get minimal workflow run status with step summaries.
@@ -412,23 +455,30 @@ export class PikkuWorkflowService {
      * @param status - New status
      */
     async updateRunStatus(id, status, output, error) {
-        await this.updateRunStatusImpl(id, status, output, error);
-        await this.safeMirror(() => this.mirror.updateRunStatus(id, status, output, error));
+        await this.mirrored(() => this.updateRunStatusImpl(id, status, output, error), (mirror) => mirror.updateRunStatus(id, status, output, error));
+        if (WORKFLOW_TERMINAL_STATES.has(status)) {
+            // The run is over: release whatever this process opened for it. Queued
+            // runs never pass through the inline path that does this, so their
+            // context was held for the life of the process.
+            this.runExtension?.detachRunContext(id);
+            this.releaseContext(id);
+        }
     }
     /**
      * Insert initial step state (called by orchestrator)
      * Creates pending step in both workflow_step and workflow_step_history
      * @param runId - Run ID
      * @param stepName - Step cache key
-     * @param rpcName - RPC function name
+     * @param rpcName - The name this step was dispatched by: an RPC for a
+     *   `workflow.do` step, a step function for a scenario step, null for a
+     *   closure. Nothing dispatches off this value — it is recorded so a reader
+     *   can join a step back to the function that ran it.
      * @param data - Step input data
      * @param stepOptions - Step options (retries, retryDelay)
      * @returns Step state with generated stepId
      */
     async insertStepState(runId, stepName, rpcName, data, stepOptions, fromStepName) {
-        const step = await this.insertStepStateImpl(runId, stepName, rpcName, data, stepOptions, fromStepName);
-        await this.safeMirror(() => this.mirror.insertStepState(runId, { ...step, stepName, rpcName, data }));
-        return step;
+        return this.mirrored(() => this.insertStepStateImpl(runId, stepName, rpcName, data, stepOptions, fromStepName), (mirror, step) => mirror.insertStepState(runId, { ...step, stepName, rpcName, data }));
     }
     /**
      * Mark step as running
@@ -436,8 +486,7 @@ export class PikkuWorkflowService {
      * @param stepId - Step ID
      */
     async setStepRunning(stepId) {
-        await this.setStepRunningImpl(stepId);
-        await this.safeMirror(() => this.mirror.setStepRunning(stepId));
+        await this.mirrored(() => this.setStepRunningImpl(stepId), (mirror) => mirror.setStepRunning(stepId));
     }
     /**
      * Mark step as scheduled (queued for execution)
@@ -445,8 +494,7 @@ export class PikkuWorkflowService {
      * @param stepId - Step ID
      */
     async setStepScheduled(stepId) {
-        await this.setStepScheduledImpl(stepId);
-        await this.safeMirror(() => this.mirror.setStepScheduled(stepId));
+        await this.mirrored(() => this.setStepScheduledImpl(stepId), (mirror) => mirror.setStepScheduled(stepId));
     }
     /**
      * Store step result and mark as succeeded
@@ -455,8 +503,7 @@ export class PikkuWorkflowService {
      * @param result - Step result
      */
     async setStepResult(stepId, result) {
-        await this.setStepResultImpl(stepId, result);
-        await this.safeMirror(() => this.mirror.setStepResult(stepId, result));
+        await this.mirrored(() => this.setStepResultImpl(stepId, result), (mirror) => mirror.setStepResult(stepId, result));
     }
     /**
      * Set the child workflow run ID on a step
@@ -464,8 +511,7 @@ export class PikkuWorkflowService {
      * @param childRunId - Child workflow run ID
      */
     async setStepChildRunId(stepId, childRunId) {
-        await this.setStepChildRunIdImpl(stepId, childRunId);
-        await this.safeMirror(() => this.mirror.setStepChildRunId(stepId, childRunId));
+        await this.mirrored(() => this.setStepChildRunIdImpl(stepId, childRunId), (mirror) => mirror.setStepChildRunId(stepId, childRunId));
     }
     /**
      * Store step error and mark as failed
@@ -474,14 +520,15 @@ export class PikkuWorkflowService {
      * @param error - Error object
      */
     async setStepError(stepId, error) {
-        await this.setStepErrorImpl(stepId, error);
-        const serialized = {
-            message: error.message,
-            stack: error.stack,
-            code: error.code,
-            expected: isExpectedError(error),
-        };
-        await this.safeMirror(() => this.mirror.setStepError(stepId, serialized));
+        await this.mirrored(() => this.setStepErrorImpl(stepId, error), (mirror) => {
+            const serialized = {
+                message: error.message,
+                stack: error.stack,
+                code: error.code,
+                expected: isExpectedError(error),
+            };
+            return mirror.setStepError(stepId, serialized);
+        });
     }
     /**
      * Create a new retry attempt for a failed step
@@ -492,13 +539,10 @@ export class PikkuWorkflowService {
      * @returns New step state for the retry attempt
      */
     async createRetryAttempt(failedStepId, status) {
-        const newStep = await this.createRetryAttemptImpl(failedStepId, status);
-        const stepName = newStep.stepName ?? '';
-        await this.safeMirror(() => this.mirror.createRetryAttempt(failedStepId, {
+        return this.mirrored(() => this.createRetryAttemptImpl(failedStepId, status), (mirror, newStep) => mirror.createRetryAttempt(failedStepId, {
             ...newStep,
-            stepName,
+            stepName: newStep.stepName ?? '',
         }));
-        return newStep;
     }
     /**
      * Set the branch key for a graph node step
@@ -506,8 +550,7 @@ export class PikkuWorkflowService {
      * @param branchKey - Branch key selected by graph.branch()
      */
     async setBranchTaken(stepId, branchKey) {
-        await this.setBranchTakenImpl(stepId, branchKey);
-        await this.safeMirror(() => this.mirror.setBranchTaken(stepId, branchKey));
+        await this.mirrored(() => this.setBranchTakenImpl(stepId, branchKey), (mirror) => mirror.setBranchTaken(stepId, branchKey));
     }
     /**
      * Update a state variable in the workflow run's state
@@ -516,16 +559,13 @@ export class PikkuWorkflowService {
      * @param value - Value to store
      */
     async updateRunState(runId, name, value) {
-        await this.updateRunStateImpl(runId, name, value);
-        await this.safeMirror(() => this.mirror.updateRunState(runId, name, value));
+        await this.mirrored(() => this.updateRunStateImpl(runId, name, value), (mirror) => mirror.updateRunState(runId, name, value));
     }
     async upsertWorkflowVersion(name, graphHash, graph, source, status) {
-        await this.upsertWorkflowVersionImpl(name, graphHash, graph, source, status);
-        await this.safeMirror(() => this.mirror.upsertWorkflowVersion(name, graphHash, graph, source, status));
+        await this.mirrored(() => this.upsertWorkflowVersionImpl(name, graphHash, graph, source, status), (mirror) => mirror.upsertWorkflowVersion(name, graphHash, graph, source, status));
     }
     async updateWorkflowVersionStatus(name, graphHash, status) {
-        await this.updateWorkflowVersionStatusImpl(name, graphHash, status);
-        await this.safeMirror(() => this.mirror.updateWorkflowVersionStatus(name, graphHash, status));
+        await this.mirrored(() => this.updateWorkflowVersionStatusImpl(name, graphHash, status), (mirror) => mirror.updateWorkflowVersionStatus(name, graphHash, status));
     }
     // ============================================================================
     // Workflow Lifecycle Methods
@@ -574,7 +614,7 @@ export class PikkuWorkflowService {
     }
     async queueStepWorker(runId, stepName, rpcName, data, stepOptions, fromStepName) {
         const queueService = this.verifyQueueService();
-        await queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), {
+        await queueService.add(this.getStepWorkerQueueName(rpcName), { runId, stepName, rpcName, data, fromStepName }, {
             ...this.resolveStepJobOptions(stepOptions),
             // Group by step function, mirroring how per-step queues split them —
             // one slow step function can't monopolise the shared step worker.
@@ -638,7 +678,7 @@ export class PikkuWorkflowService {
             throw new Error(`Workflow step '${stepName}' (function '${rpcName}') is marked 'workflowQueued: true' but no queue service is configured.`);
         }
         try {
-            await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), {
+            await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), { runId, stepName, rpcName, data, fromStepName }, {
                 ...this.resolveStepJobOptions(stepOptions),
                 group: this.getJobGroup(rpcName),
             });
@@ -669,58 +709,44 @@ export class PikkuWorkflowService {
         await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, { runId, stepId });
         return true;
     }
-    /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
-    async resolveScenarioActors() {
-        const services = getSingletonServices();
-        const variables = services?.variables;
-        const metaService = services?.metaService;
-        if (!variables || !metaService) {
-            return undefined;
-        }
-        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
-        const apiUrl = await variables.get('API_URL');
-        if (!secret || !apiUrl) {
-            services?.logger?.warn('A scenario was started without actors but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without actors.');
-            return undefined;
-        }
-        const actorsConfig = await metaService.getScenarioActorsMeta();
-        if (!actorsConfig || Object.keys(actorsConfig).length === 0) {
-            return undefined;
-        }
-        const signInPath = (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
-            '/api/auth/sign-in/actor';
-        const rpcPath = (await variables.get('SCENARIO_RPC_PATH')) ?? '/rpc';
-        return createHttpScenarioActors({
-            apiUrl,
-            secret,
-            actors: actorsConfig,
-            signInPath,
-            rpcPath,
-        });
+    /**
+     * Install the one extension a run may have, built from a handle onto the run
+     * engine so that `inlineStep` and friends stay protected rather than becoming
+     * public API. Returns the extension, so the caller keeps a typed reference to
+     * whatever it just built.
+     */
+    setRunExtension(create) {
+        const engine = {
+            inlineStep: this.inlineStep.bind(this),
+            updateRunStatus: this.updateRunStatus.bind(this),
+            onChildWorkflowFailed: this.onChildWorkflowFailed.bind(this),
+            verifyStepName: this.verifyStepName.bind(this),
+        };
+        const extension = create(engine);
+        this.runExtension = extension;
+        return extension;
+    }
+    getRunExtension() {
+        return this.runExtension;
     }
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
      * @param options.inline - If true, execute workflow directly without queue service
      * @param options.startNode - Starting node ID for graph workflows (from wire config)
+     * @param options.onRunCreated - Called with the run id the moment the run exists.
+     * An inline run that fails throws instead of returning, so this is the only
+     * way a caller can still read that run back — its steps, and which one failed.
      */
     async startWorkflow(name, input, wire, rpcService, options) {
-        // Resolve workflow from static meta (root or addon namespace), then dynamic DB
+        // Resolve workflow from static meta (root or addon namespace)
         const resolved = resolveWorkflowMeta(name);
-        let workflowMeta = resolved?.meta;
+        const workflowMeta = resolved?.meta;
         const packageName = resolved?.packageName ?? null;
-        if (!workflowMeta) {
-            const dynamicWorkflows = await this.getAIGeneratedWorkflows();
-            const match = dynamicWorkflows.find((w) => w.workflowName === name);
-            if (match?.graph) {
-                workflowMeta = match.graph;
-            }
-        }
         if (!workflowMeta) {
             throw new WorkflowNotFoundError(name);
         }
-        if (workflowMeta.source === 'graph' ||
-            workflowMeta.source === 'dynamic-workflow') {
+        if (workflowMeta.source === 'graph') {
             const shouldInline = options?.inline || !getSingletonServices()?.queueService;
             return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire, workflowMeta);
         }
@@ -738,15 +764,10 @@ export class PikkuWorkflowService {
             deterministic: workflowMeta.deterministic,
             plannedSteps: workflowMeta.plannedSteps,
         });
-        const actors = options?.actors ??
-            (workflowMeta.source === 'scenario'
-                ? await this.resolveScenarioActors()
-                : undefined);
-        if (actors) {
-            this.runActors.set(runId, actors);
-        }
+        options?.onRunCreated?.(runId);
+        await this.runExtension?.attachRunContext(runId, workflowMeta, options);
         if (shouldInline) {
-            this.inlineRuns.add(runId);
+            this.registerInlineRun(runId);
             try {
                 await this.runWorkflowJob(runId, rpcService);
             }
@@ -776,8 +797,8 @@ export class PikkuWorkflowService {
                 }
             }
             finally {
-                this.inlineRuns.delete(runId);
-                this.runActors.delete(runId);
+                this.unregisterInlineRun(runId);
+                this.runExtension?.detachRunContext(runId);
             }
         }
         else {
@@ -786,37 +807,143 @@ export class PikkuWorkflowService {
         return { runId };
     }
     async runToCompletion(name, input, rpcService, options) {
-        const pollInterval = options?.pollIntervalMs ?? 1000;
         const { runId } = await this.startWorkflow(name, input, options?.wire ?? { type: 'internal' }, rpcService, { inline: true });
+        const run = await this.awaitRunEnd(runId, options?.pollIntervalMs ?? 1000);
+        if (run.status === 'failed') {
+            throw new WorkflowRunFailedError(run.error?.message);
+        }
+        if (run.status === 'cancelled') {
+            throw new WorkflowRunCancelledError();
+        }
+        return run.output;
+    }
+    /**
+     * Read a run until it reaches an end state, backing off as it drags on.
+     *
+     * A fixed interval is wrong at both ends: it makes a workflow that finished
+     * in milliseconds wait out the whole interval anyway, and it keeps reading a
+     * long-running one at full rate for as long as it lasts. Starting short and
+     * growing to `maxIntervalMs` returns quick runs promptly while a slow run's
+     * read cost grows logarithmically rather than linearly with its duration.
+     */
+    async awaitRunEnd(runId, maxIntervalMs) {
+        let interval = Math.min(WORKFLOW_POLL_MIN_MS, maxIntervalMs);
         while (true) {
             const run = await this.getRun(runId);
             if (!run) {
                 throw new WorkflowRunNotFoundError(runId);
             }
             if (WORKFLOW_END_STATES.has(run.status)) {
-                if (run.status === 'failed') {
-                    throw new WorkflowRunFailedError(run.error?.message);
-                }
-                if (run.status === 'cancelled') {
-                    throw new WorkflowRunCancelledError();
-                }
-                return run.output;
+                return run;
             }
-            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+            await this.waitBeforeNextRead(interval);
+            interval = Math.min(interval * WORKFLOW_POLL_FACTOR, maxIntervalMs);
         }
     }
-    // Per-run, per-replay ordinal counters (runId → stepName → count).
-    stepOrdinals = new Map();
-    // Previous step key reached in the current DSL walk (runId → stepName), so a
-    // new step records where it came from. Rebuilt each replay alongside ordinals.
-    stepLineage = new Map();
-    resetStepOrdinals(runId) {
-        this.stepOrdinals.set(runId, new Map());
-        this.stepLineage.delete(runId);
+    /**
+     * Wait between two reads of a run.
+     *
+     * Its own method so the backoff schedule can be asserted on directly. Timing
+     * a poll loop by the clock measures the host's scheduler as much as the
+     * policy — `setTimeout(40)` routinely returns late on a loaded runner — which
+     * makes the obvious test both slow and flaky.
+     */
+    async waitBeforeNextRead(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Every step of a run in one read, or `null` if this backend has no bulk read.
+     *
+     * A replay walks the DSL body from the top, and each step it passes asks for
+     * its own row — so a run of N steps costs N reads per replay and O(N^2) over
+     * its lifetime. Backends that can answer this in a single query collapse that
+     * to one read per replay.
+     */
+    async listStepStates(_runId) {
+        return null;
+    }
+    /**
+     * Begin a replay pass: fresh ordinal counters, and one read of the steps the
+     * run has already taken so the walk back to where it left off is served from
+     * memory. Safe because a pass reaches each step key at most once, and the
+     * steps it replays past are `succeeded` and therefore immutable.
+     */
+    async beginReplay(runId) {
+        const context = this.contextFor(runId);
+        context.replay = { ordinals: new Map() };
+        const steps = await this.listStepStates(runId);
+        if (steps) {
+            context.replay.steps = new Map(steps.map((step) => [step.stepName, step]));
+        }
+    }
+    endReplay(runId) {
+        const context = this.runContexts.get(runId);
+        if (!context)
+            return;
+        context.replay = undefined;
+        this.releaseContext(runId);
+    }
+    /**
+     * The step row for `stepName`, creating it if the run has not reached it
+     * before. Served from the replay snapshot when one is loaded.
+     */
+    async loadOrCreateStep(runId, stepName, create) {
+        const snapshot = this.runContexts.get(runId)?.replay?.steps;
+        if (snapshot) {
+            const cached = snapshot.get(stepName);
+            if (cached) {
+                return cached;
+            }
+        }
+        else {
+            try {
+                return await this.getStepState(runId, stepName);
+            }
+            catch {
+                // No row yet — fall through and create it.
+            }
+        }
+        let step;
+        try {
+            step = await create();
+        }
+        catch (error) {
+            // A concurrent replay of this run created the row after the snapshot was
+            // taken. Its state is the truth; if it isn't really there, the insert
+            // failed for its own reasons and that error is the one worth seeing.
+            try {
+                step = await this.getStepState(runId, stepName);
+            }
+            catch {
+                throw error;
+            }
+        }
+        snapshot?.set(stepName, step);
+        return step;
+    }
+    /**
+     * The run's immutable half — which workflow it is, the wire it was started
+     * on, its input. `getRun` is otherwise called several times per step for
+     * answers that were all fixed at creation, so a replay reads it once and
+     * hands the same object to everyone who only needs that half.
+     *
+     * Anyone who needs `status`, `output`, `error` or `state` must call `getRun`:
+     * those move while the run executes, and a cached copy would be a lie.
+     */
+    async getRunIdentity(runId) {
+        const replay = this.runContexts.get(runId)?.replay;
+        if (replay?.run) {
+            return replay.run;
+        }
+        const run = await this.getRun(runId);
+        if (run && replay) {
+            replay.run = run;
+        }
+        return run;
     }
     /** The step the DSL walk last reached (the predecessor for the next step). */
     lastStepName(runId) {
-        return this.stepLineage.get(runId);
+        return this.runContexts.get(runId)?.replay?.lastStep;
     }
     /**
      * Physical, replay-stable key for the Nth reach of `logicalStepName` in a run:
@@ -825,29 +952,31 @@ export class PikkuWorkflowService {
      * the rows clobbering. Deterministic given a deterministic DSL body.
      */
     nextStepKey(runId, logicalStepName) {
-        let perRun = this.stepOrdinals.get(runId);
-        if (!perRun) {
-            perRun = new Map();
-            this.stepOrdinals.set(runId, perRun);
-        }
-        const ordinal = perRun.get(logicalStepName) ?? 0;
-        perRun.set(logicalStepName, ordinal + 1);
+        const context = this.contextFor(runId);
+        const replay = (context.replay ??= {
+            ordinals: new Map(),
+        });
+        const ordinal = replay.ordinals.get(logicalStepName) ?? 0;
+        replay.ordinals.set(logicalStepName, ordinal + 1);
         const stepName = ordinal === 0 ? logicalStepName : `${logicalStepName}#${ordinal}`;
-        this.stepLineage.set(runId, stepName);
+        replay.lastStep = stepName;
         return stepName;
     }
     async runWorkflowJob(runId, rpcService) {
-        // Fresh ordinal counters per replay so step keys are deterministic.
-        this.resetStepOrdinals(runId);
+        // Fresh ordinal counters per replay so step keys are deterministic, and one
+        // read of the steps the run has already taken.
+        await this.beginReplay(runId);
         try {
             await this.runWorkflowJobInner(runId, rpcService);
         }
         finally {
-            this.stepOrdinals.delete(runId);
+            this.endReplay(runId);
         }
     }
     async runWorkflowJobInner(runId, rpcService) {
-        const run = await this.getRun(runId);
+        // Caches the run for the rest of this replay, so the steps it walks don't
+        // each re-read the workflow name and wire it already has.
+        const run = await this.getRunIdentity(runId);
         if (!run) {
             throw new WorkflowRunNotFoundError(runId);
         }
@@ -860,8 +989,7 @@ export class PikkuWorkflowService {
             await this.runVersionMismatchFallback(run, workflowMeta, rpcService);
             return;
         }
-        if (workflowMeta?.source === 'graph' ||
-            workflowMeta?.source === 'dynamic-workflow') {
+        if (workflowMeta?.source === 'graph') {
             await continueGraph(this, runId, run.workflow);
             const updatedRun = await this.getRun(runId);
             if (updatedRun?.status === 'completed') {
@@ -873,22 +1001,6 @@ export class PikkuWorkflowService {
             }
             return;
         }
-        if (!workflowMeta) {
-            const dynamicWorkflows = await this.getAIGeneratedWorkflows();
-            const match = dynamicWorkflows.find((w) => w.workflowName === run.workflow);
-            if (match?.graph) {
-                await continueGraph(this, runId, run.workflow, match.graph);
-                const updatedRun = await this.getRun(runId);
-                if (updatedRun?.status === 'completed') {
-                    await this.onChildWorkflowCompleted(updatedRun, updatedRun.output);
-                }
-                else if (updatedRun?.status === 'failed' ||
-                    updatedRun?.status === 'cancelled') {
-                    await this.onChildWorkflowFailed(updatedRun, new Error(updatedRun.error?.message || 'Child workflow failed'));
-                }
-                return;
-            }
-        }
         const registrations = pikkuState(pkgName, 'workflows', 'registrations');
         const workflow = registrations.get(resolved?.resolvedName ?? run.workflow);
         if (!workflow) {
@@ -902,14 +1014,30 @@ export class PikkuWorkflowService {
             workflowWire.pikkuUserId = run.wire?.pikkuUserId;
             const wire = {
                 workflow: workflowWire,
-                scenario: workflowMeta?.source === 'scenario' ? workflowWire : undefined,
                 pikkuUserId: run.wire?.pikkuUserId,
                 session: rpcService?.wire?.session,
                 rpc: rpcService?.wire?.rpc,
-                // User-flow actors registered for this run (see startWorkflow options)
-                actors: this.runActors.get(runId),
             };
+            this.runExtension?.decorateRunWire(wire, {
+                runId,
+                workflowMeta,
+                workflowWire,
+            });
+            const lifecycle = {
+                runId,
+                run,
+                workflowMeta,
+                workflow,
+                wire,
+                packageName: pkgName,
+            };
+            // `interrupted` means the run has not reached a terminal state — it is
+            // suspended or waiting — so teardown would run while the run is still
+            // mid-flight.
+            let outcome = 'completed';
+            let failure;
             try {
+                await this.runExtension?.onBeforeRunFunc(lifecycle);
                 const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
                     singletonServices: getSingletonServices(),
                     wire,
@@ -921,10 +1049,13 @@ export class PikkuWorkflowService {
                 await this.onChildWorkflowCompleted(run, result);
             }
             catch (error) {
+                failure = error;
                 if (error instanceof WorkflowAsyncException) {
+                    outcome = 'interrupted';
                     throw error;
                 }
                 if (error instanceof WorkflowCancelledException) {
+                    outcome = 'failed';
                     await this.updateRunStatus(runId, 'cancelled', undefined, {
                         message: error.message || 'Workflow cancelled',
                         stack: '',
@@ -934,6 +1065,7 @@ export class PikkuWorkflowService {
                     throw error;
                 }
                 if (error instanceof WorkflowSuspendedException) {
+                    outcome = 'interrupted';
                     await this.updateRunStatus(runId, 'suspended', undefined, {
                         message: error.message || 'Workflow suspended',
                         stack: '',
@@ -941,6 +1073,7 @@ export class PikkuWorkflowService {
                     });
                     throw error;
                 }
+                outcome = 'failed';
                 await this.updateRunStatus(runId, 'failed', undefined, {
                     message: error.message,
                     stack: error.stack,
@@ -949,6 +1082,9 @@ export class PikkuWorkflowService {
                 await this.onChildWorkflowFailed(run, error);
                 throw error;
             }
+            finally {
+                await this.runExtension?.onAfterRunFunc(lifecycle, outcome, failure);
+            }
         });
     }
     async onChildWorkflowCompleted(childRun, result) {
@@ -1027,8 +1163,7 @@ export class PikkuWorkflowService {
             }
             const meta = pikkuState(null, 'workflows', 'meta');
             const workflowMeta = meta[run.workflow];
-            const isGraphWorkflow = workflowMeta?.source === 'graph' ||
-                workflowMeta?.source === 'dynamic-workflow';
+            const isGraphWorkflow = workflowMeta?.source === 'graph';
             // Map the physical step key back to its logical node: a revisit instance
             // is `node#N` (ordinal), which isn't a literal key in `nodes`.
             let graphNodeId;
@@ -1075,7 +1210,7 @@ export class PikkuWorkflowService {
                     }
                 }
                 else {
-                    result = await this.invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService);
+                    result = await this.invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService, run);
                 }
             }
             // Store result and mark succeeded
@@ -1149,10 +1284,10 @@ export class PikkuWorkflowService {
      * Identical for the queue executor and the inline executor — the only thing
      * that differs between transports is who calls it, not the call itself.
      */
-    async invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService) {
+    async invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService, knownRun) {
         // Carry the run's pikkuUserId onto the step wire so authed steps rehydrate their
         // session on the queued path too (the bare job wire lacks it; inline already has it).
-        const run = await this.getRun(runId);
+        const run = knownRun ?? (await this.getRunIdentity(runId));
         return rpcService.rpcWithWire(rpcName, data, {
             ...(run?.wire?.pikkuUserId ? { pikkuUserId: run.wire.pikkuUserId } : {}),
             workflowStep: {
@@ -1229,15 +1364,8 @@ export class PikkuWorkflowService {
             actor: stepOptions?.actor,
             onError: stepOptions?.onError,
         };
-        // Check if step already exists
-        let stepState;
-        try {
-            stepState = await this.getStepState(runId, stepName);
-        }
-        catch {
-            // Step doesn't exist - create it
-            stepState = await this.insertStepState(runId, stepName, rpcName, data, resolvedStepOptions, fromStepName);
-        }
+        // Reuse the step if the run already reached it, otherwise create it.
+        const stepState = await this.loadOrCreateStep(runId, stepName, () => this.insertStepState(runId, stepName, rpcName, data, resolvedStepOptions, fromStepName));
         if (stepState.status === 'succeeded') {
             // Return cached result
             return stepState.result;
@@ -1300,22 +1428,14 @@ export class PikkuWorkflowService {
                 const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: true });
                 await this.setStepChildRunId(currentStepState.stepId, childRunId);
                 // Poll until child workflow completes
-                while (true) {
-                    const childRun = await this.getRun(childRunId);
-                    if (!childRun) {
-                        throw new WorkflowRunNotFoundError(childRunId);
-                    }
-                    if (WORKFLOW_END_STATES.has(childRun.status)) {
-                        if (childRun.status === 'failed') {
-                            throw new Error(childRun.error?.message || 'Sub-workflow failed');
-                        }
-                        if (childRun.status === 'cancelled') {
-                            throw new Error('Sub-workflow was cancelled');
-                        }
-                        return childRun.output;
-                    }
-                    await new Promise((resolve) => setTimeout(resolve, 500));
+                const childRun = await this.awaitRunEnd(childRunId, WORKFLOW_CHILD_POLL_MAX_MS);
+                if (childRun.status === 'failed') {
+                    throw new Error(childRun.error?.message || 'Sub-workflow failed');
+                }
+                if (childRun.status === 'cancelled') {
+                    throw new Error('Sub-workflow was cancelled');
                 }
+                return childRun.output;
             }
             return this.invokeStepRpc(runId, stepName, currentStepState, rpcName, data, rpcService);
         }, async (error) => {
@@ -1328,18 +1448,26 @@ export class PikkuWorkflowService {
             }
         });
     }
-    async inlineStep(runId, logicalStepName, fn, stepOptions) {
+    async inlineStep(runId, logicalStepName, fn, stepOptions, 
+    /**
+     * The input this step was called with, recorded on the run so a reporter can
+     * name the values under test. A closure step has none; a scenario step does.
+     */
+    data = null, 
+    /**
+     * The name this step was dispatched by, for the kinds of inline step that
+     * have one. A closure step has no name; a scenario step is a step RPC, so
+     * it records the step function that ran — which is the only way to join a
+     * step back to its declaration when its durable name was built at runtime
+     * (a step called in a loop reaches the run as `sees @pikku/addon-todos`,
+     * declared as `sees ${packageName}`).
+     */
+    rpcName = null) {
         const fromStepName = this.lastStepName(runId);
         const stepName = this.nextStepKey(runId, logicalStepName);
-        // Check if step already exists
-        let stepState;
-        try {
-            stepState = await this.getStepState(runId, stepName);
-        }
-        catch {
-            // Step doesn't exist - create it (inline, no RPC)
-            stepState = await this.insertStepState(runId, stepName, null, null, stepOptions, fromStepName);
-        }
+        // Reuse the step if the run already reached it, otherwise create it
+        // (inline, so never dispatched).
+        const stepState = await this.loadOrCreateStep(runId, stepName, () => this.insertStepState(runId, stepName, rpcName, data, stepOptions, fromStepName));
         if (stepState.status === 'succeeded') {
             // Return cached result
             return stepState.result;
@@ -1381,15 +1509,9 @@ export class PikkuWorkflowService {
     async sleepStep(runId, logicalStepName, duration) {
         const fromStepName = this.lastStepName(runId);
         const stepName = this.nextStepKey(runId, logicalStepName);
-        // Check if step already exists
-        let stepState;
-        try {
-            stepState = await this.getStepState(runId, stepName);
-        }
-        catch {
-            // Step doesn't exist - create it (sleep step, no RPC)
-            stepState = await this.insertStepState(runId, stepName, null, { duration }, undefined, fromStepName);
-        }
+        // Reuse the step if the run already reached it, otherwise create it
+        // (sleep step, no RPC).
+        const stepState = await this.loadOrCreateStep(runId, stepName, () => this.insertStepState(runId, stepName, null, { duration }, undefined, fromStepName));
         if (stepState.status === 'succeeded') {
             // Sleep already completed, return immediately
             return;
@@ -1635,90 +1757,6 @@ export class PikkuWorkflowService {
                     return await this.inlineStep(runId, stepName, rpcNameOrFn, dataOrOptions);
                 }
             },
-            // Durable polling step: invoke an RPC (as an actor when options.as is
-            // set) until the predicate passes or `within` elapses. The whole poll is
-            // ONE recorded step, so replay returns the cached outcome.
-            expectEventually: async (stepName, rpcName, data, predicate, options) => {
-                this.verifyStepName(stepName);
-                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
-                    ? `${addonNamespace}:${rpcName}`
-                    : rpcName;
-                const within = getDurationInMilliseconds(options?.within ?? '30s');
-                const interval = getDurationInMilliseconds(options?.interval ?? '1s');
-                return await this.inlineStep(runId, stepName, async () => {
-                    const deadline = Date.now() + within;
-                    let last;
-                    while (true) {
-                        last = options?.actor
-                            ? await options.actor.invoke(resolvedRpcName, data)
-                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
-                        if (predicate(last))
-                            return last;
-                        if (Date.now() + interval > deadline) {
-                            throw new Error(`[workflow] expectEventually '${stepName}' ('${resolvedRpcName}'` +
-                                `${options?.actor ? ` as '${options.actor.name}'` : ''}) did not pass within ${within}ms; ` +
-                                `last result: ${JSON.stringify(last)?.slice(0, 300)}`);
-                        }
-                        await new Promise((resolve) => setTimeout(resolve, interval));
-                    }
-                }, options);
-            },
-            expectError: async (stepName, rpcName, data, options) => {
-                this.verifyStepName(stepName);
-                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
-                    ? `${addonNamespace}:${rpcName}`
-                    : rpcName;
-                return await this.inlineStep(runId, stepName, async () => {
-                    let result;
-                    try {
-                        result = options?.actor
-                            ? await options.actor.invoke(resolvedRpcName, data)
-                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
-                    }
-                    catch (e) {
-                        const message = e?.message ?? String(e);
-                        if (options?.matches) {
-                            const matched = typeof options.matches === 'string'
-                                ? message.includes(options.matches)
-                                : options.matches.test(message);
-                            if (!matched) {
-                                throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') threw, but the message did not match ${options.matches}: ${message}`);
-                            }
-                        }
-                        return message;
-                    }
-                    throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`);
-                }, options);
-            },
-            expectService: async (stepName, serviceMethod, options) => {
-                this.verifyStepName(stepName);
-                const [service, method] = serviceMethod.split('.');
-                if (!service || !method) {
-                    throw new Error(`[workflow] expectService '${stepName}' needs 'service.method', got '${serviceMethod}'`);
-                }
-                await this.inlineStep(runId, stepName, async () => {
-                    const rpcName = 'pikkuScenarioGetStubCalls';
-                    const calls = options?.actor
-                        ? await options.actor.invoke(rpcName, { service })
-                        : await rpcService.rpcWithWire(rpcName, { service }, {});
-                    const matching = (calls ?? []).filter((c) => c.service === service &&
-                        c.method === method &&
-                        (options?.calledWith === undefined ||
-                            JSON.stringify(c.args?.[0]) ===
-                                JSON.stringify(options.calledWith)));
-                    const expected = options?.times;
-                    const ok = expected === undefined
-                        ? matching.length > 0
-                        : matching.length === expected;
-                    if (!ok) {
-                        const seen = (calls ?? [])
-                            .map((c) => `${c.service}.${c.method}(${JSON.stringify(c.args?.[0])?.slice(0, 120) ?? ''})`)
-                            .join('\n  ') || '(none)';
-                        throw new Error(`[workflow] expectService '${stepName}' expected ${expected ?? 'at least one'} call(s) to '${serviceMethod}'` +
-                            `${options?.calledWith !== undefined ? ` with ${JSON.stringify(options.calledWith)}` : ''}, found ${matching.length}. Recorded:\n  ${seen}`);
-                    }
-                }, options);
-            },
             // Implement workflow.sleep()
             sleep: async (stepName, duration) => {
                 this.verifyStepName(stepName);
@@ -1732,10 +1770,13 @@ export class PikkuWorkflowService {
                 this.verifyStepName(reason);
                 return await this.approvalStep(runId, reason, options);
             }),
-            runScheduledTask: async (taskName) => {
-                await runScheduledTask({ name: taskName });
-            },
         };
+        this.runExtension?.decorateWorkflowWire(workflowWire, {
+            name,
+            runId,
+            rpcService,
+            addonNamespace,
+        });
         return workflowWire;
     }
     verifyStepName(stepName) {