@pikku/core 0.12.72 → 0.12.77

package/src/wirings/workflow/scenario-step.test.ts

@@ -5,8 +5,9 @@ import { createScenarioRunner } from './pikku-scenario-service.js'
 import type { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import { addFunction } from '../../function/function-runner.js'
-import type { ScenarioActor } from '../../services/scenario-actors-service.js'
+import type { ScenarioPersona } from '../../services/personas-service.js'
 import type { PikkuWire } from '../../types/core.types.js'
+import type { ScenarioSurface } from './scenario-step.types.js'
 import { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
@@ -14,7 +15,7 @@ const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 const fakeActor = (
   name: string,
   handler: (rpcName: string, data: unknown) => Promise<unknown>
-): ScenarioActor & { calls: Array<{ rpcName: string; data: unknown }> } => {
+): ScenarioPersona & { calls: Array<{ rpcName: string; data: unknown }> } => {
   const calls: Array<{ rpcName: string; data: unknown }> = []
   return {
     name,
@@ -87,8 +88,6 @@ describe('scenario actor steps (workflow.do with `actor`)', () => {
     const first = await wire.do('step', 'someRpc', {}, { actor: yasser })
     assert.deepEqual(first, { n: 1 })
 
-    // Simulate replay: reset per-run ordinals so the same logical step name
-    // resolves to the same durable step key.
     await (ws as any).beginReplay(runId)
     const replayWire = ws.createWorkflowWire('scenarioTest', runId, {})
     const replayed = await replayWire.do(
@@ -113,7 +112,6 @@ describe('scenario actor steps (workflow.do with `actor`)', () => {
         },
       },
     })
-    // Function meta says this RPC would normally dispatch via the queue.
     pikkuState(null, 'function', 'meta').queuedRpc = {
       pikkuFuncId: 'queuedRpc',
       workflowQueued: true,
@@ -146,20 +144,18 @@ const registerStep = (
   name: string,
   config: {
     description?: string
-    browser?: boolean
+    surfaces?: ScenarioSurface[]
     func: (services: any, data: any, wire: PikkuWire) => Promise<unknown>
   }
 ) => {
   addFunction(name, config as any)
-  // `pikkuScenarioStep` maps to PikkuFunctionSessionless, which is what the
-  // inspector records — a step is driven by an actor, not by a wire session.
   pikkuState(null, 'function', 'meta')[name] = {
     pikkuFuncId: name,
     sessionless: true,
   } as any
 }
 
-describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
+describe('pikkuScenarioStep (scenario.given/when/then)', () => {
   beforeEach(() => resetPikkuState())
 
   test('the step func is called with the phase, step identity and data on the wire', async () => {
@@ -206,12 +202,11 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
-    await wire.step('a', 'noop')
     await wire.given('b', 'noop')
     await wire.when('c', 'noop')
     await wire.then('d', 'noop')
 
-    assert.deepEqual(phases, ['step', 'given', 'when', 'then'])
+    assert.deepEqual(phases, ['given', 'when', 'then'])
   })
 
   test('the actor is handed to the step rather than used to dispatch it', async () => {
@@ -295,7 +290,7 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
-    const result = await wire.step('waits for the page', 'flaky', undefined, {
+    const result = await wire.when('waits for the page', 'flaky', undefined, {
       retries: 3,
       retryDelay: 1,
     })
@@ -306,9 +301,10 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
   test('a browser step fails loudly when no provider is registered', async () => {
     const { workflowService: ws, scenarioService } = createScenarioRunner()
+    scenarioService.setRunSurface('browser')
     const shopper = fakeActor('shopper', async () => ({}))
     registerStep('visitsCheckout', {
-      browser: true,
+      surfaces: ['browser'],
       func: async () => null,
     })
 
@@ -325,6 +321,7 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
   test('a registered provider hands the step a session keyed by the actor', async () => {
     const { workflowService: ws, scenarioService } = createScenarioRunner()
+    scenarioService.setRunSurface('browser')
     const shopper = fakeActor('shopper', async () => ({}))
     const requested: string[] = []
     const session = { actor: 'shopper' } as any
@@ -337,7 +334,7 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
 
     let handed: unknown
     registerStep('visitsCheckout', {
-      browser: true,
+      surfaces: ['browser'],
       func: async (_services, _data, wire) => {
         handed = wire.browser
         return null
@@ -354,13 +351,164 @@ describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
     assert.equal(handed, session)
   })
 
+  test('an action step falls back to its default binding rather than failing', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    scenarioService.setRunSurface('browser')
+    const ran: ScenarioSurface[] = []
+    registerStep('seedsAnAccount', {
+      surfaces: ['default'],
+      func: async (_services, _data, wire) => {
+        ran.push(wire.scenarioStep!.surface)
+        return null
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.given('an account exists', 'seedsAnAccount')
+
+    assert.deepEqual(ran, ['default'], 'setup does not need a UI to be honest')
+  })
+
+  test('an action step with no runnable binding fails rather than silently skipping', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    scenarioService.setRunSurface('cli')
+    registerStep('clicksBuy', {
+      surfaces: ['browser'],
+      func: async () => null,
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+
+    await assert.rejects(
+      wire.when('shopper buys it', 'clicksBuy'),
+      /declares no binding for 'cli'/
+    )
+  })
+
+  test('a then step runs every witness, surface first', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    scenarioService.setRunSurface('browser')
+    scenarioService.setScenarioBrowserProvider({
+      sessionFor: async () => ({ actor: 'shopper' }) as any,
+    } as any)
+    const shopper = fakeActor('shopper', async () => ({}))
+    const ran: ScenarioSurface[] = []
+    registerStep('seesTheOrderConfirmed', {
+      surfaces: ['browser', 'default'],
+      func: async (_services, _data, wire) => {
+        ran.push(wire.scenarioStep!.surface)
+        return { status: 'paid' }
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.then(
+      'shopper sees the order confirmed',
+      'seesTheOrderConfirmed',
+      undefined,
+      { actor: shopper }
+    )
+
+    assert.deepEqual(ran, ['browser', 'default'])
+  })
+
+  test('the page saying something else than the database is a failure', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    scenarioService.setRunSurface('browser')
+    scenarioService.setScenarioBrowserProvider({
+      sessionFor: async () => ({ actor: 'shopper' }) as any,
+    } as any)
+    const shopper = fakeActor('shopper', async () => ({}))
+    registerStep('seesTheOrderConfirmed', {
+      surfaces: ['browser', 'default'],
+      func: async (_services, _data, wire) =>
+        wire.scenarioStep!.surface === 'browser'
+          ? { status: 'pending' }
+          : { status: 'paid' },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+
+    await assert.rejects(
+      wire.then(
+        'shopper sees the order confirmed',
+        'seesTheOrderConfirmed',
+        undefined,
+        { actor: shopper }
+      ),
+      /observed different things on different surfaces/
+    )
+  })
+
+  test('a default run pays for only one witness', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const ran: ScenarioSurface[] = []
+    registerStep('seesTheOrderConfirmed', {
+      surfaces: ['browser', 'default'],
+      func: async (_services, _data, wire) => {
+        ran.push(wire.scenarioStep!.surface)
+        return { status: 'paid' }
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.then('shopper sees the order confirmed', 'seesTheOrderConfirmed')
+
+    assert.deepEqual(ran, ['default'])
+  })
+
+  test('an assertion with no witness for the run fails instead of passing having checked nothing', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    scenarioService.setRunSurface('cli')
+    let ran = 0
+    registerStep('seesTheBanner', {
+      surfaces: ['browser'],
+      func: async () => {
+        ran++
+        return { visible: true }
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+
+    await assert.rejects(
+      wire.then('shopper sees the banner', 'seesTheBanner'),
+      /has no witness to run on 'cli'/
+    )
+    assert.equal(ran, 0, 'nothing ran — which is exactly why it must not pass')
+  })
+
+  test('a browser-only assertion is not silently skipped by the fast suite', async () => {
+    // The fast path is where this is most dangerous: `--run default` prints no
+    // coverage line, so a skipped assertion would leave no trace at all.
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    registerStep('seesTheBanner', {
+      surfaces: ['browser'],
+      func: async () => ({ visible: true }),
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+
+    await assert.rejects(
+      wire.then('shopper sees the banner', 'seesTheBanner'),
+      /has no witness to run on 'default'/
+    )
+  })
+
   test('a non-string step target is rejected instead of silently dispatching', async () => {
     const { workflowService: ws, scenarioService } = createScenarioRunner()
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
 
     await assert.rejects(
-      (wire.step as any)('a name', async () => 'inline'),
+      (wire.when as any)('a name', async () => 'inline'),
       /string/i
     )
   })
@@ -446,8 +594,6 @@ describe('scenario step input is recorded on the run', () => {
       packageName: '@pikku/addon-todos',
     })
 
-    // A reporter renders each step's prose from this, so two calls to one step
-    // must be distinguishable by what they were asked to check.
     const steps = await ws.getRunSteps(runId)
     assert.deepEqual(
       steps.map((step) => step.data),
@@ -496,8 +642,6 @@ describe('scenario step names its function on the run', () => {
 
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
-    // What a loop produces: the durable name is the interpolated one, so it
-    // matches no statically recorded step name.
     for (const packageName of ['console', 'todos']) {
       await wire.then(`sees ${packageName}`, 'seesAddon', { packageName })
     }

package/src/wirings/workflow/scenario-step.types.ts

@@ -1,28 +1,105 @@
-import type { ScenarioActor } from '../../services/scenario-actors-service.js'
+import type { ScenarioPersona } from '../../services/personas-service.js'
 
 /**
  * Scenario steps: named, typed units of scenario behaviour.
  *
  * A step's body is an ordinary pikku function, so it may drive a browser, call
- * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
- * `step` — they only change the prose the reporter renders.
+ * an RPC as its actor, or run a workflow. `given` and `when` differ only in the
+ * prose the reporter renders; `then` also changes what runs, because its
+ * bindings are witnesses — every declared surface is observed and the
+ * observations must agree. See {@link ScenarioSurfaceResolution}.
  */
 
 /**
- * Which Gherkin-style keyword the reporter prefixes this step with. `step`
- * renders no prefix at all.
+ * Which Gherkin-style keyword the reporter prefixes this step with.
+ *
+ * Every step takes one. A scenario is read by people deciding whether it
+ * describes the behaviour they wanted, and a step that says only what it does
+ * without saying whether it is setup, action or claim is the one nobody can
+ * check — which is also why PKU680 can tell a scenario that never asserts.
+ */
+export type ScenarioStepPhase = 'given' | 'when' | 'then'
+
+/**
+ * Who acts in a step.
+ *
+ * `persona` is a person driving the system through one of its surfaces — the
+ * ordinary `pikkuScenarioStep`. `platform` is the app acting on itself ("the
+ * platform has expired the trial"), and `addon` is a third-party system acting
+ * on it ("Stripe's webhook arrives"), contributed by the addon that wraps that
+ * service.
+ *
+ * The three are separate declarations rather than a field on one, so the
+ * inspector verifies a step's kind by which function was called rather than by
+ * trusting a string literal — and so an addon package exports only addon steps,
+ * which is checkable.
  */
-export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then'
+export type ScenarioStepKind = 'persona' | 'platform' | 'addon'
 
 /**
- * Options accepted by `scenario.step/given/when/then`.
+ * How an actor drives the system for one step.
+ *
+ * A step declares one implementation per surface it supports, and the runner
+ * picks between them — so the same ladder can run through a real browser, over
+ * the websocket, or entirely server-side.
+ *
+ * `default` is the floor: it is what every other surface falls back to, so it
+ * can never itself fall back.
+ */
+export type ScenarioSurface = 'browser' | 'cli' | 'default'
+
+export const SCENARIO_SURFACES: readonly ScenarioSurface[] = [
+  'browser',
+  'cli',
+  'default',
+]
+
+/**
+ * How a step's declared surfaces resolve for one run.
+ *
+ * `given`/`when` bindings are **alternatives** — clicking Buy and calling
+ * `createOrder` are two ways to cause one effect, so exactly one runs.
+ *
+ * `then` bindings are **witnesses** — "the order row says paid" and "the
+ * confirmation panel says paid" are different claims that share a name, and the
+ * gap between them is the bug nobody catches. So every declared witness runs and
+ * they must agree.
+ */
+export type ScenarioSurfaceResolution =
+  | {
+      kind: 'action'
+      surface: ScenarioSurface
+      /** The run asked for a surface this step does not implement. */
+      fellBack: boolean
+    }
+  | {
+      kind: 'witness'
+      /**
+       * Every witness to run, surface first. Empty means the assertion has no
+       * binding this run can execute at all — nothing would check anything, so
+       * the step fails rather than reporting a pass it never earned.
+       */
+      surfaces: ScenarioSurface[]
+      /**
+       * Something checked the assertion, but not on the surface its prose
+       * claims — so nobody looked at the UI. Reported as its own state and
+       * counted against coverage: not being in the UI *is* the finding.
+       *
+       * Disjoint from an empty `surfaces`; an assertion that ran nowhere is a
+       * failure, not a coverage statistic.
+       */
+      unwitnessed: boolean
+    }
+
+/**
+ * Options accepted by `scenario.given/when/then`.
  *
  * Note the retry default differs from an ordinary workflow step: retrying a
  * failed assertion is the wrong behaviour for a test primitive, so steps
  * default to no retries.
  */
 export interface ScenarioStepOptions {
-  /** The actor this step runs as. Required for steps declaring `browser: true`. */
+  /** The actor this step runs as. Required for steps declaring a `browser` binding. */
   actor?: unknown
   /** Overrides the step's own `description` for this call site only. */
   description?: string
@@ -33,7 +110,7 @@ export interface ScenarioStepOptions {
 
 /**
  * The environment a scenario run targets, as declared in pikku.config.json
- * under `scenarios.environments`.
+ * under `environments`.
  */
 export interface ScenarioEnvironment {
   /** Base API URL of the target app, INCLUDING the HTTP prefix. */
@@ -46,16 +123,21 @@ export interface ScenarioEnvironment {
  * The `scenarioStep` wire, present on every scenario step invocation.
  *
  * `TActor` is the project's own actor type, so a step reaches only the RPCs its
- * actors can actually call. It defaults to the open `ScenarioActor` for a
+ * actors can actually call. It defaults to the open `ScenarioPersona` for a
  * project that declares no registry.
  */
-export interface PikkuScenarioStepWire<TActor = ScenarioActor> {
+export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
   /** Registered step name (also its pikkuFuncId) */
   name: string
   /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
   stepName: string
   runId: string
   phase: ScenarioStepPhase
+  /**
+   * Which of the step's bindings is currently executing. A `then` step runs once
+   * per witness, so its body sees this change between invocations.
+   */
+  surface: ScenarioSurface
   /**
    * The actor this step runs as, when one was given. Call RPCs through it
    * (`actor.invoke(...)`) so they run against the target environment as that
@@ -96,7 +178,7 @@ export interface TestIdSelector {
 
 /**
  * Structural browser handle, present only when the runner provisioned a
- * browser for this step (`browser: true` on the step config).
+ * browser for this step (a `browser` binding on the step config).
  *
  * `@pikku/core` deliberately never imports playwright — it must stay
  * dependency-free for edge runtimes. `@pikku/playwright` augments this

package/src/wirings/workflow/scenario-surface.test.ts

@@ -0,0 +1,146 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js'
+import type { ScenarioSurface } from './scenario-step.types.js'
+
+const ALL: ScenarioSurface[] = ['browser', 'cli', 'default']
+
+describe('action steps pick exactly one binding', () => {
+  test('runs the binding the run asked for', () => {
+    assert.deepEqual(resolveScenarioSurfaces('when', ALL, 'browser'), {
+      kind: 'action',
+      surface: 'browser',
+      fellBack: false,
+    })
+  })
+
+  test('falls back to default and says so when the surface is not implemented', () => {
+    assert.deepEqual(resolveScenarioSurfaces('when', ['default'], 'browser'), {
+      kind: 'action',
+      surface: 'default',
+      fellBack: true,
+    })
+  })
+
+  test('given resolves like when, not like then', () => {
+    assert.deepEqual(resolveScenarioSurfaces('given', ALL, 'cli'), {
+      kind: 'action',
+      surface: 'cli',
+      fellBack: false,
+    })
+  })
+
+  test('a default run never counts as a fallback', () => {
+    assert.deepEqual(resolveScenarioSurfaces('when', ['default'], 'default'), {
+      kind: 'action',
+      surface: 'default',
+      fellBack: false,
+    })
+  })
+})
+
+describe('then steps run every witness', () => {
+  test('a browser run checks the page AND the system of record', () => {
+    assert.deepEqual(
+      resolveScenarioSurfaces('then', ['browser', 'default'], 'browser'),
+      { kind: 'witness', surfaces: ['browser', 'default'], unwitnessed: false }
+    )
+  })
+
+  test('the surface witness comes first, so its failure is the one reported', () => {
+    const resolution = resolveScenarioSurfaces(
+      'then',
+      ['default', 'browser'],
+      'browser'
+    )
+    assert.equal(resolution.kind, 'witness')
+    assert.deepEqual(
+      resolution.kind === 'witness' ? resolution.surfaces[0] : null,
+      'browser'
+    )
+  })
+
+  test('a default run is unchanged — one witness, no extra cost', () => {
+    assert.deepEqual(
+      resolveScenarioSurfaces('then', ['browser', 'default'], 'default'),
+      { kind: 'witness', surfaces: ['default'], unwitnessed: false }
+    )
+  })
+
+  test('no witness for the run surface is flagged rather than excused', () => {
+    assert.deepEqual(resolveScenarioSurfaces('then', ['default'], 'browser'), {
+      kind: 'witness',
+      surfaces: ['default'],
+      unwitnessed: true,
+    })
+  })
+
+  test('a browser-only assertion has nothing to run on a default run', () => {
+    // No witness at all is not a coverage statistic — nothing checked anything,
+    // so `unwitnessed` stays false and the caller is expected to fail the step.
+    assert.deepEqual(resolveScenarioSurfaces('then', ['browser'], 'default'), {
+      kind: 'witness',
+      surfaces: [],
+      unwitnessed: false,
+    })
+  })
+
+  test('an assertion that runs nowhere is not counted as merely unwitnessed', () => {
+    assert.deepEqual(resolveScenarioSurfaces('then', ['browser'], 'cli'), {
+      kind: 'witness',
+      surfaces: [],
+      unwitnessed: false,
+    })
+  })
+
+  test('unwitnessed means checked somewhere else, never checked nowhere', () => {
+    const ranElsewhere = resolveScenarioSurfaces('then', ['default'], 'cli')
+    assert.equal(ranElsewhere.kind, 'witness')
+    assert.ok(
+      ranElsewhere.kind === 'witness' && ranElsewhere.surfaces.length > 0,
+      'the two states are disjoint: unwitnessed always has something that ran'
+    )
+    assert.equal(
+      ranElsewhere.kind === 'witness' && ranElsewhere.unwitnessed,
+      true
+    )
+  })
+})
+
+describe('witness agreement', () => {
+  test('key order does not make two observations disagree', () => {
+    assert.equal(
+      witnessesAgree(
+        { status: 'paid', total: 500 },
+        { total: 500, status: 'paid' }
+      ),
+      true
+    )
+  })
+
+  test('a page showing something else is a disagreement', () => {
+    assert.equal(
+      witnessesAgree({ status: 'paid' }, { status: 'pending' }),
+      false
+    )
+  })
+
+  test('a witness that asserted by throwing is not compared', () => {
+    assert.equal(witnessesAgree(undefined, { status: 'paid' }), true)
+    assert.equal(witnessesAgree({ status: 'paid' }, undefined), true)
+  })
+
+  test('nested observations compare structurally', () => {
+    assert.equal(
+      witnessesAgree(
+        { order: { items: [{ sku: 'a' }, { sku: 'b' }] } },
+        { order: { items: [{ sku: 'a' }, { sku: 'b' }] } }
+      ),
+      true
+    )
+    assert.equal(
+      witnessesAgree({ items: ['a', 'b'] }, { items: ['b', 'a'] }),
+      false
+    )
+  })
+})

package/src/wirings/workflow/scenario-surface.ts

@@ -0,0 +1,71 @@
+import type {
+  ScenarioStepPhase,
+  ScenarioSurface,
+  ScenarioSurfaceResolution,
+} from './scenario-step.types.js'
+
+/**
+ * Resolve which of a step's declared bindings run, for one step, in one run.
+ *
+ * The asymmetry between phases is the whole point — see
+ * {@link ScenarioSurfaceResolution}.
+ */
+export const resolveScenarioSurfaces = (
+  phase: ScenarioStepPhase,
+  declared: readonly ScenarioSurface[],
+  runSurface: ScenarioSurface
+): ScenarioSurfaceResolution => {
+  const has = (surface: ScenarioSurface) => declared.includes(surface)
+
+  if (phase !== 'then') {
+    if (has(runSurface)) {
+      return { kind: 'action', surface: runSurface, fellBack: false }
+    }
+    return { kind: 'action', surface: 'default', fellBack: true }
+  }
+
+  const surfaces: ScenarioSurface[] = []
+  if (runSurface !== 'default' && has(runSurface)) {
+    surfaces.push(runSurface)
+  }
+  if (has('default')) {
+    surfaces.push('default')
+  }
+  return {
+    kind: 'witness',
+    surfaces,
+    // Only meaningful once something ran: an assertion checked server-side
+    // under `--run browser` is a coverage gap, but one checked nowhere at all
+    // is a step that did not happen, which the caller fails rather than counts.
+    unwitnessed:
+      surfaces.length > 0 && runSurface !== 'default' && !has(runSurface),
+  }
+}
+
+/**
+ * Structural comparison of two witnesses' observations.
+ *
+ * A witness that returns `undefined` asserted by throwing rather than by
+ * reporting what it saw, so it is not compared — that keeps assertion-style
+ * steps working without forcing every one of them to return a value.
+ */
+export const witnessesAgree = (a: unknown, b: unknown): boolean => {
+  if (a === undefined || b === undefined) {
+    return true
+  }
+  return stableStringify(a) === stableStringify(b)
+}
+
+const stableStringify = (value: unknown): string => {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value) ?? 'undefined'
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+  return `{${entries.join(',')}}`
+}