@pikku/core 0.12.141 → 0.12.142

package/knowledge/decisions/internals/validate-checks-virtual-users-through-a-shared-module.md

@@ -0,0 +1,43 @@
+---
+type: decision
+title: Both validators check virtual users through one shared module, and a virtual user counts from either the meta or the source
+description: 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
+tags: cli, validate, scenarios, virtual users
+---
+
+# Both validators check virtual users through one shared module, and a virtual user counts from either the meta or the source
+
+`pikku workspace validate` and `pikku validate` read like one command
+with a flag. They are not. They are two implementations that walk the same
+project and duplicate about eighteen findings between them verbatim —
+`functions-dir-missing` exists twice, character for character, in two files.
+Pikku Studio Cloud adds the deploy-shaped checks (themes, frontends, the Cloudflare
+adapter, the `.gitignore` contract); workspace adds the local-development ones
+(`dev.db`, the auth migrations).
+
+So a check written into either one is a check half the projects never run. An
+app that never deploys through cloud only ever sees workspace validate; an app
+that does sees cloud validate in CI. The virtual user checks are the kind that only
+pay off when nobody remembers to ask for them, which means they had to be in
+both. Rather than duplicate them a nineteenth time, they live in
+`virtual-user-checks.ts` and both validators call `runVirtualUserChecks`. Merging the
+two validators outright is the better fix and a much larger one; this does not
+block it.
+
+**A virtual user counts from either source, and either alone is wrong at a
+predictable moment.** The generated `pikku-virtual-users-meta.gen.json` is empty on
+a fresh clone where codegen has not run, so trusting only it means a warning
+that fires on every new checkout — and a validator that cries wolf gets muted,
+after which it never says anything worth hearing. A source scan for
+`defineVirtualUsers(` cannot see virtual users an addon contributed. Declared by either
+counts as declared.
+
+**Everything here is `warn`, never `error`.** A project with no virtual users is
+under-tested, not broken, and `validate` gating a deploy on it would make the
+first thing anyone does with the check be to remove it. `knowledge-empty` stays
+at the `info` the shared `@pikku/knowledge` package already assigned it rather
+than being raised to match — the severity belongs to that package.
+
+**What this rules out:** duplicating the checks into both validators;
+adding them to only one; deriving the virtual user count from the generated meta
+alone; failing a build over a missing virtual user.

package/knowledge/decisions/internals/{actor-flow-drives-the-target-through-a-transport-seam.md → virtual-user-conversation-drives-the-target-through-a-transport-seam.md}

@@ -1,17 +1,17 @@
 ---
 type: decision
-title: The actor-flow conversation engine only sees a transport-agnostic target driver
+title: The conversation engine only sees a transport-agnostic target driver
 description: The engine never imports the agent runner; the target is injected as run/approve, so scenarios exercise the real wire path
-tags: actor-flow
+tags: virtual-user-conversation
 ---
 
-# The actor-flow conversation engine only sees a transport-agnostic target driver
+# The conversation engine only sees a transport-agnostic target driver
 
 `runConversation` reaches the target agent exclusively through the injected
 `TargetAgentDriver` — `run(message)` and `approve(runId, decisions)` — declared
-in `packages/core/src/wirings/actor-flow/actor-flow.types.ts`. In production that
-driver is HTTP-backed, issuing the actor's `agentRun` and `agentApprove` calls as
-the signed-in actor.
+in `packages/core/src/wirings/virtual-user/conversation/conversation.types.ts`. In production that
+driver is HTTP-backed, issuing the virtual user's `agentRun` and `agentApprove` calls as
+the signed-in virtual user.
 
 Keeping the seam transport-agnostic is what makes the conversation a real test:
 the agent is exercised through the same authenticated wire path a user takes,

package/knowledge/decisions/internals/virtual-user-conversation-verdicts-are-llm-self-evaluations.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A conversation verdict is the virtual user's self-evaluation, not an assertion
+description: The engine returns what the virtual user judged plus the transcript; deterministic checks stay with the caller
+tags: virtual-user-conversation
+---
+
+# A conversation verdict is the virtual user's self-evaluation, not an assertion
+
+`runConversation` ends by asking the virtual user LLM whether the `evaluate`
+criterion was met and returns that as `ConversationVerdict` — `passed`, `reasoning`
+and the full `transcript`
+(`packages/core/src/wirings/virtual-user/conversation/`). Nothing in the engine inspects the
+system the agent acted on.
+
+The verdict is deliberately soft because the thing it judges is soft: whether a
+conversation accomplished a natural-language task. Deterministic checks — that a
+row was written, that an email went out — belong to the caller, which already
+holds the virtual user and can `virtualUser.invoke(...)` after the conversation returns. The
+`reasoning` and `transcript` fields exist so a soft failure is debuggable rather
+than merely red.
+
+**What this rules out:** having `runConversation` assert or throw on a failed
+verdict, and adding deterministic post-conditions to `ConverseOptions` instead of
+running them at the call site.

package/knowledge/decisions/internals/virtual-user-conversations-seed-a-hidden-kickoff-message.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: A virtual user conversation starts from a seeded kickoff message
+description: 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
+tags: virtual-user-conversation
+---
+
+# A virtual user conversation starts from a seeded kickoff message
+
+`runConversation` in
+`packages/core/src/wirings/virtual-user/conversation/run-conversation.ts` primes
+`virtualUserMessages` with a single user message telling the virtual user to begin, before
+the first turn is generated.
+
+The virtual user speaks first, so at that point there is nothing for it to reply to —
+and LLM providers reject a completion request with no messages. The seed is
+addressed to the virtual user rather than to the target agent, which is why it is never
+pushed onto `transcript`: it is scaffolding, not something the simulated user
+said, and including it would corrupt the transcript the final evaluation reads.
+
+**What this rules out:** starting from an empty `virtualUserMessages` array, folding
+the kickoff into the virtual user instructions where a provider may weight it
+differently, and pushing the seed into the transcript for symmetry.

package/knowledge/decisions/internals/virtual-users-are-declared-in-one-definevirtualusers-call-per-codebase.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: Virtual users are declared in exactly one defineVirtualUsers call per codebase
+description: defineVirtualUsers is a no-op declaration that the inspector reads statically, and a second call anywhere in the codebase fails the build
+tags: core, inspector, virtual-users, declaration
+---
+
+# Virtual users are declared in exactly one defineVirtualUsers call per codebase
+
+`defineVirtualUsers` in `packages/core/src/wirings/virtual-user/define-virtual-users.ts`
+is a no-op (`define-virtual-users.ts:33`). The CLI reads the call by AST and
+generates a `VirtualUserId` union and `virtual-users.gen.json` from it
+(`define-virtual-users.ts:3-8`). The doc comment states the rule: "Exactly one
+`defineVirtualUsers(...)` is allowed per codebase, so there is one place to read the
+cast from and one place to add to. A second call — even in the same file — fails
+the build" (`define-virtual-users.ts:14-16`).
+
+The inspector enforces it. `addVirtualUsers` requires an inline object literal and
+refuses anything else (`packages/inspector/src/add/add-virtual-users.ts:163-170`),
+then claims the single declaration (`add-virtual-users.ts:174-181`, error
+`DUPLICATE_VIRTUAL_USERS_DEFINITION`). `claimSingleDeclaration` in
+`packages/inspector/src/utils/single-declaration.ts` refuses a second call in the
+same file or another one (`single-declaration.ts:44-56`). Generated `.gen.ts` files
+are exempt and never claim the slot (`single-declaration.ts:40-42`).
+
+**What this rules out:** a second `defineVirtualUsers` call, including in the same
+file, and splitting the cast across several declarations. The rule is about where a
+person adds a virtual user, so it applies to hand-written files only.
+
+**Related:** [scenario and virtual-user files are named for what they hold](scenarios-live-in-files-named-for-them.md)

package/knowledge/decisions/internals/workflow-core-never-imports-a-browser-driver.md

@@ -31,12 +31,12 @@ matches a family of ids, `containing` picks the match holding a piece of text,
 and `within` scopes the lookup to one row or section. Core defines the shape;
 the driver resolves it against a real page.
 
-The same dependency discipline applies at runtime: `resolveScenarioActors` in
-`pikku-scenario-service.ts` imports the HTTP actor client lazily, so even a
-runner bundle only pays for the AI persona conversation loop when a scenario
-actually signs an actor in.
+The same dependency discipline applies at runtime: `resolveScenarioVirtualUsers` in
+`pikku-scenario-service.ts` imports the HTTP virtual user client lazily, so even a
+runner bundle only pays for the AI virtual user conversation loop when a scenario
+actually signs a virtual user in.
 
 **What this rules out:** importing playwright (or any driver) from core,
 tightening `reset`/`captureFailure` to required, letting `captureFailure` throw,
-reducing `TestIdSelector` to a plain string, or making the actor-client import
+reducing `TestIdSelector` to a plain string, or making the virtual-user-client import
 static.

package/knowledge/decisions/internals/workflow-run-capabilities-are-extensions-not-subclasses.md

@@ -18,7 +18,7 @@ The reason it is not a subclass is bundle size: a bundler drops an unused
 _module_ but never an unused class member. Anything declared on
 `PikkuWorkflowService` ships in every server built on Pikku, along with
 everything it imports. `PikkuScenarioService` (`pikku-scenario-service.ts`) is
-the one implementation today — steps, actors, lifecycle hooks, the browser
+the one implementation today — steps, virtual users, lifecycle hooks, the browser
 provider and the assertion wire members — and scenarios only ever run from
 `pikku scenario run`, so the whole surface stays behind an import that only the
 runner makes. It is not a workflow service in its own right because a scenario
@@ -33,7 +33,7 @@ installed rather than inherited. It pairs the extension with
 single external process driving a deployed app over its real transport: there
 is nothing to persist and no second worker to resume it.
 
-**What this rules out:** moving scenario steps, actors, hooks or the browser
+**What this rules out:** moving scenario steps, virtual users, hooks or the browser
 provider onto `PikkuWorkflowService`, making `PikkuScenarioService` extend it,
 or widening `WorkflowRunEngine` into "just pass the service" — each one puts the
 scenario runtime, and its transitive imports, into every deployed Pikku server.

package/knowledge/decisions/internals/workflow-scenario-assertions-never-retry-and-record-one-step.md

@@ -33,10 +33,10 @@ defaults are shorter than the assertion wrappers': `within` 15s, `interval`
 `requireScenarioEnv` (`scenario-step-guards.ts`) exists for the mirror-image
 reason: `env` is optional on the step wire because most steps need nothing from
 it, so the narrowing happens in one place with a message that says what to do,
-instead of every step file writing its own guard. The actor is not narrowed at
-all — a step that runs as somebody declares `actor: true` (or a `browser`
+instead of every step file writing its own guard. The virtual user is not narrowed at
+all — a step that runs as somebody declares `virtualUser: true` (or a `browser`
 binding, which cannot be provisioned without a window to open), and the runner
-injects `wire.actor` non-optionally into every binding and refuses to dispatch
+injects `wire.virtualUser` non-optionally into every binding and refuses to dispatch
 the step without one. A wire member can be required per binding; a property of
 one cannot, which is why it is not on `scenarioStep`. `scenarioStep`'s `verifyStepName` call doubles as the guard for `then`
 being a wire member — an accidental `await scenario` calls it with a resolve
@@ -50,5 +50,5 @@ the first argument only; `times` means at-least-once unless a count is given;
 
 **What this rules out:** giving scenario steps the workflow retry default,
 recording each poll iteration as its own step, treating a falsy `pollUntil`
-result as "not yet", making `pollUntil` throw on timeout, or narrowing `actor`
+result as "not yet", making `pollUntil` throw on timeout, or narrowing `virtualUser`
 by hand inside individual step files.

package/knowledge/decisions/internals/workflow-scenario-hooks-are-a-scenario-only-affordance.md

@@ -16,7 +16,7 @@ pass by a single external process.
 A hook is not a pikku function: it has no id, no meta and no schema, so it
 cannot go through `runPikkuFunc` and the runner records nothing for it. It gets
 exactly what the scenario body gets — the same wire (which is how it reaches the
-app through `actors`) and singleton services composed with this invocation's
+app through `virtualUsers`) and singleton services composed with this invocation's
 wire services — and nothing else. `ScenarioHookError` keeps the original error
 as `cause`, so the failure that actually happened is never lost behind the label
 saying which phase it happened in.

package/knowledge/decisions/internals/workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md

@@ -1,14 +1,14 @@
 ---
 type: decision
 title: Scenario prose is rendered out of typed calls, not parsed into them
-description: The inversion of cucumber — a readable report with no regex step registry to maintain
+description: A readable report with no regex step registry to maintain
 tags: workflow
 ---
 
 # Scenario prose is rendered out of typed calls, not parsed into them
 
 `scenario-prose.ts` renders the English sentence a reporter shows for a scenario
-step. It is the inversion of cucumber: instead of parsing English into a call
+step. Instead of parsing English into a call
 through a registry of regexes, the call is typed and the English is rendered out
 of it. The readable report survives without anyone maintaining a step-definition
 registry, and a step that no longer exists cannot leave a dangling phrase behind.

package/knowledge/decisions/internals/workflow-scenario-step-targets-are-string-literals-for-the-inspector.md

@@ -19,7 +19,7 @@ generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
 prose a reporter renders (`scenario-prose.ts`), never what executes.
 
 The prose direction is itself the decision: rather than parsing English into a
-call the way cucumber does, `composeStepProse` renders English out of a typed
+call through a regex registry, `composeStepProse` renders English out of a typed
 call, so a readable report survives without a regex registry paying for it. It
 lives in core so the CLI reporter and the console render the same sentence for
 the same step, and `renderStepTemplate` fills `{placeholders}` from the input

package/knowledge/decisions/internals/workflow-suspended-runs-keep-their-in-process-context.md

@@ -11,7 +11,7 @@ tags: workflow
 `completed | failed | cancelled`. `suspended` is deliberately absent: a
 suspended run stops a poll loop but can still be resumed, so anything the
 process holds for it — the run context, an extension's per-run state such as a
-scenario's live actor clients — has to survive. `WORKFLOW_END_STATES`, which
+scenario's live virtual user clients — has to survive. `WORKFLOW_END_STATES`, which
 `awaitRunEnd` uses to stop reading, does include `suspended`, because a poller
 should not wait on a run that needs an external nudge. The two sets are not
 interchangeable.

package/knowledge/decisions/security/a-bearer-token-checked-against-a-secret-reads-it-per-request.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: A bearer token checked against a secret is read per request, and an unreadable secret means no session
+description: The secretId form of authBearer reads the secret on every request; a missing or failing read leaves the request without a session rather than raising an error
+tags: core, middleware, auth
+---
+
+# A bearer token checked against a secret is read per request, and an unreadable secret means no session
+
+In `packages/core/src/middleware/auth-bearer.ts:57-70`, a token given as a
+literal `value` is compared directly (`:59-60`). A token given a `secretId` is
+read from the secret service on each request (`:63-64`). A failed read is caught
+and becomes `undefined` (`:65`), and the code comments that an unset secret means
+the feature is off, never a request error (`:62`).
+
+An undefined expected value skips the comparison (`:68`). `userSession` stays
+null, and `setSession` is not called (`:55`, `:75-77`). A malformed scheme is a
+different case: it throws `InvalidSessionError` (`:50-53`).
+
+The static and JWT branches of this middleware are covered by the existing
+questions `a-bearer-jwt-with-no-identity-becomes-a-session.md` and
+`should-a-wrong-bearer-token-be-anonymous-or-refused.md`.
+
+**What this rules out:** turning a missing or unreadable signing secret into a
+server error, and caching the secret value across requests in the middleware
+closure.

package/knowledge/decisions/security/a-call-without-a-session-raises-missing-session-not-forbidden.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A call without a session raises MissingSessionError, and a missing scope raises MissingScopeError
+description: The function runner separates the no-session refusal from the scope and permission refusals, so a caller can tell a missing login from a denied grant
+tags: core, errors, sessions, scopes
+---
+
+# A call without a session raises MissingSessionError, and a missing scope raises MissingScopeError
+
+`resolveSession` in `packages/core/src/function/function-runner.ts` (line 64) loads a stored session when there is a user id. It throws nothing.
+
+The refusal is in `executeFunction`. A sessionless function requires a session only when its wiring, its own config, or the addon says `auth: true` (`function-runner.ts:385-395`). That refusal throws `MissingSessionError` (`function-runner.ts:392`). A `pikkuFunc` with no session throws the same error unconditionally (`function-runner.ts:402`). The class is at `packages/core/src/errors/errors.ts:36`.
+
+Scope checks use a different error. `verifyScopes` throws `MissingScopeError` (`packages/core/src/scopes.ts:84-86`, class at `packages/core/src/errors/errors.ts:118`).
+
+Permission checks use `ForbiddenError` with the message `Permission denied` (`packages/core/src/permissions.ts:155`, `:166`, class at `packages/core/src/errors/errors.ts:57`).
+
+So the three refusals are distinct: no login, a missing scope, and a failed permission function.
+
+**What this rules out:** reporting a call with no session as a `ForbiddenError`, and reading a `ForbiddenError` from the runner as proof that a session exists but lacks a grant.

package/knowledge/decisions/security/a-caller-cookie-wins-over-the-jar-for-the-same-name.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: A cookie the caller sets wins over the jar's copy of the same name
+description: createCookieJar sends the caller's cookie for a name and drops the jar's copy of that name, so one request never carries the same cookie twice
+tags: core, scenario, cookies
+---
+
+# A cookie the caller sets wins over the jar's copy of the same name
+
+In `createCookieJar` (`packages/core/src/services/scenario-cookie-jar.ts`)
+the jar builds the outgoing `cookie` header from the caller's own header and the
+jar's held cookies. A held cookie is left out when the caller's header already
+names it. The code comment says a request that already carries a session "is
+stating which one it means, and emitting the jar's copy alongside it sends the
+same name twice."
+
+The rule is per name, not per request. Cookies the caller did not name still go
+out from the jar. The jar's `Set-Cookie` handling, which replaces a reissued
+cookie rather than sending both, is covered by
+[Scenario sessions are isolated per virtual user and reset between scenarios](workflow-scenario-sessions-are-isolated-per-virtual-user-and-per-scenario.md).
+
+**What this rules out:** sending two values of one cookie name in a request, and
+letting the jar's held session override a session the caller has chosen to send.

package/knowledge/decisions/security/a-channel-lifecycle-acts-as-the-socket-upgrade-session.md

@@ -0,0 +1,16 @@
+---
+type: decision
+title: A channel lifecycle acts as the session the socket upgrade established
+description: onConnect and onDisconnect run with the userSession captured during the socket upgrade, both in the wire they receive and as the session service passed to runPikkuFunc
+tags: core, channel, sessions, lifecycle
+---
+
+# A channel lifecycle acts as the session the socket upgrade established
+
+`runChannelLifecycleWithMiddleware` in `packages/core/src/wirings/channel/channel-common.ts` takes an optional `userSession`. The comment says it is established while the socket upgrades, so `onConnect` can tell who connected (`channel-common.ts:43-47`). The same function also serves `connect` and `disconnect` (`channel-common.ts:38`).
+
+The wire for the lifecycle is built from that session when one exists (`channel-common.ts:78`). The lifecycle function then runs through `runPikkuFunc` with `sessionService: userSession` (`channel-common.ts:84-93`). So the lifecycle reads and writes the same session the upgrade produced, for both connect and disconnect.
+
+The related decision that records when the user id is stored is [a channel's user id is persisted only after onConnect middleware has run](../internals/channel-user-id-is-persisted-after-onconnect-middleware-runs.md).
+
+**What this rules out:** running a channel's disconnect handler as a different identity than the one that connected the socket, and building the lifecycle wire without the upgrade session when one was established.

package/knowledge/decisions/security/a-channel-requires-a-session-unless-it-says-auth-false.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: A channel requires a session unless it says auth: false
+description: The channel-level requirement is auth !== false, and a message handler's own auth, when it is set, decides for that message in either direction
+tags: core, channel, auth
+---
+
+# A channel requires a session unless it says auth: false
+
+Both channel runners compute the channel-level requirement as
+`channelConfig.auth !== false`: `packages/core/src/wirings/channel/channel-runner.ts:142`
+and `packages/core/src/wirings/channel/channel-handler.ts:75`. An absent `auth`
+therefore requires a session. `channel.types.ts:67-76` documents the same rule and
+says why: a proxy in front of a channel needs to tell public from private.
+
+Per message, `validateAuth` (`channel-handler.ts:49-65`) uses the channel's
+`requiresSession` when the handler is a bare function or has no `auth` of its own
+(`:50-58`). When the handler object sets `auth`, that value wins (`:58-60`). The
+check then fails only when `auth` is true and there is no session (`:62-64`).
+
+So a message handler's `auth: false` loosens a channel that requires a session for
+that message, and `auth: true` tightens a public channel for that message. A
+rejected message gets the reply described in the question
+`unauthorized-channel-replies-escape-the-declared-out-type.md`.
+
+**What this rules out:** treating a channel with no `auth` flag as public.

package/knowledge/decisions/security/a-credential-read-path-follows-its-declared-type-not-absence.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: A credential's read path follows its declared type, never a missing value
+description: The credential wire service reads a wire credential only from the user's store and a singleton only from the deployment, so an absent user value never falls back to the deployment's token
+tags: core, credentials, wire, singleton
+---
+
+# A credential's read path follows its declared type, never a missing value
+
+`packages/core/src/services/credential-wire-service.ts` decides where each
+credential is read from. The doc comment says the choice is "decided by what the
+credential IS — its declared type, as the wiring may have overridden it — and
+never by whether a per-user lookup came back empty", because an absence-driven
+fallback "would let a user who has not connected read the deployment's own token"
+(`credential-wire-service.ts:6-10`).
+
+The resolution type is `{ mode: 'wire' } | { mode: 'singleton' }`
+(`credential-wire-service.ts:12`).
+
+In `doLoad`, the user's store is read with `getAll(userId)`, and any name the
+resolution marks `singleton` is skipped (`credential-wire-service.ts:103-104`).
+The comment says this stops a user "in charge of a slot the deployment owns"
+(`credential-wire-service.ts:116-121`).
+
+`loadDeploymentCredentials` fetches only `singleton` names from the deployment
+service (`credential-wire-service.ts:137-143`). A `wire` name is skipped there
+(`credential-wire-service.ts:138`), and the comment says a wire credential "can
+never pick up a platform value" (`credential-wire-service.ts:127-130`).
+
+**What this rules out:** a `wire` credential falling back to the deployment's
+value when the user has none, and a user's stored value being imported under a
+name the deployment declared as `singleton`.

package/knowledge/decisions/security/a-credential-type-is-a-literal-the-inspector-checks-at-declaration.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: A credential's wire or singleton type is a literal the inspector checks at declaration
+description: defineCredential is a no-op read by AST, so its type must be a literal 'wire' or 'singleton' and the inspector refuses any other value
+tags: core, credentials, inspector, declaration
+---
+
+# A credential's wire or singleton type is a literal the inspector checks at declaration
+
+`defineCredential` in `packages/core/src/wirings/credential/define-credential.ts` is a
+no-op. Its doc comment says the CLI reads the call by AST, so "the declaration must
+be a top-level literal" (`define-credential.ts:4-5`). `type: 'wire'` is per-user and
+`type: 'singleton'` is platform-wide (`define-credential.ts:6`).
+
+The inspector finds the call by its identifier (`packages/inspector/src/add/add-credential.ts:27`)
+and requires a `type` property. Anything other than `'singleton'` or `'wire'` is a
+critical error: "missing or has invalid 'type' property. Must be 'singleton' or
+'wire'" (`add-credential.ts:64-68`).
+
+The read path that follows from that type is in
+[a credential's read path follows its declared type, never a missing value](a-credential-read-path-follows-its-declared-type-not-absence.md).
+This note covers the declaration only: the type is decided where the credential is
+declared, and the inspector rejects a declaration whose type is missing or not one of
+the two literals.
+
+**What this rules out:** computing a credential's type from a variable or at runtime,
+and accepting a declaration whose type is missing or spelled differently.

package/knowledge/decisions/security/a-first-party-cookie-is-written-only-after-its-purposes-consent.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: A first-party tracking cookie is written only after its purposes are consented
+description: mintCookie writes a new cookie only when every purpose it requires is true in the consent record, and writes nothing on a wire with no HTTP response
+tags: core, analytics, consent, cookies
+---
+
+# A first-party tracking cookie is written only after its purposes are consented
+
+`packages/core/src/analytics/mint-cookie.ts` creates a first-party cookie when
+none exists. The doc comment says writing the cookie "IS the act consent governs",
+so a minter that runs before the banner is answered has already done what the
+send gate was meant to prevent (`mint-cookie.ts:11-15`).
+
+The consent check is `permitted`. It returns true when no purposes are required,
+and otherwise requires each purpose to be exactly `true` in the consent record
+(`mint-cookie.ts:29-35`). A purpose missing from the record counts as refused.
+`mintCookie` runs that check after it has found no existing cookie and no cached
+value (`mint-cookie.ts:72`).
+
+An existing cookie is returned before the consent check (`mint-cookie.ts:63-64`).
+Reading a cookie the visitor already holds is therefore not gated by consent. The
+`overwrite` option is the only way to replace it (`mint-cookie.ts:19-26`).
+
+A wire with no HTTP response returns `undefined` and writes nothing
+(`mint-cookie.ts:70-71`), as the doc comment says for cron tasks and queue workers
+(`mint-cookie.ts:50-53`).
+
+The value is cached per wire, so a second call in one request returns the same
+identity (`mint-cookie.ts:66-68`, `77`, and the comment at `mint-cookie.ts:46-48`).
+
+**What this rules out:** writing a tracking cookie before its purposes are
+consented, and minting an identity on a non-HTTP wire.

package/knowledge/decisions/security/a-readonly-session-reaches-only-readonly-functions.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A readonly session reaches only functions declared readonly
+description: A session flagged readonly is refused by every function not declared readonly, checked straight after the session is required and before scopes
+tags: core, auth, function-runner
+---
+
+# A readonly session reaches only functions declared readonly
+
+`CoreUserSession.readonly` (`packages/core/src/types/core.types.ts`) restricts a
+session to functions declared `readonly`. In `runPikkuFunc`
+(`packages/core/src/function/function-runner.ts`) the check is
+`if (session?.readonly && !funcMeta.readonly) throw new ReadonlySessionError()`.
+It runs after the missing-session check and before scopes, permissions and input
+validation, so a readonly session is refused before any work is done for a
+mutating function. The unit test "should reject readonly sessions for
+non-readonly functions" in `function-runner.test.ts` pins the behaviour.
+
+Core never sets the flag. Whoever builds the session decides it, and core only
+enforces it. Readonly is a property of the session, not of a scope, so a scope
+grant cannot widen what a readonly session may reach.
+
+**What this rules out:** expressing read-only access as a scope the session
+happens to lack, and letting a readonly session call a mutating function on the
+grounds that its scopes cover it.

package/knowledge/decisions/security/a-scaffold-flag-says-a-surface-exists-not-who-may-call-it.md

@@ -13,11 +13,16 @@ The field is gone. `PikkuScaffoldFeature` is now `boolean | { path?: string }`:
 whether the surface is generated, and where the file goes.
 
 The field was a second gate in front of one that already runs. `resolveSession`
-in `packages/core/src/function/function-runner.ts` throws `ForbiddenError` for a
-`pikkuFunc` with no session, unconditionally; a `pikkuSessionlessFunc` requires
-one when its own `auth: true` says so, when its wiring says so, or when
-`resolveAddonAuth` does. That is where authentication is decided, per function,
-by whoever wrote it. A config flag three directories away could only be coarser
+in `packages/core/src/function/function-runner.ts` (line 64) only loads a stored
+session; it throws nothing. The refusal is in `executeFunction`: a `pikkuFunc`
+with no session throws `MissingSessionError` (line 402, class at
+`packages/core/src/errors/errors.ts:36`), unconditionally. A
+`pikkuSessionlessFunc` throws the same error (line 392) only when its own
+`auth: true` says so, when its wiring says so, or when `resolveAddonAuth` does. That is where authentication is decided, per function,
+by whoever wrote it. Neither refusal is a `ForbiddenError`: both throw `MissingSessionError`
+(`function-runner.ts:392`, `:402`; class at `packages/core/src/errors/errors.ts:36`). The split between
+that error, `MissingScopeError` and `ForbiddenError` is recorded in
+[a call without a session raises MissingSessionError](./a-call-without-a-session-raises-missing-session-not-forbidden.md). A config flag three directories away could only be coarser
 than that, and being coarser was the whole problem the earlier decision was
 trying to work around by defaulting it closed.
 

package/knowledge/decisions/security/a-scheduled-virtual-user-run-needs-no-admin-at-run-time.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: A scheduled virtual-user run needs no admin at run time
+description: An admin may start a virtual-user run, but the run itself never depends on an admin being signed in or on an admin's credential
+tags: services, auth, workflow
+---
+
+# A scheduled virtual-user run needs no admin at run time
+
+The people who set up virtual-user runs are not technical. A run must keep
+working after they stop being around, and it must not depend on any admin being
+signed in or on any admin's credential.
+
+An admin clicking "run" or creating a schedule is the authorization step. Once
+the schedule exists, the run is started by the app's own scheduler and performs
+the test as a provisioned test account (see
+[virtual-user-flagged users only](virtual-user-sign-in-only-works-for-virtual-user-flagged-users.md)).
+
+The run presents no credential at all. `executeVirtualUserRun`
+(`packages/core/src/wirings/virtual-user/virtual-user-scaffold.ts`) builds its
+virtual users with `signIn: inProcessSignIn(auth)`, which calls the app's
+server-only sign-in endpoint through `auth.api`
+(`packages/core/src/services/virtual-user-sign-in.ts`). The code asking is the
+app, so there is no key for an admin to hold or refresh.
+
+**What this rules out:** a run that borrows an admin's session or key, and a run
+that depends on a person to refresh a credential.

package/knowledge/decisions/security/a-scoped-credential-view-is-limited-to-declared-names.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: A scoped credential service is limited to the names its package declared
+description: ScopedCredentialService refuses any credential name outside the package's declared set, filters getAll to that set, and refuses to enumerate users
+tags: core, credentials, scoping
+---
+
+# A scoped credential service is limited to the names its package declared
+
+`packages/core/src/services/scoped-credential-service.ts` wraps a
+`CredentialService` with the set of names a package declared. The doc comment
+says it "cannot reach a credential it never declared, or enumerate the app's
+users" (`scoped-credential-service.ts:6-9`).
+
+- `get`, `set`, `delete`, `has` and `getUsersWithCredential` each call
+  `assertAllowed` and throw `Access denied to credential` for an undeclared name
+  (`scoped-credential-service.ts:16-20`, `23`, `28`, `33`, `38`, `54`).
+- `getAll(userId)` returns only the declared names that the user holds
+  (`scoped-credential-service.ts:42-51`).
+- `getAllUsers` always throws (`scoped-credential-service.ts:58-62`).
+
+Writes are allowed for declared names (`scoped-credential-service.ts:27-30`), per
+the doc comment at `scoped-credential-service.ts:6-8`.
+
+**What this rules out:** a package reading or writing another package's
+credential, and a package listing every user of the app.

package/knowledge/decisions/security/a-scoped-secret-view-reads-only-declared-keys-and-never-writes.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A scoped secret view reads only its declared keys and never writes
+description: ScopedSecretService checks every read against an allowed-key set and refuses all writes, unlike the credential service that stays writable
+tags: core, secrets, scoping
+---
+
+# A scoped secret view reads only its declared keys and never writes
+
+`packages/core/src/services/scoped-secret-service.ts` wraps a `SecretService`
+with a set of allowed keys (`scoped-secret-service.ts:4-8`).
+
+Every read is checked first. `getSecret`, `hasSecret` and `getSecrets` each call
+`assertAllowed`, which throws `Access denied to secret key` for any key outside
+the set (`scoped-secret-service.ts:10-14`, `17`, `22`, `43`).
+
+Every write is refused. `setSecret`, `setEncryptedSecret` and `deleteSecret`
+throw unconditionally (`scoped-secret-service.ts:26-38`).
+
+The credential counterpart is different. `scoped-credential-service.ts` says it
+"stays writable — an addon refreshing its own OAuth token is the normal case"
+(`scoped-credential-service.ts:6-8`).
+
+**What this rules out:** an addon reading a secret it did not declare, and an
+addon writing or deleting any secret through this view.