@pikku/core 0.12.139 → 0.12.142

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

@@ -27,10 +27,10 @@ export { SCENARIO_SURFACES } from './scenario-step.types.js';
 // Which of a step's bindings run: one for an action, every witness for a `then`
 export { resolveScenarioSurfaces } from './scenario-surface.js';
 export { pollUntil } from './scenario-poll.js';
-export { createCookieJar } from './scenario-cookie-jar.js';
+export { createCookieJar } from '../../services/scenario-cookie-jar.js';
 export { composeStepProse, renderStepTemplate } from './scenario-prose.js';
 export { requireScenarioEnv } from './scenario-step-guards.js';
-// The readers themselves live on `@pikku/core/persona`
+// The readers themselves live on `@pikku/core/virtual-user`
 /**
  * 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
@@ -68,7 +68,7 @@ addError(ScenarioHookError, {
  * 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
+ * system of record is right and the surface the virtual user 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.
  */
@@ -105,24 +105,24 @@ addError(ScenarioBrowserUnavailable, {
     message: 'No browser provider is registered.',
 });
 /**
- * A step that is driven by a persona was dispatched without one.
+ * A step that is driven by a virtual user was dispatched without one.
  *
  * Raised before the body runs rather than partway through it: the step declared
- * that it needs an actor — by having a `browser` binding, which cannot be
- * provisioned without a window to open, or by `actor: true` — so a call site
+ * that it needs a virtual user — by having a `browser` binding, which cannot be
+ * provisioned without a window to open, or by `virtualUser: true` — so a call site
  * that omits one is a mistake at the call site.
  */
-export class ScenarioActorRequired extends PikkuError {
+export class ScenarioVirtualUserRequired extends PikkuError {
     stepFunc;
     constructor(stepFunc) {
-        super(`[scenario] step '${stepFunc}' is driven by a persona but was called without an actor. ` +
-            `Pass { actor: actors.<name> } so it runs as that persona.`);
+        super(`[scenario] step '${stepFunc}' is driven by a virtual user but was called without a virtual user. ` +
+            `Pass { virtualUser: virtualUsers.<name> } so it runs as that virtual user.`);
         this.stepFunc = stepFunc;
     }
 }
-addError(ScenarioActorRequired, {
+addError(ScenarioVirtualUserRequired, {
     status: 500,
-    message: 'This step needs an actor.',
+    message: 'This step needs a virtual user.',
 });
 /**
  * A step declares no binding the run can execute.
@@ -186,7 +186,7 @@ addError(ScenarioNoWitness, {
  * An assertion ran, but not on the surface the run targets.
  *
  * The sibling of {@link ScenarioNoWitness}: that one checked nothing anywhere,
- * this one checked the system of record while the prose claims the actor saw it
+ * this one checked the system of record while the prose claims the virtual user saw it
  * on the page. Ordinary runs count it as a coverage gap; a strict run refuses
  * it, because a flow that cannot be observed end to end on the run surface is
  * not a flow that surface can be documented from.
@@ -198,7 +198,7 @@ export class ScenarioUnwitnessedAssertion extends PikkuError {
     witnessedOn;
     constructor(stepFunc, declared, runSurface, witnessedOn) {
         super(`[scenario] assertion '${stepFunc}' was checked on ${witnessedOn.join(', ')}, not on '${runSurface}'. ` +
-            `It held there — but nothing looked at '${runSurface}', which is what the step's prose claims the actor saw. ` +
+            `It held there — but nothing looked at '${runSurface}', which is what the step's prose claims the virtual user saw. ` +
             `Add a '${runSurface}' witness (declares: ${declared.join(', ') || 'nothing'}), or drop --strict.`);
         this.stepFunc = stepFunc;
         this.declared = declared;
@@ -214,7 +214,7 @@ addError(ScenarioUnwitnessedAssertion, {
  * The scenario capability, layered onto a workflow service rather than being
  * one.
  *
- * Every scenario affordance — steps, actors, lifecycle hooks, the browser
+ * Every scenario affordance — steps, virtual users, lifecycle hooks, the browser
  * provider, the assertion wire members — lives here rather than on
  * `PikkuWorkflowService`, because a bundler drops an unused *module* but never
  * an unused class member: anything declared on the workflow service ships in
@@ -236,14 +236,14 @@ addError(ScenarioUnwitnessedAssertion, {
  */
 export class PikkuScenarioService {
     engine;
-    // Scenario actors per run: live authenticated clients (cookie jars) are
+    // Scenario virtual users per run: live authenticated clients (cookie jars) are
     // process-local by nature, so they ride this map, never the persisted wire.
-    runActors = new Map();
-    // What each run has accumulated so far — process-local like the actors above,
+    runVirtualUsers = new Map();
+    // What each run has accumulated so far — process-local like the virtual users above,
     // so the body and its hooks share one object rather than reading it back off
     // the persisted wire.
     runContexts = new Map();
-    // Where each browser step landed in its actor's recording, per run. Held
+    // Where each browser step landed in its virtual user's recording, per run. Held
     // apart from the run context because the runner reads it once the run has
     // ended, which is exactly when `detachRunContext` has cleared that.
     runVideoOffsets = new Map();
@@ -255,7 +255,7 @@ export class PikkuScenarioService {
         this.engine = engine;
     }
     /**
-     * The surface every actor drives the system through for this run, set once by
+     * The surface every virtual user drives the system through for this run, set once by
      * the runner from `--run`. `default` is the server-side path — the fast suite.
      *
      * `strict` removes both routes off that surface: an action may not fall back
@@ -297,7 +297,7 @@ export class PikkuScenarioService {
         return this.scenarioEnvironment;
     }
     /**
-     * Where each of a run's browser steps fell in its actor's video, keyed by the
+     * Where each of a run's browser steps fell in its virtual user's video, keyed by the
      * durable step name, handed over and forgotten in one call.
      *
      * Taken rather than read because the runner joins these onto the step rows
@@ -309,51 +309,51 @@ export class PikkuScenarioService {
         this.runVideoOffsets.delete(runId);
         return offsets ?? new Map();
     }
-    /** Where a step starting now falls in this actor's recording, if anywhere. */
-    videoOffsetFor(actor) {
+    /** Where a step starting now falls in this virtual user's recording, if anywhere. */
+    videoOffsetFor(virtualUser) {
         const provider = this.scenarioBrowserProvider;
         if (provider?.markVideoStep) {
-            return provider.markVideoStep(actor);
+            return provider.markVideoStep(virtualUser);
         }
-        const startedAt = provider?.videoStartedAt?.(actor);
+        const startedAt = provider?.videoStartedAt?.(virtualUser);
         return startedAt === undefined
             ? undefined
             : Math.max(0, Date.now() - startedAt);
     }
     /**
-     * Stamp where a step began inside one actor's recording.
+     * Stamp where a step began inside one virtual user's recording.
      *
-     * First write per actor wins: a `then` step runs once per witness, and the
+     * First write per virtual user wins: a `then` step runs once per witness, and the
      * moment the reader wants is when the sentence started, not when its last
      * witness got around to the browser.
      */
-    recordVideoOffset(runId, stepName, actor, offsetMs) {
+    recordVideoOffset(runId, stepName, virtualUser, offsetMs) {
         let byStep = this.runVideoOffsets.get(runId);
         if (!byStep) {
             byStep = new Map();
             this.runVideoOffsets.set(runId, byStep);
         }
         const offsets = byStep.get(stepName) ?? [];
-        if (offsets.some((offset) => offset.actor === actor)) {
+        if (offsets.some((offset) => offset.virtualUser === virtualUser)) {
             return;
         }
-        offsets.push({ actor, offsetMs });
+        offsets.push({ virtualUser, offsetMs });
         byStep.set(stepName, offsets);
     }
     async attachRunContext(runId, workflowMeta, options) {
-        const actors = options?.actors ??
+        const virtualUsers = options?.virtualUsers ??
             (workflowMeta.source === 'scenario'
-                ? await this.resolvePersonas()
+                ? await this.resolveVirtualUsers()
                 : undefined);
-        if (actors) {
-            this.runActors.set(runId, actors);
+        if (virtualUsers) {
+            this.runVirtualUsers.set(runId, virtualUsers);
         }
         if (workflowMeta.source === 'scenario') {
             this.runContexts.set(runId, {});
         }
     }
     detachRunContext(runId) {
-        this.runActors.delete(runId);
+        this.runVirtualUsers.delete(runId);
         this.runContexts.delete(runId);
     }
     /**
@@ -383,7 +383,7 @@ export class PikkuScenarioService {
             context.workflowMeta?.source === 'scenario'
                 ? context.workflowWire
                 : undefined;
-        wire.actors = this.runActors.get(context.runId);
+        wire.virtualUsers = this.runVirtualUsers.get(context.runId);
     }
     async onBeforeRunFunc(context) {
         const hooks = this.scenarioHooks(context);
@@ -436,7 +436,7 @@ export class PikkuScenarioService {
      *
      * A hook is not a pikku function: it has no id, no meta and no schema, so it
      * cannot go through `runPikkuFunc` and the runner records nothing for it. It
-     * gets exactly what the scenario body gets — the same wire (so `actors` is
+     * gets exactly what the scenario body gets — the same wire (so `virtualUsers` is
      * how it reaches the app), and singleton services composed with this
      * invocation's wire services — and nothing else.
      */
@@ -467,44 +467,42 @@ export class PikkuScenarioService {
         }
     }
     /**
-     * Build HTTP scenario actors for a run started without them; undefined when
-     * SCENARIO_ACTOR_SECRET or the API URL is missing.
+     * Build HTTP scenario virtual users for a run started without them; undefined when
+     * the app has no auth service or the API URL is missing.
      *
-     * The actor client is imported lazily so that even a runner bundle only pays
-     * for the AI persona conversation loop it pulls in when a scenario actually
-     * signs an actor in.
+     * The virtual user client is imported lazily so that even a runner bundle only pays
+     * for the AI virtual user conversation loop it pulls in when a scenario actually
+     * signs a virtual user in.
      */
-    async resolvePersonas() {
+    async resolveVirtualUsers() {
         const services = getSingletonServices();
         const variables = services?.variables;
         const metaService = services?.metaService;
         if (!variables || !metaService) {
             return undefined;
         }
-        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
+        const auth = await services?.auth?.();
         const apiUrl = await variables.get('API_URL');
-        if (!secret || !apiUrl) {
-            services?.logger?.warn('A scenario was started without personas but SCENARIO_ACTOR_SECRET / API_URL is not configured — running without them.');
+        if (!auth || !apiUrl) {
+            services?.logger?.warn('A scenario was started without virtual users but the auth service / API_URL is not configured — running without them.');
             return undefined;
         }
-        const personas = await metaService.getPersonasMeta();
-        if (!personas || Object.keys(personas).length === 0) {
+        const virtualUsers = await metaService.getVirtualUsersMeta();
+        if (!virtualUsers || Object.keys(virtualUsers).length === 0) {
             return undefined;
         }
-        const signInPath = (await variables.get('SCENARIO_SIGN_IN_PATH')) ??
-            '/api/auth/sign-in/actor';
         const rpcPath = (await variables.get('SCENARIO_RPC_PATH')) ?? '/rpc';
         // A run started outside the CLI still targets an environment — its own.
         this.scenarioEnvironment ??= {
             apiUrl,
             appUrl: (await variables.get('APP_URL')) ?? undefined,
         };
-        const { createHttpPersonas } = await import('../../services/http-personas.js');
-        return createHttpPersonas({
+        const { createHttpVirtualUsers } = await import('../../services/http-virtual-users.js');
+        const { inProcessSignIn } = await import('../../services/virtual-user-sign-in.js');
+        return createHttpVirtualUsers({
             apiUrl,
-            secret,
-            personas,
-            signInPath,
+            signIn: inProcessSignIn(auth),
+            virtualUsers,
             rpcPath,
         });
     }
@@ -520,7 +518,7 @@ export class PikkuScenarioService {
         });
         Object.assign(workflowWire, {
             context: this.contextForRun(runId),
-            // Durable polling step: invoke an RPC (as an actor when options.as is
+            // Durable polling step: invoke an RPC (as a virtual user when options.as is
             // set) until the predicate passes or `within` elapses. The whole poll is
             // ONE recorded step, so replay returns the cached outcome.
             expectEventually: async (stepName, rpcName, data, predicate, options) => {
@@ -534,14 +532,14 @@ export class PikkuScenarioService {
                     const deadline = Date.now() + within;
                     let last;
                     while (true) {
-                        last = options?.actor
-                            ? await options.actor.invoke(resolvedRpcName, data)
+                        last = options?.virtualUser
+                            ? await options.virtualUser.invoke(resolvedRpcName, data)
                             : await rpcService.rpcWithWire(resolvedRpcName, data, {});
                         if (predicate(last))
                             return last;
                         if (Date.now() + interval > deadline) {
                             throw new Error(`[workflow] expectEventually '${stepName}' ('${resolvedRpcName}'` +
-                                `${options?.actor ? ` as '${options.actor.name}'` : ''}) did not pass within ${within}ms; ` +
+                                `${options?.virtualUser ? ` as '${options.virtualUser.name}'` : ''}) did not pass within ${within}ms; ` +
                                 `last result: ${JSON.stringify(last)?.slice(0, 300)}`);
                         }
                         await new Promise((resolve) => setTimeout(resolve, interval));
@@ -556,8 +554,8 @@ export class PikkuScenarioService {
                 return await this.engine.inlineStep(runId, stepName, async () => {
                     let result;
                     try {
-                        result = options?.actor
-                            ? await options.actor.invoke(resolvedRpcName, data)
+                        result = options?.virtualUser
+                            ? await options.virtualUser.invoke(resolvedRpcName, data)
                             : await rpcService.rpcWithWire(resolvedRpcName, data, {});
                     }
                     catch (e) {
@@ -583,8 +581,8 @@ export class PikkuScenarioService {
                 }
                 await this.engine.inlineStep(runId, stepName, async () => {
                     const rpcName = 'pikkuScenarioGetStubCalls';
-                    const calls = options?.actor
-                        ? await options.actor.invoke(rpcName, { service })
+                    const calls = options?.virtualUser
+                        ? await options.virtualUser.invoke(rpcName, { service })
                         : await rpcService.rpcWithWire(rpcName, { service }, {});
                     const matching = (calls ?? []).filter((c) => c.service === service &&
                         c.method === method &&
@@ -615,8 +613,8 @@ export class PikkuScenarioService {
                             ? { reference: options.reference }
                             : {}),
                     };
-                    const grade = options?.actor
-                        ? await options.actor.invoke(rpcName, data)
+                    const grade = options?.virtualUser
+                        ? await options.virtualUser.invoke(rpcName, data)
                         : await rpcService.rpcWithWire(rpcName, data, {});
                     // A scorer that graded is a scorer that answered, so an unstated
                     // bound still fails a zero rather than passing anything at all.
@@ -655,12 +653,13 @@ export class PikkuScenarioService {
         const resolvedStepFunc = addonNamespace && !stepFunc.includes(':')
             ? `${addonNamespace}:${stepFunc}`
             : stepFunc;
-        const actor = options?.actor;
+        const virtualUser = options?.virtualUser;
         const description = options?.description ??
             this.scenarioStepDescription(packageName, resolvedStepFunc) ??
             stepName;
-        if (!actor && this.requiresActor(packageName, resolvedStepFunc)) {
-            throw new ScenarioActorRequired(resolvedStepFunc);
+        if (!virtualUser &&
+            this.requiresVirtualUser(packageName, resolvedStepFunc)) {
+            throw new ScenarioVirtualUserRequired(resolvedStepFunc);
         }
         const declared = this.declaredSurfaces(packageName, resolvedStepFunc);
         const resolution = resolveScenarioSurfaces(phase, declared, this.runSurface);
@@ -671,8 +670,8 @@ export class PikkuScenarioService {
                     workflow: workflowWire,
                     scenario: workflowWire,
                     pikkuUserId: workflowWire.pikkuUserId,
-                    actors: this.runActors.get(runId),
-                    ...(actor ? { actor } : {}),
+                    virtualUsers: this.runVirtualUsers.get(runId),
+                    ...(virtualUser ? { virtualUser } : {}),
                     scenarioStep: {
                         name: resolvedStepFunc,
                         stepName,
@@ -686,12 +685,12 @@ export class PikkuScenarioService {
                     if (!this.scenarioBrowserProvider) {
                         throw new ScenarioBrowserUnavailable(resolvedStepFunc);
                     }
-                    // The dispatch guard above already refused an actor-less call, and a
+                    // The dispatch guard above already refused an anonymous call, and a
                     // browser binding always requires one.
-                    wire.browser = await this.scenarioBrowserProvider.sessionFor(actor.name);
-                    const offsetMs = this.videoOffsetFor(actor.name);
+                    wire.browser = await this.scenarioBrowserProvider.sessionFor(virtualUser.name);
+                    const offsetMs = this.videoOffsetFor(virtualUser.name);
                     if (offsetMs !== undefined) {
-                        this.recordVideoOffset(runId, stepName, actor.name, offsetMs);
+                        this.recordVideoOffset(runId, stepName, virtualUser.name, offsetMs);
                     }
                 }
                 const result = await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
@@ -765,10 +764,11 @@ export class PikkuScenarioService {
         return surfaces?.length ? surfaces : ['default'];
     }
     /**
-     * Whether a step is driven by a persona, and so must be given one. Stamped by
-     * the definer from a `browser` binding or an explicit `actor: true`.
+     * Whether a step is driven by a virtual user, and so must be given one. Stamped by
+     * the definer from a `browser` binding or an explicit `virtualUser: true`.
      */
-    requiresActor(packageName, stepFunc) {
-        return (this.scenarioStepConfig(packageName, stepFunc)?.requiresActor === true);
+    requiresVirtualUser(packageName, stepFunc) {
+        return (this.scenarioStepConfig(packageName, stepFunc)?.requiresVirtualUser ===
+            true);
     }
 }

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -3,7 +3,7 @@ import type { SerializedError } from '../../errors/serialized-error.js';
 import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.js';
 import type { PikkuWorkflowWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
-import type { ScenarioPersonas } from '../../services/personas-service.js';
+import type { ScenarioVirtualUsers } from '../../services/virtual-users-service.js';
 import type { PikkuRPC } from '../rpc/rpc-types.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
 import type { WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
@@ -194,7 +194,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: PikkuRPC, options?: {
         inline?: boolean;
         startNode?: string;
-        actors?: ScenarioPersonas;
+        virtualUsers?: ScenarioVirtualUsers;
         onRunCreated?: (runId: string) => void;
     }): Promise<{
         runId: string;

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

@@ -818,7 +818,7 @@ export class PikkuWorkflowService {
         const resolvedStepOptions = {
             retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
             retryDelay: stepOptions?.retryDelay,
-            actor: stepOptions?.actor,
+            virtualUser: stepOptions?.virtualUser,
         };
         const stepState = await this.loadOrCreateStep(runId, stepName, async () => {
             if (stepOptions?.compensate === false) {
@@ -844,7 +844,7 @@ export class PikkuWorkflowService {
         if (lease === 'held') {
             throw new WorkflowAsyncException(runId, stepName);
         }
-        const dispatched = resolvedStepOptions.actor
+        const dispatched = resolvedStepOptions.virtualUser
             ? false
             : await this.dispatchStep(runId, stepName, rpcName, data, resolvedStepOptions, fromStepName);
         if (dispatched) {
@@ -856,8 +856,8 @@ export class PikkuWorkflowService {
         const retries = resolvedStepOptions.retries ?? this.getConfig().retries;
         const retryDelay = resolvedStepOptions.retryDelay;
         return runInlineRetryLoop(this, stepState, retries, retryDelay, async (currentStepState) => {
-            if (resolvedStepOptions.actor) {
-                return resolvedStepOptions.actor.invoke(rpcName, data);
+            if (resolvedStepOptions.virtualUser) {
+                return resolvedStepOptions.virtualUser.invoke(rpcName, data);
             }
             if (pikkuState(null, 'workflows', 'meta')[rpcName]) {
                 return runInlineChildStep({

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

@@ -1,25 +1,25 @@
 import type { ScenarioStepPhase } from './scenario-step.types.js';
 export declare const renderStepTemplate: (template: string, input: unknown) => string;
-export declare const composeStepProse: ({ phase, description, template, input, actor, actorRole, continuesPhase, continuesActor, keywordWidth, }: {
+export declare const composeStepProse: ({ phase, description, template, input, virtualUser, virtualUserRole, continuesPhase, continuesVirtualUser, keywordWidth, }: {
     phase: ScenarioStepPhase;
     description: string;
     template?: string;
     input?: unknown;
-    actor?: string;
+    virtualUser?: string;
     /**
-     * What this actor is, rendered as an apposition after their key — "yasser
-     * (the founder)". Only pass it where the actor has not been named yet: an
-     * ordinary run repeats one actor for a dozen steps, and repeating the role
+     * What this virtual user is, rendered as an apposition after their key — "yasser
+     * (the founder)". Only pass it where the virtual user has not been named yet: an
+     * ordinary run repeats one virtual user for a dozen steps, and repeating the role
      * with them turns the one piece of context into the noise around it.
      */
-    actorRole?: string;
+    virtualUserRole?: string;
     /**
      * This step repeats the phase of the one before it, so it reads as `And`
      * rather than saying `Given` three times — the same thing Gherkin does.
      */
     continuesPhase?: boolean;
     /**
-     * The step before this one had the same actor. Combined with `continuesPhase`
+     * The step before this one had the same virtual user. Combined with `continuesPhase`
      * the subject is dropped, because English drops a repeated subject in a
      * compound predicate: "yasser opens the dashboard / and sees the audit log".
      *
@@ -27,6 +27,6 @@ export declare const composeStepProse: ({ phase, description, template, input, a
      * the dashboard", and a pronoun instead of a name would give "they sees",
      * since step templates are authored in the third person singular.
      */
-    continuesActor?: boolean;
+    continuesVirtualUser?: boolean;
     keywordWidth?: number;
 }) => string;

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

@@ -14,13 +14,15 @@ const formatValue = (value) => {
     }
     return String(value);
 };
-export const composeStepProse = ({ phase, description, template, input, actor, actorRole, continuesPhase, continuesActor, keywordWidth, }) => {
+export const composeStepProse = ({ phase, description, template, input, virtualUser, virtualUserRole, continuesPhase, continuesVirtualUser, keywordWidth, }) => {
     const keyword = capitalise(continuesPhase ? 'and' : phase);
-    // The actor key is the subject verbatim, with no article in front of it.
-    // "the ${actor}" only reads as English when the key happens to be a role
-    // noun — it turns a persona named after a person into "the nadia", which
+    // The virtual user key is the subject verbatim, with no article in front of it.
+    // "the ${virtual user}" only reads as English when the key happens to be a role
+    // noun — it turns a virtual user named after a person into "the nadia", which
     // is the reporter quietly imposing a naming convention on the author.
-    const subject = continuesPhase && continuesActor ? '' : composeSubject(actor, actorRole);
+    const subject = continuesPhase && continuesVirtualUser
+        ? ''
+        : composeSubject(virtualUser, virtualUserRole);
     const rendered = template ? renderStepTemplate(template, input) : description;
     const sentence = [subject, rendered].filter(Boolean).join(' ');
     if (keywordWidth === undefined) {
@@ -28,9 +30,11 @@ export const composeStepProse = ({ phase, description, template, input, actor, a
     }
     return `${keyword.padEnd(keywordWidth)} ${sentence}`;
 };
-const composeSubject = (actor, actorRole) => {
-    if (!actor)
+const composeSubject = (virtualUser, virtualUserRole) => {
+    if (!virtualUser)
         return '';
-    return actorRole ? `${actor} (the ${actorRole})` : actor;
+    return virtualUserRole
+        ? `${virtualUser} (the ${virtualUserRole})`
+        : virtualUser;
 };
 const capitalise = (value) => value.charAt(0).toUpperCase() + value.slice(1);

package/dist/wirings/workflow/scenario-run.types.d.ts

@@ -27,8 +27,8 @@ export interface ScenarioArtifact {
     scenario: string;
     kind: ScenarioArtifactKind;
     path: string;
-    /** Whose window it was — a two-actor scenario produces two of everything. */
-    actor?: string;
+    /** Whose window it was — a two-virtual-user scenario produces two of everything. */
+    virtualUser?: string;
     /** The caption the scenario author took a screenshot under. */
     name?: string;
     /**
@@ -42,9 +42,9 @@ export interface ScenarioArtifact {
     showcase?: boolean;
 }
 /**
- * Where a step falls inside one actor's recording.
+ * Where a step falls inside one virtual user's recording.
  *
- * Measured from the moment that actor's browser context opened — which is when
+ * Measured from the moment that virtual user's browser context opened — which is when
  * Playwright starts the file — rather than from the start of the scenario, so
  * it addresses the video's own clock. The two differ by however long the
  * scenario spent before that window existed, plus every non-browser step since,
@@ -52,17 +52,17 @@ export interface ScenarioArtifact {
  * being summed back out of the ladder afterwards.
  */
 export interface ScenarioStepVideoOffset {
-    /** Whose recording this offset is into: one actor, one video file. */
-    actor: string;
+    /** Whose recording this offset is into: one virtual user, one video file. */
+    virtualUser: string;
     offsetMs: number;
 }
 /** One step of a run, already joined to the prose that declared it. */
 export interface ScenarioStepRow {
     sentence: string;
     /**
-     * The same sentence with the actor's role in it — "yasser (the founder)
-     * signs in". Set only on the step that first names each actor, and only
-     * when a persona declares a job title or a role, so a reader who wants the
+     * The same sentence with the virtual user's role in it — "yasser (the founder)
+     * signs in". Set only on the step that first names each virtual user, and only
+     * when a virtual user declares a job title or a role, so a reader who wants the
      * context picks this and one who wants the bare run picks `sentence`.
      */
     sentenceWithRole?: string;
@@ -70,11 +70,11 @@ export interface ScenarioStepRow {
     durationMs?: number;
     error?: string;
     /**
-     * Where this step lands in each actor's video, for the actors whose window
-     * was being recorded when it ran. Absent for a step with no actor, a run
+     * Where this step lands in each virtual user's video, for the virtual users whose window
+     * was being recorded when it ran. Absent for a step with no virtual user, a run
      * without video, and a step that never ran at all.
      *
-     * A list rather than one number because a video belongs to an actor, not to
+     * A list rather than one number because a video belongs to a virtual user, not to
      * the scenario: a step touching two windows falls at a different moment in
      * each, and an offset that does not name its file cannot be seeked to.
      */
@@ -126,7 +126,7 @@ export interface ScenarioResult {
     title?: string;
     description?: string;
     /** Who the scenario cast, in declaration order. */
-    actors?: string[];
+    virtualUsers?: string[];
     tags?: string[];
     /** Images and footage this scenario produced, filed under the run. */
     artifacts?: ScenarioArtifact[];