@pikku/core 0.12.143 → 0.12.145

package/knowledge/decisions/internals/the-middleware-resolution-cache-is-deliberately-unbounded.md

@@ -1,40 +0,0 @@
----
-type: decision
-title: The middleware resolution cache is deliberately unbounded
-description: Its keyspace is the set of registered wires, not request traffic, and middleware is dynamic — so eviction would buy nothing and cost the dedupe guarantee
-tags: core, middleware
----
-
-# The middleware resolution cache is deliberately unbounded
-
-`middlewareCache` in `packages/core/src/middleware-runner.ts` is a plain
-`Record<PikkuWiringTypes, Record<string, readonly CorePikkuMiddleware[]>>` with
-no size limit and no eviction. That reads like an unbounded-growth bug and is
-not one.
-
-**The keyspace is finite by construction.** The cache is keyed by wire type and
-wire id, and wire ids come from registration, not from traffic — an HTTP route
-pattern, a channel name, a queue name. A million requests to the same route
-produce one entry. Nothing a caller sends creates a key: a channel message key
-is `${channel}:${routingProperty}:${routerValue}`, and `routerValue` is only
-reached after matching `routes[routerValue]`, so an unregistered value never
-gets that far.
-
-**Middleware is dynamic, and the cache is invalidated rather than aged out.**
-`addGlobalMiddleware` and `addTagMiddleware` can run after startup, and dev
-hot-reload rewires wholesale — so correctness comes from `clearMiddlewareCache()`
-at the points where the middleware set actually changes, not from entries
-expiring. An LRU would evict entries that are still current while doing nothing
-about entries that are stale.
-
-**Eviction would also weaken the chain itself.** `combineMiddleware` returns a
-`freezeDedupe`d array, and dedupe is by function identity — a middleware
-reachable through both a tag group and a direct wire registration runs exactly
-once. Callers hold that array. Recomputing it under memory pressure hands out a
-second array for the same wire, which is churn at best and, for anything
-comparing chains by identity, a silent behaviour change.
-
-**What this rules out:** adding a `MIDDLEWARE_CACHE_MAX` with LRU eviction as a
-denial-of-service mitigation. There is no traffic-driven growth to mitigate. If
-a future change ever keys this cache by something a caller controls, that is the
-bug — bound the key, not the cache.

package/knowledge/decisions/internals/the-per-invocation-rpc-view-is-a-class.md

@@ -1,40 +0,0 @@
----
-type: decision
-title: The per-invocation rpc view is a class, because an object literal with a getter is slow to build
-description: An accessor declared on an object literal is defined per instance, which drops the literal off V8's fast construction path — measured at 1.15µs against 0.47µs, on every request
-tags: core, rpc, performance
----
-
-# The per-invocation rpc view is a class
-
-`getContextRPCService` builds `wire.rpc` once per invocation. It used to return
-an object literal, and that literal declared `get agent()` so the agent facade
-stayed lazy — most requests never touch it, and reading it builds five closures.
-
-The laziness is right. Declaring the accessor _on the literal_ was not: a
-literal containing an accessor needs a real property descriptor per instance,
-which takes it off V8's fast object-literal construction path and slows the
-whole object, not just the accessor.
-
-Measured with `benchmarks/bench-profile-granular.ts`, three runs each:
-
-| shape                               | per call                 |
-| ----------------------------------- | ------------------------ |
-| object literal with `get agent()`   | 1.106 / 1.433 / 1.147 µs |
-| class with `agent` on the prototype | 0.523 / 0.461 / 0.525 µs |
-
-Roughly 2.4×, well outside the run-to-run variance, on a path every request
-takes. On the same machine a full `fetchData` measures 12–19µs, so this was on
-the order of a tenth of a request spent constructing one object.
-
-The obvious alternative is worse. Making `agent` an eager property removes the
-accessor but builds those five closures unconditionally, and measured _slower_
-than the original at 1.967µs. A prototype accessor is the only shape that keeps
-the laziness and the fast construction path.
-
-**What this rules out:** "simplifying" `ContextRPCView` back to an object
-literal. It reads as the plainer option and costs double. It also rules out
-trusting a synthetic microbenchmark here — a standalone benchmark of these
-shapes pointed at the eager version, because its stand-in for the agent getter
-was too cheap to represent the real one. The numbers above come from the
-profiler running the real code.

package/knowledge/decisions/internals/the-pikku-user-id-resolves-in-a-fixed-order.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: The pikku user id resolves in a fixed order
-description: defaultPikkuUserIdResolver takes an explicit pikkuUserId first, then the session userId, then the queue job's id, then the workflow's id
-tags: core, identity
----
-
-# The pikku user id resolves in a fixed order
-
-`defaultPikkuUserIdResolver` in `packages/core/src/services/pikku-user-id.ts:5-12`
-returns the first of these that is set:
-
-1. `wire.pikkuUserId` (`:6`);
-2. `wire.session.userId`, when it is a string (`:7-9`);
-3. `wire.queue.pikkuUserId` (`:10`);
-4. `wire.workflow.pikkuUserId` (`:11`).
-
-Otherwise it returns `undefined` (`:12`).
-
-The queue case is about the producer's identity carried on a job, and is covered in
-`queue-job-identities-are-signed-at-enqueue.md`. This note records only the order.
-
-**What this rules out:** a session user id overriding an explicit `pikkuUserId` set
-on the wire, and a queue or workflow id outranking a live session.

package/knowledge/decisions/internals/the-runner-resolves-wire-services-itself.md

@@ -1,31 +0,0 @@
----
-type: decision
-title: The function runner resolves wire services itself
-description: A function's wire services come from its own package's factory or the app's registered one, never borrowed from whoever called it
-tags: core
----
-
-# The function runner resolves wire services itself
-
-`runPikkuFunc` picks the wire-services factory for the function it is about to
-run: the function's addon package factory if it has one, else a factory the
-transport passed explicitly, else the app's registered one
-(`getCreateWireServices()`). A caller that passes nothing still gets the
-function its wire services.
-
-Before this, only the transports passed a factory. `rpc.invoke`, `rpc.exposed`,
-gateway handlers and webhook sources passed none, so an app function reached
-through them ran on whatever services its caller had already merged. That held
-until `singletonServicesOnly` let a caller skip building wire services: the
-generated `rpcCaller` behind `/rpc/:rpcName` reads no service, was marked, and
-every app function behind it lost `events` and every other wire service. Nested
-RPC therefore gets `resolvedSingletonServices`, not the caller's merged set.
-
-Channels are the one caller that legitimately shares wire services: they build
-one set per connection. They hand it over as `wireServices`, which the runner
-uses as-is and does not close, because the connection owns its lifetime.
-
-**What this rules out:** passing a caller's merged services down as
-`singletonServices` to carry wire services into a nested call, and deciding in
-one function's meta whether a different function gets wire services.
-`singletonServicesOnly` only ever describes the function it is set on.

package/knowledge/decisions/internals/the-schema-service-is-never-stubbed.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: The schema service is never stubbed, or tests validate nothing
-description: createStubProxy returns undefined for the schema property so the real schema service is built — a stubbed one turns validation into a silent no-op
-tags: services
----
-
-# The schema service is never stubbed, or tests validate nothing
-
-`createStubProxy` (`packages/core/src/services/stub-tracker.ts`) is passed as
-`existingServices` to `createSingletonServices`, and its proxy answers every
-property with `tracker.stub(prop)` — every property except `schema`, which
-returns `undefined` so the service factory goes on to construct a real schema
-service.
-
-A stub's methods resolve `undefined` and record the call. Applied to
-`validateSchema`, that means validation always "passes": a request missing a
-required field, or carrying a wrong type, sails through. Every scenario that
-believed it was exercising input validation would be asserting on nothing, and
-would keep passing after validation broke. The one-line exception in the proxy is
-what keeps the test suite honest.
-
-**What this rules out:** simplifying the `get` trap to `return tracker.stub(prop)`
-for all properties, and adding `schema` to any list of services a scenario is
-allowed to fake. If a scenario needs schema behaviour changed, change the schema,
-not the service.

package/knowledge/decisions/internals/the-transcript-event-is-sent-ahead-of-the-run.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: A voice turn's transcript is sent before the run starts, on the raw channel
-description: The client does not know what it said, and an answer starts streaming within a few hundred milliseconds — a question arriving after its answer reads as the wrong question
-tags: core, agent
----
-
-# A voice turn's transcript is sent ahead of the run
-
-A voice client sends audio, so it does not know what it said. Until the
-transcript reaches it, its own message renders as a blank bubble.
-
-The event is sent _before_ the run rather than alongside it because the answer
-begins streaming within a few hundred milliseconds. Sent concurrently, the
-transcript routinely lands after the first tokens of its own answer — and a
-question that appears beneath its answer reads as a question about something
-else entirely.
-
-It goes on the raw channel rather than through the stream middleware because it
-is not part of the reply: it is what the user said, and the stream hooks are
-built to transform what the agent says.
-
-**What this rules out:** folding the transcript into the run's event stream for
-uniformity. Ordering is the whole point, and the stream is where ordering is
-least under this code's control.

package/knowledge/decisions/internals/the-virtual-user-catalogue-is-the-only-gate-on-what-may-be-called.md

@@ -1,21 +0,0 @@
----
-type: decision
-title: The catalogue is the only gate on what a virtual user may call
-description: Narrowing happens once at derivation, so there is no second check in the run loop that could drift out of step with it
-tags: core, virtual-user
----
-
-# The catalogue is the only gate on what a virtual user may call
-
-What a virtual user may invoke is decided once, when the catalogue is narrowed
-for its disposition: a read-only disposition is never offered a mutation, and an
-approval-gated endpoint is never offered at all.
-
-The run loop then indexes into that catalogue and calls what it finds. There is
-deliberately no second permission check at call time, because a second check is
-a second thing to keep correct — and the failure mode of the two disagreeing is
-that one of them silently stops mattering.
-
-**What this rules out:** adding a "defence in depth" guard in the run loop. It
-would not be defence in depth; it would be a duplicate of the derivation rules,
-maintained separately, and the one that runs first wins.

package/knowledge/decisions/internals/the-virtual-user-prompt-says-json-because-of-json-object-mode.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: The virtual user's instructions say the word "json" because a degraded gateway demands it
-description: A gateway that cannot take a JSON schema falls back to OpenAI's json_object mode, which refuses any request whose prompt does not contain the word
-tags: core, virtual-user-conversation
----
-
-# The virtual user's instructions say the word "json"
-
-Every call the virtual user makes wants a schema'd object back. A gateway that cannot
-accept a JSON _schema_ degrades to OpenAI's `json_object` response mode, and
-that mode refuses the request outright — a hard API error, not a bad answer —
-unless the literal word "json" appears somewhere in the prompt.
-
-The word is therefore in the shared instruction block, once. All three call
-sites (turn, approvals, verdict) build on that block, so one mention covers
-them, and it costs nothing on providers that never needed telling.
-
-**What this rules out:** tidying the instructions by removing a word that reads
-as redundant. It is load-bearing for exactly one provider configuration, and its
-absence fails the request rather than degrading the output — so the failure will
-not look like a prompt problem.

package/knowledge/decisions/internals/the-virtual-user-runtime-is-exported-from-the-virtual-user-entry-point.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: The virtual user runtime is exported from @pikku/core/virtual-user, never from services
-description: Those values reach the conversation and agent runners, which no production server runs — and an unbundled deploy loads whatever the import graph names
-tags: core, services
----
-
-# The virtual user runtime lives on `@pikku/core/virtual-user`
-
-`HttpVirtualUser`, `createHttpVirtualUsers`, `readScenarioHttpResponse` and
-`postScenarioJson` are exported from `@pikku/core/virtual-user`, not from
-`@pikku/core/services`. Their _types_ are re-exported freely — TypeScript erases
-those and they cost a bundle nothing.
-
-The values are different. They reach `http-virtual-users`, which reaches the
-conversation runner, which reaches the agent runner: an entire
-scenario and virtual-user runtime that no production server executes. An
-unbundled Node or Lambda deploy does no tree-shaking — it loads whatever the
-import graph names — so exporting one value from the services barrel pulls all
-of it into every application that imports a service.
-
-This is enforced, not merely intended: `production-barrels-stay-lean.test.ts`
-walks the value-import graph from `services/index.ts` and
-`wirings/workflow/index.ts` and fails if any of those modules is reachable.
-
-**What this rules out:** re-exporting a virtual user value from the services barrel
-for convenience, and "just one small helper" — the graph is transitive, and one
-value is enough to pull the whole runtime.

package/knowledge/decisions/internals/the-worker-disposition-is-the-one-that-is-not-testing.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: The worker disposition is the only one not testing anything
-description: It is doing the job, so it abandons rarely, runs cool, and is told to stop and say so rather than guess
-tags: core, virtual-user
----
-
-# The worker disposition is the only one not testing anything
-
-Every other disposition exists to probe the product. The worker exists to _use_
-it, which changes every parameter: it abandons rarely, runs at a low temperature,
-and is instructed to stop and report rather than guess its way past an obstacle.
-
-The failure mode being guarded against is different too. For the probing
-dispositions the risk is a missed bug. For this one it is a wrong action nobody
-asked for — a real mutation performed because the model improvised when it
-should have stopped.
-
-**What this rules out:** tuning this disposition toward the others for
-consistency, in particular raising its temperature or its tolerance for
-guessing. Those settings are what make the others useful and what would make this
-one dangerous.

package/knowledge/decisions/internals/thread-history-records-the-transcript-not-the-audio.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: Thread history records what the model was asked, which for a spoken turn is the transcript
-description: The wire carried a base64 audio blob; persisting it writes megabytes of unreadable data and loses the only readable record of the turn
-tags: core, agent
----
-
-# Thread history records the transcript, not the audio that arrived
-
-What goes into thread history is what the model was actually asked. For a typed
-turn that is what arrived over the wire. For a spoken turn it is not: the wire
-carried a base64 audio blob, and `voiceInput` replaced it with a transcript
-before the model ever saw it.
-
-Persisting the blob would write megabytes of unreadable data into the history
-_and_ discard the only readable record of what was said — the worst of both.
-
-Both the streaming and non-streaming paths do this, and both check identity
-rather than assuming: a middleware is free to rewrite the message list into
-something with no relation to this turn, and in that case there is no transcript
-to substitute and the list is persisted as-is.
-
-**What this rules out:** persisting the inbound message verbatim on the grounds
-that it is the ground truth. For voice it is the least useful representation
-available, and the substitution is exactly what makes the history readable.

package/knowledge/decisions/internals/trigger-declaration-is-split-from-trigger-source.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: Trigger declaration is split from trigger source
-description: Triggers are declared everywhere but subscribed only in the trigger worker, so app processes never open the underlying subscription
-tags: trigger
----
-
-# Trigger declaration is split from trigger source
-
-`wireTrigger` and `wireTriggerSource` in
-`packages/core/src/wirings/trigger/trigger-runner.ts` are deliberately two
-separate registrations for the same trigger name. `wireTrigger` declares the
-trigger name and the target pikku function; it is meant to be loaded by every
-process, because the inspector extracts it at build time and every runtime needs
-the name-to-function mapping in `pikkuState(null, 'trigger', 'meta')`.
-`wireTriggerSource` carries the actual subscription implementation
-(`CorePikkuTriggerFunction`, which opens the connection and returns a teardown)
-and is only imported by the trigger worker process.
-
-The split exists because the subscription has side effects at import-and-setup
-time — a Redis `subscribe`, a socket, a poller. If every API instance loaded the
-source, every instance would open its own subscription and the trigger would fire
-once per instance instead of once per event. Keeping the source out of the
-general bundle also keeps the trigger's transport dependency out of runtimes that
-never need it. `CoreTriggerSource.name` must therefore match a `wireTrigger`
-name exactly; nothing in the type system enforces that, and a mismatch shows up
-only at `setupTrigger` time as `Trigger source not found`.
-
-**What this rules out:** merging `wireTrigger` and `wireTriggerSource` into one
-registration call, re-exporting trigger sources from a package barrel that
-application code imports, or "simplifying" by having `wireTrigger` accept the
-subscription function directly. Any of these pulls the subscription into every
-process and silently multiplies trigger firings by the instance count.

package/knowledge/decisions/internals/typed-secret-service-caches-for-the-process-lifetime.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: TypedSecretService caches for the process lifetime
-description: Resolved secrets are cached with no TTL, so a secret rotated out of band is not picked up until restart — tracked as pikkujs/pikku#964
-tags: services
----
-
-# TypedSecretService caches for the process lifetime
-
-`TypedSecretService` (`packages/core/src/services/typed-secret-service.ts`) keeps
-an in-process `Map` of resolved secrets so callers can read naively without
-hitting the underlying secret service on every call. Only successful reads are
-cached — a miss throws and is not stored, so the cache never memoises a negative
-— and `setSecret` / `deleteSecret` invalidate the key they touch.
-
-There is no TTL and no background refresh. One instance is created per
-`createSingletonServices`, which in practice means once per process, so a secret
-rotated out of band is not observed until the process restarts. That is a known
-gap, tracked as pikkujs/pikku#964, not an oversight to rediscover.
-
-**What this rules out:** assuming a rotation flow that writes to the secret
-backend takes effect in a running instance — it does not; the deployment has to
-cycle. It also means this cache is not a read-through cache in the usual sense,
-so do not "fix" it by caching misses. Related: the cached values are plaintext
-secrets held on the long-lived singleton services object, which is why a batch
-`getSecrets([...everything])` should be avoided.

package/knowledge/decisions/internals/validate-checks-virtual-users-through-a-shared-module.md

@@ -1,43 +0,0 @@
----
-type: decision
-title: Both validators check virtual users through one shared module, and a virtual user counts from either the meta or the source
-description: workspace validate and cloud validate are separate implementations, so the virtual user/virtual-user/knowledge checks live in virtual-user-checks.ts and are called by both — and a virtual user is counted from the generated meta or a defineVirtualUsers() source scan, whichever answers first
-tags: cli, validate, scenarios, virtual users
----
-
-# Both validators check virtual users through one shared module, and a virtual user counts from either the meta or the source
-
-`pikku workspace validate` and `pikku validate` read like one command
-with a flag. They are not. They are two implementations that walk the same
-project and duplicate about eighteen findings between them verbatim —
-`functions-dir-missing` exists twice, character for character, in two files.
-Pikku Studio Cloud adds the deploy-shaped checks (themes, frontends, the Cloudflare
-adapter, the `.gitignore` contract); workspace adds the local-development ones
-(`dev.db`, the auth migrations).
-
-So a check written into either one is a check half the projects never run. An
-app that never deploys through cloud only ever sees workspace validate; an app
-that does sees cloud validate in CI. The virtual user checks are the kind that only
-pay off when nobody remembers to ask for them, which means they had to be in
-both. Rather than duplicate them a nineteenth time, they live in
-`virtual-user-checks.ts` and both validators call `runVirtualUserChecks`. Merging the
-two validators outright is the better fix and a much larger one; this does not
-block it.
-
-**A virtual user counts from either source, and either alone is wrong at a
-predictable moment.** The generated `pikku-virtual-users-meta.gen.json` is empty on
-a fresh clone where codegen has not run, so trusting only it means a warning
-that fires on every new checkout — and a validator that cries wolf gets muted,
-after which it never says anything worth hearing. A source scan for
-`defineVirtualUsers(` cannot see virtual users an addon contributed. Declared by either
-counts as declared.
-
-**Everything here is `warn`, never `error`.** A project with no virtual users is
-under-tested, not broken, and `validate` gating a deploy on it would make the
-first thing anyone does with the check be to remove it. `knowledge-empty` stays
-at the `info` the shared `@pikku/knowledge` package already assigned it rather
-than being raised to match — the severity belongs to that package.
-
-**What this rules out:** duplicating the checks into both validators;
-adding them to only one; deriving the virtual user count from the generated meta
-alone; failing a build over a missing virtual user.

package/knowledge/decisions/internals/validate-runs-checks-by-precondition.md

@@ -1,115 +0,0 @@
----
-type: decision
-title: pikku validate runs every applicable check, it does not detect a project kind
-description: one `pikku validate` replaces `pikku workspace validate`; checks declare a precondition and run wherever it holds, because the repos that matter are an app and a pile of addons at the same time
-tags: cli, validate, addons
----
-
-# pikku validate runs every applicable check, it does not detect a project kind
-
-`pikku workspace validate` was named after one of the things a repo can be.
-Adding a second — "is this addon publishable" — invited a second command,
-`pikku addon validate`, and that is where the naming falls apart: the addons
-repo is a workspace _containing_ 217 publishable addons. Standing at its root,
-`pikku addon validate` would have to refuse or sweep every package, at which
-point it is doing the workspace thing anyway. The two nouns were never
-alternatives.
-
-So there is one command, and it does not detect a kind and dispatch. Each check
-declares the condition under which it means anything, and runs wherever that
-condition holds:
-
-- `app-project` — a `pikku.config.json` with no `types/application-types.d.ts`
-  beside it. The marker matters: an addon carries a `pikku.config.json` too, and
-  the app-shaped checks would report every app convention it has no reason to
-  follow, starting with a `packages/functions/` it will never have.
-- `addon-package` — a non-private package that ships generated pikku output.
-  Having a `.pikku` directory is not enough on its own: an app's
-  `packages/functions` has one, and it is codegen for that app rather than
-  something anyone installs. The signal is a `files`/`exports` that carries it
-  into the tarball.
-
-Detection-as-dispatch fails on the first repo that is two things at once.
-Detection-as-precondition composes: the addons repo plans 217 addon checks and
-no app check; the online-shop template plans one app check and no addon check;
-a repo that is both plans both.
-
-## Targets come from walking, not from `workspaces`
-
-The field is an array in one repo and `{ packages: [...] }` in the next, spells
-the same layout as `packages/**` or as six explicit globs, and a package that is
-real but unlisted is exactly the kind of thing worth validating. So discovery
-walks the tree for `package.json` files and lets the preconditions decide.
-Over-collecting targets is free; guessing the glob dialect is not.
-
-## A run that checked nothing must not print a tick
-
-The failure mode of auto-detection is that finding nothing looks exactly like
-finding everything and liking it. When no check applies, the renderer says so
-and names what it looked for, rather than reporting success.
-
-## The check the addon case exists for
-
-Every relative import in a shipped generated file must resolve to a file that is
-itself shipped — stated as a property, not as "the build script must copy
-`types/`". The build script is not the only way to get this wrong and will not
-always be a `cp`; the generated files already declare what they need.
-
-That property was false in all 217 published addons. `cp -r .pikku dist/`
-shipped the generated output but not the `types/application-types.d.ts` it
-imports, and `tsc` never emits a hand-written `.d.ts` to `outDir`, so nothing
-put it in `dist`. Consumers got 8 unresolved-module errors plus 6
-`RequiredServices does not satisfy CoreSecretlessSingletonServices` follow-ons
-inside `node_modules`, for merely depending on an addon. The scaffold template
-had been right the whole time — `templates/function-addon` copies `types/` —
-and the published packages had drifted from it with nothing watching.
-
-## The check walks whichever generated directory a package ships
-
-`dist/.pikku` is the target shape (below), but the check cannot assume it: the
-shape is what this work moved addons _to_, and a package that has not moved —
-or was published before it did — still carries `.pikku` at the root, listed in
-`files` and mapped by `exports` as `./.pikku/*`. There it is a public entry
-point rather than build input, and its imports climb one level fewer — to
-`<pkg>/src` and `<pkg>/types` — where the copy under `dist` reaches
-`<pkg>/dist/src` and `<pkg>/dist/types`. Two roots, two ways to fall outside
-the tarball, so the check walks whichever ones are actually shipped rather than
-the one it would prefer to find.
-
-`exports` and `imports` get the same treatment one level up: a target outside
-the published file set is the same defect, and the one the import walk cannot
-see, because nothing inside `dist/.pikku` mentions it. That is how a `#pikku`
-still pointing at `./.pikku/pikku-types.gen.ts` hides.
-
-## An addon's entry points all resolve under dist
-
-Everything an installed package reaches for lives under `dist`; the addon's own
-build resolves `#pikku` through tsconfig `paths`, so nothing in `exports` or
-`imports` has to point into the source tree, and `files` is just `["dist"]`.
-The alternative — shipping `src/` and `types/` at the root so the existing paths
-resolve as written — publishes TypeScript source and a second copy of
-everything `dist` already has.
-
-Checking only `dist` is what let the root `.pikku` stay broken through the first
-round of fixes: in the published `@pikku/addon-assemblyai@0.1.4` tarball, `.pikku`
-ships `.gen.ts` files importing a `../../src/` and `../types/` that the tarball
-does not contain, and the `pikku-bootstrap.gen.js` that consumers import through
-that subpath exists only under `dist`. Everything resolved locally through the
-workspace link and none of it resolved on install.
-
-## Only a package that publishes gets the dist shape
-
-The shape describes a tarball, so it means nothing for a `private` package —
-and applying it there actively breaks: `exports` _is_ enforced across a
-workspace link, so repointing a private fixture at `dist` makes every consumer
-demand a directory that only a build produces. The three `verifiers/db-schema`
-and `verifiers/addon-registry` fixtures have no build script at all, so `dist`
-never exists for them; the five `e2e/packages` addons build, but their metadata
-is read straight from the source tree before any build has run. Repointing all
-eight left the db-schema verifier unable to resolve
-`dist/.pikku/db/pikku-db-meta.gen.json` and every e2e addon reporting "no
-function metadata".
-
-`isAddonPackage` already draws this line — it returns false for `private` — so
-the checks and the shape agree: a package the registry never sees is consumed
-from source.

package/knowledge/decisions/internals/virtual-user-conversation-drives-the-target-through-a-transport-seam.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: The conversation engine only sees a transport-agnostic target driver
-description: The engine never imports the agent runner; the target is injected as run/approve, so scenarios exercise the real wire path
-tags: virtual-user-conversation
----
-
-# The conversation engine only sees a transport-agnostic target driver
-
-`runConversation` reaches the target agent exclusively through the injected
-`TargetAgentDriver` — `run(message)` and `approve(runId, decisions)` — declared
-in `packages/core/src/wirings/virtual-user/conversation/conversation.types.ts`. In production that
-driver is HTTP-backed, issuing the virtual user's `agentRun` and `agentApprove` calls as
-the signed-in virtual user.
-
-Keeping the seam transport-agnostic is what makes the conversation a real test:
-the agent is exercised through the same authenticated wire path a user takes,
-including middleware, permissions and session handling, rather than through an
-in-process call that skips all of it. It also lets the engine be unit-tested
-against scripted targets with no server at all.
-
-**What this rules out:** calling `runAgent` / `streamAgent` directly from the
-conversation engine, and widening `TargetAgentDriver` with transport details
-(headers, cookies, channels) that would tie the engine to HTTP.

package/knowledge/decisions/internals/virtual-user-conversation-verdicts-are-llm-self-evaluations.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: A conversation verdict is the virtual user's self-evaluation, not an assertion
-description: The engine returns what the virtual user judged plus the transcript; deterministic checks stay with the caller
-tags: virtual-user-conversation
----
-
-# A conversation verdict is the virtual user's self-evaluation, not an assertion
-
-`runConversation` ends by asking the virtual user LLM whether the `evaluate`
-criterion was met and returns that as `ConversationVerdict` — `passed`, `reasoning`
-and the full `transcript`
-(`packages/core/src/wirings/virtual-user/conversation/`). Nothing in the engine inspects the
-system the agent acted on.
-
-The verdict is deliberately soft because the thing it judges is soft: whether a
-conversation accomplished a natural-language task. Deterministic checks — that a
-row was written, that an email went out — belong to the caller, which already
-holds the virtual user and can `virtualUser.invoke(...)` after the conversation returns. The
-`reasoning` and `transcript` fields exist so a soft failure is debuggable rather
-than merely red.
-
-**What this rules out:** having `runConversation` assert or throw on a failed
-verdict, and adding deterministic post-conditions to `ConverseOptions` instead of
-running them at the call site.

package/knowledge/decisions/internals/virtual-user-conversations-seed-a-hidden-kickoff-message.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: A virtual user conversation starts from a seeded kickoff message
-description: The virtual user's first turn needs a non-empty message list because providers reject an empty prompt; the seed is an instruction and stays out of the transcript
-tags: virtual-user-conversation
----
-
-# A virtual user conversation starts from a seeded kickoff message
-
-`runConversation` in
-`packages/core/src/wirings/virtual-user/conversation/run-conversation.ts` primes
-`virtualUserMessages` with a single user message telling the virtual user to begin, before
-the first turn is generated.
-
-The virtual user speaks first, so at that point there is nothing for it to reply to —
-and LLM providers reject a completion request with no messages. The seed is
-addressed to the virtual user rather than to the target agent, which is why it is never
-pushed onto `transcript`: it is scaffolding, not something the simulated user
-said, and including it would corrupt the transcript the final evaluation reads.
-
-**What this rules out:** starting from an empty `virtualUserMessages` array, folding
-the kickoff into the virtual user instructions where a provider may weight it
-differently, and pushing the seed into the transcript for symmetry.

package/knowledge/decisions/internals/virtual-user-step-order-comes-from-insertion-order.md

@@ -1,21 +0,0 @@
----
-type: decision
-title: A scenario's step order for a virtual user is insertion order, not a graph traversal
-description: The CLI writes nodes in declaration order, so following `next` would buy an ordering that is already true and cost a traversal that has to interpret branches
-tags: core, virtual-user
----
-
-# Step order comes from insertion order, not a graph traversal
-
-When a scenario becomes catalogue entries, its steps are read in the order the
-nodes appear — which is the order the CLI wrote them, which is the order the
-scenario declares them.
-
-Following `next` edges instead would produce the same ordering in the ordinary
-case, and in the branching case it would force a decision nobody needs: which
-arm of a branch to present to a reader who will never take one. The traversal
-costs work to reproduce a fact that already holds.
-
-**What this rules out:** "correcting" this to a topological walk because a graph
-is present. The graph describes execution; the catalogue describes what the
-scenario _says_, and those are read in declaration order.