@pikku/core 0.12.72 → 0.12.77

package/dist/wirings/virtual-user/virtual-user-intents.js

@@ -0,0 +1,142 @@
+/**
+ * The stack of things this user is in the middle of — and the whole of the
+ * engine's randomness.
+ *
+ * A real person does not run a flow end to end: they start something, get
+ * pulled away, do a bit of something else, come back to a world that moved
+ * underneath them, and sometimes never come back at all. Modelling that as a
+ * stack of partially-completed intents is what produces the bugs worth having —
+ * half-mutated state, a flow resumed against changed data, an invite accepted
+ * after the plan changed — none of which a scripted scenario can reach.
+ *
+ * Scheduling is the engine's job and the model's turns are not: the model
+ * decides what to do *within* the active intent, the stack decides which intent
+ * that is. Keeping the split there is what makes a run reproducible from a seed
+ * while the work inside it stays free.
+ *
+ * A feature is only where an intent comes from. Nothing here tracks whether one
+ * was "completed correctly", and the model is never told an intent boundary
+ * exists.
+ */
+export class IntentStack {
+    rng;
+    profile;
+    maxOpen;
+    tracked = [];
+    unstarted;
+    active = null;
+    counter = 0;
+    constructor(sources, rng, profile, 
+    /** Cap on intents open at once, so a distractible user still finishes things. */
+    maxOpen = 3) {
+        this.rng = rng;
+        this.profile = profile;
+        this.maxOpen = maxOpen;
+        this.unstarted = [...sources];
+    }
+    /**
+     * Pick the intent for this tick, or `null` when there is nothing left to do.
+     *
+     * The first tick always starts something; after that the four moves are
+     * weighted by the disposition, and a move that has nowhere to go degrades to
+     * `continue` rather than stalling the run.
+     */
+    next(step) {
+        if (!this.active) {
+            const started = this.startOrResume();
+            if (!started)
+                return null;
+            started.steps.push(step);
+            this.active = started;
+            return { intent: started, move: 'start' };
+        }
+        const move = this.rng.weighted(this.profile.moves) ?? 'continue';
+        if (move === 'continue') {
+            this.active.steps.push(step);
+            return { intent: this.active, move: 'continue' };
+        }
+        const current = this.active;
+        if (move === 'abandon') {
+            current.status = 'abandoned';
+        }
+        else {
+            current.status = 'suspended';
+            current.suspensions++;
+        }
+        this.active = null;
+        const next = move === 'resume' ? this.resumeSuspended() : this.startOrResume(current);
+        if (!next) {
+            // Nowhere to go: keep working on what we had rather than ending a run
+            // early. An abandoned intent stays abandoned — that decision stands.
+            if (current.status === 'abandoned')
+                return null;
+            current.status = 'open';
+            current.suspensions--;
+            current.steps.push(step);
+            this.active = current;
+            return { intent: current, move: 'continue' };
+        }
+        next.status = 'open';
+        next.steps.push(step);
+        this.active = next;
+        return { intent: next, move };
+    }
+    /** Mark the active intent finished; the next tick schedules something else. */
+    complete(summary) {
+        if (!this.active)
+            return;
+        this.active.status = 'completed';
+        this.active.summary = summary;
+        this.active = null;
+    }
+    /** Mark the active intent as one the user could not get through. */
+    stuck(reason) {
+        if (!this.active)
+            return;
+        this.active.status = 'stuck';
+        this.active.summary = reason;
+        this.active = null;
+    }
+    /** Every intent the run touched, in the order it first opened them. */
+    records() {
+        return this.tracked.map((intent) => ({
+            id: intent.id,
+            sourceId: intent.source.id,
+            title: intent.source.title,
+            status: intent.status,
+            steps: [...intent.steps],
+            suspensions: intent.suspensions,
+            summary: intent.summary,
+        }));
+    }
+    /** Prefer opening something new, falling back to picking a suspended one up. */
+    startOrResume(exclude) {
+        const openCount = this.tracked.filter((intent) => intent.status === 'open' || intent.status === 'suspended').length;
+        if (this.unstarted.length > 0 && openCount < this.maxOpen) {
+            const source = this.rng.pick(this.unstarted);
+            this.unstarted.splice(this.unstarted.indexOf(source), 1);
+            const intent = {
+                id: `intent_${++this.counter}`,
+                source,
+                status: 'open',
+                steps: [],
+                suspensions: 0,
+            };
+            this.tracked.push(intent);
+            return intent;
+        }
+        return this.resumeSuspended(exclude);
+    }
+    resumeSuspended(exclude) {
+        const suspended = this.tracked.filter((intent) => intent.status === 'suspended' && intent !== exclude);
+        return this.rng.pick(suspended) ?? null;
+    }
+}
+/**
+ * The intents a persona may be given: those whose source names them, plus every
+ * source that names nobody.
+ *
+ * This is a free lookup rather than new authoring — scenario meta already
+ * records which personas each scenario runs as.
+ */
+export const intentsForPersona = (sources, personaId) => sources.filter((source) => !source.personas?.length || source.personas.includes(personaId));

package/dist/wirings/virtual-user/virtual-user-rng.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A seeded PRNG, so a run replays exactly.
+ *
+ * Reproducibility is the whole point: a virtual user that finds something has
+ * to be re-runnable into the same finding before it can be shrunk into a
+ * regression scenario. `Math.random` would make every finding a one-off story.
+ *
+ * mulberry32 — 32 bits of state, uniform enough for scheduling weights, and
+ * short enough to read.
+ */
+export declare const createRng: (seed: number) => {
+    next: () => number;
+    /** True with probability `p`. */
+    chance: (p: number) => boolean;
+    /** A uniform pick, or undefined for an empty list. */
+    pick: <T>(items: readonly T[]) => T | undefined;
+    /**
+     * A weighted pick over `[key, weight]` pairs. Zero-weight keys can never be
+     * drawn, which is how a disposition switches a move off entirely.
+     */
+    weighted: <K extends string>(weights: Readonly<Record<K, number>>) => K | undefined;
+};
+/** The seeded generator the engine threads through a whole run. */
+export type VirtualUserRng = ReturnType<typeof createRng>;

package/dist/wirings/virtual-user/virtual-user-rng.js

@@ -0,0 +1,44 @@
+/**
+ * A seeded PRNG, so a run replays exactly.
+ *
+ * Reproducibility is the whole point: a virtual user that finds something has
+ * to be re-runnable into the same finding before it can be shrunk into a
+ * regression scenario. `Math.random` would make every finding a one-off story.
+ *
+ * mulberry32 — 32 bits of state, uniform enough for scheduling weights, and
+ * short enough to read.
+ */
+export const createRng = (seed) => {
+    let state = seed >>> 0;
+    const next = () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    return {
+        next,
+        /** True with probability `p`. */
+        chance: (p) => next() < p,
+        /** A uniform pick, or undefined for an empty list. */
+        pick: (items) => items.length === 0 ? undefined : items[Math.floor(next() * items.length)],
+        /**
+         * A weighted pick over `[key, weight]` pairs. Zero-weight keys can never be
+         * drawn, which is how a disposition switches a move off entirely.
+         */
+        weighted: (weights) => {
+            const entries = Object.entries(weights).filter(([, weight]) => weight > 0);
+            const total = entries.reduce((sum, [, weight]) => sum + weight, 0);
+            if (total <= 0)
+                return undefined;
+            let roll = next() * total;
+            for (const [key, weight] of entries) {
+                roll -= weight;
+                if (roll <= 0)
+                    return key;
+            }
+            return entries[entries.length - 1]?.[0];
+        },
+    };
+};

package/dist/wirings/virtual-user/virtual-user-run-store.d.ts

@@ -0,0 +1,90 @@
+import type { VirtualUserDisposition, VirtualUserFinding, VirtualUserTally } from './virtual-user.types.js';
+/**
+ * One recorded run: who ran, what they were told, and what came back.
+ *
+ * A run is dispatched and answered for later, so the record is created before
+ * the work starts and is the thing the returned `runId` addresses.
+ *
+ * This record is a run's ONLY trace. A virtual user is not a workflow — it
+ * explores, so no two attempts take the same steps and there is nothing to
+ * replay — and it is not queued either, because the record already carries the
+ * progress a queue would only be holding on the way here.
+ *
+ * The cost of that is the one thing to know when reading `status`: a restart
+ * mid-run leaves a record at `running` with nothing left to finish it. A run
+ * older than its budget window and still `running` is dead, not working.
+ */
+export interface VirtualUserRunRecord {
+    runId: string;
+    persona: string;
+    disposition: VirtualUserDisposition;
+    /** What makes a run replayable at all — a finding without it is an anecdote. */
+    seed: number;
+    /**
+     * `running` until the engine returns. Not derived from `finishedAt` being
+     * unset: a crashed run has no finish time either, and the two are not the
+     * same result.
+     */
+    status: 'running' | 'completed' | 'failed';
+    /** The caller's situational goals, run alongside the derived intents. */
+    goals: string[];
+    /**
+     * Ids and slugs the user carried in, and whatever it learned on the way out.
+     * Kept because a finding only reproduces alongside the notes that produced it.
+     */
+    memory: Record<string, string>;
+    findings: VirtualUserFinding[];
+    tally: VirtualUserTally | null;
+    /** Which budget or stopping rule ended the run. */
+    stoppedBy: string | null;
+    /**
+     * Why the run itself failed, as opposed to what it found. A run that could
+     * not start has no findings and is not a clean empty result.
+     */
+    error: string | null;
+    /** The session that started it, where the host tracks one. */
+    startedBy: string | null;
+    createdAt: Date;
+    finishedAt: Date | null;
+}
+/** What a run is created with — everything else is filled in by the outcome. */
+export interface VirtualUserRunStart {
+    persona: string;
+    disposition: VirtualUserDisposition;
+    seed: number;
+    goals?: readonly string[];
+    memory?: Record<string, string>;
+    startedBy?: string | null;
+}
+/** The outcome of a run that reached the end of its budget without throwing. */
+export interface VirtualUserRunOutcome {
+    findings: readonly VirtualUserFinding[];
+    tally: VirtualUserTally;
+    memory: Record<string, string>;
+    stoppedBy: string | null;
+}
+/**
+ * Where runs are kept. Declared here rather than in a database package so the
+ * scaffolded RPCs depend on the shape and not on kysely — `@pikku/kysely` ships
+ * one implementation, and an app with its own store satisfies this instead.
+ *
+ * SECURITY: findings from an `adversarial` run are working exploits carrying
+ * live ids. An implementation is a privileged store; the scaffold gates every
+ * read behind a scope for that reason, and a host exposing these records more
+ * widely is publishing its own exploits.
+ */
+export interface VirtualUserRunStore {
+    /** Records a run as `running` and returns its id. */
+    start(run: VirtualUserRunStart): Promise<string>;
+    /** Marks a run `completed` and stores what it found. */
+    complete(runId: string, outcome: VirtualUserRunOutcome): Promise<void>;
+    /** Marks a run `failed`. The run itself broke; it has no findings. */
+    fail(runId: string, error: string): Promise<void>;
+    get(runId: string): Promise<VirtualUserRunRecord | null>;
+    /** Newest first. `persona` narrows to one persona's history. */
+    list(options?: {
+        persona?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<VirtualUserRunRecord[]>;
+}

package/dist/wirings/virtual-user/virtual-user-run-store.js

@@ -0,0 +1 @@
+export {};

package/dist/wirings/virtual-user/virtual-user-target.d.ts

@@ -0,0 +1,21 @@
+import type { ScenarioPersona } from '../../services/personas-service.js';
+import type { VirtualUserTarget } from './virtual-user.types.js';
+export interface PersonaTargetOptions {
+    /** Model the persona uses for its side of a conversation with an agent. */
+    model?: string;
+    /** Agents this user may talk to. Omit to leave `talkTo` unavailable. */
+    agents?: readonly string[];
+}
+/**
+ * Drive a virtual user through a signed-in persona.
+ *
+ * This is the only place the engine meets the network. A persona already signs
+ * in as a real user over the app's own auth, keeps its cookies, re-logs-in when
+ * a session expires mid-run and reports a status as data rather than throwing —
+ * everything a user imitating a user needs, and none of it worth building twice.
+ *
+ * `invokeRaw` rather than `invoke` matters: to a virtual user a 403 is not an
+ * error, it is the system saying no, which is information it should be allowed
+ * to act on.
+ */
+export declare const personaVirtualUserTarget: (persona: ScenarioPersona, { model, agents }?: PersonaTargetOptions) => VirtualUserTarget;

package/dist/wirings/virtual-user/virtual-user-target.js

@@ -0,0 +1,34 @@
+/**
+ * Drive a virtual user through a signed-in persona.
+ *
+ * This is the only place the engine meets the network. A persona already signs
+ * in as a real user over the app's own auth, keeps its cookies, re-logs-in when
+ * a session expires mid-run and reports a status as data rather than throwing —
+ * everything a user imitating a user needs, and none of it worth building twice.
+ *
+ * `invokeRaw` rather than `invoke` matters: to a virtual user a 403 is not an
+ * error, it is the system saying no, which is information it should be allowed
+ * to act on.
+ */
+export const personaVirtualUserTarget = (persona, { model, agents } = {}) => ({
+    call: (rpcName, args) => persona.invokeRaw(rpcName, args),
+    talkTo: agents?.length
+        ? async (agent, task) => {
+            if (!agents.includes(agent)) {
+                return {
+                    passed: false,
+                    reasoning: `There is no assistant called '${agent}'.`,
+                    transcript: [],
+                };
+            }
+            return persona.converse({
+                agent,
+                task,
+                // A user asking for something judges the answer by whether they got
+                // what they asked for. There is no separate criterion to hold it to.
+                evaluate: `The assistant did what was asked: ${task}`,
+                model,
+            });
+        }
+        : undefined,
+});

package/dist/wirings/virtual-user/virtual-user.types.d.ts

@@ -0,0 +1,199 @@
+import type { ScenarioHttpResponse } from '../../services/personas-service.js';
+import type { ActorFlowVerdict } from '../actor-flow/actor-flow.types.js';
+/**
+ * How a virtual user behaves, mechanically. A disposition changes the loop, the
+ * input generation, the memory and the oracle — anything that only changes how
+ * the user *talks* is persona prose (`ResolvedPersona.personality`) and does
+ * not belong here.
+ *
+ * - `realistic` — schema-first, goal-directed, plausible values (default).
+ * - `careless` — repeats, abandons, double-submits, boundary values.
+ * - `newcomer` — starts with empty memory and must discover everything.
+ * - `stale` — seeded from an earlier run's ids, some no longer valid.
+ * - `auditor` — pursues no goal; reads one truth from several places and compares.
+ * - `adversarial` — probes authorization and tenancy; a 2xx can be the finding.
+ * - `accountable` — pursues its goals for real; the only one production allows.
+ *
+ * `accountable` sits opposite `adversarial` on an *intent* axis — bad faith
+ * against good faith — where `careless` and `thorough` are a *care* axis. It is
+ * the one disposition whose actions carry consequences: no oracle, no rollback,
+ * and every call attributed to the persona in the audit log like anyone else's.
+ */
+export type VirtualUserDisposition = 'realistic' | 'careless' | 'newcomer' | 'stale' | 'auditor' | 'adversarial' | 'accountable';
+/**
+ * The one disposition a production environment accepts.
+ *
+ * Every other disposition exists to find out what the product does wrong, which
+ * is not a thing to do to real customers' data. Named here so the declaration
+ * check and the sign-in check cannot drift apart.
+ */
+export declare const PRODUCTION_DISPOSITION: VirtualUserDisposition;
+/**
+ * Hard caps the engine enforces itself. Anything the engine cannot count —
+ * money above all — belongs in {@link RunVirtualUserParams.stop} instead.
+ */
+export interface VirtualUserBudget {
+    /** Model turns, including ones that produced no call. */
+    steps?: number;
+    /** Non-read RPC calls. */
+    mutations?: number;
+    /** Wall clock, as ms or a duration string (`'30m'`). */
+    duration?: number | string;
+}
+/**
+ * The running count handed to {@link RunVirtualUserParams.stop}. Pikku collects
+ * it because only the engine sees every step; what it is *worth* is the app's,
+ * which is why no price or currency appears anywhere in core.
+ */
+export interface VirtualUserTally {
+    steps: number;
+    calls: number;
+    mutations: number;
+    tokensIn: number;
+    tokensOut: number;
+    model: string;
+    elapsedMs: number;
+    findings: number;
+}
+/**
+ * One RPC as the virtual user sees it before reading its schema: enough to
+ * choose from, not enough to call with. The whole catalogue goes in the prompt,
+ * so this stays deliberately compact — a project with 430 RPCs renders to
+ * roughly 8k tokens, which is cheaper than any retrieval step and hides nothing.
+ */
+export interface ApiCatalogueEntry {
+    name: string;
+    /** Top-level input property names, for choosing between similar endpoints. */
+    inputKeys?: readonly string[];
+    /** Top-level output property names. */
+    outputKeys?: readonly string[];
+    description?: string;
+    /**
+     * Whether the call only reads. `undefined` means nobody annotated it — which
+     * is not the same as safe, so the engine falls back to a name heuristic and
+     * reports how many entries it had to guess at.
+     */
+    readonly?: boolean;
+    /** Declared by the app as needing a human's approval — denied by default. */
+    approvalRequired?: boolean;
+    /**
+     * Scopes the session must hold to call this, all of them.
+     *
+     * Splits the catalogue in two: what a persona's roles entitle it to reach,
+     * and what they do not. Scopes rather than permission-function names because
+     * a scope is declared and checkable, whereas a permission is arbitrary code
+     * whose verdict nobody can predict without running it.
+     */
+    scopes?: readonly string[];
+    tags?: readonly string[];
+    /** JSON schema returned by `describe`, before the user may call. */
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * Where an intent comes from: a feature or scenario in the app's own words.
+ *
+ * Deliberately prose. The virtual user never receives the scenario's step graph
+ * — no rpc names, no `$ref` dataflow — because finding the API itself is the
+ * behaviour under test, and those graphs are a build-time artifact that no
+ * deployed stage carries.
+ */
+export interface IntentSource {
+    id: string;
+    title: string;
+    description?: string;
+    /** Step prose, as a person would be told it. Never rpc names. */
+    steps?: readonly string[];
+    tags?: readonly string[];
+    /** Persona ids this intent is available to. Empty means everyone. */
+    personas?: readonly string[];
+}
+/** Why the engine flagged something. */
+export type VirtualUserFindingKind = 'server-error' | 'transport-error' | 'schema-violation' | 'unexpected-success' | 'custom';
+/** Something worth a human's attention, found while imitating a user. */
+export interface VirtualUserFinding {
+    kind: VirtualUserFindingKind;
+    detail: string;
+    rpcName?: string;
+    status?: number;
+    intentId?: string;
+    /** Step index within the run, so the transcript can be replayed to here. */
+    step: number;
+}
+/**
+ * The transport the virtual user acts through. HTTP in production (an
+ * `HttpPersona`), but the engine only sees this contract — which is what
+ * lets the whole loop be tested without a network.
+ */
+export interface VirtualUserTarget {
+    /** Invoke an RPC as this user, reporting the status as data rather than throwing. */
+    call(rpcName: string, args: unknown): Promise<ScenarioHttpResponse>;
+    /** Converse with an AI agent in persona. Omitted by apps that have no agents. */
+    talkTo?(agent: string, task: string): Promise<ActorFlowVerdict>;
+    /** Send a fixture file. Omitted by apps with no upload surface. */
+    upload?(file: string): Promise<ScenarioHttpResponse>;
+}
+/** What the model chose to do this turn. */
+export type VirtualUserAction = {
+    kind: 'describe';
+    rpcName: string;
+} | {
+    kind: 'call';
+    rpcName: string;
+    args?: unknown;
+} | {
+    kind: 'talkTo';
+    agent: string;
+    task: string;
+} | {
+    kind: 'upload';
+    file: string;
+} | {
+    kind: 'complete';
+    summary?: string;
+} | {
+    kind: 'stuck';
+    reason?: string;
+};
+/** How an intent ended, or that it has not. */
+export type IntentStatus = 'open' | 'suspended' | 'completed' | 'abandoned' | 'stuck';
+/** One intent's life within a run. */
+export interface IntentRecord {
+    id: string;
+    sourceId: string;
+    title: string;
+    status: IntentStatus;
+    /** Step indices at which this intent was the active one. */
+    steps: number[];
+    /** How many times it was put down and picked back up. */
+    suspensions: number;
+    summary?: string;
+}
+/** One turn: what the engine scheduled, what the model did, what came back. */
+export interface StepRecord {
+    index: number;
+    intentId?: string;
+    action: VirtualUserAction | {
+        kind: 'invalid';
+        detail: string;
+    };
+    status?: number;
+    ok?: boolean;
+    /** Truncated response text, so a run record stays readable. */
+    response?: string;
+    findingKinds?: VirtualUserFindingKind[];
+    tokensIn: number;
+    tokensOut: number;
+}
+/** Everything a run produced. Seeded, so it replays. */
+export interface VirtualUserRunResult {
+    seed: number;
+    tally: VirtualUserTally;
+    findings: VirtualUserFinding[];
+    intents: IntentRecord[];
+    steps: StepRecord[];
+    /** Ids and slugs the user saw, for seeding a later `stale` run. */
+    memory: Record<string, string>;
+    /** Why the run ended. */
+    stoppedBy: 'no-intents' | 'budget-steps' | 'budget-mutations' | 'budget-duration' | 'stop-hook' | 'exhausted';
+}

package/dist/wirings/virtual-user/virtual-user.types.js

@@ -0,0 +1,8 @@
+/**
+ * The one disposition a production environment accepts.
+ *
+ * Every other disposition exists to find out what the product does wrong, which
+ * is not a thing to do to real customers' data. Named here so the declaration
+ * check and the sign-in check cannot drift apart.
+ */
+export const PRODUCTION_DISPOSITION = 'accountable';

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

@@ -4,8 +4,8 @@
  */
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { WorkflowRun } from '../workflow.types.js';
-import type { ScenarioActor } from '../../../services/scenario-actors-service.js';
-import type { ScenarioStepOptions, ScenarioStepPhase } from '../scenario-step.types.js';
+import type { ScenarioPersona } from '../../../services/personas-service.js';
+import type { ScenarioStepOptions, ScenarioStepPhase, ScenarioSurface } from '../scenario-step.types.js';
 /**
  * Workflow step options
  */
@@ -29,7 +29,7 @@ export interface WorkflowStepOptions {
      * internally — so auth middleware and permissions are exercised end-to-end.
      * The step is recorded durably like any RPC step.
      */
-    actor?: ScenarioActor;
+    actor?: ScenarioPersona;
 }
 /**
  * Options for workflow.expectEventually() — a durable polling step used by
@@ -62,7 +62,7 @@ export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(stepName: string,
  */
 export type WorkflowWireDoInline = <T>(stepName: string, fn: () => Promise<T> | T, options?: WorkflowStepOptions) => Promise<T>;
 /**
- * Type signature for scenario.step/given/when/then - used by inspector.
+ * Type signature for scenario.given/when/then - used by inspector.
  *
  * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
  * an imported symbol, so the extractor reads it as a literal.
@@ -181,7 +181,7 @@ export interface RpcStepMeta {
     expectEventually?: boolean;
 }
 /**
- * Scenario step metadata — a call to `scenario.step/given/when/then`.
+ * Scenario step metadata — a call to `scenario.given/when/then`.
  *
  * Distinct from RpcStepMeta on purpose: a step runs locally through
  * runPikkuFunc and must never be treated as dispatchable on the queue/replay
@@ -194,7 +194,7 @@ export interface ScenarioStepMeta {
     stepName: string;
     /** Registered name of the step function being run */
     stepFunc: string;
-    /** Which keyword the reporter prefixes — given/when/then, or none for `step` */
+    /** Which keyword the reporter prefixes — Given, When or Then */
     phase: ScenarioStepPhase;
     /** Output variable name (if assigned) */
     outputVar?: string;
@@ -204,8 +204,8 @@ export interface ScenarioStepMeta {
     options?: WorkflowStepOptions;
     /** Scenario actor name this step runs as ({ actor: actors.x }) */
     actor?: string;
-    /** Mirrors the step function's `browser: true` declaration */
-    browser?: boolean;
+    /** Mirrors the surfaces the step function declares a binding for */
+    surfaces?: ScenarioSurface[];
 }
 /**
  * Simple condition expression (leaf node)
@@ -484,18 +484,22 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     /** Stub-assertion step: asserts `service.method` was called on the target server */
     expectService: (stepName: string, serviceMethod: string, options?: WorkflowExpectServiceOptions) => Promise<void>;
     /**
-     * Run a registered scenario step. Shaped exactly like `do`'s RPC form —
-     * `(stepName, target, data, options)` — so the inspector reads the target as
-     * a string literal rather than resolving an imported symbol.
+     * Run a registered scenario step, as the setup the scenario starts from.
+     *
+     * Shaped exactly like `do`'s RPC form — `(stepName, target, data, options)` —
+     * so the inspector reads the target as a string literal rather than resolving
+     * an imported symbol.
      *
      * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
      */
-    step(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "Given" prefix in the rendered prose */
     given(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "When" prefix in the rendered prose */
+    /** `when`: the same call as `given`, rendered as the action under test */
     when(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "Then" prefix in the rendered prose */
+    /**
+     * `then`: a claim about what the action left behind. Unlike `given`/`when`
+     * this is not prose alone — the step's bindings become witnesses, so every
+     * declared surface is observed and the observations must agree.
+     */
     then(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
     runScheduledTask: (name: string) => Promise<unknown>;
 }

package/dist/wirings/workflow/dsl/workflow-runner.d.ts

@@ -1,5 +1 @@
-/**
- * Add a workflow to the system
- * This is called by the generated workflow wirings
- */
 export declare const addWorkflow: (workflowName: string, workflowFunc: any, packageName?: string | null) => void;

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

@@ -1,9 +1,5 @@
 import { pikkuState } from '../../../pikku-state.js';
 import { addFunction } from '../../../function/function-runner.js';
-/**
- * Add a workflow to the system
- * This is called by the generated workflow wirings
- */
 export const addWorkflow = (workflowName, workflowFunc, packageName = null) => {
     const meta = pikkuState(packageName, 'workflows', 'meta');
     const workflowMeta = meta[workflowName];