@pikku/core 0.12.69 → 0.12.71

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

@@ -1,5 +1,5 @@
-import type { SerializedError } from '../../types/core.types.js';
-import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
+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 { PikkuError } from '../../errors/error-handler.js';
@@ -89,13 +89,77 @@ export declare class WorkflowStepNameNotString extends Error {
     constructor(stepName: any);
 }
 /**
- * Abstract workflow state service
- * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
- * Combines orchestration and step execution
+ * 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;
+    workflowMeta: any;
+    workflow: CoreWorkflow;
+    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 inlineRuns;
-    private runActors;
+    private runExtension?;
+    private runContexts;
+    private contextFor;
+    /** Drop a run's context once nothing is holding it open. */
+    private releaseContext;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
     protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
@@ -105,7 +169,18 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         wireQueues?: boolean;
         mirror?: WorkflowRunMirror;
     } & WorkflowQueueOptions);
-    private safeMirror;
+    /**
+     * 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
@@ -179,7 +254,10 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * Creates pending step in both workflow_step and workflow_step_history
      * @param runId - Run ID
      * @param stepName - Step cache key
-     * @param rpcName - RPC function name
+     * @param rpcName - The name this step was dispatched by: an RPC for a
+     *   `workflow.do` step, a step function for a scenario step, null for a
+     *   closure. Nothing dispatches off this value — it is recorded so a reader
+     *   can join a step back to the function that ran it.
      * @param data - Step input data
      * @param stepOptions - Step options (retries, retryDelay)
      * @returns Step state with generated stepId
@@ -323,11 +401,6 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         graph: any;
         source: string;
     } | null>;
-    abstract getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
     /**
      * Resume a paused workflow by triggering the orchestrator
      * @param runId - Run ID
@@ -382,18 +455,28 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      *   false to fall through to inline `setTimeout` behavior.
      */
     protected scheduleSleep(runId: string, stepId: string, duration: number | string): Promise<boolean>;
-    /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
-    private resolveScenarioActors;
+    /**
+     * 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;
+        onRunCreated?: (runId: string) => void;
     }): Promise<{
         runId: string;
     }>;
@@ -401,9 +484,59 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;
     }): Promise<any>;
-    private stepOrdinals;
-    private stepLineage;
-    private resetStepOrdinals;
+    /**
+     * 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;
     /**
@@ -416,7 +549,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     runWorkflowJob(runId: string, rpcService: any): Promise<void>;
     private runWorkflowJobInner;
     private onChildWorkflowCompleted;
-    private onChildWorkflowFailed;
+    protected onChildWorkflowFailed(childRun: WorkflowRun, error: Error): Promise<void>;
     private runVersionMismatchFallback;
     /**
      * Execute a single workflow step (called by worker)
@@ -455,7 +588,21 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     private runStepCompensation;
     private rpcStep;
-    private inlineStep;
+    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>;
     private sleepStep;
     /**
      * Derive the durable step name for a suspend point from its `reason`, so each
@@ -507,8 +654,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
     private approvalStep;
-    createWorkflowWire(name: string, runId: string, rpcService: any, addonNamespace?: string | null): PikkuScenarioWire;
-    private verifyStepName;
+    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.