@pikku/core 0.12.97 → 0.12.99

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/data-lock/data-lock-wiring.d.ts

@@ -0,0 +1,40 @@
+import type { DataLock, LockState } from '../../classification/data-lock.js';
+export type DataLockStatus = {
+    state: LockState;
+    /**
+     * Milliseconds before another guess will be looked at, or 0.
+     *
+     * The unlock screen shows this as a countdown; without it the only way to
+     * learn the wait is over is to guess again, and a guess made during a
+     * lockout is itself a failure that extends it.
+     */
+    retryAfterMs: number;
+};
+export type DataLockWiringOptions = {
+    /** Where the lock routes are mounted. Defaults to `/_pikku/data`. */
+    prefix?: string;
+    /**
+     * Which keys first-run initialization mints. Derive it with
+     * `keyIdsFromManifest`.
+     *
+     * It is fixed here rather than sent by the caller because the unlock screen
+     * posts a passphrase and nothing else — and because a key the schema names
+     * but nobody minted does not fail at startup, it fails at the first write to
+     * that one column.
+     */
+    keyIds?: string[];
+};
+/**
+ * Puts the passphrase gate on HTTP, so unlocking is a page in the app rather
+ * than a prompt in whatever happens to have launched the server.
+ *
+ * That is what lets one story cover both shapes pikku ships in: a desktop
+ * build whose window is pointed at the local server, and a headless
+ * `pikku serve` somewhere else, unlock the same way and share the unlock
+ * screen. A native prompt in the desktop shell would have left the headless
+ * case with nothing.
+ *
+ * The routes are registered here rather than generated because they belong to
+ * core: an app has no source file for them to be discovered in.
+ */
+export declare const wireDataLock: (lock: DataLock, { prefix, keyIds }?: DataLockWiringOptions) => void;

package/dist/wirings/data-lock/data-lock-wiring.js

@@ -0,0 +1,77 @@
+import { pikkuState } from '../../pikku-state.js';
+import { wireHTTP } from '../http/http-runner.js';
+import { httpRouter } from '../http/routers/http-router.js';
+const helperFunctionMeta = (funcId) => ({
+    pikkuFuncId: funcId,
+    sessionless: true,
+    functionType: 'helper',
+    inputSchemaName: null,
+    outputSchemaName: null,
+});
+const DEFAULT_PREFIX = '/_pikku/data';
+/**
+ * Puts the passphrase gate on HTTP, so unlocking is a page in the app rather
+ * than a prompt in whatever happens to have launched the server.
+ *
+ * That is what lets one story cover both shapes pikku ships in: a desktop
+ * build whose window is pointed at the local server, and a headless
+ * `pikku serve` somewhere else, unlock the same way and share the unlock
+ * screen. A native prompt in the desktop shell would have left the headless
+ * case with nothing.
+ *
+ * The routes are registered here rather than generated because they belong to
+ * core: an app has no source file for them to be discovered in.
+ */
+export const wireDataLock = (lock, { prefix = DEFAULT_PREFIX, keyIds } = {}) => {
+    const status = () => ({
+        state: lock.state,
+        retryAfterMs: lock.retryAfterMs,
+    });
+    register(prefix, 'get', '/status', 'pikkuDataLockStatus', async () => status());
+    register(prefix, 'post', '/initialize', 'pikkuDataLockInitialize', async (_services, { passphrase }) => {
+        await lock.initialize(passphrase, keyIds);
+        return status();
+    });
+    register(prefix, 'post', '/unlock', 'pikkuDataLockUnlock', async (_services, { passphrase }) => {
+        await lock.unlock(passphrase);
+        return status();
+    });
+    register(prefix, 'post', '/lock', 'pikkuDataLockLock', async (_services, { passphrase }) => {
+        // Locking proves ownership first. An open POST here would be a
+        // one-request denial of service: the store shuts and stays shut until
+        // someone is around to type the passphrase back in.
+        await lock.unlock(passphrase);
+        lock.lock();
+        return status();
+    });
+    // A router that has already compiled its table would otherwise answer 404
+    // for everything registered after it woke up.
+    httpRouter.reset();
+};
+const register = (prefix, method, path, funcId, func) => {
+    const route = `${prefix}${path}`;
+    const routes = pikkuState(null, 'http', 'routes');
+    if (routes.get(method)?.has(route)) {
+        return;
+    }
+    const httpMeta = pikkuState(null, 'http', 'meta');
+    httpMeta[method][route] = {
+        pikkuFuncId: funcId,
+        route,
+        method,
+        // Never a session. The gate cannot sit in front of its own key: a session
+        // may itself live in a column this lock is holding shut.
+        auth: false,
+        requiresSession: false,
+    };
+    const functionsMeta = pikkuState(null, 'function', 'meta');
+    if (!functionsMeta[funcId]) {
+        functionsMeta[funcId] = helperFunctionMeta(funcId);
+    }
+    wireHTTP({
+        method,
+        route,
+        func: { func },
+        auth: false,
+    });
+};

package/dist/wirings/data-lock/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The HTTP face of {@link DataLock}: the routes an unlock screen talks to.
+ *
+ * Separate from `@pikku/core/classification` on purpose — that entry point is
+ * types and crypto, and a runtime that never serves HTTP should not have to
+ * load a router to use it.
+ */
+export { wireDataLock } from './data-lock-wiring.js';
+export type { DataLockStatus, DataLockWiringOptions, } from './data-lock-wiring.js';

package/dist/wirings/data-lock/index.js

@@ -0,0 +1,8 @@
+/**
+ * The HTTP face of {@link DataLock}: the routes an unlock screen talks to.
+ *
+ * Separate from `@pikku/core/classification` on purpose — that entry point is
+ * types and crypto, and a runtime that never serves HTTP should not have to
+ * load a router to use it.
+ */
+export { wireDataLock } from './data-lock-wiring.js';

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/dist/wirings/virtual-user/virtual-user-scaffold.d.ts

@@ -4,6 +4,7 @@ import type { VariablesService } from '../../services/variables-service.js';
 import type { AgentRunnerService } from '../../services/agent-runner-service.js';
 import type { HttpPersonasConfig } from '../../services/http-personas.js';
 import type { ResolvedPersona, ScenarioPersonas } from '../../services/personas-service.js';
+import type { PersonaEnvironment } from '../persona/persona-environments.js';
 import type { StepRecord, VirtualUserDisposition } from './virtual-user.types.js';
 import type { VirtualUserRunRecord, VirtualUserRunStore } from './virtual-user-run-store.js';
 import type { VirtualUserScheduleRecord, VirtualUserScheduleStore } from './virtual-user-schedule-store.js';
@@ -84,10 +85,15 @@ export interface StartVirtualUserRunParams {
     /**
      * The app's config, read only for `nodeEnv` — structural because an
      * application's Config is its own interface and need not declare it at all.
+     * The fallback signal, used only by a project that configures no environments.
      */
     config: {
         nodeEnv?: string;
     } | undefined;
+    /** `environments` from pikku.config.json, as generated beside the personas. */
+    environments?: Readonly<Record<string, PersonaEnvironment>>;
+    /** Which of them this process is. Defaults to `PIKKU_ENV`. */
+    environment?: string;
     persona: string;
     disposition?: string;
     seed?: number;
@@ -112,7 +118,7 @@ export interface StartedVirtualUserRun {
  * scheduled tick have in common. The dispatch that follows is typed off the
  * app's RPC map, so it stays in the generated wiring.
  */
-export declare const startVirtualUserRun: ({ store, personas, config, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }: StartVirtualUserRunParams) => Promise<StartedVirtualUserRun>;
+export declare const startVirtualUserRun: ({ store, personas, config, environments, environment, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }: StartVirtualUserRunParams) => Promise<StartedVirtualUserRun>;
 /**
  * One run on the wire.
  *

package/dist/wirings/virtual-user/virtual-user-scaffold.js

@@ -85,6 +85,28 @@ export const requireVirtualUserScheduleStore = (store) => {
     }
     return store;
 };
+/**
+ * Whether this process is running against production, for the disposition rule.
+ *
+ * The configured environment wins over `NODE_ENV` because they answer different
+ * questions. A deployment whose staging is a production *mirror* runs
+ * `NODE_ENV=production` there too — keying on it refuses every disposition on
+ * the one environment they exist to be used on. `PIKKU_ENV` names which of the
+ * configured environments this is, which is the question actually being asked,
+ * and it is the same signal `personaEnvironmentRefusal` already checks at
+ * sign-in.
+ *
+ * Unresolved is treated as production: an environment nobody can name is one
+ * whose data nobody can vouch for. `NODE_ENV` remains the answer only for a
+ * project that configures no environments at all, which has no production
+ * environment declared for this to be wrong about.
+ */
+const isProductionRun = (config, environments, environment) => {
+    if (!environments || Object.keys(environments).length === 0) {
+        return config?.nodeEnv === 'production';
+    }
+    return environment ? Boolean(environments[environment]?.production) : true;
+};
 /**
  * Resolves a request against the declaration and records the run.
  *
@@ -92,7 +114,7 @@ export const requireVirtualUserScheduleStore = (store) => {
  * scheduled tick have in common. The dispatch that follows is typed off the
  * app's RPC map, so it stays in the generated wiring.
  */
-export const startVirtualUserRun = async ({ store, personas, config, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
+export const startVirtualUserRun = async ({ store, personas, config, environments, environment = process.env.PIKKU_ENV, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
     const runStore = requireVirtualUserRunStore(store);
     const persona = runnablePersona(personas, personaId);
     const disposition = (requested ??
@@ -101,8 +123,8 @@ export const startVirtualUserRun = async ({ store, personas, config, persona: pe
     // Every disposition other than this one exists to find out what the product
     // does wrong, which is not a thing to do to real customers' data. Checked
     // against the effective disposition, so an override cannot smuggle one in.
-    if (config?.nodeEnv === 'production' &&
-        disposition !== PRODUCTION_DISPOSITION) {
+    if (disposition !== PRODUCTION_DISPOSITION &&
+        isProductionRun(config, environments, environment)) {
         throw new Error(`Only the '${PRODUCTION_DISPOSITION}' disposition may run against production; "${personaId}" is ${disposition}`);
     }
     // Seeded here rather than inside the engine so the record carries the seed

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.97",
+  "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",

package/src/classification/data-classification.ts

@@ -54,6 +54,16 @@ export interface ColumnClassification {
   anonymize_strategy: AnonymizeStrategy
   /** At-rest representation. Absent means `plain`. */
   form?: ColumnForm
+  /**
+   * Which key protects this column, for a `wrapped` or `sealed` form. Absent
+   * means the deployment's default key.
+   *
+   * It is a purpose, not a tenant: naming one here says "these columns open
+   * together and separately from the rest", so the key that opens notes need
+   * not open credentials. The id is stored in the value, so a column that
+   * changes key is a rewrap rather than a migration.
+   */
+  keyId?: string
   description?: string
 }
 

package/src/classification/index.ts

@@ -36,3 +36,5 @@ export {
   isSecretValue,
 } from './secret-value.js'
 export type { Safe } from './secret-value.js'
+
+export { DEFAULT_KEY_ID } from './key-ids.js'

package/src/classification/key-ids.ts

@@ -0,0 +1,2 @@
+/** The key a column protects itself with when it names none. */
+export const DEFAULT_KEY_ID = 'default'

package/src/middleware/index.ts

@@ -7,7 +7,6 @@ export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js'
 export { telemetryOuter, telemetryInner } from './telemetry.js'
 export {
   addTagMiddleware,
-  addTagMiddleware as addMiddleware,
   addGlobalMiddleware,
   runMiddleware,
 } from '../middleware-runner.js'