@pikku/core 0.12.79 → 0.12.82

package/knowledge/decisions/internals/a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md

@@ -0,0 +1,45 @@
+---
+type: decision
+title: A workflow's wire is built from the run record, not from the RPC service
+description: 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
+tags: core, workflow
+---
+
+# A workflow's wire is built from the run record, not from the RPC service
+
+`PikkuWorkflowService` builds a fresh wire each time it runs a workflow body or
+starts a child. For a while it filled parts of that wire from the RPC service it
+had been handed:
+
+```ts
+session: rpcService?.wire?.session,
+rpc: rpcService?.wire?.rpc,
+pikkuUserId: rpcService.wire?.pikkuUserId,
+```
+
+`PikkuRPC` has no `wire`. Neither does the object `getContextRPCService`
+actually returns — `ContextAwareRPCService` holds its wire *privately* and
+exposes `invoke`, `remote`, `exposed`, `startWorkflow`, `agent` and
+`rpcWithWire`, and nothing else. Every one of those reads was `undefined`, and
+the `rpcService: any` parameter type is what kept the compiler quiet about it.
+
+The consequence was silent and one-directional: a child workflow started from a
+step never inherited the `pikkuUserId` its parent was running as, so a queued
+child ran as nobody. Nothing failed — the field was simply absent, and the run
+proceeded.
+
+**The run record is the carrier.** `WorkflowRun.wire` is durable, is written
+when the run is created, and survives the process boundary a queued step
+crosses, which is exactly what a live service reference cannot do. Both the
+run-body wire and the child-run wire now read `run.wire?.pikkuUserId`.
+
+`session` and `rpc` are not copied at all. `runPikkuFunc` attaches `rpc` lazily
+for the duration of an invocation and restores the previous descriptor
+afterwards, and it resolves the session from the session store using
+`pikkuUserId` — so both were being overwritten moments later anyway. The wire
+these paths construct is a `PikkuRawWire` for that reason: it genuinely has no
+`rpc` yet, and saying so is what let the dead reads be found.
+
+**What this rules out:** reaching for the RPC service to answer "who is this
+running as". It cannot answer, and the shape of the question hides that.
+Anything a step needs to know about its caller has to be on the run.

package/knowledge/decisions/internals/addon-pikku-meta-ships-at-the-package-root-or-under-dist.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: An addon's .pikku meta ships at the package root or under dist, and readers probe both
+description: 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
+tags: services
+---
+
+# An addon's .pikku meta ships at the package root or under dist, and readers probe both
+
+An addon generates `.pikku/` at its project root, and whether that directory
+reaches the published tarball at the root or inside `dist/` depends on the
+addon's own `tsconfig` and `files` — both layouts are in the wild and both are
+supported. The published `exports` map hides the difference for anyone
+resolving by specifier: `"./.pikku/*"` points at wherever it landed, so
+`require.resolve('<pkg>/.pikku/scopes/pikku-scopes-meta.gen.json')` works for
+either shape, and that is the resolution every consumer should prefer.
+
+Code that builds the path itself must probe both. `addonPikkuDir`
+(`packages/addon/pikku-console/src/lib/derive-instance-overrides.ts`) tries
+`<pkg>/.pikku` then `<pkg>/dist/.pikku` and returns `null` when neither exists.
+The reason to say so out loud is the failure mode: a reader that assumes the
+root finds nothing under a `dist`-shipping addon and cannot distinguish that
+from an addon that declares no secrets, variables or scopes at all. Both answers
+are "empty", and the wrong one is indistinguishable from a correct one until
+something downstream reports an addon as ready when its secrets were never
+checked.
+
+**What this rules out:** hardcoding either path in a consumer, and treating a
+missing directory as evidence an addon declares nothing without having tried
+both. It also rules out normalising the layout by making the CLI move the
+directory at publish time — the export map already makes the layout private to
+the package, and the addons shipping each shape are already published.

package/knowledge/decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: Loading agent context waits for a tool result that may still be landing
+description: 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
+tags: core, ai-agent
+---
+
+# Loading agent context waits for a tool result that may still be landing
+
+Before a turn loads its thread, it settles any tool whose run was interrupted
+but whose result is still being written to that thread.
+
+The window is small and, on a typed interface, usually irrelevant — a person
+takes seconds to write the next message. In voice it is not: the next turn lands
+within a second or two of the last one. Without the wait, the model loads a
+thread that is missing the very result the user is about to ask about, and
+answers as though the tool never ran.
+
+**What this rules out:** treating the settle as belt-and-braces and dropping it
+to save a round trip. The failure it prevents is a confidently wrong answer, not
+an error, and it only appears on the fastest transport.

package/knowledge/decisions/internals/agent-speech-travels-as-a-custom-agui-event.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Agent speech travels as a CUSTOM AG-UI event rather than being dropped
+description: 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
+tags: core, ai-agent
+---
+
+# Agent speech travels as a CUSTOM AG-UI event
+
+The AG-UI protocol has no event type for synthesized speech, so the bridge
+forwards it as `CUSTOM`, the same way it forwards the other pikku-specific
+events.
+
+The alternative was tried: the mapper dropped the event, on the reasoning that a
+protocol without a speech event has no way to carry one. The result is a voice
+agent reached over HTTP that is completely silent — `voiceOutput` synthesizes
+every sentence, the provider bills for every one of them, and none of it gets
+past the mapper. Nothing errors, so there is nothing to find.
+
+**What this rules out:** filtering unknown event types at the AG-UI boundary as
+a tidiness measure. `CUSTOM` exists precisely so a protocol gap degrades to
+"the client ignores it" rather than "the server threw the work away".

package/knowledge/decisions/internals/an-addon-scope-root-loses-to-a-root-the-host-already-declares.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: An addon's scope root loses to a root the host app already declares
+description: loadAddonFunctionsMeta merges addon scope trees by root name, first declaration wins, so an addon sharing a root with its host contributes nothing — silently
+tags: services
+---
+
+# An addon's scope root loses to a root the host app already declares
+
+`loadAddonFunctionsMeta`
+(`packages/inspector/src/utils/load-addon-functions-meta.ts`) reads each wired
+addon's `pikku-scopes-meta.gen.json` and pushes its entries into
+`state.scopes.definitions`, skipping any whose root name is already present. The
+host app's own declarations were inspected first, so the host always wins.
+
+The skip is per **root**, not per node. An addon declaring `admin.console.*` in
+an app that declares `admin` contributes none of it — not the root it shares,
+and not the branch the app never declared. Nothing errors: the scopes simply do
+not exist, so `ScopeId` never gains them, no role can be granted one, and every
+addon function requiring one denies everybody. The failure surfaces as a
+`MissingScopeError` against a scope that cannot be granted, which reads as a
+permissions bug rather than a merge that dropped.
+
+This is a different rule from
+[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): that one
+is about `flattenScopeDefinitions` deduping ids *within* a build where both
+declarations are present and identical. This one is about the addon's copy never
+arriving. The consequence for addon authors is the same either way — own a root
+outright, named for the package or vendor, and nest everything under it. It is
+why `@pikku/addon-console` declares `pikku:console:*` rather than
+`admin:console:*`.
+
+**What this rules out:** shipping an addon whose scopes hang off a root a host
+is likely to declare, and deep-merging the two trees here so both survive. A
+merge would have to reconcile conflicting descriptions and display names for the
+shared nodes, and would let an addon graft capabilities onto the host's `admin`
+tree — where a role granting `admin` would pick them up without anyone having
+asked for them.

package/knowledge/decisions/internals/an-agent-interrupt-is-not-a-failure.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: An interrupt is not a failure, and the non-streaming path throws rather than returning
+description: 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
+tags: core, ai-agent
+---
+
+# An interrupt is not a failure
+
+Interrupting a run skips the `onError` hooks entirely and never becomes an
+`errorMessage`. Someone asked the agent to stop and it stopped; that is the
+feature working, and running failure handlers over it would report an incident
+that did not happen.
+
+The streaming and non-streaming paths then diverge, because what they can hand
+back differs. A stream has already delivered part of the reply, so it returns
+that fragment. `runAIAgent` has delivered nothing — there is no partial answer to
+return — so it throws a typed error instead. A caller can tell that apart from a
+provider outage, which returning an empty result would not allow.
+
+**What this rules out:** unifying the two paths on "return whatever you have".
+For the non-streaming path that is an empty string, and an empty string is
+indistinguishable from a model that answered with nothing.

package/knowledge/decisions/internals/an-agent-run-owned-by-another-instance-says-so.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: An interrupt for a run owned by another instance says so, rather than returning false
+description: A bare false is indistinguishable from "already finished", which is the one deployment shape the in-process registry cannot cover
+tags: core, ai-agent
+---
+
+# An interrupt for a run owned by another instance says so
+
+`interruptAIAgent` resolves a run through `aiRunState`, then tries to abort it
+via the in-process registry. A run still marked `running` that this process has
+no abort handle for is executing on another instance.
+
+Returning a bare `false` there is indistinguishable from "the run already
+finished" — the ordinary, uninteresting outcome. So the single deployment shape
+the in-process registry does not cover, multi-instance, fails silently: an agent
+that will not stop talking, and nothing in the logs to say why. The call reports
+the condition instead.
+
+**What this rules out:** collapsing the two outcomes into one boolean because
+the caller "only cares whether it stopped". The caller cares a great deal about
+the difference between *stopped* and *cannot be stopped from here*.
+
+The fix for the underlying gap is `signalRunInterrupt`, which fans the interrupt
+out over `eventHub` so every instance tries locally.

package/knowledge/decisions/internals/an-agent-stream-send-must-return-the-inner-sends-promise.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A wrapped agent-stream send must return the inner send's promise
+description: Middleware runs asynchronously, so dropping the returned promise turns every awaited channel.send upstream into a no-op
+tags: core, ai-agent
+---
+
+# A wrapped agent-stream send must return the inner send's promise
+
+`streamAIAgent` wraps the caller's channel so every event passes through the
+stream middleware. That wrapper's `send` returns whatever the inner `send`
+returns, and it must: the middleware chain is asynchronous, so a wrapper that
+calls the inner `send` and returns `undefined` resolves immediately while the
+event is still in flight.
+
+Every `await channel.send(...)` upstream then becomes a no-op that resolves
+before the thing it is waiting for has happened. The one that matters is the
+final flush — a buffering hook such as `voiceOutput` is still synthesizing audio
+when the awaited send resolves, and the `close()` that follows discards it.
+
+**What this rules out:** writing the wrapper as a fire-and-forget `(msg) => {
+inner.send(msg) }`, which reads as equivalent and is not.

package/knowledge/decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A message with nothing to say carries no text part at all
+description: An attachment on its own is a real turn, and providers are entitled to reject an empty text part sitting beside it
+tags: core, ai-agent
+---
+
+# A message with nothing to say carries no text part
+
+When a turn has no text, the text part is omitted rather than included as an
+empty string.
+
+An attachment on its own is a legitimate turn — a spoken one carries audio and
+no text whatsoever — so "no text" is a normal state, not a degenerate one.
+Providers are entitled to reject a message part with empty content, and that
+rejection would land on a caller who never wrote any text to begin with.
+
+**What this rules out:** normalising the text to `''` for a uniform message
+shape. Uniformity here buys nothing and costs a provider error on the one turn
+type that most needs to work.

package/knowledge/decisions/internals/an-empty-transcript-is-not-recorded.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: A transcript is recorded only when something was actually heard
+description: Recording an empty string sends a transcript event saying the user said nothing, which renders as an empty bubble rather than a pending one
+tags: core, ai-agent
+---
+
+# A transcript is recorded only when something was actually heard
+
+A turn can carry audio that reads entirely as non-speech and still have content
+— an image with a silent caption clip — so there is nothing above to throw.
+`voiceInput` records the transcript only when speech was found.
+
+Writing `''` instead would emit a transcript event asserting that the user said
+nothing. A client that distinguishes "not transcribed yet" from "transcribed"
+by whether the key is present would then render that turn as a permanently
+empty bubble rather than a pending one — a worse outcome than showing nothing,
+because it looks settled.
+
+**What this rules out:** defaulting the transcript to an empty string for a
+uniform event shape. Absence and emptiness mean different things to the client,
+and only absence is recoverable.

package/knowledge/decisions/internals/an-unref-d-timer-cannot-be-awaited-under-node-test.md

@@ -0,0 +1,66 @@
+---
+type: decision
+title: An unref'd timer cannot be awaited under node:test
+description: 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
+tags: core, channel, testing
+---
+
+# An unref'd timer cannot be awaited under node:test
+
+`ChannelRPCRegistry.register()` schedules the call's timeout and then unrefs it:
+
+```ts
+// Never hold the process open waiting on a peer that may not answer.
+timer?.unref?.()
+```
+
+That is correct, and should stay. A server shutting down must not be held open
+for up to 30 seconds per in-flight reverse RPC.
+
+It also means the timeout can never fire in a test that awaits it. An unref'd
+timer does not keep the event loop alive, so when the pending call is the only
+thing left the loop drains first, and node:test reports:
+
+```
+Promise resolution is still pending but the event loop has already resolved
+```
+
+The damage is not local. That one test hangs, the runner cancels the **file**,
+and every later test in it is reported `cancelledByParent` — 32 of them in
+`channel-rpc.test.ts`, of which only two were the actual problem. Worse, the
+count moves: under a full-suite run other ref'd handles sometimes keep the loop
+alive long enough for the timer to land, so the file reported `32 cancelled` or
+`1 fail + 31 cancelled` depending on timing. Two of the "failures" were tests
+that pass perfectly well on their own.
+
+Reproducible with no project code at all — a bare `node --test` file where one
+test awaits a ref'd timer and one awaits an unref'd one passes the first and
+cancels the second.
+
+**The fix belongs in the test, not the registry.** Use the test-scoped mock
+clock and drive it by hand:
+
+```ts
+test('times out instead of hanging forever', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const registry = new ChannelRPCRegistry(10)
+  const call = registry.register()
+
+  const rejected = assert.rejects(call.promise, ...)  // attach BEFORE ticking
+  t.mock.timers.tick(10)
+  await rejected
+})
+```
+
+`t.mock.timers` is scoped to the test and resets itself, so tests that want a
+real clock are unaffected. Attach the rejection handler before ticking, or the
+rejection lands unhandled.
+
+**What this rules out:** dropping the `unref` to make the tests pass. That
+trades a test-only annoyance for a production one — every in-flight call would
+then pin the process during shutdown. Also rules out reading a cancelled count
+in this file as a count of broken tests; check which test actually hangs first,
+because the rest are collateral.
+
+Related: [[the-api-report-pins-members-not-just-names]] for the other case where
+a measurement in this repo counted the wrong thing convincingly.

package/knowledge/decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: `getState<T>()` lets the caller name any type, so every implementation asserts
+description: 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
+tags: core, channel
+---
+
+# `getState<T>()` lets the caller name any type, so every implementation asserts
+
+`PikkuChannel` declares its per-connection scratch state as:
+
+```ts
+setState<T>(state: T): Promise<void> | void
+getState<T>(): Promise<T | undefined> | T | undefined
+```
+
+`T` on `getState` appears only in the return position, with no parameter to
+infer it from. So `T` is whatever the caller writes, and the call site gets that
+type back with nothing having checked it. `setState<T>` is separately generic,
+so the two are not even tied to each other — a channel can be written with one
+shape and read as another and neither call complains.
+
+Every implementation therefore holds its state in a concrete variable and
+asserts on the way out. The SSE channel in `http-runner.ts` and the CLI channel
+in `cli-runner.ts` both do exactly that, and the assertion is unavoidable: no
+concrete value is assignable to a type the caller has not yet chosen.
+
+**What this rules out:** deleting the assertions in the implementations — they
+are forced by the signature, not by sloppiness. Fixing this properly means
+making the channel generic in its state type (`PikkuChannel<Opening, Out,
+Remote, State>`) so `setState` and `getState` agree and inference has something
+to work from, which changes the type of every channel in every app. Until that
+is worth doing, the assertions stay and this note explains why they exist.

package/knowledge/decisions/internals/gateway-listener-middleware-runs-without-an-rpc-on-the-wire.md

@@ -0,0 +1,43 @@
+---
+type: decision
+title: Gateway middleware sees wire.rpc on webhook and websocket, but not on listener
+description: The listener transport invokes its handler directly, so middleware runs outside any runPikkuFunc call and the lazily-attached rpc is absent
+tags: core, gateway
+---
+
+# Gateway middleware sees `wire.rpc` on webhook and websocket, but not on listener
+
+`runPikkuFunc` in `packages/core/src/function/function-runner.ts` attaches `rpc`
+to the invocation wire with `Object.defineProperty`, as a lazy getter that
+replaces itself on first read — and restores the previous descriptor in its
+`finally`. `rpc` therefore exists on a wire *only for the duration of a function
+invocation*. That is why `PikkuRawWire` is `Omit<PikkuWire, 'rpc'>`: it is the
+wire as a runner constructs it, before the function runner adds `rpc`.
+
+The three gateway transports reach middleware differently:
+
+- **webhook** and **websocket** register their handlers with `addFunction`, so
+  the handler body already runs inside a `runPikkuFunc` invocation. The `wire`
+  it receives is a full `PikkuWire`, and `config.middleware` runs inside that
+  same invocation — `wire.rpc` is live.
+- **listener** has no such wrapper. `createListenerMessageHandler` is handed
+  straight to `adapter.init()` by the `GatewayService`, builds
+  `const wire: PikkuRawWire = {}` itself, and runs `config.middleware` *before*
+  `invoke()` reaches `runPikkuFunc`. There is no invocation in progress, so
+  `wire.rpc` is `undefined`.
+
+A gateway middleware that calls `wire.rpc.invoke(...)` therefore works on two
+transports and throws on the third, with nothing in the types to say so — the
+call into `runMiddleware` needs an assertion, because `runMiddleware` is typed
+off `CorePikkuMiddleware`, whose wire parameter is `PikkuWire`.
+
+**What this rules out:** treating the assertion at that call as noise to be
+deleted. It is naming a real gap. It also rules out "just widen
+`CorePikkuMiddleware` to accept `PikkuRawWire`" as a free fix — that would make
+`rpc` optional for *every* middleware in the framework, pushing the problem onto
+every consumer to satisfy one transport.
+
+**Still open:** whether the listener path should wrap its handler in a
+`runPikkuFunc` invocation the way the other two do, which would make the three
+transports behave identically and remove the assertion. Nobody has argued
+against it; it simply has not been done.

package/knowledge/decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Hot reload writes into the function map captured at startup, not pikkuState's current one
+description: A dev-server watcher may have swapped in a codegen-scoped map whose writes are discarded on restore, and schemas are deliberately left alone
+tags: core, dev
+---
+
+# Hot reload writes into the function map captured at startup
+
+`reloadGeneratedMeta` registers every function-config export it finds, replacing
+known functions and adding new ones. It writes into the map captured when the
+reloader started, **not** into whatever `pikkuState` currently returns.
+
+A dev-server watcher may have temporarily swapped in a codegen-scoped map while
+regenerating. Writes into that map are discarded when it restores the real one,
+so a reload that used the current map would appear to succeed and silently lose
+every function it registered.
+
+Schemas are deliberately not touched on this path. A function config's
+`input`/`output` hold raw schema objects as the author wrote them, while the
+schema map carries the JSON Schema that codegen produced. They are different
+representations of the same thing, and mixing them crashed reloads.
+
+**What this rules out:** "simplifying" the reloader to call `pikkuState(...)` at
+write time, and extending it to keep `input`/`output` and the schema map in sync
+without first converting between the two representations.

package/knowledge/decisions/internals/index.md

@@ -10,13 +10,23 @@ A rule about how core behaves: what runs where, in what order, and what a
 caller is entitled to assume.
 
 <!-- pikku:knowledge-index -->
+- [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 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 secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
+- [A virtual user decides whether to trust its notes once per turn, by one roll](a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md) — The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
+- [A virtual user run is not a workflow and not a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md) — runVirtualUser writes its record, dispatches the run without awaiting it, and returns the id — because an exploratory run has nothing to replay and the record already carries what a queue would be holding
+- [A 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
+- [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
+- [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
@@ -30,8 +40,16 @@ caller is entitled to assume.
 - [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
+- [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
+- [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 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
 - [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
 - [Channel state is per-socket, session state is per-user](channel-state-is-per-socket-session-state-is-per-user.md) — ChannelStore holds connection-scoped scratch data keyed by channelId, deliberately separate from the pikkuUserId-keyed SessionStore
 - [A channel's user id is persisted only after onConnect middleware has run](channel-user-id-is-persisted-after-onconnect-middleware-runs.md) — The channelId to pikkuUserId mapping is written post-onConnect, because auth middleware is what establishes the session
 - [CLI option names are camelCase in state and kebab-case on the command line](cli-option-names-are-camelcase-in-state-and-kebab-on-the-command-line.md) — Option keys match the function's input field names so they can be plucked by schema, and are converted to kebab only for display and parsing
@@ -49,9 +67,11 @@ caller is entitled to assume.
 - [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
 - [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
 - [Gateway wiring is a meta-wiring over HTTP and channels](gateway-wiring-is-a-meta-wiring-over-http-and-channels.md) — wireGateway writes handler implementations into the HTTP and channel state directly while the inspector compiles the corresponding meta, so runtime registration deliberately writes no meta
 - [Generated src paths in pikku meta are absolute](generated-src-paths-in-pikku-meta-are-absolute.md) — emailsMeta.src is resolved by the CLI at generation time, so reading through the project-relative helpers produces a wrong compound path
+- [Hot reload writes into the function map captured at startup, not pikkuState's current one](hot-reload-writes-into-the-function-map-captured-at-startup.md) — A dev-server watcher may have swapped in a codegen-scoped map whose writes are discarded on restore, and schemas are deliberately left alone
 - [HTTP request bodies are read once and shared between consumers](http-request-bodies-are-read-once-and-shared.md) — The fetch request wrapper memoises the single-use body and builds web Requests lazily, at the cost of holding the whole body in memory
 - [HTTP route groups cascade config in a fixed, per-field order](http-route-groups-cascade-config-in-a-fixed-order.md) — basePath concatenates, tags and middleware merge outward-in, auth is overridden by the innermost group
 - [The HTTP router matches normalized paths but returns the registered path](http-router-matches-normalized-paths-but-returns-registered-ones.md) — Matching normalizes the leading slash while the match result carries the original key, because pikkuState is keyed by the registered string
@@ -64,28 +84,47 @@ caller is entitled to assume.
 - [Istanbul statement counts attach to the start line only](istanbul-statement-counts-attach-to-the-start-line-only.md) — The istanbul coverage reader credits a statement's hits to its first line, so an enclosing multi-line statement cannot mask an unexecuted inner one
 - [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
 - [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
+- [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
 - [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
+- [`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
 - [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 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
+- [The ecosystem entry point carries the adapter surface, so the root can promise stability](the-ecosystem-entry-point-carries-the-adapter-surface.md) — runPikkuFunc and the singleton-service accessors are what a runtime adapter reaches for; their signatures move, and the package root should not promise otherwise
 - [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
 - [The in-memory workflow service is inline-only and single-process](the-in-memory-workflow-service-is-inline-only-and-single-process.md) — InMemoryWorkflowService wires no queues and implements withRunLock/withStepLock as pass-throughs, because inline execution has no second holder to exclude
 - [The KEK salt is scoped to the key version, not the secret](the-kek-salt-is-scoped-to-the-key-version.md) — One stored salt per key version means N secrets cost one derivation, which is the point of envelope encryption
+- [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 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
-- [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
-- [Scenarios, steps and personas live in files named for them](scenarios-live-in-files-named-for-them.md) — pikkuScenario/pikkuScenarioStep must be in *.scenario.ts/*.steps.ts and definePersonas in *.virtual-user.ts, an error because the mixing is only cheap to undo while it is one file
+- [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 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
+- [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
+- [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
+- [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
+- [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
 - [Whether a run is inline is read from the run record](whether-a-run-is-inline-is-read-from-the-run-record.md) — The runContexts map is a read-through cache over WorkflowRun.inline and a lifetime for replay ordinals, never the answer to what a run is
+- [Wiring registries erase the generics their wire* functions capture](wiring-registries-erase-the-generics-their-wire-functions-capture.md) — A registry is typed at unknown so every wiring shares one map; storing a generic config in it needs an assertion, because function parameters are contravariant
 - [Workflow approval expiry is decided from a recorded deadline, not from a timer firing](workflow-approval-expiry-is-decided-from-a-recorded-deadline.md) — The wake-up job is best-effort liveness; losing, duplicating or delaying it cannot change the gate's answer
 - [Core declares the scenario browser surface structurally and never imports a driver](workflow-core-never-imports-a-browser-driver.md) — `@pikku/core` must stay dependency-free for edge runtimes, so playwright augments the interface instead of being imported by it
 - [Workflow DSL meta keeps runtime expressions in their own field, apart from literal values](workflow-dsl-meta-separates-runtime-expressions-from-literals.md) — A string `value` regenerates as a string literal; an `expression` regenerates as code, so the two can never share a field

package/knowledge/decisions/internals/only-exposed-functions-enter-a-virtual-user-catalogue.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: Only functions marked `expose: true` enter a virtual user's catalogue
+description: Absent is not permissive — an unexposed function 404s over rpc, so offering one spends a step to learn nothing about the product
+tags: core, virtual-user
+---
+
+# Only functions marked `expose: true` enter a virtual user's catalogue
+
+`expose: true` is what puts a function on the rpc transport, which is what the
+shipped target is called over. The catalogue therefore treats an absent `expose`
+as excluded rather than as unspecified-and-allowed.
+
+Absent is not permissive here: an unexposed function returns 404, and offering
+it costs the user a step and teaches nothing about the product. On the e2e app,
+34 of 72 functions are in exactly that state — close to half a catalogue that
+cannot be called at all.
+
+**What this rules out:** defaulting the check to "include unless explicitly
+hidden", which reads as the safer default and produces a catalogue that is
+mostly dead ends.