@pikku/core 0.12.142 → 0.12.144

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

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

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

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

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

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

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

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

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

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

@@ -1,27 +0,0 @@
----
-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/feature-flag-declarations-refuse-an-empty-anyof-and-conflicting-scopes.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: Feature flag declarations refuse an empty anyOf and conflicting scopes
-description: validateAndBuildFeatureFlagDefinitionsMeta throws on an anyOf that is an empty list, and on a repeated flag name whose scopes differ between declarations
-tags: core, flags, validation
----
-
-# Feature flag declarations refuse an empty anyOf and conflicting scopes
-
-`validateAndBuildFeatureFlagDefinitionsMeta` in
-`packages/core/src/wirings/flag/validate-flag-definitions.ts:70-98` checks each
-declaration in two ways.
-
-An `anyOf` that is an empty array throws (`:78-84`). The message says an empty
-list satisfies nobody, and that a pure switch should omit `anyOf`.
-
-When a flag name is declared twice, the two `anyOf` lists are compared as sorted
-JSON (`:86-90`). A difference throws (`:91-97`), and the message says flags sharing
-a name must name the same scopes.
-
-**What this rules out:** a flag that no session can satisfy, and two declarations
-of one flag that disagree about who may see it.

package/knowledge/decisions/internals/feature-flags-fail-open-and-never-enforce-access.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: Feature flags fail open on availability and never enforce access
-description: A flag with no config row is available by default, anyOf decides only the advisory capable half, and the runner's assertFeatureAvailable checks availability alone
-tags: core, flags, authorization
----
-
-# Feature flags fail open on availability and never enforce access
-
-`resolveFlag` in `packages/core/src/wirings/flag/resolve-flag.ts:54-95`
-separates two halves. `capable` is true when `anyOf` is absent, and otherwise
-comes from `hasAnyScope` on the session's scopes (`:68-69`). If the flag has no
-config row, the result is `available: true` (`:72-74`). The doc comment at `:54-59`
-says this fail-open is safe only because `capable` comes from the session and
-`scopes:` is not changed by a flag.
-
-`FlagState` in `packages/core/src/wirings/flag/flag.types.ts:97-104` says the same
-thing: `available` is the only half the runner enforces, and `capable` is advisory
-and "protects nothing". `flag.types.ts:14-18` says `anyOf` is an OR over scopes,
-deliberately the opposite of `scopes`, which is an AND.
-
-`assertFeatureAvailable` in `packages/core/src/wirings/flag/assert-feature-available.ts`
-calls `resolveFlag` and throws only when `available` is false (`:28-30`). It does
-nothing when no feature-flag source is registered (`:24-26`). The doc comment at
-`:10-12` says enforcing `capable` here would make a second authorization path.
-
-**What this rules out:** using a flag as an access check, and a store outage
-turning every flagged feature off.

package/knowledge/decisions/internals/flag-sync-rewrites-only-the-declared-text.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: Flag declaration sync rewrites only the description and anyOf
-description: The FeatureFlagStore contract re-syncs a flag's description and anyOf on deploy and leaves enabled, rollout and overrides to the operator
-tags: core, flags, services
----
-
-# Flag declaration sync rewrites only the description and anyOf
-
-The `FeatureFlagStore` interface in `packages/core/src/services/feature-flag-service.ts:79-90`
-declares `syncFlags`. Its doc comment says a flag's `description` and `anyOf` are
-re-synced on each deploy, because that is the declaration's whole content. It also
-says `enabled`, the rollout and every override belong to the operator and are never
-touched.
-
-Lines `:80-83` say a removed declaration leaves its row marked `declared: false`
-rather than deleting the operator's switch.
-
-Core defines only the interface here. The implementing store is not in this
-package, so the rule is the contract's, and was not verified against an
-implementation.
-
-**What this rules out:** a deploy overwriting an operator's enabled state, rollout
-or overrides, and deleting a flag row because its declaration was removed.

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

@@ -1,32 +0,0 @@
----
-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-listener-middleware-runs-without-an-rpc-on-the-wire.md

@@ -1,43 +0,0 @@
----
-type: decision
-title: Gateway middleware sees wire.rpc on webhook and websocket, but not on listener
-description: The listener transport invokes its handler directly, so middleware runs outside any runPikkuFunc call and the lazily-attached rpc is absent
-tags: core, gateway
----
-
-# Gateway middleware sees `wire.rpc` on webhook and websocket, but not on listener
-
-`runPikkuFunc` in `packages/core/src/function/function-runner.ts` attaches `rpc`
-to the invocation wire with `Object.defineProperty`, as a lazy getter that
-replaces itself on first read — and restores the previous descriptor in its
-`finally`. `rpc` therefore exists on a wire _only for the duration of a function
-invocation_. That is why `PikkuRawWire` is `Omit<PikkuWire, 'rpc'>`: it is the
-wire as a runner constructs it, before the function runner adds `rpc`.
-
-The three gateway transports reach middleware differently:
-
-- **webhook** and **websocket** register their handlers with `addFunction`, so
-  the handler body already runs inside a `runPikkuFunc` invocation. The `wire`
-  it receives is a full `PikkuWire`, and `config.middleware` runs inside that
-  same invocation — `wire.rpc` is live.
-- **listener** has no such wrapper. `createListenerMessageHandler` is handed
-  straight to `adapter.init()` by the `GatewayService`, builds
-  `const wire: PikkuRawWire = {}` itself, and runs `config.middleware` _before_
-  `invoke()` reaches `runPikkuFunc`. There is no invocation in progress, so
-  `wire.rpc` is `undefined`.
-
-A gateway middleware that calls `wire.rpc.invoke(...)` therefore works on two
-transports and throws on the third, with nothing in the types to say so — the
-call into `runMiddleware` needs an assertion, because `runMiddleware` is typed
-off `CorePikkuMiddleware`, whose wire parameter is `PikkuWire`.
-
-**What this rules out:** treating the assertion at that call as noise to be
-deleted. It is naming a real gap. It also rules out "just widen
-`CorePikkuMiddleware` to accept `PikkuRawWire`" as a free fix — that would make
-`rpc` optional for _every_ middleware in the framework, pushing the problem onto
-every consumer to satisfy one transport.
-
-**Still open:** whether the listener path should wrap its handler in a
-`runPikkuFunc` invocation the way the other two do, which would make the three
-transports behave identically and remove the assertion. Nobody has argued
-against it; it simply has not been done.

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

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