@pikku/core 0.12.63 → 0.12.66

package/dist/wirings/scope/validate-scope-definitions.d.ts

@@ -0,0 +1,16 @@
+import type { FlatScope, ScopeDefinitions, ScopeDefinitionsMeta } from './scope.types.js';
+/**
+ * Flattens declared scope trees into the full list of grantable scope ids,
+ * depth-first. Every node is emitted, including intermediate ones.
+ *
+ * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
+ * the declared set into its store.
+ */
+export declare const flattenScopeDefinitions: (definitions: ScopeDefinitions) => FlatScope[];
+/**
+ * Validates declared scopes and keys them by name.
+ *
+ * Definitions sharing a name must be identical; a conflicting redeclaration is
+ * a hard error naming both source files.
+ */
+export declare function validateAndBuildScopeDefinitionsMeta(definitions: ScopeDefinitions): ScopeDefinitionsMeta;

package/dist/wirings/scope/validate-scope-definitions.js

@@ -0,0 +1,76 @@
+const SEPARATOR = ':';
+const WILDCARD = '*';
+const assertSegment = (segment, scopeName) => {
+    if (segment.includes(SEPARATOR)) {
+        throw new Error(`Scope segment '${segment}' in '${scopeName}' contains the '${SEPARATOR}' separator. ` +
+            `Nest scopes with the 'scopes' property instead of embedding '${SEPARATOR}' in a name.`);
+    }
+    if (segment === WILDCARD) {
+        throw new Error(`Scope segment '${segment}' in '${scopeName}' is the wildcard. ` +
+            `'${WILDCARD}' is reserved for granting a scope and its descendants, and cannot be declared.`);
+    }
+    if (segment.length === 0) {
+        throw new Error(`Scope '${scopeName}' contains an empty segment.`);
+    }
+};
+const assertNodesValid = (nodes, scopeName) => {
+    for (const [segment, node] of Object.entries(nodes ?? {})) {
+        assertSegment(segment, scopeName);
+        assertNodesValid(node.scopes, scopeName);
+    }
+};
+const flattenNodes = (nodes, prefix, out) => {
+    for (const [segment, node] of Object.entries(nodes ?? {})) {
+        const id = `${prefix}${SEPARATOR}${segment}`;
+        out.push({ id, description: node.description });
+        flattenNodes(node.scopes, id, out);
+    }
+};
+/**
+ * Flattens declared scope trees into the full list of grantable scope ids,
+ * depth-first. Every node is emitted, including intermediate ones.
+ *
+ * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
+ * the declared set into its store.
+ */
+export const flattenScopeDefinitions = (definitions) => {
+    const out = [];
+    for (const def of definitions) {
+        out.push({ id: def.name, description: def.description });
+        flattenNodes(def.scopes, def.name, out);
+    }
+    return out;
+};
+/**
+ * Validates declared scopes and keys them by name.
+ *
+ * Definitions sharing a name must be identical; a conflicting redeclaration is
+ * a hard error naming both source files.
+ */
+export function validateAndBuildScopeDefinitionsMeta(definitions) {
+    const meta = {};
+    for (const def of definitions) {
+        assertSegment(def.name, def.name);
+        assertNodesValid(def.scopes, def.name);
+        const existing = meta[def.name];
+        if (existing) {
+            const sameShape = JSON.stringify(existing.scopes ?? {}) ===
+                JSON.stringify(def.scopes ?? {});
+            if (!sameShape) {
+                throw new Error(`Scope '${def.name}' is declared with different nested scopes.\n` +
+                    `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
+                    `  Second declaration: ${def.sourceFile ?? 'unknown'}\n` +
+                    `Scopes sharing a name must declare the same tree.`);
+            }
+            continue;
+        }
+        meta[def.name] = {
+            name: def.name,
+            displayName: def.displayName,
+            description: def.description,
+            scopes: def.scopes,
+            sourceFile: def.sourceFile,
+        };
+    }
+    return meta;
+}

package/dist/wirings/scope/wire-scope.d.ts

@@ -0,0 +1,33 @@
+import type { CoreScopes } from './scope.types.js';
+/**
+ * No-op function for declaring scopes.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `ScopeId` union,
+ * so a function referencing an undeclared scope fails the build.
+ *
+ * Scopes are keyed by segment at every level: a scope is named by its key, and
+ * its value describes it. Every node is grantable — the declaration below
+ * yields `admin`, `admin:invoices`, `admin:invoices:create`,
+ * `admin:invoices:void` and `billing`.
+ *
+ * @example
+ * ```typescript
+ * wireScope({
+ *   admin: {
+ *     displayName: 'Administration',
+ *     description: 'Administrative access',
+ *     scopes: {
+ *       invoices: {
+ *         description: 'Invoice management',
+ *         scopes: {
+ *           create: { description: 'Create invoices' },
+ *           void: { description: 'Void invoices' },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   billing: {},
+ * })
+ * ```
+ */
+export declare const wireScope: (_config: CoreScopes) => void;

package/dist/wirings/scope/wire-scope.js

@@ -0,0 +1,32 @@
+/**
+ * No-op function for declaring scopes.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `ScopeId` union,
+ * so a function referencing an undeclared scope fails the build.
+ *
+ * Scopes are keyed by segment at every level: a scope is named by its key, and
+ * its value describes it. Every node is grantable — the declaration below
+ * yields `admin`, `admin:invoices`, `admin:invoices:create`,
+ * `admin:invoices:void` and `billing`.
+ *
+ * @example
+ * ```typescript
+ * wireScope({
+ *   admin: {
+ *     displayName: 'Administration',
+ *     description: 'Administrative access',
+ *     scopes: {
+ *       invoices: {
+ *         description: 'Invoice management',
+ *         scopes: {
+ *           create: { description: 'Create invoices' },
+ *           void: { description: 'Void invoices' },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   billing: {},
+ * })
+ * ```
+ */
+export const wireScope = (_config) => { };

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

@@ -4,6 +4,13 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     /**
      * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
      * Stored in the generated secrets metadata so consumers can tell when a
@@ -25,6 +32,13 @@ export type SecretDefinitionMeta = {
     description?: string;
     secretId: string;
     schema?: Record<string, unknown> | string;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     oauth2?: OAuth2CredentialConfig;
     rotationPeriod?: string;
     sourceFile?: string;

package/dist/wirings/secret/validate-secret-definitions.js

@@ -34,6 +34,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                     schema: def.schema,
                     oauth2: def.oauth2,
                     rotationPeriod: def.rotationPeriod,
+                    docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
             }
@@ -49,6 +50,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                 schema: def.schema,
                 oauth2: def.oauth2,
                 rotationPeriod: def.rotationPeriod,
+                docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };
         }

package/dist/wirings/variable/validate-variable-definitions.js

@@ -24,6 +24,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                     description: def.description,
                     variableId: def.variableId,
                     schema: def.schema,
+                    docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
             }
@@ -37,6 +38,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                 description: def.description,
                 variableId: def.variableId,
                 schema: def.schema,
+                docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };
         }

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

@@ -4,6 +4,13 @@ export type CoreVariable<T = unknown> = {
     description?: string;
     variableId: string;
     schema: T;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
     name: string;
@@ -11,6 +18,13 @@ export type VariableDefinitionMeta = {
     description?: string;
     variableId: string;
     schema?: Record<string, unknown> | string;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     sourceFile?: string;
 };
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;

package/dist/wirings/workflow/dsl/index.d.ts

@@ -2,4 +2,4 @@
  * DSL (Domain Specific Language) workflow exports
  */
 export { addWorkflow } from './workflow-runner.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';

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

@@ -2,6 +2,7 @@
  * DSL (Domain Specific Language) workflow types
  * These types define the step-based workflow format extracted by the inspector
  */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { WorkflowRun } from '../workflow.types.js';
 import type { ScenarioActor } from '../../../services/scenario-actors-service.js';
 /**
@@ -14,6 +15,13 @@ export interface WorkflowStepOptions {
     retries?: number;
     /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
     retryDelay?: string | number;
+    /**
+     * RPC to invoke for compensation when this step fails after exhausting its
+     * retries. Mirrors a graph node's `onError`: the handler receives
+     * `{ error: { message } }` and the original error is still thrown, so the
+     * workflow fails — this is compensation, not recovery.
+     */
+    onError?: string;
     /**
      * Run this step as an actor (scenarios). The RPC is sent through the
      * actor's authenticated client over the REAL transport — never dispatched
@@ -64,6 +72,43 @@ export type WorkflowWireSleep = (stepName: string, duration: string) => Promise<
  * loops, like dynamic `do()` step names.
  */
 export type WorkflowWireSuspend = (reason: string) => Promise<void>;
+/**
+ * Options for workflow.approval().
+ */
+export interface WorkflowApprovalOptions<TSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    /**
+     * Schema the decision payload is validated against. This is a VALUE, not a
+     * type generic: the payload arrives from an untrusted caller over the approve
+     * wire, and a generic is erased at compile time — it would validate nothing.
+     * Any standard-schema library (zod, valibot, arktype) satisfies this.
+     */
+    schema: TSchema;
+    /**
+     * Give up waiting after this long (e.g. '3d'), yielding `{ status: 'expired' }`
+     * instead of waiting forever. Evaluated on replay from a recorded deadline, so
+     * the answer is correct even if the wake-up timer is never delivered.
+     */
+    expiry?: string | number;
+}
+/**
+ * The result of an approval gate. A union rather than a throw so that callers
+ * must handle the deadline case, and so "skip it and carry on" stays trivial.
+ * `decided` means a human answered — whether that answer was yes or no is
+ * carried in `data` and is the application's business, not the framework's.
+ */
+export type ApprovalOutcome<T> = {
+    status: 'decided';
+    data: T;
+} | {
+    status: 'expired';
+};
+/**
+ * Type signature for workflow.approval() - used by inspector.
+ * Like {@link WorkflowWireSuspend}, `reason` is the approval point's stable
+ * durable identity. Unlike suspend, the gate stays closed until a decision is
+ * recorded against it, and the decision is handed back to the caller.
+ */
+export type WorkflowWireApproval = <TSchema extends StandardSchemaV1>(reason: string, options: WorkflowApprovalOptions<TSchema>) => Promise<ApprovalOutcome<StandardSchemaV1.InferOutput<TSchema>>>;
 /**
  * Input source for step arguments in DSL workflows
  */
@@ -176,16 +221,20 @@ export interface ParallelGroupStepMeta {
  */
 export interface FanoutStepMeta {
     type: 'fanout';
-    /** Step name for this fanout */
-    stepName: string;
+    /**
+     * Step name for this fanout. Optional: a fanout is not itself a cached step,
+     * and node ids are step names — borrowing a body step's name would give the
+     * loop and that step the same id, collapsing one onto the other.
+     */
+    stepName?: string;
     /** Source array variable name */
     sourceVar: string;
     /** Iterator variable name */
     itemVar: string;
     /** Execution mode */
     mode: 'parallel' | 'sequential';
-    /** Child step to execute per iteration */
-    child: RpcStepMeta;
+    /** Steps to execute inline per iteration, in order */
+    body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>;
     /** Time between iterations (sequential mode only) */
     timeBetween?: string;
 }
@@ -196,6 +245,12 @@ export interface ReturnStepMeta {
     type: 'return';
     /** Output bindings */
     outputs: Record<string, OutputBinding>;
+    /**
+     * Variables spread into the returned object (`return { ...r }`), or the sole
+     * returned variable (`return r`). Their fields are not enumerable statically,
+     * so they are recorded by name rather than expanded into `outputs`.
+     */
+    spread?: string[];
 }
 /**
  * Inline step metadata (legacy support)
@@ -220,6 +275,13 @@ export interface SleepStepMeta {
     stepName: string;
     /** Sleep duration */
     duration: string | number;
+    /**
+     * Source text of a duration only known at runtime (e.g. a loop variable).
+     * The closure evaluates it, so it is legal DSL; it is kept separate from
+     * `duration` so regenerated code emits it raw rather than as a string
+     * literal, exactly as `expression` does on a set step.
+     */
+    expression?: string;
 }
 /**
  * Cancel step metadata
@@ -238,8 +300,14 @@ export interface SetStepMeta {
     type: 'set';
     /** Variable name to set (must be in context) */
     variable: string;
-    /** Value to assign (literal or expression) */
-    value: unknown;
+    /** Literal value to assign. Mutually exclusive with `expression`. */
+    value?: unknown;
+    /**
+     * Source text of a non-literal assignment (e.g. `count + 1`). Kept separate
+     * from `value` so regenerated code can emit it raw — a string `value` is a
+     * string literal, an `expression` is code.
+     */
+    expression?: string;
 }
 /**
  * Switch case metadata
@@ -272,6 +340,18 @@ export interface SuspendStepMeta {
     /** Reason string passed to workflow.suspend() — becomes the durable step key */
     reason: string;
 }
+/**
+ * Approval step metadata (workflow.approval())
+ */
+export interface ApprovalStepMeta {
+    type: 'approval';
+    /** Reason string passed to workflow.approval() — becomes the durable step key */
+    reason: string;
+    /** Output variable name (if assigned) */
+    outputVar?: string;
+    /** Expiry duration, when one was given */
+    expiry?: string | number;
+}
 /**
  * Filter step metadata (array.filter)
  */
@@ -305,7 +385,7 @@ export interface ArrayPredicateStepMeta {
 /**
  * Workflow step metadata (extracted by inspector)
  */
-export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
+export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | ApprovalStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
 /**
  * Workflow step wire context for RPC functions
  * Provides step-level metadata including retry attempt tracking
@@ -355,6 +435,8 @@ export interface PikkuWorkflowWire {
     sleep: WorkflowWireSleep;
     /** Suspend workflow until explicitly resumed */
     suspend: WorkflowWireSuspend;
+    /** Suspend workflow until a human records a decision against this gate */
+    approval: WorkflowWireApproval;
 }
 export interface PikkuScenarioWire extends PikkuWorkflowWire {
     /**

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

@@ -93,6 +93,8 @@ type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends R
         onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[];
         retries?: number;
         retryDelay?: string | number;
+        /** Free-text node documentation. Non-semantic — excluded from graphHash. */
+        notes?: string;
     };
 };
 /**

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

@@ -246,6 +246,9 @@ function resolveTemplate(template, nodeResults) {
 }
 function resolveValue(value, nodeResults) {
     if (isDataRef(value)) {
+        if (value.$ref === '$item') {
+            return value;
+        }
         const source = nodeResults[value.$ref];
         return value.path ? getValueAtPath(source, value.path) : source;
     }

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

@@ -5,11 +5,17 @@ export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>
     tags?: string[];
     nodes: FuncMap;
     config?: T;
+    /**
+     * Graph-level free-text notes (e.g. imported sticky notes). Non-semantic:
+     * excluded from the graph topology hash.
+     */
+    notes?: string[];
 }
 export interface PikkuWorkflowGraphResult {
     __type: 'pikkuWorkflowGraph';
     name?: string;
     description?: string;
     tags?: string[];
+    notes?: string[];
 }
 export declare function pikkuWorkflowGraph<const FuncMap extends Record<string, string>>(config: PikkuWorkflowGraphConfig<FuncMap, any>): PikkuWorkflowGraphResult;

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

@@ -4,5 +4,6 @@ export function pikkuWorkflowGraph(config) {
         name: config.name,
         description: config.description,
         tags: config.tags,
+        notes: config.notes,
     };
 }

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

@@ -49,6 +49,11 @@ export interface GraphNodeConfig<NodeIds extends string = string> {
     retries?: number;
     /** Delay between retries — milliseconds, duration string, or 'exponential' */
     retryDelay?: string | number;
+    /**
+     * Free-text documentation for this node. Non-semantic: excluded from the
+     * graph topology hash, so editing a note never marks the workflow as changed.
+     */
+    notes?: string;
 }
 /**
  * Graph wire context - available to functions running in a workflow graph

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

@@ -1,7 +1,7 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 export type { RunTimeline, RunTimelineEvent, ReconstructedRunState, ReconstructedStep, RunPhase, } from './run-timeline.js';
@@ -12,4 +12,4 @@ export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-vali
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
 export type { WorkflowService, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';

package/dist/wirings/workflow/index.js

@@ -1,7 +1,7 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 // Time-travel: reconstruct run state at any point from durable history
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';

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

@@ -1,5 +1,5 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, 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';
@@ -70,6 +70,19 @@ export declare class WorkflowRunFailedError extends PikkuError {
 export declare class WorkflowRunCancelledError extends PikkuError {
     constructor();
 }
+/**
+ * A decision arrived for an approval gate that has already resolved. The gate
+ * caches its outcome as the step result and never re-reads run state, so the
+ * decision could not take effect — it is rejected rather than accepted and
+ * dropped.
+ */
+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 {
@@ -430,6 +443,14 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * loop exits immediately without recording a step error or retrying.
      */
     private runInlineRetryLoop;
+    /**
+     * Run a failed step's compensation handler as a durable step of its own.
+     *
+     * Durable rather than a bare invoke so a replay does not compensate twice —
+     * a handler is typically a refund or a rollback. `onError` is deliberately
+     * not forwarded: a compensation handler cannot itself compensate.
+     */
+    private runStepCompensation;
     private rpcStep;
     private inlineStep;
     private sleepStep;
@@ -446,6 +467,43 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     private getSuspendStepName;
     private suspendStep;
+    /**
+     * Wake a run later by enqueuing a delayed orchestrator pass. Deliberately NOT
+     * {@link scheduleSleep}: that resolves the step it is given, which for an
+     * approval would resolve the gate itself. This only nudges the run to replay
+     * and re-evaluate — the gate stays the sole judge of its own outcome.
+     *
+     * Best-effort by design. Expiry is decided from the recorded deadline on
+     * replay, so losing this wake costs liveness (the run sits until something
+     * else resumes it), never correctness.
+     */
+    private scheduleRunWake;
+    /**
+     * Durable step name for an approval gate. Namespaced separately from suspend
+     * so the two can't collide, and derived from `reason` for the same reason
+     * {@link getSuspendStepName} is: it must be stable across replays.
+     */
+    private getApprovalStepName;
+    /**
+     * Run-state key holding an approval gate's record. Hex-encoded because the
+     * Mongo backend restricts state keys to `/^[a-zA-Z0-9_]+$/` and a `reason` is
+     * arbitrary human text. One key per gate, so two gates resolving concurrently
+     * can't clobber each other through a read-modify-write.
+     */
+    private approvalStateKey;
+    /**
+     * Record a decision against an approval gate and wake the run. Called from
+     * outside the workflow (an HTTP route, an RPC), so the schema value is NOT in
+     * scope here — the payload is stored raw and validated on replay inside the
+     * workflow body, which is the only place the schema exists. An invalid payload
+     * therefore leaves the gate closed rather than failing the run.
+     *
+     * `reason` addresses the first reach of that gate. An approval reached more
+     * than once under the same reason (e.g. in a loop) gets `#N`-suffixed step
+     * rows that this cannot currently target.
+     */
+    approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
+    private approvalStep;
     createWorkflowWire(name: string, runId: string, rpcService: any, addonNamespace?: string | null): PikkuScenarioWire;
     private verifyStepName;
     private getConfig;