@pikku/core 0.12.142 → 0.12.144

package/dist/services/in-memory-queue-service.d.ts

@@ -1,8 +0,0 @@
-import type { QueueService, JobOptions } from '../wirings/queue/queue.types.js';
-export declare class InMemoryQueueService implements QueueService {
-    readonly supportsResults = false;
-    private jobCounter;
-    add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>;
-    private backoffDelay;
-    getJob(): Promise<null>;
-}

package/dist/services/in-memory-queue-service.js

@@ -1,54 +0,0 @@
-import { runQueueJob } from '../wirings/queue/queue-runner.js';
-// knowledge: decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md
-export class InMemoryQueueService {
-    supportsResults = false;
-    jobCounter = 0;
-    async add(queueName, data, options) {
-        const jobId = `inmem-${++this.jobCounter}`;
-        const maxAttempts = Math.max(1, options?.attempts ?? 1);
-        let attemptsMade = 0;
-        const createdAt = new Date();
-        const payload = data === undefined ? data : JSON.parse(JSON.stringify(data));
-        const runAttempt = async () => {
-            attemptsMade++;
-            const job = {
-                id: jobId,
-                queueName,
-                data: payload,
-                status: () => 'active',
-                metadata: () => ({ attemptsMade, maxAttempts, createdAt }),
-                pikkuUserId: options?.pikkuUserId,
-            };
-            try {
-                await runQueueJob({ job });
-            }
-            catch (e) {
-                if (attemptsMade < maxAttempts) {
-                    // Fire-and-forget retry: runAttempt catches every error itself.
-                    setTimeout(() => void runAttempt(), this.backoffDelay(options?.backoff, attemptsMade));
-                }
-                else {
-                    console.error(`[InMemoryQueue] Job ${jobId} on ${queueName} failed after ${attemptsMade} attempt(s):`, e.message);
-                }
-            }
-        };
-        const delay = options?.delay ?? 100 + Math.floor(Math.random() * 201);
-        // Fire-and-forget: runAttempt catches every error itself.
-        setTimeout(() => void runAttempt(), delay);
-        return jobId;
-    }
-    backoffDelay(backoff, attemptsMade) {
-        const baseDelay = typeof backoff === 'object' ? (backoff.delay ?? 50) : 50;
-        if (backoff === 'exponential' ||
-            (typeof backoff === 'object' && backoff?.type === 'exponential')) {
-            return Math.min(2 ** (attemptsMade - 1) * baseDelay, 2000);
-        }
-        if (typeof backoff === 'object' && backoff?.type === 'fixed') {
-            return backoff.delay ?? 50;
-        }
-        return 50;
-    }
-    async getJob() {
-        return null;
-    }
-}

package/dist/services/in-memory-trigger-service.d.ts

@@ -1,4 +0,0 @@
-import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js';
-export declare class InMemoryTriggerService extends PikkuTriggerService {
-    start(): Promise<void>;
-}

package/dist/services/local-gateway-service.d.ts

@@ -1,6 +0,0 @@
-import type { GatewayService } from './gateway-service.js';
-export declare class LocalGatewayService implements GatewayService {
-    private activeAdapters;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-}

package/dist/utils/hash.d.ts

@@ -1,2 +0,0 @@
-export declare function canonicalJSON(obj: unknown): string;
-export declare function hashString(input: string, length?: number): string;

package/dist/utils/hash.js

@@ -1,23 +0,0 @@
-import { createHash } from 'node:crypto';
-export function canonicalJSON(obj) {
-    return JSON.stringify(sortDeep(obj));
-}
-function sortDeep(value) {
-    if (value === null || value === undefined) {
-        return value;
-    }
-    if (Array.isArray(value)) {
-        return value.map(sortDeep);
-    }
-    if (typeof value === 'object') {
-        const sorted = {};
-        for (const key of Object.keys(value).sort()) {
-            sorted[key] = sortDeep(value[key]);
-        }
-        return sorted;
-    }
-    return value;
-}
-export function hashString(input, length = 16) {
-    return createHash('sha256').update(input).digest('hex').slice(0, length);
-}

package/knowledge/decisions/index.md

@@ -1,19 +0,0 @@
----
-type: overview
-title: Decisions
-description: Rules chosen in @pikku/core, and what each one rules out
----
-
-# Decisions
-
-A rule that was chosen, and what it rules out.
-
-Each note here replaces a comment that was carrying reasoning inside the source.
-If you are about to "clean up" something in core that looks pointless, search
-here first — several of these exist because the obvious simplification was tried
-and broke something.
-
-<!-- pikku:knowledge-index -->
-- [internals](internals/index.md) — a rule about how it works under the hood, and why
-- [security](security/index.md) — a rule about who may do what
-<!-- /pikku:knowledge-index -->

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

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

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

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

package/knowledge/decisions/internals/a-held-run-is-woken-later-not-retried.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: A held run is woken later, not retried
-description: 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
-tags: [workflows, leases, queues]
----
-
-# A held run is woken later, not retried
-
-Every message on the orchestrator queue carries news the run has to see — a step
-finished, a child ended — so a message that finds the run held by another pass
-cannot simply be dropped. Throwing it back to the queue looks equivalent and is
-not: it spends the retries the queue keeps for genuine failures. pg-boss gives an
-orchestrator message six attempts on an exponential backoff, the last about 55
-seconds in; a pass that holds the run longer than that leaves the message dead
-and the run `running` forever.
-
-So a `LeaseTakenError` or `LeaseLostError` enqueues a new orchestrator message
-with a one-second delay (`RUN_LEASE_RETRY_MS`) and the current message succeeds.
-`verifiers/workflows/src/runners/run-lease.runner.ts` holds a run's lease for 90
-seconds and checks the run still completes.
-
-The same errors never fail an inline run: its body already wrote its outcome,
-and losing the lease afterwards says only that the outcome was not produced
-alone — the run keeps the status it wrote.
-
-**What this rules out:** treating a taken run lease as a queue failure, and
-marking a run failed because its lease was lost.

package/knowledge/decisions/internals/a-non-streaming-agent-run-registers-with-agentrunstate-too.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: A non-streaming agent run registers with agentRunState on the same terms as a streaming one
-description: Otherwise interruptAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
-tags: core, agent
----
-
-# A non-streaming agent run registers with `agentRunState` too
-
-`runAgent` registers its run with `agentRunState` exactly as `streamAgent`
-does, even though nothing is streaming and there is no channel to interrupt.
-
-`interruptAgent` resolves a run through `agentRunState` first, checks ownership,
-then looks for a local abort handle. A run that skipped registration is invisible
-at the first step. A run that registered but has no handle is visible, passes the
-ownership check, and then cannot be stopped — which the interrupt path reports as
-"running on another instance". That message would be wrong and actively
-misleading: the run is right here, and the deployment is single-instance.
-
-**What this rules out:** treating registration as a streaming concern. It is an
-addressability concern, and the two paths have to be addressable the same way for
-the interrupt path's diagnosis to mean anything.

package/knowledge/decisions/internals/a-reset-suite-makes-the-dev-seed-the-fixture.md

@@ -1,50 +0,0 @@
----
-type: decision
-title: With scenarios.reset on, the dev seed is the fixture every assertion is written against
-description: 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
-tags: cli, scenarios
----
-
-# A reset suite makes the dev seed the fixture
-
-`scenarios.reset` takes a copy of every table when the suite starts and restores
-that copy between scenarios. It is a snapshot-and-restore, not a
-truncate-and-reseed: nothing replays the seed file, and nothing regenerates its
-rows.
-
-Two things follow, and both are easy to get wrong.
-
-**The seed is the fixture.** Before a reset was available, a project usually had
-a hand-rolled reset RPC that wiped and re-created the handful of rows its
-scenarios touched. That RPC was the fixture and the seed was scenery. With the
-rollback on, the whole seed is in scope — every booking, invoice and event a
-developer put there for their own convenience is now a row some scenario can
-count. Assertions written as counts against the old narrow fixture go wrong the
-moment the baseline widens.
-
-**A date literal in the seed expires.** A seed is applied once, and from then on
-the restore keeps handing back the same rows. Write `'2026-03-14'` and the
-fixture is correct on the day it was written and quietly wrong a month later —
-the booking that was supposed to be upcoming is in the past, and the scenario
-that asserts on it fails for a reason that has nothing to do with the code. Seed
-dates belong relative to the moment the seed is applied:
-
-```sql
-INSERT INTO booking (id, starts_at, ends_at) VALUES
-  ('b_upcoming', date('now', '+200 days'), date('now', '+207 days')),
-  ('b_ended',    date('now', '-8 days'),   date('now', '-1 days'));
-```
-
-`date('now', ...)` in sqlite, `now() + interval '200 days'` in postgres. Pick the
-offsets so each row sits unambiguously on the side of whatever boundary the
-scenarios test, rather than a day away from it.
-
-There is a third limit worth stating plainly: the baseline is the database _as
-the suite starts_, so it is not a pristine seed. Run N+1 inherits whatever run N
-left behind. A value that must be unique in the database — an invoice number, a
-reference code — has to be scoped to the run, not hard-coded, or the second run
-collides with the first.
-
-**What this rules out:** treating the reset as "the suite starts from the seed
-every time". It starts from wherever the database was, and keeps returning
-there.

package/knowledge/decisions/internals/a-resumed-agent-turn-is-as-interruptible-as-the-first.md

@@ -1,20 +0,0 @@
----
-type: decision
-title: A resumed turn is as interruptible as the first one
-description: It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
-tags: core, agent
----
-
-# A resumed turn is as interruptible as the first one
-
-Resuming after an approval registers for interruption on the same terms as the
-original turn.
-
-It is the same person listening to the same voice, so the reason to allow
-interruption has not changed. And after an approval is precisely where most of
-the reply gets spoken: an approved delete is followed by the agent describing
-what it did, which is a normal thing for a listener to talk over.
-
-**What this rules out:** treating the resume as a short continuation not worth
-wiring for interruption. By volume of speech it is usually the larger half of
-the exchange.

package/knowledge/decisions/internals/a-scenario-step-template-is-offered-unfilled.md

@@ -1,21 +0,0 @@
----
-type: decision
-title: A scenario step's prose template is offered to a virtual user unfilled
-description: 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
-tags: core, virtual-user
----
-
-# A scenario step's prose template is offered unfilled
-
-When a scenario step becomes a catalogue entry, its prose template goes in with
-its placeholders intact — braces and all.
-
-A reporter fills those placeholders from a run that already happened. There is
-no run yet at derivation time, so there is nothing to fill them from. More
-importantly, filling them would answer the wrong question: "invites {email}"
-tells the user to choose someone, where "invites ada@example.com" tells it whom
-— and _whom_ is the scenario author's answer, not something the virtual user
-worked out.
-
-**What this rules out:** substituting example or fixture values to make the
-catalogue read more naturally. It reads better and tests less.

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

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

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

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

package/knowledge/decisions/internals/a-secret-that-fails-to-decrypt-fails-the-whole-read.md

@@ -1,49 +0,0 @@
----
-type: decision
-title: A secret that fails to decrypt fails the whole read
-description: 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
-tags: crypto, storage
----
-
-# A secret that fails to decrypt fails the whole read
-
-Every store's bulk read — `getSecrets` in the kysely, mongodb and redis secret
-services — wraps the `getKEK` + `envelopeDecrypt` pair in a try/catch that
-rethrows:
-
-```
-Failed to decrypt secret "<key>" (key_version <n>): the configured KEK does not
-match the key it was wrapped under
-```
-
-with the original crypto error as `cause`. A key that has no row at all is still
-simply absent from the returned object; only a row that exists and will not
-decrypt is fatal.
-
-Those two cases look similar and are not. A missing key is an ordinary, callable
-state — the caller asked for something that was never stored, and the typed
-secret layer above already decides what to do about an absent value. A stored
-row that will not decrypt means the service is holding ciphertext it cannot
-read: a `PIKKU_SECRET_KEK` that does not match what the value was wrapped under,
-a `previousKey` missing for an older `keyVersion`, or a change to the derivation
-itself. Nothing the caller can do downstream makes that better.
-
-Dropping the row instead hands back a partial map, and the failure re-emerges
-somewhere with no connection to secrets — an auth middleware reading an
-undefined signing key and answering "server configuration error", a provider
-client constructed with `undefined` credentials and 401-ing. The name of the
-secret and the `key_version` it was wrapped under are precisely the two facts
-that turn that into a one-line fix, and they are known at the catch site and
-nowhere after it.
-
-This matters most at exactly the moment it is least convenient: a change to
-`deriveKEK` makes _every_ previously stored secret undecryptable at once. Loud
-failure names the first one; silence produces an empty map and a support ticket.
-
-**What this rules out:** a `getSecrets` that skips unreadable rows; returning
-`undefined` for a row that exists; collecting failures and returning them
-alongside the successes, which just moves the ignoring one level up; and
-treating a missing key as an error, which would break callers that legitimately
-probe for optional secrets.
-
-See [[the-kek-salt-is-scoped-to-the-key-version]].

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

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

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

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

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

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

package/knowledge/decisions/internals/a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md

@@ -1,21 +0,0 @@
----
-type: decision
-title: A virtual user decides whether to trust its notes once per turn, by one roll
-description: The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
-tags: core, virtual-user
----
-
-# A virtual user decides whether to trust its notes once per turn
-
-Each turn the run makes one weighted decision: does this user act on what it
-already recorded, or go and look again.
-
-That single roll is where the dispositions differ. `stale` almost always trusts
-its notes — that is what makes it stale. A `newcomer` has none to trust. An
-`auditor` re-checks nearly everything, which is the entire point of an auditor.
-Expressing it as one probability keeps the difference between those runs in one
-readable place instead of spread through three prompts as English that drifts.
-
-**What this rules out:** encoding "you are suspicious of your own notes" into
-each disposition's prompt text, where the behaviour becomes a property of how
-the model reads prose rather than something the run controls and can report.

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

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