@pikku/core 0.12.71 → 0.12.74

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,50 +1,26 @@
 import type { PikkuWire, SerializedError } from '../../types/core.types.js';
 import type { ApprovalOutcome, CoreWorkflow, PikkuWorkflowWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
-import type { ScenarioActors } from '../../services/scenario-actors-service.js';
+import type { ScenarioPersonas } from '../../services/personas-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
 import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.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 declare const DEFAULT_STEP_RETRIES = 5;
-/**
- * Exception thrown when workflow needs to pause for async step
- */
 export declare class WorkflowAsyncException extends Error {
     readonly runId: string;
     readonly stepName: string;
     constructor(runId: string, stepName: string);
 }
-/**
- * Exception thrown when workflow is cancelled
- */
 export declare class WorkflowCancelledException extends Error {
     readonly runId: string;
     readonly reason?: string | undefined;
     constructor(runId: string, reason?: string | undefined);
 }
-/**
- * Exception thrown when workflow is suspended
- */
 export declare class WorkflowSuspendedException extends Error {
     readonly runId: string;
     readonly reason: string;
     constructor(runId: string, reason: string);
 }
-/**
- * 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 declare class WorkflowDispatchException extends Error {
     readonly runId: string;
     readonly stepName: string;
@@ -52,9 +28,6 @@ export declare class WorkflowDispatchException extends Error {
         cause?: unknown;
     });
 }
-/**
- * Error class for workflow not found
- */
 export declare class WorkflowNotFoundError extends PikkuError {
     constructor(name: string);
 }
@@ -70,12 +43,6 @@ export declare class WorkflowRunFailedError extends PikkuError {
 export declare class WorkflowRunCancelledError extends PikkuError {
     constructor();
 }
-/**
- * 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 declare class WorkflowApprovalResolvedError extends PikkuError {
     payload: {
         reason: string;
@@ -88,11 +55,6 @@ export declare class WorkflowServiceNotInitialized extends Error {
 export declare class WorkflowStepNameNotString extends Error {
     constructor(stepName: any);
 }
-/**
- * Everything an extension needs to run something of its own around a run's
- * function: the registration it was resolved from, the run itself (so `input`
- * is the same object the function is called with), and the wire it is given.
- */
 export interface RunLifecycleContext {
     runId: string;
     run: WorkflowRun;
@@ -101,65 +63,36 @@ export interface RunLifecycleContext {
     wire: PikkuWire;
     packageName: string | null;
 }
-/**
- * The slice of the run engine an extension is allowed to drive, handed to it at
- * construction. It exists so that recording a durable step stays available to
- * an extension without `inlineStep` and friends becoming public API on every
- * workflow service a production app instantiates.
- */
 export interface WorkflowRunEngine {
     inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, data?: any, funcName?: string): Promise<any>;
     updateRunStatus(runId: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
     onChildWorkflowFailed(run: WorkflowRun, error: unknown): Promise<void>;
     verifyStepName(stepName: unknown): void;
 }
-/**
- * A capability layered onto a run without being a workflow service itself.
- *
- * The engine names nothing about what an extension is for: a bundler drops an
- * unused *module* but never an unused class member, so the alternative — a
- * subclass carrying the capability — puts it in every server built on Pikku
- * whether or not the app ever uses it. Scenarios are the one implementation
- * today (`PikkuScenarioService` in `@pikku/core/scenario`).
- */
 export interface WorkflowRunExtension {
-    /** Per-run state resolved once the run has an id. */
     attachRunContext(runId: string, workflowMeta: any, options?: Record<string, any>): Promise<void>;
-    /** Release whatever `attachRunContext` stored. */
     detachRunContext(runId: string): void;
-    /** Contribute extra members to the wire a run's function is invoked with. */
     decorateRunWire(wire: PikkuWire, context: {
         runId: string;
         workflowMeta: any;
         workflowWire: PikkuWorkflowWire;
     }): void;
-    /** Contribute extra members to the workflow wire itself, in place. */
     decorateWorkflowWire(workflowWire: PikkuWorkflowWire, context: {
         name: string;
         runId: string;
         rpcService: any;
         addonNamespace?: string | null;
     }): void;
-    /**
-     * Called immediately before the run's function, inside the run lock. Throwing
-     * skips the function and fails the run.
-     */
     onBeforeRunFunc(context: RunLifecycleContext): Promise<void>;
-    /**
-     * Called once the run reaches a terminal state, in a `finally`, so it runs
-     * whether the function passed or threw. `interrupted` means the run suspended
-     * or went async and is still mid-flight. Throwing here propagates, replacing
-     * a pending failure, so an extension that must not mask one handles that
-     * itself.
-     */
     onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
 }
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private runExtension?;
     private runContexts;
     private contextFor;
-    /** Drop a run's context once nothing is holding it open. */
     private releaseContext;
+    private enterExecution;
+    private exitExecution;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
     protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
@@ -169,36 +102,10 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         wireQueues?: boolean;
         mirror?: WorkflowRunMirror;
     } & WorkflowQueueOptions);
-    /**
-     * 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
-     */
     private mirrored;
-    /**
-     * 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(): void;
-    /**
-     * Check if a run is executing inline (without queues)
-     */
-    protected isInline(runId: string): boolean;
-    /**
-     * Register a run as inline (for graph-runner to use)
-     */
+    protected isInline(runId: string): Promise<boolean>;
     registerInlineRun(runId: string): void;
-    /**
-     * Unregister a run from inline tracking
-     */
     unregisterInlineRun(runId: string): void;
     registerWorkflowVersions(): Promise<void>;
     createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
@@ -209,189 +116,48 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         deterministic?: boolean;
         plannedSteps?: WorkflowPlannedStep[];
     }): Promise<string>;
-    /**
-     * Get a workflow run by ID
-     * @param id - Run ID
-     * @returns Workflow run or null if not found
-     */
     abstract getRun(id: string): Promise<WorkflowRun | null>;
-    /**
-     * Get minimal workflow run status with step summaries.
-     * Used by the public API — the console addon provides the full verbose view.
-     */
     getRunStatus(id: string): Promise<WorkflowRunStatus | null>;
-    /**
-     * 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
-     */
     getRunTimeline(id: string): Promise<RunTimeline | null>;
-    /**
-     * 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
-     */
     reconstructRunStateAt(id: string, at?: number | Date): Promise<ReconstructedRunState | null>;
-    /**
-     * Get workflow run history (all step attempts in chronological order)
-     * @param runId - Run ID
-     * @returns Array of step states with step names, ordered oldest to newest
-     */
     abstract getRunHistory(runId: string): Promise<Array<StepState & {
         stepName: string;
     }>>;
-    /**
-     * Update workflow run status
-     * @param id - Run ID
-     * @param status - New status
-     */
     updateRunStatus(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
     protected abstract updateRunStatusImpl(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
-    /**
-     * 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
-     */
     insertStepState(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<StepState>;
     protected abstract insertStepStateImpl(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<StepState>;
-    /**
-     * Get step state by cache key (read-only)
-     * @param runId - Run ID
-     * @param stepName - Step cache key (from workflow.do)
-     * @returns Step state with attemptCount calculated from history
-     */
     abstract getStepState(runId: string, stepName: string): Promise<StepState>;
-    /**
-     * Mark step as running
-     * Updates both workflow_step and workflow_step_history
-     * @param stepId - Step ID
-     */
     setStepRunning(stepId: string): Promise<void>;
     protected abstract setStepRunningImpl(stepId: string): Promise<void>;
-    /**
-     * Mark step as scheduled (queued for execution)
-     * Updates both workflow_step and workflow_step_history
-     * @param stepId - Step ID
-     */
     setStepScheduled(stepId: string): Promise<void>;
     protected abstract setStepScheduledImpl(stepId: string): Promise<void>;
-    /**
-     * Store step result and mark as succeeded
-     * Updates both workflow_step and workflow_step_history
-     * @param stepId - Step ID
-     * @param result - Step result
-     */
     setStepResult(stepId: string, result: any): Promise<void>;
     protected abstract setStepResultImpl(stepId: string, result: any): Promise<void>;
-    /**
-     * Set the child workflow run ID on a step
-     * @param stepId - Step ID
-     * @param childRunId - Child workflow run ID
-     */
     setStepChildRunId(stepId: string, childRunId: string): Promise<void>;
     protected abstract setStepChildRunIdImpl(stepId: string, childRunId: string): Promise<void>;
-    /**
-     * Store step error and mark as failed
-     * Updates both workflow_step and workflow_step_history
-     * @param stepId - Step ID
-     * @param error - Error object
-     */
     setStepError(stepId: string, error: Error): Promise<void>;
     protected abstract setStepErrorImpl(stepId: string, error: Error): Promise<void>;
-    /**
-     * 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
-     */
     createRetryAttempt(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
     protected abstract createRetryAttemptImpl(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
-    /**
-     * Execute function within a run lock to prevent concurrent modifications
-     * @param id - Run ID
-     * @param fn - Function to execute
-     * @returns Function result
-     */
     abstract withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
-    /**
-     * Execute function within a step lock to prevent concurrent step execution
-     * @param runId - Run ID
-     * @param stepName - Step name
-     * @param fn - Function to execute
-     * @returns Function result
-     */
     abstract withStepLock<T>(runId: string, stepName: string, fn: () => Promise<T>): Promise<T>;
-    /**
-     * Close any open connections
-     */
     abstract close(): Promise<void>;
-    /**
-     * Get completed graph state (lightweight - no results)
-     * @param runId - Run ID
-     * @returns Completed node IDs and their branch keys
-     */
     abstract getCompletedGraphState(runId: string): Promise<{
         completedNodeIds: string[];
         failedNodeIds: string[];
         branchKeys: Record<string, string>;
     }>;
-    /**
-     * Filter candidate nodes to only those without existing steps
-     * @param runId - Run ID
-     * @param nodeIds - Candidate node IDs to check
-     * @returns Node IDs that don't have a step yet
-     */
-    abstract getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
-    /**
-     * List every step instance of a run (any status) with its predecessor.
-     * Drives bounded graph revisits: the runner counts instances per logical node
-     * and treats each `fromStepName → node` as a once-fired transition.
-     * @param runId - Run ID
-     */
     abstract getStepInstances(runId: string): Promise<Array<{
         stepName: string;
         status: StepStatus;
         fromStepName?: string;
     }>>;
-    /**
-     * Get results for specific nodes
-     * @param runId - Run ID
-     * @param nodeIds - Node IDs to fetch results for
-     * @returns Map of nodeId to result
-     */
     abstract getNodeResults(runId: string, nodeIds: string[]): Promise<Record<string, any>>;
-    /**
-     * Set the branch key for a graph node step
-     * @param stepId - Step ID
-     * @param branchKey - Branch key selected by graph.branch()
-     */
     setBranchTaken(stepId: string, branchKey: string): Promise<void>;
     protected abstract setBranchTakenImpl(stepId: string, branchKey: string): Promise<void>;
-    /**
-     * Update a state variable in the workflow run's state
-     * @param runId - Run ID
-     * @param name - Variable name
-     * @param value - Value to store
-     */
     updateRunState(runId: string, name: string, value: unknown): Promise<void>;
     protected abstract updateRunStateImpl(runId: string, name: string, value: unknown): Promise<void>;
-    /**
-     * Get the entire state object for a workflow run
-     * @param runId - Run ID
-     * @returns The state object with all variables
-     */
     abstract getRunState(runId: string): Promise<Record<string, unknown>>;
     upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
     protected abstract upsertWorkflowVersionImpl(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
@@ -401,81 +167,19 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         graph: any;
         source: string;
     } | null>;
-    /**
-     * Resume a paused workflow by triggering the orchestrator
-     * @param runId - Run ID
-     */
     resumeWorkflow(runId: string, workflowName?: string): Promise<void>;
-    /**
-     * 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.
-     */
     protected resolveStepJobOptions(stepOptions?: WorkflowStepOptions): JobOptions;
     queueStepWorker(runId: string, stepName: string, rpcName: string, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<void>;
-    /**
-     * Execute a workflow sleep step completion
-     * Sets the step result to null and resumes the workflow
-     * @param data - Sleeper input data
-     */
     executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>;
-    /**
-     * Schedule orchestrator retry with delay
-     * @param runId - Run ID
-     * @param retryDelay - Delay in milliseconds or duration string (optional)
-     */
     protected scheduleOrchestratorRetry(runId: string, retryDelay?: number | string, workflowName?: string): Promise<void>;
-    /**
-     * 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.
-     */
     protected dispatchStep(runId: string, stepName: string, rpcName: string, data: unknown, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<boolean>;
-    /**
-     * 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.
-     */
     protected scheduleSleep(runId: string, stepId: string, duration: number | string): Promise<boolean>;
-    /**
-     * 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<T extends WorkflowRunExtension>(create: (engine: WorkflowRunEngine) => T): T;
     getRunExtension(): WorkflowRunExtension | undefined;
-    /**
-     * 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.
-     */
     startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
         inline?: boolean;
         startNode?: string;
-        actors?: ScenarioActors;
+        actors?: ScenarioPersonas;
         onRunCreated?: (runId: string) => void;
     }): Promise<{
         runId: string;
@@ -484,199 +188,43 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;
     }): Promise<any>;
-    /**
-     * 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.
-     */
     protected awaitRunEnd(runId: string, maxIntervalMs: number): Promise<WorkflowRun>;
-    /**
-     * 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.
-     */
     protected waitBeforeNextRead(ms: number): Promise<void>;
-    /**
-     * 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.
-     */
     protected listStepStates(_runId: string): Promise<Array<StepState & {
         stepName: string;
     }> | 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.
-     */
     private beginReplay;
     private endReplay;
-    /**
-     * The step row for `stepName`, creating it if the run has not reached it
-     * before. Served from the replay snapshot when one is loaded.
-     */
     private loadOrCreateStep;
-    /**
-     * 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.
-     */
     private getRunIdentity;
-    /** The step the DSL walk last reached (the predecessor for the next step). */
     private lastStepName;
-    /**
-     * 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.
-     */
     private nextStepKey;
     runWorkflowJob(runId: string, rpcService: any): Promise<void>;
     private runWorkflowJobInner;
     private onChildWorkflowCompleted;
     protected onChildWorkflowFailed(childRun: WorkflowRun, error: Error): Promise<void>;
     private runVersionMismatchFallback;
-    /**
-     * Execute a single workflow step (called by worker)
-     * Handles idempotency, RPC execution, result storage, retry logic, and orchestrator triggering
-     */
     executeWorkflowStep(runId: string, stepName: string, rpcName: string, data: any, rpcService: any): Promise<void>;
-    /**
-     * Orchestrate workflow execution (called by orchestrator)
-     * Runs workflow job and handles async exceptions
-     */
+    private executeWorkflowStepInner;
     orchestrateWorkflow(runId: string, rpcService: any): Promise<void>;
     private verifyQueueService;
-    /**
-     * 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.
-     */
     private invokeStepRpc;
-    /**
-     * 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.
-     */
     private runInlineRetryLoop;
-    /**
-     * 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.
-     */
     private runStepCompensation;
     private rpcStep;
-    protected inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, 
-    /**
-     * 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?: any, 
-    /**
-     * 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?: string | null): Promise<any>;
+    protected inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, data?: any, rpcName?: string | null): Promise<any>;
     private sleepStep;
-    /**
-     * 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.
-     */
     private getSuspendStepName;
     private suspendStep;
-    /**
-     * 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.
-     */
     private scheduleRunWake;
-    /**
-     * 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.
-     */
     private getApprovalStepName;
-    /**
-     * 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.
-     */
     private approvalStateKey;
-    /**
-     * 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.
-     */
     approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
     private approvalStep;
     createWorkflowWire(name: string, runId: string, rpcService: any, addonNamespace?: string | null): PikkuWorkflowWire;
     protected verifyStepName(stepName: string): void;
     private getConfig;
-    /**
-     * 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.
-     */
     protected getOrchestratorQueueName(workflowName?: string): string;
     protected getStepWorkerQueueName(rpcName?: string): string;
-    /**
-     * 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.
-     */
     protected getJobGroup(id?: string): JobGroup | undefined;
 }