@pikku/core 0.12.139 → 0.12.142

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

@@ -1,7 +1,7 @@
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, } from './virtual-user-catalogue.js';
 import { dispositionProfile, } from './virtual-user-dispositions.js';
-import { IntentStack, intentsForPersona } from './virtual-user-intents.js';
+import { IntentStack, intentsForVirtualUser } from './virtual-user-intents.js';
 import { createRng } from './virtual-user-rng.js';
 /** One turn: what the user decided to do next, and why. */
 const ACTION_SCHEMA = {
@@ -108,11 +108,11 @@ export const rememberIds = (body, into, depth = 0) => {
     }
     return into;
 };
-const personaInstructions = (persona, profile, catalogue, agents, fixtures) => [
+const virtualUserInstructions = (virtualUser, profile, catalogue, agents, fixtures) => [
     `You are a real person using a product through its API. Stay in character; you are the user, not the system.`,
-    `Your name is ${persona.name}.`,
-    persona.jobTitle ? `Your role: ${persona.jobTitle}.` : '',
-    persona.personality ? `Your manner: ${persona.personality}.` : '',
+    `Your name is ${virtualUser.name}.`,
+    virtualUser.jobTitle ? `Your role: ${virtualUser.jobTitle}.` : '',
+    virtualUser.personality ? `Your manner: ${virtualUser.personality}.` : '',
     '',
     profile.instructions,
     '',
@@ -146,7 +146,7 @@ const personaInstructions = (persona, profile, catalogue, agents, fixtures) => [
  * work inside it stays genuinely open-ended.
  */
 export const runVirtualUser = async (params) => {
-    const { persona, personaId, disposition = 'realistic', tuning, target, llm, model, budget, stop, validateOutput, classify, fixtures = [], agents = [], scopes, allowApprovalRequired = false, maxStepsPerIntent = DEFAULT_MAX_STEPS_PER_INTENT, } = params;
+    const { virtualUser, virtualUserId, disposition = 'realistic', tuning, target, llm, model, budget, stop, validateOutput, classify, fixtures = [], agents = [], scopes, allowApprovalRequired = false, maxStepsPerIntent = DEFAULT_MAX_STEPS_PER_INTENT, } = params;
     const profile = dispositionProfile(disposition, tuning);
     const seed = params.seed ?? Math.floor(Math.random() * 2 ** 31);
     const rng = createRng(seed);
@@ -161,7 +161,7 @@ export const runVirtualUser = async (params) => {
     });
     const index = catalogueIndex(reachable);
     const sources = [
-        ...intentsForPersona(params.intents, personaId),
+        ...intentsForVirtualUser(params.intents, virtualUserId),
         ...(params.goals ?? []).map((goal, i) => ({
             id: `goal_${i + 1}`,
             title: goal,
@@ -191,7 +191,7 @@ export const runVirtualUser = async (params) => {
         : typeof budget.duration === 'number'
             ? budget.duration
             : getDurationInMilliseconds(budget.duration);
-    const instructions = personaInstructions(persona, profile, renderCatalogue(reachable), agents, fixtures);
+    const instructions = virtualUserInstructions(virtualUser, profile, renderCatalogue(reachable), agents, fixtures);
     const addFinding = (finding) => {
         findings.push(finding);
         tally.findings++;
@@ -423,7 +423,7 @@ export const runVirtualUser = async (params) => {
                     });
                 }
             }
-            // This persona does not hold the scopes this endpoint declares, and the
+            // This virtual user does not hold the scopes this endpoint declares, and the
             // server served it anyway — the declaration and the enforcement disagree.
             if (response.ok &&
                 scopes &&
@@ -431,7 +431,7 @@ export const runVirtualUser = async (params) => {
                 kinds.push('unexpected-success');
                 addFinding({
                     kind: 'unexpected-success',
-                    detail: `${entry.name} succeeded for '${personaId}', who does not hold ${entry.scopes
+                    detail: `${entry.name} succeeded for '${virtualUserId}', who does not hold ${entry.scopes
                         .filter((scope) => !scopes.includes(scope))
                         .join(', ')}`,
                     rpcName: entry.name,

package/dist/wirings/{persona/validate-personas.d.ts → virtual-user/validate-virtual-users.d.ts}

@@ -1,9 +1,9 @@
-import type { PersonaDefinitions, PersonaMeta, PersonasMeta } from './persona.types.js';
+import type { VirtualUserDefinitions, VirtualUserMeta, VirtualUsersMeta } from './virtual-user-declaration.types.js';
 /**
- * Whether a persona can actually be driven by a virtual user.
+ * Whether a virtual user can actually be run.
  *
  * A provider login cannot: driving Google's or GitHub's consent screen needs a
- * human, so the persona is seedable and assertable but not runnable. Derived
+ * human, so the virtual user is seedable and assertable but not runnable. Derived
  * rather than asked for, because it is a consequence of the account rather than
  * a separate decision — and a flag someone must remember to set is a flag that
  * ships wrong.
@@ -11,22 +11,22 @@ import type { PersonaDefinitions, PersonaMeta, PersonasMeta } from './persona.ty
  * An explicit `runnable: false` still wins: it marks the person who is only
  * ever acted *upon*, which no account shape reveals.
  */
-export declare const isRunnablePersona: (persona: {
+export declare const isRunnableVirtualUser: (virtualUser: {
     runnable?: boolean;
     account?: {
         provider?: string;
     };
 }) => boolean;
 /**
- * Validates declared personas and keys them by id.
+ * Validates declared virtual users and keys them by id.
  *
  * Definitions sharing an id must be identical; a conflicting redeclaration is a
  * hard error naming both source files, on the same terms as scopes and roles.
  */
-export declare function validateAndBuildPersonasMeta(definitions: PersonaDefinitions): PersonasMeta;
+export declare function validateAndBuildVirtualUsersMeta(definitions: VirtualUserDefinitions): VirtualUsersMeta;
 /** What a run compares against the store before its first step. */
 export interface RoleVerification {
-    persona: string;
+    virtualUserId: string;
     expected: string[];
     actual: string[];
     missing: string[];
@@ -34,20 +34,20 @@ export interface RoleVerification {
     ok: boolean;
 }
 /**
- * Compares a persona's declared roles against what the stage actually granted.
+ * Compares a virtual user's declared roles against what the stage actually granted.
  *
  * Run at sign-in, before the first step. The declaration is authoritative —
  * the generated seed applies it — but pikku cannot guarantee the seed ran on a
  * stage it did not deploy, and virtual users are meant to run against staging
  * and production, so that case is the normal one.
  *
- * Both directions matter, for opposite reasons. An under-granted persona
+ * Both directions matter, for opposite reasons. An under-granted virtual user
  * reports authorization bugs that are really seed drift. An over-granted one
  * silently stops testing the boundary it was written to test — nothing fails,
  * the findings just quietly stop being about anything.
  */
-export declare const verifyPersonaRoles: (persona: string, expected: readonly string[], actual: readonly string[]) => RoleVerification;
+export declare const verifyVirtualUserRoles: (virtualUserId: string, expected: readonly string[], actual: readonly string[]) => RoleVerification;
 /** The message a run stops with, or `null` when the roles line up. */
 export declare const roleMismatchMessage: (verification: RoleVerification) => string | null;
 /** Convenience: the meta a run needs, with `runnable` already resolved. */
-export declare const runnablePersonas: (meta: PersonasMeta) => PersonaMeta[];
+export declare const runnableVirtualUsers: (meta: VirtualUsersMeta) => VirtualUserMeta[];

package/dist/wirings/{persona/validate-personas.js → virtual-user/validate-virtual-users.js}

@@ -1,8 +1,8 @@
 /**
- * Whether a persona can actually be driven by a virtual user.
+ * Whether a virtual user can actually be run.
  *
  * A provider login cannot: driving Google's or GitHub's consent screen needs a
- * human, so the persona is seedable and assertable but not runnable. Derived
+ * human, so the virtual user is seedable and assertable but not runnable. Derived
  * rather than asked for, because it is a consequence of the account rather than
  * a separate decision — and a flag someone must remember to set is a flag that
  * ships wrong.
@@ -10,62 +10,62 @@
  * An explicit `runnable: false` still wins: it marks the person who is only
  * ever acted *upon*, which no account shape reveals.
  */
-export const isRunnablePersona = (persona) => {
-    if (persona.runnable === false) {
+export const isRunnableVirtualUser = (virtualUser) => {
+    if (virtualUser.runnable === false) {
         return false;
     }
-    return persona.account?.provider === undefined;
+    return virtualUser.account?.provider === undefined;
 };
 /**
- * Validates declared personas and keys them by id.
+ * Validates declared virtual users and keys them by id.
  *
  * Definitions sharing an id must be identical; a conflicting redeclaration is a
  * hard error naming both source files, on the same terms as scopes and roles.
  */
-export function validateAndBuildPersonasMeta(definitions) {
+export function validateAndBuildVirtualUsersMeta(definitions) {
     const meta = {};
-    for (const persona of definitions) {
-        if (!persona.id) {
-            throw new Error('A persona is declared with an empty id.');
+    for (const virtualUser of definitions) {
+        if (!virtualUser.id) {
+            throw new Error('A virtual user is declared with an empty id.');
         }
-        if (!persona.name) {
-            throw new Error(`Persona '${persona.id}' has no name. A persona is a person; give them one.`);
+        if (!virtualUser.name) {
+            throw new Error(`VirtualUser '${virtualUser.id}' has no name. A virtual user is a person; give them one.`);
         }
-        const existing = meta[persona.id];
+        const existing = meta[virtualUser.id];
         if (existing) {
             const same = JSON.stringify({ ...existing, sourceFile: undefined }) ===
-                JSON.stringify({ ...persona, sourceFile: undefined });
+                JSON.stringify({ ...virtualUser, sourceFile: undefined });
             if (!same) {
-                throw new Error(`Persona '${persona.id}' is declared twice with different content.\n` +
+                throw new Error(`VirtualUser '${virtualUser.id}' is declared twice with different content.\n` +
                     `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
-                    `  Second declaration: ${persona.sourceFile ?? 'unknown'}`);
+                    `  Second declaration: ${virtualUser.sourceFile ?? 'unknown'}`);
             }
             continue;
         }
-        meta[persona.id] = persona;
+        meta[virtualUser.id] = virtualUser;
     }
     return meta;
 }
 /**
- * Compares a persona's declared roles against what the stage actually granted.
+ * Compares a virtual user's declared roles against what the stage actually granted.
  *
  * Run at sign-in, before the first step. The declaration is authoritative —
  * the generated seed applies it — but pikku cannot guarantee the seed ran on a
  * stage it did not deploy, and virtual users are meant to run against staging
  * and production, so that case is the normal one.
  *
- * Both directions matter, for opposite reasons. An under-granted persona
+ * Both directions matter, for opposite reasons. An under-granted virtual user
  * reports authorization bugs that are really seed drift. An over-granted one
  * silently stops testing the boundary it was written to test — nothing fails,
  * the findings just quietly stop being about anything.
  */
-export const verifyPersonaRoles = (persona, expected, actual) => {
+export const verifyVirtualUserRoles = (virtualUserId, expected, actual) => {
     const expectedSet = new Set(expected);
     const actualSet = new Set(actual);
     const missing = [...expectedSet].filter((r) => !actualSet.has(r)).sort();
     const extra = [...actualSet].filter((r) => !expectedSet.has(r)).sort();
     return {
-        persona,
+        virtualUserId,
         expected: [...expectedSet].sort(),
         actual: [...actualSet].sort(),
         missing,
@@ -85,10 +85,10 @@ export const roleMismatchMessage = (verification) => {
     if (verification.extra.length) {
         parts.push(`unexpectedly holds ${verification.extra.join(', ')}`);
     }
-    return (`Persona '${verification.persona}' ${parts.join(' and ')}. ` +
+    return (`VirtualUser '${verification.virtualUserId}' ${parts.join(' and ')}. ` +
         `Declared: ${verification.expected.join(', ') || 'none'}. ` +
         `On the stage: ${verification.actual.join(', ') || 'none'}. ` +
-        `Refusing to run — findings from a persona whose roles have drifted are about the seed, not the product.`);
+        `Refusing to run — findings from a virtual user whose roles have drifted are about the seed, not the product.`);
 };
 /** Convenience: the meta a run needs, with `runnable` already resolved. */
-export const runnablePersonas = (meta) => Object.values(meta).filter((persona) => persona.runnable);
+export const runnableVirtualUsers = (meta) => Object.values(meta).filter((virtualUser) => virtualUser.runnable);

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

@@ -1,14 +1,14 @@
 /**
- * Which of the product's agents a persona can actually talk to.
+ * Which of the product's agents a virtual user can actually talk to.
  *
- * An agent is not something a persona declares. It is something a persona
+ * An agent is not something a virtual user declares. It is something a virtual user
  * *reaches*, under exactly the rule an RPC is reached by: `CoreAgent.scopes`
- * is checked against the session, so a persona holding the scopes an agent
+ * is checked against the session, so a virtual user holding the scopes an agent
  * requires finds it in front of them, and one that does not, does not.
  *
- * That is the whole reason a persona has no `agent:` field. Naming one would
+ * That is the whole reason a virtual user has no `agent:` field. Naming one would
  * add no capability the roles do not already confer, and would narrow the
- * persona to a single brain when the interesting behaviour is the choice
+ * virtual user to a single brain when the interesting behaviour is the choice
  * between calling the API directly and handing the work to a specialist.
  */
 /** The part of an agent's meta this needs. */
@@ -28,12 +28,12 @@ export interface ReachableAgent {
  * That key is the export's own name, which is what `addAgent` stores and what
  * `resolveAgent` looks up. The `name` an agent declares in its config is a
  * display label and is frequently something else entirely — offering that one
- * hands the persona a name the server cannot resolve, and the run dies on a
+ * hands the virtual user a name the server cannot resolve, and the run dies on a
  * 500 the moment it takes the offer.
  *
  * Like {@link reachableCatalogue}, this narrows *what is offered* and never
  * what is enforced: the server decides who may talk to what, and an agent
- * answering a persona this filter would have withheld is a finding rather than
+ * answering a virtual user this filter would have withheld is a finding rather than
  * a bug here.
  *
  * An agent declaring no scopes is offered to everybody, on the same terms as a

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

@@ -5,12 +5,12 @@ import { hasScopes } from '../../scopes.js';
  * That key is the export's own name, which is what `addAgent` stores and what
  * `resolveAgent` looks up. The `name` an agent declares in its config is a
  * display label and is frequently something else entirely — offering that one
- * hands the persona a name the server cannot resolve, and the run dies on a
+ * hands the virtual user a name the server cannot resolve, and the run dies on a
  * 500 the moment it takes the offer.
  *
  * Like {@link reachableCatalogue}, this narrows *what is offered* and never
  * what is enforced: the server decides who may talk to what, and an agent
- * answering a persona this filter would have withheld is a finding rather than
+ * answering a virtual user this filter would have withheld is a finding rather than
  * a bug here.
  *
  * An agent declaring no scopes is offered to everybody, on the same terms as a

package/dist/wirings/{persona/persona-app-scopes.d.ts → virtual-user/virtual-user-app-scopes.d.ts}

@@ -1,5 +1,5 @@
 import type { ScopeDefinitionMeta } from '../scope/scope.types.js';
-import type { PersonaMeta } from './persona.types.js';
+import type { VirtualUserMeta } from './virtual-user-declaration.types.js';
 /**
  * The root every app grant hangs off. One segment, so a grant of `app` alone
  * means "may use all of them" under the same parent-grant rule the admin tree
@@ -10,16 +10,16 @@ export declare const APP_SCOPE_ROOT = "app";
 /** `app:staff` for `staff`. */
 export declare const appScopeId: (app: string) => string;
 /**
- * The apps named across the declared personas, sorted and deduplicated.
+ * The apps named across the declared virtual users, sorted and deduplicated.
  *
- * The personas *are* the registry. There is no separate list of apps to keep in
+ * The virtual users *are* the registry. There is no separate list of apps to keep in
  * step, because a frontend nobody signs into is not a thing the auth layer has
  * an opinion about — and the moment somebody does sign into it, they are a
- * persona and they name it.
+ * virtual user and they name it.
  */
-export declare const declaredApps: (personas: PersonaMeta[]) => string[];
+export declare const declaredApps: (virtualUsers: VirtualUserMeta[]) => string[];
 /**
- * The `app` scope tree, synthesised from the personas that name an app.
+ * The `app` scope tree, synthesised from the virtual users that name an app.
  *
  * Which frontend a person may sign into is a different question from what they
  * may do once inside it, but it is the same *kind* of question — a grant that
@@ -31,11 +31,11 @@ export declare const declaredApps: (personas: PersonaMeta[]) => string[];
  *
  * Synthesised rather than written by hand because the declaration already
  * exists. Asking an app to also spell out `defineScope({ app: { staff: {} } })`
- * beside its personas invites the two to drift, and the failure that produces —
- * a persona provisioned with a grant the vocabulary no longer declares — is one
+ * beside its virtual users invites the two to drift, and the failure that produces —
+ * a virtual user provisioned with a grant the vocabulary no longer declares — is one
  * `pikku scopes prune` away from silently revoking sign-in.
  *
- * Null when no persona names an app, which is the single-frontend case: nothing
+ * Null when no virtual user names an app, which is the single-frontend case: nothing
  * to declare, and no empty root cluttering the console's grant list.
  */
-export declare const buildAppScopeDefinition: (personas: PersonaMeta[]) => ScopeDefinitionMeta | null;
+export declare const buildAppScopeDefinition: (virtualUsers: VirtualUserMeta[]) => ScopeDefinitionMeta | null;

package/dist/wirings/{persona/persona-app-scopes.js → virtual-user/virtual-user-app-scopes.js}

@@ -8,20 +8,20 @@ export const APP_SCOPE_ROOT = 'app';
 /** `app:staff` for `staff`. */
 export const appScopeId = (app) => `${APP_SCOPE_ROOT}:${app}`;
 /**
- * The apps named across the declared personas, sorted and deduplicated.
+ * The apps named across the declared virtual users, sorted and deduplicated.
  *
- * The personas *are* the registry. There is no separate list of apps to keep in
+ * The virtual users *are* the registry. There is no separate list of apps to keep in
  * step, because a frontend nobody signs into is not a thing the auth layer has
  * an opinion about — and the moment somebody does sign into it, they are a
- * persona and they name it.
+ * virtual user and they name it.
  */
-export const declaredApps = (personas) => [
-    ...new Set(personas
-        .map((persona) => persona.app)
+export const declaredApps = (virtualUsers) => [
+    ...new Set(virtualUsers
+        .map((virtualUser) => virtualUser.app)
         .filter((app) => typeof app === 'string' && app !== '')),
 ].sort();
 /**
- * The `app` scope tree, synthesised from the personas that name an app.
+ * The `app` scope tree, synthesised from the virtual users that name an app.
  *
  * Which frontend a person may sign into is a different question from what they
  * may do once inside it, but it is the same *kind* of question — a grant that
@@ -33,15 +33,15 @@ export const declaredApps = (personas) => [
  *
  * Synthesised rather than written by hand because the declaration already
  * exists. Asking an app to also spell out `defineScope({ app: { staff: {} } })`
- * beside its personas invites the two to drift, and the failure that produces —
- * a persona provisioned with a grant the vocabulary no longer declares — is one
+ * beside its virtual users invites the two to drift, and the failure that produces —
+ * a virtual user provisioned with a grant the vocabulary no longer declares — is one
  * `pikku scopes prune` away from silently revoking sign-in.
  *
- * Null when no persona names an app, which is the single-frontend case: nothing
+ * Null when no virtual user names an app, which is the single-frontend case: nothing
  * to declare, and no empty root cluttering the console's grant list.
  */
-export const buildAppScopeDefinition = (personas) => {
-    const apps = declaredApps(personas);
+export const buildAppScopeDefinition = (virtualUsers) => {
+    const apps = declaredApps(virtualUsers);
     if (apps.length === 0) {
         return null;
     }

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

@@ -28,7 +28,7 @@ export declare const renderCatalogue: (entries: readonly ApiCatalogueEntry[]) =>
 /**
  * The entries a given user may reach: approval-gated calls dropped unless the
  * run opted in, mutations dropped for a read-only disposition, and anything the
- * actor's tier cannot satisfy dropped when the caller supplied one.
+ * virtual user's tier cannot satisfy dropped when the caller supplied one.
  *
  * This narrows *what is offered*, never what is enforced — the server is the
  * only thing that decides who may call what, and a call this filter would have
@@ -38,7 +38,7 @@ export declare const reachableCatalogue: (entries: readonly ApiCatalogueEntry[],
     readOnly?: boolean;
     allowApprovalRequired?: boolean;
     /**
-     * The scopes this persona holds, resolved from its roles. Omit to keep
+     * The scopes this virtual user holds, resolved from its roles. Omit to keep
      * every entry.
      *
      * Scopes rather than permission-function names: a function's `scopes` are
@@ -49,7 +49,7 @@ export declare const reachableCatalogue: (entries: readonly ApiCatalogueEntry[],
     scopes?: readonly string[];
 }) => ApiCatalogueEntry[];
 /**
- * Endpoints this persona is *not* entitled to reach.
+ * Endpoints this virtual user is *not* entitled to reach.
  *
  * The adversarial oracle. Withheld from the catalogue, so reaching one takes
  * initiative — and a 2xx from one is the finding, because the server is the

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

@@ -67,7 +67,7 @@ export const renderCatalogue = (entries) => entries.map(renderEntry).join('\n');
 /**
  * The entries a given user may reach: approval-gated calls dropped unless the
  * run opted in, mutations dropped for a read-only disposition, and anything the
- * actor's tier cannot satisfy dropped when the caller supplied one.
+ * virtual user's tier cannot satisfy dropped when the caller supplied one.
  *
  * This narrows *what is offered*, never what is enforced — the server is the
  * only thing that decides who may call what, and a call this filter would have
@@ -84,7 +84,7 @@ export const reachableCatalogue = (entries, { readOnly = false, allowApprovalReq
     return true;
 });
 /**
- * Endpoints this persona is *not* entitled to reach.
+ * Endpoints this virtual user is *not* entitled to reach.
  *
  * The adversarial oracle. Withheld from the catalogue, so reaching one takes
  * initiative — and a 2xx from one is the finding, because the server is the

package/dist/wirings/{persona/persona.types.d.ts → virtual-user/virtual-user-declaration.types.d.ts}

@@ -1,23 +1,23 @@
 import type { VirtualUserDisposition } from '../virtual-user/virtual-user.types.js';
 import type { VirtualUserTuning } from '../virtual-user/virtual-user-dispositions.js';
 /**
- * One login belonging to a persona.
+ * One login belonging to a virtual user.
  *
  * Deliberately near-empty in the common case: the address is computed from the
- * persona's name and the run id, and the password derives from
- * `SCENARIO_ACTOR_SECRET`, so there is nothing left to write down. It fills up
+ * virtual user's name and the run id, and sign-in needs no password, so there is
+ * nothing left to write down. It fills up
  * only for a provider login.
  *
  * Shaped after better-auth's `account` table, which is what most pikku apps are
  * actually running: `providerId` plus the provider's own id, and no email
  * column — the address belongs to the person, not the login.
  */
-export type CorePersonaAccount = {
+export type CoreVirtualUserAccount = {
     /**
      * The identity provider, e.g. `'google'`. Omit for email and password.
      *
      * A provider account is declarable but not runnable: driving its consent
-     * screen needs a human, so `pikku persona run` refuses rather than failing
+     * screen needs a human, so `pikku virtual-user run` refuses rather than failing
      * somewhere inside a browser.
      */
     provider?: string;
@@ -26,12 +26,12 @@ export type CorePersonaAccount = {
  * A person who uses your product: a name, a job, a temperament, and what they
  * are trying to get done.
  *
- * This is Cooper's persona — "a fictional character created to represent a user
+ * This is Cooper's virtual user — "a fictional character created to represent a user
  * type" — with the two things a synthetic user additionally needs: the roles
- * that say what they may do, and the account they log in with. A persona while
+ * that say what they may do, and the account they log in with. A virtual user while
  * running is a virtual user; there is no second declaration for that.
  */
-export type CorePersona = {
+export type CoreVirtualUser = {
     /** The person's name, as a person would give it. */
     name: string;
     jobTitle?: string;
@@ -41,14 +41,14 @@ export type CorePersona = {
      * serves, an asset on a CDN, a Gravatar link.
      *
      * Optional because it is decoration. Omitted, the console draws a colour and
-     * an icon derived from the persona's id, which is stable, needs no network and
+     * an icon derived from the virtual user's id, which is stable, needs no network and
      * is more legible than the identicon a synthetic address would resolve to —
      * which is also why nothing is derived here.
      */
     avatarUrl?: string;
     /**
      * The roles this person holds. Only system roles may be named — a custom
-     * role can be deleted from the console, so a persona pinned to one silently
+     * role can be deleted from the console, so a virtual user pinned to one silently
      * stops testing what it claims to.
      *
      * These are granted, not merely recorded: the generated seed applies them,
@@ -74,15 +74,15 @@ export type CorePersona = {
     /** Fixture paths this person may upload, relative to the project root. */
     fixtures?: string[];
     /** Their login. `{}` — email and password — is the normal case. */
-    account?: CorePersonaAccount;
+    account?: CoreVirtualUserAccount;
     /**
      * Further logins belonging to the same human, keyed by name.
      *
-     * Rare, and shaped that way on purpose. All of them share the persona's one
+     * Rare, and shaped that way on purpose. All of them share the virtual user's one
      * computed address: better-auth's `allowDifferentEmails` defaults to false,
      * so distinct addresses would be refused linking by the library under test.
      */
-    linkedAccounts?: Record<string, CorePersonaAccount>;
+    linkedAccounts?: Record<string, CoreVirtualUserAccount>;
     /**
      * The environments this person may run against, by config key.
      *
@@ -100,7 +100,7 @@ export type CorePersona = {
      *
      * An assertion, not something inferred from the absence of a disposition:
      * `target` *must not* run, because a run signing in as her would race the
-     * scenario banning her. "Nobody has given this persona a disposition yet" is
+     * scenario banning her. "Nobody has given this virtual user a disposition yet" is
      * a different state, and collapsing the two turns a deliberate constraint
      * into a flaky suite.
      */
@@ -110,20 +110,20 @@ export type CorePersona = {
      *
      * A person uses one of them — staff their app, customers theirs — and that is
      * what decides where a browser step navigates: `/dashboard` is a different
-     * page in each, so the actor settles which one without the scenario saying.
+     * page in each, so the virtual user settles which one without the scenario saying.
      * The runner takes the base url per app (`--app-url <app>=<url>`, or
-     * `appUrls` on the environment) and each actor browses against its own.
+     * `appUrls` on the environment) and each virtual user browses against its own.
      *
      * Omitted is the normal case: one app, one url, nothing to say.
      */
     app?: string;
 };
-/** Personas to declare, keyed by id. */
-export type CorePersonas = Record<string, CorePersona>;
-export type PersonaAccountMeta = {
+/** Virtual users to declare, keyed by id. */
+export type CoreVirtualUsers = Record<string, CoreVirtualUser>;
+export type VirtualUserAccountMeta = {
     provider?: string;
 };
-export type PersonaMeta = {
+export type VirtualUserMeta = {
     /** The key it was declared under. */
     id: string;
     name: string;
@@ -137,8 +137,8 @@ export type PersonaMeta = {
     disposition?: VirtualUserDisposition;
     tuning?: VirtualUserTuning;
     fixtures?: string[];
-    account?: PersonaAccountMeta;
-    linkedAccounts?: Record<string, PersonaAccountMeta>;
+    account?: VirtualUserAccountMeta;
+    linkedAccounts?: Record<string, VirtualUserAccountMeta>;
     /** Absent means "everywhere but production", which is resolved, not stored. */
     environments?: string[];
     runnable: boolean;
@@ -146,5 +146,5 @@ export type PersonaMeta = {
     app?: string;
     sourceFile?: string;
 };
-export type PersonaDefinitions = PersonaMeta[];
-export type PersonasMeta = Record<string, PersonaMeta>;
+export type VirtualUserDefinitions = VirtualUserMeta[];
+export type VirtualUsersMeta = Record<string, VirtualUserMeta>;

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

@@ -25,9 +25,9 @@ export const deriveCatalogue = (functions, schemas = {}) => {
         if (meta.expose !== true)
             continue;
         // A virtual user is not offered the machinery that runs virtual users. A
-        // persona whose role carries `virtualUser:*` would otherwise be able to
+        // virtual user whose role carries `virtualUser:*` would otherwise be able to
         // start further runs, read every run's findings — an adversarial run's
-        // transcript is working exploits against this same app — and put a persona
+        // transcript is working exploits against this same app — and put a virtual user
         // on a schedule that outlives it. Same reasoning as the scenario-step rule
         // above: the tool is about the run, not about the product being explored.
         if (meta.scopes?.some((scope) => scope.split(':')[0] === 'virtualUser')) {
@@ -68,15 +68,21 @@ export const deriveCatalogue = (functions, schemas = {}) => {
 const scenarioSteps = (meta) => {
     if (meta.steps?.length) {
         return meta.steps.flatMap((step) => step.type === 'scenarioStep'
-            ? [{ stepFunc: step.stepFunc, phase: step.phase, actor: step.actor }]
+            ? [
+                {
+                    stepFunc: step.stepFunc,
+                    phase: step.phase,
+                    virtualUser: step.virtualUser,
+                },
+            ]
             : []);
     }
     // knowledge: decisions/internals/virtual-user-step-order-comes-from-insertion-order.md
     return Object.values(meta.nodes ?? {}).flatMap((node) => {
-        const { rpcName, scenarioStepPhase, actor } = (node ?? {});
+        const { rpcName, scenarioStepPhase, virtualUser } = (node ?? {});
         if (!rpcName || !scenarioStepPhase)
             return [];
-        return [{ stepFunc: rpcName, phase: scenarioStepPhase, actor }];
+        return [{ stepFunc: rpcName, phase: scenarioStepPhase, virtualUser }];
     });
 };
 /**
@@ -109,7 +115,7 @@ export const deriveIntents = (workflows, functions = {}) => {
                 phase: step.phase,
                 // knowledge: decisions/internals/a-scenario-step-template-is-offered-unfilled.md
                 description: template ?? description ?? '',
-                actor: step.actor,
+                virtualUser: step.virtualUser,
             }));
         }
         intents.push({
@@ -118,7 +124,7 @@ export const deriveIntents = (workflows, functions = {}) => {
             description: meta.description,
             steps: steps.length ? steps : undefined,
             tags: meta.tags?.length ? meta.tags : undefined,
-            personas: meta.actors?.length ? meta.actors : undefined,
+            virtualUsers: meta.virtualUsers?.length ? meta.virtualUsers : undefined,
         });
     }
     return intents;

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

@@ -5,7 +5,7 @@ import type { VirtualUserDisposition } from './virtual-user.types.js';
  * behaviour the dials cannot express on their own.
  */
 export interface DispositionProfile {
-    /** Appended to the persona instructions. Behaviour, never identity. */
+    /** Appended to the virtual user instructions. Behaviour, never identity. */
     instructions: string;
     /**
      * Relative weights for the scheduler's four moves. `continue` dominating is