@pikku/core 0.12.141 → 0.12.142

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -3,7 +3,7 @@ import type { ScenarioArtifact } from './scenario-run.types.js';
  * Scenario steps: named, typed units of scenario behaviour.
  *
  * A step's body is an ordinary pikku function, so it may drive a browser, call
- * an RPC as its actor, or run a workflow. `given` and `when` differ only in the
+ * an RPC as its virtual user, or run a workflow. `given` and `when` differ only in the
  * prose the reporter renders; `then` also changes what runs, because its
  * bindings are witnesses — every declared surface is observed and the
  * observations must agree. See {@link ScenarioSurfaceResolution}.
@@ -20,7 +20,7 @@ export type ScenarioStepPhase = 'given' | 'when' | 'then';
 /**
  * Who acts in a step.
  *
- * `persona` is a person driving the system through one of its surfaces — the
+ * `virtualUser` is a person driving the system through one of its surfaces — the
  * ordinary `pikkuScenarioStep`. `platform` is the app acting on itself ("the
  * platform has expired the trial"), and `addon` is a third-party system acting
  * on it ("Stripe's webhook arrives"), contributed by the addon that wraps that
@@ -31,9 +31,9 @@ export type ScenarioStepPhase = 'given' | 'when' | 'then';
  * trusting a string literal — and so an addon package exports only addon steps,
  * which is checkable.
  */
-export type ScenarioStepKind = 'persona' | 'platform' | 'addon';
+export type ScenarioStepKind = 'virtualUser' | 'platform' | 'addon';
 /**
- * How an actor drives the system for one step.
+ * How a virtual user drives the system for one step.
  *
  * A step declares one implementation per surface it supports, and the runner
  * picks between them — so the same ladder can run through a real browser, over
@@ -87,10 +87,10 @@ export type ScenarioSurfaceResolution = {
  */
 export interface ScenarioStepOptions {
     /**
-     * The actor this step runs as. Required for a step that declares `actor: true`
+     * The virtual user this step runs as. Required for a step that declares `virtualUser: true`
      * or a `browser` binding; the runner refuses to dispatch one without it.
      */
-    actor?: unknown;
+    virtualUser?: unknown;
     /** Overrides the step's own `description` for this call site only. */
     description?: string;
     /** Defaults to 0 for steps — a failed assertion must not be retried. */
@@ -110,7 +110,7 @@ export interface ScenarioEnvironment {
 /**
  * The `scenarioStep` wire, present on every scenario step invocation.
  *
- * The persona a step runs as is not here: it arrives as `wire.actor`, injected
+ * The virtual user a step runs as is not here: it arrives as `wire.virtualUser`, injected
  * by the runner and typed as present exactly on the bindings that declared they
  * need one. Keeping it off this interface is what makes that possible — a wire
  * member can be required per binding, a property of one cannot.
@@ -178,10 +178,10 @@ export interface ScenarioScreenshotOptions {
     fullPage?: boolean;
 }
 /**
- * One actor's browser session, handed to a step as `wire.browser`.
+ * One virtual user's browser session, handed to a step as `wire.browser`.
  *
- * Every actor gets their own, so a two-actor scenario drives two sessions and
- * `screenshot` files each shot under the actor it belongs to.
+ * Every virtual user gets their own, so a two-virtual-user scenario drives two sessions and
+ * `screenshot` files each shot under the virtual user it belongs to.
  *
  * Only what every driver can honour is declared here. A driver package adds
  * the rest by declaration-merging onto this interface — `@pikku/playwright`
@@ -189,21 +189,21 @@ export interface ScenarioScreenshotOptions {
  * structural surface keeps working whichever driver runs it.
  */
 export interface PikkuBrowserWire {
-    /** The actor whose browser context this is */
-    readonly actor: string;
+    /** The virtual user whose browser context this is */
+    readonly virtualUser: string;
     goto(url: string): Promise<void>;
     screenshot(name?: string, options?: ScenarioScreenshotOptions): Promise<Uint8Array>;
 }
 /**
- * What one actor's window looked like at the moment a scenario failed.
+ * What one virtual user's window looked like at the moment a scenario failed.
  *
  * A browser step fails with a selector timeout that says nothing about *why*
  * the page never rendered. The answer is almost always in the page's own
  * errors, which the driver has been collecting all along.
  */
 export interface ScenarioBrowserFailure {
-    /** The actor whose window this is. */
-    actor: string;
+    /** The virtual user whose window this is. */
+    virtualUser: string;
     /** Where the window was pointed, when the driver can still report it. */
     url?: string;
     /** Path the screenshot was written to; absent when none could be taken. */
@@ -222,10 +222,10 @@ export interface ScenarioBrowserFailure {
  * one that simply offers no isolation and no diagnostics.
  */
 export interface ScenarioBrowserProvider {
-    /** Resolve — creating on first use — the browser session for an actor. */
-    sessionFor(actorName: string): Promise<PikkuBrowserWire>;
+    /** Resolve — creating on first use — the browser session for a virtual user. */
+    sessionFor(virtualUserName: string): Promise<PikkuBrowserWire>;
     /**
-     * Discard every actor's per-scenario state — cookies, storage, open pages —
+     * Discard every virtual user's per-scenario state — cookies, storage, open pages —
      * while keeping the browser itself. Called between scenarios, so one
      * scenario cannot leave the next signed in as somebody else.
      */
@@ -247,23 +247,23 @@ export interface ScenarioBrowserProvider {
      */
     endScenario?(outcome: 'passed' | 'failed'): void;
     /**
-     * When this actor's recording started, as epoch milliseconds.
+     * When this virtual user's recording started, as epoch milliseconds.
      *
      * The seam that keeps the video clock out of `@pikku/core`: a driver knows
      * when it opened the context it passed `recordVideo` to, and the runner turns
-     * that into a per-step offset. Absent for an actor with no window open, and
+     * that into a per-step offset. Absent for a virtual user with no window open, and
      * for a run recording nothing — both of which leave the step's offset off.
      */
-    videoStartedAt?(actorName: string): number | undefined;
+    videoStartedAt?(virtualUserName: string): number | undefined;
     /**
-     * Mark a browser step starting in this actor's recording, answering where it
+     * Mark a browser step starting in this virtual user's recording, answering where it
      * falls in the finished video (ms).
      *
      * Preferred over `videoStartedAt` when present: a driver that edits its
      * footage afterwards — holding each step's screen still, say — is the only
      * one that knows how far that moves the step. Undefined when nothing records.
      */
-    markVideoStep?(actorName: string): number | undefined;
+    markVideoStep?(virtualUserName: string): number | undefined;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must

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

@@ -193,7 +193,7 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
      */
     asserts?: boolean;
     skip?: string;
-    actors?: string[];
+    virtualUsers?: string[];
 }>;
 export interface WorkflowRuntimeMeta {
     name: string;
@@ -201,7 +201,7 @@ export interface WorkflowRuntimeMeta {
     source: 'dsl' | 'complex' | 'graph' | 'scenario';
     description?: string;
     tags?: string[];
-    actors?: string[];
+    virtualUsers?: string[];
     nodes?: Record<string, any>;
     entryNodeIds?: string[];
     graphHash?: string;

package/knowledge/decisions/index.md

@@ -14,8 +14,6 @@ here first — several of these exist because the obvious simplification was tri
 and broke something.
 
 <!-- pikku:knowledge-index -->
-
 - [internals](internals/index.md) — a rule about how it works under the hood, and why
 - [security](security/index.md) — a rule about who may do what
-
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/internals/a-credential-name-declared-twice-must-agree-on-schema-and-type.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: A credential name declared twice must agree on its schema and its type
+description: validateAndBuildCredentialDefinitionsMeta throws when two declarations of one credential name differ in schema or in type, and otherwise keeps the first declaration
+tags: core, credentials, validation
+---
+
+# A credential name declared twice must agree on its schema and its type
+
+`packages/core/src/wirings/credential/validate-credential-definitions.ts` builds
+the credential metadata, keyed by name.
+
+When a name repeats, the schema is compared first, but only if both declarations
+resolve to a schema reference (`validate-credential-definitions.ts:19-23`). Two
+references differ when their variable name or source file differs
+(`validate-credential-definitions.ts:24-27`). A difference throws, and the message
+says "Credentials sharing a name must use the same schema"
+(`validate-credential-definitions.ts:28-33`).
+
+The `type` field is then compared (`validate-credential-definitions.ts:38-45`).
+The type is `'singleton' | 'wire'` (`credential.types.ts:26`). A different type
+throws with the message "Credentials sharing a name must use the same type"
+(`validate-credential-definitions.ts:43`).
+
+When both checks pass, the repeat is skipped and the first declaration stays
+(`validate-credential-definitions.ts:47`).
+
+**What this rules out:** two addons declaring the same credential name with
+different schemas or read modes, and a silent choice between them.

package/knowledge/decisions/internals/a-grant-can-name-a-scope-declared-without-its-addon.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: declareScopes lets an app grant a scope whose addon it does not wire
+description: defineScope is a no-op read by the CLI, and declareScopes declares scope ids so a grant is valid without wiring the addon that owns the scope tree
+tags: core, scopes, addons, codegen
+---
+
+# declareScopes lets an app grant a scope whose addon it does not wire
+
+`packages/core/src/wirings/scope/define-scope.ts` has two declaration functions,
+both with empty bodies.
+
+`defineScope` is a no-op that "tree-shakes away". The CLI reads the call by AST and
+generates a `ScopeId` union, so a function that names an undeclared scope fails to
+build (`define-scope.ts:3-6`, `33`).
+
+`declareScopes` takes a list of ids (`define-scope.ts:53`). Its doc comment says it
+exists so that an app can grant a scope, in a system role or a function's
+`scopes`, whose tree belongs to an addon the app has not wired
+(`define-scope.ts:36-42`). Each id declares that node and its ancestors
+(`define-scope.ts:44`). When the addon is wired, its own description wins, and the
+two calls "never conflict, unlike a second `defineScope` for the same root"
+(`define-scope.ts:44-46`).
+
+The example is `declareScopes(['pikku:console'])` (`define-scope.ts:49-51`).
+
+**What this rules out:** declaring the same scope root with `defineScope` in two
+places, which the doc says conflicts, and making a grant valid only by wiring the
+addon that owns it.

package/knowledge/decisions/internals/a-scheduled-task-writes-its-caller-session-before-it-runs.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A scheduled task writes its caller's session to the session store before it runs
+description: runScheduledTask stores the session it is passed, or nothing, before it looks up the task, so the run uses only a session its caller supplied
+tags: core, scheduler, sessions
+---
+
+# A scheduled task writes its caller's session to the session store before it runs
+
+`runScheduledTask` in `packages/core/src/wirings/scheduler/scheduler-runner.ts:70-87`
+takes an optional `session`. It builds a `PikkuSessionService` on the session store
+(`:84`), and when a session was passed it calls `userSession.set(session)` (`:85-87`).
+Nothing else in the function sets a session. The task and its meta are looked up
+afterwards (`:89-96`), so a missing task still leaves the session written.
+
+The in-repo caller of this path, `packages/schedule/src/in-memory-scheduler-service.ts:163`,
+passes only `{ name }`, so a cron run has no session.
+
+**What this rules out:** a scheduled run taking a session from anywhere other than
+its caller, and any default system session being set by this function.
+`questions/does-a-delayed-rpc-run-as-the-session-it-was-scheduled-with.md` records a
+related gap in the delayed-RPC path.

package/knowledge/decisions/internals/a-secret-set-in-memory-shadows-the-variable-of-the-same-name.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: A secret set in memory shadows the variable of the same name
+description: LocalSecretService reads its in-memory map before the variables service, stores a SecretValue unwrapped, and treats an empty string as absent
+tags: core, secrets, local-dev
+---
+
+# A secret set in memory shadows the variable of the same name
+
+`packages/core/src/services/local-secrets.ts` keeps an in-memory map of secrets.
+`getSecret` checks that map first (`local-secrets.ts:25-29`). Only when the key is
+missing or empty does it fall back to the variables service
+(`local-secrets.ts:31-34`), and it throws if neither has the key
+(`local-secrets.ts:35`). `hasSecret` follows the same order (`local-secrets.ts:49-52`).
+
+Values are parsed as JSON when possible and kept as the raw string otherwise
+(`local-secrets.ts:13-19`).
+
+`setSecret` unwraps a `SecretValue` before storing it (`local-secrets.ts:38-45`).
+The comment gives the reason: storing the wrapper "would serialize it to
+'[secret]'" (`local-secrets.ts:39`).
+
+`deleteSecret` removes only the in-memory entry (`local-secrets.ts:56-58`), so a
+variable of the same name becomes visible again after a delete.
+
+**What this rules out:** a secret written through `setSecret` being replaced by
+the value of a variable with the same name, and storing a redacted wrapper in
+place of the secret.

package/knowledge/decisions/internals/a-virtual-user-acts-through-invokeraw-so-a-refusal-is-data.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: A virtual user acts through invokeRaw, so a refusal is data it can act on
+description: virtualUserTarget calls virtualUser.invokeRaw, which signs the virtual user in when needed, retries once after a 401, and returns the status instead of throwing
+tags: core, virtual-users
+---
+
+# A virtual user acts through invokeRaw, so a refusal is data it can act on
+
+`virtualUserTarget` in `packages/core/src/wirings/virtual-user/virtual-user-target.ts`
+is "the only place the engine meets the network" (`virtual-user-target.ts:14`). It
+drives a signed-in virtual user. The doc comment says the virtual user keeps its
+cookies, re-logs in when a session expires mid-run, and reports status as data
+rather than throwing (`virtual-user-target.ts:14-17`).
+
+The call goes through `virtualUser.invokeRaw(rpcName, args)` (`virtual-user-target.ts:27`).
+The comment gives the reason: "to a virtual user a 403 is not an error, it is the
+system saying no, which is information it should be allowed to act on"
+(`virtual-user-target.ts:19-22`).
+
+In `HttpVirtualUser.invokeRaw`, the virtual user signs in first if it is not signed
+in (`packages/core/src/services/http-virtual-users.ts:117-119`). On a 401 it signs
+in again and retries once (`http-virtual-users.ts:121-126`). The method returns the
+response for every status.
+
+The virtual user's target passes no per-call options, so it cannot add a header
+(`virtual-user-target.ts:27`). That is covered in
+[a scenario step can name an identity no virtual user holds, through per-call headers](../security/a-step-can-name-an-identity-no-virtual-user-holds-through-per-call-headers.md).
+
+**What this rules out:** a virtual user calling `invoke`, which throws on error, and
+a virtual user being given per-call headers. For why `invokeRaw` returns status rather
+than throwing, see [in a scenario a 4xx is data, not an exception](in-a-scenario-a-4xx-is-data-not-an-exception.md).

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

@@ -1,29 +1,29 @@
 ---
 type: decision
 title: A virtual user cadence is a row, not a timer
-description: 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
+description: How often a virtual user runs is stored as a due time per virtual user and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
 tags: virtual-user, storage, scheduling
 ---
 
 # A virtual user cadence is a row, not a timer
 
-A run has a budget; a persona has a cadence. The two get confused because both
+A run has a budget; a virtual user has a cadence. The two get confused because both
 answer "how often", and neither answers the other's question: a budget caps one
 outing, and raising it only buys a more tired user. What tells you about a
 product is the same person coming back over a fortnight.
 
-That cadence is one row per persona in `virtualUserSchedule`, holding
+That cadence is one row per virtual user in `virtualUserSchedule`, holding
 `nextRunAt`. `tickVirtualUserSchedules` acts on whichever rows are due. There is
 no timer, no interval, and no in-memory loop.
 
 **Not a timer**, because a process holding the next run in its own heap forgets
-it on the next deploy, and the persona silently stops — with nothing anywhere
+it on the next deploy, and the virtual user silently stops — with nothing anywhere
 saying it used to run. The row survives restarts, and any instance can act on
 it.
 
 **Not reschedule-on-completion**, which is the tempting shape: finish a run,
 draw a delay, schedule the next. It has exactly one failure mode and it is
-fatal — a crash between the two ends the persona forever, and the evidence is an
+fatal — a crash between the two ends the virtual user forever, and the evidence is an
 absence. A due time written down before the run starts cannot be lost by the run
 failing.
 
@@ -36,8 +36,8 @@ may not even run schedulers. One line in the project turns it on:
 wireScheduler({ name: 'virtualUsers', schedule: '0 * * * *', func: tickVirtualUserSchedules })
 ```
 
-Tick resolution bounds how *late* a due persona is, never how often it runs — a
-persona due at 09:07 under an hourly tick starts at 10:00. Running the tick more
+Tick resolution bounds how *late* a due virtual user is, never how often it runs — a
+virtual user due at 09:07 under an hourly tick starts at 10:00. Running the tick more
 often costs one indexed query and changes no cadence.
 
 Three rules make a tick safe to run at any resolution, from any number of
@@ -46,14 +46,14 @@ instances:
 - **The due time is written before the run is dispatched**, so a tick that dies
   halfway cannot leave the row due for the next one to pick up again. A dispatch
   that throws therefore waits a full interval, which is the right way round: a
-  persona failing to start should not be retried every minute for a week.
-- **A persona whose previous run is still `running` is skipped, not queued.**
+  virtual user failing to start should not be retried every minute for a week.
+- **A virtual user whose previous run is still `running` is skipped, not queued.**
   Two copies of the same user acting at once is not a heavier test, it is a
   different one, and every finding it produces is unreproducible.
-- **A run still `running` after `STALE_RUN_AFTER_MS` is failed and the persona
+- **A run still `running` after `STALE_RUN_AFTER_MS` is failed and the virtual user
   runs again.** This is where the stranded-record cost of
   [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
+  gets paid: without it, one restart mid-run would block that virtual user's schedule
   permanently.
 
 The interval is a range (`minIntervalMs`, `maxIntervalMs`), drawn per run. A
@@ -63,4 +63,4 @@ cron neighbourhood; a real one does not keep an appointment.
 **What this rules out:** a `setTimeout` or interval anywhere in the run path;
 the engine scheduling its own next run; a scaffolded scheduled task; a queue
 holding the next run; and a cadence that lives only in a config file, which
-cannot record when the persona last actually went.
+cannot record when the virtual user last actually went.

package/knowledge/decisions/internals/a-virtual-user-converse-signs-in-before-its-first-turn.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: A virtual user's converse signs in before its first turn
+description: HttpVirtualUser.converse calls login() before a run when it holds no session, because a public agent route never triggers the 401 retry that would sign the virtual user in
+tags: services, virtual-users, agents
+---
+
+# A virtual user's converse signs in before its first turn
+
+`HttpVirtualUser.converse` (`packages/core/src/services/http-virtual-users.ts`)
+calls `this.login()` when `signedIn` is false, before it starts the run. Only
+then does it send the agent request.
+
+The code comment gives the reason. A public agent route never returns 401, so
+the 401 retry in `sendAgent` never runs and would never sign the virtual user
+in. An agent thread is also minted under a fresh anonymous id per request when
+no one owns it, so turn one could succeed and turn two be refused as somebody
+else's. A virtual user is a real account with real credentials, so conversing as
+nobody is not the intent.
+
+**What this rules out:** relying on the 401 retry for `converse`, and running a
+virtual user's conversation unauthenticated when it was meant to sign in.
+Compare [the 401-only retry](scenario-agent-calls-sign-in-on-401-only.md), which is
+how the other agent calls behave.

package/knowledge/decisions/internals/a-virtual-user-email-is-computed-with-the-run-id-as-a-sub-address.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: A virtual user's email is computed from its id, with the run id as a sub-address
+description: virtualUserEmail derives the address from the virtual user id and a real domain, appends the run id so concurrent runs get separate inboxes and accounts, and refuses colliding addresses
+tags: core, virtual-users, email, runs
+---
+
+# A virtual user's email is computed from its id, with the run id as a sub-address
+
+`packages/core/src/wirings/virtual-user/virtual-user-email.ts` computes the address a virtual user
+reads mail at. Nothing is declared by hand.
+
+The label is the virtual user id, lower-cased, with runs of non-alphanumerics turned
+into `-` and leading or trailing dashes removed (`virtual-user-email.ts:19-30`). A
+virtual user id with no letters or digits left throws (`virtual-user-email.ts:24-28`).
+
+The domain must contain a dot and no `@` (`virtual-user-email.ts:49-54`). The error
+asks for "a domain the stage actually receives mail on" (`virtual-user-email.ts:52`).
+
+With a `runId`, the address is `label+runIdLabel@domain` (`virtual-user-email.ts:55-56`).
+The doc comment says that without the suffix, two concurrent runs share "an inbox
+_and_ a user row, and run B reads run A's magic link" (`virtual-user-email.ts:35-37`).
+Without a `runId`, the bare form is returned (`virtual-user-email.ts:40-41`).
+
+`virtualUserEmails` throws when two virtual users compute the same address
+(`virtual-user-email.ts:76-82`). The comment says they "would share a user row and read
+each other's email" (`virtual-user-email.ts:79-80`).
+
+All of one virtual user's logins share one address (`virtual-user-email.ts:62-66`). The
+comment gives the reason: better-auth keeps `email` on the `user` and defaults
+`allowDifferentEmails` to false.
+
+**What this rules out:** two concurrent runs sharing an inbox, and two virtual users
+mapping to one account.

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

@@ -30,7 +30,7 @@ unit: there is no in-process promise to leave running, and `executeVirtualUserRu
 — 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.
+`running` with zero steps and no error anywhere. That is what a cloud 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`
@@ -56,7 +56,7 @@ 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
+to: a record stuck at `running` would otherwise block its virtual user's cadence
 forever.
 
 **What this rules out:** dispatching the run through `startWorkflow`; awaiting

package/knowledge/decisions/internals/an-agent-is-offered-under-its-registry-key-and-only-within-the-virtual-users-scopes.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: A reachable agent is offered by its registry key, filtered by the virtual user's scopes
+description: reachableAgents offers an agent to a virtual user under the key it is registered with, and only when the virtual user holds the agent's declared scopes; the server still enforces access
+tags: core, virtual-users, agents, scopes
+---
+
+# A reachable agent is offered by its registry key, filtered by the virtual user's scopes
+
+`packages/core/src/wirings/virtual-user/virtual-user-agents.ts` decides which agents
+a virtual user is told about.
+
+An agent with no declared scopes is offered to everybody (`virtual-user-agents.ts:54-55`).
+The doc comment says undeclared is not the same as denied (`virtual-user-agents.ts:45-46`).
+Otherwise the agent is offered only when the virtual user's scopes satisfy the agent's
+scopes (`virtual-user-agents.ts:57`, `hasScopes`).
+
+The name offered is the registry key, not the agent's display name. The code uses
+`name: id` (`virtual-user-agents.ts:59-60`), and the doc comment says the display
+name "is frequently something else entirely", and offering it makes the run die
+on a 500 (`virtual-user-agents.ts:30-37`).
+
+The doc comment says this filter narrows only what is offered. The server decides
+who may talk to which agent (`virtual-user-agents.ts:39-44`).
+
+**What this rules out:** offering an agent name the server cannot resolve, and
+treating the offer list as the access check.

package/knowledge/decisions/internals/an-oauth2-credential-implies-an-optional-app-secret.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: An OAuth2 credential implies its app client secret, optional and overridable by declaration
+description: deriveOAuth2AppSecrets creates the app client id and secret for each OAuth2 credential, marked optional, unless the project already declares that secret id
+tags: core, secrets, credentials, oauth2
+---
+
+# An OAuth2 credential implies its app client secret, optional and overridable by declaration
+
+`packages/core/src/wirings/secret/derive-oauth2-app-secrets.ts` adds the app's
+client id and secret for each OAuth2 credential a project declares. The doc comment
+says the pair has the same shape every time, so writing it by hand "bought nothing"
+and was often skipped (`derive-oauth2-app-secrets.ts:7-12`).
+
+- A secret id that is already declared is skipped, so an explicit declaration
+  wins and keeps its own description or `docsUrl` (`derive-oauth2-app-secrets.ts:25`,
+  `31`, and the comment at `derive-oauth2-app-secrets.ts:14-15`).
+- The derived secret has `optional: true` (`derive-oauth2-app-secrets.ts:38-39`).
+  The comment says an addon that also authenticates by API key "must still deploy
+  without an OAuth app configured" (`derive-oauth2-app-secrets.ts:17-19`).
+- The OAuth2 settings (token secret, URLs, scopes, PKCE, extra params) are copied
+  from the credential (`derive-oauth2-app-secrets.ts:41-49`).
+
+**What this rules out:** requiring a deployment to configure an OAuth app for a
+credential that is not used, and a derived secret overriding one the author
+declared.

package/knowledge/decisions/internals/analytics-identity-resolvers-run-in-declared-order.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Analytics identity resolvers run in declared order so consent is read before a cookie is minted
+description: composeAnalyticsIdentity threads each resolver's output into the next, so a cookie-minting resolver sees the consent that an earlier resolver read
+tags: core, analytics, consent
+---
+
+# Analytics identity resolvers run in declared order so consent is read before a cookie is minted
+
+`composeAnalyticsIdentity` in `packages/core/src/analytics/compose-analytics-identity.ts:22-35`
+runs the resolvers in the order given. Each one receives the accumulated result of
+the ones before it (`:26`, `:29`), and its output is merged over that result (`:31-33`).
+
+The doc comment at `:8-15` states the ordering rule: a resolver that mints a cookie
+may do so only once consent has been read, so the consent reader has to come first.
+A later resolver wins a key it sets (`:17-18`).
+
+The cookie-side rule is in `a-first-party-cookie-is-written-only-after-its-purposes-consent.md`.
+That note does not record the order in which the resolvers are composed.
+
+**What this rules out:** running a cookie-minting resolver ahead of the consent
+reader, and merging independent resolver results so that no resolver sees another's output.

package/knowledge/decisions/internals/feature-flag-declarations-refuse-an-empty-anyof-and-conflicting-scopes.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Feature flag declarations refuse an empty anyOf and conflicting scopes
+description: validateAndBuildFeatureFlagDefinitionsMeta throws on an anyOf that is an empty list, and on a repeated flag name whose scopes differ between declarations
+tags: core, flags, validation
+---
+
+# Feature flag declarations refuse an empty anyOf and conflicting scopes
+
+`validateAndBuildFeatureFlagDefinitionsMeta` in
+`packages/core/src/wirings/flag/validate-flag-definitions.ts:70-98` checks each
+declaration in two ways.
+
+An `anyOf` that is an empty array throws (`:78-84`). The message says an empty
+list satisfies nobody, and that a pure switch should omit `anyOf`.
+
+When a flag name is declared twice, the two `anyOf` lists are compared as sorted
+JSON (`:86-90`). A difference throws (`:91-97`), and the message says flags sharing
+a name must name the same scopes.
+
+**What this rules out:** a flag that no session can satisfy, and two declarations
+of one flag that disagree about who may see it.

package/knowledge/decisions/internals/feature-flags-fail-open-and-never-enforce-access.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: Feature flags fail open on availability and never enforce access
+description: A flag with no config row is available by default, anyOf decides only the advisory capable half, and the runner's assertFeatureAvailable checks availability alone
+tags: core, flags, authorization
+---
+
+# Feature flags fail open on availability and never enforce access
+
+`resolveFlag` in `packages/core/src/wirings/flag/resolve-flag.ts:54-95`
+separates two halves. `capable` is true when `anyOf` is absent, and otherwise
+comes from `hasAnyScope` on the session's scopes (`:68-69`). If the flag has no
+config row, the result is `available: true` (`:72-74`). The doc comment at `:54-59`
+says this fail-open is safe only because `capable` comes from the session and
+`scopes:` is not changed by a flag.
+
+`FlagState` in `packages/core/src/wirings/flag/flag.types.ts:97-104` says the same
+thing: `available` is the only half the runner enforces, and `capable` is advisory
+and "protects nothing". `flag.types.ts:14-18` says `anyOf` is an OR over scopes,
+deliberately the opposite of `scopes`, which is an AND.
+
+`assertFeatureAvailable` in `packages/core/src/wirings/flag/assert-feature-available.ts`
+calls `resolveFlag` and throws only when `available` is false (`:28-30`). It does
+nothing when no feature-flag source is registered (`:24-26`). The doc comment at
+`:10-12` says enforcing `capable` here would make a second authorization path.
+
+**What this rules out:** using a flag as an access check, and a store outage
+turning every flagged feature off.

package/knowledge/decisions/internals/flag-sync-rewrites-only-the-declared-text.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: Flag declaration sync rewrites only the description and anyOf
+description: The FeatureFlagStore contract re-syncs a flag's description and anyOf on deploy and leaves enabled, rollout and overrides to the operator
+tags: core, flags, services
+---
+
+# Flag declaration sync rewrites only the description and anyOf
+
+The `FeatureFlagStore` interface in `packages/core/src/services/feature-flag-service.ts:79-90`
+declares `syncFlags`. Its doc comment says a flag's `description` and `anyOf` are
+re-synced on each deploy, because that is the declaration's whole content. It also
+says `enabled`, the rollout and every override belong to the operator and are never
+touched.
+
+Lines `:80-83` say a removed declaration leaves its row marked `declared: false`
+rather than deleting the operator's switch.
+
+Core defines only the interface here. The implementing store is not in this
+package, so the rule is the contract's, and was not verified against an
+implementation.
+
+**What this rules out:** a deploy overwriting an operator's enabled state, rollout
+or overrides, and deleting a flag row because its declaration was removed.

package/knowledge/decisions/internals/in-a-scenario-a-4xx-is-data-not-an-exception.md

@@ -7,15 +7,15 @@ tags: services
 
 # In a scenario a 4xx is data, not an exception
 
-`postScenarioJson` (`packages/core/src/services/scenario-actors-service.ts`) and
-`ScenarioActor.invokeRaw` return a `ScenarioHttpResponse` for every status. Only
+`postScenarioJson` (`packages/core/src/services/virtual-users-service.ts`) and
+`ScenarioVirtualUser.invokeRaw` return a `ScenarioHttpResponse` for every status. Only
 `invoke` throws, and it throws with a truncated body — which is why a scenario
 asserting on a refusal must use `invokeRaw`.
 
 A permissions or scopes scenario _expects_ the 403. The status is the assertion,
 and the body usually names the scope that was missing, so both have to survive as
 data rather than being reduced to a thrown `Error`. These helpers also exist
-because every scenario reaching past an actor was hand-writing the same
+because every scenario reaching past a virtual user was hand-writing the same
 `content-type`, `JSON.stringify` and drain — and the copies had drifted: several
 returned `res.json()`, which discards the status entirely and throws outright on
 an empty body or an HTML error page.