@pikku/core 0.12.72 → 0.12.77

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

@@ -34,17 +34,7 @@ import { RPCNotFoundError } from '../rpc/rpc-runner.js';
 import { ChildWorkflowStartedException } from './graph/graph-runner.js';
 import { deriveInvocationId } from './workflow-invocation-id.js';
 import { buildRunTimeline, reconstructStateAt, } from './run-timeline.js';
-/**
- * Default number of retries for a workflow step when none is specified. The
- * workflow — not the queue — owns retry policy; a step inherits this unless it
- * sets its own `retries` (including `retries: 0` to opt out entirely). Picked >0
- * so a transient failure (a DB blip, a downstream restart, a deploy) is ridden
- * out by default; safe because every step gets a stable `invocationId` to dedupe on.
- */
 export const DEFAULT_STEP_RETRIES = 5;
-/**
- * Exception thrown when workflow needs to pause for async step
- */
 export class WorkflowAsyncException extends Error {
     runId;
     stepName;
@@ -55,9 +45,6 @@ export class WorkflowAsyncException extends Error {
         this.name = 'WorkflowAsyncException';
     }
 }
-/**
- * Exception thrown when workflow is cancelled
- */
 export class WorkflowCancelledException extends Error {
     runId;
     reason;
@@ -68,9 +55,6 @@ export class WorkflowCancelledException extends Error {
         this.name = 'WorkflowCancelledException';
     }
 }
-/**
- * Exception thrown when workflow is suspended
- */
 export class WorkflowSuspendedException extends Error {
     runId;
     reason;
@@ -81,14 +65,6 @@ export class WorkflowSuspendedException extends Error {
         this.name = 'WorkflowSuspendedException';
     }
 }
-/**
- * Thrown when a step (or the orchestrator) could not be enqueued — the queue
- * itself failed (e.g. pg-boss is momentarily down), NOT the step's own logic.
- * This is transient infrastructure failure: the run is left untouched (the step
- * stays `pending`, the run stays running) and the orchestrator job is rethrown
- * so the queue redelivers it and the workflow replays from its snapshot. Treat
- * it as non-terminal — never mark the run `failed` for it.
- */
 export class WorkflowDispatchException extends Error {
     runId;
     stepName;
@@ -99,9 +75,6 @@ export class WorkflowDispatchException extends Error {
         this.name = 'WorkflowDispatchException';
     }
 }
-/**
- * Error class for workflow not found
- */
 export class WorkflowNotFoundError extends PikkuError {
     constructor(name) {
         super(`Workflow not found: ${name}`);
@@ -140,12 +113,6 @@ addError(WorkflowRunCancelledError, {
     status: 409,
     message: 'Workflow was cancelled.',
 });
-/**
- * A decision arrived for an approval gate that has already resolved. The gate
- * caches its outcome as the step result and never re-reads run state, so the
- * decision could not take effect — it is rejected rather than accepted and
- * dropped.
- */
 export class WorkflowApprovalResolvedError extends PikkuError {
     payload;
     constructor(reason, outcome) {
@@ -170,25 +137,13 @@ const WORKFLOW_END_STATES = new Set([
     'cancelled',
     'suspended',
 ]);
-/**
- * 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 {
     runExtension;
@@ -196,20 +151,38 @@ export class PikkuWorkflowService {
     contextFor(runId) {
         let context = this.runContexts.get(runId);
         if (!context) {
-            context = { inline: false };
+            context = { activeExecutions: 0, ordinals: new Map() };
             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)
+        if (context.activeExecutions > 0)
             return;
         this.runContexts.delete(runId);
     }
+    enterExecution(runId) {
+        const context = this.contextFor(runId);
+        context.activeExecutions++;
+        return context;
+    }
+    exitExecution(runId) {
+        const context = this.runContexts.get(runId);
+        if (!context)
+            return;
+        if (context.activeExecutions > 0) {
+            context.activeExecutions--;
+        }
+        if (context.activeExecutions === 0) {
+            context.replay = undefined;
+            context.ordinals = new Map();
+            context.lastStep = undefined;
+        }
+        this.releaseContext(runId);
+    }
     get logger() {
         return getSingletonServices()?.logger;
     }
@@ -227,17 +200,6 @@ export class PikkuWorkflowService {
             this.wireQueueWorkers();
         }
     }
-    /**
-     * 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) {
@@ -249,22 +211,15 @@ export class PikkuWorkflowService {
                     this.logger?.warn?.(`[pikku] WorkflowRunMirror write failed: ${err?.message ?? err}`);
                 }
                 catch {
-                    // logger unavailable (e.g. singleton services not initialized) — swallow
+                    // knowledge: decisions/internals/workflow-run-mirror-is-never-a-source-of-truth.md
                 }
             }
         }
         return written;
     }
-    /**
-     * Wire the queue-based orchestrator/step/sleeper workers.
-     * Subclasses that orchestrate without queues (e.g. Durable Objects) should
-     * pass `wireQueues: false` to the base constructor and skip this entirely.
-     * Call this explicitly after adding addons dynamically.
-     */
     wireQueueWorkers() {
         const functions = pikkuState(null, 'function', 'functions');
         const functionsMeta = pikkuState(null, 'function', 'meta');
-        // Minimal meta for internal workflow functions (satisfies FunctionMeta)
         const mkMeta = (funcId) => ({
             pikkuFuncId: funcId,
             sessionless: true,
@@ -285,10 +240,6 @@ export class PikkuWorkflowService {
                 functionsMeta[funcId] = mkMeta(funcId);
             }
         };
-        // Under 'shared-groups' every workflow runs through these two queues and is
-        // kept from hogging them by the per-group cap, so the per-workflow queues
-        // below are left unconsumed — one set of pollers for the whole system
-        // instead of one per workflow.
         const sharedGroups = this.queueStrategy === 'shared-groups';
         const sharedQueueConfig = sharedGroups
             ? {
@@ -296,10 +247,8 @@ export class PikkuWorkflowService {
                 groupConcurrency: this.queueGroupConcurrency,
             }
             : undefined;
-        // Register shared queue workers for monolith deployments
         registerWorkflowFunc('pikkuWorkflowOrchestrator', { func: pikkuWorkflowOrchestratorFunc }, 'pikku-workflow-orchestrator', sharedQueueConfig);
         registerWorkflowFunc('pikkuWorkflowStepWorker', { func: pikkuWorkflowWorkerFunc }, 'pikku-workflow-step-worker', sharedQueueConfig);
-        // Register per-workflow queue workers (root + addon packages)
         const registerQueueWorkers = (queueMeta) => {
             for (const [queueName, meta] of Object.entries(queueMeta)) {
                 if (functions.has(meta.pikkuFuncId))
@@ -324,13 +273,6 @@ export class PikkuWorkflowService {
                 }
             }
         }
-        // Workflows exist but no per-workflow orchestrator queue was registered:
-        // the generated queue meta never reached the runtime (most often the
-        // bootstrap doesn't import the queue-workers meta, so `queue.meta` is
-        // empty). Everything still "works" — dispatch silently falls back to the
-        // single shared orchestrator queue — but the isolation is gone: one slow
-        // workflow step head-of-line-blocks every other workflow behind it. That
-        // is invisible until a queue starves, so say so loudly at wiring time.
         const workflowCount = Object.keys(pikkuState(null, 'workflows', 'meta') ?? {}).length;
         const perWorkflowQueues = Object.keys(queueMeta).filter((name) => name.startsWith('wf-orchestrator-')).length;
         if (workflowCount > 0 && perWorkflowQueues === 0) {
@@ -347,26 +289,25 @@ export class PikkuWorkflowService {
             functionsMeta.pikkuWorkflowSleeper = mkMeta('pikkuWorkflowSleeper');
         }
     }
-    /**
-     * Check if a run is executing inline (without queues)
-     */
-    isInline(runId) {
-        return this.runContexts.get(runId)?.inline === true;
+    async isInline(runId) {
+        const context = this.runContexts.get(runId);
+        if (context?.inline !== undefined) {
+            return context.inline;
+        }
+        const inline = (await this.getRunIdentity(runId))?.inline === true;
+        if (context) {
+            context.inline = inline;
+        }
+        return inline;
     }
-    /**
-     * Register a run as inline (for graph-runner to use)
-     */
     registerInlineRun(runId) {
         this.contextFor(runId).inline = true;
     }
-    /**
-     * Unregister a run from inline tracking
-     */
     unregisterInlineRun(runId) {
         const context = this.runContexts.get(runId);
         if (!context)
             return;
-        context.inline = false;
+        context.inline = undefined;
         this.releaseContext(runId);
     }
     async registerWorkflowVersions() {
@@ -380,17 +321,12 @@ export class PikkuWorkflowService {
     async createRun(workflowName, input, inline, graphHash, wire, options) {
         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.
-     * Used by the public API — the console addon provides the full verbose view.
-     */
     async getRunStatus(id) {
         const run = await this.getRun(id);
         if (!run)
             return null;
         const history = await this.getRunHistory(id);
         const terminalStatuses = new Set(['completed', 'failed', 'cancelled']);
-        // Build step summaries from history (latest attempt per step)
         const stepMap = new Map();
         for (const step of history) {
             const existing = stepMap.get(step.stepName);
@@ -425,100 +361,40 @@ export class PikkuWorkflowService {
                 : undefined,
         };
     }
-    /**
-     * Build the run's time-travel event stream from durable history.
-     * @param id - Run ID
-     * @returns Ordered timeline, or null if the run doesn't exist
-     */
     async getRunTimeline(id) {
         const run = await this.getRun(id);
         if (!run)
             return null;
         return buildRunTimeline(await this.getRunHistory(id));
     }
-    /**
-     * Reconstruct the run's state at a point in its timeline.
-     * @param id - Run ID
-     * @param at - A seq index (inclusive) or a Date (inclusive); omit for the
-     *             final state.
-     * @returns Reconstructed state, or null if the run doesn't exist
-     */
     async reconstructRunStateAt(id, at) {
         const timeline = await this.getRunTimeline(id);
         if (!timeline)
             return null;
         return reconstructStateAt(timeline, at ?? timeline.length - 1);
     }
-    /**
-     * Update workflow run status
-     * @param id - Run ID
-     * @param status - New status
-     */
     async 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 - 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) {
         return this.mirrored(() => this.insertStepStateImpl(runId, stepName, rpcName, data, stepOptions, fromStepName), (mirror, step) => mirror.insertStepState(runId, { ...step, stepName, rpcName, data }));
     }
-    /**
-     * Mark step as running
-     * Updates both workflow_step and workflow_step_history
-     * @param stepId - Step ID
-     */
     async setStepRunning(stepId) {
         await this.mirrored(() => this.setStepRunningImpl(stepId), (mirror) => mirror.setStepRunning(stepId));
     }
-    /**
-     * Mark step as scheduled (queued for execution)
-     * Updates both workflow_step and workflow_step_history
-     * @param stepId - Step ID
-     */
     async setStepScheduled(stepId) {
         await this.mirrored(() => this.setStepScheduledImpl(stepId), (mirror) => mirror.setStepScheduled(stepId));
     }
-    /**
-     * Store step result and mark as succeeded
-     * Updates both workflow_step and workflow_step_history
-     * @param stepId - Step ID
-     * @param result - Step result
-     */
     async setStepResult(stepId, result) {
         await this.mirrored(() => this.setStepResultImpl(stepId, result), (mirror) => mirror.setStepResult(stepId, result));
     }
-    /**
-     * Set the child workflow run ID on a step
-     * @param stepId - Step ID
-     * @param childRunId - Child workflow run ID
-     */
     async setStepChildRunId(stepId, childRunId) {
         await this.mirrored(() => this.setStepChildRunIdImpl(stepId, childRunId), (mirror) => mirror.setStepChildRunId(stepId, childRunId));
     }
-    /**
-     * Store step error and mark as failed
-     * Updates both workflow_step and workflow_step_history
-     * @param stepId - Step ID
-     * @param error - Error object
-     */
     async setStepError(stepId, error) {
         await this.mirrored(() => this.setStepErrorImpl(stepId, error), (mirror) => {
             const serialized = {
@@ -530,34 +406,15 @@ export class PikkuWorkflowService {
             return mirror.setStepError(stepId, serialized);
         });
     }
-    /**
-     * Create a new retry attempt for a failed step
-     * Inserts new pending step in both workflow_step and workflow_step_history
-     * Resets status to 'pending' with new stepId
-     * Copies metadata (rpcName, data, retries, retryDelay) from failed attempt
-     * @param failedStepId - Failed step ID to copy from
-     * @returns New step state for the retry attempt
-     */
     async createRetryAttempt(failedStepId, status) {
         return this.mirrored(() => this.createRetryAttemptImpl(failedStepId, status), (mirror, newStep) => mirror.createRetryAttempt(failedStepId, {
             ...newStep,
             stepName: newStep.stepName ?? '',
         }));
     }
-    /**
-     * Set the branch key for a graph node step
-     * @param stepId - Step ID
-     * @param branchKey - Branch key selected by graph.branch()
-     */
     async 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
-     * @param runId - Run ID
-     * @param name - Variable name
-     * @param value - Value to store
-     */
     async updateRunState(runId, name, value) {
         await this.mirrored(() => this.updateRunStateImpl(runId, name, value), (mirror) => mirror.updateRunState(runId, name, value));
     }
@@ -567,44 +424,20 @@ export class PikkuWorkflowService {
     async updateWorkflowVersionStatus(name, graphHash, status) {
         await this.mirrored(() => this.updateWorkflowVersionStatusImpl(name, graphHash, status), (mirror) => mirror.updateWorkflowVersionStatus(name, graphHash, status));
     }
-    // ============================================================================
-    // Workflow Lifecycle Methods
-    // ============================================================================
-    /**
-     * Resume a paused workflow by triggering the orchestrator
-     * @param runId - Run ID
-     */
     async resumeWorkflow(runId, workflowName) {
         const queueService = this.verifyQueueService();
         if (!workflowName) {
             const run = await this.getRun(runId);
             workflowName = run?.workflow;
         }
-        // Carry an explicit retry policy on the orchestrator job too. Orchestrator
-        // runs are idempotent (they replay from the snapshot, returning cached step
-        // results), so redelivery is always safe — and it's what lets a transient
-        // dispatch/infra failure recover: the job is rethrown and retried instead of
-        // the run hanging. Passing `attempts` per-job overrides the queue default, so
-        // this holds even when the orchestrator queue is configured `retry_limit 0`.
         await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, {
             ...this.resolveStepJobOptions(),
             group: this.getJobGroup(workflowName),
         });
     }
-    /**
-     * Resolve a step's retry policy into queue job options. The workflow is the
-     * sole source of truth for retries: an explicitly-set `retries` (including 0)
-     * is always honored, an unset one defaults to {@link DEFAULT_STEP_RETRIES},
-     * and we ALWAYS pass `attempts` so the queue can never fall back to its own
-     * default — which would re-run a step the workflow said not to retry. Backoff
-     * defaults to exponential whenever there's at least one retry, so retries ride
-     * out a transient outage instead of firing instantly.
-     */
     resolveStepJobOptions(stepOptions) {
         const retries = stepOptions?.retries ?? DEFAULT_STEP_RETRIES;
         const retryDelay = stepOptions?.retryDelay;
-        // A concrete retryDelay (15000, '15s') is a fixed backoff; only the literal
-        // 'exponential' — or no delay at all — selects exponential.
         const backoff = retryDelay !== undefined && retryDelay !== 'exponential'
             ? { type: 'fixed', delay: getDurationInMilliseconds(retryDelay) }
             : retries > 0 || retryDelay === 'exponential'
@@ -616,25 +449,13 @@ export class PikkuWorkflowService {
         const queueService = this.verifyQueueService();
         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.
             group: this.getJobGroup(rpcName),
         });
     }
-    /**
-     * Execute a workflow sleep step completion
-     * Sets the step result to null and resumes the workflow
-     * @param data - Sleeper input data
-     */
     async executeWorkflowSleepCompleted(runId, stepId) {
         await this.setStepResult(stepId, null);
         await this.resumeWorkflow(runId);
     }
-    /**
-     * Schedule orchestrator retry with delay
-     * @param runId - Run ID
-     * @param retryDelay - Delay in milliseconds or duration string (optional)
-     */
     async scheduleOrchestratorRetry(runId, retryDelay, workflowName) {
         const queueService = this.verifyQueueService();
         if (!workflowName) {
@@ -648,25 +469,7 @@ export class PikkuWorkflowService {
             group: this.getJobGroup(workflowName),
         });
     }
-    /**
-     * Dispatch a workflow step to be executed asynchronously.
-     *
-     * Default implementation enqueues a step worker job via the queue service.
-     * Subclasses with non-queue transports (e.g. Durable Objects) override this
-     * to dispatch via their own mechanism (RPC to a step worker, etc.).
-     *
-     * On return, the workflow is paused via `WorkflowAsyncException` thrown by
-     * the caller; the step transport is responsible for calling back into the
-     * orchestrator (via `resumeWorkflow` or equivalent) when the step completes.
-     *
-     * @returns true if dispatch was async (caller should pause), false to fall
-     *   through to the inline execution path.
-     */
     async dispatchStep(runId, stepName, rpcName, data, stepOptions, fromStepName) {
-        // Step execution is decided purely by the function's `workflowQueued` flag
-        // (default false). Only a function explicitly marked `workflowQueued: true`
-        // dispatches via the queue. If the queue service is not configured that is
-        // a hard error — there is no inline fallback.
         const functionsMeta = pikkuState(null, 'function', 'meta');
         const rpcFuncId = pikkuState(null, 'rpc', 'meta')[rpcName];
         const rpcMeta = typeof rpcFuncId === 'string' ? functionsMeta[rpcFuncId] : undefined;
@@ -684,37 +487,18 @@ export class PikkuWorkflowService {
             });
         }
         catch (cause) {
-            // The queue is down/unreachable — NOT a step failure. Surface it as a
-            // transient dispatch error so the caller leaves the step `pending` and the
-            // orchestrator job is retried (replayed from snapshot) rather than the run
-            // being marked failed. `add` already throws on failure in every adapter.
             throw new WorkflowDispatchException(runId, stepName, { cause });
         }
         return true;
     }
-    /**
-     * Schedule a workflow sleep wakeup at the given duration.
-     *
-     * Default implementation uses the scheduler service to enqueue a delayed
-     * sleeper RPC. Subclasses with native timer primitives (e.g. Durable Object
-     * alarms) override this to schedule directly without going through queues.
-     *
-     * @returns true if the wakeup was scheduled remotely (caller should pause),
-     *   false to fall through to inline `setTimeout` behavior.
-     */
     async scheduleSleep(runId, stepId, duration) {
-        if (this.isInline(runId) || !getSingletonServices()?.schedulerService) {
+        if ((await this.isInline(runId)) ||
+            !getSingletonServices()?.schedulerService) {
             return false;
         }
         await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, { runId, stepId });
         return true;
     }
-    /**
-     * 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),
@@ -729,17 +513,7 @@ export class PikkuWorkflowService {
     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)
         const resolved = resolveWorkflowMeta(name);
         const workflowMeta = resolved?.meta;
         const packageName = resolved?.packageName ?? null;
@@ -750,7 +524,6 @@ export class PikkuWorkflowService {
             const shouldInline = options?.inline || !getSingletonServices()?.queueService;
             return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire, workflowMeta);
         }
-        // DSL workflow - check registration exists
         const registrations = pikkuState(packageName, 'workflows', 'registrations');
         const workflow = registrations.get(resolved?.resolvedName ?? name);
         if (!workflow) {
@@ -775,24 +548,16 @@ export class PikkuWorkflowService {
                 if (error.name !== 'WorkflowAsyncException' &&
                     error.name !== 'WorkflowCancelledException' &&
                     error.name !== 'WorkflowSuspendedException' &&
-                    // Transient queue failure — leave the run resumable, don't fail it.
                     error.name !== 'WorkflowDispatchException') {
                     await this.updateRunStatus(runId, 'failed', undefined, {
                         name: error.name,
                         message: error.message,
                         stack: error.stack,
                     });
-                    // An expected failure (a PikkuError, e.g. a build gate tripping) —
-                    // its message is the whole story, so don't dump the stack. The
-                    // `expected` flag survives the step-boundary rehydration that strips
-                    // the class. Anything else is an uncaught/unexpected error: log it in
-                    // full so the trace is there to debug.
                     getSingletonServices().logger.error(`Workflow ${name} (run ${runId}) failed:`, isExpectedError(error) ? error.message : error);
                     throw error;
                 }
                 if (error.name === 'WorkflowDispatchException') {
-                    // Rethrow so the caller (poll loop / starter) sees the transient
-                    // failure; the run stays running and can be resumed.
                     throw error;
                 }
             }
@@ -817,15 +582,6 @@ export class PikkuWorkflowService {
         }
         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) {
@@ -840,53 +596,25 @@ export class PikkuWorkflowService {
             interval = Math.min(interval * WORKFLOW_POLL_FACTOR, maxIntervalMs);
         }
     }
-    /**
-     * 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 context = this.enterExecution(runId);
+        context.ordinals = new Map();
+        context.lastStep = undefined;
+        context.replay = {};
         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);
+        this.exitExecution(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) {
@@ -900,7 +628,7 @@ export class PikkuWorkflowService {
                 return await this.getStepState(runId, stepName);
             }
             catch {
-                // No row yet — fall through and create it.
+                // knowledge: decisions/internals/workflow-replay-reads-its-steps-once-and-caches-only-the-immutable-half.md
             }
         }
         let step;
@@ -908,9 +636,6 @@ export class PikkuWorkflowService {
             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);
             }
@@ -921,15 +646,6 @@ export class PikkuWorkflowService {
         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) {
@@ -941,30 +657,18 @@ export class PikkuWorkflowService {
         }
         return run;
     }
-    /** The step the DSL walk last reached (the predecessor for the next step). */
     lastStepName(runId) {
-        return this.runContexts.get(runId)?.replay?.lastStep;
-    }
-    /**
-     * Physical, replay-stable key for the Nth reach of `logicalStepName` in a run:
-     * bare name for the first reach (ordinal 0, unchanged behavior), `name#N` for
-     * repeats — so the same literal step name can be invoked multiple times without
-     * the rows clobbering. Deterministic given a deterministic DSL body.
-     */
+        return this.runContexts.get(runId)?.lastStep;
+    }
     nextStepKey(runId, logicalStepName) {
         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 ordinal = context.ordinals.get(logicalStepName) ?? 0;
+        context.ordinals.set(logicalStepName, ordinal + 1);
         const stepName = ordinal === 0 ? logicalStepName : `${logicalStepName}#${ordinal}`;
-        replay.lastStep = stepName;
+        context.lastStep = stepName;
         return stepName;
     }
     async runWorkflowJob(runId, rpcService) {
-        // 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);
@@ -974,8 +678,6 @@ export class PikkuWorkflowService {
         }
     }
     async runWorkflowJobInner(runId, rpcService) {
-        // 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);
@@ -1031,9 +733,6 @@ export class PikkuWorkflowService {
                 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 {
@@ -1124,24 +823,21 @@ export class PikkuWorkflowService {
         }
         await runFromMeta(this, run.id, version.graph, rpcService);
     }
-    /**
-     * Execute a single workflow step (called by worker)
-     * Handles idempotency, RPC execution, result storage, retry logic, and orchestrator triggering
-     */
     async executeWorkflowStep(runId, stepName, rpcName, data, rpcService) {
-        // Claim the step under the lock ONLY (atomic check-and-mark-running). Do NOT
-        // hold the advisory lock — and its pooled connection — across execution: once
-        // a step is 'running' the guard below makes any concurrent worker return
-        // early, so the work + result persistence run with the lock released. Holding
-        // the lock across executeGraphStep (network I/O + more pool queries) let
-        // concurrent steps exhaust the connection pool and self-deadlock.
+        this.enterExecution(runId);
+        try {
+            await this.executeWorkflowStepInner(runId, stepName, rpcName, data, rpcService);
+        }
+        finally {
+            this.exitExecution(runId);
+        }
+    }
+    async executeWorkflowStepInner(runId, stepName, rpcName, data, rpcService) {
         const claimed = await this.withStepLock(runId, stepName, async () => {
             const stepState = await this.getStepState(runId, stepName);
-            // Already succeeded, or already claimed by another worker — nothing to do.
             if (stepState.status === 'succeeded' || stepState.status === 'running') {
                 return null;
             }
-            // A 'failed' status means this is a retry — start a fresh 'running' attempt.
             if (stepState.status === 'failed') {
                 return this.createRetryAttempt(stepState.stepId, 'running');
             }
@@ -1150,7 +846,6 @@ export class PikkuWorkflowService {
             }
             return stepState;
         });
-        // Nothing to execute: already succeeded, or another worker owns this step.
         if (!claimed) {
             return;
         }
@@ -1164,8 +859,6 @@ export class PikkuWorkflowService {
             const meta = pikkuState(null, 'workflows', 'meta');
             const workflowMeta = meta[run.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;
             if (isGraphWorkflow && workflowMeta?.nodes) {
                 if (stepName in workflowMeta.nodes) {
@@ -1182,7 +875,6 @@ export class PikkuWorkflowService {
                 result = await executeGraphStep(this, rpcService, runId, stepState.stepId, graphNodeId, rpcName, data, run.workflow);
             }
             else {
-                // Check if rpcName refers to a sub-workflow
                 const subWorkflowMeta = meta[rpcName];
                 if (subWorkflowMeta) {
                     const childWire = {
@@ -1213,9 +905,7 @@ export class PikkuWorkflowService {
                     result = await this.invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService, run);
                 }
             }
-            // Store result and mark succeeded
             await this.setStepResult(stepState.stepId, result);
-            // Resume orchestrator to continue workflow
             await this.resumeWorkflow(runId);
         }
         catch (error) {
@@ -1231,25 +921,17 @@ export class PikkuWorkflowService {
                 });
                 return;
             }
-            // Store error and mark failed
             await this.setStepError(stepState.stepId, error);
             const maxAttempts = (stepState.retries ?? DEFAULT_STEP_RETRIES) + 1;
             const retriesExhausted = stepState.attemptCount >= maxAttempts;
             if (retriesExhausted) {
-                // No more retries - resume orchestrator to mark workflow as failed
                 await this.resumeWorkflow(runId);
             }
-            // Always throw so queue knows the job failed and can retry if needed
             throw error;
         }
     }
-    /**
-     * Orchestrate workflow execution (called by orchestrator)
-     * Runs workflow job and handles async exceptions
-     */
     async orchestrateWorkflow(runId, rpcService) {
         try {
-            // Run workflow job (replays with caching)
             await this.runWorkflowJob(runId, rpcService);
         }
         catch (error) {
@@ -1259,9 +941,6 @@ export class PikkuWorkflowService {
                 return;
             }
             if (error.name === 'WorkflowDispatchException') {
-                // Transient: the queue was unreachable, not a workflow failure. Leave the
-                // run running and rethrow so the orchestrator job is redelivered and the
-                // workflow replays from its snapshot. Do NOT mark the run failed.
                 getSingletonServices().logger.warn(`Workflow run ${runId} could not dispatch a step (queue unavailable); leaving run for orchestrator retry`, error);
                 throw error;
             }
@@ -1279,14 +958,7 @@ export class PikkuWorkflowService {
         }
         return getSingletonServices().queueService;
     }
-    /**
-     * Invoke a step's RPC with the workflow-step wire (step identity + provenance).
-     * 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, 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 = knownRun ?? (await this.getRunIdentity(runId));
         return rpcService.rpcWithWire(rpcName, data, {
             ...(run?.wire?.pikkuUserId ? { pikkuUserId: run.wire.pikkuUserId } : {}),
@@ -1301,16 +973,6 @@ export class PikkuWorkflowService {
             },
         });
     }
-    /**
-     * Inline (straight-through) step execution with an in-process retry loop —
-     * shared by inline RPC steps and inline function steps. Same scaffolding
-     * (running → result, or fail → retry-attempt → backoff → retry) wrapped
-     * around a step-specific `doWork` body. Stays O(K): no suspend/replay.
-     *
-     * `onError` is an optional hook for terminal errors that must NOT retry
-     * (e.g. RPC-not-found → suspend the run for redeploy). If it throws, the
-     * loop exits immediately without recording a step error or retrying.
-     */
     async runInlineRetryLoop(stepState, retries, retryDelay, doWork, onError) {
         let currentStepState = stepState;
         while (true) {
@@ -1323,81 +985,49 @@ export class PikkuWorkflowService {
             catch (error) {
                 if (onError)
                     await onError(error);
-                // Record the error (marks step as failed)
                 await this.setStepError(currentStepState.stepId, error);
                 if (currentStepState.attemptCount < retries) {
-                    // Create a new pending retry attempt, then back off if configured.
                     currentStepState = await this.createRetryAttempt(currentStepState.stepId, 'pending');
                     if (retryDelay) {
                         await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(retryDelay)));
                     }
-                    // Continue loop to retry
                 }
                 else {
-                    // No more retries, fail the workflow
                     throw error;
                 }
             }
         }
     }
-    /**
-     * Run a failed step's compensation handler as a durable step of its own.
-     *
-     * Durable rather than a bare invoke so a replay does not compensate twice —
-     * a handler is typically a refund or a rollback. `onError` is deliberately
-     * not forwarded: a compensation handler cannot itself compensate.
-     */
     async runStepCompensation(runId, stepName, onErrorRpcName, rpcService, error) {
         await this.rpcStep(runId, `${stepName}:onError`, onErrorRpcName, { error: { message: error.message } }, rpcService, { retries: 0 });
     }
     async rpcStep(runId, logicalStepName, rpcName, data, rpcService, stepOptions) {
-        // Capture the predecessor before nextStepKey advances the lineage to us.
         const fromStepName = this.lastStepName(runId);
         const stepName = this.nextStepKey(runId, logicalStepName);
-        // Resolve the retry policy ONCE here so the value persisted on the step
-        // (which drives `retriesExhausted`) is the same one the queue dispatch turns
-        // into `attempts`. Without this the queue could retry N times while the
-        // engine thinks retries are already exhausted (or vice-versa).
         const resolvedStepOptions = {
             retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
             retryDelay: stepOptions?.retryDelay,
             actor: stepOptions?.actor,
             onError: stepOptions?.onError,
         };
-        // 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;
         }
         if (stepState.status === 'failed') {
-            // Step failed with retries exhausted - throw error to fail the workflow
             const error = new Error(stepState.error?.message ||
                 `Step '${stepName}' failed after exhausting all retries`);
-            // Compensation, mirroring a graph node's onError: run the handler, then
-            // still throw — the workflow fails either way.
             if (resolvedStepOptions.onError) {
                 await this.runStepCompensation(runId, stepName, resolvedStepOptions.onError, rpcService, error);
             }
-            // Preserve original error properties if available
             if (stepState.error) {
                 Object.assign(error, stepState.error);
             }
             throw error;
         }
         if (stepState.status === 'scheduled') {
-            // Step is already scheduled, pause workflow
             throw new WorkflowAsyncException(runId, stepName);
         }
-        // Hand off to subclass-overridable transport. Default behavior enqueues
-        // via the queue service; DO-style subclasses RPC to a step worker.
-        // Dispatch BEFORE marking the step `scheduled`: if the queue is down,
-        // dispatchStep throws WorkflowDispatchException and the step stays `pending`,
-        // so the orchestrator's next replay re-dispatches it. Marking `scheduled`
-        // first would strand the step (replay sees `scheduled`, pauses, never
-        // re-enqueues the job that was never created).
-        // Actor steps never queue: they are outbound HTTP calls made by the
-        // runner itself, and the actor's session lives on this process.
         const dispatched = resolvedStepOptions.actor
             ? false
             : await this.dispatchStep(runId, stepName, rpcName, data, resolvedStepOptions, fromStepName);
@@ -1405,18 +1035,12 @@ export class PikkuWorkflowService {
             await this.setStepScheduled(stepState.stepId);
             throw new WorkflowAsyncException(runId, stepName);
         }
-        // Inline (no transport available) - execute locally with the shared retry
-        // loop. The body resolves to a sub-workflow result or a plain RPC result.
         const retries = resolvedStepOptions.retries ?? this.getConfig().retries;
         const retryDelay = resolvedStepOptions.retryDelay;
         return this.runInlineRetryLoop(stepState, retries, retryDelay, async (currentStepState) => {
-            // Actor step: send through the actor's authenticated client over the
-            // REAL transport. Never falls back to internal dispatch — that would
-            // bypass auth and fake a green health check.
             if (resolvedStepOptions.actor) {
                 return resolvedStepOptions.actor.invoke(rpcName, data);
             }
-            // Check if the name refers to a workflow
             const workflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
             if (workflowMeta) {
                 const childWire = {
@@ -1427,7 +1051,6 @@ 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
                 const childRun = await this.awaitRunEnd(childRunId, WORKFLOW_CHILD_POLL_MAX_MS);
                 if (childRun.status === 'failed') {
                     throw new Error(childRun.error?.message || 'Sub-workflow failed');
@@ -1448,40 +1071,19 @@ export class PikkuWorkflowService {
             }
         });
     }
-    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) {
+    async inlineStep(runId, logicalStepName, fn, stepOptions, data = null, rpcName = null) {
         const fromStepName = this.lastStepName(runId);
         const stepName = this.nextStepKey(runId, logicalStepName);
-        // 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;
         }
-        // Execute inline function
         const retries = stepOptions?.retries ?? this.getConfig().retries;
         const retryDelay = stepOptions?.retryDelay ?? this.getConfig().retryDelay;
-        // Check if we're running inline (in-memory) or remote (queue-based)
-        if (this.isInline(runId)) {
-            // Inline mode - execute with the shared in-process retry loop.
+        if (await this.isInline(runId)) {
             return this.runInlineRetryLoop(stepState, retries, retryDelay, () => fn());
         }
         else {
-            // Remote mode - single attempt, then suspend for orchestrator-driven retry.
             let currentStepState = stepState;
             try {
                 await this.setStepRunning(currentStepState.stepId);
@@ -1490,18 +1092,12 @@ export class PikkuWorkflowService {
                 return result;
             }
             catch (error) {
-                // Record the error (marks step as failed)
                 await this.setStepError(currentStepState.stepId, error);
-                // Check if we should retry
                 if (currentStepState.attemptCount < retries) {
-                    // Create a new pending retry attempt (copies metadata from failed step)
                     await this.createRetryAttempt(currentStepState.stepId, 'pending');
-                    // Schedule orchestrator to retry after delay
                     await this.scheduleOrchestratorRetry(runId, retryDelay);
-                    // Pause workflow - orchestrator will replay and pick up new attempt
                     throw new WorkflowAsyncException(runId, stepName);
                 }
-                // No more retries, fail the workflow
                 throw error;
             }
         }
@@ -1509,22 +1105,13 @@ export class PikkuWorkflowService {
     async sleepStep(runId, logicalStepName, duration) {
         const fromStepName = this.lastStepName(runId);
         const stepName = this.nextStepKey(runId, logicalStepName);
-        // 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;
         }
         if (stepState.status === 'scheduled') {
-            // Sleep is already scheduled, pause workflow
             throw new WorkflowAsyncException(runId, stepName);
         }
-        // Hand off to subclass-overridable transport. Default behavior schedules
-        // a delayed sleeper RPC via the scheduler service; DO-style subclasses
-        // override to use native timer primitives (e.g. setAlarm). Schedule BEFORE
-        // marking `scheduled` so a scheduler outage leaves the step `pending` for
-        // re-scheduling on replay instead of stranding it (see rpcStep).
         let scheduled;
         try {
             scheduled = await this.scheduleSleep(runId, stepState.stepId, duration);
@@ -1536,21 +1123,9 @@ export class PikkuWorkflowService {
             await this.setStepScheduled(stepState.stepId);
             throw new WorkflowAsyncException(runId, stepName);
         }
-        // Inline mode - use setTimeout with actual duration
         await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(duration)));
         await this.setStepResult(stepState.stepId, null);
     }
-    /**
-     * Derive the durable step name for a suspend point from its `reason`, so each
-     * distinct reason is its own step row — letting one workflow have multiple
-     * independent suspends (e.g. wait-for-build, then wait-for-approval), and
-     * supporting dynamic reasons in loops (`suspend(`Wait for ${i}`)`) exactly
-     * like dynamic `do()` step names. The reason is used raw (it's just a text
-     * step name), only namespaced so it can't collide with a `do`/`sleep` step of
-     * the same name. Like `do()` / `sleep()`, the reason is the step's stable
-     * identity: it MUST be derived deterministically so it's the same every time
-     * the workflow replays through that point.
-     */
     getSuspendStepName(reason) {
         return `__workflow_suspend:${reason}`;
     }
@@ -1585,16 +1160,6 @@ export class PikkuWorkflowService {
             throw new WorkflowSuspendedException(runId, reason);
         });
     }
-    /**
-     * Wake a run later by enqueuing a delayed orchestrator pass. Deliberately NOT
-     * {@link scheduleSleep}: that resolves the step it is given, which for an
-     * approval would resolve the gate itself. This only nudges the run to replay
-     * and re-evaluate — the gate stays the sole judge of its own outcome.
-     *
-     * Best-effort by design. Expiry is decided from the recorded deadline on
-     * replay, so losing this wake costs liveness (the run sits until something
-     * else resumes it), never correctness.
-     */
     async scheduleRunWake(runId, delay) {
         try {
             const queueService = this.verifyQueueService();
@@ -1611,20 +1176,9 @@ export class PikkuWorkflowService {
             this.logger?.warn(`Failed to schedule approval expiry wake for run ${runId}; expiry will still resolve on the next replay`, error);
         }
     }
-    /**
-     * Durable step name for an approval gate. Namespaced separately from suspend
-     * so the two can't collide, and derived from `reason` for the same reason
-     * {@link getSuspendStepName} is: it must be stable across replays.
-     */
     getApprovalStepName(reason) {
         return `__workflow_approval:${reason}`;
     }
-    /**
-     * Run-state key holding an approval gate's record. Hex-encoded because the
-     * Mongo backend restricts state keys to `/^[a-zA-Z0-9_]+$/` and a `reason` is
-     * arbitrary human text. One key per gate, so two gates resolving concurrently
-     * can't clobber each other through a read-modify-write.
-     */
     approvalStateKey(stepName) {
         let hex = '';
         for (const byte of new TextEncoder().encode(stepName)) {
@@ -1632,31 +1186,15 @@ export class PikkuWorkflowService {
         }
         return `__approval_${hex}`;
     }
-    /**
-     * Record a decision against an approval gate and wake the run. Called from
-     * outside the workflow (an HTTP route, an RPC), so the schema value is NOT in
-     * scope here — the payload is stored raw and validated on replay inside the
-     * workflow body, which is the only place the schema exists. An invalid payload
-     * therefore leaves the gate closed rather than failing the run.
-     *
-     * `reason` addresses the first reach of that gate. An approval reached more
-     * than once under the same reason (e.g. in a loop) gets `#N`-suffixed step
-     * rows that this cannot currently target.
-     */
     async approveStep(runId, reason, decision) {
         const stepName = this.getApprovalStepName(reason);
         const stateKey = this.approvalStateKey(stepName);
-        // A resolved gate returns its cached step result and never re-reads state,
-        // so a decision recorded now would be silently discarded — most obviously
-        // when it loses the race with expiry. Reject instead, so the approver
-        // learns their decision did not land.
         let resolved;
         try {
             resolved = await this.getStepState(runId, stepName);
         }
         catch {
-            // No step row yet: the run has not reached the gate. Recording a decision
-            // ahead of it is legitimate — the gate picks it up on arrival.
+            // knowledge: decisions/security/workflow-approval-payloads-are-validated-on-replay-inside-the-workflow.md
         }
         if (resolved?.stepId && resolved.status === 'succeeded') {
             const outcome = resolved.result;
@@ -1686,8 +1224,6 @@ export class PikkuWorkflowService {
             if (!stepState.stepId) {
                 stepState = await this.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', { reason, expiry: options.expiry }, undefined, fromStepName);
             }
-            // Unlike suspend, `succeeded` here means a decision (or expiry) was
-            // actually resolved, and the step result IS the return channel.
             if (stepState.status === 'succeeded') {
                 return stepState.result;
             }
@@ -1695,8 +1231,6 @@ export class PikkuWorkflowService {
             let record = ((await this.getRunState(runId))[stateKey] ?? {});
             if (stepState.status === 'pending') {
                 await this.setStepRunning(stepState.stepId);
-                // First reach: stamp the deadline and nudge the run awake when it
-                // passes. The deadline is what's authoritative — see below.
                 if (options.expiry !== undefined && !record.expiresAt) {
                     const expiresAt = new Date(Date.now() + getDurationInMilliseconds(options.expiry)).toISOString();
                     record = { ...record, expiresAt };
@@ -1707,9 +1241,6 @@ export class PikkuWorkflowService {
             if (record.decision !== undefined) {
                 const validation = await options.schema['~standard'].validate(record.decision);
                 if (validation.issues) {
-                    // Drop the bad decision and re-close the gate, leaving the failure
-                    // legible to whoever tries next. Failing the run instead would let any
-                    // caller kill a workflow with a malformed payload.
                     await this.updateRunState(runId, stateKey, {
                         ...record,
                         decision: undefined,
@@ -1728,9 +1259,6 @@ export class PikkuWorkflowService {
                 await this.setStepResult(stepState.stepId, outcome);
                 return outcome;
             }
-            // Expiry is decided by comparing against the recorded deadline rather than
-            // by the timer having fired, so a duplicate, late, or dropped timer all
-            // produce the same answer.
             if (record.expiresAt && Date.now() >= Date.parse(record.expiresAt)) {
                 const outcome = { status: 'expired' };
                 await this.setStepResult(stepState.stepId, outcome);
@@ -1744,7 +1272,6 @@ export class PikkuWorkflowService {
             name,
             runId,
             getRun: async () => (await this.getRun(runId)),
-            // Implement workflow.do() - RPC form
             do: async (stepName, rpcNameOrFn, dataOrOptions, options) => {
                 this.verifyStepName(stepName);
                 if (typeof rpcNameOrFn === 'string') {
@@ -1757,7 +1284,6 @@ export class PikkuWorkflowService {
                     return await this.inlineStep(runId, stepName, rpcNameOrFn, dataOrOptions);
                 }
             },
-            // Implement workflow.sleep()
             sleep: async (stepName, duration) => {
                 this.verifyStepName(stepName);
                 await this.sleepStep(runId, stepName, getDurationInMilliseconds(duration));
@@ -1795,16 +1321,6 @@ export class PikkuWorkflowService {
             sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowSleeper',
         };
     }
-    /**
-     * Get the orchestrator queue name for a specific workflow.
-     * Checks queue meta for a per-workflow queue first (e.g. wf-orchestrator-{name}),
-     * falls back to the shared orchestrator queue.
-     *
-     * Reads from `queue.meta` (always populated globally) rather than
-     * `queue.registrations` (only populated for queues this unit consumes).
-     * In a per-unit deploy the orchestrator unit doesn't consume per-step
-     * queues — but it produces to them — so registrations would miss them.
-     */
     getOrchestratorQueueName(workflowName) {
         if (workflowName && this.queueStrategy !== 'shared-groups') {
             const perWorkflow = `wf-orchestrator-${toKebab(workflowName)}`;
@@ -1825,15 +1341,6 @@ export class PikkuWorkflowService {
         }
         return this.getConfig().stepWorkerQueueName;
     }
-    /**
-     * Fairness key for a job on a shared queue. Under `'per-workflow'` the queue
-     * name already isolates workflows, so no group is needed — returning one
-     * anyway would cap a workflow inside its own dedicated queue.
-     *
-     * The tier repeats the id so a workflow can be given its own limit purely
-     * from config, with no per-workflow wiring; an unmatched tier falls back to
-     * the default limit.
-     */
     getJobGroup(id) {
         if (!id || this.queueStrategy !== 'shared-groups') {
             return undefined;