@pikku/core 0.12.142 → 0.12.144

package/knowledge/decisions/internals/scenario-agent-calls-sign-in-on-401-only.md

@@ -1,31 +0,0 @@
----
-type: decision
-title: Scenario agent calls retry sign-in only on 401
-description: HttpVirtualUser.sendAgent sends with whatever session the jar holds and signs in only after a 401, so a no-auth agent route never needs a sign-in; converse signs in eagerly instead
-tags: services
----
-
-# Scenario agent calls retry sign-in only on 401
-
-`HttpVirtualUser.sendAgent` (`packages/core/src/services/http-virtual-users.ts`)
-sends its request with whatever cookie the jar holds. Only a 401 triggers
-`signOut()`, `login()` and a single retry. The agent calls that go through it
-are the stream and approve paths and `postAgent`. Its sibling `invokeRaw` does
-the opposite: it signs in eagerly before the first RPC.
-
-`HttpVirtualUser.converse` does not rely on that path. Before its first turn it
-calls `login()` when `signedIn` is false. The reason is in the code comment
-there: a public agent route never returns 401, so the retry would never sign
-the virtual user in, and a virtual user is a real account, so conversing as
-nobody is not the intent. See
-[a virtual user's converse signs in before its first turn](a-virtual-user-converse-signs-in-before-its-first-turn.md).
-
-The 401 path exists because agent HTTP routes may be public; RPC routes are
-assumed not to be. Making every agent call eager would mean a virtual user could
-not reach a no-auth agent without a sign-in endpoint and credentials. Deferring
-to the 401 keeps the authenticated case working (the retry succeeds with the
-session attached) at the cost of one extra round trip the first time.
-
-**What this rules out:** removing the 401 retry from `sendAgent` on the grounds
-that a sign-in always happens first, and making `sendAgent` sign in up front
-"like `invokeRaw` does" without first checking what the agent route requires.

package/knowledge/decisions/internals/scenario-given-and-when-are-sugar-but-then-is-not.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: `given` and `when` are sugar for each other; `then` is not
-description: The phase decides whether a step's bindings are alternatives or witnesses, so the same step function called as `when` and as `then` runs differently
-tags: core, workflow
----
-
-# `given` and `when` are sugar for each other; `then` is not
-
-All three run a named `pikkuScenarioStep` as one durable step. `given` and
-`when` differ only in the prose a reporter renders — the step behaves
-identically either way.
-
-`then` is a different operation. The phase is what decides how a step's surface
-bindings are treated: for an action, the bindings are _alternatives_ and one is
-chosen; for an assertion, they are _witnesses_ and every applicable one runs and
-must agree. So the same step function invoked as `when` and as `then` executes a
-different number of times against a different number of surfaces.
-
-See `resolveScenarioSurfaces` for the resolution itself.
-
-**What this rules out:** collapsing the three into one call with a cosmetic
-label, or letting a caller pass the phase as data. The phase changes execution,
-so it has to be visible at the call site.

package/knowledge/decisions/internals/scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: Scenario meta lives apart from app meta but merges when read off disk
-description: Scenarios generate into .pikku/scenarios so no app module imports them, yet MetaService folds them back into the workflow and function meta
-tags: services
----
-
-# Scenario meta lives apart from app meta but merges when read off disk
-
-Scenario workflows and scenario steps are generated into `.pikku/scenarios/`
-rather than alongside the app's own `workflow/` and `function/` meta. The split
-exists at the import level: nothing app-facing should pull a scenario into a
-production bundle.
-
-The split does not exist at the meta level. `LocalMetaService.getWorkflowMeta`
-reads both `workflow/meta` and `scenarios/meta`, and `getFunctionsMeta` reads
-both `pikku-functions-meta` and `pikku-scenario-functions-meta`
-(`packages/core/src/services/meta-service.ts`). Anything reading meta off disk —
-the console's scenario list first among them — is entitled to see scenarios,
-because to a meta reader they simply are workflows and functions.
-`packages/core/src/services/meta-service.test.ts` guards this.
-
-**What this rules out:** dropping the second read on the grounds that the app
-never registers scenario workflows, and "tidying" the two meta directories into
-one. The two reads are the seam: separate on disk and in the import graph,
-merged in `MetaService`.

package/knowledge/decisions/internals/scenario-steps-return-drained-response-records.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: Scenario steps return drained response records
-description: A scenario step hands back ScenarioHttpResponse rather than a Response, because the body stream reads once and the return value crosses into the run record
-tags: services
----
-
-# Scenario steps return drained response records
-
-`ScenarioHttpResponse` and `readScenarioHttpResponse`
-(`packages/core/src/services/virtual-users-service.ts`) exist because a `fetch`
-`Response` cannot be a scenario step's return value. A step's result is
-serialised into the workflow run record, and a `Response` body is a stream that
-reads exactly once — by the time anything downstream looks at it, it is either
-consumed or unreadable.
-
-So the response is drained at the boundary: status, `ok`, the parsed body, and
-the raw text it was parsed from. `serialized` is kept alongside `body` so an
-assertion can search the payload without knowing its shape, and so an error page
-that is HTML rather than JSON still says what went wrong instead of collapsing to
-a parse failure. `body` is `undefined` for an empty response and the raw text when
-the payload was not JSON; its type parameter is a claim the caller makes, not one
-the transport checked.
-
-**What this rules out:** returning `Response` (or anything holding a stream) from
-a scenario step or a virtual user method, and dropping `serialized` as redundant with
-`body` — a non-JSON error body has no other route to the assertion.

package/knowledge/decisions/internals/scenarios-live-in-files-named-for-them.md

@@ -1,48 +0,0 @@
----
-type: decision
-title: Scenarios, steps and virtual users live in files named for them, and validate errors when they do not
-description: pikkuScenario/pikkuFeature/pikkuScenarioStep must be in *.scenario.ts, *.scenarios.ts or *.steps.ts, and defineVirtualUsers/runVirtualUser in *.virtual-user.ts or *.vu.ts — an error, because the mixing is only cheap to undo while it is one file
-tags: cli, validate, scenarios, virtual users
----
-
-# Scenarios, steps and virtual users live in files named for them, and validate errors when they do not
-
-A `pikkuScenario` declared beside the functions it exercises reads as more of
-the same file. The wiring, the function, and the test of the function arrive in
-one scroll, and the scenario is the part that gets lost — you cannot tell from
-a directory listing which files ship and which files test.
-
-So `validate` requires the declaration to be in a file named for what it is:
-
-| declaration                                         | file                              |
-| --------------------------------------------------- | --------------------------------- |
-| `pikkuScenario`, `pikkuFeature`                     | `*.scenario.ts`, `*.scenarios.ts` |
-| `pikkuScenarioStep` and its platform/addon variants | `*.steps.ts` (or the above)       |
-| `defineVirtualUsers`, `runVirtualUser`              | `*.virtual-user.ts`, `*.vu.ts`    |
-
-Three suffixes for scenarios rather than one, because the split that matters is
-scenarios apart from application code, not a particular spelling — `.steps.ts`
-holds the steps, `.scenarios.ts` holds the scenarios that call them, and a
-project that already made that split does not have to rename anything.
-
-**Error, not warning.** The mixing is cheap to undo while it is one file and
-expensive once it is thirty, and a warning is exactly the signal a project
-learns to scroll past. This is the one place where the scenario checks are
-strict: everything else `validate` says about scenarios (no virtual users declared,
-no virtual user sign-in, no environments) is a warning, because those describe an
-under-tested project rather than an unreadable one.
-
-**Virtual users are the virtual-user file** because there is no `defineVirtualUsers`
-to look for. That name was retired in favour of `defineVirtualUsers`: a virtual user
-is derived rather than authored — the function meta becomes its catalogue, the
-scenario meta becomes its intents, the declared virtual users become its identities.
-The virtual user list is the only part a project writes, so it is the part that has
-to be findable by filename.
-
-Matching is on the call (`\bpikkuScenario\s*\(`), not the import, so an aliased
-import cannot slip past and a mention in a comment or a string does not trip it.
-Generated files are exempt — codegen puts things where it likes.
-
-**What this rules out:** a scenario in a function file; a step in a wiring file;
-virtual users in a general-purpose `virtual-users.ts`; and reporting any of these as a
-warning that a project can carry indefinitely.

package/knowledge/decisions/internals/scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: Scope roots may be co-declared by an addon and its host app
-description: flattenScopeDefinitions dedupes ids because the same root can legitimately be declared twice, and every consumer requires one entry per scope
-tags: services
----
-
-# Scope roots may be co-declared by an addon and its host app
-
-`flattenScopeDefinitions`
-(`packages/core/src/wirings/scope/validate-scope-definitions.ts`) walks the
-declared trees depth-first, emits every node including intermediate ones, and
-then filters the result through a `seen` set. The dedupe is not defensive
-programming.
-
-An addon and the app hosting it may both contribute the same root — both
-declaring an `admin` tree, say — and that is a supported arrangement, not a
-misconfiguration. `validateAndBuildScopeDefinitionsMeta` has already established
-that definitions sharing a name are identical, and errors naming both source
-files if they are not, so by the time flattening runs a repeat is redundant rather
-than conflicting. Collapsing it here is what keeps the consumers honest: codegen
-writes these ids into an object literal keyed by id, where a duplicate key is a
-TypeScript error, and a `ScopeService` syncs one row per scope instead of
-re-writing the same one. `packages/core/src/wirings/scope/scope.test.ts` covers
-the co-declaration case.
-
-**What this rules out:** dropping the `seen` filter on the grounds that ids are
-already unique per declaration, and turning a repeated root into a validation
-error. The uniqueness guarantee lives here, and both codegen and scope sync
-depend on it.

package/knowledge/decisions/internals/serverless-channel-disconnect-must-tolerate-a-missing-channel.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: Serverless channel disconnect must tolerate a missing channel
-description: A failed channel lookup on disconnect returns quietly, because serverless runtimes deliver disconnect more than once
-tags: channel
----
-
-# Serverless channel disconnect must tolerate a missing channel
-
-`runChannelDisconnect` in
-`packages/core/src/wirings/channel/serverless/serverless-channel-runner.ts`
-wraps `channelStore.getChannel(channelId)` in a `try`/`catch` and returns after
-an info log when the lookup fails, before any lifecycle function runs.
-
-Serverless runtimes do not guarantee a single disconnect delivery.
-`serverless-offline`, worker-thread runners and retried invocations all call the
-disconnect path more than once for the same connection, and the second call
-arrives after `channelStore.removeChannels` has already run. There is nothing
-left to disconnect at that point, so an error would be noise on a normal
-shutdown — and, where the platform retries on failure, a loop. The local runner
-does not need this because the channel object lives in-process for the whole
-connection.
-
-**What this rules out:** treating a missing channel as an error worth throwing or
-logging at error level, and hoisting the `getChannel` call out of its `try` while
-"tidying up" the early returns. It also means `onDisconnect` is best-effort, not
-exactly-once — anything that must happen once per connection needs its own
-idempotency, not this handler.

package/knowledge/decisions/internals/side-effects-are-an-allowlist-not-a-boolean.md

@@ -1,34 +0,0 @@
----
-type: decision
-title: sideEffects is an allowlist, because core genuinely has some
-description: The error registry is built by addError calls that run on import, so claiming sideEffects:false would let a bundler drop it and leave getErrorResponse unable to find any error
-tags: core, packaging
----
-
-# `sideEffects` is an allowlist, not `false`
-
-Without a `sideEffects` field a bundler must assume every module in the package
-does something merely by being imported, so it cannot drop any of them. That is
-the state core shipped in, and it costs every bundled consumer the whole package.
-
-The reflex fix — `"sideEffects": false` — would be untrue. Five modules run code
-at import, 59 top-level calls between them, and every one is `addError(...)`
-registering an error class in the runtime registry:
-
-- `errors/errors.js` (44)
-- `wirings/workflow/pikku-scenario-service.js` (6)
-- `wirings/workflow/workflow-errors.js` (5)
-- `wirings/rpc/rpc-runner.js` (3)
-- `wirings/rpc/remote-addon-auth.js` (1)
-
-A bundler that dropped `errors/errors.js` because nothing imported a binding
-from it would leave `getErrorResponse` unable to map any error to a status. The
-app would build, and every error would come back as a generic 500.
-
-So the field names those five exactly. Everything else can be tree-shaken.
-
-**What this rules out:** flipping this to `false` as a performance change, and
-adding a module-level `addError` (or any other registration) without adding the
-module here. `side-effects-are-declared.test.ts` walks the source for top-level
-calls and fails in both directions — a module with side effects missing from the
-list, and a listed module that no longer has any.

package/knowledge/decisions/internals/speech-synthesis-picks-a-voice-per-sentence-and-warns-once.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: Speech synthesis picks a voice per sentence but announces a limitation once
-description: A bilingual reply should speak the half it can, and repeating the notice for every sentence would bury the reply itself
-tags: core, agent
----
-
-# Speech synthesis picks a voice per sentence, and warns once per reply
-
-`voiceOutput` checks the script of each sentence separately, but emits any
-"cannot speak this" notice only once for the whole reply.
-
-Per sentence is what makes the voice correct. A reply that answers in English
-and then quotes a Chinese title is two sentences in two scripts, and each is
-synthesized in the voice its own script needs. Checking once for the whole reply
-would pick one voice and mispronounce the other half.
-
-Announcing once is what keeps the reply audible. A bilingual answer should still
-speak the part it can, and repeating the notice for every sentence of a long
-reply buries the answer under its own caveats.
-
-**What this rules out:** moving the script check up to the reply level to save
-work, and moving the notice down to the sentence level for consistency with it.
-The two belong at different granularities on purpose.

package/knowledge/decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: The agent `done` event goes through the middleware and is awaited
-description: `done` is the only end-of-reply signal a stream hook gets, and buffering hooks flush on it — sending it raw discards work already paid for
-tags: core, agent
----
-
-# The agent `done` event goes through the middleware and is awaited
-
-Both the first turn and the post-approval resume send their terminating `done`
-event through the stream middleware rather than straight at the channel, and
-await it.
-
-`done` is the only signal a stream hook receives that the reply is over. The
-hooks that buffer need it to flush: `voiceOutput` holds a trailing fragment that
-never reached a full stop, and waits on audio it has already asked the provider
-to synthesize and already been billed for. Sending `done` raw skips those hooks
-entirely, and the `close()` immediately after throws the buffered work away.
-
-It matters more on the resume path than the first turn. After an approval, most
-of what gets spoken is the agent describing what it just did — so a dropped
-flush silences the larger half of the reply.
-
-**What this rules out:** treating the terminating event as a special case that
-can bypass the chain because "nothing comes after it". Something does: the
-flush.

package/knowledge/decisions/internals/the-api-report-pins-members-not-just-names.md

@@ -1,43 +0,0 @@
----
-type: decision
-title: The API report pins members, because the export list only pins names
-description: public-surface.json catches an export appearing or vanishing; it cannot see a method added to an interface, which is the change that breaks a consumer's build
-tags: core, api
----
-
-# The API report pins members, not just names
-
-`public-surface.json` records `Object.keys(module)` for every entry point. That
-is a real guard — it caught a new `./node-host-resolver` subpath and five
-renames during a rebase — but it only sees _names_.
-
-It cannot see:
-
-- a method added to `MetaService`, which has 32 members
-- a field on `ChannelMeta` becoming required
-- a parameter added to a method on `PikkuWorkflowService`, which has 104
-- any change at all to an `interface`, since types are erased before
-  `Object.keys` can enumerate them
-
-Those are the changes that break a consumer's build, and there are far more of
-them than there are exports — roughly two members for every name. The report's
-own summary counts both, live, so the figure is not repeated here to rot: an
-earlier hand-count in this note was already wrong by 40 members within a day of
-being written.
-
-Demonstrated rather than assumed: adding `probeAddedMember(): void` to
-`MetaService` leaves `public-surface.test.ts` passing 3/0, and fails
-`api-report.test.ts`.
-
-So `api-report.md` is generated from the type checker — every exported symbol
-with its full signature, interfaces and classes rendered as their declarations
-so member changes land in the diff. It is committed, and the test fails when
-the code and the report disagree. Regenerate with `yarn api-report`.
-
-**What this rules out:** treating `public-surface.json` as the API guard. It
-guards the front door; this guards the rooms. Both are needed, and the export
-list is the cheaper of the two to run — which is why it stayed.
-
-Re-exports are resolved through `getAliasedSymbol` before the signature is
-taken. Without that, 624 of the symbols reported as `any`, which would have
-pinned nothing while looking like it did.

package/knowledge/decisions/internals/the-core-scope-validator-refuses-separator-wildcard-and-empty-segments.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: The core scope validator refuses separator, wildcard and empty scope segments
-description: assertSegment rejects a scope segment that contains the colon separator, equals the wildcard, or is empty
-tags: core, scopes, validation
----
-
-# The core scope validator refuses separator, wildcard and empty scope segments
-
-`assertSegment` in `packages/core/src/wirings/scope/validate-scope-definitions.ts:11-27`
-checks each segment of a declared scope name in three ways.
-
-A segment containing the `:` separator throws (`:12-17`). The message says to
-nest scopes with the `scopes` property instead. A segment equal to `*` throws
-(`:18-23`), because the wildcard is reserved for granting a scope and its
-descendants. An empty segment throws (`:24-26`).
-
-The separator and the wildcard constants are at `:8-9`. The walk that calls this
-check is described in `scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md`.
-
-**What this rules out:** a declared scope whose name embeds a separator, which
-would make it match a different scope, and a declared wildcard.

package/knowledge/decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: The dev queue copies prod timing and serialization semantics
-description: InMemoryQueueService dispatches via setTimeout, retries with backoff, and JSON round-trips every payload so dev behaviour matches a real backend
-tags: services
----
-
-# The dev queue copies prod timing and serialization semantics
-
-`InMemoryQueueService` (`packages/core/src/services/in-memory-queue-service.ts`)
-is the local/dev queue, and it is deliberately less direct than it could be. It
-schedules jobs on the macrotask queue via `setTimeout` rather than calling the
-worker inline, it redelivers a failed job up to `options.attempts` times with
-backoff, and it JSON round-trips every payload on the way in.
-
-Each is there so dev does not teach a false lesson. Inline dispatch would make
-enqueue synchronous, and code written against that ordering breaks the first time
-it meets a real queue. Dropping a job on its first error would hide that a
-transiently-failing workflow step recovers fine on pg-boss or BullMQ. And every
-real backend puts the job on a wire — an SQS body, a Redis value, a `jsonb`
-column — so the worker never receives the caller's live object; round-tripping
-here means a payload carrying a `Date`, a class instance or a shared mutable
-reference fails in dev rather than in production. Callers cannot know which
-backend they are talking to, so they must not have to serialise defensively.
-
-**What this rules out:** "optimising" the dev queue by invoking the handler
-directly, skipping the JSON copy for speed, or short-circuiting retries. Its job
-is fidelity, not throughput. (Separately, the detached `setTimeout` makes this
-service unusable on Lambda or Workers, where the container freezes at response
-time — it is a dev service by construction, not just by name.)

package/knowledge/decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md

@@ -1,83 +0,0 @@
----
-type: decision
-title: One door per name — the ecosystem tier and the package root are both gone
-description: the adapter surface was split onto @pikku/core/ecosystem to keep a stability promise at the root; publishing every module twice cost more than the promise was worth, so both the facades and the root barrel were deleted
-tags: core, api
----
-
-# One door per name
-
-**Reversed.** The section below records why `@pikku/core/ecosystem` existed; it
-is kept because the stability argument that produced it is still true and still
-constrains what the subpaths may promise. What changed is the mechanism.
-
-## What holds now
-
-Every name lives on the subpath that owns the module it comes from, and every
-import carries that subpath: `@pikku/core/http`, `@pikku/core/services`,
-`@pikku/core/errors`, `@pikku/core/types`. There is no second specifier for the
-same module and no package root — `.` resolves to a bootstrap shim, not an entry
-point.
-
-The facades did not survive contact with their own premise. `ecosystem/http`
-re-exported `./http`, so a name was reachable through either door; every
-addition had to be made twice, they drifted (25 names had accumulated in the
-facade tier with no raw home, and about 26 more sat under a different area than
-the module they came from), and a consumer's import told you nothing about what
-it used. The package root was the same failure at a larger scale: 206 names in
-one barrel that no bundler could take apart.
-
-The stability distinction the split was built to express is now carried by
-`public-surface.json` and `api-report.md`, which pin what each entry point
-exports. Moving a symbol across an area boundary is still a visible diff; it
-just no longer requires a parallel tree of re-export files to be visible.
-
-One module survives at an old specifier and is not an entry point:
-`bootstrap-compat/root.ts` exists because `packages/cli` is generated by the
-published CLI pinned in its `build.sh`, which still emits a bare `@pikku/core`.
-The matching `bootstrap-compat/ecosystem.ts` has already gone, along with every
-`@pikku/core/ecosystem` import in the repo — a guard test now fails if one comes
-back. A test pins the root shim's exact contents so it cannot grow, and it goes
-when the pin moves to a CLI released from this branch.
-
-**What this rules out:** re-introducing any specifier that re-exports another
-subpath's names. A curated facade over a module that is already published is the
-thing that was tried; adding a name to two places is how it decays.
-
-## Why the split existed (superseded)
-
-`@pikku/core` has two kinds of consumer. An **application** writes functions and
-wires them: `pikkuFunc`, `wireHTTP`, `PikkuWire`, the error catalogue. A
-**runtime adapter** — the express, fastify, uWS, Next, Cloudflare and Lambda
-packages, plus tests — reaches past that to drive the runner itself.
-
-Those two surfaces have measurably different stability. Over the nine months
-since `PikkuWire` was introduced, its app-facing shape took 22 additions and
-**zero removals** — every original field is still there. Over the same period
-`runPikkuFunc` was reshaped: `allServices`/`getAllServices` became
-`singletonServices`/`createWireServices`, the positional arguments became a
-`wireType`/`wireId` pair plus an options object, and `session` became `auth`.
-
-Both were exported from the package root. A compatibility promise made there
-would therefore have been a promise about the weaker of the two.
-
-So the adapter surface moved to `@pikku/core/ecosystem`: `runPikkuFunc`, the
-singleton-service accessors, and the registration calls the code generator emits
-— `addFunction`, `addGlobalMiddleware`, `addMiddleware` — alongside `pikkuState`
-and `httpRouter`, which were already separated for the same reason. The wire
-runners (`runQueueJob`, `runScheduledTask`, `runCLICommand`, `runMCP*`) left the
-root too, but for a different reason: they already lived on their wire subpaths,
-which is where every runtime package imports them from, so the root copies were
-redundant. 108 runtime exports became 95.
-
-**The name took two attempts.** Not `/internal`: the generated bootstrap
-imports from here, so the specifier appears in the user's own `.pikku`
-directory, and telling someone they are touching internals when the code
-generator put it there is both wrong and self-defeating — it could never be
-broken anyway. Not `/runtime` either: that reads as runtime-versus-compile-time,
-i.e. _the real API_, which is the opposite of the intended signal, and
-`packages/runtimes/*` already claims the word while `packages/cli` is the
-largest consumer here at 22 files.
-
-`/ecosystem` said the true thing: you are building a package in the Pikku
-ecosystem — a runtime, a service, an addon, the CLI.

package/knowledge/decisions/internals/the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: The embedding model is pinned per service and doc/query embedding is split
-description: AIEmbeddingService fixes its model at construction so index and query share a vector space, and separates embedDocuments from embedQuery for asymmetric models
-tags: services
----
-
-# The embedding model is pinned per service and doc/query embedding is split
-
-`AIEmbeddingService` (`packages/core/src/services/ai-embedding-service.ts`) is a
-deliberately narrow interface with two properties that look like restrictions.
-The model is `readonly` and fixed at construction rather than passed per call,
-and documents and queries go through separate methods.
-
-Both are about comparability. Vector stores (Qdrant, Pinecone, pgvector) embed at
-index time and again at query time; if those two moments can name different
-models they end up in different vector spaces, and similarity search does not
-error — it silently returns nonsense. Pinning the model to the service makes the
-drift unrepresentable. The split methods exist because several embedding models
-are asymmetric and must know which side they are embedding to produce comparable
-vectors: Cohere's `input_type`, E5's `query:` / `passage:` prefixes, BGE's query
-instruction. Symmetric providers such as OpenAI simply point both methods at the
-same call.
-
-**What this rules out:** adding a per-call `model` parameter, collapsing
-`embedDocuments` and `embedQuery` into one `embed`, and pointing a vector store
-at `AgentRunnerService.embed` / `embedMany` instead — those take a per-call
-model on purpose and drag in the whole agent-runner tool loop, and they give back
-neither guarantee.

package/knowledge/decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: The in-memory workflow service is inline-only and single-process
-description: InMemoryWorkflowService wires no queues and implements withRunLease/withStepLock as pass-throughs, because inline execution has no second holder to exclude
-tags: services
----
-
-# The in-memory workflow service is inline-only and single-process
-
-`InMemoryWorkflowService` (`packages/core/src/services/in-memory-workflow-service.ts`)
-calls `super({ ...options, wireQueues: false })` and implements `withRunLease` and
-`withStepLock` as bare `return fn()`. Both look like unfinished work and neither
-is.
-
-Every step runs inline in the process that started the run: there are no queue
-workers, so no other worker can be mid-step on the same run, and all state lives
-in this instance's `Map`s, so no other process can see it to contend for it. A
-lock would be excluding a competitor that cannot exist. It is offered for CLI
-tools that want step orchestration, for tests, and for single-process apps that
-do not need persistence — and the run state is unbounded and lost on restart,
-which is the price of that.
-
-**What this rules out:** treating the no-op locks as a bug and adding real
-locking here, and running this service anywhere a second process or a queue
-worker could touch the same run. A deployment that needs either wants a
-persistent `WorkflowService` implementation instead; there is nothing to fix in
-this one.

package/knowledge/decisions/internals/the-kek-salt-is-scoped-to-the-key-version.md

@@ -1,40 +0,0 @@
----
-type: decision
-title: The KEK salt is scoped to the key version, not the secret
-description: One stored salt per key version means N secrets cost one derivation, which is the point of envelope encryption
-tags: crypto, storage
----
-
-# The KEK salt is scoped to the key version, not the secret
-
-Each secret and credential service stores one random salt per `keyVersion`,
-generated on first use and read once — a `secretKekSalts` / `credentialKekSalts`
-table for kysely, a hash field for redis, a document for mongodb. `deriveKEK`
-runs against that salt to produce a `CryptoKey`, which is what
-`wrapDEK`/`unwrapDEK`/`envelope*` accept. The wrapped-DEK blob therefore carries
-no salt of its own: `[iv:12][ct+tag]`.
-
-Envelope encryption exists so the expensive derivation happens once and many
-cheap DEK unwraps follow. A per-secret salt destroys that: every
-`envelopeDecrypt` re-derives, so `getSecrets` over 50 rows cost 50 × PBKDF2-600k
-(~2.3s) and rotation cost twice that. Scoping the salt to the key version
-restored the intended shape — one derivation for a bulk read, two for a
-rotation.
-
-Keying by version rather than storing a single salt is what lets `getKEK` keep
-serving `previousKey` for older rows during rotation.
-
-A salt's job is to defeat precomputation across deployments and passphrases; one
-random salt per deployment per key version achieves that fully. Per-ciphertext
-salt only buys something when each ciphertext might use a different passphrase,
-which is never the case here. Storing the salt rather than taking it as
-configuration keeps it off the operator's plate — it needs to be
-deployment-random, not secret.
-
-**What this rules out:** deriving the KEK inside a per-row loop; a salt shared
-across key versions, which would break rotation; a deterministic salt derived
-from the version number, which is the same salt in every deployment and so
-restores the rainbow table; and caching derived keys anywhere but a read-through
-instance map whose source of truth is the store.
-
-See [[passphrases-are-stretched-key-material-is-expanded]].

package/knowledge/decisions/internals/the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: The MCP handshake is challenged only when every target is gated
-description: A client decides whether a server speaks OAuth from the handshake alone, so a fully-gated server that answers initialize with a 200 is detected as needing no sign-in
-tags: [mcp, auth, oauth]
----
-
-# The MCP handshake is challenged only when every target is gated
-
-`requestNeedsCredentials` challenges `initialize` when
-`mcpEveryTargetRequiresSession()` is true, and only then.
-
-A client decides at connection time whether a server speaks OAuth, and the only
-thing it can decide from is whether the handshake came back `401` with a
-`WWW-Authenticate` header naming the resource metadata. A server that answers
-`initialize` with a `200` and then `401`s every single tool call has told the
-client "no sign-in needed" and then refused it everything. That is how a fully
-gated server ends up shown as open, with no way for the user to sign in — the
-client never offers the option, because it was told there was nothing to offer.
-
-The condition is deliberately all-or-nothing. A server with even one open target
-genuinely is usable anonymously, and challenging its handshake would lock out
-clients that have no credentials to offer at all. An empty registry is not "all
-gated" either: there is nothing there to gate, so the handshake stays open.
-
-**What this rules out:** challenging the handshake whenever _any_ target needs a
-session. The handshake is not the place to express per-target policy — the
-per-target `401` already does that, and a client that has been let in can act on
-it. The handshake only answers "is there a sign-in here at all".