@pikku/core 0.12.72 → 0.12.77

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/scenarios-live-in-files-named-for-them.md

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

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

@@ -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.)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/knowledge/decisions/internals/webhook-delivery-history-records-every-attempt-best-effort.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Webhook delivery history records every attempt, best effort
+description: The webhook worker persists each attempt before it throws, and a failure to persist is logged rather than allowed to mask the delivery result
+tags: services
+---
+
+# Webhook delivery history records every attempt, best effort
+
+`pikkuWebhookWorkerFunc` (`packages/core/src/services/queue-webhook-service.ts`)
+POSTs the delivery, then — when the job carries a `deliveryId` — calls
+`webhookService.recordAttempt` with the outcome *before* throwing on a non-2xx.
+The throw is what makes the queue retry, so recording first is the only way the
+console's delivery history shows every try rather than just the final one.
+
+A `deliveryId` is only present when a store-backed implementation (e.g.
+`KyselyWebhookService`) enqueued the job, which is why the queue-only default's
+base `recordAttempt` — which throws `NotImplementedError` — is never reached.
+The `recordAttempt` call is wrapped in `.catch(log)`: history is bookkeeping, and
+a store outage must not turn a delivered webhook into a failed one, nor a failed
+one into an unexplained crash.
+
+**What this rules out:** awaiting `recordAttempt` without the catch, moving it
+after the throw, or making the worker's success depend on the store being
+reachable. Equally, do not delete the `.catch` as a swallowed error — the log
+line is the intended handling.

package/knowledge/decisions/internals/webhook-service-collaborators-are-constructor-args-not-locator-lookups.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Webhook service collaborators are constructor args, not locator lookups
+description: QueueWebhookService takes its queue as a constructor parameter so a project wiring webhooks without a queue fails to compile instead of at first send
+tags: services
+---
+
+# Webhook service collaborators are constructor args, not locator lookups
+
+`QueueWebhookService` (`packages/core/src/services/queue-webhook-service.ts`)
+takes `queueService` as a constructor parameter, even though it reaches for
+`config` and `secrets` through `getSingletonServices()` inside its methods. The
+queue is different on purpose: it is the collaborator without which the class
+cannot do anything at all.
+
+A `getSingletonServices()` lookup turns a wiring mistake into a runtime failure
+on the first `send()` — typically in production, typically on the first webhook a
+customer was waiting for. A constructor parameter turns the same mistake into a
+type error at the point where the service is wired.
+
+**What this rules out:** "simplifying" the constructor away so the class looks
+like its neighbours and pulls the queue from the service locator like everything
+else. The inconsistency inside this class is the decision, not an oversight; if
+anything the pressure should run the other way, toward making `config` and
+`secrets` constructor args too.

package/knowledge/decisions/internals/whether-a-run-is-inline-is-read-from-the-run-record.md

@@ -0,0 +1,58 @@
+---
+type: decision
+title: Whether a run is inline is read from the run record
+description: 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
+tags: workflow, state
+---
+
+# Whether a run is inline is read from the run record
+
+`PikkuWorkflowService.isInline` resolves `WorkflowRun.inline` from the store and
+caches it on the process-local `runContexts` entry for the duration of the
+execution that is running the step. `registerInlineRun` / `unregisterInlineRun`
+prime and evict that cache; they no longer decide anything. Both callers pass
+the same `shouldInline` to `createRun` that they pass to `registerInlineRun`, so
+the prime is only ever a saved read.
+
+`inline` decides two forks: whether a failed step retries in-process or is
+handed to the queue, and whether a sleep blocks here or goes to the
+`schedulerService`. Answering them from a `Map` that only the instance that
+called `startWorkflow` ever populated makes both forks instance-dependent. On
+Lambda, Workers, or any multi-instance container deployment, instance B reads an
+empty map, concludes the run is queued, and dispatches an orchestrator job for a
+run instance A is already driving in-process — two executors on one run. The
+durable field is the only thing every instance can agree on.
+
+`isInline` is therefore `async`. Its four call sites — `inlineStep` and
+`scheduleSleep` in core, `dispatchStep` and `scheduleSleep` in the Cloudflare
+Durable Object service — were already `async`, so nothing had to become
+asynchronous to accommodate it. Resolving it through `getRunIdentity` means a
+run job that already read its run pays no second read, and caching the answer on
+the context bounds a step worker to one read. `WorkflowRun.inline` is written
+once at `createRun` and never mutated, so a cached value cannot go stale.
+
+The same entry carries per-replay ordinals, the last step name, and the step
+snapshot. Those are genuinely process-local — they exist to give
+`name`, `name#1`, `name#2` to repeated reaches of one logical step within a
+single walk of a workflow, and to let a replay read its rows once. Their
+lifetime is now an explicit `activeExecutions` count incremented by
+`runWorkflowJob` and by `executeWorkflowStep` and decremented in their `finally`
+blocks; the entry is deleted when the count reaches zero, and a terminal
+`updateRunStatus` that arrives mid-execution defers to that. Previously
+`nextStepKey` lazily created a `replay` object on every step invocation while
+`releaseContext` refused to free any entry that had one, so any step reached
+outside a `beginReplay` bracket — a graph node's RPC using its workflow wire
+from the step-worker queue — stranded an ordinals map and a step-state snapshot
+for the life of the process.
+
+Resetting ordinals per execution rather than letting them accumulate across
+separate step-worker invocations also makes step naming independent of how the
+work happened to be distributed. Two step workers in one process used to see
+different ordinals than the same two workers on different instances.
+
+**What this rules out:** answering `isInline` from the map alone and defaulting
+to `false` on a miss, which is the split-brain; a synchronous `isInline` backed
+by a cache nothing guarantees is populated; keeping a run's entry alive because
+a value is cached in it, since a cache that is never evicted is a leak; and
+mutating `WorkflowRun.inline` after creation, which the cache is only safe
+because nothing does.

package/knowledge/decisions/internals/workflow-approval-expiry-is-decided-from-a-recorded-deadline.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: Workflow approval expiry is decided from a recorded deadline, not from a timer firing
+description: The wake-up job is best-effort liveness; losing, duplicating or delaying it cannot change the gate's answer
+tags: workflow
+---
+
+# Workflow approval expiry is decided from a recorded deadline, not from a timer firing
+
+On its first reach, `approvalStep` in `pikku-workflow-service.ts` stamps
+`expiresAt` into the gate's run-state record and calls `scheduleRunWake`. Every
+later replay decides expiry by comparing `Date.now()` against that recorded
+deadline. A duplicate, late, or entirely dropped timer therefore all produce the
+same answer, and losing the wake costs liveness — the run sits until something
+else resumes it — never correctness.
+
+`scheduleRunWake` deliberately enqueues a delayed *orchestrator* pass rather
+than reusing `scheduleSleep`. `scheduleSleep` resolves the step it is given,
+which for an approval would resolve the gate itself; the wake only nudges the
+run to replay and re-evaluate, leaving the gate the sole judge of its own
+outcome. It is wrapped in a try/catch that logs and continues, because a
+scheduling failure must not fail the run.
+
+An approval returns an `ApprovalOutcome` union (`decided` | `expired`) rather
+than throwing on the deadline, so callers are forced to handle expiry and "skip
+it and carry on" stays trivial. `decided` means a human answered — whether the
+answer was yes or no rides in `data` and is the application's business.
+
+**What this rules out:** treating the timer's delivery as the expiry signal,
+routing the wake through `scheduleSleep` or any path that writes the gate's step
+result, letting a `scheduleRunWake` failure propagate, or turning expiry into a
+thrown error. Expiry also fires unconditionally once enqueued — a durable timer
+cannot be retracted — so the replay must no-op it when a decision has already
+landed.