@pikku/core 0.12.72 → 0.12.77

package/knowledge/decisions/internals/http-route-groups-cascade-config-in-a-fixed-order.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: HTTP route groups cascade config in a fixed, per-field order
+description: basePath concatenates, tags and middleware merge outward-in, auth is overridden by the innermost group
+tags: http
+---
+
+# HTTP route groups cascade config in a fixed, per-field order
+
+`wireHTTPRoutes` in `packages/core/src/wirings/http/http-routes.ts` walks a
+nested route map and merges group config at each level through
+`mergeGroupConfig`. Each field cascades differently, and the differences are the
+contract callers write against:
+
+- `basePath` concatenates, outer prefix first, so nesting composes URLs.
+- `tags` merge, parent then child; nothing is replaced.
+- `middleware` merges with the parent's entries first, so outer middleware always
+  runs before inner middleware.
+- `auth` is a single value and the innermost declaration wins, which is what lets
+  one public route sit inside an authenticated group.
+
+`registerRoute` then applies the same rules once more between the group config
+and the individual route before calling `wireHTTP`.
+
+**What this rules out:** collapsing `mergeGroupConfig` into an object spread or a
+generic deep-merge. A spread would make the child replace the parent's `tags` and
+`middleware` instead of extending them, and a deep-merge would concatenate `auth`
+or reorder middleware — silently changing which middleware sees a request first.

package/knowledge/decisions/internals/http-router-matches-normalized-paths-but-returns-registered-ones.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: The HTTP router matches normalized paths but returns the registered path
+description: Matching normalizes the leading slash while the match result carries the original key, because pikkuState is keyed by the registered string
+tags: http
+---
+
+# The HTTP router matches normalized paths but returns the registered path
+
+`PathToRegexRouter` in `packages/core/src/wirings/http/routers/path-to-regex.ts`
+normalizes every route and every incoming path to a leading `/` before matching,
+so a route registered as `'todos'` still answers a request for `/todos`. The
+`route` field it stores alongside each matcher and static entry is the
+*un-normalized* original, and that is what `MatchResult.route` returns.
+
+That asymmetry is load-bearing. `getMatchingRoute` in `http-runner.ts` takes the
+returned route and uses it as a key into `pikkuState(null, 'http', 'routes')` and
+into the HTTP meta record — both of which are keyed by exactly the string the
+author passed to `wireHTTP`. Returning the normalized path instead would miss
+those lookups for any route registered without a leading slash.
+
+The same router also compiles channel routes, registered under the `get` method,
+because a WebSocket connection arrives as an HTTP GET upgrade;
+`getMatchingChannelConfig` in `channel-runner.ts` matches through
+`httpRouter.match('get', path)`. Channels and HTTP GET routes therefore share one
+path namespace and can collide with each other.
+
+**What this rules out:** simplifying the compile step to store
+`normalizedRoutePath` in both places, and treating the channel routes compiled
+into the GET table as stray entries to be removed from the HTTP router.

package/knowledge/decisions/internals/http-runner-logs-through-a-trace-scoped-logger-functions-do-not.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: The HTTP runner logs through a trace-scoped logger, functions do not
+description: Only runner-internal logging is scoped to the request id; functions keep the singleton logger for compatibility
+tags: http
+---
+
+# The HTTP runner logs through a trace-scoped logger, functions do not
+
+`fetchData` in `packages/core/src/wirings/http/http-runner.ts` derives
+`scopedLogger` from `singletonServices.logger.scope?.(requestId)` and uses it for
+route-matching and error-handling output only. Functions and middleware continue
+to receive `singletonServices.logger` unscoped, via the services object.
+
+The split is deliberate, not an oversight. `scope` is optional on the `Logger`
+interface, so a runtime supplying a plain logger still works — the runner falls
+back to the singleton. Threading the scoped logger into the services object
+instead would change the logger identity that every existing function and
+middleware sees, which breaks implementations that compare or wrap
+`services.logger`, and would make user code depend on an optional method.
+
+**What this rules out:** "unifying" the two by overwriting `services.logger` with
+`scopedLogger` before the handler runs, and equally the reverse cleanup of
+dropping `scopedLogger` and logging runner internals through the singleton —
+that loses the request-id correlation on 404s and unhandled errors, which is the
+only place the trace id is attached automatically.

package/knowledge/decisions/internals/http-set-cookie-headers-are-appended-never-joined.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: Set-Cookie headers are appended individually, never joined
+description: Every cookie gets its own header line, because Set-Cookie is the one header comma-joining corrupts
+tags: http
+---
+
+# Set-Cookie headers are appended individually, never joined
+
+`PikkuFetchHTTPResponse.toResponse` in
+`packages/core/src/wirings/http/pikku-fetch-http-response.ts` serializes each
+cookie separately and calls `headers.append('Set-Cookie', cookie)` per value
+rather than setting one joined string. `collectSetCookieHeaders` in
+`web-request.ts` mirrors this when copying a web `Response` back onto a
+`PikkuHTTPResponse`: it prefers `Headers.getSetCookie()` where the runtime
+provides it, falls back to scanning for the header by name, de-duplicates, and
+passes the values through as an array.
+
+RFC 6265 makes `Set-Cookie` the exception to the "fold repeated headers with
+commas" rule — cookie attributes such as `Expires` contain commas themselves, so
+a joined header is parsed as a single malformed cookie and every cookie after the
+first is lost. `Headers.set()` with a joined value, or a generic header-copy loop
+that treats `set-cookie` like any other header, produces exactly that.
+
+**What this rules out:** replacing the append loop with a single
+`set('Set-Cookie', cookies.join(', '))`, and dropping the special-cased
+`set-cookie` branch in `applyWebResponse` in favour of the generic
+`headers.forEach` copy.

package/knowledge/decisions/internals/http-sse-streams-flush-headers-only-after-middleware.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: HTTP SSE streams flush headers only after middleware has run
+description: SSE responses defer the header flush and register with the eventHub, at the cost of a stricter ordering the runner must preserve
+tags: http
+---
+
+# HTTP SSE streams flush headers only after middleware has run
+
+`executeRoute` in `packages/core/src/wirings/http/http-runner.ts` puts the
+response into `'stream'` mode and sets the SSE content-type up front, but calls
+`http.response.flushHeaders()` only after `runPikkuFunc` returns. Middleware runs
+inside `runPikkuFunc`, and middleware is where CORS, auth and cookie headers are
+set — flushing earlier would send the response head before those headers exist,
+and they can never be added afterwards. `PikkuFetchHTTPResponse.createStream` in
+`pikku-fetch-http-response.ts` enqueues a bare `:\n\n` comment frame on start for
+the same reason on the client side: proxies and browsers do not surface the
+stream until some body bytes arrive.
+
+The SSE channel is also registered with `singletonServices.eventHub` when the
+service exposes `onChannelOpened`, wrapped in a minimal object that satisfies
+`PikkuChannelHandler`. That is what makes `eventHub.publish()` reach SSE
+subscribers and not just WebSocket ones, and `channel.close` is rewrapped so the
+eventHub is told about the close. On the delivery side,
+`LocalEventHubService.publish` treats a throwing `channel.send` as a disconnect
+and calls `onChannelClosed` — an SSE `ReadableStream` controller that the browser
+has already abandoned throws rather than reporting closure.
+
+**What this rules out:** hoisting `flushHeaders()` next to the other SSE header
+calls; dropping the `:\n\n` priming frame as dead output; treating the eventHub
+registration as WebSocket-only bookkeeping; and letting `publish` propagate a
+send error instead of unregistering the channel.

package/knowledge/decisions/internals/http-wiring-without-metadata-is-skipped-not-fatal.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: HTTP wiring without generated metadata is skipped, not fatal
+description: wireHTTP warns and returns when a route has no metadata, so partial deploy units still boot
+tags: http
+---
+
+# HTTP wiring without generated metadata is skipped, not fatal
+
+`wireHTTP` in `packages/core/src/wirings/http/http-runner.ts` looks the route up in
+`pikkuState(null, 'http', 'meta')` and, when nothing is found, logs a warning and
+returns instead of throwing. `wireChannel` in
+`packages/core/src/wirings/channel/channel-runner.ts` does the same for channels.
+
+A deploy unit is built from filtered metadata: only the functions belonging to
+that unit get meta entries. A wiring file, however, is imported whole. When two
+wirings share one file, importing it for the sake of the first wiring also
+executes the second — whose function is not in this unit and therefore has no
+metadata. Throwing there would make an otherwise valid deploy unit fail to boot.
+The warning names the route and tells the author to split the wirings into
+separate files, which both fixes the warning and improves tree-shaking.
+
+**What this rules out:** turning the missing-metadata branch into a thrown error
+or an assertion "because a route should always have metadata". It should not, in
+filtered builds. It also rules out silently dropping the warning — the warning is
+the only signal an author gets that a route they wired is not actually served.

package/knowledge/decisions/internals/in-a-scenario-a-4xx-is-data-not-an-exception.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: In a scenario a 4xx is data, not an exception
+description: postScenarioJson and invokeRaw report the status instead of throwing, because a refusal is the expected outcome of a permissions scenario
+tags: services
+---
+
+# In a scenario a 4xx is data, not an exception
+
+`postScenarioJson` (`packages/core/src/services/scenario-actors-service.ts`) and
+`ScenarioActor.invokeRaw` return a `ScenarioHttpResponse` for every status. Only
+`invoke` throws, and it throws with a truncated body — which is why a scenario
+asserting on a refusal must use `invokeRaw`.
+
+A permissions or scopes scenario *expects* the 403. The status is the assertion,
+and the body usually names the scope that was missing, so both have to survive as
+data rather than being reduced to a thrown `Error`. These helpers also exist
+because every scenario reaching past an actor was hand-writing the same
+`content-type`, `JSON.stringify` and drain — and the copies had drifted: several
+returned `res.json()`, which discards the status entirely and throws outright on
+an empty body or an HTML error page.
+
+**What this rules out:** adding a `throwOnError` default to these helpers,
+routing scenario assertions through `invoke`, and reintroducing per-scenario
+fetch wrappers that return a parsed body without the status.

package/knowledge/decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: In-memory workflow history aliases the live step object
+description: stepHistory pushes the same StepState reference that steps holds, so later mutations to a step are visible in its history entry
+tags: services
+---
+
+# In-memory workflow history aliases the live step object
+
+`InMemoryWorkflowService` (`packages/core/src/services/in-memory-workflow-service.ts`)
+stores each step twice: in `steps`, keyed `${runId}:${stepName}`, and appended to
+`stepHistory` for the run. Both hold the *same object*. `createStepImpl` and
+`createRetryAttemptImpl` push the reference they just put into `steps`, not a
+copy.
+
+That aliasing is the mechanism, not an accident. The service mutates a step in
+place as it progresses — status, `runningAt`, `completedAt`, output, error — and
+every one of those updates has to appear in the run's history without the history
+being rewritten. Break the aliasing and history freezes at the moment each step
+was created: every entry reads `pending`, and `getRunHistory` reports a run in
+which nothing ever finished.
+
+**What this rules out:** pushing `{ ...step }` into `stepHistory`, or introducing
+any clone/freeze/structuredClone on the way in — the obvious "don't share mutable
+state" cleanup. If history ever needs to be immutable, the step updates have to
+start writing to both structures explicitly, in the same change.

package/knowledge/decisions/internals/index.md

@@ -0,0 +1,117 @@
+---
+type: overview
+title: Internals
+description: How core behaves — runtime constraints, execution semantics, and the shapes the API commits to
+---
+
+# Internals
+
+A rule about how core behaves: what runs where, in what order, and what a
+caller is entitled to assume.
+
+<!-- pikku:knowledge-index -->
+- [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
+- [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
+- [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
+- [Delegate mode hides the parent's later text, supervise mode hides the sub-agent's](ai-agent-delegate-and-supervise-hide-different-text.md) — Exactly one voice reaches the client per agent-mode; approvals and tool events always flow through either way
+- [Nulls are stripped from approved tool arguments before execution](ai-agent-llm-tool-arguments-have-nulls-stripped.md) — LLMs emit null for optional fields where the schema layer expects undefined, so a resumed tool call is cleaned recursively first
+- [Model resolution stays a single seam even though it is currently a passthrough](ai-agent-model-config-stays-a-single-resolution-seam.md) — resolveModelConfig looks removable but is the one merge point for per-request model overrides
+- [An aiMiddleware onError hook cannot change how a run fails](ai-agent-onerror-hooks-cannot-change-the-failure.md) — Hook throws are swallowed so observability code can never convert, mask, or replace the original error
+- [AI runner methods must be called on the runner, never as detached references](ai-agent-runner-methods-must-keep-their-receiver.md) — Implementations use this internally, so grabbing transcribe or generateSpeech as a bare function loses the receiver and throws at runtime
+- [Persisting an agent stream from send is best-effort and must never reject](ai-agent-stream-persistence-is-best-effort.md) — The persisting channel flushes fire-and-forget because send is synchronous; a storage failure degrades the transcript instead of killing the process
+- [A delegated sub-agent inherits the parent run's context block](ai-agent-sub-agents-inherit-the-parent-context-block.md) — The sub-agent tool schema carries only message and session, so the parent's identifier block is forwarded rather than re-typed by the model
+- [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
+- [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
+- [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 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
+- [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
+- [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
+- [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
+- [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
+- [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 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 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
+- [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
+- [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
+- [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/istanbul-statement-counts-attach-to-the-start-line-only.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Istanbul statement counts attach to the start line only
+description: 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
+tags: services
+---
+
+# Istanbul statement counts attach to the start line only
+
+`IstanbulCoverageService` (`packages/core/src/services/istanbul-coverage-service.ts`)
+reads instrumented counters off the `__coverage__` global and, when turning
+statement maps into line hits, credits each statement's count to its *start* line
+and no other line it spans.
+
+This is istanbul's own semantics, and the reason matters: statements nest. An
+`if` block spanning ten lines has a non-zero count as soon as the `if` is
+reached, and a `throw` on line six inside it that never ran has a count of zero.
+Spreading the enclosing statement's count across its whole range would paint that
+`throw` as covered — the uncovered branch disappears into the covered one, which
+is precisely the case coverage exists to surface.
+
+**What this rules out:** filling in `start.line`..`end.line` from a single
+statement's count, or merging a nested statement's zero into its parent's total.
+Any change here has to keep the innermost statement's own count as the authority
+for its line.

package/knowledge/decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Local trigger and gateway services assume a single process
+description: InMemoryTriggerService and LocalGatewayService start every listener unconditionally with no distributed claiming, so a second instance duplicates every event
+tags: services
+---
+
+# Local trigger and gateway services assume a single process
+
+`InMemoryTriggerService` (`packages/core/src/services/in-memory-trigger-service.ts`)
+and `LocalGatewayService` (`packages/core/src/services/local-gateway-service.ts`)
+start every registered trigger source and every listener gateway
+unconditionally. There is no claiming, no lease, no leader election: whoever
+boots, listens.
+
+That is correct for exactly one owner. Run two instances and both subscribe to
+the same source, so every external event fires its RPC target twice — and because
+triggers and listener gateways are typically wired to side-effecting functions,
+the duplicate is not idempotent. A distributed deployment needs a different
+`TriggerService` / `GatewayService` implementation that coordinates first; the
+interfaces exist so that implementation can be dropped in.
+
+**What this rules out:** scaling a `pikku serve` or container running these
+services beyond one replica, and adding coordination inside these two classes.
+They are the single-process implementations by definition — coordination belongs
+in a sibling implementation, not behind a flag here.

package/knowledge/decisions/internals/node-only-builtins-are-imported-dynamically.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: Node-only builtins are imported dynamically
+description: V8CoverageService imports node:inspector inside start() so the module stays loadable on runtimes that have no such builtin
+tags: services
+---
+
+# Node-only builtins are imported dynamically
+
+`V8CoverageService` (`packages/core/src/services/v8-coverage-service.ts`) reaches
+`node:inspector` through `await import('node:inspector')` inside `doStart()`,
+not through a top-level import.
+
+`@pikku/core` is loaded whole on runtimes that have no Node builtins —
+Cloudflare Workers most notably. A static `import 'node:inspector'` is resolved
+when the module graph loads, so it would fail the entire bundle at startup on
+those runtimes, for a service that would never have been started there anyway.
+Deferring the import moves the failure to the point of use, where it is both
+correct and avoidable.
+
+**What this rules out:** hoisting the import to the top of the file because the
+dynamic form "looks unnecessary", and the same move in any other core module that
+touches a Node-only builtin. The rule is general: if core can be loaded on
+Workers, a Node builtin is imported at the call site.

package/knowledge/decisions/internals/one-project-shape-check-two-validators.md

@@ -0,0 +1,53 @@
+---
+type: decision
+title: One project-shape check, called by both validators
+description: workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and fabric validate is that plus the deploy-shaped checks
+tags: cli, validate, fabric
+---
+
+# One project-shape check, called by both validators
+
+`pikku workspace validate` and `pikku fabric validate` read like one command
+with a flag. They were two implementations — 495 lines and 2026 — that walked
+the same project and emitted sixteen identical findings. `functions-dir-missing`
+existed character for character in both files. All sixteen already agreed on
+severity, which is the only reason the duplication was invisible.
+
+What the duplication cost was not the lines. It was that each validator carried
+checks the other lacked for no reason anyone could name, and nobody noticed
+because nobody read them side by side:
+
+- fabric validate never checked that `packages/functions` declares zod v4, or
+  that it has a `package.json` at all — while it did check that six other
+  dependencies are present.
+- workspace validate never checked the four scaffold flags beyond `console`,
+  though the console it requires is useless without `rpc`.
+- fabric validate swallowed a JSON parse error and reported
+  `pikku-config-missing` for a file sitting right there.
+
+Two of workspace validate's own checks were not merely absent from fabric — they
+had never run anywhere:
+
+- the auth checks were gated on a middleware instance with `definitionId ===
+  'betterAuthSession'`, but the CLI wires `betterAuthStatelessSession` whenever
+  `session.cookieCache` is on, which is the configuration Fabric asks for. So
+  they skipped precisely the apps most likely to have auth.
+- they looked for migrations in `packages/functions/db/`, and for tables named
+  `app_user` and `auth_verification_token`. `pikku db migrate` reads migrations
+  from `<root>/db/<engine>/`, and those two table names appear nowhere else in
+  pikku or in any template. Had the gate ever opened, the check would have been
+  wrong for every project it fired on.
+
+`shared-checks.ts` is now the half that is true of any pikku project regardless
+of where it deploys. Workspace validate is exactly that module; fabric validate
+is that module plus the deploy-shaped checks — themes, frontends, the
+Cloudflare adapter, the `.gitignore` contract, the frontend type-check.
+
+Fabric's fix hints won where the two differed: they are multi-line and show the
+config block to paste, and there was no reason workspace users were getting the
+one-line version.
+
+**What this rules out:** adding a check to one validator and not the other;
+`pikku fabric validate` reporting a corrupt config as a missing one; asserting
+auth table names no scaffold generates; and reading migrations from anywhere
+other than where `pikku db migrate` reads them.

package/knowledge/decisions/internals/queue-group-concurrency-keeps-one-shared-queue-fair.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: Queue group concurrency keeps one shared queue fair
+description: 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
+tags: queue
+---
+
+# Queue group concurrency keeps one shared queue fair
+
+`PikkuWorkerConfig.groupConcurrency` in
+`packages/core/src/wirings/queue/queue.types.ts` caps how many jobs of any one
+group (`JobOptions.group`, a `JobGroup` with an `id` and optional `tier`) may run
+at once. Jobs sharing a group `id` count against the same limit;
+`GroupConcurrencyConfig.tiers` varies the limit per tier so a slow group can be
+allowed more or fewer slots than the default.
+
+The alternative considered was one queue per producer, which gives isolation for
+free. It was rejected because pull-based backends poll per queue, so splitting
+multiplies polling cost linearly with the number of producers. A single shared
+queue plus a per-group cap gets the same "no one producer starves the others"
+property at constant polling cost. The cap must not exceed
+`PikkuWorkerConfig.batchSize`, which is the worker's total concurrency — a group
+limit above it can never bind and silently reverts the queue to unfair.
+
+**What this rules out:** dropping `group`/`groupConcurrency` in favour of
+per-producer queues, and raising a group limit to or above `batchSize` as a way
+to "disable" fairness — that reintroduces head-of-line blocking by a single
+producer rather than turning the feature off.

package/knowledge/decisions/internals/queue-jobs-always-carry-an-explicit-attempts-count.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: Queue jobs always carry an explicit attempts count
+description: resolveJobOptions always passes attempts so a queue backend can never apply its own retry default, and an explicit retries of 0 is honoured
+tags: services
+---
+
+# Queue jobs always carry an explicit attempts count
+
+`QueueWebhookService.resolveJobOptions`
+(`packages/core/src/services/queue-webhook-service.ts`) resolves retries as
+per-call `retries` → `config.webhook.retries` → `DEFAULT_WEBHOOK_RETRIES`, then
+*always* puts `attempts: retries + 1` on the job options. It mirrors the workflow
+service's policy resolution. Backoff is exponential unless a concrete
+`retryDelay` selects a fixed one.
+
+Two rules are load-bearing. `attempts` is passed unconditionally so the queue
+backend never gets to apply its own default — pg-boss, BullMQ and SQS disagree
+about what that default is, and a webhook silently retried a different number of
+times per backend is not a behaviour anyone can reason about. And an explicitly
+set `retries: 0` is honoured rather than treated as unset, because "deliver this
+exactly once, do not retry" is a real caller intent that `??` chains lose.
+
+**What this rules out:** omitting `attempts` when it equals the default, folding
+`retries` into a truthiness check (`retries || configRetries`, which turns 0 back
+into the default), and relying on a queue adapter's retry configuration in place
+of passing the value.

package/knowledge/decisions/internals/remote-addons-dispatch-over-http-instead-of-local-meta.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: Remote addons dispatch over HTTP instead of through local function meta
+description: wireRemoteAddon ships the addon as a devDependency and posts to the host, so there is deliberately no local handler to resolve
+tags: rpc
+---
+
+# Remote addons dispatch over HTTP instead of through local function meta
+
+`wireAddon` bundles an addon's functions in-process: the package is a production
+dependency and its handlers run inside the consumer. `wireRemoteAddon`
+(`packages/core/src/wirings/rpc/wire-remote-addon.ts`) does the opposite — the
+package is installed as a **devDependency**, contributing types only, and the
+handlers run on the host at `serverUrl`. `pikku verify` enforces the
+devDependency placement.
+
+`ContextAwareRPCService.invokeAddonFunction` in `rpc-runner.ts` therefore checks
+`resolved.addonConfig?.remote` *before* it looks for local function meta, and
+routes to `invokeRemoteAddonFunction`. That method POSTs the addon's own function
+name — the bare name, not the namespaced `ns:fn` form, optionally remapped by
+`remoteName` — to `${serverUrl}/remote/rpc/:rpcName`, authenticating as a client
+with the token bound in `wireRemoteAddon({ auth })`. There is no local meta entry
+to fall back on, which is why a missing `serverUrl` raises
+`RemoteAddonConfigError` rather than degrading to a local lookup, and a non-2xx
+response raises `RemoteAddonRequestError` with a truncated body for context.
+
+**What this rules out:** moving the `remote` check after the local meta lookup
+(the lookup will always miss and mask the real error), sending the namespaced
+name over the wire, and promoting the addon to a production dependency so its
+handlers can be "used directly" — that defeats the point of the remote wiring and
+puts the host's code in the consumer's bundle.