@pikku/core 0.12.84 → 0.12.86

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

@@ -23,11 +23,25 @@ function buildTemplateRegex(nodeId) {
         .join('.+');
     return new RegExp(`^${escaped}$`);
 }
-function stripInstanceOrdinal(name) {
-    const hash = name.lastIndexOf('#');
+const FANOUT_INSTANCE = /^(.+)\[(\d+)\]$/;
+function fanoutInstanceKey(base, index) {
+    return `${base}[${index}]`;
+}
+function splitFanoutInstance(name) {
+    const match = FANOUT_INSTANCE.exec(name);
+    if (!match)
+        return null;
+    return { base: match[1], index: Number(match[2]) };
+}
+export function stripInstanceOrdinal(name) {
+    const fanout = splitFanoutInstance(name);
+    const withoutItem = fanout ? fanout.base : name;
+    const hash = withoutItem.lastIndexOf('#');
     if (hash <= 0)
-        return name;
-    return /^\d+$/.test(name.slice(hash + 1)) ? name.slice(0, hash) : name;
+        return withoutItem;
+    return /^\d+$/.test(withoutItem.slice(hash + 1))
+        ? withoutItem.slice(0, hash)
+        : withoutItem;
 }
 function remapStepNamesToNodeIds(stepNames, nodes, graphName) {
     const templatePatterns = new Map();
@@ -72,40 +86,123 @@ function closesCycle(source, target, nodes) {
     }
     return false;
 }
-function planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, graphName) {
+function planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, graphName, fanoutWidths = {}) {
     const toLogical = (name) => remapStepNamesToNodeIds([name], nodes, graphName)[0];
     const countByLogical = {};
+    const instancesByLogical = {};
     const consumed = new Set();
     for (const inst of instances) {
         const logical = toLogical(inst.stepName);
         countByLogical[logical] = (countByLogical[logical] ?? 0) + 1;
+        (instancesByLogical[logical] ??= []).push(inst);
         consumed.add(`${inst.fromStepName ?? ENTRY_FROM}->${logical}`);
     }
+    const isFanned = (nodeId) => Boolean(nodes[nodeId]?.forEach);
+    const fanoutComplete = (nodeId) => {
+        const width = fanoutWidths[nodeId];
+        if (width === undefined)
+            return false;
+        const succeeded = (instancesByLogical[nodeId] ?? []).filter((i) => i.status === 'succeeded').length;
+        return succeeded >= width;
+    };
     const completed = instances.filter((i) => i.status === 'succeeded');
-    const completedLogical = new Set(completed.map((i) => toLogical(i.stepName)));
+    const completedLogical = new Set();
+    for (const inst of completed) {
+        const logical = toLogical(inst.stepName);
+        if (!isFanned(logical))
+            completedLogical.add(logical);
+    }
+    for (const nodeId of Object.keys(fanoutWidths)) {
+        if (isFanned(nodeId) && fanoutComplete(nodeId))
+            completedLogical.add(nodeId);
+    }
     const edges = [];
     for (const entryId of entryNodeIds) {
         edges.push({ fromKey: ENTRY_FROM, target: entryId });
     }
+    const fannedEdgesEmitted = new Set();
     for (const inst of completed) {
         const fromLogical = toLogical(inst.stepName);
         const node = nodes[fromLogical];
         if (!node?.next)
             continue;
-        for (const target of resolveNextFromConfig(node.next, branchByStep[inst.stepName])) {
-            edges.push({
-                from: inst.stepName,
-                fromKey: inst.stepName,
-                fromLogical,
-                target,
-            });
+        let from = inst.stepName;
+        let branchKey = branchByStep[inst.stepName];
+        if (isFanned(fromLogical)) {
+            if (!completedLogical.has(fromLogical))
+                continue;
+            if (fannedEdgesEmitted.has(fromLogical))
+                continue;
+            fannedEdgesEmitted.add(fromLogical);
+            from = fromLogical;
+            branchKey = branchByStep[fromLogical] ?? branchByStep[inst.stepName];
+        }
+        for (const target of resolveNextFromConfig(node.next, branchKey)) {
+            edges.push({ from, fromKey: from, fromLogical, target });
+        }
+    }
+    // A zero-width fanout produces no instances at all, so its outgoing edges
+    // have no completed instance to hang off — emit them from the logical node.
+    for (const [nodeId, width] of Object.entries(fanoutWidths)) {
+        if (width !== 0 || fannedEdgesEmitted.has(nodeId))
+            continue;
+        const node = nodes[nodeId];
+        if (!node?.next)
+            continue;
+        fannedEdgesEmitted.add(nodeId);
+        for (const target of resolveNextFromConfig(node.next, branchByStep[nodeId])) {
+            edges.push({ from: nodeId, fromKey: nodeId, fromLogical: nodeId, target });
         }
     }
     const toFire = [];
+    const plannedFanout = new Set();
     let blockedWaiting = false;
     for (const edge of edges) {
         const target = edge.target;
         const edgeKey = `${edge.fromKey}->${target}`;
+        if (isFanned(target)) {
+            if (plannedFanout.has(target))
+                continue;
+            plannedFanout.add(target);
+            if (!areDependenciesSatisfied(nodes[target] ?? {}, completedLogical)) {
+                blockedWaiting = true;
+                continue;
+            }
+            const width = fanoutWidths[target];
+            if (width === undefined) {
+                blockedWaiting = true;
+                continue;
+            }
+            const existing = instancesByLogical[target] ?? [];
+            const existingIndexes = new Set(existing
+                .map((i) => splitFanoutInstance(i.stepName)?.index)
+                .filter((index) => index !== undefined));
+            const pending = [];
+            for (let index = 0; index < width; index++) {
+                if (!existingIndexes.has(index))
+                    pending.push(index);
+            }
+            if (pending.length === 0)
+                continue;
+            const sequential = nodes[target]?.mode === 'sequential';
+            const anyInFlight = existing.some((i) => i.status !== 'succeeded');
+            const emit = sequential
+                ? anyInFlight
+                    ? []
+                    : pending.slice(0, 1)
+                : pending;
+            for (const index of emit) {
+                toFire.push({
+                    logical: target,
+                    instanceKey: fanoutInstanceKey(target, index),
+                    fromStepName: edge.from,
+                    itemIndex: index,
+                });
+            }
+            if (emit.length === 0)
+                blockedWaiting = true;
+            continue;
+        }
         if (consumed.has(edgeKey))
             continue;
         const visits = countByLogical[target] ?? 0;
@@ -237,7 +334,7 @@ function resolveTemplate(template, nodeResults) {
 }
 function resolveValue(value, nodeResults) {
     if (isDataRef(value)) {
-        if (value.$ref === '$item') {
+        if (value.$ref === '$item' && !('$item' in nodeResults)) {
             return value;
         }
         const source = nodeResults[value.$ref];
@@ -297,6 +394,7 @@ function extractReferencedNodeIds(input) {
     return [...new Set(nodeIds)];
 }
 const IGNORED_REFS = new Set(['trigger', '$item', 'unknown']);
+const FOREACH_MODES = new Set(['parallel', 'sequential']);
 function normalizeNodeTargets(value) {
     if (!value)
         return [];
@@ -327,6 +425,21 @@ function validateGraphReferences(graphName, nodes, entryNodes) {
                 throw new Error(`Workflow graph '${graphName}': node '${nodeId}' references unknown node '${refId}' in input`);
             }
         }
+        if (node.forEach !== undefined) {
+            const source = forEachSource(node);
+            if (!source) {
+                throw new Error(`Workflow graph '${graphName}': node '${nodeId}' forEach must reference a node`);
+            }
+            if (!IGNORED_REFS.has(source.$ref) && !nodeIds.has(source.$ref)) {
+                throw new Error(`Workflow graph '${graphName}': node '${nodeId}' references unknown node '${source.$ref}' in forEach`);
+            }
+            if (node.mode !== undefined && !FOREACH_MODES.has(node.mode)) {
+                throw new Error(`Workflow graph '${graphName}': node '${nodeId}' has an unknown forEach mode '${node.mode}'`);
+            }
+        }
+        else if (node.mode !== undefined) {
+            throw new Error(`Workflow graph '${graphName}': node '${nodeId}' sets mode '${node.mode}' without a forEach`);
+        }
         const nextTargets = normalizeNodeTargets(node.next);
         for (const nextId of nextTargets) {
             if (!nodeIds.has(nextId)) {
@@ -341,9 +454,114 @@ function validateGraphReferences(graphName, nodes, entryNodes) {
         }
     }
 }
+function forEachSource(node) {
+    return isDataRef(node.forEach) ? node.forEach : undefined;
+}
+function nodeDependencies(node) {
+    const deps = extractReferencedNodeIds(node.input);
+    const source = forEachSource(node);
+    if (source)
+        deps.push(source.$ref);
+    return [...new Set(deps)].filter((id) => !IGNORED_REFS.has(id));
+}
+function describeValue(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    return typeof value;
+}
+function resolveForEachItems(graphName, nodeId, node, nodeResults) {
+    const source = forEachSource(node);
+    if (!source) {
+        throw new Error(`Workflow graph '${graphName}': node '${nodeId}' has an unusable forEach configuration`);
+    }
+    const raw = nodeResults[source.$ref];
+    const value = source.path ? getValueAtPath(raw, source.path) : raw;
+    if (!Array.isArray(value)) {
+        const label = source.path ? `${source.$ref}.${source.path}` : source.$ref;
+        throw new Error(`Workflow graph '${graphName}': node '${nodeId}' forEach source '${label}' resolved to ${describeValue(value)}, expected an array`);
+    }
+    return value;
+}
 function areDependenciesSatisfied(node, completedNodeIds) {
-    const deps = extractReferencedNodeIds(node.input).filter((id) => !IGNORED_REFS.has(id));
-    return deps.every((dep) => completedNodeIds.has(dep));
+    return nodeDependencies(node).every((dep) => completedNodeIds.has(dep));
+}
+async function createGraphResultReader(workflowService, runId, graphName, nodes, triggerInput, instances) {
+    const succeeded = new Set(instances.filter((i) => i.status === 'succeeded').map((i) => i.stepName));
+    const fanoutItems = {};
+    const fanoutWidths = {};
+    const resultCache = new Map();
+    const resolving = new Set();
+    const readResult = async (nodeId) => {
+        if (nodeId === 'trigger')
+            return triggerInput;
+        if (resultCache.has(nodeId))
+            return resultCache.get(nodeId);
+        if (resolving.has(nodeId))
+            return undefined;
+        resolving.add(nodeId);
+        try {
+            let value;
+            if (nodes[nodeId]?.forEach) {
+                const items = await readFanoutItems(nodeId);
+                if (items === undefined)
+                    return undefined;
+                const keys = items.map((_, index) => fanoutInstanceKey(nodeId, index));
+                if (keys.some((key) => !succeeded.has(key)))
+                    return undefined;
+                const fetched = keys.length
+                    ? await workflowService.getNodeResults(runId, keys)
+                    : {};
+                value = keys.map((key) => fetched[key]);
+            }
+            else {
+                if (!succeeded.has(nodeId))
+                    return undefined;
+                const fetched = await workflowService.getNodeResults(runId, [nodeId]);
+                value = fetched[nodeId];
+            }
+            resultCache.set(nodeId, value);
+            return value;
+        }
+        finally {
+            resolving.delete(nodeId);
+        }
+    };
+    const readFanoutItems = async (nodeId) => {
+        if (fanoutItems[nodeId])
+            return fanoutItems[nodeId];
+        const node = nodes[nodeId];
+        const source = forEachSource(node);
+        if (!source)
+            return undefined;
+        const sourceValue = await readResult(source.$ref);
+        if (sourceValue === undefined)
+            return undefined;
+        const items = resolveForEachItems(graphName, nodeId, node, {
+            [source.$ref]: sourceValue,
+        });
+        fanoutItems[nodeId] = items;
+        fanoutWidths[nodeId] = items.length;
+        return items;
+    };
+    for (const nodeId of Object.keys(nodes)) {
+        if (nodes[nodeId]?.forEach)
+            await readFanoutItems(nodeId);
+    }
+    return {
+        fanoutItems,
+        fanoutWidths,
+        read: async (nodeIds) => {
+            const results = {};
+            for (const nodeId of nodeIds) {
+                const value = await readResult(nodeId);
+                if (value !== undefined)
+                    results[nodeId] = value;
+            }
+            return results;
+        },
+    };
 }
 async function queueGraphNode(workflowService, runId, _graphName, nodeId, rpcName, input, nodeConfig, fromStepName) {
     const stepOptions = {
@@ -378,21 +596,28 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
         return;
     }
     const instances = await workflowService.getStepInstances(runId);
-    const plan = planGraphTransitions(nodes, instances, branchByStep, meta.entryNodeIds ?? [], graphName);
+    const triggerInput = currentRun?.input;
+    const reader = await createGraphResultReader(workflowService, runId, graphName, nodes, triggerInput, instances);
+    const plan = planGraphTransitions(nodes, instances, branchByStep, meta.entryNodeIds ?? [], graphName, reader.fanoutWidths);
     if (plan.toFire.length === 0) {
         if (!plan.hasInFlight && !plan.blockedWaiting) {
             await workflowService.updateRunStatus(runId, 'completed');
         }
         return;
     }
-    const triggerInput = currentRun?.input;
     for (const fire of plan.toFire) {
         const node = nodes[fire.logical];
         if (!node?.rpcName)
             continue;
         const referencedNodeIds = extractReferencedNodeIds(node.input).filter((id) => !IGNORED_REFS.has(id));
-        const fetchedResults = await workflowService.getNodeResults(runId, referencedNodeIds);
-        const nodeResults = { trigger: triggerInput, ...fetchedResults };
+        const fetchedResults = await reader.read(referencedNodeIds);
+        const nodeResults = {
+            trigger: triggerInput,
+            ...fetchedResults,
+        };
+        if (fire.itemIndex !== undefined) {
+            nodeResults['$item'] = reader.fanoutItems[fire.logical]?.[fire.itemIndex];
+        }
         const resolvedInput = resolveSerializedInput(node.input, nodeResults);
         await queueGraphNode(workflowService, runId, graphName, fire.instanceKey, node.rpcName, resolvedInput, node, fire.fromStepName);
     }
@@ -579,7 +804,8 @@ async function continueGraphInline(workflowService, rpcService, runId, graphName
             return;
         }
         const instances = await workflowService.getStepInstances(runId);
-        const plan = planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, graphName);
+        const reader = await createGraphResultReader(workflowService, runId, graphName, nodes, triggerInput, instances);
+        const plan = planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, graphName, reader.fanoutWidths);
         if (plan.toFire.length === 0) {
             if (!plan.hasInFlight && !plan.blockedWaiting) {
                 await workflowService.updateRunStatus(runId, 'completed');
@@ -592,8 +818,15 @@ async function continueGraphInline(workflowService, rpcService, runId, graphName
             if (!node?.rpcName)
                 return;
             const referencedNodeIds = extractReferencedNodeIds(node.input).filter((id) => !IGNORED_REFS.has(id));
-            const fetchedResults = await workflowService.getNodeResults(runId, referencedNodeIds);
-            const nodeResults = { trigger: triggerInput, ...fetchedResults };
+            const fetchedResults = await reader.read(referencedNodeIds);
+            const nodeResults = {
+                trigger: triggerInput,
+                ...fetchedResults,
+            };
+            if (fire.itemIndex !== undefined) {
+                nodeResults['$item'] =
+                    reader.fanoutItems[fire.logical]?.[fire.itemIndex];
+            }
             const resolvedInput = resolveSerializedInput(node.input, nodeResults);
             executed++;
             await executeGraphNodeInline(workflowService, rpcService, runId, graphName, fire.logical, fire.instanceKey, resolvedInput, nodes, fire.fromStepName);
@@ -602,6 +835,27 @@ async function continueGraphInline(workflowService, rpcService, runId, graphName
             return;
     }
 }
+function planEntryFirings(graphName, nodeId, node, triggerNodeResults, triggerInput) {
+    if (!node.forEach) {
+        const input = node.input && Object.keys(node.input).length > 0
+            ? resolveSerializedInput(node.input, triggerNodeResults)
+            : triggerInput;
+        return [{ instanceKey: nodeId, input }];
+    }
+    const items = resolveForEachItems(graphName, nodeId, node, triggerNodeResults);
+    const width = node.mode === 'sequential' ? Math.min(items.length, 1) : items.length;
+    const firings = [];
+    for (let index = 0; index < width; index++) {
+        firings.push({
+            instanceKey: fanoutInstanceKey(nodeId, index),
+            input: resolveSerializedInput(node.input, {
+                ...triggerNodeResults,
+                $item: items[index],
+            }),
+        });
+    }
+    return firings;
+}
 export async function runWorkflowGraph(workflowService, graphName, triggerInput, rpcService, inline, startNode, wire, overrideMeta) {
     const meta = overrideMeta ?? getWorkflowMeta(graphName);
     if (!meta?.nodes) {
@@ -643,10 +897,8 @@ export async function runWorkflowGraph(workflowService, graphName, triggerInput,
                     const node = nodes[nodeId];
                     if (!node?.rpcName)
                         return;
-                    const resolvedInput = node.input && Object.keys(node.input).length > 0
-                        ? resolveSerializedInput(node.input, triggerNodeResults)
-                        : triggerInput;
-                    await executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, nodeId, resolvedInput, nodes);
+                    const firings = planEntryFirings(graphName, nodeId, node, triggerNodeResults, triggerInput);
+                    await Promise.all(firings.map((firing) => executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, firing.instanceKey, firing.input, nodes)));
                 }));
                 await continueGraphInline(workflowService, rpcService, runId, graphName, nodes, triggerInput, entryNodes);
             }
@@ -672,10 +924,10 @@ export async function runWorkflowGraph(workflowService, graphName, triggerInput,
             const node = nodes[nodeId];
             if (!node?.rpcName)
                 continue;
-            const resolvedInput = node.input && Object.keys(node.input).length > 0
-                ? resolveSerializedInput(node.input, triggerNodeResults)
-                : triggerInput;
-            await queueGraphNode(workflowService, runId, graphName, nodeId, node.rpcName, resolvedInput, node);
+            const firings = planEntryFirings(graphName, nodeId, node, triggerNodeResults, triggerInput);
+            for (const firing of firings) {
+                await queueGraphNode(workflowService, runId, graphName, firing.instanceKey, node.rpcName, firing.input, node);
+            }
         }
         if (inline) {
             workflowService.unregisterInlineRun(runId);

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

@@ -1,3 +1,4 @@
+import type { TemplateString } from './template.js';
 export interface RefValue {
     __isRef: true;
     nodeId: string;
@@ -7,9 +8,23 @@ export declare const createRef: (nodeId: string, path?: string) => 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[]>;
+export type TemplateFn = (templateStr: string, refs: Array<{
+    $ref: string;
+    path?: string;
+}>) => TemplateString;
+export type ItemFn = (path?: string) => RefValue;
+export type ForEachConfig<NodeIds extends string = string> = NodeIds | RefValue | ((ref: RefFn<NodeIds>) => RefValue);
+export type ForEachMode = 'parallel' | 'sequential';
 export interface GraphNodeConfig<NodeIds extends string = string> {
     func: string;
-    input?: (ref: RefFn<NodeIds>) => Record<string, unknown>;
+    /**
+     * Run this node once per element of an upstream array. The node's own result
+     * becomes the ordered array of per-item results.
+     */
+    forEach?: ForEachConfig<NodeIds>;
+    /** How the per-item instances of a `forEach` node run. Defaults to 'parallel'. */
+    mode?: ForEachMode;
+    input?: (ref: RefFn<NodeIds>, template: TemplateFn, $item: ItemFn) => Record<string, unknown>;
     next?: NextConfig<NodeIds>;
     onError?: NodeIds | NodeIds[];
     retries?: number;

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

@@ -15,3 +15,5 @@ export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGr
 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, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowsRuntimeMeta, } from './workflow.types.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';
+export { createGraph } from './graph/graph-node.js';
+export type { GraphNodeConfig, ForEachConfig, ForEachMode, ItemFn, TemplateFn, } from './graph/workflow-graph.types.js';

package/dist/wirings/workflow/index.js

@@ -9,3 +9,4 @@ export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './
 export { addWorkflow } from './dsl/workflow-runner.js';
 export { template } from './graph/template.js';
 export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
+export { createGraph } from './graph/graph-node.js';

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

@@ -7,13 +7,14 @@ import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } fr
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
 export { addFeature, resolveFeatureScenarios } from './feature.js';
 export type * from './scenario.types.js';
+export type * from './scenario-run.types.js';
 export { SCENARIO_SURFACES } from './scenario-step.types.js';
 export { resolveScenarioSurfaces } from './scenario-surface.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 { composeStepProse, renderStepTemplate } from './scenario-prose.js';
-export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+export { requireScenarioEnv } from './scenario-step-guards.js';
 export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/personas-service.js';
 /**
  * A workflow service with the scenario capability attached — the two lines
@@ -72,10 +73,14 @@ export declare class ScenarioBrowserUnavailable extends PikkuError {
     constructor(stepFunc: string);
 }
 /**
- * A browser binding was reached without an actor, so there is no persona whose
- * window it would run in.
+ * A step that is driven by a persona was dispatched without one.
+ *
+ * Raised before the body runs rather than partway through it: the step declared
+ * that it needs an actor — by having a `browser` binding, which cannot be
+ * provisioned without a window to open, or by `actor: true` — so a call site
+ * that omits one is a mistake at the call site.
  */
-export declare class ScenarioBrowserActorRequired extends PikkuError {
+export declare class ScenarioActorRequired extends PikkuError {
     readonly stepFunc: string;
     constructor(stepFunc: string);
 }
@@ -224,4 +229,9 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
      * treated as server-side only, which is what an ordinary function is.
      */
     private declaredSurfaces;
+    /**
+     * Whether a step is driven by a persona, and so must be given one. Stamped by
+     * the definer from a `browser` binding or an explicit `actor: true`.
+     */
+    private requiresActor;
 }

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

@@ -7,6 +7,21 @@ import { InMemoryWorkflowService } from '../../services/in-memory-workflow-servi
 import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { WorkflowStepNameNotString } from './workflow-errors.js';
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
+/**
+ * The retry default for the `expect*` family: none, the same as `given`,
+ * `when` and `then` take, and for the same reason — a failed assertion is a
+ * result, not a transient fault.
+ *
+ * Left to the workflow-wide `DEFAULT_STEP_RETRIES` they get six attempts each,
+ * which re-runs the RPC behind a failing `expectError`, restarts a whole
+ * `expectEventually` poll after it has already spent its own deadline, and
+ * lets a live judge re-roll a grade until one lands inside the band. The last
+ * of those is how it was found: a judge scored a deliberately useless answer
+ * 1, and the scenario went green anyway on the next attempt.
+ *
+ * A caller that genuinely wants attempts still asks for them.
+ */
+const assertionStep = (options) => ({ ...options, retries: options?.retries ?? 0 });
 export { addFeature, resolveFeatureScenarios } from './feature.js';
 export { SCENARIO_SURFACES } from './scenario-step.types.js';
 // Which of a step's bindings run: one for an action, every witness for a `then`
@@ -14,7 +29,7 @@ export { resolveScenarioSurfaces } from './scenario-surface.js';
 export { pollUntil } from './scenario-poll.js';
 export { createCookieJar } from './scenario-cookie-jar.js';
 export { composeStepProse, renderStepTemplate } from './scenario-prose.js';
-export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+export { requireScenarioEnv } from './scenario-step-guards.js';
 // The readers themselves live on `@pikku/core/persona`
 /**
  * A workflow service with the scenario capability attached — the two lines
@@ -90,20 +105,24 @@ addError(ScenarioBrowserUnavailable, {
     message: 'No browser provider is registered.',
 });
 /**
- * A browser binding was reached without an actor, so there is no persona whose
- * window it would run in.
+ * A step that is driven by a persona was dispatched without one.
+ *
+ * Raised before the body runs rather than partway through it: the step declared
+ * that it needs an actor — by having a `browser` binding, which cannot be
+ * provisioned without a window to open, or by `actor: true` — so a call site
+ * that omits one is a mistake at the call site.
  */
-export class ScenarioBrowserActorRequired extends PikkuError {
+export class ScenarioActorRequired extends PikkuError {
     stepFunc;
     constructor(stepFunc) {
-        super(`[scenario] step '${stepFunc}' resolved to its browser binding but was called without an actor. ` +
-            `Pass { actor: actors.<name> } so the browser signs in as that persona.`);
+        super(`[scenario] step '${stepFunc}' is driven by a persona but was called without an actor. ` +
+            `Pass { actor: actors.<name> } so it runs as that persona.`);
         this.stepFunc = stepFunc;
     }
 }
-addError(ScenarioBrowserActorRequired, {
+addError(ScenarioActorRequired, {
     status: 500,
-    message: 'A browser binding needs an actor.',
+    message: 'This step needs an actor.',
 });
 /**
  * A step declares no binding the run can execute.
@@ -433,7 +452,7 @@ export class PikkuScenarioService {
                         }
                         await new Promise((resolve) => setTimeout(resolve, interval));
                     }
-                }, options);
+                }, assertionStep(options));
             },
             expectError: async (stepName, rpcName, data, options) => {
                 this.engine.verifyStepName(stepName);
@@ -460,7 +479,7 @@ export class PikkuScenarioService {
                         return message;
                     }
                     throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`);
-                }, options);
+                }, assertionStep(options));
             },
             expectService: async (stepName, serviceMethod, options) => {
                 this.engine.verifyStepName(stepName);
@@ -489,7 +508,7 @@ export class PikkuScenarioService {
                         throw new Error(`[workflow] expectService '${stepName}' expected ${expected ?? 'at least one'} call(s) to '${serviceMethod}'` +
                             `${options?.calledWith !== undefined ? ` with ${JSON.stringify(options.calledWith)}` : ''}, found ${matching.length}. Recorded:\n  ${seen}`);
                     }
-                }, options);
+                }, assertionStep(options));
             },
             expectScore: async (stepName, agentRunId, scorerName, options) => {
                 this.engine.verifyStepName(stepName);
@@ -518,7 +537,7 @@ export class PikkuScenarioService {
                             `${grade.reason ? `: ${grade.reason}` : ''}`);
                     }
                     return grade;
-                }, options);
+                }, assertionStep(options));
             },
             // knowledge: decisions/internals/scenario-given-and-when-are-sugar-but-then-is-not.md
             given: (stepName, stepFunc, data, options) => this.scenarioStep('given', scenarioStepContext(), stepName, stepFunc, data, options),
@@ -546,6 +565,9 @@ export class PikkuScenarioService {
         const description = options?.description ??
             this.scenarioStepDescription(packageName, resolvedStepFunc) ??
             stepName;
+        if (!actor && this.requiresActor(packageName, resolvedStepFunc)) {
+            throw new ScenarioActorRequired(resolvedStepFunc);
+        }
         const declared = this.declaredSurfaces(packageName, resolvedStepFunc);
         const resolution = resolveScenarioSurfaces(phase, declared, this.runSurface);
         return await this.engine.inlineStep(runId, stepName, async () => {
@@ -556,13 +578,13 @@ export class PikkuScenarioService {
                     scenario: workflowWire,
                     pikkuUserId: workflowWire.pikkuUserId,
                     actors: this.runActors.get(runId),
+                    ...(actor ? { actor } : {}),
                     scenarioStep: {
                         name: resolvedStepFunc,
                         stepName,
                         runId,
                         phase,
                         surface,
-                        actor,
                         env: this.scenarioEnvironment,
                     },
                 };
@@ -570,9 +592,8 @@ export class PikkuScenarioService {
                     if (!this.scenarioBrowserProvider) {
                         throw new ScenarioBrowserUnavailable(resolvedStepFunc);
                     }
-                    if (!actor) {
-                        throw new ScenarioBrowserActorRequired(resolvedStepFunc);
-                    }
+                    // The dispatch guard above already refused an actor-less call, and a
+                    // browser binding always requires one.
                     wire.browser = await this.scenarioBrowserProvider.sessionFor(actor.name);
                 }
                 return await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
@@ -640,4 +661,11 @@ export class PikkuScenarioService {
         const surfaces = this.scenarioStepConfig(packageName, stepFunc)?.surfaces;
         return surfaces?.length ? surfaces : ['default'];
     }
+    /**
+     * Whether a step is driven by a persona, and so must be given one. Stamped by
+     * the definer from a `browser` binding or an explicit `actor: true`.
+     */
+    requiresActor(packageName, stepFunc) {
+        return (this.scenarioStepConfig(packageName, stepFunc)?.requiresActor === true);
+    }
 }