@pikku/core 0.12.79 → 0.12.82

package/knowledge/decisions/internals/scenario-given-and-when-are-sugar-but-then-is-not.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: `given` and `when` are sugar for each other; `then` is not
+description: 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
+tags: core, workflow
+---
+
+# `given` and `when` are sugar for each other; `then` is not
+
+All three run a named `pikkuScenarioStep` as one durable step. `given` and
+`when` differ only in the prose a reporter renders — the step behaves
+identically either way.
+
+`then` is a different operation. The phase is what decides how a step's surface
+bindings are treated: for an action, the bindings are *alternatives* and one is
+chosen; for an assertion, they are *witnesses* and every applicable one runs and
+must agree. So the same step function invoked as `when` and as `then` executes a
+different number of times against a different number of surfaces.
+
+See `resolveScenarioSurfaces` for the resolution itself.
+
+**What this rules out:** collapsing the three into one call with a cosmetic
+label, or letting a caller pass the phase as data. The phase changes execution,
+so it has to be visible at the call site.

package/knowledge/decisions/internals/side-effects-are-an-allowlist-not-a-boolean.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: sideEffects is an allowlist, because core genuinely has some
+description: 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
+tags: core, packaging
+---
+
+# `sideEffects` is an allowlist, not `false`
+
+Without a `sideEffects` field a bundler must assume every module in the package
+does something merely by being imported, so it cannot drop any of them. That is
+the state core shipped in, and it costs every bundled consumer the whole package.
+
+The reflex fix — `"sideEffects": false` — would be untrue. Five modules run code
+at import, 59 top-level calls between them, and every one is `addError(...)`
+registering an error class in the runtime registry:
+
+- `errors/errors.js` (44)
+- `wirings/workflow/pikku-scenario-service.js` (6)
+- `wirings/workflow/workflow-errors.js` (5)
+- `wirings/rpc/rpc-runner.js` (3)
+- `wirings/rpc/remote-addon-auth.js` (1)
+
+A bundler that dropped `errors/errors.js` because nothing imported a binding
+from it would leave `getErrorResponse` unable to map any error to a status. The
+app would build, and every error would come back as a generic 500.
+
+So the field names those five exactly. Everything else can be tree-shaken.
+
+**What this rules out:** flipping this to `false` as a performance change, and
+adding a module-level `addError` (or any other registration) without adding the
+module here. `side-effects-are-declared.test.ts` walks the source for top-level
+calls and fails in both directions — a module with side effects missing from the
+list, and a listed module that no longer has any.

package/knowledge/decisions/internals/speech-synthesis-picks-a-voice-per-sentence-and-warns-once.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: Speech synthesis picks a voice per sentence but announces a limitation once
+description: A bilingual reply should speak the half it can, and repeating the notice for every sentence would bury the reply itself
+tags: core, ai-agent
+---
+
+# Speech synthesis picks a voice per sentence, and warns once per reply
+
+`voiceOutput` checks the script of each sentence separately, but emits any
+"cannot speak this" notice only once for the whole reply.
+
+Per sentence is what makes the voice correct. A reply that answers in English
+and then quotes a Chinese title is two sentences in two scripts, and each is
+synthesized in the voice its own script needs. Checking once for the whole reply
+would pick one voice and mispronounce the other half.
+
+Announcing once is what keeps the reply audible. A bilingual answer should still
+speak the part it can, and repeating the notice for every sentence of a long
+reply buries the answer under its own caveats.
+
+**What this rules out:** moving the script check up to the reply level to save
+work, and moving the notice down to the sentence level for consistency with it.
+The two belong at different granularities on purpose.

package/knowledge/decisions/internals/the-actor-prompt-says-json-because-of-json-object-mode.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: The actor's instructions say the word "json" because a degraded gateway demands it
+description: A gateway that cannot take a JSON schema falls back to OpenAI's json_object mode, which refuses any request whose prompt does not contain the word
+tags: core, actor-flow
+---
+
+# The actor's instructions say the word "json"
+
+Every call the actor makes wants a schema'd object back. A gateway that cannot
+accept a JSON *schema* degrades to OpenAI's `json_object` response mode, and
+that mode refuses the request outright — a hard API error, not a bad answer —
+unless the literal word "json" appears somewhere in the prompt.
+
+The word is therefore in the shared instruction block, once. All three call
+sites (turn, approvals, verdict) build on that block, so one mention covers
+them, and it costs nothing on providers that never needed telling.
+
+**What this rules out:** tidying the instructions by removing a word that reads
+as redundant. It is load-bearing for exactly one provider configuration, and its
+absence fails the request rather than degrading the output — so the failure will
+not look like a prompt problem.

package/knowledge/decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: The agent `done` event goes through the middleware and is awaited
+description: `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
+tags: core, ai-agent
+---
+
+# The agent `done` event goes through the middleware and is awaited
+
+Both the first turn and the post-approval resume send their terminating `done`
+event through the stream middleware rather than straight at the channel, and
+await it.
+
+`done` is the only signal a stream hook receives that the reply is over. The
+hooks that buffer need it to flush: `voiceOutput` holds a trailing fragment that
+never reached a full stop, and waits on audio it has already asked the provider
+to synthesize and already been billed for. Sending `done` raw skips those hooks
+entirely, and the `close()` immediately after throws the buffered work away.
+
+It matters more on the resume path than the first turn. After an approval, most
+of what gets spoken is the agent describing what it just did — so a dropped
+flush silences the larger half of the reply.
+
+**What this rules out:** treating the terminating event as a special case that
+can bypass the chain because "nothing comes after it". Something does: the
+flush.

package/knowledge/decisions/internals/the-api-report-pins-members-not-just-names.md

@@ -0,0 +1,43 @@
+---
+type: decision
+title: The API report pins members, because the export list only pins names
+description: 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
+tags: core, api
+---
+
+# The API report pins members, not just names
+
+`public-surface.json` records `Object.keys(module)` for every entry point. That
+is a real guard — it caught a new `./node-host-resolver` subpath and five
+renames during a rebase — but it only sees *names*.
+
+It cannot see:
+
+- a method added to `MetaService`, which has 32 members
+- a field on `ChannelMeta` becoming required
+- a parameter added to a method on `PikkuWorkflowService`, which has 104
+- any change at all to an `interface`, since types are erased before
+  `Object.keys` can enumerate them
+
+Those are the changes that break a consumer's build, and there are far more of
+them than there are exports — roughly two members for every name. The report's
+own summary counts both, live, so the figure is not repeated here to rot: an
+earlier hand-count in this note was already wrong by 40 members within a day of
+being written.
+
+Demonstrated rather than assumed: adding `probeAddedMember(): void` to
+`MetaService` leaves `public-surface.test.ts` passing 3/0, and fails
+`api-report.test.ts`.
+
+So `api-report.md` is generated from the type checker — every exported symbol
+with its full signature, interfaces and classes rendered as their declarations
+so member changes land in the diff. It is committed, and the test fails when
+the code and the report disagree. Regenerate with `yarn api-report`.
+
+**What this rules out:** treating `public-surface.json` as the API guard. It
+guards the front door; this guards the rooms. Both are needed, and the export
+list is the cheaper of the two to run — which is why it stayed.
+
+Re-exports are resolved through `getAliasedSymbol` before the signature is
+taken. Without that, 624 of the symbols reported as `any`, which would have
+pinned nothing while looking like it did.

package/knowledge/decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md

@@ -0,0 +1,58 @@
+---
+type: decision
+title: The ecosystem entry point carries the adapter surface, so the root can promise stability
+description: runPikkuFunc and the singleton-service accessors are what a runtime adapter reaches for; their signatures move, and the package root should not promise otherwise
+tags: core, api
+---
+
+# The ecosystem entry point carries the adapter surface
+
+`@pikku/core` has two kinds of consumer. An **application** writes functions and
+wires them: `pikkuFunc`, `wireHTTP`, `PikkuWire`, the error catalogue. A
+**runtime adapter** — the express, fastify, uWS, Next, Cloudflare and Lambda
+packages, plus tests — reaches past that to drive the runner itself.
+
+Those two surfaces have measurably different stability. Over the nine months
+since `PikkuWire` was introduced, its app-facing shape took 22 additions and
+**zero removals** — every original field is still there. Over the same period
+`runPikkuFunc` was reshaped: `allServices`/`getAllServices` became
+`singletonServices`/`createWireServices`, the positional arguments became a
+`wireType`/`wireId` pair plus an options object, and `session` became `auth`.
+
+Both were exported from the package root. A compatibility promise made there
+would therefore have been a promise about the weaker of the two.
+
+So the adapter surface moved to `@pikku/core/ecosystem`: `runPikkuFunc`, the
+singleton-service accessors, and the registration calls the code generator emits
+— `addFunction`, `addGlobalMiddleware`, `addMiddleware` — alongside `pikkuState`
+and `httpRouter`, which were already separated for the same reason. The wire
+runners (`runQueueJob`, `runScheduledTask`, `runCLICommand`, `runMCP*`) left the
+root too, but for a different reason: they already lived on their wire subpaths,
+which is where every runtime package imports them from, so the root copies were
+redundant. 108 runtime exports became 95.
+
+**The name took two attempts.** Not `/internal`: the generated bootstrap
+imports from here, so the specifier appears in the user's own `.pikku`
+directory, and telling someone they are touching internals when the code
+generator put it there is both wrong and self-defeating — it could never be
+broken anyway. Not `/runtime` either: that reads as runtime-versus-compile-time,
+i.e. _the real API_, which is the opposite of the intended signal, and
+`packages/runtimes/*` already claims the word while `packages/cli` is the
+largest consumer here at 22 files.
+
+`/ecosystem` says the true thing: you are building a package in the Pikku
+ecosystem — a runtime, a service, an addon, the CLI. `/internal` remains as an
+alias to the same module because the pinned bootstrap CLI still emits it.
+
+Nothing was deleted. What stayed public is what applications actually
+hand-write: `addTagMiddleware` (8 files), `addGlobalPermission`, `fetch` (31),
+`wireAddon`, and the authoring helpers.
+
+**What this rules out:** re-exporting anything from `/internal` at the package
+root for convenience. The split is the whole point — `/internal` may change in
+any release, and the root may not. It also rules out treating `/internal` as
+private: it is a published entry point that runtime authors are expected to use,
+just without the compatibility guarantee.
+
+`public-surface.json` pins both, so moving a symbol across the line is a visible
+diff rather than an accident.

package/knowledge/decisions/internals/the-middleware-resolution-cache-is-deliberately-unbounded.md

@@ -0,0 +1,40 @@
+---
+type: decision
+title: The middleware resolution cache is deliberately unbounded
+description: 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
+tags: core, middleware
+---
+
+# The middleware resolution cache is deliberately unbounded
+
+`middlewareCache` in `packages/core/src/middleware-runner.ts` is a plain
+`Record<PikkuWiringTypes, Record<string, readonly CorePikkuMiddleware[]>>` with
+no size limit and no eviction. That reads like an unbounded-growth bug and is
+not one.
+
+**The keyspace is finite by construction.** The cache is keyed by wire type and
+wire id, and wire ids come from registration, not from traffic — an HTTP route
+pattern, a channel name, a queue name. A million requests to the same route
+produce one entry. Nothing a caller sends creates a key: a channel message key
+is `${channel}:${routingProperty}:${routerValue}`, and `routerValue` is only
+reached after matching `routes[routerValue]`, so an unregistered value never
+gets that far.
+
+**Middleware is dynamic, and the cache is invalidated rather than aged out.**
+`addGlobalMiddleware` and `addTagMiddleware` can run after startup, and dev
+hot-reload rewires wholesale — so correctness comes from `clearMiddlewareCache()`
+at the points where the middleware set actually changes, not from entries
+expiring. An LRU would evict entries that are still current while doing nothing
+about entries that are stale.
+
+**Eviction would also weaken the chain itself.** `combineMiddleware` returns a
+`freezeDedupe`d array, and dedupe is by function identity — a middleware
+reachable through both a tag group and a direct wire registration runs exactly
+once. Callers hold that array. Recomputing it under memory pressure hands out a
+second array for the same wire, which is churn at best and, for anything
+comparing chains by identity, a silent behaviour change.
+
+**What this rules out:** adding a `MIDDLEWARE_CACHE_MAX` with LRU eviction as a
+denial-of-service mitigation. There is no traffic-driven growth to mitigate. If
+a future change ever keys this cache by something a caller controls, that is the
+bug — bound the key, not the cache.

package/knowledge/decisions/internals/the-per-invocation-rpc-view-is-a-class.md

@@ -0,0 +1,40 @@
+---
+type: decision
+title: The per-invocation rpc view is a class, because an object literal with a getter is slow to build
+description: 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
+tags: core, rpc, performance
+---
+
+# The per-invocation rpc view is a class
+
+`getContextRPCService` builds `wire.rpc` once per invocation. It used to return
+an object literal, and that literal declared `get agent()` so the agent facade
+stayed lazy — most requests never touch it, and reading it builds five closures.
+
+The laziness is right. Declaring the accessor *on the literal* was not: a
+literal containing an accessor needs a real property descriptor per instance,
+which takes it off V8's fast object-literal construction path and slows the
+whole object, not just the accessor.
+
+Measured with `benchmarks/bench-profile-granular.ts`, three runs each:
+
+| shape | per call |
+| --- | --- |
+| object literal with `get agent()` | 1.106 / 1.433 / 1.147 µs |
+| class with `agent` on the prototype | 0.523 / 0.461 / 0.525 µs |
+
+Roughly 2.4×, well outside the run-to-run variance, on a path every request
+takes. On the same machine a full `fetchData` measures 12–19µs, so this was on
+the order of a tenth of a request spent constructing one object.
+
+The obvious alternative is worse. Making `agent` an eager property removes the
+accessor but builds those five closures unconditionally, and measured *slower*
+than the original at 1.967µs. A prototype accessor is the only shape that keeps
+the laziness and the fast construction path.
+
+**What this rules out:** "simplifying" `ContextRPCView` back to an object
+literal. It reads as the plainer option and costs double. It also rules out
+trusting a synthetic microbenchmark here — a standalone benchmark of these
+shapes pointed at the eager version, because its stand-in for the agent getter
+was too cheap to represent the real one. The numbers above come from the
+profiler running the real code.

package/knowledge/decisions/internals/the-persona-runtime-is-exported-from-the-persona-entry-point.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: The persona runtime is exported from @pikku/core/persona, never from services
+description: Those values reach the actor-flow and agent runners, which no production server runs — and an unbundled deploy loads whatever the import graph names
+tags: core, services
+---
+
+# The persona runtime lives on `@pikku/core/persona`
+
+`HttpPersona`, `createHttpPersonas`, `readScenarioHttpResponse` and
+`postScenarioJson` are exported from `@pikku/core/persona`, not from
+`@pikku/core/services`. Their *types* are re-exported freely — TypeScript erases
+those and they cost a bundle nothing.
+
+The values are different. They reach `http-personas`, which reaches the
+actor-flow conversation runner, which reaches the agent runner: an entire
+scenario and virtual-user runtime that no production server executes. An
+unbundled Node or Lambda deploy does no tree-shaking — it loads whatever the
+import graph names — so exporting one value from the services barrel pulls all
+of it into every application that imports a service.
+
+This is enforced, not merely intended: `production-barrels-stay-lean.test.ts`
+walks the value-import graph from `services/index.ts` and
+`wirings/workflow/index.ts` and fails if any of those modules is reachable.
+
+**What this rules out:** re-exporting a persona value from the services barrel
+for convenience, and "just one small helper" — the graph is transitive, and one
+value is enough to pull the whole runtime.

package/knowledge/decisions/internals/the-transcript-event-is-sent-ahead-of-the-run.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A voice turn's transcript is sent before the run starts, on the raw channel
+description: 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
+tags: core, ai-agent
+---
+
+# A voice turn's transcript is sent ahead of the run
+
+A voice client sends audio, so it does not know what it said. Until the
+transcript reaches it, its own message renders as a blank bubble.
+
+The event is sent *before* the run rather than alongside it because the answer
+begins streaming within a few hundred milliseconds. Sent concurrently, the
+transcript routinely lands after the first tokens of its own answer — and a
+question that appears beneath its answer reads as a question about something
+else entirely.
+
+It goes on the raw channel rather than through the stream middleware because it
+is not part of the reply: it is what the user said, and the stream hooks are
+built to transform what the agent says.
+
+**What this rules out:** folding the transcript into the run's event stream for
+uniformity. Ordering is the whole point, and the stream is where ordering is
+least under this code's control.

package/knowledge/decisions/internals/the-virtual-user-catalogue-is-the-only-gate-on-what-may-be-called.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: The catalogue is the only gate on what a virtual user may call
+description: Narrowing happens once at derivation, so there is no second check in the run loop that could drift out of step with it
+tags: core, virtual-user
+---
+
+# The catalogue is the only gate on what a virtual user may call
+
+What a virtual user may invoke is decided once, when the catalogue is narrowed
+for its disposition: a read-only disposition is never offered a mutation, and an
+approval-gated endpoint is never offered at all.
+
+The run loop then indexes into that catalogue and calls what it finds. There is
+deliberately no second permission check at call time, because a second check is
+a second thing to keep correct — and the failure mode of the two disagreeing is
+that one of them silently stops mattering.
+
+**What this rules out:** adding a "defence in depth" guard in the run loop. It
+would not be defence in depth; it would be a duplicate of the derivation rules,
+maintained separately, and the one that runs first wins.

package/knowledge/decisions/internals/the-worker-disposition-is-the-one-that-is-not-testing.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: The worker disposition is the only one not testing anything
+description: It is doing the job, so it abandons rarely, runs cool, and is told to stop and say so rather than guess
+tags: core, virtual-user
+---
+
+# The worker disposition is the only one not testing anything
+
+Every other disposition exists to probe the product. The worker exists to *use*
+it, which changes every parameter: it abandons rarely, runs at a low temperature,
+and is instructed to stop and report rather than guess its way past an obstacle.
+
+The failure mode being guarded against is different too. For the probing
+dispositions the risk is a missed bug. For this one it is a wrong action nobody
+asked for — a real mutation performed because the model improvised when it
+should have stopped.
+
+**What this rules out:** tuning this disposition toward the others for
+consistency, in particular raising its temperature or its tolerance for
+guessing. Those settings are what make the others useful and what would make this
+one dangerous.

package/knowledge/decisions/internals/thread-history-records-the-transcript-not-the-audio.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Thread history records what the model was asked, which for a spoken turn is the transcript
+description: The wire carried a base64 audio blob; persisting it writes megabytes of unreadable data and loses the only readable record of the turn
+tags: core, ai-agent
+---
+
+# Thread history records the transcript, not the audio that arrived
+
+What goes into thread history is what the model was actually asked. For a typed
+turn that is what arrived over the wire. For a spoken turn it is not: the wire
+carried a base64 audio blob, and `voiceInput` replaced it with a transcript
+before the model ever saw it.
+
+Persisting the blob would write megabytes of unreadable data into the history
+*and* discard the only readable record of what was said — the worst of both.
+
+Both the streaming and non-streaming paths do this, and both check identity
+rather than assuming: a middleware is free to rewrite the message list into
+something with no relation to this turn, and in that case there is no transcript
+to substitute and the list is persisted as-is.
+
+**What this rules out:** persisting the inbound message verbatim on the grounds
+that it is the ground truth. For voice it is the least useful representation
+available, and the substitution is exactly what makes the history readable.

package/knowledge/decisions/internals/validate-runs-checks-by-precondition.md

@@ -0,0 +1,115 @@
+---
+type: decision
+title: pikku validate runs every applicable check, it does not detect a project kind
+description: 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
+tags: cli, validate, addons
+---
+
+# pikku validate runs every applicable check, it does not detect a project kind
+
+`pikku workspace validate` was named after one of the things a repo can be.
+Adding a second — "is this addon publishable" — invited a second command,
+`pikku addon validate`, and that is where the naming falls apart: the addons
+repo is a workspace *containing* 217 publishable addons. Standing at its root,
+`pikku addon validate` would have to refuse or sweep every package, at which
+point it is doing the workspace thing anyway. The two nouns were never
+alternatives.
+
+So there is one command, and it does not detect a kind and dispatch. Each check
+declares the condition under which it means anything, and runs wherever that
+condition holds:
+
+- `app-project` — a `pikku.config.json` with no `types/application-types.d.ts`
+  beside it. The marker matters: an addon carries a `pikku.config.json` too, and
+  the app-shaped checks would report every app convention it has no reason to
+  follow, starting with a `packages/functions/` it will never have.
+- `addon-package` — a non-private package that ships generated pikku output.
+  Having a `.pikku` directory is not enough on its own: an app's
+  `packages/functions` has one, and it is codegen for that app rather than
+  something anyone installs. The signal is a `files`/`exports` that carries it
+  into the tarball.
+
+Detection-as-dispatch fails on the first repo that is two things at once.
+Detection-as-precondition composes: the addons repo plans 217 addon checks and
+no app check; the online-shop template plans one app check and no addon check;
+a repo that is both plans both.
+
+## Targets come from walking, not from `workspaces`
+
+The field is an array in one repo and `{ packages: [...] }` in the next, spells
+the same layout as `packages/**` or as six explicit globs, and a package that is
+real but unlisted is exactly the kind of thing worth validating. So discovery
+walks the tree for `package.json` files and lets the preconditions decide.
+Over-collecting targets is free; guessing the glob dialect is not.
+
+## A run that checked nothing must not print a tick
+
+The failure mode of auto-detection is that finding nothing looks exactly like
+finding everything and liking it. When no check applies, the renderer says so
+and names what it looked for, rather than reporting success.
+
+## The check the addon case exists for
+
+Every relative import in a shipped generated file must resolve to a file that is
+itself shipped — stated as a property, not as "the build script must copy
+`types/`". The build script is not the only way to get this wrong and will not
+always be a `cp`; the generated files already declare what they need.
+
+That property was false in all 217 published addons. `cp -r .pikku dist/`
+shipped the generated output but not the `types/application-types.d.ts` it
+imports, and `tsc` never emits a hand-written `.d.ts` to `outDir`, so nothing
+put it in `dist`. Consumers got 8 unresolved-module errors plus 6
+`RequiredServices does not satisfy CoreSecretlessSingletonServices` follow-ons
+inside `node_modules`, for merely depending on an addon. The scaffold template
+had been right the whole time — `templates/function-addon` copies `types/` —
+and the published packages had drifted from it with nothing watching.
+
+## The check walks whichever generated directory a package ships
+
+`dist/.pikku` is the target shape (below), but the check cannot assume it: the
+shape is what this work moved addons *to*, and a package that has not moved —
+or was published before it did — still carries `.pikku` at the root, listed in
+`files` and mapped by `exports` as `./.pikku/*`. There it is a public entry
+point rather than build input, and its imports climb one level fewer — to
+`<pkg>/src` and `<pkg>/types` — where the copy under `dist` reaches
+`<pkg>/dist/src` and `<pkg>/dist/types`. Two roots, two ways to fall outside
+the tarball, so the check walks whichever ones are actually shipped rather than
+the one it would prefer to find.
+
+`exports` and `imports` get the same treatment one level up: a target outside
+the published file set is the same defect, and the one the import walk cannot
+see, because nothing inside `dist/.pikku` mentions it. That is how a `#pikku`
+still pointing at `./.pikku/pikku-types.gen.ts` hides.
+
+## An addon's entry points all resolve under dist
+
+Everything an installed package reaches for lives under `dist`; the addon's own
+build resolves `#pikku` through tsconfig `paths`, so nothing in `exports` or
+`imports` has to point into the source tree, and `files` is just `["dist"]`.
+The alternative — shipping `src/` and `types/` at the root so the existing paths
+resolve as written — publishes TypeScript source and a second copy of
+everything `dist` already has.
+
+Checking only `dist` is what let the root `.pikku` stay broken through the first
+round of fixes: in the published `@pikku/addon-assemblyai@0.1.4` tarball, `.pikku`
+ships `.gen.ts` files importing a `../../src/` and `../types/` that the tarball
+does not contain, and the `pikku-bootstrap.gen.js` that consumers import through
+that subpath exists only under `dist`. Everything resolved locally through the
+workspace link and none of it resolved on install.
+
+## Only a package that publishes gets the dist shape
+
+The shape describes a tarball, so it means nothing for a `private` package —
+and applying it there actively breaks: `exports` *is* enforced across a
+workspace link, so repointing a private fixture at `dist` makes every consumer
+demand a directory that only a build produces. The three `verifiers/db-schema`
+and `verifiers/addon-registry` fixtures have no build script at all, so `dist`
+never exists for them; the five `e2e/packages` addons build, but their metadata
+is read straight from the source tree before any build has run. Repointing all
+eight left the db-schema verifier unable to resolve
+`dist/.pikku/db/pikku-db-meta.gen.json` and every e2e addon reporting "no
+function metadata".
+
+`isAddonPackage` already draws this line — it returns false for `private` — so
+the checks and the shape agree: a package the registry never sees is consumed
+from source.

package/knowledge/decisions/internals/virtual-user-step-order-comes-from-insertion-order.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: A scenario's step order for a virtual user is insertion order, not a graph traversal
+description: 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
+tags: core, virtual-user
+---
+
+# Step order comes from insertion order, not a graph traversal
+
+When a scenario becomes catalogue entries, its steps are read in the order the
+nodes appear — which is the order the CLI wrote them, which is the order the
+scenario declares them.
+
+Following `next` edges instead would produce the same ordering in the ordinary
+case, and in the branching case it would force a decision nobody needs: which
+arm of a branch to present to a reader who will never take one. The traversal
+costs work to reproduce a fact that already holds.
+
+**What this rules out:** "correcting" this to a topological walk because a graph
+is present. The graph describes execution; the catalogue describes what the
+scenario *says*, and those are read in declaration order.

package/knowledge/decisions/internals/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: Only an explicit `false` silences a spoken reply
+description: 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
+tags: core, ai-agent
+---
+
+# Only an explicit `false` silences a spoken reply
+
+`voiceOutput` speaks a reply unless the turn is explicitly marked as not having
+arrived by voice. The distinction is between three states, not two:
+
+- `true` — `voiceInput` handled this turn and it carried speech.
+- `false` — `voiceInput` handled this turn and a real user really typed it.
+- absent — no voice input is wired at all, so nothing reported either way.
+
+Treating absent as `false` would silence every caller who wired `voiceOutput`
+without `voiceInput`, changing behaviour that worked before the option existed.
+Treating absent as `true` would speak replies to typists on any stack where the
+flag never gets set.
+
+**What this rules out:** normalising the flag to a boolean at any point between
+`voiceInput` and `voiceOutput` — that collapses absent into one of the other two
+and picks a wrong answer for somebody.

package/knowledge/decisions/internals/wiring-registries-erase-the-generics-their-wire-functions-capture.md

@@ -0,0 +1,35 @@
+---
+type: decision
+title: Wiring registries erase the generics their wire* functions capture
+description: 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
+tags: core
+---
+
+# Wiring registries erase the generics their `wire*` functions capture
+
+Every `wire*` entry point — `wireTrigger`, `wireTriggerSource`, `wireChannel`,
+`wireQueueWorker`, and the rest — is generic in the shape a caller declares, so
+the caller gets a checked `func`. The registry each one writes to is not:
+`pikkuState(null, 'trigger', 'triggers')` is a
+`Map<string, CoreTriggerSource>` where `CoreTriggerSource` fixes input and
+output at `unknown`, because one map has to hold every trigger in the app.
+
+Handing `CoreTriggerSource<TInput, TOutput>` to a slot typed
+`CoreTriggerSource<unknown, unknown>` is not an upcast. `func` takes its input
+as a *parameter*, and parameters are contravariant: a function that accepts
+`TInput` cannot stand in for one that accepts `unknown`, since `unknown` admits
+values `TInput` does not. TypeScript is right to reject it, and no variance
+annotation makes it go away — the registry genuinely holds functions whose input
+types it cannot name.
+
+The runtime is nonetheless sound, because the only thing that ever invokes a
+registered `func` is the function runner, which validates the incoming data
+against that function's own generated schema before the call. The type the
+registry lost is re-established at the call boundary by the schema, not by the
+type system.
+
+**What this rules out:** deleting these assertions as if they were noise — the
+code does not compile without them. It equally rules out `as any` in their
+place: `as any` discards the target type too, so a genuinely wrong config would
+also slip through. Assert to the registry's own element type and let everything
+except the erased generic stay checked.