@pikku/core 0.12.79 → 0.12.82

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

@@ -1,91 +1,11 @@
-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 { CoreUserSession, SerializedError } from '../../types/core.types.js';
+import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.js';
+import type { 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 { ScenarioPersonas } from '../../services/personas-service.js';
-import { PikkuError } from '../../errors/error-handler.js';
+import type { PikkuRPC } from '../rpc/rpc-types.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
-import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.js';
-export declare const DEFAULT_STEP_RETRIES = 5;
-export declare class WorkflowAsyncException extends Error {
-    readonly runId: string;
-    readonly stepName: string;
-    constructor(runId: string, stepName: string);
-}
-export declare class WorkflowCancelledException extends Error {
-    readonly runId: string;
-    readonly reason?: string | undefined;
-    constructor(runId: string, reason?: string | undefined);
-}
-export declare class WorkflowSuspendedException extends Error {
-    readonly runId: string;
-    readonly reason: string;
-    constructor(runId: string, reason: string);
-}
-export declare class WorkflowDispatchException extends Error {
-    readonly runId: string;
-    readonly stepName: string;
-    constructor(runId: string, stepName: string, options?: {
-        cause?: unknown;
-    });
-}
-export declare class WorkflowNotFoundError extends PikkuError {
-    constructor(name: string);
-}
-export declare class WorkflowRunNotFoundError extends PikkuError {
-    constructor(runId: string);
-}
-export declare class WorkflowRunFailedError extends PikkuError {
-    payload: {
-        message?: string;
-    };
-    constructor(message?: string);
-}
-export declare class WorkflowRunCancelledError extends PikkuError {
-    constructor();
-}
-export declare class WorkflowApprovalResolvedError extends PikkuError {
-    payload: {
-        reason: string;
-        outcome: ApprovalOutcome<unknown>['status'];
-    };
-    constructor(reason: string, outcome: ApprovalOutcome<unknown>['status']);
-}
-export declare class WorkflowServiceNotInitialized extends Error {
-}
-export declare class WorkflowStepNameNotString extends Error {
-    constructor(stepName: any);
-}
-export interface RunLifecycleContext {
-    runId: string;
-    run: WorkflowRun;
-    workflowMeta: any;
-    workflow: CoreWorkflow;
-    wire: PikkuWire;
-    packageName: string | null;
-}
-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;
-}
-export interface WorkflowRunExtension {
-    attachRunContext(runId: string, workflowMeta: any, options?: Record<string, any>): Promise<void>;
-    detachRunContext(runId: string): void;
-    decorateRunWire(wire: PikkuWire, context: {
-        runId: string;
-        workflowMeta: any;
-        workflowWire: PikkuWorkflowWire;
-    }): void;
-    decorateWorkflowWire(workflowWire: PikkuWorkflowWire, context: {
-        name: string;
-        runId: string;
-        rpcService: any;
-        addonNamespace?: string | null;
-    }): void;
-    onBeforeRunFunc(context: RunLifecycleContext): Promise<void>;
-    onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
-}
+import type { WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private runExtension?;
     private runContexts;
@@ -178,31 +98,6 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * `recoverStalledRuns`.
      */
     protected findStalledRunIds(_before: Date, _limit: number): Promise<string[]>;
-    /**
-     * Re-drive runs whose next move was lost, and report which were resumed.
-     *
-     * Arming a step is two writes to two systems — the step row, then the queue
-     * or scheduler job — so a process that dies between them leaves a run that is
-     * `running` with nothing in flight. Nothing notices: the run parks on a step
-     * that will never complete and never error, so it neither finishes nor fails.
-     * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
-     * step's insert and its timer, parking the run permanently.)
-     *
-     * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted
-     * step state, and every settled step is memoized, so resuming a run that was
-     * not actually stuck costs an orchestration pass and changes nothing. That
-     * idempotence is what makes an idle-time heuristic safe here; a run that is
-     * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
-     *
-     * This is not self-starting. Call it from a scheduled task at whatever
-     * interval suits the workload.
-     */
-    recoverStalledRuns(options?: {
-        stalledAfterMs?: number;
-        limit?: number;
-    }): Promise<{
-        resumed: string[];
-    }>;
     /**
      * Runs holding a step that has sat `pending` since before `before`, paired
      * with the step that flagged them.
@@ -220,30 +115,22 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         runId: string;
         stepId: string;
     }>>;
+    private readonly redispatchBackoff;
+    private get sweepDeps();
     /**
-     * Re-drive steps whose dispatch was lost, and report which runs were nudged.
-     *
-     * Arming a step is two writes to two systems: the step row lands `pending`,
-     * then a queue or scheduler job is published. Nothing spans both, so a crash
-     * in between leaves a durable row that nothing will ever pick up — the run
-     * neither finishes nor fails. (Seen on a `workflow.sleep()`: a deploy restart
-     * landed between the sleep step's insert and its timer.)
-     *
-     * The row is the outbox record and this is the relay. Age is the only signal
-     * available — a step `pending` because its dispatch was lost is
-     * indistinguishable from one whose job is merely still queued — so a step
-     * past `undispatchedAfterMs` is re-dispatched regardless, and correctness
-     * rests on the claim rather than on the guess being right. A redundant
-     * dispatch costs one queue message: the loser reads `running` and returns
-     * without invoking anything.
-     *
-     * Re-dispatches back off per step (doubling from 30s, capped at 10m) so a
-     * genuine queue backlog is not amplified by a tick that keeps firing at the
-     * steps the backlog is already delaying. The backoff is per process and
-     * advisory — losing it on restart costs extra dispatches, never correctness.
-     *
-     * This is not self-starting. Call it from a scheduled task; ~30s suits a
-     * queue whose `pending`→`running` latency is well under that.
+     * Re-drive runs whose next move was lost. Not self-starting — call it from a
+     * scheduled task at whatever interval suits the workload.
+     */
+    recoverStalledRuns(options?: {
+        stalledAfterMs?: number;
+        limit?: number;
+    }): Promise<{
+        resumed: string[];
+    }>;
+    /**
+     * Re-drive steps whose dispatch was lost. Not self-starting — call it from a
+     * scheduled task; ~30s suits a queue whose `pending`→`running` latency is
+     * well under that.
      */
     relayUndispatchedSteps(options?: {
         undispatchedAfterMs?: number;
@@ -251,10 +138,6 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     }): Promise<{
         redispatched: string[];
     }>;
-    /** Advisory, per-process record of when a run may next be re-dispatched. */
-    private readonly redispatchBackoff;
-    private readonly redispatchDelays;
-    private noteRedispatch;
     protected resolveStepJobOptions(stepOptions?: WorkflowStepOptions): JobOptions;
     queueStepWorker(runId: string, stepName: string, rpcName: string, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<void>;
     executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>;
@@ -263,7 +146,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     protected scheduleSleep(runId: string, stepId: string, duration: number | string): Promise<boolean>;
     setRunExtension<T extends WorkflowRunExtension>(create: (engine: WorkflowRunEngine) => T): T;
     getRunExtension(): WorkflowRunExtension | undefined;
-    startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
+    startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: PikkuRPC, options?: {
         inline?: boolean;
         startNode?: string;
         actors?: ScenarioPersonas;
@@ -271,7 +154,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     }): Promise<{
         runId: string;
     }>;
-    runToCompletion<I>(name: string, input: I, rpcService: any, options?: {
+    runToCompletion<I>(name: string, input: I, rpcService: PikkuRPC, options?: {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;
     }): Promise<any>;
@@ -286,14 +169,14 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private getRunIdentity;
     private lastStepName;
     private nextStepKey;
-    runWorkflowJob(runId: string, rpcService: any): Promise<void>;
+    runWorkflowJob(runId: string, rpcService: PikkuRPC): Promise<void>;
     private runWorkflowJobInner;
     private onChildWorkflowCompleted;
     protected onChildWorkflowFailed(childRun: WorkflowRun, error: Error): Promise<void>;
     private runVersionMismatchFallback;
-    executeWorkflowStep(runId: string, stepName: string, rpcName: string, data: any, rpcService: any): Promise<void>;
+    executeWorkflowStep(runId: string, stepName: string, rpcName: string, data: any, rpcService: PikkuRPC): Promise<void>;
     private executeWorkflowStepInner;
-    orchestrateWorkflow(runId: string, rpcService: any): Promise<void>;
+    orchestrateWorkflow(runId: string, rpcService: PikkuRPC): Promise<void>;
     private verifyQueueService;
     private invokeStepRpc;
     private runInlineRetryLoop;
@@ -301,14 +184,12 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private rpcStep;
     protected inlineStep(runId: string, logicalStepName: string, fn: Function, stepOptions?: WorkflowStepOptions, data?: any, rpcName?: string | null): Promise<any>;
     private sleepStep;
-    private getSuspendStepName;
     private suspendStep;
     private scheduleRunWake;
-    private getApprovalStepName;
-    private approvalStateKey;
-    approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
+    private get approvalStore();
+    approveStep(runId: string, reason: string, decision: unknown, session?: CoreUserSession): Promise<void>;
     private approvalStep;
-    createWorkflowWire(name: string, runId: string, rpcService: any, addonNamespace?: string | null): PikkuWorkflowWire;
+    createWorkflowWire(name: string, runId: string, rpcService: PikkuRPC, addonNamespace?: string | null): PikkuWorkflowWire;
     protected verifyStepName(stepName: string): void;
     private getConfig;
     protected getOrchestratorQueueName(workflowName?: string): string;