@pikku/core 0.12.71 → 0.12.74

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

@@ -1,91 +1,21 @@
 import type { GraphNodeConfig, NextConfig, RefValue } from './workflow-graph.types.js';
-/**
- * Standard RPC handler interface (matches generated FlattenedRPCMap entries)
- */
 export interface RPCHandler<I = any, O = any> {
     input: I;
     output: O;
 }
-/**
- * Compute output types for all nodes based on their func (RPC name)
- */
-export type NodeOutputMap<Nodes extends Record<string, {
-    func: string;
-}>, RPCMap extends Record<string, RPCHandler>> = {
-    [K in keyof Nodes]: Nodes[K]['func'] extends keyof RPCMap ? RPCMap[Nodes[K]['func']]['output'] : unknown;
-};
-/**
- * Node definition with RPC name reference
- */
-export interface GraphNodeDef<RPCMap extends Record<string, RPCHandler>, NodeIds extends string = string, NodeOutputs extends Record<string, any> = Record<string, any>> {
-    /** RPC function name (must be a key in RPCMap) */
-    func: keyof RPCMap & string;
-    /** Input mapping - reference outputs from other nodes with autocomplete */
-    input?: (ref: <N extends keyof NodeOutputs & string>(nodeId: N, path: keyof NodeOutputs[N] & string) => RefValue) => Record<string, unknown>;
-    /** Next node(s) to execute */
-    next?: NextConfig<NodeIds>;
-    /** Error handling - node(s) to execute on error */
-    onError?: NodeIds | NodeIds[];
-    /** Maximum retry attempts allowed (excludes the initial attempt) */
-    retries?: number;
-    /** Delay between retries — milliseconds, duration string, or 'exponential' */
-    retryDelay?: string | number;
-}
-/**
- * Helper to create a type-safe graph definition with RPC autocomplete.
- * Pass node IDs as first type parameter for type-safe next/ref/output key completion.
- *
- * @example
- * ```typescript
- * // Import the typed graph from generated types
- * import { pikkuWorkflowGraph } from './.pikku/workflow/pikku-workflow-types.gen.js'
- *
- * export const myGraph = pikkuWorkflowGraph({
- *   name: 'myWorkflow',
- *   nodes: {
- *     entry: 'createUserProfile',  // autocompletes RPC names
- *     sendWelcome: 'sendEmail',
- *   },
- *   config: {
- *     entry: { next: 'sendWelcome' },
- *     sendWelcome: {
- *       input: (ref) => ({
- *         to: ref('entry', 'email'),  // 'entry' and 'email' both autocomplete
- *       }),
- *     },
- *   },
- * })
- * ```
- */
-/**
- * Type to compute output types for all nodes based on their func mapping
- */
 type ComputeNodeOutputs<FuncMap extends Record<string, string>, RPCMap extends Record<string, RPCHandler>> = {
     [K in keyof FuncMap]: FuncMap[K] extends keyof RPCMap ? RPCMap[FuncMap[K]]['output'] : unknown;
 };
-/**
- * Type to compute input types for all nodes based on their func mapping
- */
 type ComputeNodeInputs<FuncMap extends Record<string, string>, RPCMap extends Record<string, RPCHandler>> = {
     [K in keyof FuncMap]: FuncMap[K] extends keyof RPCMap ? RPCMap[FuncMap[K]]['input'] : unknown;
 };
-/**
- * Typed ref value - carries the type of the referenced field as a phantom type.
- * At runtime this is just RefValue, but TypeScript tracks the type T.
- */
 export type TypedRef<T> = RefValue & {
     __phantomType?: T;
 };
-/**
- * Map input type fields to allow TypedRef of matching type as an alternative
- */
 type InputWithRefs<T> = {
     [K in keyof T]: T[K] | TypedRef<T[K]>;
 };
 export declare function createGraph<RPCMap extends Record<string, RPCHandler>>(): <const FuncMap extends Record<string, keyof RPCMap & string>>(funcMap: FuncMap, nodesOrBuilder?: GraphNodeConfigMap<FuncMap, RPCMap> | ((nodes: FuncMap) => GraphNodeConfigMap<FuncMap, RPCMap>)) => Record<Extract<keyof FuncMap, string>, GraphNodeConfig<Extract<keyof FuncMap, string>>>;
-/**
- * Type helper for node configuration map
- */
 type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends Record<string, RPCHandler>> = {
     [K in Extract<keyof FuncMap, string>]?: {
         next?: NextConfig<Extract<keyof FuncMap, string>>;
@@ -93,35 +23,7 @@ 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;
     };
 };
-/**
- * Untyped graph for use without RPC map.
- * Pass node IDs as type parameter for type-safe next/ref, or omit for untyped usage.
- *
- * @example
- * ```typescript
- * // Typed usage - next and ref are type-checked
- * graph<'entry' | 'sendWelcome'>({
- *   entry: { func: 'createUserProfile', next: 'sendWelcome' },
- *   sendWelcome: { func: 'sendEmail', input: (ref) => ({ to: ref('entry', 'email') }) },
- * })
- *
- * // Untyped usage - no type checking on next/ref
- * graph({
- *   entry: { func: 'createUserProfile', next: 'sendWelcome' },
- *   sendWelcome: { func: 'sendEmail' },
- * })
- * ```
- */
-export declare function graph<NodeIds extends string = string>(nodes: Record<NodeIds, {
-    func: string;
-    next?: NextConfig<NodeIds>;
-    input?: (ref: (nodeId: NodeIds, path: string) => RefValue) => Record<string, unknown>;
-    onError?: NodeIds | NodeIds[];
-    retries?: number;
-    retryDelay?: string | number;
-}>): Record<NodeIds, GraphNodeConfig<NodeIds>>;
 export {};

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

@@ -1,6 +1,5 @@
 export function createGraph() {
     return (funcMap, nodesOrBuilder) => {
-        // If no nodes provided, return just the funcMap converted to graph nodes
         if (!nodesOrBuilder) {
             const result = {};
             for (const [nodeId, rpcName] of Object.entries(funcMap)) {
@@ -27,36 +26,3 @@ export function createGraph() {
         return result;
     };
 }
-/**
- * Untyped graph for use without RPC map.
- * Pass node IDs as type parameter for type-safe next/ref, or omit for untyped usage.
- *
- * @example
- * ```typescript
- * // Typed usage - next and ref are type-checked
- * graph<'entry' | 'sendWelcome'>({
- *   entry: { func: 'createUserProfile', next: 'sendWelcome' },
- *   sendWelcome: { func: 'sendEmail', input: (ref) => ({ to: ref('entry', 'email') }) },
- * })
- *
- * // Untyped usage - no type checking on next/ref
- * graph({
- *   entry: { func: 'createUserProfile', next: 'sendWelcome' },
- *   sendWelcome: { func: 'sendEmail' },
- * })
- * ```
- */
-export function graph(nodes) {
-    const result = {};
-    for (const [nodeId, def] of Object.entries(nodes)) {
-        result[nodeId] = {
-            func: def.func,
-            input: def.input,
-            next: def.next,
-            onError: def.onError,
-            retries: def.retries,
-            retryDelay: def.retryDelay,
-        };
-    }
-    return result;
-}

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

@@ -22,7 +22,6 @@ function buildTemplateRegex(nodeId) {
         .join('.+');
     return new RegExp(`^${escaped}$`);
 }
-/** Strip a trailing revisit ordinal (`node#2` → `node`); leaves other names as-is. */
 function stripInstanceOrdinal(name) {
     const hash = name.lastIndexOf('#');
     if (hash <= 0)
@@ -39,7 +38,6 @@ function remapStepNamesToNodeIds(stepNames, nodes, graphName) {
     return stepNames.map((name) => {
         if (nodes[name])
             return name;
-        // Revisit instance (`node#N`) maps to its logical node.
         const base = stripInstanceOrdinal(name);
         if (base !== name && nodes[base])
             return base;
@@ -58,8 +56,6 @@ function remapStepNamesToNodeIds(stepNames, nodes, graphName) {
     });
 }
 const ENTRY_FROM = '__entry__';
-/** Whether `target` can reach `source` over `next` edges — i.e. an edge
- *  source→target closes a cycle (a back-edge), vs a plain forward edge. */
 function closesCycle(source, target, nodes) {
     const seen = new Set();
     const stack = [target];
@@ -75,15 +71,6 @@ function closesCycle(source, target, nodes) {
     }
     return false;
 }
-/**
- * Decide which next steps to fire this tick. Two kinds of edge:
- *  - forward edge → node-once: fire the target only if it has no instance yet,
- *    so converging edges (joins) collapse to a single run (unchanged behavior).
- *  - back-edge (target can reach the source, closing a cycle) → revisit: fire a
- *    fresh ordinal instance (`target#1`, …), edge-once on `from → target` so it
- *    doesn't re-fire every tick. Cycles terminate when branch routing stops
- *    looping back; a node always records the predecessor it was reached from.
- */
 function planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, graphName) {
     const toLogical = (name) => remapStepNamesToNodeIds([name], nodes, graphName)[0];
     const countByLogical = {};
@@ -95,7 +82,6 @@ function planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, grap
     }
     const completed = instances.filter((i) => i.status === 'succeeded');
     const completedLogical = new Set(completed.map((i) => toLogical(i.stepName)));
-    // Available edges: entry edges + each completed instance's resolved `next`.
     const edges = [];
     for (const entryId of entryNodeIds) {
         edges.push({ fromKey: ENTRY_FROM, target: entryId });
@@ -106,7 +92,12 @@ function planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, grap
         if (!node?.next)
             continue;
         for (const target of resolveNextFromConfig(node.next, branchByStep[inst.stepName])) {
-            edges.push({ from: inst.stepName, fromKey: inst.stepName, fromLogical, target });
+            edges.push({
+                from: inst.stepName,
+                fromKey: inst.stepName,
+                fromLogical,
+                target,
+            });
         }
     }
     const toFire = [];
@@ -119,7 +110,6 @@ function planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, grap
         const visits = countByLogical[target] ?? 0;
         const isBackEdge = edge.fromLogical !== undefined &&
             closesCycle(edge.fromLogical, target, nodes);
-        // Forward edge into an already-started node = a join; node-once.
         if (!isBackEdge && visits > 0) {
             consumed.add(edgeKey);
             continue;
@@ -355,8 +345,6 @@ function areDependenciesSatisfied(node, completedNodeIds) {
     return deps.every((dep) => completedNodeIds.has(dep));
 }
 async function queueGraphNode(workflowService, runId, _graphName, nodeId, rpcName, input, nodeConfig, fromStepName) {
-    // Default to the workflow-wide retry policy when the node sets none, so the
-    // persisted step retries match the queue `attempts` (see resolveStepJobOptions).
     const stepOptions = {
         retries: nodeConfig?.retries ?? DEFAULT_STEP_RETRIES,
         retryDelay: nodeConfig?.retryDelay,
@@ -372,8 +360,6 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
     const nodes = meta.nodes;
     validateGraphReferences(graphName, nodes, meta.entryNodeIds ?? []);
     const { completedNodeIds: rawCompleted, failedNodeIds: rawFailed, branchKeys: branchByStep, } = await workflowService.getCompletedGraphState(runId);
-    // Validate step/branch names map to unambiguous nodes (planning keys
-    // physically; these calls only surface ambiguous template configs).
     remapStepNamesToNodeIds(rawCompleted, nodes, graphName);
     remapBranchKeys(branchByStep, nodes, graphName);
     const failedNodeIds = remapStepNamesToNodeIds(rawFailed, nodes, graphName);
@@ -393,14 +379,11 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
     const instances = await workflowService.getStepInstances(runId);
     const plan = planGraphTransitions(nodes, instances, branchByStep, meta.entryNodeIds ?? [], graphName);
     if (plan.toFire.length === 0) {
-        // Nothing left to fire and nothing running/blocked → the run is done.
         if (!plan.hasInFlight && !plan.blockedWaiting) {
             await workflowService.updateRunStatus(runId, 'completed');
         }
         return;
     }
-    // The same run read a few lines up: nothing between here and there writes it,
-    // and `input` is fixed at creation anyway.
     const triggerInput = currentRun?.input;
     for (const fire of plan.toFire) {
         const node = nodes[fire.logical];
@@ -413,13 +396,6 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
         await queueGraphNode(workflowService, runId, graphName, fire.instanceKey, node.rpcName, resolvedInput, node, fire.fromStepName);
     }
 }
-/**
- * Invoke a graph node's RPC with the graph + workflow wires, capturing any
- * branch the node selects and persisting it. Shared by the queued
- * (executeGraphStep) and inline (executeGraphNodeInline) executors so both build
- * the wire and record the branch identically — only their child-workflow and
- * onError handling differs around this call.
- */
 async function invokeGraphNodeRpc(workflowService, rpcService, runId, stepId, nodeId, rpcName, input, graphName) {
     const wireState = {};
     const graphWire = {
@@ -526,9 +502,6 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
     if (!node)
         return;
     const rpcName = node.rpcName;
-    // Persist under the physical instance key (node, node#1 … for revisits) and
-    // record the predecessor — same as the queued path (queueGraphNode), so an
-    // inline graph run stores identical step rows + provenance.
     const stepState = await workflowService.insertStepState(runId, instanceKey, rpcName, input, { retries: node.retries ?? 0, retryDelay: node.retryDelay }, fromStepName);
     await workflowService.setStepRunning(stepState.stepId);
     try {
@@ -589,15 +562,8 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
     }
 }
 async function continueGraphInline(workflowService, rpcService, runId, graphName, nodes, triggerInput, entryNodeIds) {
-    // Drive the run to completion in-process using the SAME planner as the queued
-    // path (continueGraph): each loop plans the next wave of transitions, executes
-    // them inline (vs queueGraphNode dispatch), then re-plans. Sharing the planner
-    // gives the inline path joins, cycle revisits and fromStepName provenance
-    // identical to the queue — instead of a second, weaker traversal.
     while (true) {
         const { failedNodeIds: rawFailed, branchKeys: branchByStep, completedNodeIds: rawCompleted, } = await workflowService.getCompletedGraphState(runId);
-        // Validate step/branch names map to unambiguous nodes (planning keys
-        // physically; these calls only surface ambiguous template configs).
         remapStepNamesToNodeIds(rawCompleted, nodes, graphName);
         remapBranchKeys(branchByStep, nodes, graphName);
         const failedNodeIds = remapStepNamesToNodeIds(rawFailed, nodes, graphName);
@@ -634,7 +600,6 @@ async function continueGraphInline(workflowService, rpcService, runId, graphName
             executed++;
             await executeGraphNodeInline(workflowService, rpcService, runId, graphName, fire.logical, fire.instanceKey, resolvedInput, nodes, fire.fromStepName);
         }));
-        // Nothing executable fired (e.g. nodes without an rpcName) → can't progress.
         if (executed === 0)
             return;
     }

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

@@ -5,10 +5,6 @@ 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 {

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

@@ -1,91 +1,33 @@
-/**
- * Ref value - internal representation after input callback is evaluated
- */
 export interface RefValue {
     __isRef: true;
     nodeId: string;
     path?: string;
 }
-/**
- * Helper to create a ref value
- */
 export declare const createRef: (nodeId: string, path?: string) => RefValue;
-/**
- * Check if a value is a ref
- */
 export declare const isRef: (value: unknown) => value is RefValue;
-/**
- * Input reference for fetching step results
- */
 export interface InputRef {
     nodeId: string;
     path?: string;
 }
-/**
- * Ref function type - provides type-safe references to other nodes' outputs
- * The actual typing is done at the pikkuWorkflowGraph level
- */
 export type RefFn<NodeIds extends string = string> = (nodeId: NodeIds, path?: string) => RefValue;
-/**
- * Next node configuration - fully serializable
- * - string: single next node
- * - string[]: parallel execution (all run concurrently)
- * - Record<string, string | string[]>: branching (function calls graph.branch('key'))
- */
 export type NextConfig<NodeIds extends string = string> = NodeIds | NodeIds[] | Record<string, NodeIds | NodeIds[]>;
-/**
- * Graph node configuration - references functions by RPC name
- */
 export interface GraphNodeConfig<NodeIds extends string = string> {
-    /** RPC function name */
     func: string;
-    /** Input mapping callback - receives ref function, returns input object */
     input?: (ref: RefFn<NodeIds>) => Record<string, unknown>;
-    /** Next nodes - string, array, or record for branching */
     next?: NextConfig<NodeIds>;
-    /** Error routing - node(s) to execute on error */
     onError?: NodeIds | NodeIds[];
-    /** Maximum retry attempts allowed (excludes the initial attempt) */
     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
- */
 export interface PikkuGraphWire {
-    /** Workflow run ID */
     runId: string;
-    /** Graph name */
     graphName: string;
-    /** Current node ID */
     nodeId: string;
-    /**
-     * Select which branch to take for Record-based next config.
-     * Must be called if the node has a Record `next` configuration.
-     * @param key - The branch key to take (must match a key in the next Record)
-     */
     branch: (key: string) => void;
-    /**
-     * Set a state variable value.
-     * @param name - Variable name
-     * @param value - Value to store
-     */
     setState: (name: string, value: unknown) => Promise<void>;
-    /**
-     * Get the entire state object.
-     * @returns The state object with all variables
-     */
     getState: () => Promise<Record<string, unknown>>;
 }
-/**
- * Internal mutable state for graph wire (used by runner to capture branch)
- */
 export interface GraphWireState {
     branchKey?: string;
 }

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

@@ -1,14 +1,8 @@
-/**
- * Helper to create a ref value
- */
 export const createRef = (nodeId, path) => ({
     __isRef: true,
     nodeId,
     path,
 });
-/**
- * Check if a value is a ref
- */
 export const isRef = (value) => typeof value === 'object' &&
     value !== null &&
     '__isRef' in value &&

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

@@ -1,6 +1,3 @@
-/**
- * Workflow module exports
- */
 export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
 export type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension, } from './pikku-workflow-service.js';
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
@@ -12,14 +9,15 @@ export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, CoreFeature, CoreFeatureScenario, FeatureMeta, FeatureMetaEntry, FeaturesMeta, FeaturePlanEntry, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, CoreFeature, CoreFeatureScenario, FeatureMeta, FeatureMetaEntry, FeaturesMeta, FeaturePlanEntry, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, } 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, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
-export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, } from './scenario-step.types.js';
+export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, } from './scenario-step.types.js';
+export { SCENARIO_SURFACES } from './scenario-step.types.js';
+export { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
 export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
 export { pollUntil, type PollOptions } from './scenario-poll.js';
 export { createCookieJar } from './scenario-cookie-jar.js';
 export type { ScenarioCookieJar } from './scenario-cookie-jar.js';
-export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/scenario-actors-service.js';
-export { readScenarioHttpResponse, postScenarioJson, } from '../../services/scenario-actors-service.js';
+export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/personas-service.js';
 export type { PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
 export { composeStepProse, renderStepTemplate } from './scenario-prose.js';

package/dist/wirings/workflow/index.js

@@ -1,29 +1,15 @@
-/**
- * Workflow module exports
- */
 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';
-// Internal registration functions (used by generated code)
 export { addWorkflow } from './dsl/workflow-runner.js';
 export { addFeature, resolveFeatureScenarios } from './feature.js';
-// Graph helpers (template, pikkuWorkflowGraph)
 export { template } from './graph/template.js';
 export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
-// Queue worker functions (registered by codegen, executed at runtime)
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
-// Narrows the optional halves of the step wire, with a message that says what to do
+export { SCENARIO_SURFACES } from './scenario-step.types.js';
+// Which of a step's bindings run: one for an action, every witness for a `then`
+export { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
 export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
-// Waits for the target to catch up, without every step writing the loop again
 export { pollUntil } from './scenario-poll.js';
-// Persists cookies across a step's requests, the way a browser would
 export { createCookieJar } from './scenario-cookie-jar.js';
-export { readScenarioHttpResponse, postScenarioJson, } from '../../services/scenario-actors-service.js';
-/* ------------------------------------------------------------------ *
- * Scenarios — reporting a run
- *
- * Used by the CLI reporter and the console, so the two render the same
- * sentence for the same step. A step body needs none of it.
- * ------------------------------------------------------------------ */
 export { composeStepProse, renderStepTemplate } from './scenario-prose.js';

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

@@ -2,8 +2,8 @@ import { PikkuError } from '../../errors/error-handler.js';
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
 import { type RunLifecycleContext, type WorkflowRunEngine, type WorkflowRunExtension } from './pikku-workflow-service.js';
 import type { PikkuWire } from '../../types/core.types.js';
-import type { ScenarioActors } from '../../services/scenario-actors-service.js';
-import type { ScenarioBrowserProvider, ScenarioEnvironment } from './scenario-step.types.js';
+import type { ScenarioPersonas } from '../../services/personas-service.js';
+import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } from './scenario-step.types.js';
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
 /**
  * A workflow service with the scenario capability attached — the two lines
@@ -28,6 +28,77 @@ export declare class ScenarioHookError extends PikkuError {
     readonly phase: 'before' | 'after';
     constructor(scenarioName: string, phase: 'before' | 'after', cause: unknown);
 }
+/**
+ * Two witnesses of the same `then` disagreed.
+ *
+ * This is the failure the whole additive-witness design exists to produce: the
+ * system of record is right and the surface the actor was looking at is not, or
+ * the other way round. Both observations go in the message, because either one
+ * alone reads as a passing assertion.
+ */
+export declare class ScenarioWitnessDisagreement extends PikkuError {
+    readonly stepFunc: string;
+    readonly expected: {
+        surface: ScenarioSurface;
+        observed: unknown;
+    };
+    readonly actual: {
+        surface: ScenarioSurface;
+        observed: unknown;
+    };
+    constructor(stepFunc: string, expected: {
+        surface: ScenarioSurface;
+        observed: unknown;
+    }, actual: {
+        surface: ScenarioSurface;
+        observed: unknown;
+    });
+}
+/**
+ * A step resolved to its browser binding but nothing can provide a browser.
+ */
+export declare class ScenarioBrowserUnavailable extends PikkuError {
+    readonly stepFunc: string;
+    constructor(stepFunc: string);
+}
+/**
+ * A browser binding was reached without an actor, so there is no persona whose
+ * window it would run in.
+ */
+export declare class ScenarioBrowserActorRequired extends PikkuError {
+    readonly stepFunc: string;
+    constructor(stepFunc: string);
+}
+/**
+ * A step declares no binding the run can execute.
+ *
+ * Reached when a step has no `default` and the run targets a surface it does not
+ * implement — an action step with nothing to run is a broken ladder, not a
+ * coverage gap. (A `then` that ran somewhere, just not on the run surface, is
+ * the coverage gap; it is reported rather than thrown. See
+ * {@link ScenarioNoWitness} for one that ran nowhere.)
+ */
+export declare class ScenarioNoSurfaceBinding extends PikkuError {
+    readonly stepFunc: string;
+    readonly declared: ScenarioSurface[];
+    readonly runSurface: ScenarioSurface;
+    constructor(stepFunc: string, declared: ScenarioSurface[], runSurface: ScenarioSurface);
+}
+/**
+ * An assertion had no witness this run could execute.
+ *
+ * Distinct from an unwitnessed `then`, which ran server-side and merely did not
+ * look at the surface its prose claims. This one ran nowhere: without the throw
+ * the step returns `undefined` and renders as a tick, reporting a pass for
+ * something nobody checked. That is the exact failure the phase exists to
+ * prevent, so it is fatal regardless of `--strict`.
+ */
+export declare class ScenarioNoWitness extends PikkuError {
+    readonly stepFunc: string;
+    readonly declared: ScenarioSurface[];
+    readonly runSurface: ScenarioSurface;
+    constructor(stepFunc: string, declared: ScenarioSurface[], runSurface: ScenarioSurface);
+}
 /**
  * The scenario capability, layered onto a workflow service rather than being
  * one.
@@ -57,7 +128,14 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     private runActors;
     private scenarioBrowserProvider?;
     private scenarioEnvironment?;
+    private runSurface;
     constructor(engine: WorkflowRunEngine);
+    /**
+     * The surface every actor drives the system through for this run, set once by
+     * the runner from `--run`. `default` is the server-side path — the fast suite.
+     */
+    setRunSurface(surface: ScenarioSurface): void;
+    getRunSurface(): ScenarioSurface;
     /**
      * Registered by `@pikku/playwright` (or any other driver) before a scenario
      * runs. Absent means browser steps cannot run, which the CLI checks up front
@@ -73,7 +151,7 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     setScenarioEnvironment(env: ScenarioEnvironment | undefined): void;
     getScenarioEnvironment(): ScenarioEnvironment | undefined;
     attachRunContext(runId: string, workflowMeta: any, options?: {
-        actors?: ScenarioActors;
+        actors?: ScenarioPersonas;
     }): Promise<void>;
     detachRunContext(runId: string): void;
     decorateRunWire(wire: PikkuWire, context: {
@@ -107,7 +185,7 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
      * for the AI persona conversation loop it pulls in when a scenario actually
      * signs an actor in.
      */
-    resolveScenarioActors(): Promise<ScenarioActors | undefined>;
+    resolvePersonas(): Promise<ScenarioPersonas | undefined>;
     decorateWorkflowWire(wire: PikkuWorkflowWire, context: {
         name: string;
         runId: string;
@@ -117,5 +195,9 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     private scenarioStep;
     private scenarioStepConfig;
     private scenarioStepDescription;
-    private requiresBrowser;
+    /**
+     * Which surfaces a step declares a binding for. A step that declares none is
+     * treated as server-side only, which is what an ordinary function is.
+     */
+    private declaredSurfaces;
 }