@pikku/core 0.12.142 → 0.12.144

package/dist/wirings/workflow/graph/wire-workflow-graph.js

@@ -1,3 +1,13 @@
+/**
+ * Declares a workflow as a graph: each node names an RPC, and `config` says what
+ * feeds it and which nodes run next. The shape is data, so the console can draw
+ * it and a run records which branch it took.
+ *
+ * The inspector reads the graph from source at build time; at runtime this only
+ * returns a marker carrying the descriptive fields.
+ *
+ * @example snippet: workflowGraph
+ */
 export function pikkuWorkflowGraph(config) {
     return {
         __type: 'pikkuWorkflowGraph',

package/dist/wirings/workflow/graph/workflow-graph.types.d.ts

@@ -1,20 +1,31 @@
 import type { TemplateString } from './template.js';
+/** A reference to another node's output, or a path inside it, resolved when the node runs. */
 export interface RefValue {
     __isRef: true;
     nodeId: string;
     path?: string;
 }
 export declare const createRef: (nodeId: string, path?: string) => RefValue;
+/** Whether a value is a {@link RefValue}. */
 export declare const isRef: (value: unknown) => value is RefValue;
 export type RefFn<NodeIds extends string = string> = (nodeId: NodeIds, path?: string) => RefValue;
 export type NextConfig<NodeIds extends string = string> = NodeIds | NodeIds[] | Record<string, NodeIds | NodeIds[]>;
+/** The `template` helper as a graph node's `input` builder receives it. */
 export type TemplateFn = (templateStr: string, refs: Array<{
     $ref: string;
     path?: string;
 }>) => TemplateString;
+/** Refers to the current element (or a path inside it) of a `forEach` node. */
 export type ItemFn = (path?: string) => RefValue;
+/**
+ * The upstream array a `forEach` node iterates: a node id, a ref, or a function returning a ref.
+ */
 export type ForEachConfig<NodeIds extends string = string> = NodeIds | RefValue | ((ref: RefFn<NodeIds>) => RefValue);
+/** Whether a `forEach` node's per-item instances run in parallel or one after another. */
 export type ForEachMode = 'parallel' | 'sequential';
+/**
+ * One node of a workflow graph: the RPC it runs, its input, its outgoing edges and its failure handling.
+ */
 export interface GraphNodeConfig<NodeIds extends string = string> {
     func: string;
     /**

package/dist/wirings/workflow/graph/workflow-graph.types.js

@@ -3,6 +3,7 @@ export const createRef = (nodeId, path) => ({
     nodeId,
     path,
 });
+/** Whether a value is a {@link RefValue}. */
 export const isRef = (value) => typeof value === 'object' &&
     value !== null &&
     '__isRef' in value &&

package/dist/{services → wirings/workflow}/in-memory-workflow-service.d.ts

@@ -1,6 +1,11 @@
-import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
-import type { SerializedError } from '../errors/serialized-error.js';
-import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+import { PikkuWorkflowService } from './pikku-workflow-service.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
+import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+/**
+ * A workflow service that keeps runs, steps and state in memory and runs every
+ * step inline. For tests and local development: nothing survives a restart, and
+ * it does not wire workflow queues or coordinate with another process.
+ */
 export declare class InMemoryWorkflowService extends PikkuWorkflowService implements WorkflowRunService {
     constructor(options?: WorkflowQueueOptions);
     private sleepTimers;

package/dist/{services → wirings/workflow}/in-memory-workflow-service.js

@@ -1,8 +1,13 @@
-import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
-import { isExpectedError } from '../errors/error-handler.js';
-import { isStepLeaseLive } from '../wirings/workflow/workflow-constants.js';
-import { WorkflowStepSupersededError } from '../wirings/workflow/workflow-errors.js';
+import { PikkuWorkflowService } from './pikku-workflow-service.js';
+import { isExpectedError } from '../../errors/error-handler.js';
+import { isStepLeaseLive } from './workflow-constants.js';
+import { WorkflowStepSupersededError } from './workflow-errors.js';
 // knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
+/**
+ * A workflow service that keeps runs, steps and state in memory and runs every
+ * step inline. For tests and local development: nothing survives a restart, and
+ * it does not wire workflow queues or coordinate with another process.
+ */
 export class InMemoryWorkflowService extends PikkuWorkflowService {
     constructor(options = {}) {
         super({ ...options, wireQueues: false });

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

@@ -1,5 +1,5 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
+import { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 import type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 import type { ScenarioVirtualUsers } from '../../services/virtual-users-service.js';

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

@@ -3,7 +3,7 @@ import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { closeWireServices } from '../../utils.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
-import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
+import { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { WorkflowStepNameNotString } from './workflow-errors.js';
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
@@ -497,7 +497,7 @@ export class PikkuScenarioService {
             apiUrl,
             appUrl: (await variables.get('APP_URL')) ?? undefined,
         };
-        const { createHttpVirtualUsers } = await import('../../services/http-virtual-users.js');
+        const { createHttpVirtualUsers } = await import('../virtual-user/http-virtual-users.js');
         const { inProcessSignIn } = await import('../../services/virtual-user-sign-in.js');
         return createHttpVirtualUsers({
             apiUrl,

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

@@ -8,6 +8,7 @@ import type { PikkuRPC } from '../rpc/rpc-types.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
 import type { WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
 import type { LeaseService } from '../../services/lease-service.js';
+/** The workflow engine; subclasses supply storage. Leases serialise runs and step claims over a shared store. */
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private runExtension?;
     private runContexts;

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

@@ -26,6 +26,7 @@ import { runDslWorkflowPass } from './workflow-dsl-pass.js';
 import { childRunFailure, failRunOrUnwind, isUnwound, compensatingForStep, cancelAndUnwind, createUnwindHost, driveUnwind, recordHasCompensation, isChildWorkflowRecord, } from './workflow-compensation.js';
 import { runVersionMismatchFallback } from './workflow-version-fallback.js';
 import { RedispatchBackoff, sweepStalledRuns, sweepUndispatchedSteps, } from './workflow-recovery.js';
+/** The workflow engine; subclasses supply storage. Leases serialise runs and step claims over a shared store. */
 export class PikkuWorkflowService {
     runExtension;
     runContexts = new Map();

package/dist/wirings/workflow/run-timeline.d.ts

@@ -1,5 +1,6 @@
 import type { SerializedError } from '../../errors/serialized-error.js';
 import type { StepState, StepStatus } from './workflow.types.js';
+/** One lifecycle transition of one step, in run order. */
 export interface RunTimelineEvent {
     seq: number;
     at: Date;
@@ -11,11 +12,19 @@ export interface RunTimelineEvent {
     result?: unknown;
     error?: SerializedError;
 }
+/** Every step transition in a run, ordered by time. */
 export type RunTimeline = RunTimelineEvent[];
+/** One stored step attempt, with the name of the step it belongs to. */
 export type HistoryEntry = StepState & {
     stepName: string;
 };
+/**
+ * Flattens a run's step history into a {@link RunTimeline}: one event per
+ * recorded transition, ordered by timestamp, then lifecycle order, then history
+ * order, and numbered with `seq`.
+ */
 export declare function buildRunTimeline(history: HistoryEntry[]): RunTimeline;
+/** A step as it stood at a point in a run's timeline. */
 export interface ReconstructedStep {
     stepName: string;
     compensating: boolean;
@@ -25,7 +34,11 @@ export interface ReconstructedStep {
     result?: unknown;
     error?: SerializedError;
 }
+/**
+ * Where a reconstructed run stood: nothing started, a step in flight, a step failed, or nothing in flight.
+ */
 export type RunPhase = 'pending' | 'running' | 'failed' | 'idle';
+/** A run's steps, results and path as of one point in its timeline. */
 export interface ReconstructedRunState {
     /** seq of the last applied event, or -1 if the point precedes all events. */
     seq: number;
@@ -35,5 +48,13 @@ export interface ReconstructedRunState {
     path: string[];
     phase: RunPhase;
 }
+/**
+ * Replays a timeline up to a point, for stepping through a run after the fact.
+ *
+ * @param timeline - The run's timeline, from {@link buildRunTimeline}.
+ * @param at - The last event to apply, by `seq`, or every event up to a time.
+ * @returns The run as it stood at that point.
+ */
 export declare function reconstructStateAt(timeline: RunTimeline, at: number | Date): ReconstructedRunState;
+/** The run as its whole timeline leaves it. */
 export declare function reconstructFinalState(timeline: RunTimeline): ReconstructedRunState;

package/dist/wirings/workflow/run-timeline.js

@@ -1,4 +1,4 @@
-import { isCompensationStepName } from './workflow-constants.js';
+import { isCompensationStepName, STEP_IN_FLIGHT_STATES, } from './workflow-constants.js';
 const LIFECYCLE_ORDER = {
     pending: 0,
     scheduled: 1,
@@ -6,6 +6,11 @@ const LIFECYCLE_ORDER = {
     succeeded: 3,
     failed: 3,
 };
+/**
+ * Flattens a run's step history into a {@link RunTimeline}: one event per
+ * recorded transition, ordered by timestamp, then lifecycle order, then history
+ * order, and numbered with `seq`.
+ */
 export function buildRunTimeline(history) {
     const raw = [];
     history.forEach((entry, order) => {
@@ -57,11 +62,13 @@ export function buildRunTimeline(history) {
     });
     return raw.map(({ order: _order, ...event }, seq) => ({ ...event, seq }));
 }
-const IN_FLIGHT = new Set([
-    'pending',
-    'scheduled',
-    'running',
-]);
+/**
+ * Replays a timeline up to a point, for stepping through a run after the fact.
+ *
+ * @param timeline - The run's timeline, from {@link buildRunTimeline}.
+ * @param at - The last event to apply, by `seq`, or every event up to a time.
+ * @returns The run as it stood at that point.
+ */
 export function reconstructStateAt(timeline, at) {
     const cutoff = (event) => typeof at === 'number'
         ? event.seq <= at
@@ -120,13 +127,14 @@ export function reconstructStateAt(timeline, at) {
         phase: derivePhase(orderedSteps),
     };
 }
+/** The run as its whole timeline leaves it. */
 export function reconstructFinalState(timeline) {
     return reconstructStateAt(timeline, timeline.length - 1);
 }
 function derivePhase(steps) {
     if (steps.length === 0)
         return 'pending';
-    if (steps.some((s) => IN_FLIGHT.has(s.status)))
+    if (steps.some((s) => STEP_IN_FLIGHT_STATES.has(s.status)))
         return 'running';
     if (steps.some((s) => s.status === 'failed'))
         return 'failed';

package/dist/wirings/workflow/scenario-coverage.d.ts

@@ -33,6 +33,7 @@ export interface UncoveredMutation {
     id: string;
     sourceFile?: string;
 }
+/** How much of the app the scenario suite exercises: API lines, user mutations and routes. */
 export interface ScenarioCoverage {
     /** Line coverage across every scenario; `null` until a run with `--coverage` has been recorded. */
     api: {

package/dist/wirings/workflow/scenario-poll.d.ts

@@ -1,3 +1,4 @@
+/** How long `pollUntil` keeps trying (default 15s) and how often (default 250ms). */
 export interface PollOptions {
     timeoutMs?: number;
     intervalMs?: number;

package/dist/wirings/workflow/scenario-prose.d.ts

@@ -1,5 +1,11 @@
 import type { ScenarioStepPhase } from './scenario-step.types.js';
+/**
+ * Fills a step template's `{key}` placeholders from its input, collapsing whitespace. Missing values render as empty.
+ */
 export declare const renderStepTemplate: (template: string, input: unknown) => string;
+/**
+ * Renders one scenario step as a Gherkin-style sentence — keyword, virtual user, then the step text.
+ */
 export declare const composeStepProse: ({ phase, description, template, input, virtualUser, virtualUserRole, continuesPhase, continuesVirtualUser, keywordWidth, }: {
     phase: ScenarioStepPhase;
     description: string;

package/dist/wirings/workflow/scenario-prose.js

@@ -1,3 +1,6 @@
+/**
+ * Fills a step template's `{key}` placeholders from its input, collapsing whitespace. Missing values render as empty.
+ */
 export const renderStepTemplate = (template, input) => {
     const values = input && typeof input === 'object' ? input : {};
     return template
@@ -14,6 +17,9 @@ const formatValue = (value) => {
     }
     return String(value);
 };
+/**
+ * Renders one scenario step as a Gherkin-style sentence — keyword, virtual user, then the step text.
+ */
 export const composeStepProse = ({ phase, description, template, input, virtualUser, virtualUserRole, continuesPhase, continuesVirtualUser, keywordWidth, }) => {
     const keyword = capitalise(continuesPhase ? 'and' : phase);
     // The virtual user key is the subject verbatim, with no article in front of it.

package/dist/wirings/workflow/scenario-run.types.d.ts

@@ -93,6 +93,7 @@ export interface ScenarioFailureDetail {
     expected?: boolean;
     browser?: ScenarioBrowserFailure[];
 }
+/** The outcome of one scenario in a run. */
 export interface ScenarioResult {
     name: string;
     /**
@@ -136,6 +137,7 @@ export interface ScenarioSkip {
     name: string;
     reason: string;
 }
+/** Everything one scenario run produced, scenario by scenario. */
 export interface ScenarioRunReport {
     environment: string;
     results: ScenarioResult[];
@@ -149,6 +151,7 @@ export interface ScenarioRunReport {
     /** Feature-level hook failures, which belong to no single scenario. */
     hookFailures: string[];
 }
+/** The state of a whole scenario run. */
 export type ScenarioRunStatus = 'running' | 'passed' | 'failed';
 /**
  * The filters a run was selected with, recorded when it was narrowed at all.

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -43,6 +43,7 @@ export type ScenarioStepKind = 'virtualUser' | 'platform' | 'addon';
  * can never itself fall back.
  */
 export type ScenarioSurface = 'browser' | 'cli' | 'default';
+/** Every {@link ScenarioSurface}, in order of preference. */
 export declare const SCENARIO_SURFACES: readonly ScenarioSurface[];
 /**
  * How a step's declared surfaces resolve for one run.

package/dist/wirings/workflow/scenario-step.types.js

@@ -1,3 +1,4 @@
+/** Every {@link ScenarioSurface}, in order of preference. */
 export const SCENARIO_SURFACES = [
     'browser',
     'cli',

package/dist/wirings/workflow/scenario-surface.js

@@ -1,3 +1,4 @@
+import { stableStringify } from '../../utils/stable-stringify.js';
 /**
  * Resolve which of a step's declared bindings run, for one step, in one run.
  *
@@ -41,16 +42,3 @@ export const witnessesAgree = (a, b) => {
     }
     return stableStringify(a) === stableStringify(b);
 };
-const stableStringify = (value) => {
-    if (value === null || typeof value !== 'object') {
-        return JSON.stringify(value) ?? 'undefined';
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map(stableStringify).join(',')}]`;
-    }
-    const entries = Object.entries(value)
-        .filter(([, v]) => v !== undefined)
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
-    return `{${entries.join(',')}}`;
-};

package/dist/wirings/workflow/scenario.types.d.ts

@@ -1,10 +1,14 @@
 import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
 export type { ScenarioStepInvocation, ScenarioStepMeta, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
 export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, PikkuBrowserWire, ScenarioScreenshotOptions, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
+/**
+ * A scenario a feature runs: the scenario itself, or the scenario paired with the input it runs with.
+ */
 export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
     scenario: CorePikkuFunctionConfig<any, any, any>;
     data: unknown;
 };
+/** What `pikkuFeature` takes: a named group of scenarios, with hooks around them. */
 export type CoreFeature = {
     name: string;
     description?: string;
@@ -25,6 +29,7 @@ export type FeatureMetaEntry = {
     scenario: string;
     data?: unknown;
 };
+/** Generated metadata for one feature. */
 export type FeatureMeta = {
     id: string;
     name: string;
@@ -37,6 +42,7 @@ export type FeatureMeta = {
     hasBefore: boolean;
     hasAfter: boolean;
 };
+/** Generated metadata for every feature, keyed by id. */
 export type FeaturesMeta = Record<string, FeatureMeta>;
 export type FeaturePlanEntry = {
     featureId: string;

package/dist/wirings/workflow/workflow-approval-policy.d.ts

@@ -1,6 +1,12 @@
 import { ForbiddenError } from '../../errors/errors.js';
 import type { CoreUserSession } from '../../types/core.types.js';
 import type { ApprovalDecider, WorkflowApprovalPolicy } from './dsl/workflow-dsl.types.js';
+/**
+ * A decision on an approval gate was refused by the gate's declared policy:
+ * the decider lacks its `approverScope`, or is not the permitted approver under
+ * `approvers` (`owner` or `not-initiator`). Responds 403; the refusal is
+ * audited before it is thrown.
+ */
 export declare class WorkflowApprovalForbiddenError extends ForbiddenError {
     payload: {
         reason: string;

package/dist/wirings/workflow/workflow-approval-policy.js

@@ -1,5 +1,11 @@
 import { ForbiddenError } from '../../errors/errors.js';
 import { addError } from '../../errors/error-handler.js';
+/**
+ * A decision on an approval gate was refused by the gate's declared policy:
+ * the decider lacks its `approverScope`, or is not the permitted approver under
+ * `approvers` (`owner` or `not-initiator`). Responds 403; the refusal is
+ * audited before it is thrown.
+ */
 export class WorkflowApprovalForbiddenError extends ForbiddenError {
     payload;
     constructor(reason, detail) {

package/dist/wirings/workflow/workflow-constants.d.ts

@@ -1,8 +1,14 @@
+import type { StepStatus } from './workflow.types.js';
+/**
+ * How many times a failed step is retried when neither the step nor the app's `workflow.retries` config says.
+ */
 export declare const DEFAULT_STEP_RETRIES = 5;
 /** Statuses from which a run never advances again on its own. */
 export declare const WORKFLOW_END_STATES: ReadonlySet<string>;
 /** Statuses a run cannot leave at all. */
 export declare const WORKFLOW_TERMINAL_STATES: ReadonlySet<string>;
+/** Step statuses that mean the step has not settled yet. */
+export declare const STEP_IN_FLIGHT_STATES: ReadonlySet<StepStatus>;
 export declare const NO_COMPENSATE_STATE_PREFIX = "noCompensate:";
 export declare const MILESTONE_STEP_PREFIX = "__milestone__:";
 export declare const milestoneStepName: (name: string) => string;
@@ -72,4 +78,4 @@ export declare const isStepLeaseLive: (leaseExpiresAt: Date | null | undefined,
 export declare const RUN_LEASE_RETRY_MS = 1000;
 /** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
 export declare const REDISPATCH_BACKOFF_MAX_ENTRIES = 10000;
-export { COMPENSATION_STEP_SUFFIX, compensationStepName, forwardStepName, isCompensationStepName, } from '../../function/compensation-name.js';
+export { COMPENSATION_STEP_SUFFIX, compensationStepName, forwardStepName, isCompensationStepName, } from '../../compensation-name.js';

package/dist/wirings/workflow/workflow-constants.js

@@ -1,3 +1,6 @@
+/**
+ * How many times a failed step is retried when neither the step nor the app's `workflow.retries` config says.
+ */
 export const DEFAULT_STEP_RETRIES = 5;
 /** Statuses from which a run never advances again on its own. */
 export const WORKFLOW_END_STATES = new Set([
@@ -16,6 +19,12 @@ export const WORKFLOW_TERMINAL_STATES = new Set([
     'compensated',
     'compensation_failed',
 ]);
+/** Step statuses that mean the step has not settled yet. */
+export const STEP_IN_FLIGHT_STATES = new Set([
+    'pending',
+    'scheduled',
+    'running',
+]);
 export const NO_COMPENSATE_STATE_PREFIX = 'noCompensate:';
 export const MILESTONE_STEP_PREFIX = '__milestone__:';
 export const milestoneStepName = (name) => `${MILESTONE_STEP_PREFIX}${name}`;
@@ -85,4 +94,4 @@ export const isStepLeaseLive = (leaseExpiresAt, now = Date.now()) => leaseExpire
 export const RUN_LEASE_RETRY_MS = 1_000;
 /** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
 export const REDISPATCH_BACKOFF_MAX_ENTRIES = 10_000;
-export { COMPENSATION_STEP_SUFFIX, compensationStepName, forwardStepName, isCompensationStepName, } from '../../function/compensation-name.js';
+export { COMPENSATION_STEP_SUFFIX, compensationStepName, forwardStepName, isCompensationStepName, } from '../../compensation-name.js';

package/dist/wirings/workflow/workflow-errors.d.ts

@@ -18,11 +18,15 @@ export declare class WorkflowCancelledException extends Error {
     readonly reason?: string | undefined;
     constructor(runId: string, reason?: string | undefined);
 }
+/**
+ * Thrown to stop a run that is now waiting to be resumed — a `suspend`, an approval gate. Not a failure.
+ */
 export declare class WorkflowSuspendedException extends Error {
     readonly runId: string;
     readonly reason: string;
     constructor(runId: string, reason: string);
 }
+/** A step could not be queued; the queue's error is the `cause`. */
 export declare class WorkflowDispatchException extends Error {
     readonly runId: string;
     readonly stepName: string;
@@ -30,9 +34,11 @@ export declare class WorkflowDispatchException extends Error {
         cause?: unknown;
     });
 }
+/** No workflow is registered under the name asked for. Responds 404. */
 export declare class WorkflowNotFoundError extends PikkuError {
     constructor(name: string);
 }
+/** No run exists with the id asked for. Responds 404. */
 export declare class WorkflowRunNotFoundError extends PikkuError {
     constructor(runId: string);
 }
@@ -45,6 +51,9 @@ export declare class WorkflowRunFailedError extends PikkuError {
 export declare class WorkflowRunCancelledError extends PikkuError {
     constructor();
 }
+/**
+ * The approval gate already has a recorded outcome, so a second decision is refused. Responds 409.
+ */
 export declare class WorkflowApprovalResolvedError extends PikkuError {
     payload: {
         reason: string;
@@ -52,6 +61,10 @@ export declare class WorkflowApprovalResolvedError extends PikkuError {
     };
     constructor(reason: string, outcome: ApprovalOutcome<unknown>['status']);
 }
+/**
+ * A queued step named a different function from the one the workflow recorded
+ * when it dispatched the step, so the worker refuses to run it. Responds 409.
+ */
 export declare class WorkflowStepFunctionMismatchError extends PikkuError {
     readonly runId: string;
     readonly stepName: string;

package/dist/wirings/workflow/workflow-errors.js

@@ -27,6 +27,9 @@ export class WorkflowCancelledException extends Error {
         this.name = 'WorkflowCancelledException';
     }
 }
+/**
+ * Thrown to stop a run that is now waiting to be resumed — a `suspend`, an approval gate. Not a failure.
+ */
 export class WorkflowSuspendedException extends Error {
     runId;
     reason;
@@ -37,6 +40,7 @@ export class WorkflowSuspendedException extends Error {
         this.name = 'WorkflowSuspendedException';
     }
 }
+/** A step could not be queued; the queue's error is the `cause`. */
 export class WorkflowDispatchException extends Error {
     runId;
     stepName;
@@ -47,6 +51,7 @@ export class WorkflowDispatchException extends Error {
         this.name = 'WorkflowDispatchException';
     }
 }
+/** No workflow is registered under the name asked for. Responds 404. */
 export class WorkflowNotFoundError extends PikkuError {
     constructor(name) {
         super(`Workflow not found: ${name}`);
@@ -56,6 +61,7 @@ addError(WorkflowNotFoundError, {
     status: 404,
     message: 'Workflow not found.',
 });
+/** No run exists with the id asked for. Responds 404. */
 export class WorkflowRunNotFoundError extends PikkuError {
     constructor(runId) {
         super(`Workflow run not found: ${runId}`);
@@ -85,6 +91,9 @@ addError(WorkflowRunCancelledError, {
     status: 409,
     message: 'Workflow was cancelled.',
 });
+/**
+ * The approval gate already has a recorded outcome, so a second decision is refused. Responds 409.
+ */
 export class WorkflowApprovalResolvedError extends PikkuError {
     payload;
     constructor(reason, outcome) {
@@ -96,6 +105,10 @@ addError(WorkflowApprovalResolvedError, {
     status: 409,
     message: 'Approval has already been resolved.',
 });
+/**
+ * A queued step named a different function from the one the workflow recorded
+ * when it dispatched the step, so the worker refuses to run it. Responds 409.
+ */
 export class WorkflowStepFunctionMismatchError extends PikkuError {
     runId;
     stepName;

package/dist/wirings/workflow/workflow-invocation-id.d.ts

@@ -1,2 +1,6 @@
+/** A name-based (version 5) UUID, deterministic for the same name and namespace. */
 export declare const uuidv5: (name: string, namespace?: string) => string;
+/**
+ * A stable id for one step of one run, the same on every retry and replay — usable as an idempotency key.
+ */
 export declare const deriveInvocationId: (runId: string, stepName: string) => string;

package/dist/wirings/workflow/workflow-invocation-id.js

@@ -81,6 +81,7 @@ const sha1 = (message) => {
     [h0, h1, h2, h3, h4].forEach((h, i) => outView.setUint32(i * 4, h));
     return out;
 };
+/** A name-based (version 5) UUID, deterministic for the same name and namespace. */
 export const uuidv5 = (name, namespace = PIKKU_WORKFLOW_NAMESPACE) => {
     const ns = parseUuid(namespace);
     const nameBytes = encoder.encode(name);
@@ -92,4 +93,7 @@ export const uuidv5 = (name, namespace = PIKKU_WORKFLOW_NAMESPACE) => {
     bytes[8] = (bytes[8] & 0x3f) | 0x80;
     return formatUuid(bytes);
 };
+/**
+ * A stable id for one step of one run, the same on every retry and replay — usable as an idempotency key.
+ */
 export const deriveInvocationId = (runId, stepName) => uuidv5(`${runId}:${stepName}`);

package/dist/wirings/workflow/workflow-queue-workers.d.ts

@@ -1,4 +1,5 @@
 import type { PikkuRPC } from '../rpc/rpc-types.js';
+/** The job the workflow step-worker queue carries: one step of one run. */
 export interface WorkflowStepInput {
     runId: string;
     stepName: string;
@@ -6,9 +7,11 @@ export interface WorkflowStepInput {
     data: unknown;
     fromStepName?: string;
 }
+/** The job the workflow orchestrator queue carries: a run to advance. */
 export interface PikkuWorkflowOrchestratorInput {
     runId: string;
 }
+/** The job that wakes a run when a `sleep` step's duration has passed. */
 export interface PikkuWorkflowSleeperInput {
     runId: string;
     stepId: string;

package/dist/wirings/workflow/workflow-run-ownership.d.ts

@@ -1,6 +1,7 @@
 import { ForbiddenError } from '../../errors/errors.js';
 import type { CoreUserSession } from '../../types/core.types.js';
 import type { WorkflowRunWire } from './workflow.types.js';
+/** The caller is not the user who started this workflow run. Responds 403. */
 export declare class WorkflowRunForbiddenError extends ForbiddenError {
     constructor();
 }

package/dist/wirings/workflow/workflow-run-ownership.js

@@ -1,5 +1,6 @@
 import { ForbiddenError } from '../../errors/errors.js';
 import { addError } from '../../errors/error-handler.js';
+/** The caller is not the user who started this workflow run. Responds 403. */
 export class WorkflowRunForbiddenError extends ForbiddenError {
     constructor() {
         super('Not authorized to access this workflow run');

package/dist/wirings/workflow/workflow-status-stream.d.ts

@@ -1,6 +1,7 @@
 import type { CoreUserSession } from '../../types/core.types.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 import type { WorkflowRunService } from './workflow.types.js';
+/** What `streamWorkflowRunStatus` streams, to whom, and how much detail it includes. */
 export interface WorkflowStatusStreamParams {
     workflowRunService: WorkflowRunService;
     runId: string;