@pikku/core 0.12.78 → 0.12.80

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,22 @@ 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
 - [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,88 +39,91 @@ 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 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
 - [CLI parse errors are routed by message prefix](cli-parse-errors-are-routed-by-message-prefix.md) — The CLI runners decide between printing help and printing errors by string-matching the prefixes the parser writes, so those message strings are an interface
 - [CLI stdout is reserved for machine-readable output](cli-stdout-is-reserved-for-machine-readable-output.md) — The default renderer emits single-line NDJSON, diagnostics go to stderr, and --json only hijacks rendering for commands that declared a renderer
 - [CLI unknown long options warn instead of failing](cli-unknown-long-options-warn-instead-of-failing.md) — Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
-- [A column's at-rest form is an axis of its own](core-column-form-is-an-axis-of-its-own.md) — How a value is stored is independent of how sensitive it is, so form carries a required nominal brand on writes while classification stays optional on reads
-- [The data-classification brand is an optional property](core-data-classification-brand-is-an-optional-property.md) — Making __classification__ required would break ordinary Kysely operands, so the brand only constrains values flowing out
 - [The function runner restores the wire fields it overwrites](core-function-runner-restores-the-wire-fields-it-overwrites.md) — One wire object is reused across nested calls, so functionId, audit, addonNamespace and rpc are saved and put back in a finally
 - [Hot reload merges generated meta and never replaces it](core-hot-reload-merges-generated-meta-never-replaces-it.md) — Reloading codegen output must preserve runtime-registered meta, which no generated JSON contains
 - [Hot reload owns its module registry instead of re-importing](core-hot-reload-owns-its-module-registry.md) — Dev reload transpiles to CJS and runs modules through vm.compileFunction, because the native ESM loader map cannot be evicted
 - [Middleware order is resolution scope first, then priority](core-middleware-order-is-scope-then-priority.md) — Middleware is collected global to function, then stably sorted by priority, deduped, frozen and cached per wire
-- [Schema defaults are applied on every transport, not just HTTP](core-schema-defaults-apply-on-every-transport.md) — Defaults belong to the schema rather than the call's encoding, so they run unconditionally and are cloned per request
 - [Scopes are an AND gate, separate from permissions](core-scopes-are-an-and-gate-separate-from-permissions.md) — Every declared scope must be held, so adding one can only narrow access — permissions OR, and can only widen it
-- [Pikku state is a global map written only at registration time](core-state-is-a-global-map-written-only-at-registration-time.md) — A symbol-keyed globalThis map holds the wiring registry; nothing per-request may ever be written to it
 - [Email meta is read uncached because codegen rewrites it mid-session](email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md) — getEmailMeta re-reads its file on every call, unlike every other meta accessor, because the file appears and changes during a long-lived session
 - [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
-- [The HTTP runner logs through a trace-scoped logger, functions do not](http-runner-logs-through-a-trace-scoped-logger-functions-do-not.md) — Only runner-internal logging is scoped to the request id; functions keep the singleton logger for compatibility
-- [Set-Cookie headers are appended individually, never joined](http-set-cookie-headers-are-appended-never-joined.md) — Every cookie gets its own header line, because Set-Cookie is the one header comma-joining corrupts
-- [HTTP SSE streams flush headers only after middleware has run](http-sse-streams-flush-headers-only-after-middleware.md) — SSE responses defer the header flush and register with the eventHub, at the cost of a stricter ordering the runner must preserve
 - [HTTP wiring without generated metadata is skipped, not fatal](http-wiring-without-metadata-is-skipped-not-fatal.md) — wireHTTP warns and returns when a route has no metadata, so partial deploy units still boot
 - [In a scenario a 4xx is data, not an exception](in-a-scenario-a-4xx-is-data-not-an-exception.md) — postScenarioJson and invokeRaw report the status instead of throwing, because a refusal is the expected outcome of a permissions scenario
 - [In-memory workflow history aliases the live step object](in-memory-workflow-history-aliases-the-live-step-object.md) — stepHistory pushes the same StepState reference that steps holds, so later mutations to a step are visible in its history entry
 - [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
+- [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](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
 - [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
+- [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
-- [A feature resolves its scenarios by object identity, never by name or shape](workflow-features-resolve-scenarios-by-object-identity.md) — An unregistered scenario comes back explicitly unresolved rather than silently running as something else
 - [Inline and queued workflow graph runs share one transition planner](workflow-graph-inline-and-queued-runs-share-one-planner.md) — A second, weaker inline traversal would lose joins, cycle revisits and step provenance that the queued path has
 - [Workflow graph node notes are non-semantic and excluded from the graph hash](workflow-graph-node-notes-are-excluded-from-the-graph-hash.md) — Documentation on a node must not count as a topology change, or editing a comment redeploys the workflow
-- [An inline workflow run reports its run id the moment it exists, because a failure throws instead of returning](workflow-inline-runs-report-their-run-id-before-they-can-fail.md) — `onRunCreated` is the only moment guaranteed to happen whether the run passes, fails or suspends
 - [`invocationId` is a workflow step's dedupe key; `stepId` is store-specific and must never be used as one](workflow-invocation-id-is-the-dedupe-key-not-step-id.md) — The invocation id is a frozen UUIDv5 of runId + stepName, identical across retries on every backend
-- [A workflow step goes through the queue only if its function opts in, and there is no inline fallback](workflow-queued-step-dispatch-requires-an-explicit-opt-in.md) — `workflowQueued: true` is the whole decision; a missing queue service is a hard error, not a silent downgrade
 - [Workflows get their own queues by default, and queue names are resolved from queue meta](workflow-queues-are-per-workflow-by-default.md) — Per-workflow queues stop one slow step head-of-line-blocking every other workflow; `shared-groups` trades that for one set of pollers
-- [A workflow step name repeated in one run gets an ordinal suffix, and the first reach stays bare](workflow-repeated-step-names-get-an-ordinal-suffix.md) — `name`, `name#1`, `name#2` keys each reach separately without changing the durable key of any existing run
-- [A workflow replay reads its steps once and caches only the run's immutable half](workflow-replay-reads-its-steps-once-and-caches-only-the-immutable-half.md) — The per-replay snapshot collapses O(N^2) step reads to one, but caching mutable run fields would make the replay read a lie
 - [Workflow step retries are owned by the workflow, never by the queue](workflow-retries-are-owned-by-the-workflow-not-the-queue.md) — A step's retry count is resolved once and always passed to the queue as `attempts`, so the queue can never apply its own default
 - [Workflow run capabilities are extensions, not subclasses](workflow-run-capabilities-are-extensions-not-subclasses.md) — Scenario support lives in a separate module behind `setRunExtension` because a bundler drops an unused module but never an unused class member
-- [The workflow run mirror is an observability sink, never a second source of truth](workflow-run-mirror-is-never-a-source-of-truth.md) — Every mirrored write happens after the authoritative write lands, and a mirror failure can never fail the workflow
 - [Workflow run polling starts short and backs off to the caller's ceiling](workflow-run-polling-backs-off-to-the-callers-ceiling.md) — `pollIntervalMs` is a ceiling, not a cadence, and the wait lives in its own method so the schedule can be asserted without the clock
-- [The workflow run timeline is a pure fold over durable history, with the row's status as the authority](workflow-run-timeline-is-a-pure-fold-over-durable-history.md) — No IO in the fold keeps time-travel transport-independent; the terminal event comes from `status`, not from a timestamp every backend populates
 - [Scenario steps default to no retries, and a whole poll is one durable step](workflow-scenario-assertions-never-retry-and-record-one-step.md) — Retrying a failed assertion is wrong for a test primitive; recording the poll as one step means replay returns the outcome, not the loop
-- [Scenario lifecycle hooks are a scenario-only affordance and never mask the failure they follow](workflow-scenario-hooks-are-a-scenario-only-affordance.md) — A durable workflow replays, so a callback that reruns each replay has no honest meaning there
 - [Scenario prose is rendered out of typed calls, not parsed into them](workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md) — The inversion of cucumber — a readable report with no regex step registry to maintain
-- [A quarantined scenario states its reason in code, not in a CI invocation](workflow-scenario-quarantine-reason-lives-in-code.md) — `skip` carries the why next to the scenario it applies to, and naming the scenario explicitly still runs it
 - [Scenario step targets are string literals so the inspector can read them statically](workflow-scenario-step-targets-are-string-literals-for-the-inspector.md) — `step/given/when/then` mirror `do`'s RPC shape because the extractor reads a literal, not an imported symbol
-- [A step's compensation handler runs as a durable step of its own, and never compensates itself](workflow-step-compensation-runs-as-its-own-durable-step.md) — A refund or rollback must not fire twice on replay, so `onError` is recorded as `<step>:onError` with retries disabled
-- [A failed workflow step dispatch is transient infrastructure, not a run failure](workflow-step-dispatch-failure-is-transient-not-a-run-failure.md) — Queue-unreachable errors leave the run running and the step pending so the orchestrator replays; marking the run failed loses it
-- [A workflow step lock is held only to claim the step, never across its execution](workflow-step-lock-is-held-only-to-claim-the-step.md) — Holding the advisory lock — and its pooled connection — across step work exhausted the connection pool and self-deadlocked
-- [A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it](workflow-step-rpc-name-is-provenance-only.md) — It exists so a reader can join a runtime step row back to the declaration that produced it, especially when the durable name was built in a loop
-- [A suspend or approval `reason` is the step's durable identity, not just a message](workflow-suspend-and-approval-reasons-are-durable-step-identities.md) — The reason is namespaced and used raw as the step key, so it must be derived deterministically across replays
-- [A suspended workflow run keeps its in-process context; only terminal runs release it](workflow-suspended-runs-keep-their-in-process-context.md) — `suspended` is absent from the terminal set on purpose, and a context is dropped only when nothing is holding it open
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/internals/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.

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.