@pikku/core 0.12.141 → 0.12.143

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.

package/knowledge/decisions/internals/index.md

@@ -10,47 +10,54 @@ A rule about how core behaves: what runs where, in what order, and what a
 caller is entitled to assume.
 
 <!-- pikku:knowledge-index -->
-
+- [A credential name declared twice must agree on its schema and its type](a-credential-name-declared-twice-must-agree-on-schema-and-type.md) — validateAndBuildCredentialDefinitionsMeta throws when two declarations of one credential name differ in schema or in type, and otherwise keeps the first declaration
+- [declareScopes lets an app grant a scope whose addon it does not wire](a-grant-can-name-a-scope-declared-without-its-addon.md) — 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
 - [A held run is woken later, not retried](a-held-run-is-woken-later-not-retried.md) — An orchestrator message that finds its run held enqueues a fresh wake-up a second later instead of failing, because the queue's retry budget is for real failures and a long pass outlasts it
-- [A non-streaming agent run registers with aiRunState on the same terms as a streaming one](a-non-streaming-agent-run-registers-with-airunstate-too.md) — Otherwise interruptAIAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
+- [A latency budget is asserted by its cause, not by the clock](a-latency-budget-is-asserted-by-its-cause.md) — The per-request key derivation and remote RPC round-trip tests count WebCrypto calls and check the algorithm instead of timing them, because a millisecond budget fails under CI load while the regression it guards is a choice of KDF
+- [A non-streaming agent run registers with agentRunState on the same terms as a streaming one](a-non-streaming-agent-run-registers-with-agentrunstate-too.md) — Otherwise interruptAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
 - [With scenarios.reset on, the dev seed is the fixture every assertion is written against](a-reset-suite-makes-the-dev-seed-the-fixture.md) — The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
 - [A resumed turn is as interruptible as the first one](a-resumed-agent-turn-is-as-interruptible-as-the-first.md) — It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
 - [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
+- [A scheduled task writes its caller's session to the session store before it runs](a-scheduled-task-writes-its-caller-session-before-it-runs.md) — 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
+- [A secret set in memory shadows the variable of the same name](a-secret-set-in-memory-shadows-the-variable-of-the-same-name.md) — LocalSecretService reads its in-memory map before the variables service, stores a SecretValue unwrapped, and treats an empty string as absent
 - [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 acts through invokeRaw, so a refusal is data it can act on](a-virtual-user-acts-through-invokeraw-so-a-refusal-is-data.md) — virtualUserTarget calls virtualUser.invokeRaw, which signs the virtual user in when needed, retries once after a 401, and returns the status instead of throwing
+- [A virtual user cadence is a row, not a timer](a-virtual-user-cadence-is-a-row-not-a-timer.md) — 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
+- [A virtual user's converse signs in before its first turn](a-virtual-user-converse-signs-in-before-its-first-turn.md) — 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
 - [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's email is computed from its id, with the run id as a sub-address](a-virtual-user-email-is-computed-with-the-run-id-as-a-sub-address.md) — 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
 - [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
-- [The actor-flow conversation engine only sees a transport-agnostic target driver](actor-flow-drives-the-target-through-a-transport-seam.md) — The engine never imports the agent runner; the target is injected as run/approve, so scenarios exercise the real wire path
-- [An actor-flow verdict is the persona's self-evaluation, not an assertion](actor-flow-verdicts-are-llm-self-evaluations.md) — The engine returns what the actor judged plus the transcript; deterministic checks stay with the caller
 - [Addon package roots resolve by walking node module search paths](addon-package-roots-resolve-by-walking-node-module-search-paths.md) — LocalMetaService finds an addon's directory by scanning resolve.paths, not by require.resolve, because addon packages expose no main entry
 - [An addon's .pikku meta ships at the package root or under dist, and readers probe both](addon-pikku-meta-ships-at-the-package-root-or-under-dist.md) — The layout depends on the addon's build and files field, so a consumer resolving the directory by path must try `<pkg>/.pikku` and `<pkg>/dist/.pikku` before concluding an addon declares nothing
 - [Addon singleton services are cached per namespace, not per package](addon-singleton-services-are-cached-per-namespace-not-per-package.md) — Each wireAddon instance gets its own services built from its own overrides, at the cost of one service graph per wired instance
 - [Bare workflow names from inside an addon are prefixed with the consumer's namespace](addon-workflow-names-are-prefixed-with-the-consumer-namespace.md) — The addon's workflowService is proxied so an addon never has to hardcode the name its consumer chose
+- [The AG-UI bridge obeys the client's event-ordering contract exactly](agent-agui-bridge-obeys-the-client-ordering-contract.md) — RUN_STARTED opens lazily, RUN_FINISHED fires once on done, and step names are globally sequential — a violation makes the client drop the whole stream
+- [Audio chunks are labelled with the format the provider actually returned](agent-audio-chunks-carry-the-format-the-provider-returned.md) — The configured format is only a request, so the response's own format wins with the request and pcm16 as fallbacks
 - [Loading agent context waits for a tool result that may still be landing](agent-context-waits-for-a-tool-result-still-being-written.md) — An interrupted run's tool can still be writing to the thread, and in voice the next turn arrives within seconds — soon enough to load context missing what it is about to be asked about
+- [A credential-required tool result never reaches the client or the transcript](agent-credential-suspensions-hide-the-tool-result.md) — The run suspends with credential-request events instead, leaving the tool call unresulted so it can be resumed after connecting
+- [Delegate mode hides the parent's later text, supervise mode hides the sub-agent's](agent-delegate-and-supervise-hide-different-text.md) — Exactly one voice reaches the client per agent-mode; approvals and tool events always flow through either way
+- [Nulls are stripped from approved tool arguments before execution](agent-llm-tool-arguments-have-nulls-stripped.md) — LLMs emit null for optional fields where the schema layer expects undefined, so a resumed tool call is cleaned recursively first
+- [Model resolution stays a single seam even though it is currently a passthrough](agent-model-config-stays-a-single-resolution-seam.md) — resolveModelConfig looks removable but is the one merge point for per-request model overrides
+- [An agentMiddleware onError hook cannot change how a run fails](agent-onerror-hooks-cannot-change-the-failure.md) — Hook throws are swallowed so observability code can never convert, mask, or replace the original error
+- [AI runner methods must be called on the runner, never as detached references](agent-runner-methods-must-keep-their-receiver.md) — Implementations use this internally, so grabbing transcribe or generateSpeech as a bare function loses the receiver and throws at runtime
 - [Agent speech travels as a CUSTOM AG-UI event rather than being dropped](agent-speech-travels-as-a-custom-agui-event.md) — AG-UI has no speech event, and dropping it makes a voice agent reached over HTTP silently inaudible while the provider still bills for the audio
-- [The AG-UI bridge obeys the client's event-ordering contract exactly](ai-agent-agui-bridge-obeys-the-client-ordering-contract.md) — RUN_STARTED opens lazily, RUN_FINISHED fires once on done, and step names are globally sequential — a violation makes the client drop the whole stream
-- [Audio chunks are labelled with the format the provider actually returned](ai-agent-audio-chunks-carry-the-format-the-provider-returned.md) — The configured format is only a request, so the response's own format wins with the request and pcm16 as fallbacks
-- [A credential-required tool result never reaches the client or the transcript](ai-agent-credential-suspensions-hide-the-tool-result.md) — The run suspends with credential-request events instead, leaving the tool call unresulted so it can be resumed after connecting
-- [Delegate mode hides the parent's later text, supervise mode hides the sub-agent's](ai-agent-delegate-and-supervise-hide-different-text.md) — Exactly one voice reaches the client per agent-mode; approvals and tool events always flow through either way
-- [Nulls are stripped from approved tool arguments before execution](ai-agent-llm-tool-arguments-have-nulls-stripped.md) — LLMs emit null for optional fields where the schema layer expects undefined, so a resumed tool call is cleaned recursively first
-- [Model resolution stays a single seam even though it is currently a passthrough](ai-agent-model-config-stays-a-single-resolution-seam.md) — resolveModelConfig looks removable but is the one merge point for per-request model overrides
-- [An aiMiddleware onError hook cannot change how a run fails](ai-agent-onerror-hooks-cannot-change-the-failure.md) — Hook throws are swallowed so observability code can never convert, mask, or replace the original error
-- [AI runner methods must be called on the runner, never as detached references](ai-agent-runner-methods-must-keep-their-receiver.md) — Implementations use this internally, so grabbing transcribe or generateSpeech as a bare function loses the receiver and throws at runtime
-- [Persisting an agent stream from send is best-effort and must never reject](ai-agent-stream-persistence-is-best-effort.md) — The persisting channel flushes fire-and-forget because send is synchronous; a storage failure degrades the transcript instead of killing the process
-- [A delegated sub-agent inherits the parent run's context block](ai-agent-sub-agents-inherit-the-parent-context-block.md) — The sub-agent tool schema carries only message and session, so the parent's identifier block is forwarded rather than re-typed by the model
-- [A tool's execute() failure is logged before the AI SDK swallows it](ai-agent-tool-execute-failures-are-logged-unconditionally.md) — Every agent tool is wrapped in a logging try/catch, because a thrown tool error otherwise becomes a conversational reply and is invisible server-side
-- [Voice input transcribes audio parts sequentially and in place](ai-agent-voice-input-transcribes-audio-parts-in-place.md) — Each audio part is replaced by its text where it sat, one at a time, bounding concurrent downloads and preserving content order
-- [Working memory is persisted only when the merged value validates](ai-agent-working-memory-is-persisted-only-when-valid.md) — A failed schema check logs and drops the update rather than saving it, because invalid state poisons every later read
+- [Persisting an agent stream from send is best-effort and must never reject](agent-stream-persistence-is-best-effort.md) — The persisting channel flushes fire-and-forget because send is synchronous; a storage failure degrades the transcript instead of killing the process
+- [A delegated sub-agent inherits the parent run's context block](agent-sub-agents-inherit-the-parent-context-block.md) — The sub-agent tool schema carries only message and session, so the parent's identifier block is forwarded rather than re-typed by the model
+- [A tool's execute() failure is logged before the AI SDK swallows it](agent-tool-execute-failures-are-logged-unconditionally.md) — Every agent tool is wrapped in a logging try/catch, because a thrown tool error otherwise becomes a conversational reply and is invisible server-side
+- [Voice input transcribes audio parts sequentially and in place](agent-voice-input-transcribes-audio-parts-in-place.md) — Each audio part is replaced by its text where it sat, one at a time, bounding concurrent downloads and preserving content order
+- [Working memory is persisted only when the merged value validates](agent-working-memory-is-persisted-only-when-valid.md) — A failed schema check logs and drops the update rather than saving it, because invalid state poisons every later read
 - [An addon's scope root loses to a root the host app already declares](an-addon-scope-root-loses-to-a-root-the-host-already-declares.md) — loadAddonFunctionsMeta merges addon scope trees by root name, first declaration wins, so an addon sharing a root with its host contributes nothing — silently
 - [An interrupt is not a failure, and the non-streaming path throws rather than returning](an-agent-interrupt-is-not-a-failure.md) — It skips the onError hooks and never becomes an errorMessage; with no partial reply to hand back, a typed throw is what distinguishes it from a provider outage
+- [A reachable agent is offered by its registry key, filtered by the virtual user's scopes](an-agent-is-offered-under-its-registry-key-and-only-within-the-virtual-users-scopes.md) — 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
 - [An interrupt for a run owned by another instance says so, rather than returning false](an-agent-run-owned-by-another-instance-says-so.md) — A bare false is indistinguishable from "already finished", which is the one deployment shape the in-process registry cannot cover
 - [A wrapped agent-stream send must return the inner send's promise](an-agent-stream-send-must-return-the-inner-sends-promise.md) — Middleware runs asynchronously, so dropping the returned promise turns every awaited channel.send upstream into a no-op
 - [A message with nothing to say carries no text part at all](an-empty-text-part-is-omitted-from-an-agent-message.md) — An attachment on its own is a real turn, and providers are entitled to reject an empty text part sitting beside it
 - [A transcript is recorded only when something was actually heard](an-empty-transcript-is-not-recorded.md) — Recording an empty string sends a transcript event saying the user said nothing, which renders as an empty bubble rather than a pending one
+- [An OAuth2 credential implies its app client secret, optional and overridable by declaration](an-oauth2-credential-implies-an-optional-app-secret.md) — deriveOAuth2AppSecrets creates the app client id and secret for each OAuth2 credential, marked optional, unless the project already declares that secret id
 - [An unref'd timer cannot be awaited under node:test](an-unref-d-timer-cannot-be-awaited-under-node-test.md) — The channel RPC registry unrefs its timeout so a pending call never holds a process open, which makes that timeout unawaitable in a test and silently cancels the rest of the file
+- [Analytics identity resolvers run in declared order so consent is read before a cookie is minted](analytics-identity-resolvers-run-in-declared-order.md) — composeAnalyticsIdentity threads each resolver's output into the next, so a cookie-minting resolver sees the consent that an earlier resolver read
 - [Channel message handlers accept three config shapes](channel-message-handlers-accept-three-config-shapes.md) — onMessage may be a function config, a wrapper with middleware, or a wrapper around a function config — the runtime discriminates structurally
 - [Channel middleware caching covers only statically resolved middleware](channel-middleware-caches-only-statically-resolved-middleware.md) — Inherited tag/named middleware is cached per uid; per-run closures are appended fresh every call, at the cost of re-allocating the array
 - [`getState<T>()` lets the caller name any type, so every implementation asserts](channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md) — The type parameter appears only in the return position with nothing to infer from, so it is a caller-chosen claim rather than a checked fact
@@ -61,9 +68,8 @@ caller is entitled to assume.
 - [CLI stdout is reserved for machine-readable output](cli-stdout-is-reserved-for-machine-readable-output.md) — The default renderer emits single-line NDJSON, diagnostics go to stderr, and --json only hijacks rendering for commands that declared a renderer
 - [CLI unknown long options warn instead of failing](cli-unknown-long-options-warn-instead-of-failing.md) — Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
 - [A column's at-rest form is an axis of its own](core-column-form-is-an-axis-of-its-own.md) — How a value is stored is independent of how sensitive it is, so form carries a required nominal brand on writes while classification stays optional on reads
-- [The data-classification brand is an optional property](core-data-classification-brand-is-an-optional-property.md) — Making **classification** required would break ordinary Kysely operands, so the brand only constrains values flowing out
+- [The data-classification brand is an optional property](core-data-classification-brand-is-an-optional-property.md) — Making __classification__ required would break ordinary Kysely operands, so the brand only constrains values flowing out
 - [The function runner restores the wire fields it overwrites](core-function-runner-restores-the-wire-fields-it-overwrites.md) — One wire object is reused across nested calls, so functionId, audit, addonNamespace and rpc are saved and put back in a finally
-- [The function runner resolves wire services itself](the-runner-resolves-wire-services-itself.md) — A function's wire services come from its own package's factory or the app's registered one, never borrowed from whoever called it
 - [Hot reload merges generated meta and never replaces it](core-hot-reload-merges-generated-meta-never-replaces-it.md) — Reloading codegen output must preserve runtime-registered meta, which no generated JSON contains
 - [Hot reload owns its module registry instead of re-importing](core-hot-reload-owns-its-module-registry.md) — Dev reload transpiles to CJS and runs modules through vm.compileFunction, because the native ESM loader map cannot be evicted
 - [Middleware order is resolution scope first, then priority](core-middleware-order-is-scope-then-priority.md) — Middleware is collected global to function, then stably sorted by priority, deduped, frozen and cached per wire
@@ -71,6 +77,9 @@ caller is entitled to assume.
 - [Scopes are an AND gate, separate from permissions](core-scopes-are-an-and-gate-separate-from-permissions.md) — Every declared scope must be held, so adding one can only narrow access — permissions OR, and can only widen it
 - [Pikku state is a global map written only at registration time](core-state-is-a-global-map-written-only-at-registration-time.md) — A symbol-keyed globalThis map holds the wiring registry; nothing per-request may ever be written to it
 - [Email meta is read uncached because codegen rewrites it mid-session](email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md) — getEmailMeta re-reads its file on every call, unlike every other meta accessor, because the file appears and changes during a long-lived session
+- [Feature flag declarations refuse an empty anyOf and conflicting scopes](feature-flag-declarations-refuse-an-empty-anyof-and-conflicting-scopes.md) — validateAndBuildFeatureFlagDefinitionsMeta throws on an anyOf that is an empty list, and on a repeated flag name whose scopes differ between declarations
+- [Feature flags fail open on availability and never enforce access](feature-flags-fail-open-and-never-enforce-access.md) — 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
+- [Flag declaration sync rewrites only the description and anyOf](flag-sync-rewrites-only-the-declared-text.md) — The FeatureFlagStore contract re-syncs a flag's description and anyOf on deploy and leaves enabled, rollout and overrides to the operator
 - [Gateway adapters resolve lazily and are promise-cached](gateway-adapters-resolve-lazily-and-are-promise-cached.md) — wireGateway accepts an adapter factory because real adapters need boot-time secrets, which forces the webhook GET route to be registered unconditionally
 - [Gateway middleware sees wire.rpc on webhook and websocket, but not on listener](gateway-listener-middleware-runs-without-an-rpc-on-the-wire.md) — The listener transport invokes its handler directly, so middleware runs outside any runPikkuFunc call and the lazily-attached rpc is absent
 - [Gateway webhook challenges echo bytes not JSON](gateway-webhook-challenges-echo-bytes-not-json.md) — String verification challenges are returned raw with returnsJSON false, because platforms byte-compare the echo and JSON quoting fails the handshake
@@ -92,24 +101,25 @@ caller is entitled to assume.
 - [Local trigger and gateway services assume a single process](local-trigger-and-gateway-services-assume-a-single-process.md) — InMemoryTriggerService and LocalGatewayService start every listener unconditionally with no distributed claiming, so a second instance duplicates every event
 - [MCP wire names are assigned over the whole registry, not derived per name](mcp-wire-names-are-assigned-over-the-whole-registry.md) — Sanitising each name on its own is lossy — `a:b` and `a.b` both become `a_b` — so one of the two targets would be unreachable
 - [Node-only builtins are imported dynamically](node-only-builtins-are-imported-dynamically.md) — V8CoverageService imports node:inspector inside start() so the module stays loadable on runtimes that have no such builtin
-- [One project-shape check, called by both validators](one-project-shape-check-two-validators.md) — workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and fabric validate is that plus the deploy-shaped checks
+- [One project-shape check, called by both validators](one-project-shape-check-two-validators.md) — workspace validate and cloud validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and cloud validate is that plus the deploy-shaped checks
 - [Only functions marked `expose: true` enter a virtual user's catalogue](only-exposed-functions-enter-a-virtual-user-catalogue.md) — Absent is not permissive — an unexposed function 404s over rpc, so offering one spends a step to learn nothing about the product
 - [Queue group concurrency keeps one shared queue fair](queue-group-concurrency-keeps-one-shared-queue-fair.md) — Per-group slot caps let many producers share a single queue instead of one queue each, at the cost of a cap that must stay under batchSize
 - [Queue jobs always carry an explicit attempts count](queue-jobs-always-carry-an-explicit-attempts-count.md) — resolveJobOptions always passes attempts so a queue backend can never apply its own retry default, and an explicit retries of 0 is honoured
 - [Remote addons dispatch over HTTP instead of through local function meta](remote-addons-dispatch-over-http-instead-of-local-meta.md) — wireRemoteAddon ships the addon as a devDependency and posts to the host, so there is deliberately no local handler to resolve
+- [System role names cannot contain the scope separator, and redeclared roles must grant the same scopes](role-names-cannot-contain-the-scope-separator.md) — validateAndBuildSystemRoleDefinitionsMeta rejects an empty role name or one containing ':', and throws when two declarations of one role name grant different scopes
 - [Bare RPC names resolve through the caller's package scope before root](rpc-names-resolve-through-package-scope-before-root.md) — An addon's own functions win over root RPC meta for bare names, and the resolving scope is returned so it can be threaded into runPikkuFunc
-- [Scenario agent calls sign in on 401 only](scenario-agent-calls-sign-in-on-401-only.md) — postAgent sends the first request with whatever session it holds and logs in only if refused, so an actor can converse with a no-auth agent with no sign-in wiring
+- [Scenario agent calls retry sign-in only on 401](scenario-agent-calls-sign-in-on-401-only.md) — HttpVirtualUser.sendAgent sends with whatever session the jar holds and signs in only after a 401, so a no-auth agent route never needs a sign-in; converse signs in eagerly instead
 - [`given` and `when` are sugar for each other; `then` is not](scenario-given-and-when-are-sugar-but-then-is-not.md) — The phase decides whether a step's bindings are alternatives or witnesses, so the same step function called as `when` and as `then` runs differently
 - [Scenario meta lives apart from app meta but merges when read off disk](scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md) — Scenarios generate into .pikku/scenarios so no app module imports them, yet MetaService folds them back into the workflow and function meta
 - [Scenario steps return drained response records](scenario-steps-return-drained-response-records.md) — A scenario step hands back ScenarioHttpResponse rather than a Response, because the body stream reads once and the return value crosses into the run record
-- [Scenarios, steps and personas live in files named for them, and validate errors when they do not](scenarios-live-in-files-named-for-them.md) — pikkuScenario/pikkuFeature/pikkuScenarioStep must be in *.scenario.ts, *.scenarios.ts or *.steps.ts, and definePersonas/runVirtualUser in *.virtual-user.ts or *.vu.ts — an error, because the mixing is only cheap to undo while it is one file
+- [Scenarios, steps and virtual users live in files named for them, and validate errors when they do not](scenarios-live-in-files-named-for-them.md) — pikkuScenario/pikkuFeature/pikkuScenarioStep must be in *.scenario.ts, *.scenarios.ts or *.steps.ts, and defineVirtualUsers/runVirtualUser in *.virtual-user.ts or *.vu.ts — an error, because the mixing is only cheap to undo while it is one file
 - [Scope roots may be co-declared by an addon and its host app](scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md) — flattenScopeDefinitions dedupes ids because the same root can legitimately be declared twice, and every consumer requires one entry per scope
 - [Serverless channel disconnect must tolerate a missing channel](serverless-channel-disconnect-must-tolerate-a-missing-channel.md) — A failed channel lookup on disconnect returns quietly, because serverless runtimes deliver disconnect more than once
 - [sideEffects is an allowlist, because core genuinely has some](side-effects-are-an-allowlist-not-a-boolean.md) — The error registry is built by addError calls that run on import, so claiming sideEffects:false would let a bundler drop it and leave getErrorResponse unable to find any error
 - [Speech synthesis picks a voice per sentence but announces a limitation once](speech-synthesis-picks-a-voice-per-sentence-and-warns-once.md) — A bilingual reply should speak the half it can, and repeating the notice for every sentence would bury the reply itself
-- [The actor's instructions say the word "json" because a degraded gateway demands it](the-actor-prompt-says-json-because-of-json-object-mode.md) — A gateway that cannot take a JSON schema falls back to OpenAI's json_object mode, which refuses any request whose prompt does not contain the word
 - [The agent `done` event goes through the middleware and is awaited](the-agent-done-event-goes-through-the-middleware-and-is-awaited.md) — `done` is the only end-of-reply signal a stream hook gets, and buffering hooks flush on it — sending it raw discards work already paid for
 - [The API report pins members, because the export list only pins names](the-api-report-pins-members-not-just-names.md) — public-surface.json catches an export appearing or vanishing; it cannot see a method added to an interface, which is the change that breaks a consumer's build
+- [The core scope validator refuses separator, wildcard and empty scope segments](the-core-scope-validator-refuses-separator-wildcard-and-empty-segments.md) — assertSegment rejects a scope segment that contains the colon separator, equals the wildcard, or is empty
 - [The dev queue copies prod timing and serialization semantics](the-dev-queue-copies-prod-timing-and-serialization-semantics.md) — InMemoryQueueService dispatches via setTimeout, retries with backoff, and JSON round-trips every payload so dev behaviour matches a real backend
 - [One door per name — the ecosystem tier and the package root are both gone](the-ecosystem-entry-point-carries-the-adapter-surface.md) — the adapter surface was split onto @pikku/core/ecosystem to keep a stability promise at the root; publishing every module twice cost more than the promise was worth, so both the facades and the root barrel were deleted
 - [The embedding model is pinned per service and doc/query embedding is split](the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md) — AIEmbeddingService fixes its model at construction so index and query share a vector space, and separates embedDocuments from embedQuery for asymmetric models
@@ -118,17 +128,24 @@ caller is entitled to assume.
 - [The MCP handshake is challenged only when every target is gated](the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md) — A client decides whether a server speaks OAuth from the handshake alone, so a fully-gated server that answers initialize with a 200 is detected as needing no sign-in
 - [The middleware resolution cache is deliberately unbounded](the-middleware-resolution-cache-is-deliberately-unbounded.md) — Its keyspace is the set of registered wires, not request traffic, and middleware is dynamic — so eviction would buy nothing and cost the dedupe guarantee
 - [The per-invocation rpc view is a class, because an object literal with a getter is slow to build](the-per-invocation-rpc-view-is-a-class.md) — An accessor declared on an object literal is defined per instance, which drops the literal off V8's fast construction path — measured at 1.15µs against 0.47µs, on every request
-- [The persona runtime is exported from @pikku/core/persona, never from services](the-persona-runtime-is-exported-from-the-persona-entry-point.md) — Those values reach the actor-flow and agent runners, which no production server runs — and an unbundled deploy loads whatever the import graph names
+- [The pikku user id resolves in a fixed order](the-pikku-user-id-resolves-in-a-fixed-order.md) — defaultPikkuUserIdResolver takes an explicit pikkuUserId first, then the session userId, then the queue job's id, then the workflow's id
+- [The function runner resolves wire services itself](the-runner-resolves-wire-services-itself.md) — A function's wire services come from its own package's factory or the app's registered one, never borrowed from whoever called it
 - [The schema service is never stubbed, or tests validate nothing](the-schema-service-is-never-stubbed.md) — createStubProxy returns undefined for the schema property so the real schema service is built — a stubbed one turns validation into a silent no-op
 - [A voice turn's transcript is sent before the run starts, on the raw channel](the-transcript-event-is-sent-ahead-of-the-run.md) — The client does not know what it said, and an answer starts streaming within a few hundred milliseconds — a question arriving after its answer reads as the wrong question
 - [The catalogue is the only gate on what a virtual user may call](the-virtual-user-catalogue-is-the-only-gate-on-what-may-be-called.md) — Narrowing happens once at derivation, so there is no second check in the run loop that could drift out of step with it
+- [The virtual user's instructions say the word "json" because a degraded gateway demands it](the-virtual-user-prompt-says-json-because-of-json-object-mode.md) — A gateway that cannot take a JSON schema falls back to OpenAI's json_object mode, which refuses any request whose prompt does not contain the word
+- [The virtual user runtime is exported from @pikku/core/virtual-user, never from services](the-virtual-user-runtime-is-exported-from-the-virtual-user-entry-point.md) — Those values reach the conversation and agent runners, which no production server runs — and an unbundled deploy loads whatever the import graph names
 - [The worker disposition is the only one not testing anything](the-worker-disposition-is-the-one-that-is-not-testing.md) — It is doing the job, so it abandons rarely, runs cool, and is told to stop and say so rather than guess
 - [Thread history records what the model was asked, which for a spoken turn is the transcript](thread-history-records-the-transcript-not-the-audio.md) — The wire carried a base64 audio blob; persisting it writes megabytes of unreadable data and loses the only readable record of the turn
 - [Trigger declaration is split from trigger source](trigger-declaration-is-split-from-trigger-source.md) — Triggers are declared everywhere but subscribed only in the trigger worker, so app processes never open the underlying subscription
 - [TypedSecretService caches for the process lifetime](typed-secret-service-caches-for-the-process-lifetime.md) — Resolved secrets are cached with no TTL, so a secret rotated out of band is not picked up until restart — tracked as pikkujs/pikku#964
-- [Both validators check personas through one shared module, and a persona counts from either the meta or the source](validate-checks-personas-through-a-shared-module.md) — workspace validate and fabric validate are separate implementations, so the persona/actor/knowledge checks live in persona-checks.ts and are called by both — and a persona is counted from the generated meta or a definePersonas() source scan, whichever answers first
+- [Both validators check virtual users through one shared module, and a virtual user counts from either the meta or the source](validate-checks-virtual-users-through-a-shared-module.md) — workspace validate and cloud validate are separate implementations, so the virtual user/virtual-user/knowledge checks live in virtual-user-checks.ts and are called by both — and a virtual user is counted from the generated meta or a defineVirtualUsers() source scan, whichever answers first
 - [pikku validate runs every applicable check, it does not detect a project kind](validate-runs-checks-by-precondition.md) — one `pikku validate` replaces `pikku workspace validate`; checks declare a precondition and run wherever it holds, because the repos that matter are an app and a pile of addons at the same time
+- [The conversation engine only sees a transport-agnostic target driver](virtual-user-conversation-drives-the-target-through-a-transport-seam.md) — The engine never imports the agent runner; the target is injected as run/approve, so scenarios exercise the real wire path
+- [A conversation verdict is the virtual user's self-evaluation, not an assertion](virtual-user-conversation-verdicts-are-llm-self-evaluations.md) — The engine returns what the virtual user judged plus the transcript; deterministic checks stay with the caller
+- [A virtual user conversation starts from a seeded kickoff message](virtual-user-conversations-seed-a-hidden-kickoff-message.md) — The virtual user'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
 - [A scenario's step order for a virtual user is insertion order, not a graph traversal](virtual-user-step-order-comes-from-insertion-order.md) — The CLI writes nodes in declaration order, so following `next` would buy an ordering that is already true and cost a traversal that has to interpret branches
+- [Virtual users are declared in exactly one defineVirtualUsers call per codebase](virtual-users-are-declared-in-one-definevirtualusers-call-per-codebase.md) — defineVirtualUsers is a no-op declaration that the inspector reads statically, and a second call anywhere in the codebase fails the build
 - [Only an explicit `false` silences a spoken reply](voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md) — The key being absent means no voice input is wired and nothing reported either way, so those callers keep the behaviour they had before the option existed
 - [Webhook delivery history records every attempt, best effort](webhook-delivery-history-records-every-attempt-best-effort.md) — The webhook worker persists each attempt before it throws, and a failure to persist is logged rather than allowed to mask the delivery result
 - [Webhook service collaborators are constructor args, not locator lookups](webhook-service-collaborators-are-constructor-args-not-locator-lookups.md) — QueueWebhookService takes its queue as a constructor parameter so a project wiring webhooks without a queue fails to compile instead of at first send
@@ -153,14 +170,13 @@ caller is entitled to assume.
 - [The workflow run timeline is a pure fold over durable history, with the row's status as the authority](workflow-run-timeline-is-a-pure-fold-over-durable-history.md) — No IO in the fold keeps time-travel transport-independent; the terminal event comes from `status`, not from a timestamp every backend populates
 - [Scenario steps default to no retries, and a whole poll is one durable step](workflow-scenario-assertions-never-retry-and-record-one-step.md) — Retrying a failed assertion is wrong for a test primitive; recording the poll as one step means replay returns the outcome, not the loop
 - [Scenario lifecycle hooks are a scenario-only affordance and never mask the failure they follow](workflow-scenario-hooks-are-a-scenario-only-affordance.md) — A durable workflow replays, so a callback that reruns each replay has no honest meaning there
-- [Scenario prose is rendered out of typed calls, not parsed into them](workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md) — The inversion of cucumber — a readable report with no regex step registry to maintain
+- [Scenario prose is rendered out of typed calls, not parsed into them](workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md) — A readable report with no regex step registry to maintain
 - [A quarantined scenario states its reason in code, not in a CI invocation](workflow-scenario-quarantine-reason-lives-in-code.md) — `skip` carries the why next to the scenario it applies to, and naming the scenario explicitly still runs it
 - [Scenario step targets are string literals so the inspector can read them statically](workflow-scenario-step-targets-are-string-literals-for-the-inspector.md) — `step/given/when/then` mirror `do`'s RPC shape because the extractor reads a literal, not an imported symbol
-- [A step's compensation handler runs as a durable step of its own, and never compensates itself](workflow-step-compensation-runs-as-its-own-durable-step.md) — A refund or rollback must not fire twice on replay, so `onError` is recorded as `<step>:onError` with retries disabled
+- [A step's compensation runs as a durable step of its own, declared on the function](workflow-step-compensation-runs-as-its-own-durable-step.md) — A refund or rollback must not fire twice on replay, so it is recorded as `<step>:compensate`; `onError` is gone
 - [A failed workflow step dispatch is transient infrastructure, not a run failure](workflow-step-dispatch-failure-is-transient-not-a-run-failure.md) — Queue-unreachable errors leave the run running and the step pending so the orchestrator replays; marking the run failed loses it
-- [A workflow step lock is held only to claim the step, never across its execution](workflow-step-lock-is-held-only-to-claim-the-step.md) — Holding the advisory lock — and its pooled connection — across step work exhausted the connection pool and self-deadlocked
+- [A workflow step lock is held only to claim the step, never across its execution](workflow-step-lock-is-held-only-to-claim-the-step.md) — Holding the step lock across step work exhausted the connection pool and self-deadlocked when it was an advisory lock; it stays claim-only on leases
 - [A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it](workflow-step-rpc-name-is-provenance-only.md) — It exists so a reader can join a runtime step row back to the declaration that produced it, especially when the durable name was built in a loop
 - [A suspend or approval `reason` is the step's durable identity, not just a message](workflow-suspend-and-approval-reasons-are-durable-step-identities.md) — The reason is namespaced and used raw as the step key, so it must be derived deterministically across replays
 - [A suspended workflow run keeps its in-process context; only terminal runs release it](workflow-suspended-runs-keep-their-in-process-context.md) — `suspended` is absent from the terminal set on purpose, and a context is dropped only when nothing is holding it open
-
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/internals/one-project-shape-check-two-validators.md

@@ -1,13 +1,13 @@
 ---
 type: decision
 title: One project-shape check, called by both validators
-description: workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and fabric validate is that plus the deploy-shaped checks
-tags: cli, validate, fabric
+description: workspace validate and cloud validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and cloud validate is that plus the deploy-shaped checks
+tags: cli, validate, cloud
 ---
 
 # One project-shape check, called by both validators
 
-`pikku workspace validate` and `pikku fabric validate` read like one command
+`pikku workspace validate` and `pikku validate` read like one command
 with a flag. They were two implementations — 495 lines and 2026 — that walked
 the same project and emitted sixteen identical findings. `functions-dir-missing`
 existed character for character in both files. All sixteen already agreed on
@@ -17,20 +17,20 @@ What the duplication cost was not the lines. It was that each validator carried
 checks the other lacked for no reason anyone could name, and nobody noticed
 because nobody read them side by side:
 
-- fabric validate never checked that `packages/functions` declares zod v4, or
+- cloud validate never checked that `packages/functions` declares zod v4, or
   that it has a `package.json` at all — while it did check that six other
   dependencies are present.
 - workspace validate never checked the four scaffold flags beyond `console`,
   though the console it requires is useless without `rpc`.
-- fabric validate swallowed a JSON parse error and reported
+- cloud validate swallowed a JSON parse error and reported
   `pikku-config-missing` for a file sitting right there.
 
-Two of workspace validate's own checks were not merely absent from fabric — they
+Two of workspace validate's own checks were not merely absent from cloud — they
 had never run anywhere:
 
 - the auth checks were gated on a middleware instance with `definitionId ===
 'betterAuthSession'`, but the CLI wires `betterAuthStatelessSession` whenever
-  `session.cookieCache` is on, which is the configuration Fabric asks for. So
+  `session.cookieCache` is on, which is the configuration Pikku Studio Cloud asks for. So
   they skipped precisely the apps most likely to have auth.
 - they looked for migrations in `packages/functions/db/`, and for tables named
   `app_user` and `auth_verification_token`. `pikku db migrate` reads migrations
@@ -39,15 +39,15 @@ had never run anywhere:
   wrong for every project it fired on.
 
 `shared-checks.ts` is now the half that is true of any pikku project regardless
-of where it deploys. Workspace validate is exactly that module; fabric validate
+of where it deploys. Workspace validate is exactly that module; cloud validate
 is that module plus the deploy-shaped checks — themes, frontends, the
 Cloudflare adapter, the `.gitignore` contract, the frontend type-check.
 
-Fabric's fix hints won where the two differed: they are multi-line and show the
+Pikku Studio Cloud's fix hints won where the two differed: they are multi-line and show the
 config block to paste, and there was no reason workspace users were getting the
 one-line version.
 
 **What this rules out:** adding a check to one validator and not the other;
-`pikku fabric validate` reporting a corrupt config as a missing one; asserting
+`pikku validate` reporting a corrupt config as a missing one; asserting
 auth table names no scaffold generates; and reading migrations from anywhere
 other than where `pikku db migrate` reads them.

package/knowledge/decisions/internals/role-names-cannot-contain-the-scope-separator.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: System role names cannot contain the scope separator, and redeclared roles must grant the same scopes
+description: validateAndBuildSystemRoleDefinitionsMeta rejects an empty role name or one containing ':', and throws when two declarations of one role name grant different scopes
+tags: core, roles, scopes, validation
+---
+
+# System role names cannot contain the scope separator, and redeclared roles must grant the same scopes
+
+`packages/core/src/wirings/role/validate-role-definitions.ts` checks declared
+system roles.
+
+The separator is `:` (`validate-role-definitions.ts:7`). A name is refused when it
+is empty (`validate-role-definitions.ts:10-12`) or contains the separator
+(`validate-role-definitions.ts:13-18`). The message says the separator "delimits
+scope ids; a role named like a scope reads as one" (`validate-role-definitions.ts:16`).
+
+When a name is declared twice, the scope lists are compared after sorting, so order
+does not matter (`validate-role-definitions.ts:69-71`). A different set throws,
+with the message "Roles sharing a name must grant the same scopes"
+(`validate-role-definitions.ts:72-79`). An identical repeat is skipped
+(`validate-role-definitions.ts:80`).
+
+`flattenSystemRoleDefinitions` keeps the first entry for each name
+(`validate-role-definitions.ts:36-40`). Its doc comment says this is safe only
+because the validator already guaranteed the repeats are identical
+(`validate-role-definitions.ts:24-29`).
+
+**What this rules out:** a role named with a scope-like `:` in it, and two
+declarations of one role that grant different scopes.

package/knowledge/decisions/internals/scenario-agent-calls-sign-in-on-401-only.md

@@ -1,27 +1,31 @@
 ---
 type: decision
-title: Scenario agent calls sign in on 401 only
-description: postAgent sends the first request with whatever session it holds and logs in only if refused, so an actor can converse with a no-auth agent with no sign-in wiring
+title: Scenario agent calls retry sign-in only on 401
+description: HttpVirtualUser.sendAgent sends with whatever session the jar holds and signs in only after a 401, so a no-auth agent route never needs a sign-in; converse signs in eagerly instead
 tags: services
 ---
 
-# Scenario agent calls sign in on 401 only
+# Scenario agent calls retry sign-in only on 401
 
-`HttpScenarioActor.postAgent`
-(`packages/core/src/services/http-scenario-actors.ts`) sends its first request
-with whatever cookie the jar happens to hold — none, for an actor that has never
-signed in — and only a 401 triggers `login()` and a single retry. Its sibling
-`invokeRaw` does the opposite: it signs in eagerly before the first RPC.
+`HttpVirtualUser.sendAgent` (`packages/core/src/services/http-virtual-users.ts`)
+sends its request with whatever cookie the jar holds. Only a 401 triggers
+`signOut()`, `login()` and a single retry. The agent calls that go through it
+are the stream and approve paths and `postAgent`. Its sibling `invokeRaw` does
+the opposite: it signs in eagerly before the first RPC.
 
-The asymmetry is deliberate. Agent HTTP routes may be public; RPC routes are
-assumed not to be. Making agent calls eager would mean an actor could not talk to
-a no-auth agent at all without a sign-in endpoint, an actor secret and a user
-table — a large amount of wiring to exercise an agent that requires none of it.
-Deferring to the 401 keeps the authenticated case working (the retry succeeds
-with the session attached) at the cost of one extra round trip the first time.
+`HttpVirtualUser.converse` does not rely on that path. Before its first turn it
+calls `login()` when `signedIn` is false. The reason is in the code comment
+there: a public agent route never returns 401, so the retry would never sign
+the virtual user in, and a virtual user is a real account, so conversing as
+nobody is not the intent. See
+[a virtual user's converse signs in before its first turn](a-virtual-user-converse-signs-in-before-its-first-turn.md).
 
-**What this rules out:** unifying the two paths so `postAgent` signs in up front
-"like `invokeRaw` does", and removing the 401 retry on the grounds that
-`invokeRaw` already guarantees a session. Note the ordering consequence: an actor
-whose first action is `converse` against a no-auth agent never signs in at all, so
-nothing else may assume `signedIn` is true after a conversation.
+The 401 path exists because agent HTTP routes may be public; RPC routes are
+assumed not to be. Making every agent call eager would mean a virtual user could
+not reach a no-auth agent without a sign-in endpoint and credentials. Deferring
+to the 401 keeps the authenticated case working (the retry succeeds with the
+session attached) at the cost of one extra round trip the first time.
+
+**What this rules out:** removing the 401 retry from `sendAgent` on the grounds
+that a sign-in always happens first, and making `sendAgent` sign in up front
+"like `invokeRaw` does" without first checking what the agent route requires.

package/knowledge/decisions/internals/scenario-steps-return-drained-response-records.md

@@ -8,7 +8,7 @@ tags: services
 # Scenario steps return drained response records
 
 `ScenarioHttpResponse` and `readScenarioHttpResponse`
-(`packages/core/src/services/scenario-actors-service.ts`) exist because a `fetch`
+(`packages/core/src/services/virtual-users-service.ts`) exist because a `fetch`
 `Response` cannot be a scenario step's return value. A step's result is
 serialised into the workflow run record, and a `Response` body is a stream that
 reads exactly once — by the time anything downstream looks at it, it is either
@@ -23,5 +23,5 @@ the payload was not JSON; its type parameter is a claim the caller makes, not on
 the transport checked.
 
 **What this rules out:** returning `Response` (or anything holding a stream) from
-a scenario step or an actor method, and dropping `serialized` as redundant with
+a scenario step or a virtual user method, and dropping `serialized` as redundant with
 `body` — a non-JSON error body has no other route to the assertion.

package/knowledge/decisions/internals/scenarios-live-in-files-named-for-them.md

@@ -1,11 +1,11 @@
 ---
 type: decision
-title: Scenarios, steps and personas live in files named for them, and validate errors when they do not
-description: pikkuScenario/pikkuFeature/pikkuScenarioStep must be in *.scenario.ts, *.scenarios.ts or *.steps.ts, and definePersonas/runVirtualUser in *.virtual-user.ts or *.vu.ts — an error, because the mixing is only cheap to undo while it is one file
-tags: cli, validate, scenarios, personas
+title: Scenarios, steps and virtual users live in files named for them, and validate errors when they do not
+description: pikkuScenario/pikkuFeature/pikkuScenarioStep must be in *.scenario.ts, *.scenarios.ts or *.steps.ts, and defineVirtualUsers/runVirtualUser in *.virtual-user.ts or *.vu.ts — an error, because the mixing is only cheap to undo while it is one file
+tags: cli, validate, scenarios, virtual users
 ---
 
-# Scenarios, steps and personas live in files named for them, and validate errors when they do not
+# Scenarios, steps and virtual users live in files named for them, and validate errors when they do not
 
 A `pikkuScenario` declared beside the functions it exercises reads as more of
 the same file. The wiring, the function, and the test of the function arrive in
@@ -18,7 +18,7 @@ So `validate` requires the declaration to be in a file named for what it is:
 | --------------------------------------------------- | --------------------------------- |
 | `pikkuScenario`, `pikkuFeature`                     | `*.scenario.ts`, `*.scenarios.ts` |
 | `pikkuScenarioStep` and its platform/addon variants | `*.steps.ts` (or the above)       |
-| `definePersonas`, `runVirtualUser`                  | `*.virtual-user.ts`, `*.vu.ts`    |
+| `defineVirtualUsers`, `runVirtualUser`              | `*.virtual-user.ts`, `*.vu.ts`    |
 
 Three suffixes for scenarios rather than one, because the split that matters is
 scenarios apart from application code, not a particular spelling — `.steps.ts`
@@ -28,15 +28,15 @@ project that already made that split does not have to rename anything.
 **Error, not warning.** The mixing is cheap to undo while it is one file and
 expensive once it is thirty, and a warning is exactly the signal a project
 learns to scroll past. This is the one place where the scenario checks are
-strict: everything else `validate` says about scenarios (no personas declared,
-no actor sign-in, no environments) is a warning, because those describe an
+strict: everything else `validate` says about scenarios (no virtual users declared,
+no virtual user sign-in, no environments) is a warning, because those describe an
 under-tested project rather than an unreadable one.
 
-**Personas are the virtual-user file** because there is no `defineVirtualUsers`
-to look for. That name was retired in favour of `definePersonas`: a virtual user
+**Virtual users are the virtual-user file** because there is no `defineVirtualUsers`
+to look for. That name was retired in favour of `defineVirtualUsers`: a virtual user
 is derived rather than authored — the function meta becomes its catalogue, the
-scenario meta becomes its intents, the declared personas become its identities.
-The persona list is the only part a project writes, so it is the part that has
+scenario meta becomes its intents, the declared virtual users become its identities.
+The virtual user list is the only part a project writes, so it is the part that has
 to be findable by filename.
 
 Matching is on the call (`\bpikkuScenario\s*\(`), not the import, so an aliased
@@ -44,5 +44,5 @@ import cannot slip past and a mention in a comment or a string does not trip it.
 Generated files are exempt — codegen puts things where it likes.
 
 **What this rules out:** a scenario in a function file; a step in a wiring file;
-personas in a general-purpose `personas.ts`; and reporting any of these as a
+virtual users in a general-purpose `virtual-users.ts`; and reporting any of these as a
 warning that a project can carry indefinitely.

package/knowledge/decisions/internals/the-core-scope-validator-refuses-separator-wildcard-and-empty-segments.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: The core scope validator refuses separator, wildcard and empty scope segments
+description: assertSegment rejects a scope segment that contains the colon separator, equals the wildcard, or is empty
+tags: core, scopes, validation
+---
+
+# The core scope validator refuses separator, wildcard and empty scope segments
+
+`assertSegment` in `packages/core/src/wirings/scope/validate-scope-definitions.ts:11-27`
+checks each segment of a declared scope name in three ways.
+
+A segment containing the `:` separator throws (`:12-17`). The message says to
+nest scopes with the `scopes` property instead. A segment equal to `*` throws
+(`:18-23`), because the wildcard is reserved for granting a scope and its
+descendants. An empty segment throws (`:24-26`).
+
+The separator and the wildcard constants are at `:8-9`. The walk that calls this
+check is described in `scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md`.
+
+**What this rules out:** a declared scope whose name embeds a separator, which
+would make it match a different scope, and a declared wildcard.

package/knowledge/decisions/internals/the-pikku-user-id-resolves-in-a-fixed-order.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: The pikku user id resolves in a fixed order
+description: defaultPikkuUserIdResolver takes an explicit pikkuUserId first, then the session userId, then the queue job's id, then the workflow's id
+tags: core, identity
+---
+
+# The pikku user id resolves in a fixed order
+
+`defaultPikkuUserIdResolver` in `packages/core/src/services/pikku-user-id.ts:5-12`
+returns the first of these that is set:
+
+1. `wire.pikkuUserId` (`:6`);
+2. `wire.session.userId`, when it is a string (`:7-9`);
+3. `wire.queue.pikkuUserId` (`:10`);
+4. `wire.workflow.pikkuUserId` (`:11`).
+
+Otherwise it returns `undefined` (`:12`).
+
+The queue case is about the producer's identity carried on a job, and is covered in
+`queue-job-identities-are-signed-at-enqueue.md`. This note records only the order.
+
+**What this rules out:** a session user id overriding an explicit `pikkuUserId` set
+on the wire, and a queue or workflow id outranking a live session.

package/knowledge/decisions/internals/{the-actor-prompt-says-json-because-of-json-object-mode.md → the-virtual-user-prompt-says-json-because-of-json-object-mode.md}

@@ -1,13 +1,13 @@
 ---
 type: decision
-title: The actor's instructions say the word "json" because a degraded gateway demands it
+title: The virtual user's instructions say the word "json" because a degraded gateway demands it
 description: A gateway that cannot take a JSON schema falls back to OpenAI's json_object mode, which refuses any request whose prompt does not contain the word
-tags: core, actor-flow
+tags: core, virtual-user-conversation
 ---
 
-# The actor's instructions say the word "json"
+# The virtual user's instructions say the word "json"
 
-Every call the actor makes wants a schema'd object back. A gateway that cannot
+Every call the virtual user makes wants a schema'd object back. A gateway that cannot
 accept a JSON _schema_ degrades to OpenAI's `json_object` response mode, and
 that mode refuses the request outright — a hard API error, not a bad answer —
 unless the literal word "json" appears somewhere in the prompt.