@pikku/core 0.12.72 → 0.12.77

package/knowledge/decisions/internals/cli-unknown-long-options-warn-instead-of-failing.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: CLI unknown long options warn instead of failing
+description: Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
+tags: cli
+---
+
+# CLI unknown long options warn instead of failing
+
+`warnUnknownOption` in `packages/core/src/wirings/cli/command-parser.ts` pushes
+onto `ParsedCommand.warnings`, not `ParsedCommand.errors`, so an unrecognised
+`--long` option does not abort the command. The value is still parsed into
+`optionArgs`, but `pluckCLIData` in `cli-runner.ts` drops anything absent from
+the function's input schema — so the option is silently ignored at execution
+time. The warning exists precisely so that dropping is not silent.
+
+The reason is forward compatibility: a script or wrapper written against a newer
+command version may pass options an older installed binary does not know, and
+failing hard there turns a harmless extra flag into a broken pipeline.
+`RESERVED_OPTIONS` exempts flags the runner handles itself (`help`) from the
+warning. Unknown *short* flags are treated differently — they go to
+`result.errors` and do fail — because a bundled short-flag cluster like `-abc`
+cannot be reliably attributed, and a typo'd short flag is far more likely than a
+version skew.
+
+**What this rules out:** promoting unknown long options to errors "for
+strictness", and removing the warning on the grounds that the schema pluck
+already handles it — that restores the silent drop this was added to end. It also
+rules out making unknown short flags non-fatal for symmetry.

package/knowledge/decisions/internals/core-column-form-is-an-axis-of-its-own.md

@@ -0,0 +1,84 @@
+---
+type: decision
+title: A column's at-rest form is an axis of its own
+description: 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
+tags: core
+---
+
+# A column's at-rest form is an axis of its own
+
+`ColumnForm` in `packages/core/src/data-classification.ts` is a second,
+independent annotation on a column: `plain | hashed | wrapped | sealed`. It
+answers "how are these bytes held?", where `Classification` answers "may this
+value leave the process?".
+
+The two axes were one field before this, with `security: 'encrypted'` sitting
+alongside `secret` as though they were alternatives. They are not, and the
+conflation made the field unanswerable: a token hash and a live bearer token are
+both `secret`, one must never be encrypted — the digest *is* the lookup key —
+and the other must always be. Nothing in a single enum could tell them apart, so
+nothing could check either.
+
+## Why `wrapped` and `sealed` rather than `encrypted`
+
+Sealed values *are* encrypted, so an `encrypted` member sitting beside `sealed`
+would be a supertype posing as a sibling, and every new column would be an
+even-odds guess. What actually separates them is who can read the value back:
+`wrapped` is symmetric and the application holds the key; `sealed` is asymmetric
+and the application holds only the public half. Writing one where the other
+belongs produces a row nobody can ever open, which is why the type system is
+made to know the difference.
+
+## Why these brands are required when `Secret<T>` is optional
+
+`WrappedValue`, `SealedValue` and `HashedValue` are `string & { readonly [sym]:
+true }` with a `unique symbol` — nominal, and **required**, which
+[the classification-brand decision](core-data-classification-brand-is-an-optional-property.md)
+explicitly rules out for `Private`/`Pii`/`Secret`. That decision still stands and
+this does not weaken it. It applies to a different side of a different set of
+columns:
+
+- `Secret<T>` brands **every** classified column's SELECT type. A required brand
+  there would break `where('email', '=', someString)` in every downstream
+  project.
+- A form brands **only** the INSERT/UPDATE type, and only on the columns that
+  opt in by declaring a form. There is nothing to break, because a column
+  without a form generates exactly what it generated before.
+
+The brands compose rather than compete: a wrapped secret column selects as
+`Secret<WrappedValue>`, so the inspector's PKU910 check still finds
+`__classification__`, while a row read back is already a `WrappedValue` and
+flows into a rewrap or re-seal without a cast.
+
+Each brand widens to `string`, so query operands, serialization and template
+literals are unaffected. The constraint is on **construction**: the only way to
+produce one is `envelopeEncrypt`/`envelopeRewrap`/`wrapDEK` (wrapped) or
+`hashToken` (hashed), or the deliberately-named `unsafeAs*` assertions in
+`column-form.ts` for the three cases a bare string legitimately arrives —
+backfill migrations, test fixtures, and values sealed by another service.
+
+## What is deliberately NOT enforced
+
+`envelopeDecrypt` and `unwrapDEK` take plain `string`, not the brand. Requiring
+it would buy nothing — feeding in the wrong string already fails at the AEAD tag
+— while forcing a cast into every path that reads ciphertext out of a row or off
+the wire, which is where casts are least reviewable.
+
+The brand proves *provenance*, not correctness. It cannot know a value was
+wrapped under the right key, and making it know would mean phantom-typing key
+ids per scope, which the multi-recipient path would fight constantly.
+
+## The plain-secret diagnostic
+
+A `secret` column with no declared form raises **PKU483** as a warning, not an
+error. Every project predating the axis has such columns, and failing their next
+`db migrate` would be a breaking change for a diagnosis they have not had a
+chance to act on. `pikku db --fail-on-warn` is how a project opts into the
+ratchet. An explicit `form: 'plain'` silences it — that is the acknowledgement
+that reading the row is *meant* to yield a usable credential.
+
+**What this rules out:** collapsing `wrapped` and `sealed` back into one
+`encrypted`; making the form brands optional (they would enforce nothing);
+re-declaring them in generated schema files, since a local `unique symbol` is a
+distinct nominal type and core's own ciphertext would not be assignable to the
+column it belongs in — `db-codegen` imports them from `@pikku/core` instead.

package/knowledge/decisions/internals/core-data-classification-brand-is-an-optional-property.md

@@ -0,0 +1,41 @@
+---
+type: decision
+title: The data-classification brand is an optional property
+description: Making __classification__ required would break ordinary Kysely operands, so the brand only constrains values flowing out
+tags: core
+---
+
+# The data-classification brand is an optional property
+
+`Private<T>`, `Pii<T>` and `Secret<T>` in
+`packages/core/src/data-classification.ts` brand a type with
+`{ readonly __classification__?: 'private' | 'pii' | 'secret' }` — and the
+marker is **optional on purpose**.
+
+A required property would make a plain value unassignable to a branded column: a
+`string` could no longer be passed where `Private<string>` is expected, which
+breaks every ordinary Kysely query operand — `where('email', '=', someString)`,
+inserts, and `.set(...)`. Making it optional keeps the brand structurally present
+so static analysis still sees it, while letting plain values flow *in*. The
+asymmetry is the point: the brand constrains what comes out of a query, not what
+goes into one.
+
+The consumer is `@pikku/inspector`, whose `findPiiPaths` reads the level union
+directly and whose PKU910 output check detects the brand on a function's return
+type. The brands are populated from the hand-authored `db/annotations.ts`
+(`DbClassificationMap`) via `pikku db migrate`, which regenerates
+`outDir/db/schema.d.ts` and `outDir/db/classification.gen.ts`.
+
+A column's **at-rest form** is a separate axis making the opposite trade — see
+[form is an axis of its own](core-column-form-is-an-axis-of-its-own.md). Its
+brands are nominal and required, which is safe precisely because they land on
+the INSERT/UPDATE side of the columns that opt in, rather than on the SELECT
+side of every classified column. That is not an exception to the rule below; it
+is a different rule about a different side.
+
+**What this rules out:** making `__classification__` required to get stronger
+guarantees, or replacing the optional property with a unique symbol / nominal
+brand that behaves like a required one. Either change compiles here and then
+breaks every generated Kysely call site in every downstream project. It also
+rules out renaming the property or narrowing its literal union without updating
+`findPiiPaths` in the inspector, which matches on both.

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.