@pikku/core 0.12.72 → 0.12.77

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;
 }

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

@@ -6,6 +6,7 @@ import { PikkuError, addError } from '../../errors/error-handler.js';
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
 import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { WorkflowStepNameNotString, } from './pikku-workflow-service.js';
+import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
 /**
  * A workflow service with the scenario capability attached — the two lines
  * `pikku scenario run` needs, in one call so no caller has to remember that the
@@ -39,6 +40,113 @@ addError(ScenarioHookError, {
     status: 500,
     message: 'A scenario lifecycle hook failed.',
 });
+/**
+ * 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 class ScenarioWitnessDisagreement extends PikkuError {
+    stepFunc;
+    expected;
+    actual;
+    constructor(stepFunc, expected, actual) {
+        super(`Scenario step '${stepFunc}' observed different things on different surfaces — ` +
+            `${expected.surface}: ${JSON.stringify(expected.observed)}, ` +
+            `${actual.surface}: ${JSON.stringify(actual.observed)}.`);
+        this.stepFunc = stepFunc;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+addError(ScenarioWitnessDisagreement, {
+    status: 500,
+    message: 'Two surfaces disagreed about what happened.',
+});
+/**
+ * A step resolved to its browser binding but nothing can provide a browser.
+ */
+export class ScenarioBrowserUnavailable extends PikkuError {
+    stepFunc;
+    constructor(stepFunc) {
+        super(`[scenario] step '${stepFunc}' resolved to its browser binding but no browser provider is registered. ` +
+            `Install @pikku/playwright and register its provider, or run with --run default to take the server-side path.`);
+        this.stepFunc = stepFunc;
+    }
+}
+addError(ScenarioBrowserUnavailable, {
+    status: 500,
+    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.
+ */
+export class ScenarioBrowserActorRequired 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.`);
+        this.stepFunc = stepFunc;
+    }
+}
+addError(ScenarioBrowserActorRequired, {
+    status: 500,
+    message: 'A browser binding needs an actor.',
+});
+/**
+ * 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 class ScenarioNoSurfaceBinding extends PikkuError {
+    stepFunc;
+    declared;
+    runSurface;
+    constructor(stepFunc, declared, runSurface) {
+        super(`[scenario] step '${stepFunc}' declares no binding for '${runSurface}' and no 'default' to fall back to ` +
+            `(declares: ${declared.join(', ') || 'nothing'}).`);
+        this.stepFunc = stepFunc;
+        this.declared = declared;
+        this.runSurface = runSurface;
+    }
+}
+addError(ScenarioNoSurfaceBinding, {
+    status: 500,
+    message: 'Step has no runnable binding for this surface.',
+});
+/**
+ * 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 class ScenarioNoWitness extends PikkuError {
+    stepFunc;
+    declared;
+    runSurface;
+    constructor(stepFunc, declared, runSurface) {
+        super(`[scenario] assertion '${stepFunc}' has no witness to run on '${runSurface}' ` +
+            `(declares: ${declared.join(', ') || 'nothing'}). Add a 'default' witness so the ` +
+            `assertion is checked server-side even when the surface cannot check it.`);
+        this.stepFunc = stepFunc;
+        this.declared = declared;
+        this.runSurface = runSurface;
+    }
+}
+addError(ScenarioNoWitness, {
+    status: 500,
+    message: 'Assertion has no witness for this surface.',
+});
 /**
  * The scenario capability, layered onto a workflow service rather than being
  * one.
@@ -70,9 +178,20 @@ export class PikkuScenarioService {
     runActors = new Map();
     scenarioBrowserProvider;
     scenarioEnvironment;
+    runSurface = 'default';
     constructor(engine) {
         this.engine = engine;
     }
+    /**
+     * 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) {
+        this.runSurface = surface;
+    }
+    getRunSurface() {
+        return this.runSurface;
+    }
     /**
      * Registered by `@pikku/playwright` (or any other driver) before a scenario
      * runs. Absent means browser steps cannot run, which the CLI checks up front
@@ -98,7 +217,7 @@ export class PikkuScenarioService {
     async attachRunContext(runId, workflowMeta, options) {
         const actors = options?.actors ??
             (workflowMeta.source === 'scenario'
-                ? await this.resolveScenarioActors()
+                ? await this.resolvePersonas()
                 : undefined);
         if (actors) {
             this.runActors.set(runId, actors);
@@ -203,7 +322,7 @@ export class PikkuScenarioService {
      * for the AI persona conversation loop it pulls in when a scenario actually
      * signs an actor in.
      */
-    async resolveScenarioActors() {
+    async resolvePersonas() {
         const services = getSingletonServices();
         const variables = services?.variables;
         const metaService = services?.metaService;
@@ -213,11 +332,11 @@ export class PikkuScenarioService {
         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.');
+            services?.logger?.warn('A scenario was started without personas but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without them.');
             return undefined;
         }
-        const actorsConfig = await metaService.getScenarioActorsMeta();
-        if (!actorsConfig || Object.keys(actorsConfig).length === 0) {
+        const personas = await metaService.getPersonasMeta();
+        if (!personas || Object.keys(personas).length === 0) {
             return undefined;
         }
         const signInPath = (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
@@ -228,11 +347,11 @@ export class PikkuScenarioService {
             apiUrl,
             appUrl: (await variables.get('APP_URL')) ?? undefined,
         };
-        const { createHttpScenarioActors } = await import('../../services/http-scenario-actors.js');
-        return createHttpScenarioActors({
+        const { createHttpPersonas } = await import('../../services/http-personas.js');
+        return createHttpPersonas({
             apiUrl,
             secret,
-            actors: actorsConfig,
+            personas,
             signInPath,
             rpcPath,
         });
@@ -333,9 +452,11 @@ export class PikkuScenarioService {
                 }, options);
             },
             // Scenario steps: a named `pikkuScenarioStep` run as one durable step.
-            // `given`/`when`/`then` are pure sugar over `step` — the phase only
-            // changes the prose a reporter renders.
-            step: (stepName, stepFunc, data, options) => this.scenarioStep('step', scenarioStepContext(), stepName, stepFunc, data, options),
+            // `given`/`when` are sugar for each other, differing only in the
+            // prose a reporter renders. `then` is not: the phase is what decides
+            // whether the step's bindings are alternatives or witnesses, so the same
+            // step function called two ways runs differently. See
+            // {@link resolveScenarioSurfaces}.
             given: (stepName, stepFunc, data, options) => this.scenarioStep('given', scenarioStepContext(), stepName, stepFunc, data, options),
             when: (stepName, stepFunc, data, options) => this.scenarioStep('when', scenarioStepContext(), stepName, stepFunc, data, options),
             then: (stepName, stepFunc, data, options) => this.scenarioStep('then', scenarioStepContext(), stepName, stepFunc, data, options),
@@ -361,41 +482,76 @@ export class PikkuScenarioService {
         const description = options?.description ??
             this.scenarioStepDescription(packageName, resolvedStepFunc) ??
             stepName;
+        const declared = this.declaredSurfaces(packageName, resolvedStepFunc);
+        const resolution = resolveScenarioSurfaces(phase, declared, this.runSurface);
         return await this.engine.inlineStep(runId, stepName, async () => {
-            const wire = {
-                workflow: workflowWire,
-                scenario: workflowWire,
-                rpc: rpcService?.wire?.rpc,
-                session: rpcService?.wire?.session,
-                pikkuUserId: workflowWire.pikkuUserId,
-                actors: this.runActors.get(runId),
-                scenarioStep: {
-                    name: resolvedStepFunc,
-                    stepName,
-                    runId,
-                    phase,
-                    actor,
-                    env: this.scenarioEnvironment,
-                },
+            const runOnSurface = async (surface) => {
+                const wire = {
+                    workflow: workflowWire,
+                    scenario: workflowWire,
+                    rpc: rpcService?.wire?.rpc,
+                    session: rpcService?.wire?.session,
+                    pikkuUserId: workflowWire.pikkuUserId,
+                    actors: this.runActors.get(runId),
+                    scenarioStep: {
+                        name: resolvedStepFunc,
+                        stepName,
+                        runId,
+                        phase,
+                        surface,
+                        actor,
+                        env: this.scenarioEnvironment,
+                    },
+                };
+                if (surface === 'browser') {
+                    if (!this.scenarioBrowserProvider) {
+                        throw new ScenarioBrowserUnavailable(resolvedStepFunc);
+                    }
+                    if (!actor) {
+                        throw new ScenarioBrowserActorRequired(resolvedStepFunc);
+                    }
+                    wire.browser = await this.scenarioBrowserProvider.sessionFor(actor.name);
+                }
+                return await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
+                    singletonServices: getSingletonServices(),
+                    createWireServices: getCreateWireServices(),
+                    data: () => data,
+                    wire,
+                    packageName: packageName ?? undefined,
+                });
             };
-            if (this.requiresBrowser(packageName, resolvedStepFunc)) {
-                if (!this.scenarioBrowserProvider) {
-                    throw new Error(`[scenario] step '${resolvedStepFunc}' declares 'browser: true' but no browser provider is registered. ` +
-                        `Install @pikku/playwright and register its provider, or run with --no-browser to skip browser steps.`);
+            if (resolution.kind === 'action') {
+                if (resolution.fellBack && !declared.includes('default')) {
+                    throw new ScenarioNoSurfaceBinding(resolvedStepFunc, declared, this.runSurface);
                 }
-                if (!actor) {
-                    throw new Error(`[scenario] step '${resolvedStepFunc}' declares 'browser: true' but was called without an actor. ` +
-                        `Pass { actor: actors.<name> } so the browser signs in as that persona.`);
+                return await runOnSurface(resolution.surface);
+            }
+            if (resolution.surfaces.length === 0) {
+                throw new ScenarioNoWitness(resolvedStepFunc, declared, this.runSurface);
+            }
+            // A `then` runs every witness it has and they must agree. The surface
+            // witness runs first so that when the page is the thing that is wrong,
+            // it is the failure that surfaces.
+            let first;
+            for (const surface of resolution.surfaces) {
+                const observed = await runOnSurface(surface);
+                if (!first) {
+                    first = { surface, observed };
+                    continue;
+                }
+                if (!witnessesAgree(first.observed, observed)) {
+                    throw new ScenarioWitnessDisagreement(resolvedStepFunc, first, {
+                        surface,
+                        observed,
+                    });
+                }
+                // Keep whichever witness actually reported a value, so a step pairing
+                // a returning witness with a throwing one still records an output.
+                if (first.observed === undefined) {
+                    first = { surface, observed };
                 }
-                wire.browser = await this.scenarioBrowserProvider.sessionFor(actor.name);
             }
-            return await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
-                singletonServices: getSingletonServices(),
-                createWireServices: getCreateWireServices(),
-                data: () => data,
-                wire,
-                packageName: packageName ?? undefined,
-            });
+            return first?.observed;
         }, {
             description,
             // Retrying a failed assertion is the wrong behaviour for a test
@@ -413,7 +569,12 @@ export class PikkuScenarioService {
     scenarioStepDescription(packageName, stepFunc) {
         return this.scenarioStepConfig(packageName, stepFunc)?.description;
     }
-    requiresBrowser(packageName, stepFunc) {
-        return this.scenarioStepConfig(packageName, stepFunc)?.browser === true;
+    /**
+     * 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.
+     */
+    declaredSurfaces(packageName, stepFunc) {
+        const surfaces = this.scenarioStepConfig(packageName, stepFunc)?.surfaces;
+        return surfaces?.length ? surfaces : ['default'];
     }
 }