@pikku/core 0.12.72 → 0.12.74

package/knowledge/decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md

@@ -0,0 +1,44 @@
+---
+type: decision
+title: The function runner restores the wire fields it overwrites
+description: One wire object is reused across nested calls, so functionId, audit, addonNamespace and rpc are saved and put back in a finally
+tags: core
+---
+
+# The function runner restores the wire fields it overwrites
+
+`runPikkuFunc` in `packages/core/src/function/function-runner.ts` does not build a
+fresh wire per call. Nested invocations — an RPC from inside a function, an addon
+sibling call, a workflow step — reuse the *same* wire object the outer transport
+created. So before it runs, the runner captures `functionId`, `audit`,
+`addonNamespace` and the property descriptor for `rpc`, overwrites them for the
+duration of this function, and restores or `delete`s them in a `finally`. Both
+the middleware path and the direct path carry that restore block. Without it, an
+inner call would leave its identity on the wire and every subsequent outer step
+would be attributed to the wrong function.
+
+The same reuse is why the audit binding is re-gated inside `executeFunction`
+rather than trusted from `createWireServices`. The audit *gate* is per-function
+but the `auditLog` wire service is created per-transport-invocation. A nested or
+exposed-RPC call would otherwise inherit an `auditLog` built while the outer
+wire's audit config was unset (the generated `rpcCaller` declares none), and
+every write from the audited inner function would be silently dropped. The runner
+compares config identity (`services.auditLog?.config !== resolvedAuditConfig`)
+and binds a fresh invocation audit when they differ, then closes it in the
+`finally` before wire services are closed.
+
+Authorization order in `executeFunction` is also deliberate: session resolution,
+then the auth/readonly checks, then `verifyScopes` — all of which depend only on
+the session — and only then `await data()`, schema defaults, coercion, validation
+and `runPermissions`. A request denied by scope never pays to parse or validate
+its body. `rpc` is installed as a lazily-evaluating accessor that replaces itself
+with the resolved value on first read, capturing the *caller's* package name in
+the closure so an addon's RPCs resolve in its own namespace.
+
+**What this rules out:** dropping the save/restore blocks as duplicated
+boilerplate, or "hoisting" them into a single wrapper that only runs on the
+outermost call. It rules out moving `verifyScopes` down next to `runPermissions`
+for tidiness — that reintroduces body parsing for denied requests. And it rules
+out taking `services.auditLog` at face value when the function declares audit;
+the identity check is the only thing distinguishing an inherited disabled
+instance from one built for this invocation.

package/knowledge/decisions/internals/core-hot-reload-merges-generated-meta-never-replaces-it.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: Hot reload merges generated meta and never replaces it
+description: Reloading codegen output must preserve runtime-registered meta, which no generated JSON contains
+tags: core
+---
+
+# Hot reload merges generated meta and never replaces it
+
+`reloadGeneratedMeta` in `packages/core/src/dev/reload-meta.ts` re-reads the
+codegen output (`.pikku/**/​*.gen.json`) straight into `pikkuState` after each dev
+codegen pass. It reads the JSON directly rather than re-importing the generated
+`*-meta.gen.ts` wrappers because the ESM cache pins both the wrapper and its JSON
+import, so a re-import returns the stale value.
+
+For `function.meta` and `queue.meta` it merges over the existing map instead of
+assigning. Framework internals are registered at service-init time and appear in
+no generated file: `pikkuWorkflowOrchestrator` and the per-workflow
+`wf-orchestrator-*` / `wf-step-*` queue workers are added by
+`pikku-workflow-service.ts`. A wholesale replace drops them, and the next
+workflow job fails with `Function meta not found: pikkuWorkflowOrchestrator`.
+`dev/reload-meta.test.ts` pins this. Meta maps that only codegen ever writes
+(`http`, `rpc`, `agent`) are assigned outright.
+
+Two limits are inherent rather than incidental. Routes registered by a *new*
+`wireHTTP` file are not picked up here — those modules were never imported — which
+is why `hot-reload.ts` keeps a `postCodegenQueue` and exposes `reimportPending()`
+for the dev server to drain after codegen, so registrations that were skipped for
+missing meta run again against fresh meta. And `reconcileAddonRegistry` has to
+prune `addons.packages` explicitly, because hot reload only ever re-imports files
+that still exist, so a deleted `*.addon.ts` would otherwise leave its `wireAddon`
+entry stranded until a restart.
+
+**What this rules out:** replacing the two merges with plain
+`pikkuState(null, 'function', 'meta', functionsMeta)` assignments on the grounds
+that codegen output is authoritative — it is authoritative only for what codegen
+emits. It also rules out folding `reimportPending()` back into the debounced
+reload (the whole point is that it runs *after* codegen), and dropping
+`reconcileAddonRegistry` as dead code.

package/knowledge/decisions/internals/core-hot-reload-owns-its-module-registry.md

@@ -0,0 +1,42 @@
+---
+type: decision
+title: Hot reload owns its module registry instead of re-importing
+description: Dev reload transpiles to CJS and runs modules through vm.compileFunction, because the native ESM loader map cannot be evicted
+tags: core
+---
+
+# Hot reload owns its module registry instead of re-importing
+
+`packages/core/src/dev/module-runner.ts` re-runs a changed user file by
+transpiling it to CJS with esbuild, executing it via `vm.compileFunction`, and
+storing the resulting exports under a **stable absolute-path key**. A reload
+overwrites that one registry slot, so the previous module becomes unreachable and
+is collected. `packages/core/src/dev/hot-reload.ts` drives it from the file
+watcher.
+
+The obvious alternative — re-`import()`ing the file under a fresh URL (a `data:`
+URL on Node, a uniquely-named temp sibling on Bun) — is unbounded. The native ESM
+loader keeps a `Map<url, moduleRecord>` for the life of the realm with no
+eviction API, so every reload permanently leaks a module record; measured at
+roughly 0.3–1.3 MB per edit, which is ~84 MB on Node and ~222 MB on Bun over 200
+edits, and eventually OOMs a long editing session. `dev/module-runner.test.ts`
+asserts both the single-slot guarantee and bounded heap growth.
+
+Two details keep the mechanism honest. `import`s inside the user file are
+delegated to `createRequire`, whose resolution matches the native loader *and*
+returns the same live singletons (Node and Bun share the require/import cache) —
+that is what lets a reloaded file's top-level `wireHTTP` side effects mutate the
+services the running server is already using. And esbuild is invoked with no
+sourcemap: an inline sourcemap embeds a base64 copy of the source that the engine
+retains per compile, reintroducing exactly the linear growth this runner exists
+to remove. The known limitation is that a file using top-level `await` cannot be
+emitted as CJS; `run` returns `null` and the caller keeps the previously loaded
+code.
+
+**What this rules out:** "simplifying" the reloader back to `await
+import(url + '?t=' + Date.now())` or any fresh-URL variant, and turning
+sourcemaps back on for nicer stack traces (`filename` already anchors traces to
+the user file). It also rules out swapping `createRequire` for a fresh `import()`
+inside the compiled module — resolution would produce a *distinct* copy of every
+dependency, and the reloaded file would then wire itself into services nobody is
+serving from.

package/knowledge/decisions/internals/core-middleware-order-is-scope-then-priority.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: Middleware order is resolution scope first, then priority
+description: Middleware is collected global to function, then stably sorted by priority, deduped, frozen and cached per wire
+tags: core
+---
+
+# Middleware order is resolution scope first, then priority
+
+`combineMiddleware` in `packages/core/src/middleware-runner.ts` builds the chain
+for a wire by appending, in this order: global middleware
+(`addGlobalMiddleware`), then wire-inherited entries (the HTTP route group, then
+tag groups resolved parent-first by `getTagGroups`, then named wire middleware),
+then inline wire middleware, then function-inherited tag groups, then inline
+function middleware. That collected array is then stably sorted by
+`MiddlewarePriority` — `highest` (0) runs first and outermost, `lowest` (4) runs
+last and innermost, closest to the function, with `medium` the default — and
+finally passed through `freezeDedupe` and cached in `middlewareCache` keyed by
+wire type and wire id.
+
+Two properties fall out of that and both are load-bearing. Because the sort is
+stable, priority is a coarse band and registration order breaks ties *within* a
+band, so declaration order still means something. And because the result is
+deduped by function identity, a middleware reachable through both a tag group and
+a direct wire registration runs exactly once — a fact several tests assert
+directly. `runMiddleware` re-sorts only when `isSortedByPriority` says the input
+is not already ordered, which is why the cached array must never be handed back
+unsorted.
+
+The cache is why `clearMiddlewareCache()` exists and why dev hot-reload calls it
+alongside `clearPermissionsCache()`, `clearChannelMiddlewareCache()` and
+`httpRouter.reset()` on every reload.
+
+**What this rules out:** switching `sortByPriority` to a comparator that is not
+stable, or to a sort that runs before the scope-ordered collection — either one
+silently reorders same-priority middleware and breaks the "declaration order
+wins within a band" contract. It also rules out dropping `freezeDedupe` as
+redundant (a tag-plus-wire registration would then run twice), and rules out
+caching by wire id alone without clearing on reload.

package/knowledge/decisions/internals/core-schema-defaults-apply-on-every-transport.md

@@ -0,0 +1,43 @@
+---
+type: decision
+title: Schema defaults are applied on every transport, not just HTTP
+description: Defaults belong to the schema rather than the call's encoding, so they run unconditionally and are cloned per request
+tags: core
+---
+
+# Schema defaults are applied on every transport, not just HTTP
+
+`applyDefaultsFromSchema` in `packages/core/src/schema.ts` fills in absent
+top-level properties from their JSON Schema `default`, and the function runner
+calls it **unconditionally** — before coercion, before validation, on every wire
+type.
+
+It exists because a `default` reaches the generated JSON Schema and keeps the
+property out of `required`, so omitting it validates. But JSON Schema validators
+are pure by specification, and none of the ones Pikku ships with
+(`@cfworker/json-schema`, and Ajv unless `useDefaults` is set) annotate the
+instance. The function therefore received `undefined` for a property its
+generated TypeScript type declares as present — the worst shape a mismatch can
+take: validation permits the omission, the type promises the value, the body
+reads `undefined`.
+
+It is deliberately *not* gated on the `coerceDataFromSchema` flag that guards
+`coerceTopLevelDataFromSchema`. That flag is about decoding transport-encoded
+values — a query string's `"1,2"` into an array, an ISO string into a `Date` —
+and is set only by transports that need it. Defaults are a property of the
+schema, not of how the call arrived, so gating them on that flag would apply them
+over HTTP and skip them on a direct RPC invocation. Two smaller rules follow: a
+non-null primitive body is returned untouched for the validator to reject rather
+than reshaped into something that would pass; and each value is
+`structuredClone`d, so an object or array default (`[]`, `{}`) is never shared as
+one mutable instance across every request. The result object is allocated only
+once a default is actually found, which is what lets a call made with no
+arguments at all still receive them.
+
+**What this rules out:** moving the `applyDefaultsFromSchema` call inside the
+`if (coerceDataFromSchema)` branch next to the coercion call, or reordering it
+after validation. It also rules out dropping the `structuredClone` as an
+allocation — the shared-mutable-default bug it prevents is cross-request and
+`schema.test.ts` pins it — and rules out replacing the `'default' in property`
+presence check with a truthiness check, since `false` and `0` are exactly the
+defaults a truthiness check silently discards.

package/knowledge/decisions/internals/core-scopes-are-an-and-gate-separate-from-permissions.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: Scopes are an AND gate, separate from permissions
+description: Every declared scope must be held, so adding one can only narrow access — permissions OR, and can only widen it
+tags: core
+---
+
+# Scopes are an AND gate, separate from permissions
+
+`packages/core/src/scopes.ts` implements the scope check that
+`runPikkuFunc` performs before permissions. Every entry in a function's `scopes`
+must be satisfied by the session's grants — an AND gate — and the check fails
+closed: a session without a `scopes` field, or no session at all, satisfies
+nothing. An empty `required` is the only thing anything satisfies.
+
+This is deliberately the opposite composition from `permissions`, whose groups OR
+together. Because permissions OR, adding a permission group can only *widen*
+access; because scopes AND, adding a scope can only *narrow* it. That is the
+whole reason the two are separate mechanisms and separate code paths rather than
+one merged authorization step, and it is why a passing global or function
+permission must never be allowed to satisfy a scope.
+
+Satisfaction itself is hierarchical, computed by `satisfyingGrants`: a grant
+matches when it is the scope itself, a plain ancestor (`admin` covers
+`admin:invoices:create`), a wildcard at or above it (`admin:*`, or the bare `*`),
+or a wildcard directly beneath it. Narrower never satisfies broader —
+`admin:invoices` does not grant `admin`. Core only ever *reads*
+`session.scopes`; whoever builds the session populates it (better-auth's
+`mapSession` resolving through a `ScopeService`, for instance), and the runner
+never fetches. `hasScopes` is the non-throwing counterpart of `verifyScopes`, for
+gates that fall back to another check rather than rejecting outright.
+
+**What this rules out:** folding the scope check into `runPermissions` so there
+is "one authorization step", or making an OR of scopes so a session holding any
+one of them passes. Either turns a narrowing gate into a widening one, which is a
+privilege escalation and not a refactor. It also rules out defaulting an absent
+`session.scopes` to "all" for convenience, and rules out having core resolve
+scopes itself at call time.

package/knowledge/decisions/internals/core-state-is-a-global-map-written-only-at-registration-time.md

@@ -0,0 +1,44 @@
+---
+type: decision
+title: Pikku state is a global map written only at registration time
+description: A symbol-keyed globalThis map holds the wiring registry; nothing per-request may ever be written to it
+tags: core
+---
+
+# Pikku state is a global map written only at registration time
+
+`packages/core/src/pikku-state.ts` keeps every registry Pikku has —
+functions, HTTP routes, channels, schedulers, queues, workflows, triggers, MCP
+tools, agents, gateways, CLI programs, middleware groups, permissions, schemas
+and error definitions — in a single `Map<string, PikkuPackageState>` hung off
+`globalThis` under `Symbol('@pikku/core/state')`. `pikkuState(packageName, type,
+content, value?)` is the only accessor; `PikkuPackageState` in
+`packages/core/src/types/state.types.ts` is its shape.
+
+It is on `globalThis` rather than in a module-level `const` because a bundled
+app can end up with more than one copy of `@pikku/core` in the module graph
+(workspace links, addon packages that depend on their own core, a runtime
+adapter pulling a second instance). Module-level state would give each copy its
+own empty registry and functions would go missing at call time; a symbol on the
+realm global is shared by every copy in that realm. The package-name dimension
+is what keeps addon registries from colliding with the host project's.
+
+Everything written here is written **once, at import time**, by `wireHTTP`,
+`addFunction`, `addTagMiddleware`, `addError`, `addSchema` and friends — that is,
+by the top-level side effects of the generated and user modules. It is
+registration data, not request data. Pikku must stay stateless and
+serverless-compatible: the same process serves concurrent invocations on Lambda,
+Workers and multi-instance containers, and nothing in a request may outlive it.
+The file reads like a violation of that rule until you know the writes are all
+registration-time. The one exception is deliberate and narrow:
+`resetPikkuState()` preserves the `misc.errors` map across a reset, because error
+definitions are registered by module-import side effects that will not re-run.
+
+**What this rules out:** using `pikkuState` as a convenient place to stash
+anything derived from an invocation — a session, a request-scoped cache, a
+pending workflow, a "current user". Any such write is shared across every
+concurrent request in the process and lost entirely on the next cold start. It
+also rules out replacing the `globalThis` symbol with a module-scoped `Map` "for
+cleanliness", and rules out making the state per-request (an `AsyncLocalStorage`
+context, say) — the registry is read on hot paths by the function runner and the
+routers, and it must be identical for every caller.

package/knowledge/decisions/internals/email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: Email meta is read uncached because codegen rewrites it mid-session
+description: getEmailMeta re-reads its file on every call, unlike every other meta accessor, because the file appears and changes during a long-lived session
+tags: services
+---
+
+# Email meta is read uncached because codegen rewrites it mid-session
+
+`LocalMetaService.getEmailMeta` (`packages/core/src/services/meta-service.ts`)
+reads `email/pikku-emails-meta.gen.json` fresh on every call. Every other
+`getXMeta` on that class memoises into a private cache field; this one
+deliberately does not.
+
+The email meta file is written by `pikku all` / `pikku emails generate`, and in a
+long-lived session it is regenerated underneath a running process — the sandbox
+boots the orchestrator before the user project's codegen has produced it. When
+this accessor was cached, the first call landed before the file existed, cached
+the empty `{ templates: {} }` fallback, and the console's emails screen stayed
+blank for the rest of the session even after the file appeared. A local JSON
+read is essentially free, so re-reading is the cheaper mistake.
+
+**What this rules out:** "consistency" refactors that give every meta accessor
+the same caching treatment, including the one that collapses the ~25 hand-written
+`getXMeta` methods and their cache fields into a single generic
+`cached(key, loader)` helper. Email meta must stay outside whatever cache that
+introduces.

package/knowledge/decisions/internals/gateway-adapters-resolve-lazily-and-are-promise-cached.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: Gateway adapters resolve lazily and are promise-cached
+description: wireGateway accepts an adapter factory because real adapters need boot-time secrets, which forces the webhook GET route to be registered unconditionally
+tags: gateway
+---
+
+# Gateway adapters resolve lazily and are promise-cached
+
+`wireGateway` runs at module load, before secrets and services exist. Real
+platform adapters (WhatsApp Cloud API, Slack, …) need both, so
+`CoreGateway.adapter` accepts a `GatewayAdapterFactory` as well as an instance.
+`resolveGatewayAdapter` in
+`packages/core/src/wirings/gateway/gateway-runner.ts` invokes the factory on the
+first inbound request (webhook/websocket) or on gateway start (listener). The
+`resolvedAdapters` WeakMap caches the *promise*, not the resolved adapter, so
+concurrent first requests share one construction instead of racing to build two
+adapters — which for a stateful adapter would mean two platform connections.
+
+The lazy resolution has one visible consequence in `wireWebhookGateway`: a
+factory cannot be probed for `verifyWebhook` at wiring time, because it has not
+run yet. The GET verification route is therefore registered unconditionally
+whenever the adapter is a function, and only conditionally
+(`adapter.verifyWebhook`) when it is a concrete instance. The GET handler throws
+`NotFoundError` at request time if the resolved adapter turns out not to support
+verification.
+
+**What this rules out:** calling the factory eagerly inside `wireGateway` to
+"simplify" route registration, caching the resolved adapter instead of the
+promise, and narrowing the GET route registration to `adapter.verifyWebhook` for
+all adapters — the last silently drops webhook verification for every
+factory-based gateway.

package/knowledge/decisions/internals/gateway-webhook-challenges-echo-bytes-not-json.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: Gateway webhook challenges echo bytes not JSON
+description: String verification challenges are returned raw with returnsJSON false, because platforms byte-compare the echo and JSON quoting fails the handshake
+tags: gateway
+---
+
+# Gateway webhook challenges echo bytes not JSON
+
+Webhook verification handshakes (WhatsApp's `hub.challenge`, similar GET
+challenges elsewhere) are validated by the platform doing a byte-for-byte
+comparison of the response body against the challenge it sent. JSON-encoding a
+string challenge adds surrounding quotes and fails the handshake, and the gateway
+is then never activated.
+
+`wireWebhookGateway` in
+`packages/core/src/wirings/gateway/gateway-runner.ts` therefore registers the GET
+verification route with `returnsJSON: false`, and
+`createWebhookVerifyHandler` returns `String(response)` when the adapter's
+`WebhookVerificationResult.response` is a string or number. Object responses
+(Slack's `url_verification` style) still go out as JSON, with the
+`content-type: application/json` header set explicitly by the handler, since the
+route no longer does it.
+
+**What this rules out:** setting `returnsJSON: true` on the gateway GET route for
+consistency with other routes, and routing the challenge response through the
+normal JSON serializer. Any change that makes the string branch serialize as JSON
+breaks webhook activation on every platform that byte-compares.

package/knowledge/decisions/internals/gateway-wiring-is-a-meta-wiring-over-http-and-channels.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: Gateway wiring is a meta-wiring over HTTP and channels
+description: 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
+tags: gateway
+---
+
+# Gateway wiring is a meta-wiring over HTTP and channels
+
+`wireGateway` in `packages/core/src/wirings/gateway/gateway-runner.ts` is not a
+transport of its own. It composes the existing primitives: a `webhook` gateway
+pushes entries straight into `pikkuState(null, 'http', 'routes')`, a `websocket`
+gateway pushes into `pikkuState(null, 'channel', 'meta')` and `'channels'`, and a
+`listener` gateway registers no route at all and is driven by a
+`GatewayService` calling `createListenerMessageHandler`. Each mutation is
+followed by `httpRouter.reset()` because the router caches its match table.
+
+The wrapper functions and routes created here look like they are missing their
+metadata. They are not: the inspector projects a `wireGateway` call into the
+generated HTTP and function meta at build time, so only the handler
+*implementations* register at runtime — the same split every other wire uses.
+This is why `wireWebhookGateway` writes route entries but no `CommonWireMeta`,
+and why the websocket path sets `channels.set(name, …)` with empty
+`onConnect`/`onMessage` stubs while the real handlers live under the
+`gateway__<name>__connect` / `__message` function ids named in the channel meta.
+
+**What this rules out:** adding runtime meta generation inside `wireGateway` to
+"fix" the apparently missing metadata — it would duplicate or conflict with the
+compiled meta. It also rules out replacing the empty channel `onConnect` /
+`onMessage` stubs with the real handler functions; the channel runner dispatches
+through the meta's `pikkuFuncId`, not through those fields.

package/knowledge/decisions/internals/generated-src-paths-in-pikku-meta-are-absolute.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Generated src paths in pikku meta are absolute
+description: emailsMeta.src is resolved by the CLI at generation time, so reading through the project-relative helpers produces a wrong compound path
+tags: services
+---
+
+# Generated src paths in pikku meta are absolute
+
+`emailsMeta.src` is written by the CLI at generation time and is already an
+absolute filesystem path. `LocalMetaService.getEmailTemplateAssets`
+(`packages/core/src/services/meta-service.ts`) therefore calls `readFile` on
+`join(baseDir, rel)` directly instead of going through its own
+`readProjectFile`, which is the helper every other read in that class uses.
+
+`readProjectFile` prepends the project root (`join(basePath, '..', relativePath)`).
+Handing it an already-absolute `src` yields a compound path that points nowhere,
+and the failure is silent — the helpers return `null` on a missing file, so the
+symptom is a template that reports itself as having no assets rather than an
+error naming the path.
+
+**What this rules out:** routing the email asset reads through `readProjectFile`
+or `readFile` "for consistency", and assuming that any `src` field appearing in a
+`.gen.json` is relative to the project. If a remote `MetaService` ever needs to
+serve these assets, it has to translate the absolute path rather than pass it
+through.

package/knowledge/decisions/internals/http-request-bodies-are-read-once-and-shared.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: HTTP request bodies are read once and shared between consumers
+description: The fetch request wrapper memoises the single-use body and builds web Requests lazily, at the cost of holding the whole body in memory
+tags: http
+---
+
+# HTTP request bodies are read once and shared between consumers
+
+A fetch `Request` body is a single-use stream: the second reader gets "Body has
+already been used". `PikkuFetchHTTPRequest` in
+`packages/core/src/wirings/http/pikku-fetch-http-request.ts` therefore funnels
+`json()`, `arrayBuffer()`, `data()` and everything reached through
+`toWebRequest()` into `#readRawBuffer`, which memoises both the in-flight promise
+and the resolved buffer. A second consumer arriving while the first read is still
+running is served the same promise — and warned, because a duplicate consumer is
+a bug to remove at the source rather than a case to lean on the cache for.
+
+`toWebRequest` in `packages/core/src/wirings/http/web-request.ts` builds its body
+stream with `pull` rather than `start`, so the underlying body is touched only
+when the stream is actually consumed. A caller that constructs a web `Request`
+purely to read headers — session middleware calling `getSession({ headers })` is
+the common case — performs zero body I/O and cannot race the route handler's own
+read. Its fallback path exists because some runtimes (Express with a body-parser
+in front) hand pikku a request whose raw body is already drained; there
+`arrayBuffer()` is empty and the body has to be reconstructed from the parsed
+form or JSON.
+
+**What this rules out:** calling `request.arrayBuffer()`/`request.json()` on the
+underlying fetch `Request` directly anywhere in the runner; switching the
+`toWebRequest` stream to `start` for eagerness; and deleting the empty-buffer
+reconstruction branch as an impossible case.

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.