@pikku/core 0.12.98 → 0.12.99

package/CHANGELOG.md

@@ -1,3 +1,54 @@
+## 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.
      *

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,12 +39,17 @@ 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>;
 }

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) {

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, } 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

@@ -15,4 +15,5 @@ export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './persona-
  */
 export { HttpPersona, createHttpPersonas, } from '../../services/http-personas.js';
 export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, } 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

package/knowledge/decisions/security/actor-sign-in-only-works-for-actor-flagged-users.md

@@ -1,27 +1,31 @@
 ---
 type: decision
 title: Actor sign-in only works for actor-flagged users
-description: The scenario actor secret mints sessions for user rows flagged actor and nothing else, so holding it never impersonates a real user
+description: An actor credential mints sessions for user rows flagged actor and nothing else, so holding one never impersonates a real user
 tags: services
 ---
 
 # Actor sign-in only works for actor-flagged users
 
-`HttpScenarioActorsConfig.secret`
-(`packages/core/src/services/http-scenario-actors.ts`) is a shared impersonation
-secret: `HttpScenarioActor.login` POSTs `{ email, name, secret }` to
+`HttpPersonasConfig.secret` (`packages/core/src/services/http-personas.ts`) is
+what `ActorSignIn.login` presents: it POSTs `{ email, name, secret }` to
 `/auth/sign-in/actor` and gets back a session. That looks like a master key, and
-it deliberately is not one.
+it deliberately is not one — for two independent reasons.
 
-The Better Auth actor plugin on the other end upserts and signs in only user rows
-flagged `actor: true`. Presenting the secret with a real customer's email does not
-mint that customer's session — it is refused. The `actor` flag also flows into the
-minted session, so audits and analytics can tell scenario traffic from human
-traffic after the fact. The blast radius of a leaked actor secret is therefore the
-synthetic actor population, not the user table.
+The first is the flag. The Better Auth actor plugin on the other end upserts and
+signs in only user rows flagged `actor: true`. Presenting a credential with a
+real customer's email does not mint that customer's session — it is refused. The
+`actor` flag also flows into the minted session, so audits and analytics can tell
+scenario traffic from human traffic after the fact.
+
+The second is that a credential is not shared. What is presented is derived from
+the root `SCENARIO_ACTOR_SECRET` and the address it signs in as — see
+[an actor credential is derived per persona](an-actor-credential-is-derived-per-persona.md) —
+so the blast radius of a leaked credential is one synthetic account, not the
+synthetic actor population.
 
 **What this rules out:** widening the sign-in endpoint to accept any email "so
-scenarios can test as a real user", and treating the actor secret as equivalent to
-a session-signing key. It also rules out dropping the `actor` flag from the minted
-session — the audit trail's ability to separate synthetic from real activity
-depends on it.
+scenarios can test as a real user", and treating an actor credential as
+equivalent to a session-signing key. It also rules out dropping the `actor` flag
+from the minted session — the audit trail's ability to separate synthetic from
+real activity depends on it.

package/knowledge/decisions/security/an-actor-credential-is-derived-per-persona.md

@@ -0,0 +1,41 @@
+---
+type: decision
+title: An actor credential is derived per persona
+description: What a caller presents to the actor endpoint is HKDF-derived from the root secret and the address it signs in as, so one credential opens one persona
+tags: services
+---
+
+# An actor credential is derived per persona
+
+`SCENARIO_ACTOR_SECRET` is a root, not a password. What a caller presents to
+`/auth/sign-in/actor` is `deriveActorSecret(root, email)`
+(`packages/core/src/services/persona-actor-secret.ts`) — an HKDF-expanded
+HMAC-SHA256 over the lowercased address, on the same key-material primitives
+everything else in core signs with. The endpoint does not store or look anything
+up: it re-derives the expected value for whichever address is being signed in as
+and compares. A credential minted for one persona is refused for every other.
+
+The root itself is not accepted as a credential, and a root shorter than 32
+characters refuses the endpoint outright rather than deriving weak credentials
+from it. The server-side warning names the problem; what the client is told does
+not.
+
+Derivation rather than a per-persona secrets table because there is then nothing
+to store, provision, or keep in sync — the target already holds the root, and
+rotating it invalidates every credential at once.
+
+This is what lets a holder be handed less than everything:
+
+- The browser switcher gets `VITE_DEV_ACTOR_SECRETS`, one credential per
+  declared persona. The root stays on the dev server, so a bundle can no longer
+  hold the thing that is entitled to every persona.
+- A run can be given `PIKKU_PERSONA_SECRETS` (`id=secret,…`, minted with
+  `pikku persona secret`) instead of the root, and then it can sign in as those
+  personas and no others. Asking for one outside the list throws naming the
+  persona rather than falling back to the root.
+
+**What this rules out:** accepting the root as a credential at the endpoint,
+putting the root in any client bundle, and comparing a presented credential
+against a stored one. It also rules out per-persona secrets that are generated
+randomly and written down — the derivation is the reason there is nothing to
+provision.

package/knowledge/decisions/security/index.md

@@ -19,7 +19,8 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [A workflow run is read and approved by its owner](a-workflow-run-is-read-and-approved-by-its-owner.md) — A run started through a session records that user and only that user may read it or answer its approval gates; a run with no recorded owner has no ownership to enforce
 - [An actor's missing approval decision defaults to denied](actor-flow-missing-approval-decisions-default-to-denied.md) — Every pending tool call gets an explicit decision; an id the persona LLM omitted is denied, so a dropped field can never read as consent
 - [Actor sign-in is proven by Set-Cookie, not a non-empty jar](actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md) — HttpScenarioActor tracks its own signedIn flag and requires the sign-in response itself to set a cookie, because a populated jar proves nothing
-- [Actor sign-in only works for actor-flagged users](actor-sign-in-only-works-for-actor-flagged-users.md) — The scenario actor secret mints sessions for user rows flagged actor and nothing else, so holding it never impersonates a real user
+- [Actor sign-in only works for actor-flagged users](actor-sign-in-only-works-for-actor-flagged-users.md) — An actor credential mints sessions for user rows flagged actor and nothing else, so holding one never impersonates a real user
+- [An actor credential is derived per persona](an-actor-credential-is-derived-per-persona.md) — What a caller presents to the actor endpoint is HKDF-derived from the root secret and the address it signs in as, so one credential opens one persona
 - [Addon auth and tags only tighten, and resolve where the function runs](addon-auth-and-tags-only-tighten.md) — wireAddon auth and tags are applied in runPikkuFunc like scopes, but auth:false is ignored and tags resolve against the consuming app's tag groups rather than the addon package's
 - [Addon auth and tag gates apply wherever the function runs, including inside the addon](addon-config-gates-apply-only-at-the-namespaced-rpc-boundary.md) — wireAddon's auth and tags moved from the namespaced RPC boundary into runPikkuFunc, so they also apply to direct wirings and to bare intra-addon calls
 - [Addon scopes are resolved where the function runs](addon-scopes-are-resolved-where-the-function-runs.md) — wireAddon scopes are merged inside runPikkuFunc rather than at namespace resolution, because most wirings reach an addon function without ever resolving a namespace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.98",
+  "version": "0.12.99",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -18,12 +18,12 @@
   },
   "sideEffects": [
     "./dist/errors/errors.js",
-    "./dist/wirings/rpc/rpc-runner.js",
     "./dist/wirings/addon/remote-addon-auth.js",
+    "./dist/wirings/rpc/rpc-runner.js",
+    "./dist/wirings/workflow/pikku-scenario-service.js",
     "./dist/wirings/workflow/workflow-approval-policy.js",
     "./dist/wirings/workflow/workflow-errors.js",
-    "./dist/wirings/workflow/workflow-run-ownership.js",
-    "./dist/wirings/workflow/pikku-scenario-service.js"
+    "./dist/wirings/workflow/workflow-run-ownership.js"
   ],
   "exports": {
     ".": "./dist/bootstrap-compat/root.js",