@pikku/core 0.12.71 → 0.12.74

package/src/wirings/workflow/pikku-scenario-service.ts

@@ -16,14 +16,16 @@ import {
   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 { ScenarioPersonas } from '../../services/personas-service.js'
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type {
   ScenarioBrowserProvider,
   ScenarioEnvironment,
   ScenarioStepOptions,
   ScenarioStepPhase,
+  ScenarioSurface,
 } from './scenario-step.types.js'
+import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js'
 import type {
   PikkuScenarioWire,
   PikkuWorkflowWire,
@@ -103,6 +105,118 @@ addError(ScenarioHookError, {
   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 {
+  constructor(
+    public readonly stepFunc: string,
+    public readonly expected: { surface: ScenarioSurface; observed: unknown },
+    public readonly actual: { surface: ScenarioSurface; observed: unknown }
+  ) {
+    super(
+      `Scenario step '${stepFunc}' observed different things on different surfaces — ` +
+        `${expected.surface}: ${JSON.stringify(expected.observed)}, ` +
+        `${actual.surface}: ${JSON.stringify(actual.observed)}.`
+    )
+  }
+}
+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 {
+  constructor(public readonly stepFunc: string) {
+    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.`
+    )
+  }
+}
+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 {
+  constructor(public readonly stepFunc: string) {
+    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.`
+    )
+  }
+}
+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 {
+  constructor(
+    public readonly stepFunc: string,
+    public readonly declared: ScenarioSurface[],
+    public readonly runSurface: ScenarioSurface
+  ) {
+    super(
+      `[scenario] step '${stepFunc}' declares no binding for '${runSurface}' and no 'default' to fall back to ` +
+        `(declares: ${declared.join(', ') || 'nothing'}).`
+    )
+  }
+}
+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 {
+  constructor(
+    public readonly stepFunc: string,
+    public readonly declared: ScenarioSurface[],
+    public readonly runSurface: ScenarioSurface
+  ) {
+    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.`
+    )
+  }
+}
+addError(ScenarioNoWitness, {
+  status: 500,
+  message: 'Assertion has no witness for this surface.',
+})
+
 /**
  * The scenario capability, layered onto a workflow service rather than being
  * one.
@@ -130,12 +244,25 @@ addError(ScenarioHookError, {
 export class PikkuScenarioService implements WorkflowRunExtension {
   // Scenario actors per run: live authenticated clients (cookie jars) are
   // process-local by nature, so they ride this map, never the persisted wire.
-  private runActors = new Map<string, ScenarioActors>()
+  private runActors = new Map<string, ScenarioPersonas>()
   private scenarioBrowserProvider?: ScenarioBrowserProvider
   private scenarioEnvironment?: ScenarioEnvironment
+  private runSurface: ScenarioSurface = 'default'
 
   constructor(private readonly 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.
+   */
+  public setRunSurface(surface: ScenarioSurface) {
+    this.runSurface = surface
+  }
+
+  public getRunSurface(): ScenarioSurface {
+    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
@@ -167,12 +294,12 @@ export class PikkuScenarioService implements WorkflowRunExtension {
   public async attachRunContext(
     runId: string,
     workflowMeta: any,
-    options?: { actors?: ScenarioActors }
+    options?: { actors?: ScenarioPersonas }
   ): Promise<void> {
     const actors =
       options?.actors ??
       (workflowMeta.source === 'scenario'
-        ? await this.resolveScenarioActors()
+        ? await this.resolvePersonas()
         : undefined)
     if (actors) {
       this.runActors.set(runId, actors)
@@ -323,7 +450,7 @@ export class PikkuScenarioService implements WorkflowRunExtension {
    * for the AI persona conversation loop it pulls in when a scenario actually
    * signs an actor in.
    */
-  public async resolveScenarioActors(): Promise<ScenarioActors | undefined> {
+  public async resolvePersonas(): Promise<ScenarioPersonas | undefined> {
     const services = getSingletonServices()
     const variables = services?.variables
     const metaService = services?.metaService
@@ -334,12 +461,12 @@ export class PikkuScenarioService implements WorkflowRunExtension {
     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.'
+        '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 =
@@ -351,12 +478,12 @@ export class PikkuScenarioService implements WorkflowRunExtension {
       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,
     })
@@ -522,8 +649,11 @@ export class PikkuScenarioService implements WorkflowRunExtension {
       },
 
       // 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.
+      // `given`/`when`/`step` 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}.
       step: (stepName, stepFunc, data, options) =>
         this.scenarioStep(
           'step',
@@ -592,56 +722,104 @@ export class PikkuScenarioService implements WorkflowRunExtension {
         ? `${addonNamespace}:${stepFunc}`
         : stepFunc
 
-    const actor = options?.actor as ScenarioActors[string] | undefined
+    const actor = options?.actor as ScenarioPersonas[string] | undefined
     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: PikkuWire = {
-          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,
-          },
-        }
-        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.`
+        const runOnSurface = async (surface: ScenarioSurface) => {
+          const wire: PikkuWire = {
+            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
             )
           }
-          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 runPikkuFunc(
+            'workflow',
+            workflowName,
+            resolvedStepFunc,
+            {
+              singletonServices: getSingletonServices()!,
+              createWireServices: getCreateWireServices(),
+              data: () => data,
+              wire,
+              packageName: packageName ?? undefined,
+            }
+          )
+        }
+
+        if (resolution.kind === 'action') {
+          if (resolution.fellBack && !declared.includes('default')) {
+            throw new ScenarioNoSurfaceBinding(
+              resolvedStepFunc,
+              declared,
+              this.runSurface
             )
           }
-          wire.browser = await this.scenarioBrowserProvider.sessionFor(
-            actor.name
+          return await runOnSurface(resolution.surface)
+        }
+
+        if (resolution.surfaces.length === 0) {
+          throw new ScenarioNoWitness(
+            resolvedStepFunc,
+            declared,
+            this.runSurface
           )
         }
-        return await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
-          singletonServices: getSingletonServices()!,
-          createWireServices: getCreateWireServices(),
-          data: () => data,
-          wire,
-          packageName: packageName ?? undefined,
-        })
+
+        // 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: { surface: ScenarioSurface; observed: unknown } | undefined
+        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 }
+          }
+        }
+        return first?.observed
       },
       {
         description,
@@ -673,10 +851,15 @@ export class PikkuScenarioService implements WorkflowRunExtension {
     return this.scenarioStepConfig(packageName, stepFunc)?.description
   }
 
-  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(
     packageName: string | null,
     stepFunc: string
-  ): boolean {
-    return this.scenarioStepConfig(packageName, stepFunc)?.browser === true
+  ): ScenarioSurface[] {
+    const surfaces = this.scenarioStepConfig(packageName, stepFunc)?.surfaces
+    return surfaces?.length ? surfaces : ['default']
   }
 }

package/src/wirings/workflow/pikku-workflow-service.test.ts

@@ -30,9 +30,6 @@ describe('pikku-workflow-service worker registration', () => {
 })
 
 describe('pikku-workflow-service per-workflow queue warning', () => {
-  // Losing the per-workflow orchestrator queues is silent — dispatch just falls
-  // back to the single shared queue and one slow step starves every workflow
-  // behind it. These assert the misconfiguration is announced at wiring time.
   const setup = (workflowNames: string[], perWorkflowQueues: string[] = []) => {
     resetPikkuState()
     const warnings: string[] = []
@@ -106,7 +103,6 @@ describe('pikku-workflow-service run-level inline', () => {
     const workflowName = 'testRunInlineNoQueue'
     const graphHash = 'run-inline-no-queue-hash'
 
-    // No queueService configured at all → the run executes inline.
     pikkuState(null, 'package', 'singletonServices', {
       logger: {
         error: () => {},
@@ -139,7 +135,6 @@ describe('pikku-workflow-service run-level inline', () => {
 
     const { runId } = await ws.startWorkflow(workflowName, {}, {}, {})
 
-    // With no queue service the run is created as inline.
     const run = await ws.getRun(runId)
     assert.equal(run?.inline, true, 'run should be marked as inline')
 
@@ -168,7 +163,6 @@ describe('pikku-workflow-service run-level inline', () => {
       pikkuFuncId: workflowName,
       source: 'dsl',
       graphHash,
-      // no inline flag
     }
 
     const functionMetaState = pikkuState(null, 'function', 'meta')
@@ -186,7 +180,6 @@ describe('pikku-workflow-service run-level inline', () => {
 
     await ws.startWorkflow(workflowName, {}, {})
 
-    // Wait a tick
     await new Promise((r) => setTimeout(r, 50))
 
     assert.equal(queued, true, 'workflow should have been queued')
@@ -198,9 +191,6 @@ describe('pikku-workflow-service run-level inline', () => {
 })
 
 describe('pikku-workflow-service per-function step dispatch', () => {
-  // Expose the protected dispatchStep so we can assert the dispatch decision
-  // in isolation: a step queues only when its function opts out of inline
-  // execution (workflowQueued: true).
   class TestWorkflowService extends InMemoryWorkflowService {
     public callDispatchStep(rpcName: string) {
       return this.dispatchStep('run-1', 'step-1', rpcName, {})
@@ -263,7 +253,6 @@ describe('pikku-workflow-service per-function step dispatch', () => {
     const ws = new TestWorkflowService()
     pikkuState(null, 'package', 'singletonServices', {
       logger: { error() {}, info() {}, warn() {}, debug() {} },
-      // no queueService
     } as any)
 
     setupFunction('queuedStepNoQueue', true)
@@ -504,7 +493,6 @@ describe('pikku-workflow-service suspend', () => {
       type: 'test',
     })
 
-    // First suspend: 'await_build' pauses the run.
     await assert.rejects(
       ws.runWorkflowJob(runId, {}),
       (error: unknown) => error instanceof WorkflowSuspendedException
@@ -513,8 +501,6 @@ describe('pikku-workflow-service suspend', () => {
     assert.equal(run?.status, 'suspended')
     assert.equal(run?.error?.message, 'Building')
 
-    // Resuming must hit the SECOND suspend ('awaiting_approval'), not fall
-    // through it — this is what the shared-step-name bug broke.
     await ws.resumeWorkflow(runId)
     await assert.rejects(
       ws.runWorkflowJob(runId, {}),
@@ -524,7 +510,6 @@ describe('pikku-workflow-service suspend', () => {
     assert.equal(run?.status, 'suspended')
     assert.equal(run?.error?.message, 'Awaiting approval')
 
-    // Resuming again completes the workflow.
     await ws.resumeWorkflow(runId)
     await ws.runWorkflowJob(runId, {})
     run = await ws.getRun(runId)
@@ -537,11 +522,6 @@ describe('pikku-workflow-service suspend', () => {
   })
 })
 
-/**
- * A minimal StandardSchemaV1 — the same interface zod/valibot/arktype expose via
- * `~standard`. Hand-rolled here because @pikku/core deliberately has no zod
- * dependency: schemas reach it through the standard-schema spec only.
- */
 const approvalDecisionSchema: StandardSchemaV1<
   { approved: boolean; comment?: string },
   { approved: boolean; comment?: string }
@@ -638,8 +618,6 @@ describe('pikku-workflow-service approval', () => {
     )
     assert.equal((await ws.getRun(runId))?.status, 'suspended')
 
-    // THE point of an approval vs a suspend: a bare resume with no decision
-    // recorded must re-suspend, not walk past the gate.
     await ws.resumeWorkflow(runId)
     await assert.rejects(
       ws.runWorkflowJob(runId, {}),
@@ -717,19 +695,14 @@ describe('pikku-workflow-service approval', () => {
       (error: unknown) => error instanceof WorkflowSuspendedException
     )
 
-    // The resume payload crosses an HTTP boundary from an untrusted caller.
-    // approveStep only records it; validation happens on replay, inside the
-    // workflow body, which is the only place the schema value is in scope.
     await ws.approveStep(runId, 'Approve invoice', { approved: 'yes-please' })
 
-    // An invalid decision must leave the gate closed rather than fail the run.
     await assert.rejects(
       ws.runWorkflowJob(runId, {}),
       (error: unknown) => error instanceof WorkflowSuspendedException
     )
     assert.equal((await ws.getRun(runId))?.status, 'suspended')
 
-    // ...and the rejection is legible to whoever tries to approve next.
     const state = await ws.getRunState(runId)
     assert.match(
       JSON.stringify(state),
@@ -737,7 +710,6 @@ describe('pikku-workflow-service approval', () => {
       'expected the validation failure to be recorded in run state'
     )
 
-    // A subsequent valid decision still lands.
     await ws.approveStep(runId, 'Approve invoice', { approved: false })
     await ws.runWorkflowJob(runId, {})
     const run = await ws.getRun(runId)
@@ -811,14 +783,11 @@ describe('pikku-workflow-service approval', () => {
       (error: unknown) => error instanceof WorkflowSuspendedException
     )
 
-    // Let the gate expire and resolve.
     await new Promise((resolve) => setTimeout(resolve, 25))
     await ws.resumeWorkflow(runId)
     await ws.runWorkflowJob(runId, {})
     assert.equal((await ws.getRun(runId))?.status, 'completed')
 
-    // The gate caches its outcome and never re-reads state, so accepting this
-    // would discard it silently. The approver must be told it did not land.
     await assert.rejects(
       ws.approveStep(runId, 'Approve invoice', { approved: true }),
       (error: unknown) =>
@@ -826,7 +795,6 @@ describe('pikku-workflow-service approval', () => {
         error.payload.outcome === 'expired'
     )
 
-    // The resolved outcome stands.
     const run = await ws.getRun(runId)
     assert.deepEqual(run?.output, { decision: { status: 'expired' } })
 
@@ -860,8 +828,6 @@ describe('pikku-workflow-service approval', () => {
 
     await ws.approveStep(runId, 'Approve invoice', { approved: true })
 
-    // Expiry fires unconditionally (an enqueued durable timer can't be
-    // retracted), so it must no-op once a decision has landed.
     await new Promise((resolve) => setTimeout(resolve, 25))
     await ws.resumeWorkflow(runId)
     await ws.runWorkflowJob(runId, {})
@@ -877,11 +843,6 @@ describe('pikku-workflow-service approval', () => {
 })
 
 describe('pikku-workflow-service run identity on failure', () => {
-  // A failing inline run throws before startWorkflow can return `{ runId }`,
-  // so a caller that wants to read the run back — its steps, which one failed,
-  // what it was called with — has nothing to read it by. `onRunCreated` fires
-  // as soon as the run exists, which is the only moment guaranteed to happen
-  // whether the run goes on to pass, fail, or suspend.
   const runFailing = async (name: string) => {
     resetPikkuState()
     const ws = new InMemoryWorkflowService()