@pikku/core 0.12.71 → 0.12.74

package/knowledge/decisions/internals/http-wiring-without-metadata-is-skipped-not-fatal.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: HTTP wiring without generated metadata is skipped, not fatal
+description: wireHTTP warns and returns when a route has no metadata, so partial deploy units still boot
+tags: http
+---
+
+# HTTP wiring without generated metadata is skipped, not fatal
+
+`wireHTTP` in `packages/core/src/wirings/http/http-runner.ts` looks the route up in
+`pikkuState(null, 'http', 'meta')` and, when nothing is found, logs a warning and
+returns instead of throwing. `wireChannel` in
+`packages/core/src/wirings/channel/channel-runner.ts` does the same for channels.
+
+A deploy unit is built from filtered metadata: only the functions belonging to
+that unit get meta entries. A wiring file, however, is imported whole. When two
+wirings share one file, importing it for the sake of the first wiring also
+executes the second — whose function is not in this unit and therefore has no
+metadata. Throwing there would make an otherwise valid deploy unit fail to boot.
+The warning names the route and tells the author to split the wirings into
+separate files, which both fixes the warning and improves tree-shaking.
+
+**What this rules out:** turning the missing-metadata branch into a thrown error
+or an assertion "because a route should always have metadata". It should not, in
+filtered builds. It also rules out silently dropping the warning — the warning is
+the only signal an author gets that a route they wired is not actually served.

package/knowledge/decisions/internals/in-a-scenario-a-4xx-is-data-not-an-exception.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: In a scenario a 4xx is data, not an exception
+description: postScenarioJson and invokeRaw report the status instead of throwing, because a refusal is the expected outcome of a permissions scenario
+tags: services
+---
+
+# In a scenario a 4xx is data, not an exception
+
+`postScenarioJson` (`packages/core/src/services/scenario-actors-service.ts`) and
+`ScenarioActor.invokeRaw` return a `ScenarioHttpResponse` for every status. Only
+`invoke` throws, and it throws with a truncated body — which is why a scenario
+asserting on a refusal must use `invokeRaw`.
+
+A permissions or scopes scenario *expects* the 403. The status is the assertion,
+and the body usually names the scope that was missing, so both have to survive as
+data rather than being reduced to a thrown `Error`. These helpers also exist
+because every scenario reaching past an actor was hand-writing the same
+`content-type`, `JSON.stringify` and drain — and the copies had drifted: several
+returned `res.json()`, which discards the status entirely and throws outright on
+an empty body or an HTML error page.
+
+**What this rules out:** adding a `throwOnError` default to these helpers,
+routing scenario assertions through `invoke`, and reintroducing per-scenario
+fetch wrappers that return a parsed body without the status.

package/knowledge/decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: In-memory workflow history aliases the live step object
+description: stepHistory pushes the same StepState reference that steps holds, so later mutations to a step are visible in its history entry
+tags: services
+---
+
+# In-memory workflow history aliases the live step object
+
+`InMemoryWorkflowService` (`packages/core/src/services/in-memory-workflow-service.ts`)
+stores each step twice: in `steps`, keyed `${runId}:${stepName}`, and appended to
+`stepHistory` for the run. Both hold the *same object*. `createStepImpl` and
+`createRetryAttemptImpl` push the reference they just put into `steps`, not a
+copy.
+
+That aliasing is the mechanism, not an accident. The service mutates a step in
+place as it progresses — status, `runningAt`, `completedAt`, output, error — and
+every one of those updates has to appear in the run's history without the history
+being rewritten. Break the aliasing and history freezes at the moment each step
+was created: every entry reads `pending`, and `getRunHistory` reports a run in
+which nothing ever finished.
+
+**What this rules out:** pushing `{ ...step }` into `stepHistory`, or introducing
+any clone/freeze/structuredClone on the way in — the obvious "don't share mutable
+state" cleanup. If history ever needs to be immutable, the step updates have to
+start writing to both structures explicitly, in the same change.

package/knowledge/decisions/internals/index.md

@@ -0,0 +1,113 @@
+---
+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 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
+- [An actor conversation starts from a seeded kickoff message](actor-flow-conversations-seed-a-hidden-kickoff-message.md) — The actor'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
+- [The actor-flow conversation engine only sees a transport-agnostic target driver](actor-flow-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
+- [An actor-flow verdict is the persona's self-evaluation, not an assertion](actor-flow-verdicts-are-llm-self-evaluations.md) — The engine returns what the actor judged plus the transcript; deterministic checks stay with the caller
+- [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
+- [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](ai-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](ai-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
+- [A credential-required tool result never reaches the client or the transcript](ai-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](ai-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](ai-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](ai-agent-model-config-stays-a-single-resolution-seam.md) — resolveModelConfig looks removable but is the one merge point for per-request model overrides
+- [An aiMiddleware onError hook cannot change how a run fails](ai-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](ai-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
+- [Persisting an agent stream from send is best-effort and must never reject](ai-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](ai-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](ai-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](ai-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](ai-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
+- [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
+- [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
+- [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
+- [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 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
+- [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
+- [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
+- [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
+- [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 sign in on 401 only](scenario-agent-calls-sign-in-on-401-only.md) — postAgent sends the first request with whatever session it holds and logs in only if refused, so an actor can converse with a no-auth agent with no sign-in wiring
+- [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
+- [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
+- [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
+- [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 withRunLock/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 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
+- [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
+- [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
+- [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) — The inversion of cucumber — 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 handler runs as a durable step of its own, and never compensates itself](workflow-step-compensation-runs-as-its-own-durable-step.md) — A refund or rollback must not fire twice on replay, so `onError` is recorded as `<step>:onError` with retries disabled
+- [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 advisory lock — and its pooled connection — across step work exhausted the connection pool and self-deadlocked
+- [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

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

@@ -0,0 +1,26 @@
+---
+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/node-only-builtins-are-imported-dynamically.md

@@ -0,0 +1,24 @@
+---
+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/queue-group-concurrency-keeps-one-shared-queue-fair.md

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

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

@@ -0,0 +1,31 @@
+---
+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/rpc-names-resolve-through-package-scope-before-root.md

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

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

@@ -0,0 +1,27 @@
+---
+type: decision
+title: Scenario agent calls sign in on 401 only
+description: postAgent sends the first request with whatever session it holds and logs in only if refused, so an actor can converse with a no-auth agent with no sign-in wiring
+tags: services
+---
+
+# Scenario agent calls sign in on 401 only
+
+`HttpScenarioActor.postAgent`
+(`packages/core/src/services/http-scenario-actors.ts`) sends its first request
+with whatever cookie the jar happens to hold — none, for an actor that has never
+signed in — and only a 401 triggers `login()` and a single retry. Its sibling
+`invokeRaw` does the opposite: it signs in eagerly before the first RPC.
+
+The asymmetry is deliberate. Agent HTTP routes may be public; RPC routes are
+assumed not to be. Making agent calls eager would mean an actor could not talk to
+a no-auth agent at all without a sign-in endpoint, an actor secret and a user
+table — a large amount of wiring to exercise an agent that requires none of it.
+Deferring to the 401 keeps the authenticated case working (the retry succeeds
+with the session attached) at the cost of one extra round trip the first time.
+
+**What this rules out:** unifying the two paths so `postAgent` signs in up front
+"like `invokeRaw` does", and removing the 401 retry on the grounds that
+`invokeRaw` already guarantees a session. Note the ordering consequence: an actor
+whose first action is `converse` against a no-auth agent never signs in at all, so
+nothing else may assume `signedIn` is true after a conversation.

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

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

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

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

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

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

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

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

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

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