@pikku/core 0.12.142 → 0.12.144

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

@@ -1,31 +0,0 @@
----
-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

@@ -1,26 +0,0 @@
----
-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/global-middleware-resolves-from-the-root-namespace-too.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: Global middleware resolves from the root namespace too
-description: An addon's dispatch carries the addon's package name, so reading globals from that namespace alone meant the application's own global middleware never ran for it
-tags: [middleware, addons, packages]
----
-
-# Global middleware resolves from the root namespace too
-
-`combineMiddleware` collects global middleware from `[null]` for a root
-dispatch, and from `[null, packageName]` for a dispatch belonging to a package.
-
-It previously read one namespace: whichever `packageName` the dispatch carried.
-Application wirings carry `null`, so they were unaffected. A wiring contributed
-by an addon carries that addon's package name, and the application's own globals
-were not in that list — so an addon-contributed MCP tool ran with no session
-middleware at all and refused every caller, while the same function reached over
-HTTP authenticated normally.
-
-Global middleware is application-wide by definition, and an addon's function
-still runs inside the host application, so the root namespace always applies.
-One addon's globals still do not reach another addon's dispatches.
-
-The consequence is that a global written against the application's services now
-runs where those services may not exist — an addon builds its own. Middleware
-that reaches for a service it was not given has to stand down rather than throw;
-see `a-session-middleware-stands-down-where-it-cannot-authenticate.md` in
-`@pikku/better-auth`, which is where this first surfaced.
-
-**What this rules out:** treating a package namespace as a middleware boundary
-in both directions. It is a boundary for what an addon contributes, not a wall
-that the host application's own policy stops at.

package/knowledge/decisions/internals/hot-reload-reads-the-changed-source-never-a-compiled-copy.md

@@ -1,38 +0,0 @@
----
-type: decision
-title: Hot reload reads the changed source, never a compiled copy of it
-description: A leftover .js beside a .ts made the reloader announce a reload while re-registering the previous implementation; project TypeScript is now compiled by the reloader itself
-tags: core, dev
----
-
-# Hot reload reads the changed source, never a compiled copy of it
-
-The reloader watches `.ts` files and runs the file that changed. It used to
-look for a compiled `.js` first — `<outDir>/dist/<rel>.js`, then the sibling
-`<file>.js` — and import the source only when neither existed.
-
-`pikku dev` compiles nothing. Every one of those `.js` files is a leftover from
-an earlier `tsc`, `pikku dist` or bundler run, so reading one re-registered the
-implementation the developer had just replaced and logged `Hot-reloaded: <fn>`
-over the top of it. The log line reads as confirmation, so the change looks
-applied and wrong rather than unapplied — which is the expensive way round
-(#1721).
-
-The lookup was a leftover of the first implementation, which imported raw file
-content through a `data:` URL and genuinely could not handle TypeScript. The
-module runner has transpiled with esbuild since, so the source was loadable all
-along and the compiled candidates could only ever supply stale code.
-
-Loading the source means the reloader also owns resolution. `require('./x.js')`
-where only `x.ts` exists is what every relative import in a TypeScript project
-looks like, and node's `require` has no `.js → .ts` rewrite. Resolution goes
-through the host first — so packages bind to the instance the rest of the
-process holds and `wire*` side effects mutate live state — and a resolved
-TypeScript file outside `node_modules` is then compiled by the reloader rather
-than handed back, because both node and Bun cache what they load and a helper
-edited alongside its caller would otherwise keep answering with the copy loaded
-at startup. That cache is scoped to a single reload for the same reason.
-
-**What this rules out:** reintroducing a compiled-output lookup as a
-"performance" shortcut, and letting the host load project `.ts` dependencies so
-reloads inherit its module cache.

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

@@ -1,26 +0,0 @@
----
-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/http-request-bodies-are-read-once-and-shared.md

@@ -1,32 +0,0 @@
----
-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

@@ -1,28 +0,0 @@
----
-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

@@ -1,30 +0,0 @@
----
-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

@@ -1,26 +0,0 @@
----
-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

@@ -1,28 +0,0 @@
----
-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

@@ -1,32 +0,0 @@
----
-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

@@ -1,26 +0,0 @@
----
-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

@@ -1,25 +0,0 @@
----
-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/virtual-users-service.ts`) and
-`ScenarioVirtualUser.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 a virtual user 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

@@ -1,26 +0,0 @@
----
-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.