@pikku/core 0.12.71 → 0.12.74

package/dist/services/local-content.js

@@ -2,6 +2,31 @@ import { createReadStream, createWriteStream, promises } from 'fs';
 import { mkdir, readFile } from 'fs/promises';
 import { resolve, normalize } from 'path';
 import { pipeline } from 'stream/promises';
+/**
+ * The representation of an asset that gets bound into a signed URL's
+ * signature, and that a server can reconstruct from an incoming request:
+ * the decoded path, without origin or query string.
+ *
+ * Both sides must derive it the same way, so signer and verifier share this
+ * function. Percent escapes are decoded so that a client re-encoding an
+ * optional character still matches; a malformed escape is left verbatim
+ * rather than throwing, which keeps both sides in agreement.
+ */
+export const signedContentPath = (urlOrPath) => {
+    let pathname;
+    try {
+        pathname = new URL(urlOrPath, 'http://pikku.local').pathname;
+    }
+    catch {
+        pathname = urlOrPath;
+    }
+    try {
+        return decodeURIComponent(pathname);
+    }
+    catch {
+        return pathname;
+    }
+};
 export class LocalContent {
     config;
     logger;
@@ -10,6 +35,9 @@ export class LocalContent {
         this.config = config;
         this.logger = logger;
         this.jwt = jwt;
+        if (!jwt) {
+            throw new Error('LocalContent requires a JWTService: without one it cannot sign asset URLs, and unsigned URLs cannot be verified.');
+        }
     }
     safePath(bucket, key) {
         const base = resolve(this.config.localFileUploadPath);
@@ -24,7 +52,7 @@ export class LocalContent {
         return `${bucket}/${key}`;
     }
     async init() { }
-    async signParams(dateLessThan, dateGreaterThan) {
+    async signParams(url, dateLessThan, dateGreaterThan) {
         const signedAt = Date.now();
         const expiresAt = dateLessThan.getTime();
         const params = new URLSearchParams({
@@ -34,22 +62,21 @@ export class LocalContent {
         if (dateGreaterThan) {
             params.set('notBefore', String(dateGreaterThan.getTime()));
         }
-        if (this.jwt) {
-            const expiresInSeconds = Math.max(1, Math.floor((expiresAt - signedAt) / 1000));
-            const payload = {
-                signedAt,
-                expiresAt,
-            };
-            if (dateGreaterThan) {
-                payload.notBefore = dateGreaterThan.getTime();
-            }
-            const signature = await this.jwt.encode({ value: expiresInSeconds, unit: 'second' }, payload);
-            params.set('signature', signature);
+        const expiresInSeconds = Math.max(1, Math.floor((expiresAt - signedAt) / 1000));
+        const payload = {
+            signedAt,
+            expiresAt,
+            path: signedContentPath(url),
+        };
+        if (dateGreaterThan) {
+            payload.notBefore = dateGreaterThan.getTime();
         }
+        const signature = await this.jwt.encode({ value: expiresInSeconds, unit: 'second' }, payload);
+        params.set('signature', signature);
         return params.toString();
     }
     async signURL(args) {
-        const params = await this.signParams(args.dateLessThan, args.dateGreaterThan);
+        const params = await this.signParams(args.url, args.dateLessThan, args.dateGreaterThan);
         return `${args.url}?${params}`;
     }
     async signContentKey(args) {

package/dist/services/local-gateway-service.d.ts

@@ -1,20 +1,4 @@
 import type { GatewayService } from './gateway-service.js';
-/**
- * Local GatewayService implementation.
- *
- * Starts all registered listener gateways unconditionally (single-process).
- * For distributed deployments, implement `GatewayService` with leader
- * election or similar coordination.
- *
- * @example
- * ```typescript
- * const gatewayService = new LocalGatewayService()
- * await gatewayService.start()
- *
- * // On shutdown
- * await gatewayService.stop()
- * ```
- */
 export declare class LocalGatewayService implements GatewayService {
     private activeAdapters;
     start(): Promise<void>;

package/dist/services/local-gateway-service.js

@@ -1,21 +1,6 @@
 import { pikkuState, getSingletonServices } from '../pikku-state.js';
 import { createListenerMessageHandler, resolveGatewayAdapter, } from '../wirings/gateway/gateway-runner.js';
-/**
- * Local GatewayService implementation.
- *
- * Starts all registered listener gateways unconditionally (single-process).
- * For distributed deployments, implement `GatewayService` with leader
- * election or similar coordination.
- *
- * @example
- * ```typescript
- * const gatewayService = new LocalGatewayService()
- * await gatewayService.start()
- *
- * // On shutdown
- * await gatewayService.stop()
- * ```
- */
+// knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
 export class LocalGatewayService {
     activeAdapters = new Map();
     async start() {
@@ -43,7 +28,7 @@ export class LocalGatewayService {
                     getSingletonServices().logger.error(`Error closing listener gateway '${name}':`, e);
                 }
                 catch {
-                    // logger may not be available during shutdown
+                    // The logger may already be gone during shutdown.
                 }
             }
         }

package/dist/services/local-secrets.d.ts

@@ -1,9 +1,5 @@
 import type { SecretService } from './secret-service.js';
 import type { VariablesService } from './variables-service.js';
-/**
- * Service for retrieving secrets from environment variables.
- * Supports storing secrets locally in memory for CLI operations.
- */
 export declare class LocalSecretService implements SecretService {
     private variables;
     private localSecrets;

package/dist/services/local-secrets.js

@@ -1,8 +1,4 @@
 import { LocalVariablesService } from './local-variables.js';
-/**
- * Service for retrieving secrets from environment variables.
- * Supports storing secrets locally in memory for CLI operations.
- */
 export class LocalSecretService {
     variables;
     localSecrets = new Map();

package/dist/services/logger-console.d.ts

@@ -1,9 +1,6 @@
 import type { Logger } from './logger.js';
 import { LogLevel } from './logger.js';
-/**
- * Text-mode console logger.
- * Output: `INFO: message` or `[traceId] INFO: message`
- */
+/** Emits `INFO: message`, or `[traceId] INFO: message` when scoped. */
 export declare class ConsoleLogger implements Logger {
     private level;
     private prefix;
@@ -19,9 +16,8 @@ export declare class ConsoleLogger implements Logger {
     log(level: string, message: string, ...meta: any[]): void;
 }
 /**
- * JSON-mode console logger.
- * Output: `{"level":"info","message":"...","traceId":"..."}`
- * CF Workers Logs auto-indexes JSON keys for filtering.
+ * Emits `{"level":"info","message":"...","traceId":"..."}` — one JSON object per
+ * line, because Cloudflare Workers Logs auto-indexes JSON keys for filtering.
  */
 export declare class JsonConsoleLogger implements Logger {
     private level;

package/dist/services/logger-console.js

@@ -1,8 +1,5 @@
 import { LogLevel } from './logger.js';
-/**
- * Text-mode console logger.
- * Output: `INFO: message` or `[traceId] INFO: message`
- */
+/** Emits `INFO: message`, or `[traceId] INFO: message` when scoped. */
 export class ConsoleLogger {
     level = LogLevel.info;
     prefix;
@@ -61,9 +58,8 @@ export class ConsoleLogger {
     }
 }
 /**
- * JSON-mode console logger.
- * Output: `{"level":"info","message":"...","traceId":"..."}`
- * CF Workers Logs auto-indexes JSON keys for filtering.
+ * Emits `{"level":"info","message":"...","traceId":"..."}` — one JSON object per
+ * line, because Cloudflare Workers Logs auto-indexes JSON keys for filtering.
  */
 export class JsonConsoleLogger {
     level = LogLevel.info;

package/dist/services/logger.d.ts

@@ -1,53 +1,18 @@
 export declare enum LogLevel {
-    'trace' = 0,// Add this level
+    'trace' = 0,
     'debug' = 1,
     'info' = 2,
     'warn' = 3,
     'error' = 4,
     'critical' = 5
 }
-/**
- * Interface for logging messages at various levels.
- */
 export interface Logger {
-    /**
-     * Logs an informational message.
-     * @param messageOrObj - The message or object to log.
-     * @param meta - Additional metadata to log.
-     */
     info(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
-    /**
-     * Logs a warning message.
-     * @param messageOrObj - The message or object to log.
-     * @param meta - Additional metadata to log.
-     */
     warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void;
-    /**
-     * Logs an error message.
-     * @param messageOrObj - The message, object, or error to log.
-     * @param meta - Additional metadata to log.
-     */
     error(messageOrObj: string | Record<string, any> | Error, ...meta: any[]): void;
-    /**
-     * Logs a debug message.
-     * @param message - The message to log.
-     * @param meta - Additional metadata to log.
-     */
     debug(message: string, ...meta: any[]): void;
-    /**
-     * Logs a trace message.
-     * @param message - The message to log.
-     * @param meta - Additional metadata to log.
-     */
     trace?(message: string, ...meta: any[]): void;
-    /**
-     * Sets the logging level.
-     * @param level - The logging level to set.
-     */
     setLevel(level: LogLevel): void;
-    /**
-     * Creates a scoped logger with a traceId included in every log entry.
-     * Used per-request to correlate logs across function calls.
-     */
+    /** A logger carrying a traceId on every entry, taken per-request to correlate calls. */
     scope?(traceId: string): Logger;
 }

package/dist/services/meta-service.d.ts

@@ -6,7 +6,8 @@ import type { QueueWorkersMeta } from '../wirings/queue/queue.types.js';
 import type { CLIMeta } from '../wirings/cli/cli.types.js';
 import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
 import type { FeaturesMeta, WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
-import type { ScenarioActorConfig } from './scenario-actors-service.js';
+import type { ResolvedPersona } from './personas-service.js';
+import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
 import type { CredentialDefinitionsMeta } from '../wirings/credential/credential.types.js';
@@ -114,32 +115,21 @@ export interface EmailTemplateAssets {
     text: string;
     missing: string[];
 }
-/**
- * Abstraction over .pikku metadata file access.
- * All paths are relative to the .pikku root directory.
- *
- * Node.js uses LocalMetaService (filesystem).
- * Cloudflare uses an R2/KV implementation.
- */
+/** Every `relativePath` below is relative to the `.pikku` root directory. */
 export interface MetaService {
-    /** Base path for local filesystem implementations. Undefined for remote/non-local implementations. */
+    /** Undefined for remote/non-local implementations. */
     readonly basePath?: string;
-    /** Read a file's content by relative path. Returns null if not found. */
     readFile(relativePath: string): Promise<string | null>;
-    /** List files in a directory by relative path. Returns empty array if not found. */
     readDir(relativePath: string): Promise<string[]>;
-    /** Read a project source file relative to the project root (one level above .pikku). */
+    /** Relative to the project root, one level above `.pikku`. */
     readProjectFile(relativePath: string): Promise<string | null>;
     /**
-     * Read a file from an *installed addon package's* own `.pikku` directory
-     * (resolved from node_modules), NOT the app's `.pikku`. `relativePath` is
-     * relative to that package's `.pikku` root (use `../` to reach the package
-     * root itself, e.g. `../README.md`). Returns null if the package or file is
-     * absent. Only local/Node implementations resolve packages; remote impls omit
-     * this and callers guard with `?.`.
+     * Reads an *installed addon package's* own `.pikku`, not the app's, with
+     * `relativePath` rooted there (`../README.md` reaches the package root).
+     * Optional because only local/Node implementations resolve packages — remote
+     * ones omit it and callers guard with `?.`.
      */
     readPackageFile?(packageName: string, relativePath: string): Promise<string | null>;
-    /** List a directory inside an installed addon package's `.pikku`. */
     readPackageDir?(packageName: string, relativePath: string): Promise<string[]>;
     getHttpMeta(): Promise<HTTPWiringsMeta>;
     getChannelsMeta(): Promise<ChannelsMeta>;
@@ -150,7 +140,16 @@ export interface MetaService {
     getGatewayMeta(): Promise<GatewaysMeta>;
     getRpcMeta(): Promise<RPCMetaRecord>;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
-    getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>;
+    getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
+    /**
+     * The roles declared with `defineSystemRole`, keyed by name.
+     *
+     * A persona declares roles; a function checks scopes. Anything showing what a
+     * persona can reach — the console's persona page, a run's catalogue — needs
+     * this to get from one to the other, and needs it to be the same expansion the
+     * seed granted from rather than a second one.
+     */
+    getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;
@@ -168,10 +167,6 @@ export interface MetaService {
     getSchemas(schemaNames: string[]): Promise<Record<string, JSONSchema7 | null>>;
     clearCache(): void;
 }
-/**
- * Node.js filesystem implementation of MetaService.
- * Reads .gen.json files from a local .pikku directory.
- */
 export declare class LocalMetaService implements MetaService {
     readonly basePath: string;
     private httpMetaCache;
@@ -183,7 +178,8 @@ export declare class LocalMetaService implements MetaService {
     private gatewayMetaCache;
     private rpcMetaCache;
     private workflowMetaCache;
-    private scenarioActorsMetaCache;
+    private personasMetaCache;
+    private systemRolesMetaCache;
     private featuresMetaCache;
     private triggerMetaCache;
     private triggerSourceMetaCache;
@@ -216,7 +212,8 @@ export declare class LocalMetaService implements MetaService {
     getRpcMeta(): Promise<RPCMetaRecord>;
     private readWorkflowMetaDir;
     getWorkflowMeta(): Promise<WorkflowsMeta>;
-    getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>;
+    getPersonasMeta(): Promise<Record<string, ResolvedPersona>>;
+    getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>;
     getFeaturesMeta(): Promise<FeaturesMeta>;
     getTriggerMeta(): Promise<TriggerMeta>;
     getTriggerSourceMeta(): Promise<TriggerSourceMeta>;

package/dist/services/meta-service.js

@@ -2,10 +2,6 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
-/**
- * Node.js filesystem implementation of MetaService.
- * Reads .gen.json files from a local .pikku directory.
- */
 export class LocalMetaService {
     basePath;
     httpMetaCache = null;
@@ -17,7 +13,8 @@ export class LocalMetaService {
     gatewayMetaCache = null;
     rpcMetaCache = null;
     workflowMetaCache = null;
-    scenarioActorsMetaCache = null;
+    personasMetaCache = null;
+    systemRolesMetaCache = null;
     featuresMetaCache = null;
     triggerMetaCache = null;
     triggerSourceMetaCache = null;
@@ -57,10 +54,7 @@ export class LocalMetaService {
             return null;
         }
     }
-    // Resolve an installed addon package's root dir from the app's node_modules.
-    // The addon packages have no main `exports` entry, so `require.resolve(pkg)`
-    // throws; instead we walk the node_modules search paths (anchored at the app
-    // root, one level above `.pikku`) and pick the first that contains the package.
+    // knowledge: decisions/internals/addon-package-roots-resolve-by-walking-node-module-search-paths.md
     packageRootCache = new Map();
     resolvePackageRoot(packageName) {
         const cached = this.packageRootCache.get(packageName);
@@ -115,7 +109,8 @@ export class LocalMetaService {
         this.gatewayMetaCache = null;
         this.rpcMetaCache = null;
         this.workflowMetaCache = null;
-        this.scenarioActorsMetaCache = null;
+        this.personasMetaCache = null;
+        this.systemRolesMetaCache = null;
         this.featuresMetaCache = null;
         this.triggerMetaCache = null;
         this.triggerSourceMetaCache = null;
@@ -129,7 +124,6 @@ export class LocalMetaService {
         this.agentsMetaCache = null;
         this.schemaCache.clear();
     }
-    // -- Private helpers --
     async readMetaJson(dir, baseName) {
         const verbose = await this.readFile(`${dir}/${baseName}-verbose.gen.json`);
         if (verbose)
@@ -139,7 +133,6 @@ export class LocalMetaService {
             return minimal;
         return null;
     }
-    // -- Typed metadata accessors --
     async getHttpMeta() {
         if (this.httpMetaCache)
             return this.httpMetaCache;
@@ -248,9 +241,7 @@ export class LocalMetaService {
             return this.workflowMetaCache;
         try {
             const result = {};
-            // Scenarios keep their meta in `scenarios/meta` so nothing app-facing
-            // imports them, but they are still workflows to anything reading meta off
-            // disk — the console's scenario list among them.
+            // knowledge: decisions/internals/scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md
             await Promise.all([
                 this.readWorkflowMetaDir('workflow/meta', result),
                 this.readWorkflowMetaDir('scenarios/meta', result),
@@ -264,12 +255,20 @@ export class LocalMetaService {
             return this.workflowMetaCache;
         }
     }
-    async getScenarioActorsMeta() {
-        if (this.scenarioActorsMetaCache)
-            return this.scenarioActorsMetaCache;
-        const content = await this.readFile('workflow/scenario-actors.gen.json');
-        this.scenarioActorsMetaCache = content ? JSON.parse(content) : {};
-        return this.scenarioActorsMetaCache;
+    async getPersonasMeta() {
+        if (this.personasMetaCache)
+            return this.personasMetaCache;
+        const content = await this.readFile('workflow/personas.gen.json');
+        this.personasMetaCache = content ? JSON.parse(content) : {};
+        return this.personasMetaCache;
+    }
+    async getSystemRolesMeta() {
+        if (this.systemRolesMetaCache)
+            return this.systemRolesMetaCache;
+        // Beside the scopes it is composed from, which is where codegen writes it.
+        const content = await this.readFile('scopes/pikku-roles-meta.gen.json');
+        this.systemRolesMetaCache = content ? JSON.parse(content) : {};
+        return this.systemRolesMetaCache;
     }
     async getFeaturesMeta() {
         if (this.featuresMetaCache)
@@ -297,8 +296,6 @@ export class LocalMetaService {
             return this.functionsMetaCache;
         const [content, scenarioContent] = await Promise.all([
             this.readMetaJson('function', 'pikku-functions-meta'),
-            // Scenario steps register only into the scenario bootstrap, but they are
-            // still functions to anything reading meta off disk.
             this.readMetaJson('scenarios', 'pikku-scenario-functions-meta'),
         ]);
         this.functionsMetaCache = {
@@ -360,12 +357,7 @@ export class LocalMetaService {
         return this.variablesMetaCache;
     }
     async getEmailMeta() {
-        // Read fresh every call — never cache. The email meta file is generated by
-        // `pikku all`/`pikku emails generate` and is regenerated DURING a long-lived
-        // session (sandbox boots the orchestrator before the user project's codegen
-        // has written it). Caching here once returned an empty {templates:{}} that
-        // then stuck for the whole session, leaving the console emails screen blank
-        // even after the file appeared. A local JSON read is essentially free.
+        // knowledge: decisions/internals/email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md
         const content = await this.readFile('email/pikku-emails-meta.gen.json');
         return content
             ? JSON.parse(content)
@@ -380,9 +372,7 @@ export class LocalMetaService {
         if (!emailsMeta.src) {
             throw new Error('No generated email metadata found. Run `pikku emails generate`.');
         }
-        // emailsMeta.src is an absolute path resolved by the CLI at generation time.
-        // Read directly rather than through readProjectFile (which prepends the project
-        // root and produces a wrong compound path when baseDir is absolute).
+        // knowledge: decisions/internals/generated-src-paths-in-pikku-meta-are-absolute.md
         const baseDir = emailsMeta.src;
         const readEmailFile = async (rel) => {
             try {
@@ -409,10 +399,6 @@ export class LocalMetaService {
             ...(templateText ? [] : ['text']),
         ];
         if (missing.length > 0) {
-            // Diagnostic for the intermittent "Missing source files" report: logs which
-            // process and which resolved baseDir saw the gap. Different pids across
-            // failures => multiple runtime workers with divergent cached `src`; same pid
-            // + transient absence => files being rewritten under us (e.g. regeneration).
             console.warn(`[email-assets] pid=${process.pid} template=${templateName} locale=${locale} baseDir=${baseDir} missing=${missing.join(',')}`);
         }
         return {

package/dist/services/personas-service.d.ts

@@ -0,0 +1,134 @@
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
+import type { PersonaMeta } from '../wirings/persona/persona.types.js';
+/**
+ * What the transport answered, for a step that treats the status as data.
+ *
+ * An HTTP response with its body already drained: the stream can only be read
+ * once, and a step's return value crosses into the run record, so the response
+ * object itself cannot travel. This is the shape every caller ends up with.
+ */
+export interface ScenarioHttpResponse<T = unknown> {
+    status: number;
+    ok: boolean;
+    /**
+     * The parsed JSON body — or, when the body was not JSON, the raw text it was
+     * parsed from, so an HTML error page is still readable rather than lost.
+     * `undefined` for an empty response.
+     *
+     * `T` is a claim the caller makes, not one the transport checked: a step that
+     * knows the route's payload names it here instead of casting at every use.
+     */
+    body: T;
+    /**
+     * The whole body as text, so an assertion can search it without knowing the
+     * payload's shape — and so an error body that is HTML rather than JSON still
+     * says what went wrong.
+     */
+    serialized: string;
+}
+/**
+ * Drain a response into the shape a step can carry: the parsed body (an empty
+ * one counting as no body at all) alongside the text it was parsed from.
+ *
+ * `invokeRaw` returns this, and a step that has to reach past a persona — a
+ * route with no RPC, an identity no persona can hold — reaches for this rather
+ * than writing the same record by hand.
+ */
+export declare const readScenarioHttpResponse: <T = unknown>(res: Response) => Promise<ScenarioHttpResponse<T>>;
+/** How to send one JSON request, for `postScenarioJson`. */
+export interface ScenarioJsonRequest {
+    /** Serialised as the JSON body. Omit for a request that carries none. */
+    body?: unknown;
+    /** Sent alongside `content-type: application/json`, and may override it. */
+    headers?: Record<string, string>;
+    /** Defaults to `POST` — the method every scenario route here answers. */
+    method?: string;
+    /**
+     * The `fetch` to send it with. Pass a `ScenarioCookieJar`'s to keep the
+     * session; the global `fetch` otherwise, which is what a step asserting on a
+     * sessionless call wants.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
+ *
+ * Every scenario that reaches past a persona was writing this by hand — the same
+ * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
+ * drifted: some returned `res.json()`, which loses the status and throws
+ * outright when the target answers an empty body or an HTML error page. A
+ * refusal is the expected outcome of a permissions scenario, so it has to
+ * survive as data.
+ */
+export declare const postScenarioJson: <T = unknown>(url: string, { body, headers, method, fetch: send, }?: ScenarioJsonRequest) => Promise<ScenarioHttpResponse<T>>;
+/** Per-call transport options. */
+export interface ScenarioInvokeOptions {
+    /**
+     * Headers to send alongside the persona's own session. This is how a step
+     * expresses an identity no declared persona can — an impersonation header, or
+     * one of the header-shim principals a credential scenario invents.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * The RPC surface a persona can reach, as name → input/output. A project binds
+ * its generated exposed RPC map here; the default leaves every name open, which
+ * is what a persona built by hand (or by a third-party driver) gets.
+ */
+export type ScenarioRpcMap = Record<string, {
+    input: any;
+    output: any;
+}>;
+/**
+ * The persona a step's `actor` slot carries, for a project whose personas are
+ * known. No declared personas keeps the open type rather than collapsing to
+ * `never` — a project may still build one itself.
+ */
+export type ScenarioPersonaOf<TPersonas> = [keyof TPersonas] extends [never] ? ScenarioPersona : TPersonas[keyof TPersonas];
+/**
+ * A declared person, signed in and acting over the real transport.
+ *
+ * The runtime half of `definePersonas()`: sign-in materialises a user row
+ * flagged `actor: true`, and everything a step or a virtual user does goes
+ * through here.
+ */
+export interface ScenarioPersona<TAgentName extends string = string, TRpcMap extends ScenarioRpcMap = ScenarioRpcMap> {
+    /** The id it was declared under — what a step's `actor` slot names. */
+    readonly name: string;
+    /** Their address, computed from the id. Flows use it for invites/lookups. */
+    readonly email: string;
+    /** Invoke an exposed RPC as this person over the real transport. */
+    invoke<TName extends keyof TRpcMap & string>(rpcName: TName, data: TRpcMap[TName]['input']): Promise<TRpcMap[TName]['output']>;
+    /**
+     * The same call, reporting what the transport answered rather than throwing.
+     * A refusal is the expected outcome of a permissions or scopes scenario, and
+     * `invoke`'s error truncates the body that names which scope was missing.
+     */
+    invokeRaw<TName extends keyof TRpcMap & string>(rpcName: TName, data: TRpcMap[TName]['input'], options?: ScenarioInvokeOptions): Promise<ScenarioHttpResponse>;
+    /** Converse with a Pikku AI agent in character and return its verdict. */
+    converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>;
+    /**
+     * The roles this person actually holds on the stage, read back after signing
+     * in — what a run compares against the declaration before its first step.
+     *
+     * `null` when the target does not say. That is not the same as "no roles": a
+     * run that treats silence as an empty list refuses to start against every
+     * stage whose auth reports roles somewhere else, so the caller must decide
+     * whether it can verify at all.
+     */
+    sessionRoles(): Promise<string[] | null>;
+}
+/**
+ * A declared persona with its address filled in — what codegen writes and what
+ * a seed, a scenario run and a virtual-user run all read.
+ *
+ * The address is not declared. It is derived from the persona's id and the
+ * project's persona domain, so two people can never accidentally share one and
+ * sign in as the same user row — which would silently collapse exactly the
+ * isolation scenarios a second person exists for.
+ */
+export type ResolvedPersona = PersonaMeta & {
+    email: string;
+};
+/** The injected `personas` service: persona id → persona. */
+export type ScenarioPersonas = Record<string, ScenarioPersona>;