@pikku/inspector 0.12.103 → 0.12.107

package/dist/utils/post-process.js

@@ -1,16 +1,12 @@
-import { existsSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { join } from "node:path";
-import { extractTypeKeys } from "./type-utils.js";
-import { ErrorCode } from "../error-codes.js";
-import { findSecretAliasServices } from "./secret-alias-services.js";
-import { deriveOAuth2AppSecrets } from "@pikku/core/secret";
-import { resolveCoreType } from "./resolve-core-type.js";
-import { relative } from "node:path";
-import { AUTH_HANDLER_FUNC_ID } from "../add/add-auth.js";
-import { flattenScopeDefinitions } from "@pikku/core/scope";
-import { DYNAMIC_SCENARIO_STEP_TARGET } from "./workflow/dsl/patterns.js";
-import { addonResolutionDirs } from "./addon-resolution.js";
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { ErrorCode } from '../error-codes.js';
+import { deriveOAuth2AppSecrets } from '@pikku/core/secret';
+import { relative } from 'node:path';
+import { AUTH_HANDLER_FUNC_ID, DYNAMIC_SCENARIO_STEP_TARGET, } from './inspector-constants.js';
+import { flattenScopeDefinitions } from '@pikku/core/scope';
+import { addonResolutionDirs } from './addon-resolution.js';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -45,7 +41,7 @@ export function extractWireNames(list) {
     if (!list)
         return [];
     return list
-        .filter((item) => item.type === "wire")
+        .filter((item) => item.type === 'wire')
         .map((item) => item.name);
 }
 /**
@@ -57,13 +53,13 @@ function expandAndAddGroupServices(list, state, addServices) {
     if (!list)
         return;
     for (const item of list) {
-        if (item.type === "tag") {
+        if (item.type === 'tag') {
             const groupMeta = state.middleware.tagMiddleware.get(item.tag);
             if (groupMeta?.services) {
                 addServices(groupMeta.services);
             }
         }
-        else if (item.type === "http" && "route" in item) {
+        else if (item.type === 'http' && 'route' in item) {
             const groupMeta = state.http.routeMiddleware.get(item.route);
             if (groupMeta?.services) {
                 addServices(groupMeta.services);
@@ -72,26 +68,25 @@ function expandAndAddGroupServices(list, state, addServices) {
     }
 }
 /**
- * Extracts all service names from SingletonServices and Services types.
- * This provides the complete list of available services for code generation.
- * Only runs if typesLookup is available (omitted in deserialized states).
+ * Applies the service names of the SingletonServices and Services types, which
+ * `resolveServiceTypes` read off the checker during analysis. This provides the
+ * complete list of available services for code generation.
+ * Skipped when analysis did not resolve them (e.g. an older serialized state).
  */
 function extractAllServices(state) {
-    // Skip if typesLookup is not available (e.g., deserialized state)
-    if (!("typesLookup" in state)) {
+    const resolved = state.serviceTypes;
+    if (!resolved) {
         return;
     }
-    // Extract all singleton services from the SingletonServices type
-    const singletonServicesType = resolveCoreType(state.typesLookup, state.singletonServicesTypeImportMap);
-    if (singletonServicesType) {
-        state.serviceAggregation.allSingletonServices = extractTypeKeys(singletonServicesType).sort();
+    if (resolved.singletonServices) {
+        state.serviceAggregation.allSingletonServices = [
+            ...resolved.singletonServices,
+        ];
     }
-    // Extract all services from the Services type
-    const servicesType = resolveCoreType(state.typesLookup, state.wireServicesTypeImportMap);
-    if (servicesType) {
+    if (resolved.services) {
         // Wire services are those in Services but not in SingletonServices
         const singletonSet = new Set(state.serviceAggregation.allSingletonServices);
-        state.serviceAggregation.allWireServices = extractTypeKeys(servicesType)
+        state.serviceAggregation.allWireServices = resolved.services
             .filter((name) => !singletonSet.has(name))
             .sort();
         markSingletonServicesOnly(state, new Set(state.serviceAggregation.allWireServices));
@@ -126,7 +121,7 @@ export function aggregateRequiredServices(state) {
     extractAllServices(state);
     const { requiredServices, usedFunctions, usedMiddleware, usedPermissions } = state.serviceAggregation;
     // Internal services (always excluded from tree-shaking)
-    const internalServices = new Set(["rpc", "mcp", "channel", "userSession"]);
+    const internalServices = new Set(['rpc', 'mcp', 'channel', 'userSession']);
     const addServices = (services) => {
         if (!services || !services.services)
             return;
@@ -170,9 +165,29 @@ export function aggregateRequiredServices(state) {
             addServices(permissionMeta.services);
         }
     });
+    // 3b. Global permissions and global middleware apply to every function, so
+    // whatever they touch is required wherever any function runs.
+    for (const registration of state.permissions?.global ?? []) {
+        for (const definitionId of registration.definitionIds) {
+            addServices(state.permissions.definitions[definitionId]?.services);
+        }
+    }
+    for (const [instanceId, instance] of Object.entries(state.middleware?.instances ?? {})) {
+        if (instanceId.startsWith('global:')) {
+            addServices(state.middleware.definitions[instance.definitionId]?.services);
+        }
+    }
     // 4. Services from middleware/permission groups used in wirings
     // We need to check all wirings and expand any tag/HTTP-pattern groups they use
-    for (const method of ["get", "post", "put", "patch", "delete", "head", "options"]) {
+    for (const method of [
+        'get',
+        'post',
+        'put',
+        'patch',
+        'delete',
+        'head',
+        'options',
+    ]) {
         for (const routeMeta of Object.values(state.http.meta[method])) {
             expandAndAddGroupServices(routeMeta.middleware, state, addServices);
         }
@@ -210,22 +225,23 @@ export function aggregateRequiredServices(state) {
     // that wrap workflow operations but don't destructure the services.
     const hasWorkflows = Object.keys(state.workflows.graphMeta).length > 0 ||
         Object.keys(state.workflows.meta).length > 0 ||
-        Object.keys(state.functions.meta).some((id) => id.startsWith("workflowStart:") ||
-            id.startsWith("workflowStatus:") ||
-            id.startsWith("workflow:"));
+        Object.keys(state.functions.meta).some((id) => id.startsWith('workflowStart:') ||
+            id.startsWith('workflowStatus:') ||
+            id.startsWith('workflow:'));
     if (hasWorkflows) {
-        requiredServices.add("workflowService");
-        requiredServices.add("workflowRunService");
-        requiredServices.add("schedulerService");
-        requiredServices.add("queueService");
+        requiredServices.add('workflowService');
+        requiredServices.add('workflowRunService');
+        requiredServices.add('schedulerService');
+        requiredServices.add('queueService');
     }
     // Webhook source routes and their worker are generated and destructure
     // nothing, so they are found by id: the route accepts into the queue through
     // incomingWebhookService and the worker records attempts through it.
     const hasWebhookSources = Object.values(state.triggers?.webhookSourceMeta ?? {}).some(({ method, route }) => state.functions.meta[`http:${method}:${route}`] !== undefined);
-    if (hasWebhookSources || state.functions.meta["queue:pikku-incoming-webhooks"] !== undefined) {
-        requiredServices.add("incomingWebhookService");
-        requiredServices.add("queueService");
+    if (hasWebhookSources ||
+        state.functions.meta['queue:pikku-incoming-webhooks'] !== undefined) {
+        requiredServices.add('incomingWebhookService');
+        requiredServices.add('queueService');
     }
     // 6b. Inject synthetic queue workers for workflow graph steps.
     // Each workflow gets an orchestrator queue and per-step queues.
@@ -239,11 +255,11 @@ export function aggregateRequiredServices(state) {
         // synthetic entries were pure leakage: they put a
         // `wf-orchestrator-<scenario>` worker into the app's queue meta, which every
         // bundle imports and a provider then creates as a real production queue.
-        if (graph.source === "scenario")
+        if (graph.source === 'scenario')
             continue;
         const toKebab = (s) => s
-            .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
-            .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+            .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+            .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
             .toLowerCase();
         // Orchestrator queue
         const orchQueueName = `wf-orchestrator-${toKebab(graph.name)}`;
@@ -255,11 +271,14 @@ export function aggregateRequiredServices(state) {
         }
         // Per-step queues — only for steps explicitly marked workflowQueued: true
         for (const node of Object.values(graph.nodes)) {
-            if (!("rpcName" in node) || !node.rpcName)
+            if (!('rpcName' in node) || !node.rpcName)
                 continue;
             const rpcName = node.rpcName;
-            const funcId = state.rpc?.internalMeta?.[rpcName] ?? state.rpc?.exposedMeta?.[rpcName] ?? rpcName;
-            const funcMeta = (state.functions.meta[funcId] ?? state.functions.meta[rpcName]);
+            const funcId = state.rpc?.internalMeta?.[rpcName] ??
+                state.rpc?.exposedMeta?.[rpcName] ??
+                rpcName;
+            const funcMeta = (state.functions.meta[funcId] ??
+                state.functions.meta[rpcName]);
             if (funcMeta?.workflowQueued !== true)
                 continue;
             const stepQueueName = `wf-step-${toKebab(rpcName)}`;
@@ -273,20 +292,20 @@ export function aggregateRequiredServices(state) {
     }
     // AI agents need agentStorage + agentRunState + agentRunService + agentRunner
     if (Object.keys(state.agents.agentsMeta).length > 0) {
-        requiredServices.add("agentStorage");
-        requiredServices.add("agentRunState");
-        requiredServices.add("agentRunService");
-        requiredServices.add("agentRunner");
+        requiredServices.add('agentStorage');
+        requiredServices.add('agentRunState');
+        requiredServices.add('agentRunService');
+        requiredServices.add('agentRunner');
     }
     // Channels need eventHub for pub/sub
     if (Object.keys(state.channels.meta).length > 0) {
-        requiredServices.add("eventHub");
+        requiredServices.add('eventHub');
     }
     // Declared scopes need scopeService to resolve a grant. Nothing in a project
     // destructures it — the generated auth layer reaches it — so the declaration
     // is the only signal there is.
     if ((state.scopes?.definitions?.length ?? 0) > 0) {
-        requiredServices.add("scopeService");
+        requiredServices.add('scopeService');
     }
     // Declared feature flags need featureFlags for the same reason, from the
     // other side: `assertFeatureAvailable` reads the source out of the singleton
@@ -294,17 +313,17 @@ export function aggregateRequiredServices(state) {
     // ever says the project has flags. Without this the flag tables are left out
     // of the generated migration and every gate silently resolves open.
     if ((state.featureFlags?.definitions?.length ?? 0) > 0) {
-        requiredServices.add("featureFlags");
+        requiredServices.add('featureFlags');
     }
     // A `defineAnalyticsEvents` declaration means events are emitted, and the
     // invocation buffer flushes into `analyticsService`. Nothing destructures
     // that either — functions are handed the request-scoped `analytics` — so the
     // declaration is again the only signal.
     if ((state.analytics?.length ?? 0) > 0) {
-        requiredServices.add("analyticsService");
+        requiredServices.add('analyticsService');
     }
     if ((state.credentials?.definitions?.length ?? 0) > 0) {
-        requiredServices.add("credentialService");
+        requiredServices.add('credentialService');
     }
     // 7. Services that consumed addons need from the parent project.
     const addonFnServices = new Map();
@@ -315,7 +334,13 @@ export function aggregateRequiredServices(state) {
     }
     const parentDeclared = state.addonRequiredParentServices ?? [];
     const parentDeclaredSet = new Set(parentDeclared);
-    const defaultServices = new Set(["config", "logger", "variables", "schema", "secrets"]);
+    const defaultServices = new Set([
+        'config',
+        'logger',
+        'variables',
+        'schema',
+        'secrets',
+    ]);
     let usesAddonFn = false;
     let addonFactoryNeeded = false;
     for (const funcId of usedFunctions) {
@@ -331,7 +356,8 @@ export function aggregateRequiredServices(state) {
             if (parentDeclaredSet.has(service)) {
                 requiredServices.add(service);
             }
-            else if (!internalServices.has(service) && !defaultServices.has(service)) {
+            else if (!internalServices.has(service) &&
+                !defaultServices.has(service)) {
                 addonFactoryNeeded = true;
             }
         }
@@ -379,7 +405,7 @@ export function validateSecretOverrides(logger, state) {
         for (const [logicalName, resolvedName] of Object.entries(addonDecl.secretOverrides ?? {})) {
             if (!secretIds.has(resolvedName)) {
                 const availableSecrets = Array.from(secretIds);
-                logger.critical(ErrorCode.INVALID_VALUE, `Secret override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(", ") || "none"}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `Secret override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`);
             }
         }
         // A grant names the secret as the addon reads it, so it resolves through
@@ -388,7 +414,7 @@ export function validateSecretOverrides(logger, state) {
             const resolvedName = addonDecl.secretOverrides?.[logicalName] ?? logicalName;
             if (!secretIds.has(resolvedName)) {
                 const availableSecrets = Array.from(secretIds);
-                logger.critical(ErrorCode.INVALID_VALUE, `Secret grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(", ") || "none"}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `Secret grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`);
             }
         }
     }
@@ -401,7 +427,7 @@ export function validateAddonUses(logger, state) {
         for (const [pkg, target] of Object.entries(addonDecl.uses ?? {})) {
             const wired = wireAddonDeclarations.get(target);
             if (!wired) {
-                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but no addon is wired under the name '${target}'. Wired: ${Array.from(wireAddonDeclarations.keys()).join(", ")}`);
+                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but no addon is wired under the name '${target}'. Wired: ${Array.from(wireAddonDeclarations.keys()).join(', ')}`);
             }
             else if (wired.package !== pkg) {
                 logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but '${target}' is wired from '${wired.package}'.`);
@@ -416,12 +442,12 @@ export function validateAddonContentGrants(logger, state) {
     const buckets = new Set(Array.from(wireAddonDeclarations.entries()).map(([namespace, decl]) => decl.contentBucket ?? namespace));
     for (const [namespace, decl] of wireAddonDeclarations.entries()) {
         for (const [prefix, mode] of Object.entries(decl.contentGrants ?? {})) {
-            if (mode !== "read" && mode !== "write") {
+            if (mode !== 'read' && mode !== 'write') {
                 logger.critical(ErrorCode.ADDON_CONTENT_GRANT_INVALID, `Addon '${namespace}' grants '${prefix}' as '${mode}', but a content grant must be 'read' or 'write'.`);
             }
-            const first = prefix.split("/").find((segment) => segment !== "");
+            const first = prefix.split('/').find((segment) => segment !== '');
             if (!first || !buckets.has(first)) {
-                logger.critical(ErrorCode.ADDON_CONTENT_GRANT_INVALID, `Addon '${namespace}' grants content under '${prefix}', but '${first ?? ""}' is not the content bucket of any wired addon. Buckets: ${Array.from(buckets).join(", ")}`);
+                logger.critical(ErrorCode.ADDON_CONTENT_GRANT_INVALID, `Addon '${namespace}' grants content under '${prefix}', but '${first ?? ''}' is not the content bucket of any wired addon. Buckets: ${Array.from(buckets).join(', ')}`);
             }
         }
     }
@@ -432,8 +458,8 @@ export function validateCredentialOverrides(logger, state) {
         return;
     const credentialNames = new Set(state.credentials?.definitions.map((d) => d.name) ?? []);
     /** Only a rename has a target to check; a mode-only override renames nothing. */
-    const renameTarget = (override) => typeof override === "string" ? override : override.name;
-    const overrideMode = (override) => typeof override === "string" ? undefined : override.mode;
+    const renameTarget = (override) => typeof override === 'string' ? override : override.name;
+    const overrideMode = (override) => typeof override === 'string' ? undefined : override.mode;
     /**
      * Which declaration set each resolved name's mode. Credential generation
      * writes one shared metadata entry per name, so two declarations that map
@@ -450,8 +476,10 @@ export function validateCredentialOverrides(logger, state) {
             const resolvedName = renamed ?? logicalName;
             if (!credentialNames.has(resolvedName)) {
                 const availableCredentials = Array.from(credentialNames);
-                const target = renamed ? `'${logicalName}' -> '${resolvedName}'` : `'${logicalName}'`;
-                logger.critical(ErrorCode.INVALID_VALUE, `Credential override ${target} in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(", ") || "none"}`);
+                const target = renamed
+                    ? `'${logicalName}' -> '${resolvedName}'`
+                    : `'${logicalName}'`;
+                logger.critical(ErrorCode.INVALID_VALUE, `Credential override ${target} in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
             }
             const mode = overrideMode(override);
             if (!mode)
@@ -467,7 +495,7 @@ export function validateCredentialOverrides(logger, state) {
             const resolvedName = (override ? renameTarget(override) : undefined) ?? logicalName;
             if (!credentialNames.has(resolvedName)) {
                 const availableCredentials = Array.from(credentialNames);
-                logger.critical(ErrorCode.INVALID_VALUE, `Credential grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(", ") || "none"}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `Credential grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
             }
         }
     }
@@ -485,7 +513,7 @@ export function validateVariableOverrides(logger, state) {
         for (const [logicalName, resolvedName] of Object.entries(addonDecl.variableOverrides)) {
             if (!variableIds.has(resolvedName)) {
                 const availableVariables = Array.from(variableIds);
-                logger.critical(ErrorCode.INVALID_VALUE, `Variable override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a variable that does not exist. Available variables: ${availableVariables.join(", ") || "none"}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `Variable override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a variable that does not exist. Available variables: ${availableVariables.join(', ') || 'none'}`);
             }
         }
     }
@@ -501,11 +529,11 @@ export function validateVariableOverrides(logger, state) {
  * attempt means it is genuinely absent.
  */
 const isPackageResolvable = (pkg, dirs) => {
-    const NOT_FOUND = new Set(["MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND"]);
+    const NOT_FOUND = new Set(['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND']);
     for (const dir of dirs) {
         let req;
         try {
-            req = createRequire(join(dir, "package.json"));
+            req = createRequire(join(dir, 'package.json'));
         }
         catch {
             return true; // cannot ask; do not accuse
@@ -559,7 +587,7 @@ export function validateRemoteAddonDependencies(logger, state) {
         const dirs = addonResolutionDirs(state.rootDir, decl.file);
         if (isPackageResolvable(decl.package, dirs))
             continue;
-        logger.critical(ErrorCode.ADDON_NOT_INSTALLED, `Addon '${namespace}' ('${decl.package}') is wired with wireAddon but cannot be resolved from ${dirs.join(" or ")} — every ref('${namespace}:…') will resolve to nothing and the surface will be dead at runtime. Add it to the dependencies of ${join(dirs[0], "package.json")} and install, or remove the wireAddon call.`);
+        logger.critical(ErrorCode.ADDON_NOT_INSTALLED, `Addon '${namespace}' ('${decl.package}') is wired with wireAddon but cannot be resolved from ${dirs.join(' or ')} — every ref('${namespace}:…') will resolve to nothing and the surface will be dead at runtime. Add it to the dependencies of ${join(dirs[0], 'package.json')} and install, or remove the wireAddon call.`);
     }
     // A remote addon belongs in the devDependencies of the package that wires
     // it, which in a workspace is not the root.
@@ -570,7 +598,7 @@ export function validateRemoteAddonDependencies(logger, state) {
         let manifest = null;
         if (existsSync(path)) {
             try {
-                manifest = JSON.parse(readFileSync(path, "utf-8"));
+                manifest = JSON.parse(readFileSync(path, 'utf-8'));
             }
             catch (e) {
                 logger.warn(`Could not read ${path} to verify remote addon dependencies: ${e?.message ?? e}`);
@@ -582,7 +610,7 @@ export function validateRemoteAddonDependencies(logger, state) {
     for (const [namespace, decl] of wireAddonDeclarations.entries()) {
         if (!decl.remote)
             continue;
-        const pkgJsonPath = join(addonResolutionDirs(state.rootDir, decl.file)[0], "package.json");
+        const pkgJsonPath = join(addonResolutionDirs(state.rootDir, decl.file)[0], 'package.json');
         const pkgJson = readManifest(pkgJsonPath);
         if (!pkgJson)
             continue; // no manifest to check (e.g. some tests)
@@ -614,10 +642,10 @@ export function validateRemoteAddonAuth(logger, state) {
         if (!decl.remote)
             continue;
         if (decl.authCredentialId && !credentialNames.has(decl.authCredentialId)) {
-            logger.critical(ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED, `Remote addon '${namespace}' binds auth.credentialId '${decl.authCredentialId}', but no such credential is wired. Available credentials: ${Array.from(credentialNames).join(", ") || "none"}`);
+            logger.critical(ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED, `Remote addon '${namespace}' binds auth.credentialId '${decl.authCredentialId}', but no such credential is wired. Available credentials: ${Array.from(credentialNames).join(', ') || 'none'}`);
         }
         if (decl.authSecretId && !secretNames.has(decl.authSecretId)) {
-            logger.critical(ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED, `Remote addon '${namespace}' binds auth.secretId '${decl.authSecretId}', but no such secret is wired. Available secrets: ${Array.from(secretNames).join(", ") || "none"}`);
+            logger.critical(ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED, `Remote addon '${namespace}' binds auth.secretId '${decl.authSecretId}', but no such secret is wired. Available secrets: ${Array.from(secretNames).join(', ') || 'none'}`);
         }
     }
 }
@@ -626,7 +654,7 @@ export function computeResolvedIOTypes(state) {
     for (const [pikkuFuncId, meta] of Object.entries(functions.meta)) {
         const input = meta.inputs?.[0];
         const output = meta.outputs?.[0];
-        let inputType = "null";
+        let inputType = 'null';
         if (input) {
             try {
                 inputType = functions.typesMap.getTypeMeta(input).uniqueName;
@@ -635,7 +663,7 @@ export function computeResolvedIOTypes(state) {
                 inputType = input;
             }
         }
-        let outputType = "null";
+        let outputType = 'null';
         if (output) {
             try {
                 outputType = functions.typesMap.getTypeMeta(output).uniqueName;
@@ -645,10 +673,10 @@ export function computeResolvedIOTypes(state) {
             }
         }
         state.resolvedIOTypes[pikkuFuncId] = { inputType, outputType };
-        if (meta.inputSchemaName && inputType !== "null") {
+        if (meta.inputSchemaName && inputType !== 'null') {
             meta.inputSchemaName = inputType;
         }
-        if (meta.outputSchemaName && outputType !== "null") {
+        if (meta.outputSchemaName && outputType !== 'null') {
             meta.outputSchemaName = outputType;
         }
         if (meta.inputs) {
@@ -710,15 +738,15 @@ export function computePermissionsGroupsMeta(state) {
     };
 }
 const PRIMITIVE_TYPES = new Set([
-    "boolean",
-    "string",
-    "number",
-    "null",
-    "undefined",
-    "void",
-    "any",
-    "unknown",
-    "never",
+    'boolean',
+    'string',
+    'number',
+    'null',
+    'undefined',
+    'void',
+    'any',
+    'unknown',
+    'never',
 ]);
 export function computeRequiredSchemas(state, options) {
     const { functions, schemaLookup } = state;
@@ -779,8 +807,8 @@ export function unresolvedSchemaReferences(state) {
     };
     for (const [funcName, meta] of Object.entries(functions.meta)) {
         for (const [role, declared] of [
-            ["input", meta.inputs?.[0]],
-            ["output", meta.outputs?.[0]],
+            ['input', meta.inputs?.[0]],
+            ['output', meta.outputs?.[0]],
         ]) {
             if (!declared || PRIMITIVE_TYPES.has(declared))
                 continue;
@@ -797,12 +825,12 @@ export function validateSchemaReferences(logger, state) {
     if (unresolved.length === 0)
         return;
     logger.diagnostic({
-        severity: "error",
+        severity: 'error',
         code: ErrorCode.SCHEMA_REFERENCE_UNRESOLVED,
-        message: `${unresolved.length} function contract${unresolved.length === 1 ? "" : "s"} ` +
-            `name${unresolved.length === 1 ? "s" : ""} a schema that was never generated, so ` +
-            `calling ${unresolved.length === 1 ? "it" : "them"} fails at runtime with ` +
-            `MissingSchemaError: ${unresolved.join(", ")}. ` +
+        message: `${unresolved.length} function contract${unresolved.length === 1 ? '' : 's'} ` +
+            `name${unresolved.length === 1 ? 's' : ''} a schema that was never generated, so ` +
+            `calling ${unresolved.length === 1 ? 'it' : 'them'} fails at runtime with ` +
+            `MissingSchemaError: ${unresolved.join(', ')}. ` +
             `The usual cause is a named type used as the function's input/output that ` +
             `is declared but not exported — export it, or inline the type at the call site.`,
     });
@@ -821,11 +849,11 @@ export function validateAgentModels(logger, state, modelAliases = {}) {
         // `hasOwn`, not a truthy lookup: every object literal inherits `toString`,
         // `constructor` and `__proto__`, so a bare model named after one of them
         // would read as a configured alias and pass a check nothing else repeats.
-        if (!model.includes("/") && !Object.hasOwn(modelAliases, model)) {
+        if (!model.includes('/') && !Object.hasOwn(modelAliases, model)) {
             const known = Object.keys(modelAliases).sort();
             logger.critical(ErrorCode.INVALID_MODEL, `AI agent '${meta.name}' uses model '${model}', which is neither provider-qualified as '<provider>/<model>' (e.g. 'openai/gpt-4') nor an alias in the "models" table of pikku.config.json. ` +
                 (known.length
-                    ? `Known aliases: ${known.join(", ")}.`
+                    ? `Known aliases: ${known.join(', ')}.`
                     : `No "models" aliases are configured.`));
         }
     }
@@ -833,7 +861,7 @@ export function validateAgentModels(logger, state, modelAliases = {}) {
 /**
  * Scenarios are pure stories of remote RPCs (same rule as client-side CLI
  * renderers): the func may only destructure logger/config — everything else
- * must go through actor steps so the flow runs against the TARGET
+ * must go through virtual user steps so the flow runs against the TARGET
  * environment, never local services.
  *
  * This runs in post-processing rather than in `addWorkflow` because
@@ -848,30 +876,30 @@ export function validateScenarioServices(logger, state) {
         const funcMeta = state.functions.meta[meta.pikkuFuncId];
         if (!funcMeta?.services)
             continue;
-        const disallowed = funcMeta.services.services.filter((svc) => svc !== "logger" && svc !== "config");
+        const disallowed = funcMeta.services.services.filter((svc) => svc !== 'logger' && svc !== 'config');
         if (disallowed.length > 0) {
-            logger.critical(ErrorCode.SCENARIO_HAS_SERVICES, `Scenario '${workflowName}' destructures services: ${disallowed.join(", ")}. ` +
+            logger.critical(ErrorCode.SCENARIO_HAS_SERVICES, `Scenario '${workflowName}' destructures services: ${disallowed.join(', ')}. ` +
                 `Scenarios may only use 'logger'/'config' — drive everything else through ` +
-                `actor steps (workflow.do(step, rpc, data, { actor: actors.x })) so the flow ` +
+                `virtualUser steps (workflow.do(step, rpc, data, { virtualUser: virtualUsers.x })) so the flow ` +
                 `runs against the target environment.`);
         }
     }
 }
 /**
- * Does this step's prose open by naming the actor who is already its subject?
+ * Does this step's prose open by naming the virtual user who is already its subject?
  *
- * `composeStepProse` renders the actor as the sentence's subject, so a step
+ * `composeStepProse` renders the virtual user as the sentence's subject, so a step
  * authored as `'sam' creates the client` reads "Given sam 'sam' creates the
- * client". Only the subject position counts: a persona keyed after a role noun
+ * client". Only the subject position counts: a virtual user keyed after a role noun
  * ("admin") must still be able to say "creates the admin client", and naming
  * someone mid-sentence — "sends sam an invite" — is ordinary prose.
  */
-export const proseOpensWithActor = (prose, actor) => {
-    if (!actor) {
+export const proseOpensWithVirtualUser = (prose, virtualUser) => {
+    if (!virtualUser) {
         return false;
     }
-    const escaped = actor.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(`^["'“‘\\s]*${escaped}(?:['’]s)?\\b`, "i").test(prose);
+    const escaped = virtualUser.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^["'“‘\\s]*${escaped}(?:['’]s)?\\b`, 'i').test(prose);
 };
 /**
  * The prose that will actually render for one step, in the runtime's own
@@ -879,39 +907,43 @@ export const proseOpensWithActor = (prose, actor) => {
  * overrides its declared description, which falls back to the durable name.
  *
  * Every candidate is returned rather than only the winner, because a template
- * is authored where the actor is not yet known — so it is wrong at every call
- * site that runs it as the persona it names, not just the winning one.
+ * is authored where the virtual user is not yet known — so it is wrong at every call
+ * site that runs it as the virtual user it names, not just the winning one.
  */
 const renderableProse = (step, stepMeta) => {
     const description = step.options?.description;
     if (description) {
         return [step.stepName, description];
     }
-    return [step.stepName, stepMeta?.scenarioStepTemplate, stepMeta?.description].filter((prose) => typeof prose === "string");
+    return [
+        step.stepName,
+        stepMeta?.scenarioStepTemplate,
+        stepMeta?.description,
+    ].filter((prose) => typeof prose === 'string');
 };
 /**
- * A step's prose must not open by naming the actor it already runs as (PKU681).
+ * A step's prose must not open by naming the virtual user it already runs as (PKU681).
  *
- * The reporter renders the actor as the sentence's subject, so `'sam' creates
- * the client` run as `actors.sam` reads "Given sam 'sam' creates the client" —
+ * The reporter renders the virtual user as the sentence's subject, so `'sam' creates
+ * the client` run as `virtualUsers.sam` reads "Given sam 'sam' creates the client" —
  * and the hardcoded copy silently desyncs the moment the call site changes
- * actor. Only the subject position is refused; naming someone mid-sentence is
- * ordinary prose, and a persona keyed after a role noun can still say "creates
+ * virtual user. Only the subject position is refused; naming someone mid-sentence is
+ * ordinary prose, and a virtual user keyed after a role noun can still say "creates
  * the admin client".
  */
 const validateStepProse = (logger, workflowName, step, stepMeta) => {
-    const actor = step.actor;
-    if (!actor) {
+    const virtualUser = step.virtualUser;
+    if (!virtualUser) {
         return;
     }
-    const offender = renderableProse(step, stepMeta).find((prose) => proseOpensWithActor(prose, actor));
+    const offender = renderableProse(step, stepMeta).find((prose) => proseOpensWithVirtualUser(prose, virtualUser));
     if (offender === undefined) {
         return;
     }
-    logger.critical(ErrorCode.SCENARIO_STEP_PROSE_NAMES_ACTOR, `Scenario '${workflowName}' names its actor in the step prose: '${offender}' runs as '${actor}'. ` +
-        `The reporter already renders the actor as the subject, so this reads ` +
-        `"${capitaliseFirst(step.phase)} ${actor} ${offender}". Drop the name and let ` +
-        `{ actor: actors.${actor} } supply it — the step reads as a bare third-person predicate.`);
+    logger.critical(ErrorCode.SCENARIO_STEP_PROSE_NAMES_VIRTUAL_USER, `Scenario '${workflowName}' names its virtual user in the step prose: '${offender}' runs as '${virtualUser}'. ` +
+        `The reporter already renders the virtual user as the subject, so this reads ` +
+        `"${capitaliseFirst(step.phase)} ${virtualUser} ${offender}". Drop the name and let ` +
+        `{ virtualUser: virtualUsers.${virtualUser} } supply it — the step reads as a bare third-person predicate.`);
 };
 const capitaliseFirst = (value) => value.charAt(0).toUpperCase() + value.slice(1);
 /**
@@ -921,9 +953,9 @@ const capitaliseFirst = (value) => value.charAt(0).toUpperCase() + value.slice(1
  *
  * - the step target must be a static string literal (PKU678) — otherwise it
  *   can't be bundled, typed or drawn;
- * - a step that runs as a persona must be given one (PKU677) — declared by
- *   `actor: true`, or implied by a `browser` binding, since the browser context
- *   signs in as that persona. It is checked statically even though a browser
+ * - a step that runs as a virtual user must be given one (PKU677) — declared by
+ *   `virtualUser: true`, or implied by a `browser` binding, since the browser context
+ *   signs in as that virtual user. It is checked statically even though a browser
  *   binding only runs on a browser run: a step that can never be driven by a
  *   human is a latent failure, not a passing default run.
  * - a scenario written as a step ladder must assert something (PKU680).
@@ -935,7 +967,7 @@ export function validateScenarioSteps(logger, state) {
     const phasesSeen = new Set();
     const visit = (workflowName, steps) => {
         for (const step of steps) {
-            if (step.type === "scenarioStep") {
+            if (step.type === 'scenarioStep') {
                 phasesSeen.add(step.phase);
                 if (step.stepFunc === DYNAMIC_SCENARIO_STEP_TARGET) {
                     logger.critical(ErrorCode.SCENARIO_STEP_TARGET_NOT_STATIC, `Scenario '${workflowName}' calls step '${step.stepName}' with a target that isn't a string literal. ` +
@@ -946,22 +978,22 @@ export function validateScenarioSteps(logger, state) {
                 state.serviceAggregation.usedFunctions.add(step.stepFunc);
                 const stepMeta = state.functions.meta[step.stepFunc];
                 validateStepProse(logger, workflowName, step, stepMeta);
-                if (stepMeta?.scenarioStepRequiresActor && !step.actor) {
-                    const why = stepMeta.scenarioStepSurfaces?.includes("browser")
-                        ? "declares a browser binding"
-                        : "is driven by a persona";
-                    logger.critical(ErrorCode.SCENARIO_STEP_NEEDS_ACTOR, `Scenario '${workflowName}' calls step '${step.stepFunc}', which ${why}, without an actor. ` +
-                        `Pass { actor: actors.<name> } so it runs as that persona.`);
+                if (stepMeta?.scenarioStepRequiresVirtualUser && !step.virtualUser) {
+                    const why = stepMeta.scenarioStepSurfaces?.includes('browser')
+                        ? 'declares a browser binding'
+                        : 'is driven by a virtual user';
+                    logger.critical(ErrorCode.SCENARIO_STEP_NEEDS_VIRTUAL_USER, `Scenario '${workflowName}' calls step '${step.stepFunc}', which ${why}, without a virtual user. ` +
+                        `Pass { virtualUser: virtualUsers.<name> } so it runs as that virtual user.`);
                 }
                 continue;
             }
-            if (step.type === "branch") {
+            if (step.type === 'branch') {
                 for (const branch of step.branches)
                     visit(workflowName, branch.steps);
                 if (step.elseSteps)
                     visit(workflowName, step.elseSteps);
             }
-            else if (step.type === "switch") {
+            else if (step.type === 'switch') {
                 for (const c of step.cases ?? []) {
                     if (c.steps)
                         visit(workflowName, c.steps);
@@ -969,10 +1001,10 @@ export function validateScenarioSteps(logger, state) {
                 if (step.defaultSteps)
                     visit(workflowName, step.defaultSteps);
             }
-            else if (step.type === "fanout" && step.body) {
+            else if (step.type === 'fanout' && step.body) {
                 visit(workflowName, step.body);
             }
-            else if (step.type === "parallel" && step.children) {
+            else if (step.type === 'parallel' && step.children) {
                 visit(workflowName, step.children);
             }
         }
@@ -987,9 +1019,9 @@ export function validateScenarioSteps(logger, state) {
         // `asserts` is the escape for a flow whose witness is an expectation helper
         // instead: those are inline steps and leave no phase behind, but a recorded
         // service call or a refusal is an assertion all the same.
-        if (phasesSeen.size > 0 && !phasesSeen.has("then") && !meta.asserts) {
-            logger.critical(ErrorCode.SCENARIO_HAS_NO_ASSERTION, `Scenario '${workflowName}' has ${[...phasesSeen].join("/")} steps but never asserts. ` +
-                `Add a scenario.then(...) naming what the actor should now see — a flow with no 'then' ` +
+        if (phasesSeen.size > 0 && !phasesSeen.has('then') && !meta.asserts) {
+            logger.critical(ErrorCode.SCENARIO_HAS_NO_ASSERTION, `Scenario '${workflowName}' has ${[...phasesSeen].join('/')} steps but never asserts. ` +
+                `Add a scenario.then(...) naming what the virtual user should now see — a flow with no 'then' ` +
                 `only proves nothing threw, and contributes nothing to witness coverage.`);
         }
     }
@@ -1049,17 +1081,17 @@ export function validateScenarioFeatures(logger, state) {
         .map((feature) => feature.exportedName);
     if (unreadable.length > 0) {
         logger.diagnostic({
-            severity: "warn",
+            severity: 'warn',
             code: ErrorCode.SCENARIO_HAS_NO_FEATURE,
-            message: `${unowned.map((name) => `'${name}'`).join(", ")} appear in no feature's \`scenarios\` array, ` +
-                `but ${unreadable.map((name) => `'${name}'`).join(", ")} build theirs with a spread or a call, so one of them may still be listed there. ` +
+            message: `${unowned.map((name) => `'${name}'`).join(', ')} appear in no feature's \`scenarios\` array, ` +
+                `but ${unreadable.map((name) => `'${name}'`).join(', ')} build theirs with a spread or a call, so one of them may still be listed there. ` +
                 `List those scenarios literally and this becomes a definite answer either way.`,
         });
         return;
     }
     for (const name of unowned) {
         logger.diagnostic({
-            severity: "error",
+            severity: 'error',
             code: ErrorCode.SCENARIO_HAS_NO_FEATURE,
             message: `Scenario '${name}' is listed by no pikkuFeature, so nothing downstream can reach it — ` +
                 `a run stamps no feature onto its results, the console groups it under none, and a guide cannot cite it. ` +
@@ -1074,16 +1106,16 @@ export function validateScenarioFeatures(logger, state) {
  * early with an actionable message pointing at `scaffold: { graph: true }`.
  */
 export function validateWorkflowGraphAddons(logger, state) {
-    const addonGraphWired = Array.from(state.rpc.wireAddonDeclarations.values()).some((decl) => decl.package === "@pikku/addon-graph");
+    const addonGraphWired = Array.from(state.rpc.wireAddonDeclarations.values()).some((decl) => decl.package === '@pikku/addon-graph');
     if (addonGraphWired) {
         return;
     }
     for (const [name, graph] of Object.entries(state.workflows.graphMeta)) {
         for (const node of Object.values(graph.nodes)) {
-            if (!("rpcName" in node) || typeof node.rpcName !== "string") {
+            if (!('rpcName' in node) || typeof node.rpcName !== 'string') {
                 continue;
             }
-            if (!node.rpcName.startsWith("graph:")) {
+            if (!node.rpcName.startsWith('graph:')) {
                 continue;
             }
             if (state.functions.meta[node.rpcName]) {
@@ -1133,7 +1165,7 @@ export function validateSchemaWiringSeparation(logger, state) {
             const schemas = Array.from(state.schemaLookup.entries())
                 .filter(([, ref]) => ref.sourceFile === file)
                 .map(([name]) => name);
-            logger.critical(ErrorCode.SCHEMA_AND_WIRING_COLOCATED, `File '${file}' contains both Zod schemas (${schemas.join(", ")}) and wiring calls (wireHTTPRoutes, addPermission, etc.). ` +
+            logger.critical(ErrorCode.SCHEMA_AND_WIRING_COLOCATED, `File '${file}' contains both Zod schemas (${schemas.join(', ')}) and wiring calls (wireHTTPRoutes, addPermission, etc.). ` +
                 `These must be in separate files because the CLI imports schema files at runtime, which triggers wiring side-effects that crash without server context. ` +
                 `Move the route/wiring definitions to a dedicated wiring file.`);
         }
@@ -1147,15 +1179,8 @@ export function validateSchemaWiringSeparation(logger, state) {
  * a name the omit does not cover. A name-based rule misses this; the type does
  * not.
  */
-export function validateNoSecretAliasServices(logger, checker, state) {
-    if (!("typesLookup" in state)) {
-        return;
-    }
-    const singletonServicesType = resolveCoreType(state.typesLookup, state.singletonServicesTypeImportMap);
-    if (!singletonServicesType) {
-        return;
-    }
-    const aliases = findSecretAliasServices(singletonServicesType, checker);
+export function validateNoSecretAliasServices(logger, state) {
+    const aliases = state.serviceTypes?.secretAliases ?? [];
     if (aliases.length === 0) {
         return;
     }
@@ -1164,14 +1189,14 @@ export function validateNoSecretAliasServices(logger, checker, state) {
         if (used.length === 0) {
             return;
         }
-        logger.critical(ErrorCode.SECRET_SERVICE_ALIASED, `${kind} '${id}' receives ${used.map((s) => `'${s}'`).join(", ")}, which ${used.length === 1 ? "is" : "are"} a SecretService under another name. ` +
+        logger.critical(ErrorCode.SECRET_SERVICE_ALIASED, `${kind} '${id}' receives ${used.map((s) => `'${s}'`).join(', ')}, which ${used.length === 1 ? 'is' : 'are'} a SecretService under another name. ` +
             `SecretService is confined to pikkuServices, pikkuWireServices, addon service factories and middleware — give a service the secret value when you construct it and expose only what the function needs.`);
     };
     for (const [id, meta] of Object.entries(state.functions.meta)) {
-        report("Function", id, meta.services?.services ?? []);
+        report('Function', id, meta.services?.services ?? []);
     }
     for (const [id, def] of Object.entries(state.permissions.definitions)) {
-        report("Permission", id, def.services?.services ?? []);
+        report('Permission', id, def.services?.services ?? []);
     }
 }
 /**
@@ -1200,22 +1225,22 @@ export function validateSecretUsage(logger, state) {
     // auth-secrets.gen.ts declares it, but that file is written after the first
     // inspection of a fresh project, so its defineSecret is not seen yet.
     if (state.auth?.definition)
-        declared.add("BETTER_AUTH_SECRET");
+        declared.add('BETTER_AUTH_SECRET');
     for (const [file, usage] of state.secrets.usage) {
         const relativeFile = relative(state.rootDir, file);
         const undeclared = usage.keys.filter((key) => !declared.has(key));
         if (undeclared.length > 0) {
             logger.diagnostic({
-                severity: "warn",
+                severity: 'warn',
                 code: ErrorCode.SECRET_NOT_DECLARED,
-                message: `${relativeFile} reads ${undeclared.map((k) => `'${k}'`).join(", ")}, which no defineSecret declares. Declare it so it is validated at deploy time and shown to whoever has to provision it.`,
+                message: `${relativeFile} reads ${undeclared.map((k) => `'${k}'`).join(', ')}, which no defineSecret declares. Declare it so it is validated at deploy time and shown to whoever has to provision it.`,
             });
         }
         if (usage.dynamic.length > 0) {
             logger.diagnostic({
-                severity: "warn",
+                severity: 'warn',
                 code: ErrorCode.SECRET_KEY_NOT_STATIC,
-                message: `${relativeFile} reads a secret with a non-literal key (${usage.dynamic.join(", ")}). The deployment cannot narrow its secret scope around a key it cannot see.`,
+                message: `${relativeFile} reads a secret with a non-literal key (${usage.dynamic.join(', ')}). The deployment cannot narrow its secret scope around a key it cannot see.`,
             });
         }
     }
@@ -1229,9 +1254,9 @@ export function computeDiagnostics(state) {
         // source file). The user can't edit any of these, so a destructure lint
         // meant to nudge them about their own code must not fail the build over them.
         if (!meta.sourceFile ||
-            meta.sourceFile.endsWith(".gen.ts") ||
-            meta.functionType === "inline" ||
-            meta.functionType === "helper") {
+            meta.sourceFile.endsWith('.gen.ts') ||
+            meta.functionType === 'inline' ||
+            meta.functionType === 'helper') {
             continue;
         }
         if (meta.services && !meta.services.optimized) {
@@ -1311,14 +1336,14 @@ export function validateScopeReferences(logger, state) {
             continue;
         for (const scope of meta.scopes) {
             // A trailing wildcard grants a subtree; the node it hangs off must exist.
-            const declaredForm = scope.endsWith(":*") ? scope.slice(0, -2) : scope;
-            if (scope === "*") {
+            const declaredForm = scope.endsWith(':*') ? scope.slice(0, -2) : scope;
+            if (scope === '*') {
                 logger.critical(ErrorCode.INVALID_VALUE, `Function '${funcName}' requires the bare wildcard scope '*'. A function must require a specific scope — '*' is only meaningful as a grant.`);
                 continue;
             }
             if (!declared.has(declaredForm)) {
                 const available = Array.from(declared);
-                logger.critical(ErrorCode.INVALID_VALUE, `Function '${funcName}' requires scope '${scope}' which is not declared. Declare it with defineScope. Available scopes: ${available.join(", ") || "none"}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `Function '${funcName}' requires scope '${scope}' which is not declared. Declare it with defineScope. Available scopes: ${available.join(', ') || 'none'}`);
             }
         }
     }
@@ -1345,12 +1370,12 @@ export function validateAgentToolReferences(logger, state, options = {}) {
         return;
     const { wireAddonDeclarations } = state.rpc;
     for (const [agentKey, agent] of agents) {
-        const where = agent.sourceFile ? ` (${agent.sourceFile})` : "";
+        const where = agent.sourceFile ? ` (${agent.sourceFile})` : '';
         for (const tool of agent.tools ?? []) {
             // A workflow reference is resolved against the workflow map, not here.
-            if (tool.startsWith("workflow:"))
+            if (tool.startsWith('workflow:'))
                 continue;
-            const separator = tool.indexOf(":");
+            const separator = tool.indexOf(':');
             let meta;
             if (separator === -1) {
                 const funcId = state.rpc.internalMeta[tool] ?? tool;
@@ -1367,7 +1392,7 @@ export function validateAgentToolReferences(logger, state, options = {}) {
                 if (!addon) {
                     const known = Array.from(wireAddonDeclarations?.keys() ?? []);
                     logger.critical(ErrorCode.AGENT_TOOL_UNKNOWN_NAMESPACE, `AI agent '${agentKey}'${where} references tool '${tool}', but no addon is wired under the namespace '${namespace}'. ` +
-                        `Wired namespaces: ${known.join(", ") || "none"}.`);
+                        `Wired namespaces: ${known.join(', ') || 'none'}.`);
                     continue;
                 }
                 // An addon that has not been built yet contributed no metadata, which
@@ -1384,7 +1409,7 @@ export function validateAgentToolReferences(logger, state, options = {}) {
             if (options.strictMeta && !meta.description) {
                 logger.critical(ErrorCode.AGENT_TOOL_MISSING_DESCRIPTION, `AI agent '${agentKey}'${where} uses tool '${tool}', which has no description. ` +
                     `An agent tool's description is what the model is told it does; without one it is offered the tool under its own name. ` +
-                    `Add a 'description' to '${tool}'${meta.title ? " (a 'title' does not count — it labels the tool, it does not explain it)" : ""}.`);
+                    `Add a 'description' to '${tool}'${meta.title ? " (a 'title' does not count — it labels the tool, it does not explain it)" : ''}.`);
             }
         }
     }
@@ -1399,12 +1424,12 @@ export function validateAgentToolReferences(logger, state, options = {}) {
 export function validateAgentScorerReferences(logger, state) {
     const known = Object.keys(state.scorers.scorersMeta);
     for (const [agentKey, agent] of Object.entries(state.agents.agentsMeta)) {
-        const where = agent.sourceFile ? ` (${agent.sourceFile})` : "";
+        const where = agent.sourceFile ? ` (${agent.sourceFile})` : '';
         for (const scorer of agent.scorers ?? []) {
             if (known.includes(scorer))
                 continue;
             logger.critical(ErrorCode.AGENT_SCORER_NOT_FOUND, `AI agent '${agentKey}'${where} asks to be graded by scorer '${scorer}', which is not declared in this project. ` +
-                `Declared scorers: ${known.join(", ") || "none"}.`);
+                `Declared scorers: ${known.join(', ') || 'none'}.`);
         }
     }
 }
@@ -1415,7 +1440,7 @@ export function validateAgentScorerReferences(logger, state) {
  * The same rule functions get, for a sharper reason: a role granting an
  * undeclared scope is not merely useless, it is *invisibly* useless. No
  * function checks the scope, so the role appears to work — every call a
- * persona holding it makes succeeds or fails for unrelated reasons, and the
+ * virtual user holding it makes succeeds or fails for unrelated reasons, and the
  * authorization boundary it was written to describe is never exercised.
  *
  * A `*` suffix grants a subtree; the node it hangs off must exist.
@@ -1427,41 +1452,41 @@ export function validateSystemRoleScopes(logger, state) {
     const declared = new Set(flattenScopeDefinitions(state.scopes.definitions).map((s) => s.id));
     for (const role of state.systemRoles.definitions) {
         for (const scope of role.scopes) {
-            if (scope === "*") {
+            if (scope === '*') {
                 logger.critical(ErrorCode.INVALID_VALUE, `System role '${role.name}' grants the bare wildcard scope '*'. Grant the roots it should cover instead — '*' hides what the role actually confers.`);
                 continue;
             }
-            const declaredForm = scope.endsWith(":*") ? scope.slice(0, -2) : scope;
+            const declaredForm = scope.endsWith(':*') ? scope.slice(0, -2) : scope;
             if (!declared.has(declaredForm)) {
                 const available = Array.from(declared);
-                logger.critical(ErrorCode.INVALID_VALUE, `System role '${role.name}' grants scope '${scope}' which is not declared. Declare it with defineScope. Available scopes: ${available.join(", ") || "none"}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `System role '${role.name}' grants scope '${scope}' which is not declared. Declare it with defineScope. Available scopes: ${available.join(', ') || 'none'}`);
             }
         }
     }
 }
 /**
- * Validates that every role a persona names is declared with
+ * Validates that every role a virtual user names is declared with
  * `defineSystemRole`. Runs after all visitors, so declaration order does not
  * matter.
  *
  * Custom roles are refused rather than tolerated. A role composed in the
  * console does not exist at build time and can be deleted after it, so a
- * persona pinned to one silently stops testing what it claims to — and the
+ * virtual user pinned to one silently stops testing what it claims to — and the
  * symptom is a scatter of 403s that read like authorization findings rather
  * than like a deleted role.
  */
-export function validatePersonaRoles(logger, state) {
-    if (!state.personas.definitions.length) {
+export function validateVirtualUserRoles(logger, state) {
+    if (!state.virtualUsers.definitions.length) {
         return;
     }
     const declared = new Set(state.systemRoles.definitions.map((r) => r.name));
-    for (const persona of state.personas.definitions) {
-        for (const role of persona.roles) {
+    for (const virtualUser of state.virtualUsers.definitions) {
+        for (const role of virtualUser.roles) {
             if (!declared.has(role)) {
                 const available = Array.from(declared).sort();
-                logger.critical(ErrorCode.INVALID_VALUE, `Persona '${persona.id}' holds role '${role}', which is not declared with defineSystemRole. ` +
-                    `A persona may only name a system role — a role composed in the console can be deleted, and the persona would go on claiming to test it. ` +
-                    `Declared roles: ${available.join(", ") || "none"}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `VirtualUser '${virtualUser.id}' holds role '${role}', which is not declared with defineSystemRole. ` +
+                    `A virtual user may only name a system role — a role composed in the console can be deleted, and the virtual user would go on claiming to test it. ` +
+                    `Declared roles: ${available.join(', ') || 'none'}`);
             }
         }
     }