@pikku/core 0.12.141 → 0.12.142

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

@@ -1,21 +1,21 @@
 /**
- * No-op function for declaring personas.
+ * No-op function for declaring virtual users.
  * This exists purely for TypeScript type checking and will be tree-shaken.
- * The CLI extracts metadata via AST parsing and generates a `PersonaId` union
- * and a `personas.gen.json` the console and `pikku persona run` read off disk —
+ * The CLI extracts metadata via AST parsing and generates a `VirtualUserId` union
+ * and a `virtual-users.gen.json` the console and `pikku virtual-user run` read off disk —
  * describing, listing or running one never has to load the app.
  *
- * `definePersonas` rather than `defineVirtualUsers` because declaring is not
- * running: a persona that exists only to be acted upon (the account an admin
- * bans, the colleague a document is shared with) is seeded and never run.
+ * Declaring is not running: a virtual user that exists only to be acted upon
+ * (the account an admin bans, the colleague a document is shared with) is
+ * seeded and never run.
  *
- * Exactly one `definePersonas(...)` is allowed per codebase, so there is one
+ * Exactly one `defineVirtualUsers(...)` is allowed per codebase, so there is one
  * place to read the cast from and one place to add to. A second call — even in
  * the same file — fails the build.
  *
  * @example
  * ```typescript
- * definePersonas({
+ * defineVirtualUsers({
  *   susan: {
  *     name: 'Susan',
  *     jobTitle: 'Buys for a small café',
@@ -28,4 +28,4 @@
  * })
  * ```
  */
-export const definePersonas = (_config) => { };
+export const defineVirtualUsers = (_config) => { };

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

@@ -1,7 +1,7 @@
 /**
  * Virtual user module exports.
  *
- * A virtual user is an LLM playing a persona that signs into a *running* stage
+ * A virtual user is an LLM that signs into a *running* stage
  * and works its API in character — non-deterministically, with a budget, and
  * with oracles watching what comes back. It is not a test runner: nothing here
  * asserts an expected outcome, because the point is the outcomes nobody thought
@@ -9,24 +9,47 @@
  *
  * Everything it needs is derived from what a pikku project already generates —
  * the function meta becomes the catalogue, the scenario meta becomes the
- * intents, the declared personas become the identities — so adopting it is
+ * intents, the declared virtual users become the identities — so adopting it is
  * configuration rather than authoring.
  *
  * The engine is transport-agnostic: the virtual user drives an
- * {@link VirtualUserTarget}, which in production is an `HttpPersona`
+ * {@link VirtualUserTarget}, which in production is an `HttpVirtualUser`
  * signed in as a real user against staging or production.
  */
 export type { ApiCatalogueEntry, IntentRecord, IntentSource, StepRecord, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTarget, } from './virtual-user.types.js';
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, type RunVirtualUserParams, } from './run-virtual-user.js';
-export { personaScopes, prepareVirtualUserRun, type VirtualUserPreparation, } from './prepare-virtual-user-run.js';
+export { virtualUserScopes, prepareVirtualUserRun, type VirtualUserPreparation, } from './prepare-virtual-user-run.js';
 export type { VirtualUserRunOutcome, VirtualUserRunRecord, VirtualUserRunStart, VirtualUserRunStore, } from './virtual-user-run-store.js';
 export type { VirtualUserScheduleInput, VirtualUserScheduleRecord, VirtualUserScheduleStore, } from './virtual-user-schedule-store.js';
 export { DEFAULT_MAX_INTERVAL_MS, DEFAULT_MIN_INTERVAL_MS, isDue, nextRunAt, STALE_RUN_AFTER_MS, tickVirtualUserSchedules, type VirtualUserTickParams, type VirtualUserTickResult, } from './virtual-user-schedule.js';
 export { DISPOSITIONS, dispositionProfile, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';
-export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
+export { IntentStack, intentsForVirtualUser } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, type SchemaMap, } from './virtual-user-derive.js';
-export { personaVirtualUserTarget, type PersonaTargetOptions, } from './virtual-user-target.js';
-export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnablePersona, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, signInPathFor, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, type ExecuteVirtualUserRunParams, type ScaffoldPersonas, type StartedVirtualUserRun, type StartVirtualUserRunParams, type WriteVirtualUserScheduleParams, } from './virtual-user-scaffold.js';
+export { virtualUserTarget, type VirtualUserTargetOptions, } from './virtual-user-target.js';
+export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnableVirtualUser, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, type ExecuteVirtualUserRunParams, type ScaffoldVirtualUsers, type StartedVirtualUserRun, type StartVirtualUserRunParams, type WriteVirtualUserScheduleParams, } from './virtual-user-scaffold.js';
+export { defineVirtualUsers } from './define-virtual-users.js';
+export { isRunnableVirtualUser, roleMismatchMessage, runnableVirtualUsers, validateAndBuildVirtualUsersMeta, verifyVirtualUserRoles, } from './validate-virtual-users.js';
+export type { RoleVerification } from './validate-virtual-users.js';
+export { virtualUserEnvironmentErrors, virtualUserEnvironmentRefusal, } from './virtual-user-environments.js';
+export type { VirtualUserEnvironment, VirtualUserEnvironmentSubject, } from './virtual-user-environments.js';
+export { virtualUserEmail, virtualUserEmails } from './virtual-user-email.js';
+export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './virtual-user-app-scopes.js';
+export type { MailboxAllowlist, VirtualUserMailbox, ReceivedEmail, } from './virtual-user-mailbox.js';
+export type { CoreVirtualUser, CoreVirtualUsers, VirtualUserAccountMeta, VirtualUserDefinitions, VirtualUserMeta, VirtualUsersMeta, } from './virtual-user-declaration.types.js';
+/**
+ * Signing in as a virtual user and talking to a stage over HTTP.
+ *
+ * Deliberately reached through this entry point rather than `@pikku/core/services`.
+ * `HttpVirtualUser` pulls in the conversation runner and, through it, the
+ * agent runner — none of which a production server has any use for. Exporting it
+ * from the services barrel put that chain in the module graph of every app that
+ * imports services, which only a bundler could remove and an unbundled Node or
+ * Lambda deploy would load outright.
+ */
+export { HttpVirtualUser, createHttpVirtualUsers, type HttpVirtualUsersConfig, } from '../../services/http-virtual-users.js';
+export { statementSignIn, inProcessSignIn, authMount, type VirtualUserSignIn, type VirtualUserStatementMint, type StatementSignInOptions, type InProcessAuth, } from '../../services/virtual-user-sign-in.js';
+export { createCookieJar, type ScenarioCookieJar, } from '../../services/scenario-cookie-jar.js';
+export { postScenarioJson, readScenarioHttpResponse, } from '../../services/virtual-users-service.js';

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

@@ -1,10 +1,29 @@
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
 export { runVirtualUser, } from './run-virtual-user.js';
-export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
+export { virtualUserScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
 export { DEFAULT_MAX_INTERVAL_MS, DEFAULT_MIN_INTERVAL_MS, isDue, nextRunAt, STALE_RUN_AFTER_MS, tickVirtualUserSchedules, } from './virtual-user-schedule.js';
 export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
-export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
+export { IntentStack, intentsForVirtualUser } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
-export { personaVirtualUserTarget, } from './virtual-user-target.js';
-export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnablePersona, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, signInPathFor, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, } from './virtual-user-scaffold.js';
+export { virtualUserTarget, } from './virtual-user-target.js';
+export { executeVirtualUserRun, logVirtualUserTick, requireVirtualUserRunStore, requireVirtualUserScheduleStore, runnableVirtualUser, serializeVirtualUserRun, serializeVirtualUserSchedule, serializeVirtualUserSteps, startVirtualUserRun, VIRTUAL_USER_VARIABLES, virtualUserScheduleRunInput, writeVirtualUserSchedule, } from './virtual-user-scaffold.js';
+export { defineVirtualUsers } from './define-virtual-users.js';
+export { isRunnableVirtualUser, roleMismatchMessage, runnableVirtualUsers, validateAndBuildVirtualUsersMeta, verifyVirtualUserRoles, } from './validate-virtual-users.js';
+export { virtualUserEnvironmentErrors, virtualUserEnvironmentRefusal, } from './virtual-user-environments.js';
+export { virtualUserEmail, virtualUserEmails } from './virtual-user-email.js';
+export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './virtual-user-app-scopes.js';
+/**
+ * Signing in as a virtual user and talking to a stage over HTTP.
+ *
+ * Deliberately reached through this entry point rather than `@pikku/core/services`.
+ * `HttpVirtualUser` pulls in the conversation runner and, through it, the
+ * agent runner — none of which a production server has any use for. Exporting it
+ * from the services barrel put that chain in the module graph of every app that
+ * imports services, which only a bundler could remove and an unbundled Node or
+ * Lambda deploy would load outright.
+ */
+export { HttpVirtualUser, createHttpVirtualUsers, } from '../../services/http-virtual-users.js';
+export { statementSignIn, inProcessSignIn, authMount, } from '../../services/virtual-user-sign-in.js';
+export { createCookieJar, } from '../../services/scenario-cookie-jar.js';
+export { postScenarioJson, readScenarioHttpResponse, } from '../../services/virtual-users-service.js';

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

@@ -5,19 +5,19 @@ import { type SchemaMap } from './virtual-user-derive.js';
 import { type AgentReachability, type ReachableAgent } from './virtual-user-agents.js';
 import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js';
 /**
- * The scopes a persona holds, resolved through its roles.
+ * The scopes a virtual user holds, resolved through its roles.
  *
- * Roles are the only thing a persona declares; scopes are what a function
+ * Roles are the only thing a virtual user declares; scopes are what a function
  * checks. Narrowing a virtual user's catalogue needs the second, so the
  * expansion happens once, here, against the same `defineSystemRole` definitions
  * the seed grants from.
  */
-export declare const personaScopes: (persona: {
+export declare const virtualUserScopes: (virtualUser: {
     roles?: readonly string[];
 }, roleScopes: Record<string, readonly string[]>) => string[];
 /** Everything a run needs that is derived rather than decided. */
 export interface VirtualUserPreparation {
-    /** Every RPC the app exposes, narrowed to what this persona can reach. */
+    /** Every RPC the app exposes, narrowed to what this virtual user can reach. */
     catalogue: ApiCatalogueEntry[];
     intents: IntentSource[];
     scopes: string[];
@@ -27,18 +27,18 @@ export interface VirtualUserPreparation {
  * Derive what a virtual user needs from what the project already generates.
  *
  * Shared because there are two callers with the same problem and different
- * sources for it: `pikku persona run` reads the inspector state at build time,
+ * sources for it: `pikku virtual-user run` reads the inspector state at build time,
  * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
- * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * must agree — a virtual user whose catalogue is narrower over RPC than on the CLI
  * finds different things from the same seed, which is exactly the property a
  * seed exists to give.
  *
  * Nothing here is authored for the virtual user's benefit: the function meta is
  * the catalogue, the scenario meta is the intents, and the role definitions are
- * what turn a persona's declared roles into the scopes a function checks.
+ * what turn a virtual user's declared roles into the scopes a function checks.
  */
 export declare const prepareVirtualUserRun: (input: {
-    persona: {
+    virtualUser: {
         roles?: readonly string[];
     };
     functionsMeta: FunctionsMeta;

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

@@ -2,16 +2,16 @@ import { flattenSystemRoleDefinitions } from '../role/validate-role-definitions.
 import { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
 import { reachableAgents, } from './virtual-user-agents.js';
 /**
- * The scopes a persona holds, resolved through its roles.
+ * The scopes a virtual user holds, resolved through its roles.
  *
- * Roles are the only thing a persona declares; scopes are what a function
+ * Roles are the only thing a virtual user declares; scopes are what a function
  * checks. Narrowing a virtual user's catalogue needs the second, so the
  * expansion happens once, here, against the same `defineSystemRole` definitions
  * the seed grants from.
  */
-export const personaScopes = (persona, roleScopes) => {
+export const virtualUserScopes = (virtualUser, roleScopes) => {
     const scopes = new Set();
-    for (const role of persona.roles ?? []) {
+    for (const role of virtualUser.roles ?? []) {
         for (const scope of roleScopes[role] ?? []) {
             scopes.add(scope);
         }
@@ -22,15 +22,15 @@ export const personaScopes = (persona, roleScopes) => {
  * Derive what a virtual user needs from what the project already generates.
  *
  * Shared because there are two callers with the same problem and different
- * sources for it: `pikku persona run` reads the inspector state at build time,
+ * sources for it: `pikku virtual-user run` reads the inspector state at build time,
  * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
- * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * must agree — a virtual user whose catalogue is narrower over RPC than on the CLI
  * finds different things from the same seed, which is exactly the property a
  * seed exists to give.
  *
  * Nothing here is authored for the virtual user's benefit: the function meta is
  * the catalogue, the scenario meta is the intents, and the role definitions are
- * what turn a persona's declared roles into the scopes a function checks.
+ * what turn a virtual user's declared roles into the scopes a function checks.
  */
 export const prepareVirtualUserRun = (input) => {
     const catalogue = deriveCatalogue(input.functionsMeta, input.schemas ?? {});
@@ -40,10 +40,10 @@ export const prepareVirtualUserRun = (input) => {
     for (const role of flattenSystemRoleDefinitions(Array.isArray(declared) ? declared : Object.values(declared))) {
         roleScopes[role.name] = role.scopes;
     }
-    const scopes = personaScopes(input.persona, roleScopes);
+    const scopes = virtualUserScopes(input.virtualUser, roleScopes);
     // Gated by the same scopes as the RPCs, because an agent is reached rather
     // than declared: `CoreAgent.scopes` is checked against the session, so a
-    // persona finds the specialists its roles unlock and no others.
+    // virtual user finds the specialists its roles unlock and no others.
     const agents = reachableAgents(input.agentsMeta ?? {}, scopes);
     return { catalogue, intents, scopes, agents };
 };

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

@@ -1,5 +1,5 @@
-import type { ResolvedPersona } from '../../services/personas-service.js';
-import type { ActorLLM } from '../actor-flow/run-conversation.js';
+import type { ResolvedVirtualUser } from '../../services/virtual-users-service.js';
+import type { VirtualUserLLM } from './conversation/run-conversation.js';
 import { type VirtualUserTuning } from './virtual-user-dispositions.js';
 import type { ApiCatalogueEntry, IntentSource, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTally, VirtualUserTarget } from './virtual-user.types.js';
 /** What an app-specific oracle is shown about one call. */
@@ -15,9 +15,9 @@ export interface VirtualUserCallContext {
 }
 export interface RunVirtualUserParams {
     /** The person being run — name, job title, personality, goals. */
-    persona: ResolvedPersona;
+    virtualUser: ResolvedVirtualUser;
     /** The id they were declared under, as the intent sources refer to them. */
-    personaId: string;
+    virtualUserId: string;
     /** How it behaves. Default `realistic`. */
     disposition?: VirtualUserDisposition;
     /** Per-user overrides for that disposition's dials. */
@@ -31,7 +31,7 @@ export interface RunVirtualUserParams {
     /** The transport it acts through. */
     target: VirtualUserTarget;
     /** The user's own LLM. */
-    llm: ActorLLM;
+    llm: VirtualUserLLM;
     model: string;
     budget?: VirtualUserBudget;
     /**
@@ -60,7 +60,7 @@ export interface RunVirtualUserParams {
     /** Ids and slugs remembered from an earlier run, for a `stale` user. */
     memory?: Record<string, string>;
     /**
-     * The scopes this persona actually holds, resolved from its roles at sign-in.
+     * The scopes this virtual user actually holds, resolved from its roles at sign-in.
      *
      * Used two ways: to narrow a large catalogue to what it is entitled to reach,
      * and as an oracle — a call whose scopes it does not hold that nonetheless

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;