@pikku/core 0.12.139 → 0.12.142

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

@@ -1,9 +1,9 @@
-import type { ScenarioHttpResponse } from '../../services/personas-service.js';
-import type { ActorFlowVerdict } from '../actor-flow/actor-flow.types.js';
+import type { ScenarioHttpResponse } from '../../services/virtual-users-service.js';
+import type { ConversationVerdict } from './conversation/conversation.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
+ * the user *talks* is virtual user prose (`ResolvedVirtualUser.personality`) and does
  * not belong here.
  *
  * - `realistic` — schema-first, goal-directed, plausible values (default).
@@ -17,11 +17,11 @@ import type { ActorFlowVerdict } from '../actor-flow/actor-flow.types.js';
  * `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.
+ * and every call attributed to the virtual user 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.
+ * The one disposition a declaration may name for a production environment. Virtual users never run against production, so this only keeps the declaration check honest.
  *
  * 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
@@ -79,7 +79,7 @@ export interface ApiCatalogueEntry {
     /**
      * 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,
+     * Splits the catalogue in two: what a virtual user'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.
@@ -105,8 +105,8 @@ export interface IntentSource {
     /** 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[];
+    /** Virtual user ids this intent is available to. Empty means everyone. */
+    virtualUsers?: readonly string[];
 }
 /** Why the engine flagged something. */
 export type VirtualUserFindingKind = 'server-error' | 'transport-error' | 'schema-violation' | 'unexpected-success' | 'custom';
@@ -122,14 +122,14 @@ export interface VirtualUserFinding {
 }
 /**
  * The transport the virtual user acts through. HTTP in production (an
- * `HttpPersona`), but the engine only sees this contract — which is what
+ * `HttpVirtualUser`), 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>;
+    /** Converse with an AI agent in virtual user. Omitted by apps that have no agents. */
+    talkTo?(agent: string, task: string): Promise<ConversationVerdict>;
     /** Send a fixture file. Omitted by apps with no upload surface. */
     upload?(file: string): Promise<ScenarioHttpResponse>;
 }

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

@@ -1,5 +1,5 @@
 /**
- * The one disposition a production environment accepts.
+ * The one disposition a declaration may name for a production environment. Virtual users never run against production, so this only keeps the declaration check honest.
  *
  * 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

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

@@ -5,7 +5,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { SerializedError } from '../../../errors/serialized-error.js';
 import type { WorkflowRun } from '../workflow.types.js';
-import type { ScenarioPersona } from '../../../services/personas-service.js';
+import type { ScenarioVirtualUser } from '../../../services/virtual-users-service.js';
 import type { ScenarioStepOptions, ScenarioStepPhase, ScenarioSurface } from '../scenario-step.types.js';
 /**
  * Workflow step options
@@ -24,12 +24,12 @@ export interface WorkflowStepOptions {
      */
     compensate?: false;
     /**
-     * Run this step as an actor (scenarios). The RPC is sent through the
-     * actor's authenticated client over the REAL transport — never dispatched
+     * Run this step as a virtual user (scenarios). The RPC is sent through the
+     * virtual user's authenticated client over the REAL transport — never dispatched
      * internally — so auth middleware and permissions are exercised end-to-end.
      * The step is recorded durably like any RPC step.
      */
-    actor?: ScenarioPersona;
+    virtualUser?: ScenarioVirtualUser;
 }
 /**
  * Options for workflow.expectEventually() — a durable polling step used by
@@ -240,8 +240,8 @@ export interface RpcStepMeta {
     inputs?: Record<string, InputSource> | 'passthrough';
     /** Step options */
     options?: WorkflowStepOptions;
-    /** Scenario actor name this step runs as ({ actor: actors.x }) */
-    actor?: string;
+    /** Scenario virtual user name this step runs as ({ virtualUser: virtualUsers.x }) */
+    virtualUser?: string;
     /** True for workflow.expectEventually polling steps */
     expectEventually?: boolean;
 }
@@ -267,8 +267,8 @@ export interface ScenarioStepMeta {
     inputs?: Record<string, InputSource> | 'passthrough';
     /** Step options */
     options?: WorkflowStepOptions;
-    /** Scenario actor name this step runs as ({ actor: actors.x }) */
-    actor?: string;
+    /** Scenario virtual user name this step runs as ({ virtualUser: virtualUsers.x }) */
+    virtualUser?: string;
     /** Mirrors the surfaces the step function declares a binding for */
     surfaces?: ScenarioSurface[];
 }
@@ -595,7 +595,7 @@ export interface PikkuScenarioWire<Out = unknown> extends PikkuWorkflowWire {
      */
     context: ScenarioContext<Out>;
     /**
-     * Durable polling step: invoke `rpcName` (as an actor when `options.actor`
+     * Durable polling step: invoke `rpcName` (as a virtual user when `options.virtualUser`
      * is set) until `predicate` passes or `options.within` elapses.
      */
     expectEventually: <TOutput = any, TInput = any>(stepName: string, rpcName: string, data: TInput, predicate: (output: TOutput) => boolean, options?: WorkflowExpectEventuallyOptions) => Promise<TOutput>;

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

@@ -2,7 +2,7 @@ import { PikkuError } from '../../errors/error-handler.js';
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
 import type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
-import type { ScenarioPersonas } from '../../services/personas-service.js';
+import type { ScenarioVirtualUsers } from '../../services/virtual-users-service.js';
 import type { ScenarioStepVideoOffset } from './scenario-run.types.js';
 import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } from './scenario-step.types.js';
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
@@ -12,11 +12,11 @@ export type { ScenarioArtifact, ScenarioFailureDetail, ScenarioResult, ScenarioR
 export { SCENARIO_SURFACES } from './scenario-step.types.js';
 export { resolveScenarioSurfaces } from './scenario-surface.js';
 export { pollUntil, type PollOptions } from './scenario-poll.js';
-export { createCookieJar } from './scenario-cookie-jar.js';
-export type { ScenarioCookieJar } from './scenario-cookie-jar.js';
+export { createCookieJar } from '../../services/scenario-cookie-jar.js';
+export type { ScenarioCookieJar } from '../../services/scenario-cookie-jar.js';
 export { composeStepProse, renderStepTemplate } from './scenario-prose.js';
 export { requireScenarioEnv } from './scenario-step-guards.js';
-export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/personas-service.js';
+export type { ScenarioHttpResponse, ScenarioJsonRequest, } from '../../services/virtual-users-service.js';
 /**
  * A workflow service with the scenario capability attached — the two lines
  * `pikku scenario run` needs, in one call so no caller has to remember that the
@@ -44,7 +44,7 @@ export declare class ScenarioHookError extends PikkuError {
  * 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.
  */
@@ -74,14 +74,14 @@ export declare class ScenarioBrowserUnavailable extends PikkuError {
     constructor(stepFunc: string);
 }
 /**
- * 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 declare class ScenarioActorRequired extends PikkuError {
+export declare class ScenarioVirtualUserRequired extends PikkuError {
     readonly stepFunc: string;
     constructor(stepFunc: string);
 }
@@ -122,7 +122,7 @@ export declare class ScenarioNoWitness extends PikkuError {
  * 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.
@@ -138,7 +138,7 @@ export declare class ScenarioUnwitnessedAssertion extends PikkuError {
  * 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
@@ -160,7 +160,7 @@ export declare class ScenarioUnwitnessedAssertion extends PikkuError {
  */
 export declare class PikkuScenarioService implements WorkflowRunExtension {
     private readonly engine;
-    private runActors;
+    private runVirtualUsers;
     private runContexts;
     private runVideoOffsets;
     private scenarioBrowserProvider?;
@@ -169,7 +169,7 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     private strictSurface;
     constructor(engine: WorkflowRunEngine);
     /**
-     * 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
@@ -196,7 +196,7 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     setScenarioEnvironment(env: ScenarioEnvironment | undefined): void;
     getScenarioEnvironment(): ScenarioEnvironment | undefined;
     /**
-     * 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
@@ -204,18 +204,18 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
      * clear them, and the only moment they are still wanted.
      */
     takeStepVideoOffsets(runId: string): Map<string, ScenarioStepVideoOffset[]>;
-    /** Where a step starting now falls in this actor's recording, if anywhere. */
+    /** Where a step starting now falls in this virtual user's recording, if anywhere. */
     private videoOffsetFor;
     /**
-     * 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.
      */
     private recordVideoOffset;
     attachRunContext(runId: string, workflowMeta: any, options?: {
-        actors?: ScenarioPersonas;
+        virtualUsers?: ScenarioVirtualUsers;
     }): Promise<void>;
     detachRunContext(runId: string): void;
     /**
@@ -249,20 +249,20 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
      *
      * 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.
      */
     private runScenarioHook;
     /**
-     * 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.
      */
-    resolvePersonas(): Promise<ScenarioPersonas | undefined>;
+    resolveVirtualUsers(): Promise<ScenarioVirtualUsers | undefined>;
     decorateWorkflowWire(wire: PikkuWorkflowWire, context: {
         name: string;
         runId: string;
@@ -278,8 +278,8 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
      */
     private declaredSurfaces;
     /**
-     * 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`.
      */
-    private requiresActor;
+    private requiresVirtualUser;
 }