@pikku/cli 0.12.92 → 0.12.96

package/dist/src/functions/wirings/personas/serialize-personas-types.d.ts

@@ -0,0 +1,18 @@
+import type { PersonaDefinitions } from '@pikku/core/persona';
+export interface SerializePersonasOptions {
+    definitions: PersonaDefinitions;
+    /** Relative import path to the generated roles file. */
+    rolesImportPath: string;
+    /** Keys of `environments` in pikku.config.json. */
+    environmentNames: string[];
+}
+/**
+ * Generates the `PersonaId` union and a `definePersonas` whose `roles` are
+ * checked against the declared system roles.
+ *
+ * The wrapper is why this is generated rather than re-exported: `roles` typed
+ * as `string[]` would let a persona name a role nobody declared, and the
+ * failure — a scatter of 403s in a run days later — looks nothing like the
+ * mistake. Typed as `SystemRoleName[]`, it is a red squiggle in the editor.
+ */
+export declare const serializePersonasTypes: ({ definitions, rolesImportPath, environmentNames, }: SerializePersonasOptions) => string;

package/dist/src/functions/wirings/personas/serialize-personas-types.js

@@ -0,0 +1,76 @@
+const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
+/**
+ * Generates the `PersonaId` union and a `definePersonas` whose `roles` are
+ * checked against the declared system roles.
+ *
+ * The wrapper is why this is generated rather than re-exported: `roles` typed
+ * as `string[]` would let a persona name a role nobody declared, and the
+ * failure — a scatter of 403s in a run days later — looks nothing like the
+ * mistake. Typed as `SystemRoleName[]`, it is a red squiggle in the editor.
+ */
+export const serializePersonasTypes = ({ definitions, rolesImportPath, environmentNames, }) => {
+    const ids = [...new Set(definitions.map((d) => d.id))].sort();
+    const environmentUnion = environmentNames.length > 0
+        ? `\n${[...environmentNames].sort().map((name) => `  | ${quote(name)}`).join('\n')}`
+        : ' never';
+    const union = ids.length > 0
+        ? `\n${ids.map((id) => `  | ${quote(id)}`).join('\n')}`
+        : ' never';
+    const runnable = definitions
+        .filter((d) => d.runnable)
+        .map((d) => d.id)
+        .sort();
+    const runnableUnion = runnable.length > 0
+        ? `\n${runnable.map((id) => `  | ${quote(id)}`).join('\n')}`
+        : ' never';
+    return `/**
+ * This file was generated by the @pikku/cli
+ */
+import { definePersonas as definePersonasCore } from '@pikku/core/persona'
+import type { CorePersona, PersonaMeta, PersonasMeta } from '@pikku/core/persona'
+import type { SystemRoleName } from '${rolesImportPath}'
+import definitions from './pikku-personas-meta.gen.json' with { type: 'json' }
+
+/** Every declared persona. */
+export type PersonaId =${union}
+
+/**
+ * The personas a virtual user can actually be.
+ *
+ * Excludes anyone whose only login is a provider account — driving a consent
+ * screen needs a human — and anyone declared \`runnable: false\`, who exists to
+ * be acted upon rather than to act.
+ */
+export type RunnablePersonaId =${runnableUnion}
+
+/** Every environment configured in pikku.config.json. */
+export type EnvironmentName =${environmentUnion}
+
+/**
+ * A persona whose roles are checked against \`defineSystemRole\` and whose
+ * environments are checked against the config.
+ *
+ * Omitting \`environments\` means every environment except the ones flagged
+ * \`production: true\`. Naming a production one additionally requires
+ * \`disposition: 'accountable'\`, which the type cannot express and \`pikku\`
+ * refuses at build time.
+ */
+export type TypedPersona = Omit<CorePersona, 'roles' | 'environments'> & {
+  roles?: SystemRoleName[]
+  environments?: EnvironmentName[]
+}
+
+/**
+ * Declare the people who use this application.
+ *
+ * A persona while running is a virtual user; there is no second declaration.
+ */
+export const definePersonas = (personas: Record<string, TypedPersona>): void =>
+  definePersonasCore(personas)
+
+/** Declared personas, keyed by id. Read by the console and \`pikku persona\`. */
+export const PERSONAS: PersonasMeta = definitions as unknown as PersonasMeta
+
+export const PERSONA_LIST: PersonaMeta[] = Object.values(PERSONAS)
+`;
+};

package/dist/src/functions/wirings/realtime/pikku-command-events-scaffold.js

@@ -4,6 +4,7 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializeEventsScaffold } from './serialize-events-scaffold.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuEventsScaffold = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
         if (!config.scaffold?.events ||
@@ -15,7 +16,7 @@ export const pikkuEventsScaffold = pikkuSessionlessFunc({
             });
             return false;
         }
-        const authRequired = config.scaffold.events === 'auth';
+        const authRequired = resolveScaffoldFeature('events', config.scaffold.events).auth;
         const pikkuTypesImportPath = getFileImportRelativePath(config.eventsChannelFile, config.typesDeclarationFile, config.packageMappings);
         const { schemas, functions } = serializeEventsScaffold(authRequired, pikkuTypesImportPath);
         await writeFileInDir(logger, config.eventsSchemasFile, schemas);

package/dist/src/functions/wirings/roles/pikku-command-roles.d.ts

@@ -0,0 +1,7 @@
+export declare const pikkuRoles: import("#pikku").PikkuFunctionConfig<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/wirings/roles/pikku-command-roles.js

@@ -0,0 +1,33 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeRolesTypes } from './serialize-roles-types.js';
+import { validateAndBuildSystemRoleDefinitionsMeta } from '@pikku/core/role';
+export const pikkuRoles = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }, data) => {
+        const { rolesFile, rolesMetaJsonFile } = config;
+        if (!rolesFile) {
+            return;
+        }
+        // Same cold-start reasoning as Scopes: on a bare .pikku this runs before
+        // pikku-types.gen.ts exists, so it takes the zero state. The file only has
+        // to exist so personas can import SystemRoleName; the real Roles step
+        // regenerates it with the declarations once setup has run.
+        const bootstrap = data?.bootstrap ?? false;
+        const state = await getInspectorState(false, bootstrap, bootstrap);
+        const content = serializeRolesTypes({
+            definitions: state.systemRoles.definitions,
+        });
+        await writeFileInDir(logger, rolesFile, content);
+        if (rolesMetaJsonFile) {
+            const meta = validateAndBuildSystemRoleDefinitionsMeta(state.systemRoles.definitions);
+            await writeFileInDir(logger, rolesMetaJsonFile, JSON.stringify(meta, null, 2));
+        }
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Creating PikkuRoles types',
+            commandEnd: 'Created PikkuRoles types',
+        }),
+    ],
+});

package/dist/src/functions/wirings/roles/serialize-roles-types.d.ts

@@ -0,0 +1,14 @@
+import type { SystemRoleDefinitions } from '@pikku/core/role';
+export interface SerializeRolesOptions {
+    definitions: SystemRoleDefinitions;
+}
+/**
+ * Generates the `SystemRoleName` union and role metadata from
+ * `defineSystemRole` declarations.
+ *
+ * The union is what makes a persona's `roles: ['buyer']` checkable. Custom
+ * roles are deliberately absent: an admin can delete one from the console, so
+ * a persona pinned to it would silently stop testing what it claims to — the
+ * failure would be a scatter of 403s rather than a build error.
+ */
+export declare const serializeRolesTypes: ({ definitions }: SerializeRolesOptions) => string;

package/dist/src/functions/wirings/roles/serialize-roles-types.js

@@ -0,0 +1,55 @@
+const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
+/**
+ * Generates the `SystemRoleName` union and role metadata from
+ * `defineSystemRole` declarations.
+ *
+ * The union is what makes a persona's `roles: ['buyer']` checkable. Custom
+ * roles are deliberately absent: an admin can delete one from the console, so
+ * a persona pinned to it would silently stop testing what it claims to — the
+ * failure would be a scatter of 403s rather than a build error.
+ */
+export const serializeRolesTypes = ({ definitions }) => {
+    const names = [...new Set(definitions.map((d) => d.name))].sort();
+    const union = names.length > 0
+        ? `\n${names.map((name) => `  | ${quote(name)}`).join('\n')}`
+        : ' never';
+    return `/**
+ * This file was generated by the @pikku/cli
+ */
+import type { SystemRole, SystemRoleDefinitionsMeta } from '@pikku/core/role'
+import { flattenSystemRoleDefinitions } from '@pikku/core/role'
+import definitions from './pikku-roles-meta.gen.json' with { type: 'json' }
+
+/**
+ * Every role that ships with this application.
+ *
+ * Roles an admin composes in the console are not here and cannot be: they do
+ * not exist at build time, and can be deleted after it.
+ */
+export type SystemRoleName =${union}
+
+/**
+ * The declared role set, for a ScopeService to sync into its store.
+ *
+ * Derived from the metadata sidecar rather than inlined, so the import above
+ * forces tsc to emit the .json alongside this file — an addon publishes only
+ * its compiled output, and a host reads that .json to merge the addon's roles
+ * into its own union.
+ *
+ * Additive on removal: a deleted declaration leaves an inert row rather than
+ * revoking everyone's grant on deploy. Use \`pikku roles prune\` to remove them.
+ */
+export const SYSTEM_ROLES: SystemRole[] = flattenSystemRoleDefinitions(
+  Object.values(definitions as SystemRoleDefinitionsMeta)
+)
+
+/** Declared roles, keyed by name. Rendered by the console when granting. */
+export const SYSTEM_ROLES_META: Record<string, SystemRole> = Object.fromEntries(
+  SYSTEM_ROLES.map((role) => [role.name, role])
+)
+
+/** Whether a role name is declared in code, and therefore not editable. */
+export const isSystemRole = (name: string): boolean =>
+  Object.prototype.hasOwnProperty.call(SYSTEM_ROLES_META, name)
+`;
+};

package/dist/src/functions/wirings/rpc/pikku-command-public-rpc.js

@@ -4,6 +4,7 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializePublicRPC } from './serialize-public-rpc.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuPublicRPC = pikkuSessionlessFunc({
     func: async ({ logger, config, variables }) => {
         const deployCodegenFlag = await variables.get('PIKKU_DEPLOY_CODEGEN');
@@ -12,7 +13,7 @@ export const pikkuPublicRPC = pikkuSessionlessFunc({
         }
         if (config.scaffold?.rpc && config.publicRpcSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.publicRpcFile, config.typesDeclarationFile, config.packageMappings);
-            const { schemas, functions } = serializePublicRPC(pathToPikkuTypes, config.scaffold.rpc === 'auth', config.globalHTTPPrefix || '');
+            const { schemas, functions } = serializePublicRPC(pathToPikkuTypes, resolveScaffoldFeature('rpc', config.scaffold.rpc).auth, config.globalHTTPPrefix || '');
             await writeFileInDir(logger, config.publicRpcSchemasFile, schemas);
             await writeFileInDir(logger, config.publicRpcFile, functions);
             await removeLegacyScaffoldFile(config.publicRpcFile);

package/dist/src/functions/wirings/scenarios/register-scenario-instrumentation.d.ts

@@ -3,8 +3,8 @@
  * scenario runner can reach it over `/rpc/<name>` exactly as before.
  *
  * They are registered sessionless: `auth` decides whether a session is
- * *required*, and a sessioned function would demand one regardless of the flag —
- * which is what made `scaffold.scenarios: true` (as opposed to `'auth'`) refuse
- * every call and log a warning about it.
+ * *required*, and a sessioned function would demand one regardless of the flag.
+ * `scaffold.scenarios: true` therefore requires a session; `{ auth: false }` is
+ * what opens them.
  */
 export declare const registerScenarioInstrumentation: (requireAuth: boolean) => void;

package/dist/src/functions/wirings/scenarios/register-scenario-instrumentation.js

@@ -79,9 +79,9 @@ const instrumentation = {
  * scenario runner can reach it over `/rpc/<name>` exactly as before.
  *
  * They are registered sessionless: `auth` decides whether a session is
- * *required*, and a sessioned function would demand one regardless of the flag —
- * which is what made `scaffold.scenarios: true` (as opposed to `'auth'`) refuse
- * every call and log a warning about it.
+ * *required*, and a sessioned function would demand one regardless of the flag.
+ * `scaffold.scenarios: true` therefore requires a session; `{ auth: false }` is
+ * what opens them.
  */
 export const registerScenarioInstrumentation = (requireAuth) => {
     const meta = pikkuState(null, 'function', 'meta');

package/dist/src/functions/wirings/scopes/serialize-scopes-types.d.ts

@@ -3,7 +3,7 @@ export interface SerializeScopesOptions {
     definitions: ScopeDefinitions;
 }
 /**
- * Generates the `ScopeId` union and scope metadata from `wireScope`
+ * Generates the `ScopeId` union and scope metadata from `defineScope`
  * declarations.
  *
  * The union carries every declared node plus a wildcard form for each node that

package/dist/src/functions/wirings/scopes/serialize-scopes-types.js

@@ -1,7 +1,7 @@
 import { flattenScopeDefinitions } from '@pikku/core/scope';
 const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
 /**
- * Generates the `ScopeId` union and scope metadata from `wireScope`
+ * Generates the `ScopeId` union and scope metadata from `defineScope`
  * declarations.
  *
  * The union carries every declared node plus a wildcard form for each node that

package/dist/src/functions/wirings/secrets/serialize-secrets-types.js

@@ -1,5 +1,12 @@
 import { validateAndBuildSecretDefinitionsMeta } from '@pikku/core/secret';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+/**
+ * A display name is the human-facing label a developer wrote, so an apostrophe
+ * in it is ordinary. `JSON.stringify` emits a valid, escaped TypeScript string
+ * literal; interpolating the raw text into a quoted one terminates the string
+ * and the generated file stops parsing.
+ */
+const literal = (value) => JSON.stringify(value);
 export const serializeSecretsTypes = ({ definitions, schemaLookup, secretsFile, packageMappings, }) => {
     const secrets = validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup);
     const credentialEntries = Object.entries(secrets);
@@ -13,8 +20,8 @@ export const serializeSecretsTypes = ({ definitions, schemaLookup, secretsFile,
             needsOAuth2Types = true;
             mapEntries.push(`  '${meta.secretId}': OAuth2AppCredential`);
             mapEntries.push(`  '${meta.oauth2.tokenSecretId}': OAuth2Token`);
-            metaEntries.push(`  '${meta.secretId}': { name: '${name}', displayName: '${meta.displayName}', oauth2: { tokenSecretId: '${meta.oauth2.tokenSecretId}' } }`);
-            metaEntries.push(`  '${meta.oauth2.tokenSecretId}': { name: '${name}_tokens', displayName: '${meta.displayName} Tokens' }`);
+            metaEntries.push(`  '${meta.secretId}': { name: '${name}', displayName: ${literal(meta.displayName)}, oauth2: { tokenSecretId: '${meta.oauth2.tokenSecretId}' } }`);
+            metaEntries.push(`  '${meta.oauth2.tokenSecretId}': { name: '${name}_tokens', displayName: ${literal(`${meta.displayName} Tokens`)} }`);
         }
         else if (meta.schema && typeof meta.schema === 'string') {
             const schemaRef = schemaLookup.get(meta.schema);
@@ -25,7 +32,7 @@ export const serializeSecretsTypes = ({ definitions, schemaLookup, secretsFile,
                 }
                 schemaImports.get(schemaRef.sourceFile).add(schemaRef.variableName);
                 mapEntries.push(`  '${meta.secretId}': z.infer<typeof ${schemaRef.variableName}>`);
-                metaEntries.push(`  '${meta.secretId}': { name: '${name}', displayName: '${meta.displayName}' }`);
+                metaEntries.push(`  '${meta.secretId}': { name: '${name}', displayName: ${literal(meta.displayName)} }`);
             }
         }
     }

package/dist/src/functions/wirings/user-admin/pikku-command-user-admin-functions.js

@@ -3,6 +3,7 @@ import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeUserAdminFunctions } from './serialize-user-admin-functions.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         if (!config.scaffold?.userAdmin ||
@@ -35,7 +36,7 @@ export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
                 `Then re-run codegen. Or remove "scaffold.userAdmin" from pikku.config.json.`);
         }
         const pathToPikkuTypes = getFileImportRelativePath(config.userAdminFunctionsFile, config.typesDeclarationFile, config.packageMappings);
-        const { schemas, functions } = serializeUserAdminFunctions(pathToPikkuTypes, config.scaffold.userAdmin === 'auth');
+        const { schemas, functions } = serializeUserAdminFunctions(pathToPikkuTypes, resolveScaffoldFeature('userAdmin', config.scaffold.userAdmin).auth);
         await writeFileInDir(logger, config.userAdminSchemasFile, schemas);
         await writeFileInDir(logger, config.userAdminFunctionsFile, functions);
         return true;

package/dist/src/functions/wirings/user-admin/serialize-user-admin-functions.js

@@ -86,7 +86,7 @@ export const Success = z.object({
  * Auto-generated user management functions
  * Do not edit manually - regenerate with 'npx pikku'
  */
-import { pikkuFunc, wireScope } from '${pathToPikkuTypes}'
+import { pikkuFunc, defineScope } from '${pathToPikkuTypes}'
 import { callAdminApi } from '@pikku/better-auth'
 import {
   CreateUserInput,
@@ -103,7 +103,7 @@ import {
 // this is the whole \`admin\` tree — not just the leaves gated below. It must stay
 // byte-identical to ADMIN_SCOPE_TREE in @pikku/better-auth and to the copy in
 // @pikku/addon-console, or codegen fails with conflicting declarations.
-wireScope({
+defineScope({
   admin: {
     displayName: 'Administration',
     description: 'Capabilities that act on the application as a whole',

package/dist/src/functions/wirings/variables/serialize-variables-types.js

@@ -1,5 +1,12 @@
 import { validateAndBuildVariableDefinitionsMeta } from '@pikku/core/variable';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+/**
+ * A display name is the human-facing label a developer wrote, so an apostrophe
+ * in it is ordinary. `JSON.stringify` emits a valid, escaped TypeScript string
+ * literal; interpolating the raw text into a quoted one terminates the string
+ * and the generated file stops parsing.
+ */
+const literal = (value) => JSON.stringify(value);
 export const serializeVariablesTypes = ({ definitions, schemaLookup, variablesFile, packageMappings, }) => {
     const variables = validateAndBuildVariableDefinitionsMeta(definitions, schemaLookup);
     const variableEntries = Object.entries(variables);
@@ -17,7 +24,7 @@ export const serializeVariablesTypes = ({ definitions, schemaLookup, variablesFi
                 }
                 schemaImports.get(schemaRef.sourceFile).add(schemaRef.variableName);
                 mapEntries.push(`  '${meta.variableId}': z.infer<typeof ${schemaRef.variableName}>`);
-                metaEntries.push(`  '${meta.variableId}': { name: '${name}', displayName: '${meta.displayName}' }`);
+                metaEntries.push(`  '${meta.variableId}': { name: '${name}', displayName: ${literal(meta.displayName)} }`);
             }
         }
     }

package/dist/src/functions/wirings/workflow/pikku-command-workflow-routes.js

@@ -4,13 +4,14 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializeWorkflowRoutes } from './serialize-workflow-routes.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuWorkflowRoutes = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
         if (config.scaffold?.workflow &&
             config.workflowRoutesFile &&
             config.workflowRoutesSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.workflowRoutesFile, config.typesDeclarationFile, config.packageMappings);
-            const { schemas, functions } = serializeWorkflowRoutes(pathToPikkuTypes, config.scaffold?.workflow === 'auth');
+            const { schemas, functions } = serializeWorkflowRoutes(pathToPikkuTypes, resolveScaffoldFeature('workflow', config.scaffold?.workflow).auth);
             await writeFileInDir(logger, config.workflowRoutesSchemasFile, schemas);
             await writeFileInDir(logger, config.workflowRoutesFile, functions);
             await removeLegacyScaffoldFile(config.workflowRoutesFile);

package/dist/src/functions/wirings/workflow/pikku-command-workflow.js

@@ -3,8 +3,8 @@ import { ErrorCode } from '@pikku/inspector';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeWorkflowTypes } from './serialize-workflow-types.js';
-import { serializeScenarioActors } from './serialize-scenario-actors.js';
-import { resolveScenarioActors } from '../../../utils/resolve-scenario-actors.js';
+import { serializePersonas } from './serialize-personas.js';
+import { resolvePersonas } from '../../../utils/resolve-personas.js';
 import { serializeWorkflowRegistration } from './serialize-workflow-registration.js';
 import { serializeWorkflowMap } from './serialize-workflow-map.js';
 import { serializeScenarioStepMap } from './serialize-scenario-step-map.js';
@@ -89,21 +89,21 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
         const agentMapImportPath = getFileImportRelativePath(workflowTypesFile, config.agentMapDeclarationFile, packageMappings);
         const scopesImportPath = getFileImportRelativePath(workflowTypesFile, config.scopesFile, packageMappings);
         const scenarioStepMapImportPath = getFileImportRelativePath(workflowTypesFile, config.scenarioStepMapDeclarationFile, packageMappings);
-        const scenarioActorsImportPath = getFileImportRelativePath(workflowTypesFile, config.scenarioActorsFile, packageMappings);
-        await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath, scenarioActorsImportPath));
+        const personasImportPath = getFileImportRelativePath(workflowTypesFile, config.personasWiringFile, packageMappings);
+        await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath, personasImportPath));
         // Rides the workflow command rather than getting its own codegen node, so
         // it can't drift out of the two hand-maintained ordering lists.
         await writeFileInDir(logger, config.scenarioStepMapDeclarationFile, serializeScenarioStepMap(logger, config.scenarioStepMapDeclarationFile, packageMappings, typesMap, functionState.meta));
-        // Written even for an empty registry, so `TypedScenarioActors` is always a
-        // resolvable import for the generated function types.
-        const scenarioActors = resolveScenarioActors(config.scenarios);
+        // Written even when nobody declared a persona, so `TypedPersonas` is always
+        // a resolvable import for the generated function types.
+        const personas = resolvePersonas(visitState.personas.definitions, config.scenarios?.emailDomain);
         {
-            const agentMapImportPath = getFileImportRelativePath(config.scenarioActorsFile, config.agentMapDeclarationFile, packageMappings);
-            const exposedRpcMapImportPath = getFileImportRelativePath(config.scenarioActorsFile, config.rpcMapDeclarationFile, packageMappings);
-            await writeFileInDir(logger, config.scenarioActorsFile, serializeScenarioActors(scenarioActors, agentMapImportPath, exposedRpcMapImportPath));
-            // Fixed path getScenarioActorsMeta() reads; kept out of workflow/meta,
-            // which getWorkflowMeta() globs as workflows.
-            await writeFileInDir(logger, join(config.outDir, 'workflow', 'scenario-actors.gen.json'), JSON.stringify(scenarioActors, null, 2));
+            const agentMapImportPath = getFileImportRelativePath(config.personasWiringFile, config.agentMapDeclarationFile, packageMappings);
+            const exposedRpcMapImportPath = getFileImportRelativePath(config.personasWiringFile, config.rpcMapDeclarationFile, packageMappings);
+            await writeFileInDir(logger, config.personasWiringFile, serializePersonas(personas, agentMapImportPath, exposedRpcMapImportPath));
+            // Fixed path getPersonasMeta() reads; kept out of workflow/meta, which
+            // getWorkflowMeta() globs as workflows.
+            await writeFileInDir(logger, join(config.outDir, 'workflow', 'personas.gen.json'), JSON.stringify(personas, null, 2));
         }
         // Fixed path getFeaturesMeta() reads. Written even when empty so the
         // console can tell "no features declared" from "meta not generated yet".

package/dist/src/functions/wirings/workflow/serialize-personas.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedPersona } from '@pikku/core/services';
+/**
+ * The runtime half of `definePersonas()`.
+ *
+ * Generated rather than re-exported because the addresses are computed: nobody
+ * writes one down, and a seed, a scenario run and a virtual-user run all have
+ * to arrive at the same one. Baking them here is what makes that a single fact
+ * rather than three implementations of the same rule.
+ */
+export declare const serializePersonas: (personas: Record<string, ResolvedPersona>, agentMapImportPath: string, rpcMapImportPath: string) => string;

package/dist/src/functions/wirings/workflow/serialize-personas.js

@@ -0,0 +1,46 @@
+/**
+ * The runtime half of `definePersonas()`.
+ *
+ * Generated rather than re-exported because the addresses are computed: nobody
+ * writes one down, and a seed, a scenario run and a virtual-user run all have
+ * to arrive at the same one. Baking them here is what makes that a single fact
+ * rather than three implementations of the same rule.
+ */
+export const serializePersonas = (personas, agentMapImportPath, rpcMapImportPath) => {
+    return `/** Personas declared with definePersonas() */
+import { createHttpPersonas } from '@pikku/core/persona'
+import type {
+  HttpPersonasConfig,
+  ScenarioPersona,
+  ResolvedPersona,
+} from '@pikku/core/services'
+import type { AgentMap } from '${agentMapImportPath}'
+import type { FlattenedRPCMap } from '${rpcMapImportPath}'
+
+export const personaConfigs = ${JSON.stringify(personas, null, 2)} as const satisfies Record<string, ResolvedPersona>
+
+export type PersonaName = keyof typeof personaConfigs
+
+/**
+ * The same personas as a list, widened to \`ResolvedPersona\`. Iterating
+ * \`personaConfigs\` directly yields the literal type of each entry, on which an
+ * optional field a persona did not declare does not exist — so a seed reading
+ * \`roles\` off every persona needs this instead.
+ */
+export const personaList: ResolvedPersona[] = Object.values(personaConfigs)
+
+export type AgentName = keyof AgentMap & string
+export type TypedPersonas = Record<
+  PersonaName,
+  ScenarioPersona<AgentName, FlattenedRPCMap>
+>
+
+export const createPersonas = (
+  options: Omit<HttpPersonasConfig, 'personas'>
+): TypedPersonas =>
+  createHttpPersonas({
+    ...options,
+    personas: personaConfigs,
+  }) as TypedPersonas
+`;
+};

package/dist/src/functions/wirings/workflow/serialize-scenario-step-map.js

@@ -9,10 +9,19 @@
  */
 import { serializeImportMap } from '../../../utils/serialize-import-map.js';
 import { generateCustomTypes } from '@pikku/inspector';
-const SCENARIO_STEP_WRAPPER = 'pikkuScenarioStep';
+/**
+ * All three step wrappers. A scenario calls a platform or addon step by name
+ * exactly as it calls a persona one — who acts changes what the step may do, not
+ * how it is referenced — so all three belong in the map.
+ */
+const SCENARIO_STEP_WRAPPERS = new Set([
+    'pikkuScenarioStep',
+    'pikkuPlatformScenarioStep',
+    'pikkuAddonScenarioStep',
+]);
 export const serializeScenarioStepMap = (logger, relativeToPath, packageMappings, typesMap, functionsMeta) => {
     const requiredTypes = new Set();
-    const steps = Object.entries(functionsMeta).filter(([, meta]) => meta.funcWrapper === SCENARIO_STEP_WRAPPER);
+    const steps = Object.entries(functionsMeta).filter(([, meta]) => !!meta.funcWrapper && SCENARIO_STEP_WRAPPERS.has(meta.funcWrapper));
     const resolveType = (name) => {
         if (!name) {
             return 'void';