@pikku/core 0.12.143 → 0.12.145

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;

package/dist/wirings/workflow/workflow-unwind-plan.js

@@ -1,9 +1,4 @@
-import { isCompensationStepName, isMilestoneStepName, } from './workflow-constants.js';
-const IN_FLIGHT = new Set([
-    'pending',
-    'scheduled',
-    'running',
-]);
+import { isCompensationStepName, isMilestoneStepName, STEP_IN_FLIGHT_STATES, } from './workflow-constants.js';
 const startedAt = (record) => record.createdAt.getTime();
 const finishedAt = (record) => (record.succeededAt ?? record.failedAt ?? record.updatedAt).getTime();
 export function planUnwind(input) {
@@ -16,7 +11,7 @@ export function planUnwind(input) {
         .sort((a, b) => finishedAt(b) - finishedAt(a) ||
         input.records.indexOf(b) - input.records.indexOf(a));
     const lastMilestone = milestones[0];
-    const forwardInFlight = forward.some((r) => IN_FLIGHT.has(r.status) && input.hasCompensation(r));
+    const forwardInFlight = forward.some((r) => STEP_IN_FLIGHT_STATES.has(r.status) && input.hasCompensation(r));
     let candidates = forward.filter((r) => {
         if (!r.rpcName || input.skip.has(r.stepName))
             return false;

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

@@ -6,6 +6,10 @@ import type { LeaseService } from '../../services/lease-service.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, MilestoneStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
+/**
+ * How a run was started: the wire type, the parent run and step for a child
+ * workflow, and the user whose session started it — who becomes its owner.
+ */
 export interface WorkflowRunWire {
     type: string;
     id?: string;
@@ -13,6 +17,9 @@ export interface WorkflowRunWire {
     parentStepId?: string;
     pikkuUserId?: string;
 }
+/**
+ * The resolved `workflow` section of the app config: default retries and the queue names the engine uses.
+ */
 export interface WorkflowServiceConfig {
     retries: number;
     retryDelay: number;
@@ -20,6 +27,13 @@ export interface WorkflowServiceConfig {
     stepWorkerQueueName: string;
     sleeperRPCName: string;
 }
+/**
+ * How a workflow service routes its jobs. `per-workflow` (the default) uses a
+ * workflow's dedicated queue when one is declared; `shared-groups` sends every
+ * job through the shared queues, grouped by workflow, with
+ * `queueGroupConcurrency` (default 2) per group. `queueConcurrency` defaults
+ * to 20.
+ */
 export interface WorkflowQueueOptions {
     queueStrategy?: 'per-workflow' | 'shared-groups';
     queueConcurrency?: number;
@@ -34,13 +48,20 @@ export interface WorkflowQueueOptions {
 export interface WorkflowServiceOptions extends WorkflowQueueOptions {
     leaseService: LeaseService;
 }
+/** A step a deterministic workflow is known to run, before it runs. */
 export interface WorkflowPlannedStep {
     stepName: string;
     displayName?: string;
 }
+/**
+ * Where a run stands. `compensating` and the two after it belong to a saga unwinding after a failure.
+ */
 export type WorkflowStatus = 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled' | 'compensating' | 'compensated' | 'compensation_failed';
+/** Whether a recorded version of a workflow's graph may be run. */
 export type WorkflowVersionStatus = 'draft' | 'active' | 'declined';
+/** Where one step attempt stands. */
 export type StepStatus = 'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed' | 'suspended';
+/** One stored workflow run. */
 export interface WorkflowRun {
     id: string;
     workflow: string;
@@ -56,6 +77,7 @@ export interface WorkflowRun {
     createdAt: Date;
     updatedAt: Date;
 }
+/** One stored attempt at a workflow step. */
 export interface StepState {
     stepId: string;
     status: StepStatus;
@@ -89,6 +111,7 @@ export interface StepState {
     succeededAt?: Date;
     failedAt?: Date;
 }
+/** A run summarised for display: status, steps and outcome. */
 export interface WorkflowRunStatus {
     id: string;
     status: WorkflowStatus;
@@ -112,6 +135,11 @@ export interface WorkflowRunStatus {
         error: string;
     }>;
 }
+/**
+ * Read and delete access to stored workflow runs, for consoles and status
+ * routes. It applies no ownership check of its own: callers that expose it to
+ * users check with `assertWorkflowRunOwner` first.
+ */
 export interface WorkflowRunService {
     listRuns(options?: {
         workflowName?: string;
@@ -135,6 +163,11 @@ export interface WorkflowRunService {
     } | null>;
     deleteRun(id: string): Promise<boolean>;
 }
+/**
+ * A secondary store that receives a copy of every write a workflow service
+ * makes — for reporting or a console database. A failed mirror write is logged
+ * and ignored, and the engine never reads from it.
+ */
 export interface WorkflowRunMirror {
     createRun(runId: string, workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
         deterministic?: boolean;
@@ -159,12 +192,14 @@ export interface WorkflowRunMirror {
     upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
     updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
 }
+/** A registered workflow: its name and the function that runs it. */
 export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> = CorePikkuFunctionConfig<any, any, any>> = {
     name: string;
     func: PikkuFunctionConfig;
     middleware?: PikkuFunctionConfig['middleware'];
     tags?: string[];
 };
+/** Start, read and cancel runs of one workflow. */
 export interface PikkuWorkflow {
     start: <I>(input: I) => Promise<{
         runId: string;
@@ -172,12 +207,15 @@ export interface PikkuWorkflow {
     getRun: (runId: string) => Promise<WorkflowRun>;
     cancelRun: (runId: string) => Promise<void>;
 }
+/** One declared workflow context variable: its type, default and description. */
 export interface ContextVariable {
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
     default?: unknown;
     description?: string;
 }
+/** A workflow's declared context variables, keyed by name. */
 export type WorkflowContext = Record<string, ContextVariable>;
+/** Generated metadata for every workflow, keyed by name. */
 export type WorkflowsMeta = Record<string, CommonWireMeta & {
     name: string;
     steps: WorkflowStepMeta[];
@@ -195,6 +233,7 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     skip?: string;
     virtualUsers?: string[];
 }>;
+/** The slice of a workflow's generated metadata the engine needs at run time. */
 export interface WorkflowRuntimeMeta {
     name: string;
     pikkuFuncId: string;
@@ -208,4 +247,5 @@ export interface WorkflowRuntimeMeta {
     deterministic?: boolean;
     plannedSteps?: WorkflowPlannedStep[];
 }
+/** Runtime workflow metadata, keyed by name. */
 export type WorkflowsRuntimeMeta = Record<string, WorkflowRuntimeMeta>;