@pikku/core 0.12.67 → 0.12.70

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

@@ -1,10 +1,10 @@
-import type { SerializedError } from '../../types/core.types.js';
-import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, 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';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
-import type { JobOptions } from '../queue/queue.types.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
@@ -88,6 +88,72 @@ 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;
+    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>;
+}
 /**
  * Abstract workflow state service
  * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
@@ -95,13 +161,16 @@ export declare class WorkflowStepNameNotString extends Error {
  */
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private inlineRuns;
-    private runActors;
+    private runExtension?;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
+    protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
+    protected readonly queueConcurrency: number;
+    protected readonly queueGroupConcurrency: number | GroupConcurrencyConfig;
     constructor(options?: {
         wireQueues?: boolean;
         mirror?: WorkflowRunMirror;
-    });
+    } & WorkflowQueueOptions);
     private safeMirror;
     /**
      * Wire the queue-based orchestrator/step/sleeper workers.
@@ -176,7 +245,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
@@ -379,18 +451,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;
     }>;
@@ -413,7 +495,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)
@@ -452,7 +534,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
@@ -504,8 +600,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.
@@ -519,4 +615,14 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     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;
 }