@pikku/core 0.12.142 → 0.12.144

package/knowledge/decisions/internals/index.md

@@ -1,181 +0,0 @@
----
-type: overview
-title: Internals
-description: How core behaves — runtime constraints, execution semantics, and the shapes the API commits to
----
-
-# Internals
-
-A rule about how core behaves: what runs where, in what order, and what a
-caller is entitled to assume.
-
-<!-- pikku:knowledge-index -->
-- [A credential name declared twice must agree on its schema and its type](a-credential-name-declared-twice-must-agree-on-schema-and-type.md) — validateAndBuildCredentialDefinitionsMeta throws when two declarations of one credential name differ in schema or in type, and otherwise keeps the first declaration
-- [declareScopes lets an app grant a scope whose addon it does not wire](a-grant-can-name-a-scope-declared-without-its-addon.md) — defineScope is a no-op read by the CLI, and declareScopes declares scope ids so a grant is valid without wiring the addon that owns the scope tree
-- [A held run is woken later, not retried](a-held-run-is-woken-later-not-retried.md) — An orchestrator message that finds its run held enqueues a fresh wake-up a second later instead of failing, because the queue's retry budget is for real failures and a long pass outlasts it
-- [A non-streaming agent run registers with agentRunState on the same terms as a streaming one](a-non-streaming-agent-run-registers-with-agentrunstate-too.md) — Otherwise interruptAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
-- [With scenarios.reset on, the dev seed is the fixture every assertion is written against](a-reset-suite-makes-the-dev-seed-the-fixture.md) — The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
-- [A resumed turn is as interruptible as the first one](a-resumed-agent-turn-is-as-interruptible-as-the-first.md) — It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
-- [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
-- [A scheduled task writes its caller's session to the session store before it runs](a-scheduled-task-writes-its-caller-session-before-it-runs.md) — runScheduledTask stores the session it is passed, or nothing, before it looks up the task, so the run uses only a session its caller supplied
-- [A secret set in memory shadows the variable of the same name](a-secret-set-in-memory-shadows-the-variable-of-the-same-name.md) — LocalSecretService reads its in-memory map before the variables service, stores a SecretValue unwrapped, and treats an empty string as absent
-- [A secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
-- [A virtual user acts through invokeRaw, so a refusal is data it can act on](a-virtual-user-acts-through-invokeraw-so-a-refusal-is-data.md) — virtualUserTarget calls virtualUser.invokeRaw, which signs the virtual user in when needed, retries once after a 401, and returns the status instead of throwing
-- [A virtual user cadence is a row, not a timer](a-virtual-user-cadence-is-a-row-not-a-timer.md) — How often a virtual user runs is stored as a due time per virtual user and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
-- [A virtual user's converse signs in before its first turn](a-virtual-user-converse-signs-in-before-its-first-turn.md) — HttpVirtualUser.converse calls login() before a run when it holds no session, because a public agent route never triggers the 401 retry that would sign the virtual user in
-- [A virtual user decides whether to trust its notes once per turn, by one roll](a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md) — The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
-- [A virtual user's email is computed from its id, with the run id as a sub-address](a-virtual-user-email-is-computed-with-the-run-id-as-a-sub-address.md) — virtualUserEmail derives the address from the virtual user id and a real domain, appends the run id so concurrent runs get separate inboxes and accounts, and refuses colliding addresses
-- [A virtual user run is not a workflow, but it needs a trigger](a-virtual-user-run-is-not-a-workflow-but-it-needs-a-trigger.md) — runVirtualUser writes its record and dispatches the run onto a queue at one attempt — an exploratory run has nothing to replay, but a deployment that puts each function in its own unit has nothing to fire it either
-- [A wall-clock threshold is a load test in disguise](a-wall-clock-threshold-is-a-load-test-in-disguise.md) — The KEK derivation test asserted a fixed 50ms budget for work that took 10ms, which went red about one run in five once the suite was large enough to compete for the machine
-- [A workflow's wire is built from the run record, not from the RPC service](a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md) — The RPC service exposes no wire, so every rpcService.wire read was undefined; the run record is the only thing that carries the caller across a step boundary
-- [Addon package roots resolve by walking node module search paths](addon-package-roots-resolve-by-walking-node-module-search-paths.md) — LocalMetaService finds an addon's directory by scanning resolve.paths, not by require.resolve, because addon packages expose no main entry
-- [An addon's .pikku meta ships at the package root or under dist, and readers probe both](addon-pikku-meta-ships-at-the-package-root-or-under-dist.md) — The layout depends on the addon's build and files field, so a consumer resolving the directory by path must try `<pkg>/.pikku` and `<pkg>/dist/.pikku` before concluding an addon declares nothing
-- [Addon singleton services are cached per namespace, not per package](addon-singleton-services-are-cached-per-namespace-not-per-package.md) — Each wireAddon instance gets its own services built from its own overrides, at the cost of one service graph per wired instance
-- [Bare workflow names from inside an addon are prefixed with the consumer's namespace](addon-workflow-names-are-prefixed-with-the-consumer-namespace.md) — The addon's workflowService is proxied so an addon never has to hardcode the name its consumer chose
-- [The AG-UI bridge obeys the client's event-ordering contract exactly](agent-agui-bridge-obeys-the-client-ordering-contract.md) — RUN_STARTED opens lazily, RUN_FINISHED fires once on done, and step names are globally sequential — a violation makes the client drop the whole stream
-- [Audio chunks are labelled with the format the provider actually returned](agent-audio-chunks-carry-the-format-the-provider-returned.md) — The configured format is only a request, so the response's own format wins with the request and pcm16 as fallbacks
-- [Loading agent context waits for a tool result that may still be landing](agent-context-waits-for-a-tool-result-still-being-written.md) — An interrupted run's tool can still be writing to the thread, and in voice the next turn arrives within seconds — soon enough to load context missing what it is about to be asked about
-- [A credential-required tool result never reaches the client or the transcript](agent-credential-suspensions-hide-the-tool-result.md) — The run suspends with credential-request events instead, leaving the tool call unresulted so it can be resumed after connecting
-- [Delegate mode hides the parent's later text, supervise mode hides the sub-agent's](agent-delegate-and-supervise-hide-different-text.md) — Exactly one voice reaches the client per agent-mode; approvals and tool events always flow through either way
-- [Nulls are stripped from approved tool arguments before execution](agent-llm-tool-arguments-have-nulls-stripped.md) — LLMs emit null for optional fields where the schema layer expects undefined, so a resumed tool call is cleaned recursively first
-- [Model resolution stays a single seam even though it is currently a passthrough](agent-model-config-stays-a-single-resolution-seam.md) — resolveModelConfig looks removable but is the one merge point for per-request model overrides
-- [An agentMiddleware onError hook cannot change how a run fails](agent-onerror-hooks-cannot-change-the-failure.md) — Hook throws are swallowed so observability code can never convert, mask, or replace the original error
-- [AI runner methods must be called on the runner, never as detached references](agent-runner-methods-must-keep-their-receiver.md) — Implementations use this internally, so grabbing transcribe or generateSpeech as a bare function loses the receiver and throws at runtime
-- [Agent speech travels as a CUSTOM AG-UI event rather than being dropped](agent-speech-travels-as-a-custom-agui-event.md) — AG-UI has no speech event, and dropping it makes a voice agent reached over HTTP silently inaudible while the provider still bills for the audio
-- [Persisting an agent stream from send is best-effort and must never reject](agent-stream-persistence-is-best-effort.md) — The persisting channel flushes fire-and-forget because send is synchronous; a storage failure degrades the transcript instead of killing the process
-- [A delegated sub-agent inherits the parent run's context block](agent-sub-agents-inherit-the-parent-context-block.md) — The sub-agent tool schema carries only message and session, so the parent's identifier block is forwarded rather than re-typed by the model
-- [A tool's execute() failure is logged before the AI SDK swallows it](agent-tool-execute-failures-are-logged-unconditionally.md) — Every agent tool is wrapped in a logging try/catch, because a thrown tool error otherwise becomes a conversational reply and is invisible server-side
-- [Voice input transcribes audio parts sequentially and in place](agent-voice-input-transcribes-audio-parts-in-place.md) — Each audio part is replaced by its text where it sat, one at a time, bounding concurrent downloads and preserving content order
-- [Working memory is persisted only when the merged value validates](agent-working-memory-is-persisted-only-when-valid.md) — A failed schema check logs and drops the update rather than saving it, because invalid state poisons every later read
-- [An addon's scope root loses to a root the host app already declares](an-addon-scope-root-loses-to-a-root-the-host-already-declares.md) — loadAddonFunctionsMeta merges addon scope trees by root name, first declaration wins, so an addon sharing a root with its host contributes nothing — silently
-- [An interrupt is not a failure, and the non-streaming path throws rather than returning](an-agent-interrupt-is-not-a-failure.md) — It skips the onError hooks and never becomes an errorMessage; with no partial reply to hand back, a typed throw is what distinguishes it from a provider outage
-- [A reachable agent is offered by its registry key, filtered by the virtual user's scopes](an-agent-is-offered-under-its-registry-key-and-only-within-the-virtual-users-scopes.md) — reachableAgents offers an agent to a virtual user under the key it is registered with, and only when the virtual user holds the agent's declared scopes; the server still enforces access
-- [An interrupt for a run owned by another instance says so, rather than returning false](an-agent-run-owned-by-another-instance-says-so.md) — A bare false is indistinguishable from "already finished", which is the one deployment shape the in-process registry cannot cover
-- [A wrapped agent-stream send must return the inner send's promise](an-agent-stream-send-must-return-the-inner-sends-promise.md) — Middleware runs asynchronously, so dropping the returned promise turns every awaited channel.send upstream into a no-op
-- [A message with nothing to say carries no text part at all](an-empty-text-part-is-omitted-from-an-agent-message.md) — An attachment on its own is a real turn, and providers are entitled to reject an empty text part sitting beside it
-- [A transcript is recorded only when something was actually heard](an-empty-transcript-is-not-recorded.md) — Recording an empty string sends a transcript event saying the user said nothing, which renders as an empty bubble rather than a pending one
-- [An OAuth2 credential implies its app client secret, optional and overridable by declaration](an-oauth2-credential-implies-an-optional-app-secret.md) — deriveOAuth2AppSecrets creates the app client id and secret for each OAuth2 credential, marked optional, unless the project already declares that secret id
-- [An unref'd timer cannot be awaited under node:test](an-unref-d-timer-cannot-be-awaited-under-node-test.md) — The channel RPC registry unrefs its timeout so a pending call never holds a process open, which makes that timeout unawaitable in a test and silently cancels the rest of the file
-- [Analytics identity resolvers run in declared order so consent is read before a cookie is minted](analytics-identity-resolvers-run-in-declared-order.md) — composeAnalyticsIdentity threads each resolver's output into the next, so a cookie-minting resolver sees the consent that an earlier resolver read
-- [Channel message handlers accept three config shapes](channel-message-handlers-accept-three-config-shapes.md) — onMessage may be a function config, a wrapper with middleware, or a wrapper around a function config — the runtime discriminates structurally
-- [Channel middleware caching covers only statically resolved middleware](channel-middleware-caches-only-statically-resolved-middleware.md) — Inherited tag/named middleware is cached per uid; per-run closures are appended fresh every call, at the cost of re-allocating the array
-- [`getState<T>()` lets the caller name any type, so every implementation asserts](channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md) — The type parameter appears only in the return position with nothing to infer from, so it is a caller-chosen claim rather than a checked fact
-- [Channel state is per-socket, session state is per-user](channel-state-is-per-socket-session-state-is-per-user.md) — ChannelStore holds connection-scoped scratch data keyed by channelId, deliberately separate from the pikkuUserId-keyed SessionStore
-- [A channel's user id is persisted only after onConnect middleware has run](channel-user-id-is-persisted-after-onconnect-middleware-runs.md) — The channelId to pikkuUserId mapping is written post-onConnect, because auth middleware is what establishes the session
-- [CLI option names are camelCase in state and kebab-case on the command line](cli-option-names-are-camelcase-in-state-and-kebab-on-the-command-line.md) — Option keys match the function's input field names so they can be plucked by schema, and are converted to kebab only for display and parsing
-- [CLI parse errors are routed by message prefix](cli-parse-errors-are-routed-by-message-prefix.md) — The CLI runners decide between printing help and printing errors by string-matching the prefixes the parser writes, so those message strings are an interface
-- [CLI stdout is reserved for machine-readable output](cli-stdout-is-reserved-for-machine-readable-output.md) — The default renderer emits single-line NDJSON, diagnostics go to stderr, and --json only hijacks rendering for commands that declared a renderer
-- [CLI unknown long options warn instead of failing](cli-unknown-long-options-warn-instead-of-failing.md) — Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
-- [A column's at-rest form is an axis of its own](core-column-form-is-an-axis-of-its-own.md) — 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
-- [The data-classification brand is an optional property](core-data-classification-brand-is-an-optional-property.md) — Making __classification__ required would break ordinary Kysely operands, so the brand only constrains values flowing out
-- [The function runner restores the wire fields it overwrites](core-function-runner-restores-the-wire-fields-it-overwrites.md) — One wire object is reused across nested calls, so functionId, audit, addonNamespace and rpc are saved and put back in a finally
-- [Hot reload merges generated meta and never replaces it](core-hot-reload-merges-generated-meta-never-replaces-it.md) — Reloading codegen output must preserve runtime-registered meta, which no generated JSON contains
-- [Hot reload owns its module registry instead of re-importing](core-hot-reload-owns-its-module-registry.md) — Dev reload transpiles to CJS and runs modules through vm.compileFunction, because the native ESM loader map cannot be evicted
-- [Middleware order is resolution scope first, then priority](core-middleware-order-is-scope-then-priority.md) — Middleware is collected global to function, then stably sorted by priority, deduped, frozen and cached per wire
-- [Schema defaults are applied on every transport, not just HTTP](core-schema-defaults-apply-on-every-transport.md) — Defaults belong to the schema rather than the call's encoding, so they run unconditionally and are cloned per request
-- [Scopes are an AND gate, separate from permissions](core-scopes-are-an-and-gate-separate-from-permissions.md) — Every declared scope must be held, so adding one can only narrow access — permissions OR, and can only widen it
-- [Pikku state is a global map written only at registration time](core-state-is-a-global-map-written-only-at-registration-time.md) — A symbol-keyed globalThis map holds the wiring registry; nothing per-request may ever be written to it
-- [Email meta is read uncached because codegen rewrites it mid-session](email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md) — getEmailMeta re-reads its file on every call, unlike every other meta accessor, because the file appears and changes during a long-lived session
-- [Feature flag declarations refuse an empty anyOf and conflicting scopes](feature-flag-declarations-refuse-an-empty-anyof-and-conflicting-scopes.md) — validateAndBuildFeatureFlagDefinitionsMeta throws on an anyOf that is an empty list, and on a repeated flag name whose scopes differ between declarations
-- [Feature flags fail open on availability and never enforce access](feature-flags-fail-open-and-never-enforce-access.md) — 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
-- [Flag declaration sync rewrites only the description and anyOf](flag-sync-rewrites-only-the-declared-text.md) — The FeatureFlagStore contract re-syncs a flag's description and anyOf on deploy and leaves enabled, rollout and overrides to the operator
-- [Gateway adapters resolve lazily and are promise-cached](gateway-adapters-resolve-lazily-and-are-promise-cached.md) — wireGateway accepts an adapter factory because real adapters need boot-time secrets, which forces the webhook GET route to be registered unconditionally
-- [Gateway middleware sees wire.rpc on webhook and websocket, but not on listener](gateway-listener-middleware-runs-without-an-rpc-on-the-wire.md) — The listener transport invokes its handler directly, so middleware runs outside any runPikkuFunc call and the lazily-attached rpc is absent
-- [Gateway webhook challenges echo bytes not JSON](gateway-webhook-challenges-echo-bytes-not-json.md) — String verification challenges are returned raw with returnsJSON false, because platforms byte-compare the echo and JSON quoting fails the handshake
-- [Gateway wiring is a meta-wiring over HTTP and channels](gateway-wiring-is-a-meta-wiring-over-http-and-channels.md) — wireGateway writes handler implementations into the HTTP and channel state directly while the inspector compiles the corresponding meta, so runtime registration deliberately writes no meta
-- [Generated src paths in pikku meta are absolute](generated-src-paths-in-pikku-meta-are-absolute.md) — emailsMeta.src is resolved by the CLI at generation time, so reading through the project-relative helpers produces a wrong compound path
-- [Global middleware resolves from the root namespace too](global-middleware-resolves-from-the-root-namespace-too.md) — An addon's dispatch carries the addon's package name, so reading globals from that namespace alone meant the application's own global middleware never ran for it
-- [Hot reload reads the changed source, never a compiled copy of it](hot-reload-reads-the-changed-source-never-a-compiled-copy.md) — A leftover .js beside a .ts made the reloader announce a reload while re-registering the previous implementation; project TypeScript is now compiled by the reloader itself
-- [Hot reload writes into the function map captured at startup, not pikkuState's current one](hot-reload-writes-into-the-function-map-captured-at-startup.md) — A dev-server watcher may have swapped in a codegen-scoped map whose writes are discarded on restore, and schemas are deliberately left alone
-- [HTTP request bodies are read once and shared between consumers](http-request-bodies-are-read-once-and-shared.md) — The fetch request wrapper memoises the single-use body and builds web Requests lazily, at the cost of holding the whole body in memory
-- [HTTP route groups cascade config in a fixed, per-field order](http-route-groups-cascade-config-in-a-fixed-order.md) — basePath concatenates, tags and middleware merge outward-in, auth is overridden by the innermost group
-- [The HTTP router matches normalized paths but returns the registered path](http-router-matches-normalized-paths-but-returns-registered-ones.md) — Matching normalizes the leading slash while the match result carries the original key, because pikkuState is keyed by the registered string
-- [The HTTP runner logs through a trace-scoped logger, functions do not](http-runner-logs-through-a-trace-scoped-logger-functions-do-not.md) — Only runner-internal logging is scoped to the request id; functions keep the singleton logger for compatibility
-- [Set-Cookie headers are appended individually, never joined](http-set-cookie-headers-are-appended-never-joined.md) — Every cookie gets its own header line, because Set-Cookie is the one header comma-joining corrupts
-- [HTTP SSE streams flush headers only after middleware has run](http-sse-streams-flush-headers-only-after-middleware.md) — SSE responses defer the header flush and register with the eventHub, at the cost of a stricter ordering the runner must preserve
-- [HTTP wiring without generated metadata is skipped, not fatal](http-wiring-without-metadata-is-skipped-not-fatal.md) — wireHTTP warns and returns when a route has no metadata, so partial deploy units still boot
-- [In a scenario a 4xx is data, not an exception](in-a-scenario-a-4xx-is-data-not-an-exception.md) — postScenarioJson and invokeRaw report the status instead of throwing, because a refusal is the expected outcome of a permissions scenario
-- [In-memory workflow history aliases the live step object](in-memory-workflow-history-aliases-the-live-step-object.md) — stepHistory pushes the same StepState reference that steps holds, so later mutations to a step are visible in its history entry
-- [Istanbul statement counts attach to the start line only](istanbul-statement-counts-attach-to-the-start-line-only.md) — The istanbul coverage reader credits a statement's hits to its first line, so an enclosing multi-line statement cannot mask an unexecuted inner one
-- [Local trigger and gateway services assume a single process](local-trigger-and-gateway-services-assume-a-single-process.md) — InMemoryTriggerService and LocalGatewayService start every listener unconditionally with no distributed claiming, so a second instance duplicates every event
-- [MCP wire names are assigned over the whole registry, not derived per name](mcp-wire-names-are-assigned-over-the-whole-registry.md) — Sanitising each name on its own is lossy — `a:b` and `a.b` both become `a_b` — so one of the two targets would be unreachable
-- [Node-only builtins are imported dynamically](node-only-builtins-are-imported-dynamically.md) — V8CoverageService imports node:inspector inside start() so the module stays loadable on runtimes that have no such builtin
-- [One project-shape check, called by both validators](one-project-shape-check-two-validators.md) — workspace validate and cloud validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and cloud validate is that plus the deploy-shaped checks
-- [Only functions marked `expose: true` enter a virtual user's catalogue](only-exposed-functions-enter-a-virtual-user-catalogue.md) — Absent is not permissive — an unexposed function 404s over rpc, so offering one spends a step to learn nothing about the product
-- [Queue group concurrency keeps one shared queue fair](queue-group-concurrency-keeps-one-shared-queue-fair.md) — Per-group slot caps let many producers share a single queue instead of one queue each, at the cost of a cap that must stay under batchSize
-- [Queue jobs always carry an explicit attempts count](queue-jobs-always-carry-an-explicit-attempts-count.md) — resolveJobOptions always passes attempts so a queue backend can never apply its own retry default, and an explicit retries of 0 is honoured
-- [Remote addons dispatch over HTTP instead of through local function meta](remote-addons-dispatch-over-http-instead-of-local-meta.md) — wireRemoteAddon ships the addon as a devDependency and posts to the host, so there is deliberately no local handler to resolve
-- [System role names cannot contain the scope separator, and redeclared roles must grant the same scopes](role-names-cannot-contain-the-scope-separator.md) — validateAndBuildSystemRoleDefinitionsMeta rejects an empty role name or one containing ':', and throws when two declarations of one role name grant different scopes
-- [Bare RPC names resolve through the caller's package scope before root](rpc-names-resolve-through-package-scope-before-root.md) — An addon's own functions win over root RPC meta for bare names, and the resolving scope is returned so it can be threaded into runPikkuFunc
-- [Scenario agent calls retry sign-in only on 401](scenario-agent-calls-sign-in-on-401-only.md) — 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
-- [`given` and `when` are sugar for each other; `then` is not](scenario-given-and-when-are-sugar-but-then-is-not.md) — 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
-- [Scenario meta lives apart from app meta but merges when read off disk](scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md) — Scenarios generate into .pikku/scenarios so no app module imports them, yet MetaService folds them back into the workflow and function meta
-- [Scenario steps return drained response records](scenario-steps-return-drained-response-records.md) — 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
-- [Scenarios, steps and virtual users live in files named for them, and validate errors when they do not](scenarios-live-in-files-named-for-them.md) — 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
-- [Scope roots may be co-declared by an addon and its host app](scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md) — flattenScopeDefinitions dedupes ids because the same root can legitimately be declared twice, and every consumer requires one entry per scope
-- [Serverless channel disconnect must tolerate a missing channel](serverless-channel-disconnect-must-tolerate-a-missing-channel.md) — A failed channel lookup on disconnect returns quietly, because serverless runtimes deliver disconnect more than once
-- [sideEffects is an allowlist, because core genuinely has some](side-effects-are-an-allowlist-not-a-boolean.md) — 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
-- [Speech synthesis picks a voice per sentence but announces a limitation once](speech-synthesis-picks-a-voice-per-sentence-and-warns-once.md) — A bilingual reply should speak the half it can, and repeating the notice for every sentence would bury the reply itself
-- [The agent `done` event goes through the middleware and is awaited](the-agent-done-event-goes-through-the-middleware-and-is-awaited.md) — `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
-- [The API report pins members, because the export list only pins names](the-api-report-pins-members-not-just-names.md) — 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
-- [The core scope validator refuses separator, wildcard and empty scope segments](the-core-scope-validator-refuses-separator-wildcard-and-empty-segments.md) — assertSegment rejects a scope segment that contains the colon separator, equals the wildcard, or is empty
-- [The dev queue copies prod timing and serialization semantics](the-dev-queue-copies-prod-timing-and-serialization-semantics.md) — InMemoryQueueService dispatches via setTimeout, retries with backoff, and JSON round-trips every payload so dev behaviour matches a real backend
-- [One door per name — the ecosystem tier and the package root are both gone](the-ecosystem-entry-point-carries-the-adapter-surface.md) — 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
-- [The embedding model is pinned per service and doc/query embedding is split](the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md) — AIEmbeddingService fixes its model at construction so index and query share a vector space, and separates embedDocuments from embedQuery for asymmetric models
-- [The in-memory workflow service is inline-only and single-process](the-in-memory-workflow-service-is-inline-only-and-single-process.md) — InMemoryWorkflowService wires no queues and implements withRunLease/withStepLock as pass-throughs, because inline execution has no second holder to exclude
-- [The KEK salt is scoped to the key version, not the secret](the-kek-salt-is-scoped-to-the-key-version.md) — One stored salt per key version means N secrets cost one derivation, which is the point of envelope encryption
-- [The MCP handshake is challenged only when every target is gated](the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md) — 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
-- [The middleware resolution cache is deliberately unbounded](the-middleware-resolution-cache-is-deliberately-unbounded.md) — 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
-- [The per-invocation rpc view is a class, because an object literal with a getter is slow to build](the-per-invocation-rpc-view-is-a-class.md) — 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
-- [The pikku user id resolves in a fixed order](the-pikku-user-id-resolves-in-a-fixed-order.md) — defaultPikkuUserIdResolver takes an explicit pikkuUserId first, then the session userId, then the queue job's id, then the workflow's id
-- [The function runner resolves wire services itself](the-runner-resolves-wire-services-itself.md) — A function's wire services come from its own package's factory or the app's registered one, never borrowed from whoever called it
-- [The schema service is never stubbed, or tests validate nothing](the-schema-service-is-never-stubbed.md) — createStubProxy returns undefined for the schema property so the real schema service is built — a stubbed one turns validation into a silent no-op
-- [A voice turn's transcript is sent before the run starts, on the raw channel](the-transcript-event-is-sent-ahead-of-the-run.md) — 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
-- [The catalogue is the only gate on what a virtual user may call](the-virtual-user-catalogue-is-the-only-gate-on-what-may-be-called.md) — Narrowing happens once at derivation, so there is no second check in the run loop that could drift out of step with it
-- [The virtual user's instructions say the word "json" because a degraded gateway demands it](the-virtual-user-prompt-says-json-because-of-json-object-mode.md) — 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
-- [The virtual user runtime is exported from @pikku/core/virtual-user, never from services](the-virtual-user-runtime-is-exported-from-the-virtual-user-entry-point.md) — Those values reach the conversation and agent runners, which no production server runs — and an unbundled deploy loads whatever the import graph names
-- [The worker disposition is the only one not testing anything](the-worker-disposition-is-the-one-that-is-not-testing.md) — It is doing the job, so it abandons rarely, runs cool, and is told to stop and say so rather than guess
-- [Thread history records what the model was asked, which for a spoken turn is the transcript](thread-history-records-the-transcript-not-the-audio.md) — The wire carried a base64 audio blob; persisting it writes megabytes of unreadable data and loses the only readable record of the turn
-- [Trigger declaration is split from trigger source](trigger-declaration-is-split-from-trigger-source.md) — Triggers are declared everywhere but subscribed only in the trigger worker, so app processes never open the underlying subscription
-- [TypedSecretService caches for the process lifetime](typed-secret-service-caches-for-the-process-lifetime.md) — 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
-- [Both validators check virtual users through one shared module, and a virtual user counts from either the meta or the source](validate-checks-virtual-users-through-a-shared-module.md) — 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
-- [pikku validate runs every applicable check, it does not detect a project kind](validate-runs-checks-by-precondition.md) — 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
-- [The conversation engine only sees a transport-agnostic target driver](virtual-user-conversation-drives-the-target-through-a-transport-seam.md) — The engine never imports the agent runner; the target is injected as run/approve, so scenarios exercise the real wire path
-- [A conversation verdict is the virtual user's self-evaluation, not an assertion](virtual-user-conversation-verdicts-are-llm-self-evaluations.md) — The engine returns what the virtual user judged plus the transcript; deterministic checks stay with the caller
-- [A virtual user conversation starts from a seeded kickoff message](virtual-user-conversations-seed-a-hidden-kickoff-message.md) — 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
-- [A scenario's step order for a virtual user is insertion order, not a graph traversal](virtual-user-step-order-comes-from-insertion-order.md) — 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
-- [Virtual users are declared in exactly one defineVirtualUsers call per codebase](virtual-users-are-declared-in-one-definevirtualusers-call-per-codebase.md) — defineVirtualUsers is a no-op declaration that the inspector reads statically, and a second call anywhere in the codebase fails the build
-- [Only an explicit `false` silences a spoken reply](voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md) — The key being absent means no voice input is wired and nothing reported either way, so those callers keep the behaviour they had before the option existed
-- [Webhook delivery history records every attempt, best effort](webhook-delivery-history-records-every-attempt-best-effort.md) — The webhook worker persists each attempt before it throws, and a failure to persist is logged rather than allowed to mask the delivery result
-- [Webhook service collaborators are constructor args, not locator lookups](webhook-service-collaborators-are-constructor-args-not-locator-lookups.md) — QueueWebhookService takes its queue as a constructor parameter so a project wiring webhooks without a queue fails to compile instead of at first send
-- [Whether a run is inline is read from the run record](whether-a-run-is-inline-is-read-from-the-run-record.md) — The runContexts map is a read-through cache over WorkflowRun.inline and a lifetime for replay ordinals, never the answer to what a run is
-- [Wiring registries erase the generics their wire* functions capture](wiring-registries-erase-the-generics-their-wire-functions-capture.md) — A registry is typed at unknown so every wiring shares one map; storing a generic config in it needs an assertion, because function parameters are contravariant
-- [Workflow approval expiry is decided from a recorded deadline, not from a timer firing](workflow-approval-expiry-is-decided-from-a-recorded-deadline.md) — The wake-up job is best-effort liveness; losing, duplicating or delaying it cannot change the gate's answer
-- [Core declares the scenario browser surface structurally and never imports a driver](workflow-core-never-imports-a-browser-driver.md) — `@pikku/core` must stay dependency-free for edge runtimes, so playwright augments the interface instead of being imported by it
-- [Workflow DSL meta keeps runtime expressions in their own field, apart from literal values](workflow-dsl-meta-separates-runtime-expressions-from-literals.md) — A string `value` regenerates as a string literal; an `expression` regenerates as code, so the two can never share a field
-- [A feature resolves its scenarios by object identity, never by name or shape](workflow-features-resolve-scenarios-by-object-identity.md) — An unregistered scenario comes back explicitly unresolved rather than silently running as something else
-- [Inline and queued workflow graph runs share one transition planner](workflow-graph-inline-and-queued-runs-share-one-planner.md) — A second, weaker inline traversal would lose joins, cycle revisits and step provenance that the queued path has
-- [Workflow graph node notes are non-semantic and excluded from the graph hash](workflow-graph-node-notes-are-excluded-from-the-graph-hash.md) — Documentation on a node must not count as a topology change, or editing a comment redeploys the workflow
-- [An inline workflow run reports its run id the moment it exists, because a failure throws instead of returning](workflow-inline-runs-report-their-run-id-before-they-can-fail.md) — `onRunCreated` is the only moment guaranteed to happen whether the run passes, fails or suspends
-- [`invocationId` is a workflow step's dedupe key; `stepId` is store-specific and must never be used as one](workflow-invocation-id-is-the-dedupe-key-not-step-id.md) — The invocation id is a frozen UUIDv5 of runId + stepName, identical across retries on every backend
-- [A workflow step goes through the queue only if its function opts in, and there is no inline fallback](workflow-queued-step-dispatch-requires-an-explicit-opt-in.md) — `workflowQueued: true` is the whole decision; a missing queue service is a hard error, not a silent downgrade
-- [Workflows get their own queues by default, and queue names are resolved from queue meta](workflow-queues-are-per-workflow-by-default.md) — Per-workflow queues stop one slow step head-of-line-blocking every other workflow; `shared-groups` trades that for one set of pollers
-- [A workflow step name repeated in one run gets an ordinal suffix, and the first reach stays bare](workflow-repeated-step-names-get-an-ordinal-suffix.md) — `name`, `name#1`, `name#2` keys each reach separately without changing the durable key of any existing run
-- [A workflow replay reads its steps once and caches only the run's immutable half](workflow-replay-reads-its-steps-once-and-caches-only-the-immutable-half.md) — The per-replay snapshot collapses O(N^2) step reads to one, but caching mutable run fields would make the replay read a lie
-- [Workflow step retries are owned by the workflow, never by the queue](workflow-retries-are-owned-by-the-workflow-not-the-queue.md) — A step's retry count is resolved once and always passed to the queue as `attempts`, so the queue can never apply its own default
-- [Workflow run capabilities are extensions, not subclasses](workflow-run-capabilities-are-extensions-not-subclasses.md) — Scenario support lives in a separate module behind `setRunExtension` because a bundler drops an unused module but never an unused class member
-- [The workflow run mirror is an observability sink, never a second source of truth](workflow-run-mirror-is-never-a-source-of-truth.md) — Every mirrored write happens after the authoritative write lands, and a mirror failure can never fail the workflow
-- [Workflow run polling starts short and backs off to the caller's ceiling](workflow-run-polling-backs-off-to-the-callers-ceiling.md) — `pollIntervalMs` is a ceiling, not a cadence, and the wait lives in its own method so the schedule can be asserted without the clock
-- [The workflow run timeline is a pure fold over durable history, with the row's status as the authority](workflow-run-timeline-is-a-pure-fold-over-durable-history.md) — No IO in the fold keeps time-travel transport-independent; the terminal event comes from `status`, not from a timestamp every backend populates
-- [Scenario steps default to no retries, and a whole poll is one durable step](workflow-scenario-assertions-never-retry-and-record-one-step.md) — Retrying a failed assertion is wrong for a test primitive; recording the poll as one step means replay returns the outcome, not the loop
-- [Scenario lifecycle hooks are a scenario-only affordance and never mask the failure they follow](workflow-scenario-hooks-are-a-scenario-only-affordance.md) — A durable workflow replays, so a callback that reruns each replay has no honest meaning there
-- [Scenario prose is rendered out of typed calls, not parsed into them](workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md) — A readable report with no regex step registry to maintain
-- [A quarantined scenario states its reason in code, not in a CI invocation](workflow-scenario-quarantine-reason-lives-in-code.md) — `skip` carries the why next to the scenario it applies to, and naming the scenario explicitly still runs it
-- [Scenario step targets are string literals so the inspector can read them statically](workflow-scenario-step-targets-are-string-literals-for-the-inspector.md) — `step/given/when/then` mirror `do`'s RPC shape because the extractor reads a literal, not an imported symbol
-- [A step's compensation runs as a durable step of its own, declared on the function](workflow-step-compensation-runs-as-its-own-durable-step.md) — A refund or rollback must not fire twice on replay, so it is recorded as `<step>:compensate`; `onError` is gone
-- [A failed workflow step dispatch is transient infrastructure, not a run failure](workflow-step-dispatch-failure-is-transient-not-a-run-failure.md) — Queue-unreachable errors leave the run running and the step pending so the orchestrator replays; marking the run failed loses it
-- [A workflow step lock is held only to claim the step, never across its execution](workflow-step-lock-is-held-only-to-claim-the-step.md) — Holding the step lock across step work exhausted the connection pool and self-deadlocked when it was an advisory lock; it stays claim-only on leases
-- [A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it](workflow-step-rpc-name-is-provenance-only.md) — It exists so a reader can join a runtime step row back to the declaration that produced it, especially when the durable name was built in a loop
-- [A suspend or approval `reason` is the step's durable identity, not just a message](workflow-suspend-and-approval-reasons-are-durable-step-identities.md) — The reason is namespaced and used raw as the step key, so it must be derived deterministically across replays
-- [A suspended workflow run keeps its in-process context; only terminal runs release it](workflow-suspended-runs-keep-their-in-process-context.md) — `suspended` is absent from the terminal set on purpose, and a context is dropped only when nothing is holding it open
-<!-- /pikku:knowledge-index -->

package/knowledge/decisions/internals/istanbul-statement-counts-attach-to-the-start-line-only.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: Istanbul statement counts attach to the start line only
-description: The istanbul coverage reader credits a statement's hits to its first line, so an enclosing multi-line statement cannot mask an unexecuted inner one
-tags: services
----
-
-# Istanbul statement counts attach to the start line only
-
-`IstanbulCoverageService` (`packages/core/src/services/istanbul-coverage-service.ts`)
-reads instrumented counters off the `__coverage__` global and, when turning
-statement maps into line hits, credits each statement's count to its _start_ line
-and no other line it spans.
-
-This is istanbul's own semantics, and the reason matters: statements nest. An
-`if` block spanning ten lines has a non-zero count as soon as the `if` is
-reached, and a `throw` on line six inside it that never ran has a count of zero.
-Spreading the enclosing statement's count across its whole range would paint that
-`throw` as covered — the uncovered branch disappears into the covered one, which
-is precisely the case coverage exists to surface.
-
-**What this rules out:** filling in `start.line`..`end.line` from a single
-statement's count, or merging a nested statement's zero into its parent's total.
-Any change here has to keep the innermost statement's own count as the authority
-for its line.

package/knowledge/decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: Local trigger and gateway services assume a single process
-description: InMemoryTriggerService and LocalGatewayService start every listener unconditionally with no distributed claiming, so a second instance duplicates every event
-tags: services
----
-
-# Local trigger and gateway services assume a single process
-
-`InMemoryTriggerService` (`packages/core/src/services/in-memory-trigger-service.ts`)
-and `LocalGatewayService` (`packages/core/src/services/local-gateway-service.ts`)
-start every registered trigger source and every listener gateway
-unconditionally. There is no claiming, no lease, no leader election: whoever
-boots, listens.
-
-That is correct for exactly one owner. Run two instances and both subscribe to
-the same source, so every external event fires its RPC target twice — and because
-triggers and listener gateways are typically wired to side-effecting functions,
-the duplicate is not idempotent. A distributed deployment needs a different
-`TriggerService` / `GatewayService` implementation that coordinates first; the
-interfaces exist so that implementation can be dropped in.
-
-**What this rules out:** scaling a `pikku serve` or container running these
-services beyond one replica, and adding coordination inside these two classes.
-They are the single-process implementations by definition — coordination belongs
-in a sibling implementation, not behind a flag here.

package/knowledge/decisions/internals/mcp-wire-names-are-assigned-over-the-whole-registry.md

@@ -1,39 +0,0 @@
----
-type: decision
-title: MCP wire names are assigned over the whole registry, not derived per name
-description: Sanitising each name on its own is lossy — `a:b` and `a.b` both become `a_b` — so one of the two targets would be unreachable
-tags: [mcp, naming]
----
-
-# MCP wire names are assigned over the whole registry
-
-MCP clients constrain tool and prompt names to `[A-Za-z0-9_-]`. Pikku's
-namespace separator is `:`, so every target contributed by an addon — `bb2:getMe`
-and friends — carries a name the client cannot accept. Clients drop such names
-from the session rather than fail the connection, which reads as the tools simply
-not existing. The names are therefore rewritten at the transport boundary and
-resolved back on the way in; the namespace itself is untouched, since it is what
-dispatch keys on.
-
-The rewrite is computed for **all** names of a target type at once, not for one
-name in isolation. Replacing illegal characters one name at a time is not
-injective: `a:b` and `a.b` both sanitise to `a_b`, so the list handlers would
-advertise one name twice and the resolver could only ever pick one of them. The
-other target becomes unreachable, silently.
-
-The assignment runs in two passes over the sorted names:
-
-1. Every name that is already wire-legal claims itself. A target whose name a
-   client can already spell keeps that spelling, whatever else is registered.
-2. The rest are sanitised, and a collision takes the next free `_2`, `_3`, …
-   suffix.
-
-Sorting makes the result depend only on the set of registered names, so the same
-registry always produces the same wire names, across processes and restarts.
-
-**What this rules out:** a pure `wireName(name)` function. Correctness here is a
-property of the whole registry, and a signature that cannot see the registry
-cannot have it. It also rules out percent-style escaping, which would be
-injective but would turn every namespaced tool into something unreadable in the
-client's UI, for a collision that needs two targets differing only in their
-separator.

package/knowledge/decisions/internals/node-only-builtins-are-imported-dynamically.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: Node-only builtins are imported dynamically
-description: V8CoverageService imports node:inspector inside start() so the module stays loadable on runtimes that have no such builtin
-tags: services
----
-
-# Node-only builtins are imported dynamically
-
-`V8CoverageService` (`packages/core/src/services/v8-coverage-service.ts`) reaches
-`node:inspector` through `await import('node:inspector')` inside `doStart()`,
-not through a top-level import.
-
-`@pikku/core` is loaded whole on runtimes that have no Node builtins —
-Cloudflare Workers most notably. A static `import 'node:inspector'` is resolved
-when the module graph loads, so it would fail the entire bundle at startup on
-those runtimes, for a service that would never have been started there anyway.
-Deferring the import moves the failure to the point of use, where it is both
-correct and avoidable.
-
-**What this rules out:** hoisting the import to the top of the file because the
-dynamic form "looks unnecessary", and the same move in any other core module that
-touches a Node-only builtin. The rule is general: if core can be loaded on
-Workers, a Node builtin is imported at the call site.

package/knowledge/decisions/internals/one-project-shape-check-two-validators.md

@@ -1,53 +0,0 @@
----
-type: decision
-title: One project-shape check, called by both validators
-description: workspace validate and cloud validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and cloud validate is that plus the deploy-shaped checks
-tags: cli, validate, cloud
----
-
-# One project-shape check, called by both validators
-
-`pikku workspace validate` and `pikku validate` read like one command
-with a flag. They were two implementations — 495 lines and 2026 — that walked
-the same project and emitted sixteen identical findings. `functions-dir-missing`
-existed character for character in both files. All sixteen already agreed on
-severity, which is the only reason the duplication was invisible.
-
-What the duplication cost was not the lines. It was that each validator carried
-checks the other lacked for no reason anyone could name, and nobody noticed
-because nobody read them side by side:
-
-- cloud validate never checked that `packages/functions` declares zod v4, or
-  that it has a `package.json` at all — while it did check that six other
-  dependencies are present.
-- workspace validate never checked the four scaffold flags beyond `console`,
-  though the console it requires is useless without `rpc`.
-- cloud validate swallowed a JSON parse error and reported
-  `pikku-config-missing` for a file sitting right there.
-
-Two of workspace validate's own checks were not merely absent from cloud — they
-had never run anywhere:
-
-- the auth checks were gated on a middleware instance with `definitionId ===
-'betterAuthSession'`, but the CLI wires `betterAuthStatelessSession` whenever
-  `session.cookieCache` is on, which is the configuration Pikku Studio Cloud asks for. So
-  they skipped precisely the apps most likely to have auth.
-- they looked for migrations in `packages/functions/db/`, and for tables named
-  `app_user` and `auth_verification_token`. `pikku db migrate` reads migrations
-  from `<root>/db/<engine>/`, and those two table names appear nowhere else in
-  pikku or in any template. Had the gate ever opened, the check would have been
-  wrong for every project it fired on.
-
-`shared-checks.ts` is now the half that is true of any pikku project regardless
-of where it deploys. Workspace validate is exactly that module; cloud validate
-is that module plus the deploy-shaped checks — themes, frontends, the
-Cloudflare adapter, the `.gitignore` contract, the frontend type-check.
-
-Pikku Studio Cloud's fix hints won where the two differed: they are multi-line and show the
-config block to paste, and there was no reason workspace users were getting the
-one-line version.
-
-**What this rules out:** adding a check to one validator and not the other;
-`pikku validate` reporting a corrupt config as a missing one; asserting
-auth table names no scaffold generates; and reading migrations from anywhere
-other than where `pikku db migrate` reads them.

package/knowledge/decisions/internals/only-exposed-functions-enter-a-virtual-user-catalogue.md

@@ -1,21 +0,0 @@
----
-type: decision
-title: Only functions marked `expose: true` enter a virtual user's catalogue
-description: Absent is not permissive — an unexposed function 404s over rpc, so offering one spends a step to learn nothing about the product
-tags: core, virtual-user
----
-
-# Only functions marked `expose: true` enter a virtual user's catalogue
-
-`expose: true` is what puts a function on the rpc transport, which is what the
-shipped target is called over. The catalogue therefore treats an absent `expose`
-as excluded rather than as unspecified-and-allowed.
-
-Absent is not permissive here: an unexposed function returns 404, and offering
-it costs the user a step and teaches nothing about the product. On the e2e app,
-34 of 72 functions are in exactly that state — close to half a catalogue that
-cannot be called at all.
-
-**What this rules out:** defaulting the check to "include unless explicitly
-hidden", which reads as the safer default and produces a catalogue that is
-mostly dead ends.

package/knowledge/decisions/internals/queue-group-concurrency-keeps-one-shared-queue-fair.md

@@ -1,28 +0,0 @@
----
-type: decision
-title: Queue group concurrency keeps one shared queue fair
-description: Per-group slot caps let many producers share a single queue instead of one queue each, at the cost of a cap that must stay under batchSize
-tags: queue
----
-
-# Queue group concurrency keeps one shared queue fair
-
-`PikkuWorkerConfig.groupConcurrency` in
-`packages/core/src/wirings/queue/queue.types.ts` caps how many jobs of any one
-group (`JobOptions.group`, a `JobGroup` with an `id` and optional `tier`) may run
-at once. Jobs sharing a group `id` count against the same limit;
-`GroupConcurrencyConfig.tiers` varies the limit per tier so a slow group can be
-allowed more or fewer slots than the default.
-
-The alternative considered was one queue per producer, which gives isolation for
-free. It was rejected because pull-based backends poll per queue, so splitting
-multiplies polling cost linearly with the number of producers. A single shared
-queue plus a per-group cap gets the same "no one producer starves the others"
-property at constant polling cost. The cap must not exceed
-`PikkuWorkerConfig.batchSize`, which is the worker's total concurrency — a group
-limit above it can never bind and silently reverts the queue to unfair.
-
-**What this rules out:** dropping `group`/`groupConcurrency` in favour of
-per-producer queues, and raising a group limit to or above `batchSize` as a way
-to "disable" fairness — that reintroduces head-of-line blocking by a single
-producer rather than turning the feature off.

package/knowledge/decisions/internals/queue-jobs-always-carry-an-explicit-attempts-count.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: Queue jobs always carry an explicit attempts count
-description: resolveJobOptions always passes attempts so a queue backend can never apply its own retry default, and an explicit retries of 0 is honoured
-tags: services
----
-
-# Queue jobs always carry an explicit attempts count
-
-`QueueWebhookService.resolveJobOptions`
-(`packages/core/src/services/queue-webhook-service.ts`) resolves retries as
-per-call `retries` → `config.webhook.retries` → `DEFAULT_WEBHOOK_RETRIES`, then
-_always_ puts `attempts: retries + 1` on the job options. It mirrors the workflow
-service's policy resolution. Backoff is exponential unless a concrete
-`retryDelay` selects a fixed one.
-
-Two rules are load-bearing. `attempts` is passed unconditionally so the queue
-backend never gets to apply its own default — pg-boss, BullMQ and SQS disagree
-about what that default is, and a webhook silently retried a different number of
-times per backend is not a behaviour anyone can reason about. And an explicitly
-set `retries: 0` is honoured rather than treated as unset, because "deliver this
-exactly once, do not retry" is a real caller intent that `??` chains lose.
-
-**What this rules out:** omitting `attempts` when it equals the default, folding
-`retries` into a truthiness check (`retries || configRetries`, which turns 0 back
-into the default), and relying on a queue adapter's retry configuration in place
-of passing the value.

package/knowledge/decisions/internals/remote-addons-dispatch-over-http-instead-of-local-meta.md

@@ -1,31 +0,0 @@
----
-type: decision
-title: Remote addons dispatch over HTTP instead of through local function meta
-description: wireRemoteAddon ships the addon as a devDependency and posts to the host, so there is deliberately no local handler to resolve
-tags: rpc
----
-
-# Remote addons dispatch over HTTP instead of through local function meta
-
-`wireAddon` bundles an addon's functions in-process: the package is a production
-dependency and its handlers run inside the consumer. `wireRemoteAddon`
-(`packages/core/src/wirings/rpc/wire-remote-addon.ts`) does the opposite — the
-package is installed as a **devDependency**, contributing types only, and the
-handlers run on the host at `serverUrl`. `pikku verify` enforces the
-devDependency placement.
-
-`ContextAwareRPCService.invokeAddonFunction` in `rpc-runner.ts` therefore checks
-`resolved.addonConfig?.remote` _before_ it looks for local function meta, and
-routes to `invokeRemoteAddonFunction`. That method POSTs the addon's own function
-name — the bare name, not the namespaced `ns:fn` form, optionally remapped by
-`remoteName` — to `${serverUrl}/remote/rpc/:rpcName`, authenticating as a client
-with the token bound in `wireRemoteAddon({ auth })`. There is no local meta entry
-to fall back on, which is why a missing `serverUrl` raises
-`RemoteAddonConfigError` rather than degrading to a local lookup, and a non-2xx
-response raises `RemoteAddonRequestError` with a truncated body for context.
-
-**What this rules out:** moving the `remote` check after the local meta lookup
-(the lookup will always miss and mask the real error), sending the namespaced
-name over the wire, and promoting the addon to a production dependency so its
-handlers can be "used directly" — that defeats the point of the remote wiring and
-puts the host's code in the consumer's bundle.

package/knowledge/decisions/internals/role-names-cannot-contain-the-scope-separator.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: System role names cannot contain the scope separator, and redeclared roles must grant the same scopes
-description: validateAndBuildSystemRoleDefinitionsMeta rejects an empty role name or one containing ':', and throws when two declarations of one role name grant different scopes
-tags: core, roles, scopes, validation
----
-
-# System role names cannot contain the scope separator, and redeclared roles must grant the same scopes
-
-`packages/core/src/wirings/role/validate-role-definitions.ts` checks declared
-system roles.
-
-The separator is `:` (`validate-role-definitions.ts:7`). A name is refused when it
-is empty (`validate-role-definitions.ts:10-12`) or contains the separator
-(`validate-role-definitions.ts:13-18`). The message says the separator "delimits
-scope ids; a role named like a scope reads as one" (`validate-role-definitions.ts:16`).
-
-When a name is declared twice, the scope lists are compared after sorting, so order
-does not matter (`validate-role-definitions.ts:69-71`). A different set throws,
-with the message "Roles sharing a name must grant the same scopes"
-(`validate-role-definitions.ts:72-79`). An identical repeat is skipped
-(`validate-role-definitions.ts:80`).
-
-`flattenSystemRoleDefinitions` keeps the first entry for each name
-(`validate-role-definitions.ts:36-40`). Its doc comment says this is safe only
-because the validator already guaranteed the repeats are identical
-(`validate-role-definitions.ts:24-29`).
-
-**What this rules out:** a role named with a scope-like `:` in it, and two
-declarations of one role that grant different scopes.

package/knowledge/decisions/internals/rpc-names-resolve-through-package-scope-before-root.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: Bare RPC names resolve through the caller's package scope before root
-description: An addon's own functions win over root RPC meta for bare names, and the resolving scope is returned so it can be threaded into runPikkuFunc
-tags: rpc
----
-
-# Bare RPC names resolve through the caller's package scope before root
-
-`resolvePikkuFunction` in `packages/core/src/wirings/rpc/rpc-runner.ts` tries the
-caller's package function meta first when a `packageName` is supplied, then root
-RPC meta, then a versioned base name, then root function meta, and only then
-throws `RPCNotFoundError`. It returns the resolving package alongside the
-`pikkuFuncId` so `ContextAwareRPCService` can pass the right scope into
-`runPikkuFunc` without a second lookup.
-
-The package-first order exists because RPC meta only ever lives in root: addon
-packages register their handlers under their own package name as _function_ meta,
-never as RPC meta. Without the package probe, a bare `rpc('doThing')` made from
-inside an addon would skip that addon's own `doThing` and either resolve to an
-unrelated root function of the same name or fail outright. The versioned retry
-exists so `name@2` falls back to the meta registered under `name`.
-
-When even root resolution fails, `rpc` and `rpcWithWire` catch the
-`RPCNotFoundError` and hand the call to `services.deploymentService` if one is
-configured — a Cloudflare service binding or a Lambda invoke — so a name that is
-not in this deploy unit can still be served by another.
-
-**What this rules out:** flattening the lookup to a single root meta read,
-resolving the package scope separately from the function id (the two must agree),
-and treating an `RPCNotFoundError` as terminal before the deployment-service
-fallback has had a chance.