@pikku/core 0.12.78 → 0.12.80

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

@@ -5,7 +5,7 @@ import { closeWireServices } from '../../utils.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
 import { runScheduledTask } from '../scheduler/scheduler-runner.js';
-import { WorkflowStepNameNotString, } from './pikku-workflow-service.js';
+import { WorkflowStepNameNotString } from './workflow-errors.js';
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
 /**
  * A workflow service with the scenario capability attached — the two lines
@@ -176,6 +176,10 @@ export class PikkuScenarioService {
     // Scenario actors per run: live authenticated clients (cookie jars) are
     // process-local by nature, so they ride this map, never the persisted wire.
     runActors = new Map();
+    // What each run has accumulated so far. Process-local like the actors above:
+    // a scenario is a single in-process run, so the body and its hooks share one
+    // object rather than reading it back off the persisted wire.
+    runContexts = new Map();
     scenarioBrowserProvider;
     scenarioEnvironment;
     runSurface = 'default';
@@ -222,9 +226,35 @@ export class PikkuScenarioService {
         if (actors) {
             this.runActors.set(runId, actors);
         }
+        if (workflowMeta.source === 'scenario') {
+            this.runContexts.set(runId, {});
+        }
     }
     detachRunContext(runId) {
         this.runActors.delete(runId);
+        this.runContexts.delete(runId);
+    }
+    /**
+     * What the run has accumulated, for a reporter that wants to say what a
+     * failed scenario left behind. Undefined for a plain workflow.
+     */
+    getRunContext(runId) {
+        return this.runContexts.get(runId);
+    }
+    /**
+     * The run's context, created on demand.
+     *
+     * `attachRunContext` seeds it for an ordinary scenario run, but the wire is
+     * also built on paths that skip attach; without this the body would be
+     * writing to an `undefined` and teardown would read nothing.
+     */
+    contextForRun(runId) {
+        let runContext = this.runContexts.get(runId);
+        if (!runContext) {
+            runContext = {};
+            this.runContexts.set(runId, runContext);
+        }
+        return runContext;
     }
     decorateRunWire(wire, context) {
         wire.scenario =
@@ -367,6 +397,10 @@ export class PikkuScenarioService {
             rpcService,
         });
         Object.assign(workflowWire, {
+            // One object per run, resolved through the map rather than created here,
+            // so the body and its before/after hooks share the same scratch even
+            // though the hooks are separate functions that cannot see its locals.
+            context: this.contextForRun(runId),
             // Durable polling step: invoke an RPC (as an actor when options.as is
             // set) until the predicate passes or `within` elapses. The whole poll is
             // ONE recorded step, so replay returns the cached outcome.
@@ -451,12 +485,7 @@ export class PikkuScenarioService {
                     }
                 }, options);
             },
-            // Scenario steps: a named `pikkuScenarioStep` run as one durable step.
-            // `given`/`when` are sugar for each other, differing only in the
-            // prose a reporter renders. `then` is not: the phase is what decides
-            // whether the step's bindings are alternatives or witnesses, so the same
-            // step function called two ways runs differently. See
-            // {@link resolveScenarioSurfaces}.
+            // knowledge: decisions/internals/scenario-given-and-when-are-sugar-but-then-is-not.md
             given: (stepName, stepFunc, data, options) => this.scenarioStep('given', scenarioStepContext(), stepName, stepFunc, data, options),
             when: (stepName, stepFunc, data, options) => this.scenarioStep('when', scenarioStepContext(), stepName, stepFunc, data, options),
             then: (stepName, stepFunc, data, options) => this.scenarioStep('then', scenarioStepContext(), stepName, stepFunc, data, options),
@@ -466,7 +495,7 @@ export class PikkuScenarioService {
         });
     }
     async scenarioStep(phase, context, stepName, stepFunc, data, options) {
-        const { runId, workflowName, addonNamespace, workflowWire, rpcService } = context;
+        const { runId, workflowName, addonNamespace, workflowWire } = context;
         // Also the guard for `then` being a wire member: an accidental
         // `await scenario` calls it with a resolve function, which lands here as a
         // loud, named error instead of a silent hang.
@@ -486,11 +515,10 @@ export class PikkuScenarioService {
         const resolution = resolveScenarioSurfaces(phase, declared, this.runSurface);
         return await this.engine.inlineStep(runId, stepName, async () => {
             const runOnSurface = async (surface) => {
+                // No `rpc` yet — runPikkuFunc attaches it lazily for the invocation.
                 const wire = {
                     workflow: workflowWire,
                     scenario: workflowWire,
-                    rpc: rpcService?.wire?.rpc,
-                    session: rpcService?.wire?.session,
                     pikkuUserId: workflowWire.pikkuUserId,
                     actors: this.runActors.get(runId),
                     scenarioStep: {

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;
@@ -179,23 +99,27 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     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.)
+     * Runs holding a step that has sat `pending` since before `before`, paired
+     * with the step that flagged them.
      *
-     * 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.
+     * Returns nothing by default so a store that cannot express the query keeps
+     * working unchanged — and, because it does not opt in, gains no re-dispatches
+     * either. A store must have an atomic `withStepLock` before overriding this,
+     * or no concurrency for one to exclude: the relay makes duplicate dispatch
+     * routine, and the claim in `executeWorkflowStepInner` is what keeps a
+     * duplicate from becoming a second execution. `kysely-postgres` and
+     * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
+     * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+     */
+    protected findUndispatchedSteps(_before: Date, _limit: number): Promise<Array<{
+        runId: string;
+        stepId: string;
+    }>>;
+    private readonly redispatchBackoff;
+    private get sweepDeps();
+    /**
+     * 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;
@@ -203,6 +127,17 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     }): 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;
+        limit?: number;
+    }): Promise<{
+        redispatched: string[];
+    }>;
     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>;
@@ -211,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;
@@ -219,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>;
@@ -234,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;
@@ -249,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;