@pikku/core 0.12.69 → 0.12.70

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

@@ -3,7 +3,6 @@ import { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSl
 import { wireQueueWorker } from '../queue/queue-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-import { createHttpScenarioActors } from '../../services/http-scenario-actors.js';
 const resolveWorkflowMeta = (name) => {
     const rootMeta = pikkuState(null, 'workflows', 'meta');
     if (rootMeta[name]) {
@@ -29,7 +28,6 @@ const resolveWorkflowMeta = (name) => {
     return null;
 };
 const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
-import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
 import { PikkuError, addError, isExpectedError, } from '../../errors/error-handler.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
@@ -179,9 +177,7 @@ const WORKFLOW_END_STATES = new Set([
  */
 export class PikkuWorkflowService {
     inlineRuns = new Set();
-    // User-flow actors per run: live authenticated clients (cookie jars) are
-    // process-local by nature, so they ride this map, never the persisted wire.
-    runActors = new Map();
+    runExtension;
     get logger() {
         return getSingletonServices()?.logger;
     }
@@ -420,7 +416,10 @@ export class PikkuWorkflowService {
      * Creates pending step in both workflow_step and workflow_step_history
      * @param runId - Run ID
      * @param stepName - Step cache key
-     * @param rpcName - RPC function name
+     * @param rpcName - The name this step was dispatched by: an RPC for a
+     *   `workflow.do` step, a step function for a scenario step, null for a
+     *   closure. Nothing dispatches off this value — it is recorded so a reader
+     *   can join a step back to the function that ran it.
      * @param data - Step input data
      * @param stepOptions - Step options (retries, retryDelay)
      * @returns Step state with generated stepId
@@ -669,40 +668,34 @@ export class PikkuWorkflowService {
         await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, { runId, stepId });
         return true;
     }
-    /** Build HTTP scenario actors for a run started without them; undefined when SCENARIO_ACTOR_SECRET or the API URL is missing */
-    async resolveScenarioActors() {
-        const services = getSingletonServices();
-        const variables = services?.variables;
-        const metaService = services?.metaService;
-        if (!variables || !metaService) {
-            return undefined;
-        }
-        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
-        const apiUrl = await variables.get('API_URL');
-        if (!secret || !apiUrl) {
-            services?.logger?.warn('A scenario was started without actors but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without actors.');
-            return undefined;
-        }
-        const actorsConfig = await metaService.getScenarioActorsMeta();
-        if (!actorsConfig || Object.keys(actorsConfig).length === 0) {
-            return undefined;
-        }
-        const signInPath = (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
-            '/api/auth/sign-in/actor';
-        const rpcPath = (await variables.get('SCENARIO_RPC_PATH')) ?? '/rpc';
-        return createHttpScenarioActors({
-            apiUrl,
-            secret,
-            actors: actorsConfig,
-            signInPath,
-            rpcPath,
-        });
+    /**
+     * Install the one extension a run may have, built from a handle onto the run
+     * engine so that `inlineStep` and friends stay protected rather than becoming
+     * public API. Returns the extension, so the caller keeps a typed reference to
+     * whatever it just built.
+     */
+    setRunExtension(create) {
+        const engine = {
+            inlineStep: this.inlineStep.bind(this),
+            updateRunStatus: this.updateRunStatus.bind(this),
+            onChildWorkflowFailed: this.onChildWorkflowFailed.bind(this),
+            verifyStepName: this.verifyStepName.bind(this),
+        };
+        const extension = create(engine);
+        this.runExtension = extension;
+        return extension;
+    }
+    getRunExtension() {
+        return this.runExtension;
     }
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
      * @param options.inline - If true, execute workflow directly without queue service
      * @param options.startNode - Starting node ID for graph workflows (from wire config)
+     * @param options.onRunCreated - Called with the run id the moment the run exists.
+     * An inline run that fails throws instead of returning, so this is the only
+     * way a caller can still read that run back — its steps, and which one failed.
      */
     async startWorkflow(name, input, wire, rpcService, options) {
         // Resolve workflow from static meta (root or addon namespace), then dynamic DB
@@ -738,13 +731,8 @@ export class PikkuWorkflowService {
             deterministic: workflowMeta.deterministic,
             plannedSteps: workflowMeta.plannedSteps,
         });
-        const actors = options?.actors ??
-            (workflowMeta.source === 'scenario'
-                ? await this.resolveScenarioActors()
-                : undefined);
-        if (actors) {
-            this.runActors.set(runId, actors);
-        }
+        options?.onRunCreated?.(runId);
+        await this.runExtension?.attachRunContext(runId, workflowMeta, options);
         if (shouldInline) {
             this.inlineRuns.add(runId);
             try {
@@ -777,7 +765,7 @@ export class PikkuWorkflowService {
             }
             finally {
                 this.inlineRuns.delete(runId);
-                this.runActors.delete(runId);
+                this.runExtension?.detachRunContext(runId);
             }
         }
         else {
@@ -902,14 +890,30 @@ export class PikkuWorkflowService {
             workflowWire.pikkuUserId = run.wire?.pikkuUserId;
             const wire = {
                 workflow: workflowWire,
-                scenario: workflowMeta?.source === 'scenario' ? workflowWire : undefined,
                 pikkuUserId: run.wire?.pikkuUserId,
                 session: rpcService?.wire?.session,
                 rpc: rpcService?.wire?.rpc,
-                // User-flow actors registered for this run (see startWorkflow options)
-                actors: this.runActors.get(runId),
             };
+            this.runExtension?.decorateRunWire(wire, {
+                runId,
+                workflowMeta,
+                workflowWire,
+            });
+            const lifecycle = {
+                runId,
+                run,
+                workflowMeta,
+                workflow,
+                wire,
+                packageName: pkgName,
+            };
+            // `interrupted` means the run has not reached a terminal state — it is
+            // suspended or waiting — so teardown would run while the run is still
+            // mid-flight.
+            let outcome = 'completed';
+            let failure;
             try {
+                await this.runExtension?.onBeforeRunFunc(lifecycle);
                 const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
                     singletonServices: getSingletonServices(),
                     wire,
@@ -921,10 +925,13 @@ export class PikkuWorkflowService {
                 await this.onChildWorkflowCompleted(run, result);
             }
             catch (error) {
+                failure = error;
                 if (error instanceof WorkflowAsyncException) {
+                    outcome = 'interrupted';
                     throw error;
                 }
                 if (error instanceof WorkflowCancelledException) {
+                    outcome = 'failed';
                     await this.updateRunStatus(runId, 'cancelled', undefined, {
                         message: error.message || 'Workflow cancelled',
                         stack: '',
@@ -934,6 +941,7 @@ export class PikkuWorkflowService {
                     throw error;
                 }
                 if (error instanceof WorkflowSuspendedException) {
+                    outcome = 'interrupted';
                     await this.updateRunStatus(runId, 'suspended', undefined, {
                         message: error.message || 'Workflow suspended',
                         stack: '',
@@ -941,6 +949,7 @@ export class PikkuWorkflowService {
                     });
                     throw error;
                 }
+                outcome = 'failed';
                 await this.updateRunStatus(runId, 'failed', undefined, {
                     message: error.message,
                     stack: error.stack,
@@ -949,6 +958,9 @@ export class PikkuWorkflowService {
                 await this.onChildWorkflowFailed(run, error);
                 throw error;
             }
+            finally {
+                await this.runExtension?.onAfterRunFunc(lifecycle, outcome, failure);
+            }
         });
     }
     async onChildWorkflowCompleted(childRun, result) {
@@ -1328,7 +1340,21 @@ export class PikkuWorkflowService {
             }
         });
     }
-    async inlineStep(runId, logicalStepName, fn, stepOptions) {
+    async inlineStep(runId, logicalStepName, fn, stepOptions, 
+    /**
+     * The input this step was called with, recorded on the run so a reporter can
+     * name the values under test. A closure step has none; a scenario step does.
+     */
+    data = null, 
+    /**
+     * The name this step was dispatched by, for the kinds of inline step that
+     * have one. A closure step has no name; a scenario step is a step RPC, so
+     * it records the step function that ran — which is the only way to join a
+     * step back to its declaration when its durable name was built at runtime
+     * (a step called in a loop reaches the run as `sees @pikku/addon-todos`,
+     * declared as `sees ${packageName}`).
+     */
+    rpcName = null) {
         const fromStepName = this.lastStepName(runId);
         const stepName = this.nextStepKey(runId, logicalStepName);
         // Check if step already exists
@@ -1337,8 +1363,8 @@ export class PikkuWorkflowService {
             stepState = await this.getStepState(runId, stepName);
         }
         catch {
-            // Step doesn't exist - create it (inline, no RPC)
-            stepState = await this.insertStepState(runId, stepName, null, null, stepOptions, fromStepName);
+            // Step doesn't exist - create it (inline, so never dispatched)
+            stepState = await this.insertStepState(runId, stepName, rpcName, data, stepOptions, fromStepName);
         }
         if (stepState.status === 'succeeded') {
             // Return cached result
@@ -1635,90 +1661,6 @@ export class PikkuWorkflowService {
                     return await this.inlineStep(runId, stepName, rpcNameOrFn, dataOrOptions);
                 }
             },
-            // Durable polling step: invoke an RPC (as an actor when options.as is
-            // set) until the predicate passes or `within` elapses. The whole poll is
-            // ONE recorded step, so replay returns the cached outcome.
-            expectEventually: async (stepName, rpcName, data, predicate, options) => {
-                this.verifyStepName(stepName);
-                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
-                    ? `${addonNamespace}:${rpcName}`
-                    : rpcName;
-                const within = getDurationInMilliseconds(options?.within ?? '30s');
-                const interval = getDurationInMilliseconds(options?.interval ?? '1s');
-                return await this.inlineStep(runId, stepName, async () => {
-                    const deadline = Date.now() + within;
-                    let last;
-                    while (true) {
-                        last = options?.actor
-                            ? await options.actor.invoke(resolvedRpcName, data)
-                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
-                        if (predicate(last))
-                            return last;
-                        if (Date.now() + interval > deadline) {
-                            throw new Error(`[workflow] expectEventually '${stepName}' ('${resolvedRpcName}'` +
-                                `${options?.actor ? ` as '${options.actor.name}'` : ''}) did not pass within ${within}ms; ` +
-                                `last result: ${JSON.stringify(last)?.slice(0, 300)}`);
-                        }
-                        await new Promise((resolve) => setTimeout(resolve, interval));
-                    }
-                }, options);
-            },
-            expectError: async (stepName, rpcName, data, options) => {
-                this.verifyStepName(stepName);
-                const resolvedRpcName = addonNamespace && !rpcName.includes(':')
-                    ? `${addonNamespace}:${rpcName}`
-                    : rpcName;
-                return await this.inlineStep(runId, stepName, async () => {
-                    let result;
-                    try {
-                        result = options?.actor
-                            ? await options.actor.invoke(resolvedRpcName, data)
-                            : await rpcService.rpcWithWire(resolvedRpcName, data, {});
-                    }
-                    catch (e) {
-                        const message = e?.message ?? String(e);
-                        if (options?.matches) {
-                            const matched = typeof options.matches === 'string'
-                                ? message.includes(options.matches)
-                                : options.matches.test(message);
-                            if (!matched) {
-                                throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') threw, but the message did not match ${options.matches}: ${message}`);
-                            }
-                        }
-                        return message;
-                    }
-                    throw new Error(`[workflow] expectError '${stepName}' ('${resolvedRpcName}') expected an error but the call succeeded: ${JSON.stringify(result)?.slice(0, 300)}`);
-                }, options);
-            },
-            expectService: async (stepName, serviceMethod, options) => {
-                this.verifyStepName(stepName);
-                const [service, method] = serviceMethod.split('.');
-                if (!service || !method) {
-                    throw new Error(`[workflow] expectService '${stepName}' needs 'service.method', got '${serviceMethod}'`);
-                }
-                await this.inlineStep(runId, stepName, async () => {
-                    const rpcName = 'pikkuScenarioGetStubCalls';
-                    const calls = options?.actor
-                        ? await options.actor.invoke(rpcName, { service })
-                        : await rpcService.rpcWithWire(rpcName, { service }, {});
-                    const matching = (calls ?? []).filter((c) => c.service === service &&
-                        c.method === method &&
-                        (options?.calledWith === undefined ||
-                            JSON.stringify(c.args?.[0]) ===
-                                JSON.stringify(options.calledWith)));
-                    const expected = options?.times;
-                    const ok = expected === undefined
-                        ? matching.length > 0
-                        : matching.length === expected;
-                    if (!ok) {
-                        const seen = (calls ?? [])
-                            .map((c) => `${c.service}.${c.method}(${JSON.stringify(c.args?.[0])?.slice(0, 120) ?? ''})`)
-                            .join('\n  ') || '(none)';
-                        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);
-            },
             // Implement workflow.sleep()
             sleep: async (stepName, duration) => {
                 this.verifyStepName(stepName);
@@ -1732,10 +1674,13 @@ export class PikkuWorkflowService {
                 this.verifyStepName(reason);
                 return await this.approvalStep(runId, reason, options);
             }),
-            runScheduledTask: async (taskName) => {
-                await runScheduledTask({ name: taskName });
-            },
         };
+        this.runExtension?.decorateWorkflowWire(workflowWire, {
+            name,
+            runId,
+            rpcService,
+            addonNamespace,
+        });
         return workflowWire;
     }
     verifyStepName(stepName) {

package/dist/wirings/workflow/scenario-cookie-jar.d.ts

@@ -0,0 +1,29 @@
+/** A session held the way a browser holds one, for code driving a real target. */
+export interface ScenarioCookieJar {
+    /** `fetch`, but it sends what the target has set and keeps what it sets. */
+    fetch: typeof fetch;
+    /** Forgets the session — what an actor does before signing in again. */
+    clear(): void;
+    /**
+     * Whether the target has set anything yet. This is a fact about the jar, not
+     * about the session: a target that sets a CSRF or locale cookie before anyone
+     * signs in fills the jar without establishing one. Whoever needs to know
+     * whether a sign-in happened has to track the sign-in.
+     */
+    readonly empty: boolean;
+}
+/**
+ * A `fetch` that remembers cookies.
+ *
+ * A browser persists the session cookie on its own; anything driving a target
+ * from this process has to. Every response is read, not just the sign-in, so a
+ * cookie the target rotates mid-session is followed rather than dropped.
+ *
+ * The jar is a closure local, so two jars never share a session — which is what
+ * lets one scenario sign in as several people without one of them inheriting
+ * the other's session.
+ *
+ * It also stamps `Origin`, because Better Auth rejects a state-changing POST
+ * whose Origin does not match its baseURL.
+ */
+export declare const createCookieJar: (apiUrl: string) => ScenarioCookieJar;

package/dist/wirings/workflow/scenario-cookie-jar.js

@@ -0,0 +1,51 @@
+/**
+ * A `fetch` that remembers cookies.
+ *
+ * A browser persists the session cookie on its own; anything driving a target
+ * from this process has to. Every response is read, not just the sign-in, so a
+ * cookie the target rotates mid-session is followed rather than dropped.
+ *
+ * The jar is a closure local, so two jars never share a session — which is what
+ * lets one scenario sign in as several people without one of them inheriting
+ * the other's session.
+ *
+ * It also stamps `Origin`, because Better Auth rejects a state-changing POST
+ * whose Origin does not match its baseURL.
+ */
+export const createCookieJar = (apiUrl) => {
+    const jar = new Map();
+    const origin = new URL(apiUrl).origin;
+    return {
+        fetch: async (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set('origin', origin);
+            const held = [...jar].map(([name, value]) => `${name}=${value}`);
+            const caller = headers.get('cookie');
+            if (held.length > 0 || caller) {
+                headers.set('cookie', [caller, ...held].filter(Boolean).join('; '));
+            }
+            const response = await fetch(input, { ...init, headers });
+            for (const raw of response.headers.getSetCookie()) {
+                const [pair] = raw.split(';');
+                const separator = pair.indexOf('=');
+                if (separator > 0) {
+                    const name = pair.slice(0, separator);
+                    const value = pair.slice(separator + 1);
+                    // An empty value is how a target deletes a cookie — drop the name
+                    // rather than holding a cookie whose value says it is gone.
+                    if (value) {
+                        jar.set(name, value);
+                    }
+                    else {
+                        jar.delete(name);
+                    }
+                }
+            }
+            return response;
+        },
+        clear: () => jar.clear(),
+        get empty() {
+            return jar.size === 0;
+        },
+    };
+};

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

@@ -0,0 +1,20 @@
+/** How long to keep trying, and how long to wait between tries. */
+export interface PollOptions {
+    /** Total time to keep attempting before giving up. Default 15s. */
+    timeoutMs?: number;
+    /** Gap between attempts. Default 250ms. */
+    intervalMs?: number;
+}
+/**
+ * Attempt something until it answers, or the deadline passes.
+ *
+ * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
+ * answers, because a probe asking whether something happened reports `false`
+ * when it did not. Answering `undefined` at the deadline rather than throwing
+ * leaves the error to the caller, who is the only one who knows what was being
+ * waited for.
+ *
+ * A step that polls its target — a delivery reaching a terminal status, a run
+ * finishing — reaches for this rather than writing the deadline loop again.
+ */
+export declare const pollUntil: <T>(attempt: () => Promise<T | undefined> | T | undefined, { timeoutMs, intervalMs }?: PollOptions) => Promise<T | undefined>;

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

@@ -0,0 +1,25 @@
+/**
+ * Attempt something until it answers, or the deadline passes.
+ *
+ * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
+ * answers, because a probe asking whether something happened reports `false`
+ * when it did not. Answering `undefined` at the deadline rather than throwing
+ * leaves the error to the caller, who is the only one who knows what was being
+ * waited for.
+ *
+ * A step that polls its target — a delivery reaching a terminal status, a run
+ * finishing — reaches for this rather than writing the deadline loop again.
+ */
+export const pollUntil = async (attempt, { timeoutMs = 15_000, intervalMs = 250 } = {}) => {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const answer = await attempt();
+        if (answer !== undefined) {
+            return answer;
+        }
+        if (Date.now() >= deadline) {
+            return undefined;
+        }
+        await new Promise((done) => setTimeout(done, intervalMs));
+    }
+};

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

@@ -0,0 +1,38 @@
+import type { ScenarioStepPhase } from './scenario-step.types.js';
+/**
+ * Renders the English sentence a reporter shows for a scenario step.
+ *
+ * This is the inversion of cucumber: rather than parsing English into a call,
+ * we render English out of a typed call, so the readable report survives
+ * without a regex registry paying for it.
+ *
+ * Lives in core so the CLI reporter and the console render identically.
+ */
+/**
+ * Fill a step's `template` from the input that step was actually called with,
+ * so the reported sentence names the values under test — "sees @pikku/addon-todos"
+ * rather than "sees an addon in the gallery" repeated three times.
+ *
+ * A placeholder with no recorded value renders as nothing and the surrounding
+ * whitespace collapses, so an optional input that was omitted reads as a shorter
+ * sentence rather than a literal `{state}` leaking into the report.
+ */
+export declare const renderStepTemplate: (template: string, input: unknown) => string;
+export declare const composeStepProse: ({ phase, description, template, input, actor, keywordWidth, }: {
+    phase: ScenarioStepPhase;
+    description: string;
+    /**
+     * The prose this step renders, with `{placeholders}` filled from `input`.
+     * Unlike `description`, which documents what the step does, this is what a
+     * reader of the report sees. Falls back to `description` when absent.
+     */
+    template?: string;
+    /** The input this step was called with, as recorded on the run. */
+    input?: unknown;
+    actor?: string;
+    /**
+     * Pad the keyword to this width so a ladder of steps lines its sentences up
+     * under each other. Omit for inline prose.
+     */
+    keywordWidth?: number;
+}) => string;

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

@@ -0,0 +1,45 @@
+/**
+ * Renders the English sentence a reporter shows for a scenario step.
+ *
+ * This is the inversion of cucumber: rather than parsing English into a call,
+ * we render English out of a typed call, so the readable report survives
+ * without a regex registry paying for it.
+ *
+ * Lives in core so the CLI reporter and the console render identically.
+ */
+/**
+ * Fill a step's `template` from the input that step was actually called with,
+ * so the reported sentence names the values under test — "sees @pikku/addon-todos"
+ * rather than "sees an addon in the gallery" repeated three times.
+ *
+ * A placeholder with no recorded value renders as nothing and the surrounding
+ * whitespace collapses, so an optional input that was omitted reads as a shorter
+ * sentence rather than a literal `{state}` leaking into the report.
+ */
+export const renderStepTemplate = (template, input) => {
+    const values = input && typeof input === 'object' ? input : {};
+    return template
+        .replace(/\{(\w+)\}/g, (_match, key) => formatValue(values[key]))
+        .replace(/\s+/g, ' ')
+        .trim();
+};
+const formatValue = (value) => {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+};
+export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
+    const keyword = phase === 'step' ? '' : capitalise(phase);
+    const subject = actor ? `the ${actor}` : '';
+    const rendered = template ? renderStepTemplate(template, input) : description;
+    const sentence = [subject, rendered].filter(Boolean).join(' ');
+    if (keywordWidth === undefined) {
+        return [keyword, sentence].filter(Boolean).join(' ');
+    }
+    return `${keyword.padEnd(keywordWidth)} ${sentence}`;
+};
+const capitalise = (value) => value.charAt(0).toUpperCase() + value.slice(1);

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

@@ -0,0 +1,16 @@
+import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
+/**
+ * The actor this step was called with, or a loud error naming the step.
+ *
+ * A step that talks to the target app needs an identity, but `actor` is
+ * optional on the wire because a pure assertion step needs none. This is the
+ * one place that narrowing happens, so every step file stops writing its own
+ * `actorOf(...)` guard.
+ */
+export declare const requireActor: <TActor>(scenarioStep: PikkuScenarioStepWire<TActor> | undefined) => TActor;
+/**
+ * The environment this run targets, or a loud error naming the step. A run
+ * started outside `pikku scenario run` only carries one when the server has
+ * `API_URL` configured.
+ */
+export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire<unknown> | undefined) => ScenarioEnvironment;

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

@@ -0,0 +1,29 @@
+/**
+ * The actor this step was called with, or a loud error naming the step.
+ *
+ * A step that talks to the target app needs an identity, but `actor` is
+ * optional on the wire because a pure assertion step needs none. This is the
+ * one place that narrowing happens, so every step file stops writing its own
+ * `actorOf(...)` guard.
+ */
+export const requireActor = (scenarioStep) => {
+    const actor = scenarioStep?.actor;
+    if (!actor) {
+        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' was called without an actor. ` +
+            `Pass { actor: actors.<name> } so it runs as that persona.`);
+    }
+    return actor;
+};
+/**
+ * The environment this run targets, or a loud error naming the step. A run
+ * started outside `pikku scenario run` only carries one when the server has
+ * `API_URL` configured.
+ */
+export const requireScenarioEnv = (scenarioStep) => {
+    const env = scenarioStep?.env;
+    if (!env) {
+        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' needs the target environment, but this run carries none. ` +
+            `Run it through 'pikku scenario run <environment>' with scenarios.environments.<environment> declared in pikku.config.json.`);
+    }
+    return env;
+};