@pikku/core 0.12.98 → 0.12.100

package/CHANGELOG.md

@@ -1,3 +1,78 @@
+## 0.12.100
+
+### Patch Changes
+
+- a0ed1e8: Derive a persona's session and operator paths from the mount its sign-in path names.
+
+  Both `sessionRoles()` and the Fabric operator handshake asked for a fixed
+  `/auth/…` no matter where auth was mounted. An app serving better-auth under
+  `/api/auth` while keeping its RPCs at the root cannot put the mount in
+  `apiUrl`, so it moves `signInPath` — and the other two stayed behind.
+
+  For the session read that meant a 404, which returns `null`, which means "this
+  stage does not report roles": every `pikku persona run` on such an app warned
+  "running unverified" and lost the one thing that tells a permissions finding
+  from seed drift. For the operator handshake it was worse — `HttpPersona`
+  reused the _actor_ path verbatim, so an operator token was posted to the actor
+  endpoint and came back as a validation error about a missing email and secret,
+  which reads like a broken persona rather than a wrong URL. The browser provider
+  had the same fixed default.
+
+  All three now follow `signInPath`, and `environments[].sessionPath` in
+  pikku.config.json overrides the session read for a stage that reports it
+  elsewhere.
+
+## 0.12.99
+
+### Patch Changes
+
+- ee9da9e: Reading an optional secret that is not set no longer makes `hasSecret` report it as set. `TypedSecretService` caches `undefined` to remember the absence, and the cache probe read that as a value.
+- 7a15c9c: An actor credential is one persona's, not everyone's
+
+  `SCENARIO_ACTOR_SECRET` was a skeleton key. Anyone holding it could post any
+  `actor: true` address to `/auth/sign-in/actor` and get that persona's session —
+  including the `admin` persona, which provisioning grants real admin. The browser
+  switcher held it too, baked into the dev bundle as `VITE_SCENARIO_ACTOR_SECRET`,
+  so "the reviewer can sign in as each kind of user" and "the reviewer's bundle is
+  entitled to every persona" were the same fact.
+
+  It is now a root that credentials derive from, never one that is presented:
+
+  ```ts
+  deriveActorSecret(root, email) // HKDF-expanded HMAC-SHA256 over the address
+  ```
+
+  The endpoint re-derives the expected value for whichever address is signing in
+  and compares, so nothing is stored or looked up, a credential minted for one
+  persona is refused for every other, and rotating the root invalidates all of
+  them at once. The root itself is no longer a valid credential, and a root under
+  32 characters refuses the endpoint rather than deriving weak credentials from
+  it — the server log says why, the client is not told.
+
+  What that buys, in the places that used to need the whole key:
+
+  - **`pikku dev`** mints one credential per declared persona into
+    `VITE_DEV_ACTOR_SECRETS` and no longer writes `VITE_SCENARIO_ACTOR_SECRET` at
+    all. The root stays on the server.
+  - **`pikku persona secret <id>`** mints them for anything else, and a run given
+    `PIKKU_PERSONA_SECRETS=id=secret,…` can sign in as those personas and no
+    others — asking for one outside the list throws naming the persona instead of
+    falling back to the root.
+
+  `useDevActors()` and `<DevActorSwitcher />` take `secrets` (one per address)
+  where they took `secret`, and an actor with no credential is no longer offered
+  rather than rendering a row that 401s. `HttpPersonasConfig.secret` and the
+  Playwright provider's `secret` additionally accept a resolver, which is how a
+  partially-credentialled run is expressed.
+
+- ee9da9e: the surface gate measures the surface it actually ships
+
+  The doc-quality gate went in with ceilings of 112, 823 and 10 beside a surface
+  that measured 160, 1210 and 15, so it never passed on any build. Re-baselined to
+  the real measurements, and the key-documentation floor earned its way from 76%
+  to 79% by documenting what a caller has to put in `defineSecret`, the gateway
+  message shapes, and the scorer and judge configs.
+
 ## 0.12.98
 
 ### Patch Changes

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

@@ -1,6 +1,6 @@
 import type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, ScenarioInvokeOptions, ScenarioHttpResponse } from './personas-service.js';
 import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
-import { type OperatorSignInOptions } from './persona-sign-in.js';
+import { type ActorSecretResolver, type OperatorSignInOptions } from './persona-sign-in.js';
 export interface HttpPersonasConfig {
     /**
      * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
@@ -10,13 +10,19 @@ export interface HttpPersonasConfig {
      */
     apiUrl: string;
     /**
-     * The impersonation secret. Sign-in only ever works for user rows flagged
-     * `actor: true` — knowing the secret never impersonates real users.
+     * The ROOT actor secret, from which each persona's own credential is derived
+     * and bound to their address. Sign-in only ever works for user rows flagged
+     * `actor: true`, and a derived credential only ever works for the one address
+     * it was derived for.
+     *
+     * Pass an {@link ActorSecretResolver} instead to drive personas whose
+     * credentials were minted elsewhere — a caller entitled to one persona then
+     * never holds the root.
      *
      * The local-development credential. A deployed stage has none, and passes
      * {@link HttpPersonasConfig.operator} instead.
      */
-    secret?: string;
+    secret?: string | ActorSecretResolver;
     /**
      * Fabric operator credentials, for signing personas into a DEPLOYED stage.
      *
@@ -34,7 +40,12 @@ export interface HttpPersonasConfig {
      * {@link OperatorSignInOptions.signInPath} overrides it.
      */
     signInPath?: string;
-    /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
+    /**
+     * Where the session (and its roles) is read back. Defaults to `get-session`
+     * under the same auth mount as {@link HttpPersonasConfig.signInPath}, so an
+     * app that moved auth under `/api` moves this with it and does not have to
+     * say so twice.
+     */
     sessionPath?: string;
     /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
     rpcPath?: string;

package/dist/services/http-personas.js

@@ -1,7 +1,7 @@
 import { readScenarioHttpResponse } from './personas-service.js';
 import { runConversation } from '../wirings/actor-flow/run-conversation.js';
 import { createCookieJar, } from '../wirings/workflow/scenario-cookie-jar.js';
-import { ActorSignIn, OperatorSignIn, } from './persona-sign-in.js';
+import { ActorSignIn, OperatorSignIn, authMount, } from './persona-sign-in.js';
 import { getSingletonServices } from '../pikku-state.js';
 import { AIProviderNotConfiguredError } from '../errors/errors.js';
 /**
@@ -34,7 +34,10 @@ export class HttpPersona {
         if (config.operator) {
             this.signIn = new OperatorSignIn(config.apiUrl, {
                 ...config.operator,
-                signInPath: config.operator.signInPath ?? config.signInPath,
+                signInPath: config.operator.signInPath ??
+                    (authMount(config.signInPath)
+                        ? `${authMount(config.signInPath)}/sign-in/fabric`
+                        : undefined),
             });
         }
         else if (config.secret) {
@@ -115,7 +118,8 @@ export class HttpPersona {
         if (!this.signedIn) {
             await this.login();
         }
-        const sessionPath = this.config.sessionPath ?? '/auth/get-session';
+        const mount = authMount(this.config.operator?.signInPath ?? this.config.signInPath);
+        const sessionPath = this.config.sessionPath ?? `${mount ?? '/auth'}/get-session`;
         const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
             headers: this.signIn.headers(),
         });

package/dist/services/index.d.ts

@@ -23,6 +23,7 @@ export type { JWTService } from './jwt-service.js';
 export type { EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export { renderEmail, type EmailAssets, type EmailTemplateAssets, type EmailTemplateHashes, type RenderEmailRequest, type RenderedEmailResult, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
+export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';
 export type { Logger } from './logger.js';
 export type { SecretService, SecretValues } from './secret-service.js';
 export type { VariablesService } from './variables-service.js';

package/dist/services/index.js

@@ -19,6 +19,7 @@ export { LocalGatewayService } from './local-gateway-service.js';
 export { FileScenarioRunStore, scenarioArtifactContentType, scenarioRunSummary, } from './file-scenario-run-store.js';
 export { renderEmail, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
+export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';
 export { SchedulerService } from './scheduler-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
 export { NoopAuditService, createInvocationAudit } from './audit-service.js';

package/dist/services/persona-actor-secret.d.ts

@@ -0,0 +1,38 @@
+/** The name the root secret is held under, used only in error messages. */
+export declare const ACTOR_SECRET_NAME = "SCENARIO_ACTOR_SECRET";
+/**
+ * Namespaces the derivation so the same root secret used for anything else
+ * produces different values. See knowledge/crypto.md.
+ */
+export declare const ACTOR_SECRET_INFO = "pikku:actor-sign-in";
+/** The root must be strong: every persona's credential is derived from it. */
+export declare const ACTOR_ROOT_SECRET_MIN_LENGTH = 32;
+/**
+ * What the derivation is bound to. Lowercased because the sign-in endpoint
+ * looks the user up by lowercased address, and a credential that verified
+ * against a different string than the row it opens is a credential for nothing.
+ */
+export declare const actorSecretSubject: (email: string) => string;
+/**
+ * One persona's actor credential: `HMAC-SHA256(root, email)`, base64url.
+ *
+ * The root secret is not itself a valid credential and never travels: what a
+ * scenario run, a CI job or a virtual user is handed is the derived value for
+ * the one address it is entitled to. Presenting it for any other address fails,
+ * so a leaked credential is worth exactly one synthetic account rather than the
+ * whole actor population.
+ *
+ * Deterministic, so nothing is stored and nothing is provisioned — the target
+ * re-derives the expected value from the address being signed in as. Rotating
+ * the root invalidates every derived credential at once, which is the property
+ * a per-persona secret table would have to implement by hand.
+ */
+export declare const deriveActorSecret: (rootSecret: string, email: string) => Promise<string>;
+/**
+ * Whether `presented` is the credential for `email` under `rootSecret`.
+ *
+ * False — never throws — for a malformed, truncated or mismatched value, and
+ * the comparison is WebCrypto's own HMAC verify, so it does not exit early on
+ * the first differing byte.
+ */
+export declare const verifyActorSecret: (rootSecret: string, email: string, presented: string) => Promise<boolean>;

package/dist/services/persona-actor-secret.js

@@ -0,0 +1,39 @@
+import { MIN_KEY_MATERIAL_LENGTH, signWithKeyMaterial, verifyWithKeyMaterial, } from '../crypto-utils.js';
+/** The name the root secret is held under, used only in error messages. */
+export const ACTOR_SECRET_NAME = 'SCENARIO_ACTOR_SECRET';
+/**
+ * Namespaces the derivation so the same root secret used for anything else
+ * produces different values. See knowledge/crypto.md.
+ */
+export const ACTOR_SECRET_INFO = 'pikku:actor-sign-in';
+/** The root must be strong: every persona's credential is derived from it. */
+export const ACTOR_ROOT_SECRET_MIN_LENGTH = MIN_KEY_MATERIAL_LENGTH;
+/**
+ * What the derivation is bound to. Lowercased because the sign-in endpoint
+ * looks the user up by lowercased address, and a credential that verified
+ * against a different string than the row it opens is a credential for nothing.
+ */
+export const actorSecretSubject = (email) => email.trim().toLowerCase();
+/**
+ * One persona's actor credential: `HMAC-SHA256(root, email)`, base64url.
+ *
+ * The root secret is not itself a valid credential and never travels: what a
+ * scenario run, a CI job or a virtual user is handed is the derived value for
+ * the one address it is entitled to. Presenting it for any other address fails,
+ * so a leaked credential is worth exactly one synthetic account rather than the
+ * whole actor population.
+ *
+ * Deterministic, so nothing is stored and nothing is provisioned — the target
+ * re-derives the expected value from the address being signed in as. Rotating
+ * the root invalidates every derived credential at once, which is the property
+ * a per-persona secret table would have to implement by hand.
+ */
+export const deriveActorSecret = async (rootSecret, email) => signWithKeyMaterial(ACTOR_SECRET_NAME, rootSecret, ACTOR_SECRET_INFO, actorSecretSubject(email));
+/**
+ * Whether `presented` is the credential for `email` under `rootSecret`.
+ *
+ * False — never throws — for a malformed, truncated or mismatched value, and
+ * the comparison is WebCrypto's own HMAC verify, so it does not exit early on
+ * the first differing byte.
+ */
+export const verifyActorSecret = async (rootSecret, email, presented) => verifyWithKeyMaterial(ACTOR_SECRET_NAME, rootSecret, ACTOR_SECRET_INFO, actorSecretSubject(email), presented);

package/dist/services/persona-sign-in.d.ts

@@ -26,6 +26,11 @@ export interface PersonaSignIn {
     /** Headers every request after `login` must carry. */
     headers(): Record<string, string>;
 }
+/**
+ * Yields the credential for one persona, for a caller that holds that persona's
+ * derived secret and not the root it came from.
+ */
+export type ActorSecretResolver = (persona: ResolvedPersona) => string | Promise<string>;
 /**
  * Sign a persona in through the Better Auth actor plugin — the local-development
  * path.
@@ -34,15 +39,32 @@ export interface PersonaSignIn {
  * for it. Passwordless by design and refused for any row not carrying that flag,
  * so the secret can never reach a real user's account; the plugin still declines
  * to serve the endpoint at all outside `pikku dev`.
+ *
+ * What is presented is the persona's own credential, derived from the root and
+ * bound to their address. A run driving many personas holds the root and
+ * derives as it goes; a run entitled to one persona is handed that one value
+ * through a resolver and can sign in as nobody else.
  */
 export declare class ActorSignIn implements PersonaSignIn {
     private readonly apiUrl;
     private readonly secret;
     private readonly signInPath;
-    constructor(apiUrl: string, secret: string, signInPath: string);
+    constructor(apiUrl: string, secret: string | ActorSecretResolver, signInPath: string);
     login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
     headers(): Record<string, string>;
 }
+/**
+ * The auth mount a configured sign-in path sits under, or `undefined` when it
+ * names nothing recognisable.
+ *
+ * better-auth serves sign-in, operator sign-in and `get-session` from one
+ * prefix, so an app that mounts it at `/api/auth` moves all three together and
+ * says so once through `signInPath`. Reading the other two from a hardcoded
+ * `/auth` on such an app 404s — and for `get-session` a 404 reads as "this
+ * stage does not report roles", which silently turns off the check that tells a
+ * permissions finding from seed drift.
+ */
+export declare const authMount: (signInPath?: string) => string | undefined;
 export interface OperatorSignInOptions {
     /**
      * The short-lived RS256 operator token, or a function that mints one. Prefer

package/dist/services/persona-sign-in.js

@@ -1,3 +1,4 @@
+import { deriveActorSecret } from './persona-actor-secret.js';
 /**
  * The header `resolveImpersonatedSession` reads the target user id from.
  *
@@ -18,6 +19,11 @@ const failed = async (what, personaId, res) => {
  * for it. Passwordless by design and refused for any row not carrying that flag,
  * so the secret can never reach a real user's account; the plugin still declines
  * to serve the endpoint at all outside `pikku dev`.
+ *
+ * What is presented is the persona's own credential, derived from the root and
+ * bound to their address. A run driving many personas holds the root and
+ * derives as it goes; a run entitled to one persona is handed that one value
+ * through a resolver and can sign in as nobody else.
  */
 export class ActorSignIn {
     apiUrl;
@@ -29,13 +35,16 @@ export class ActorSignIn {
         this.signInPath = signInPath;
     }
     async login(jar, persona) {
+        const secret = typeof this.secret === 'function'
+            ? await this.secret(persona)
+            : await deriveActorSecret(this.secret, persona.email);
         const res = await jar.fetch(`${this.apiUrl}${this.signInPath}`, {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
             body: JSON.stringify({
                 email: persona.email,
                 name: persona.name,
-                secret: this.secret,
+                secret,
             }),
         });
         if (!res.ok) {
@@ -51,6 +60,21 @@ export class ActorSignIn {
         return {};
     }
 }
+/**
+ * The auth mount a configured sign-in path sits under, or `undefined` when it
+ * names nothing recognisable.
+ *
+ * better-auth serves sign-in, operator sign-in and `get-session` from one
+ * prefix, so an app that mounts it at `/api/auth` moves all three together and
+ * says so once through `signInPath`. Reading the other two from a hardcoded
+ * `/auth` on such an app 404s — and for `get-session` a 404 reads as "this
+ * stage does not report roles", which silently turns off the check that tells a
+ * permissions finding from seed drift.
+ */
+export const authMount = (signInPath) => {
+    const mount = signInPath ? signInPath.lastIndexOf('/sign-in/') : -1;
+    return !signInPath || mount === -1 ? undefined : signInPath.slice(0, mount);
+};
 /**
  * Establish a Fabric operator session against `apiUrl` and resolve the target's
  * own id for `persona`, which is what the impersonation header names.

package/dist/services/typed-secret-service.js

@@ -21,8 +21,11 @@ export class TypedSecretService {
         return value;
     }
     async hasSecret(key) {
+        // `undefined` is cached for an optional secret that resolved absent, so a
+        // cache hit means "already looked", not "there is a value". Reporting true
+        // for it would let a read of an optional secret assert its own presence.
         if (this.cache.has(key)) {
-            return true;
+            return this.cache.get(key) !== undefined;
         }
         return this.secrets.hasSecret(key);
     }

package/dist/wirings/agent-scorer/agent-scorer.d.ts

@@ -6,7 +6,9 @@ import type { JudgeToolCallDisclosure, PikkuAgentScorer, ScorerInput, ScorerOutp
  * @example snippet: agentScorer
  */
 export declare const pikkuAgentScorer: <Services = any>(config: {
+    /** Identifies the scorer in results and in the Console. Unique per project. */
     name: string;
+    /** What this scorer grades, in one line, for whoever reads the score later. */
     description: string;
     /** 0..1 fraction of live runs to grade. Defaults to all of them. */
     sampleRate?: number;
@@ -15,6 +17,10 @@ export declare const pikkuAgentScorer: <Services = any>(config: {
      * traffic has no answer key, so the runtime never samples it.
      */
     requiresReference?: boolean;
+    /**
+     * The grade itself: read the finished run and return `{ score, reason }`.
+     * Runs in-process, so it may use your own services.
+     */
     score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>;
 }) => PikkuAgentScorer<Services>;
 /**
@@ -28,7 +34,9 @@ export declare const pikkuAgentScorer: <Services = any>(config: {
  * @example snippet: agentJudge
  */
 export declare const pikkuAgentJudge: <Services = any>(config: {
+    /** Identifies the judge in results and in the Console. Unique per project. */
     name: string;
+    /** What this judge grades, in one line, for whoever reads the score later. */
     description: string;
     /** 0..1 fraction of live runs to grade. Defaults to all of them. */
     sampleRate?: number;
@@ -37,7 +45,9 @@ export declare const pikkuAgentJudge: <Services = any>(config: {
      * traffic has no answer key, so the runtime never samples it.
      */
     requiresReference?: boolean;
+    /** The model that grades, e.g. `'claude-sonnet-4-5'`. Not the model under test. */
     model: string;
+    /** The rubric: what a good answer looks like, phrased as the goal it should meet. */
     goal: string;
     /**
      * How much of the run's trajectory to disclose to the judge. Defaults to
@@ -45,5 +55,9 @@ export declare const pikkuAgentJudge: <Services = any>(config: {
      * sending a third-party model the rows the tools returned.
      */
     toolCalls?: JudgeToolCallDisclosure;
+    /**
+     * Replaces the generated rubric prompt outright, for framing `goal` cannot
+     * express. The `{ score, reason }` response is still forced.
+     */
     prompt?: (input: ScorerInput) => string;
 }) => PikkuAgentScorer<Services>;

package/dist/wirings/gateway/gateway.types.d.ts

@@ -16,9 +16,13 @@ export interface GatewayAttachment {
 export interface GatewayInboundMessage {
     /** Platform-specific: a phone number, a Slack user id, and so on. */
     senderId: string;
+    /** What they said, as plain text, with the provider's markup stripped. */
     text: string;
+    /** The provider's own event, untouched, for anything this shape drops. */
     raw: unknown;
+    /** Files and media that came with the message. */
     attachments?: GatewayAttachment[];
+    /** Anything else the adapter wants to carry through to the wiring. */
     metadata?: Record<string, unknown>;
 }
 /**
@@ -26,8 +30,11 @@ export interface GatewayInboundMessage {
  * own rich content.
  */
 export interface GatewayOutboundMessage {
+    /** The reply as plain text. Every provider can render this. */
     text?: string;
+    /** The provider's own rich payload, e.g. Slack blocks. Passed through as-is. */
     richContent?: Record<string, unknown>;
+    /** Files and media to send alongside. */
     attachments?: GatewayAttachment[];
 }
 /**
@@ -35,9 +42,12 @@ export interface GatewayOutboundMessage {
  * provider expects back, or not.
  */
 export type WebhookVerificationResult = {
+    /** True when the request really came from the provider. */
     verified: true;
+    /** What to echo back, e.g. Meta's hub.challenge. */
     response: unknown;
 } | {
+    /** False when the signature or challenge did not check out. */
     verified: false;
 };
 /**
@@ -45,12 +55,15 @@ export type WebhookVerificationResult = {
  * message, send one back, and open and close the connection.
  */
 export interface GatewayAdapter {
+    /** Identifies the gateway in wirings and logs, e.g. `'slack'`. */
     name: string;
     /** Return null to ignore the event, e.g. a delivery receipt. */
     parse(data: unknown): GatewayInboundMessage | null;
+    /** Deliver a reply back to the sender the message came from. */
     send(senderId: string, message: GatewayOutboundMessage): Promise<void>;
     /** Called by GatewayService.start(); must call onMessage per incoming event. */
     init(onMessage: (data: unknown) => Promise<void>): Promise<void>;
+    /** Called by GatewayService.stop(); release the connection init() opened. */
     close(): Promise<void>;
     /** Receives the GET query params, or the POST body when called from the POST handler. */
     verifyWebhook?(data: unknown, request?: PikkuHTTPRequest): WebhookVerificationResult | Promise<WebhookVerificationResult>;

package/dist/wirings/persona/index.d.ts

@@ -18,5 +18,6 @@ export type { CorePersona, CorePersonas, PersonaAccountMeta, PersonaDefinitions,
  * Lambda deploy would load outright.
  */
 export { HttpPersona, createHttpPersonas, type HttpPersonasConfig, } from '../../services/http-personas.js';
-export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, type PersonaSignIn, type OperatorSignInOptions, type OperatorSessionResult, } from '../../services/persona-sign-in.js';
+export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, type ActorSecretResolver, type PersonaSignIn, type OperatorSignInOptions, type OperatorSessionResult, authMount, } from '../../services/persona-sign-in.js';
+export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from '../../services/persona-actor-secret.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/persona/index.js

@@ -14,5 +14,6 @@ export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './persona-
  * Lambda deploy would load outright.
  */
 export { HttpPersona, createHttpPersonas, } from '../../services/http-personas.js';
-export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, } from '../../services/persona-sign-in.js';
+export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, authMount, } from '../../services/persona-sign-in.js';
+export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from '../../services/persona-actor-secret.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/secret/secret.types.d.ts

@@ -1,8 +1,16 @@
 export type CoreSecret<T = unknown> = {
+    /** The key code reads it by: `secrets.getSecret('NAME')`. SCREAMING_SNAKE_CASE. */
     name: string;
+    /** How the secret is labelled wherever a person is asked to supply it. */
     displayName: string;
+    /** What this secret is for, shown beside the field someone has to fill in. */
     description?: string;
+    /** The id under the backing store, which is where the value actually lives. */
     secretId: string;
+    /**
+     * The shape of the value, as a schema. This is what types `getSecret`'s
+     * result — pass the schema itself, not an instance of it.
+     */
     schema: T;
     /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
     optional?: boolean;

package/knowledge/decisions/internals/a-virtual-user-cadence-is-a-row-not-a-timer.md

@@ -52,7 +52,7 @@ instances:
   different one, and every finding it produces is unreproducible.
 - **A run still `running` after `STALE_RUN_AFTER_MS` is failed and the persona
   runs again.** This is where the stranded-record cost of
-  [a virtual user run being neither a workflow nor a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md)
+  [a virtual user run not being a workflow](a-virtual-user-run-is-not-a-workflow-but-it-needs-a-trigger.md)
   gets paid: without it, one restart mid-run would block that persona's schedule
   permanently.
 

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-but-it-needs-a-trigger.md

@@ -0,0 +1,65 @@
+---
+type: decision
+title: A virtual user run is not a workflow, but it needs a trigger
+description: runVirtualUser writes its record and dispatches the run onto a queue at one attempt — an exploratory run has nothing to replay, but a deployment that puts each function in its own unit has nothing to fire it either
+tags: virtual-user, storage, deploy
+---
+
+# A virtual user run is not a workflow, but it needs a trigger
+
+`runVirtualUser` — the RPC `scaffold.virtualUser` generates — does three things
+in order: writes a `VirtualUserRunStore` record, dispatches
+`executeVirtualUserRun`, and returns the `runId`. The request never waits for
+the run; a run takes minutes and survives neither a rollout nor a proxy timeout.
+
+**A workflow** is still the wrong shape, for the reason it always was. Its value
+is that a run can be resumed at the step it died on, and that the same input
+reaches the same step. A virtual user is the opposite by construction — it is an
+LLM deciding what to try next, so no two attempts take the same steps, and there
+is no step to resume _to_. Recording a run as a workflow puts entries in the
+workflow store that can never be replayed, and gives every operator reading that
+store a row that lies about what it is. The seed makes a run _reproducible_ —
+run it again and it explores the same way — which is a different property from
+resumable, and one the record already carries.
+
+**A queue was rejected once, on durability, and that was the wrong question.**
+The original reasoning weighed a broker dependency against a retry nobody wants,
+and concluded the in-process dispatch was enough. It is enough in one process.
+It is not a dispatch at all under a deployment that puts each function in its own
+unit: there is no in-process promise to leave running, and `executeVirtualUserRun`
+— sessionless, unexposed, wired to nothing — is not a function any unit can be
+reached at. The RPC resolves to nothing, the rejection is swallowed by the
+`catch` that exists to stop it taking the process down, and the run parks at
+`running` with zero steps and no error anywhere. That is what a fabric stage did.
+
+So the queue is not bought for durability. It is bought because **a trigger is
+what makes a function deployable**: `wireQueueWorker` puts `executeVirtualUserRun`
+in the manifest, which gives it a unit and gives the platform somewhere to
+deliver to. The job is dispatched at `attempts: 1`, because a redelivery is a
+second different outing writing into a record that already has an outcome — the
+retry the queue offers is precisely the part that stays unused.
+
+A project with no queue service keeps the in-process dispatch. That is not a
+fallback that hides a failure: a project without a broker runs in one process,
+where an unawaited promise is a real dispatch and the only correct one.
+
+The record remains the run's only trace, and that is what `VirtualUserRunStore`
+exists for. It is also why `fail()` is a method rather than an absence: a run
+that crashed and a run that found nothing are different answers, and a record
+left at `running` is neither.
+
+The cost is smaller than it was but has not gone: **a restart mid-run strands a
+record at `running` with nothing left to finish it**, since nothing retries. A
+run older than its budget window and still `running` is dead, not working — a
+read-side rule. A stranded run is started again, with its seed if the caller
+wants the same exploration.
+
+Where that rule is actually applied is
+[the schedule tick](a-virtual-user-cadence-is-a-row-not-a-timer.md), which has
+to: a record stuck at `running` would otherwise block its persona's cadence
+forever.
+
+**What this rules out:** dispatching the run through `startWorkflow`; awaiting
+the engine inside the request; retrying a run that failed; storing the operator
+token on the record rather than on the dispatch; and inferring `status` from
+`finishedAt` being unset, which cannot separate a crash from a run still going.

package/knowledge/decisions/internals/index.md

@@ -17,7 +17,7 @@ caller is entitled to assume.
 - [A secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
 - [A virtual user decides whether to trust its notes once per turn, by one roll](a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md) — The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
 - [A virtual user cadence is a row, not a timer](a-virtual-user-cadence-is-a-row-not-a-timer.md) — how often a persona runs is stored as a due time per persona and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
-- [A virtual user run is not a workflow and not a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md) — runVirtualUser writes its record, dispatches the run without awaiting it, and returns the id — because an exploratory run has nothing to replay and the record already carries what a queue would be holding
+- [A virtual user run is not a workflow, but it needs a trigger](a-virtual-user-run-is-not-a-workflow-but-it-needs-a-trigger.md) — runVirtualUser writes its record and dispatches the run onto a queue at one attempt — an exploratory run has nothing to replay, but a deployment that puts each function in its own unit has nothing to fire it either
 - [A wall-clock threshold is a load test in disguise](a-wall-clock-threshold-is-a-load-test-in-disguise.md) — The KEK derivation test asserted a fixed 50ms budget for work that took 10ms, which went red about one run in five once the suite was large enough to compete for the machine
 - [A workflow's wire is built from the run record, not from the RPC service](a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md) — The RPC service exposes no wire, so every rpcService.wire read was undefined; the run record is the only thing that carries the caller across a step boundary
 - [An actor conversation starts from a seeded kickoff message](actor-flow-conversations-seed-a-hidden-kickoff-message.md) — The actor's first turn needs a non-empty message list because providers reject an empty prompt; the seed is an instruction and stays out of the transcript