@pikku/core 0.12.71 → 0.12.74

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/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.

package/knowledge/decisions/internals/workflow-core-never-imports-a-browser-driver.md

@@ -0,0 +1,42 @@
+---
+type: decision
+title: Core declares the scenario browser surface structurally and never imports a driver
+description: `@pikku/core` must stay dependency-free for edge runtimes, so playwright augments the interface instead of being imported by it
+tags: workflow
+---
+
+# Core declares the scenario browser surface structurally and never imports a driver
+
+`PikkuBrowserWire`, `TestIdSelector`, `ScenarioBrowserProvider` and
+`ScenarioBrowserFailure` all live in `scenario-step.types.ts` as plain
+structural types. `@pikku/core` deliberately never imports playwright — it has
+to stay dependency-free for edge runtimes — so `@pikku/playwright` augments
+`PikkuBrowserWire` via `declare module`, and `wire.browser.page` becomes a fully
+typed Playwright `Page` only in a project that installs it. Declaring the
+provider contract here is also what lets the CLI depend on core alone.
+
+`reset` and `captureFailure` are optional on `ScenarioBrowserProvider` so a
+driver written against an earlier version keeps compiling; the runner treats a
+driver without them as one offering no isolation and no diagnostics.
+`captureFailure` must never throw — a failure to capture must not replace the
+failure being captured — and exists because a browser step fails with a selector
+timeout that says nothing about *why* the page never rendered; the answer is
+almost always in the page's own console and request errors, which the driver has
+been collecting all along.
+
+`TestIdSelector` is richer than a bare `data-testid` because one rarely names
+exactly one element: `where` matches the element's own data attributes (so a
+step asserts a status without reading translated copy back to the app), `prefix`
+matches a family of ids, `containing` picks the match holding a piece of text,
+and `within` scopes the lookup to one row or section. Core defines the shape;
+the driver resolves it against a real page.
+
+The same dependency discipline applies at runtime: `resolveScenarioActors` in
+`pikku-scenario-service.ts` imports the HTTP actor client lazily, so even a
+runner bundle only pays for the AI persona conversation loop when a scenario
+actually signs an actor in.
+
+**What this rules out:** importing playwright (or any driver) from core,
+tightening `reset`/`captureFailure` to required, letting `captureFailure` throw,
+reducing `TestIdSelector` to a plain string, or making the actor-client import
+static.

package/knowledge/decisions/internals/workflow-dsl-meta-separates-runtime-expressions-from-literals.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: Workflow DSL meta keeps runtime expressions in their own field, apart from literal values
+description: A string `value` regenerates as a string literal; an `expression` regenerates as code, so the two can never share a field
+tags: workflow
+---
+
+# Workflow DSL meta keeps runtime expressions in their own field, apart from literal values
+
+Several step metas in `dsl/workflow-dsl.types.ts` carry a literal field and a
+parallel `expression` field: `SetStepMeta` has `value` and `expression`
+(`count + 1`), `SleepStepMeta` has `duration` and `expression` (a duration known
+only at runtime, e.g. a loop variable). They are mutually exclusive by
+construction because regenerated code has to emit them differently — a string
+`value` becomes a string literal, an `expression` becomes raw code. Collapsing
+them would make every computed assignment regenerate as a quoted string.
+
+Two related shapes exist for the same "the extractor cannot see this
+statically" reason. `ReturnStepMeta.spread` records variables spread into a
+returned object (`return { ...r }`) or a sole returned variable (`return r`) by
+name, because their fields are not enumerable statically and cannot be expanded
+into `outputs`. `FeatureMeta.unresolvedEntries` counts feature entries that
+could not be read statically (a spread, a `.map()`), so a non-zero count marks
+the listing as partial rather than pretending it is complete.
+
+`FanoutStepMeta.stepName` is optional for a different structural reason: a
+fanout is not itself a cached step, and node ids are step names — borrowing a
+body step's name would give the loop and that step the same id, collapsing one
+onto the other.
+
+Free-text documentation (`GraphNodeConfig.notes`,
+`PikkuWorkflowGraphConfig.notes`) is excluded from the graph topology hash, so
+editing a note never marks the workflow as changed and never triggers a version
+mismatch on in-flight runs.
+
+**What this rules out:** merging `expression` into `value`/`duration`, expanding
+`spread` into concrete `outputs`, giving a fanout a required `stepName` taken
+from its body, and folding `notes` into `graphHash`.

package/knowledge/decisions/internals/workflow-features-resolve-scenarios-by-object-identity.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: A feature resolves its scenarios by object identity, never by name or shape
+description: An unregistered scenario comes back explicitly unresolved rather than silently running as something else
+tags: workflow
+---
+
+# A feature resolves its scenarios by object identity, never by name or shape
+
+`resolveFeatureScenarios` in `feature.ts` builds a `Map` keyed by the registered
+config object itself and looks each feature entry up in it. `pikkuScenario`
+returns its config verbatim and `addWorkflow` registers that same object, so a
+feature holding the imported identifier holds the very object that was
+registered. Nothing is matched by shape, by name, or by any other guess.
+
+That is also why a scenario built inline inside a feature — and therefore never
+registered — comes back in `unresolved` rather than silently running as
+something else. Because scenarios are referenced by imported identifier, a
+renamed or deleted scenario is a compile error rather than a silent skip.
+
+Entries are returned in declaration order and features in registration order,
+since a feature's reading order is its declaration order. A scenario's effective
+tags are its own unioned with the containing feature's, so a tag filter selects
+through the feature.
+
+**What this rules out:** falling back to name matching when identity lookup
+misses, structurally comparing configs, or dropping unresolved entries silently
+instead of reporting them — each turns "this scenario is not registered" into
+"some other scenario ran instead".

package/knowledge/decisions/internals/workflow-graph-inline-and-queued-runs-share-one-planner.md

@@ -0,0 +1,42 @@
+---
+type: decision
+title: Inline and queued workflow graph runs share one transition planner
+description: A second, weaker inline traversal would lose joins, cycle revisits and step provenance that the queued path has
+tags: workflow
+---
+
+# Inline and queued workflow graph runs share one transition planner
+
+`planGraphTransitions` in `graph/graph-runner.ts` is the single place that
+decides which nodes fire next. `continueGraph` (queued) and
+`continueGraphInline` (in-process loop) both call it; they differ only in
+whether the planned wave is dispatched via `queueGraphNode` or executed by
+`executeGraphNodeInline`. Sharing the planner is what gives the inline path
+joins, cycle revisits and `fromStepName` provenance identical to the queue,
+instead of a second and weaker traversal. `executeGraphNodeInline` persists
+under the same physical instance key and records the same predecessor as
+`queueGraphNode` for the same reason.
+
+The planner distinguishes two kinds of edge. A forward edge is node-once: the
+target fires only if it has no instance yet, so converging edges (joins)
+collapse to a single run. A back-edge — one whose target can reach the source,
+detected by `closesCycle` — is a revisit: it fires a fresh ordinal instance
+(`target#1`, …) and is edge-once on `from → target` so it does not re-fire every
+tick. Cycles terminate when branch routing stops looping back, and every
+instance records the predecessor it was reached from.
+
+`remapStepNamesToNodeIds` and `remapBranchKeys` are called on the completed and
+branch sets even where their results are discarded: planning keys steps
+physically, so those calls exist only to surface an ambiguous template-node
+config as an error.
+
+On the queued path a node that sets no `retries` falls back to
+`DEFAULT_STEP_RETRIES` rather than to zero, so the persisted step's retry count
+matches the queue job's `attempts` (see `resolveStepJobOptions`). A step row
+claiming one attempt while the queue silently delivers five is the kind of
+disagreement that makes a retry bug unreadable from the outside.
+
+**What this rules out:** writing a separate traversal for the inline path,
+making forward edges fire per-edge (which breaks joins) or back-edges fire
+node-once (which breaks loops), dropping `fromStepName` from either path, and
+deleting the "unused" remap calls as dead code.

package/knowledge/decisions/internals/workflow-graph-node-notes-are-excluded-from-the-graph-hash.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Workflow graph node notes are non-semantic and excluded from the graph hash
+description: Documentation on a node must not count as a topology change, or editing a comment redeploys the workflow
+tags: workflow
+---
+
+# Workflow graph node notes are non-semantic and excluded from the graph hash
+
+`GraphNodeConfig.notes` (`graph/workflow-graph.types.ts`, mirrored on the typed
+builder in `graph/graph-node.ts`) is free-text documentation attached to a node.
+It is deliberately excluded from the graph topology hash (`graphHash`), so
+editing a note never marks the workflow as changed. The graph-level `notes`
+field on `wireWorkflowGraph` (`graph/wire-workflow-graph.ts`) — which carries
+things like imported sticky notes — is excluded for the same reason.
+
+The hash exists to answer "is this the same workflow the running instances were
+started against?". Prose about a node has no bearing on that. If notes were
+hashed, adding a sentence of documentation would register as a topology change
+and the only safe habit would be to never document a node.
+
+**What this rules out:** folding `notes` into `graphHash` "for completeness",
+or using `notes` to carry anything semantic — a routing hint, a version marker,
+a flag some other code reads — since nothing that changes behaviour may live in
+a field the change-detection hash ignores.

package/knowledge/decisions/internals/workflow-inline-runs-report-their-run-id-before-they-can-fail.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: An inline workflow run reports its run id the moment it exists, because a failure throws instead of returning
+description: `onRunCreated` is the only moment guaranteed to happen whether the run passes, fails or suspends
+tags: workflow
+---
+
+# An inline workflow run reports its run id the moment it exists, because a failure throws instead of returning
+
+`startWorkflow` in `pikku-workflow-service.ts` calls `options.onRunCreated(runId)`
+immediately after `createRun`, before any execution. An inline run that fails
+throws rather than returning `{ runId }`, so a caller wanting to read the run
+back — its steps, which one failed, what it was called with — would otherwise
+have nothing to read it by. Run creation is the only moment guaranteed to happen
+whether the run goes on to pass, fail or suspend.
+
+The failure path is equally deliberate. `WorkflowAsyncException`,
+`WorkflowCancelledException`, `WorkflowSuspendedException` and
+`WorkflowDispatchException` are all excluded from the "mark the run failed"
+branch: the first three already recorded their own status, and the fourth is
+transient. When a run does fail, an *expected* error (a `PikkuError`, e.g. a
+build gate tripping) logs only its message — the message is the whole story, and
+the `expected` flag survives the step-boundary rehydration that strips the
+class. Anything else is logged in full so the trace is there to debug.
+
+**What this rules out:** moving `onRunCreated` to after execution or into the
+success path, returning a sentinel run id instead of throwing, folding the four
+control-flow exceptions into the generic failure branch, or dumping a stack for
+every expected error.

package/knowledge/decisions/internals/workflow-invocation-id-is-the-dedupe-key-not-step-id.md

@@ -0,0 +1,43 @@
+---
+type: decision
+title: `invocationId` is a workflow step's dedupe key; `stepId` is store-specific and must never be used as one
+description: The invocation id is a frozen UUIDv5 of runId + stepName, identical across retries on every backend
+tags: workflow
+---
+
+# `invocationId` is a workflow step's dedupe key; `stepId` is store-specific and must never be used as one
+
+`deriveInvocationId` (`workflow-invocation-id.ts`) is `uuidv5(runId:stepName)`.
+Because both inputs are stable across replays, the same call yields the same
+UUID on every attempt and on every storage backend — so a step can
+`INSERT … ON CONFLICT (invocation_id)` or pass it as an external idempotency
+key (a Stripe key, say) and have a retry of a half-applied side effect collapse
+onto the first attempt.
+
+`stepId` cannot do that job. Whether it stays the same or is minted fresh per
+attempt is store-specific: the in-memory store mints a new one each attempt
+while the SQL store reuses the row. `WorkflowStepWire` documents `invocationId`
+as the dedupe key for exactly this reason.
+
+`PIKKU_WORKFLOW_NAMESPACE` in `workflow-invocation-id.ts` is frozen. Changing it
+would alter every derived invocation id and break dedupe across a deploy — steps
+that already ran would look new. The v5 implementation is hand-rolled (SHA-1
+plus the version and variant bit twiddling) rather than pulled from the `uuid`
+package, and `workflow-invocation-id.test.ts` pins it against the known
+`www.example.com`-in-DNS-namespace vector.
+
+Calling the same step name more than once in a run *is* disambiguated. Ordinals
+are already in: `nextStepKey` (`pikku-workflow-service.ts`) mints a physical key
+per reach — `name`, then `name#1`, `name#2` — and every step entry point routes
+through it, so `deriveInvocationId` hashes the physical key, not the logical
+name. Each reach therefore gets its own row and its own invocation id. The first
+reach keeps the bare name, so ids minted before ordinals landed are unchanged,
+and the ordinal counters reset at the start of each replay, so a given call site
+resolves to the same key on every attempt. `workflow-step-ordinal.test.ts` pins
+all three properties.
+
+**What this rules out:** using `stepId` as an idempotency key, regenerating the
+namespace UUID, swapping in a different hash or a random id, passing the logical
+step name to `deriveInvocationId` instead of the physical key from
+`nextStepKey`, or "simplifying" the derivation to include anything that varies
+between replays.

package/knowledge/decisions/internals/workflow-queued-step-dispatch-requires-an-explicit-opt-in.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: A workflow step goes through the queue only if its function opts in, and there is no inline fallback
+description: `workflowQueued: true` is the whole decision; a missing queue service is a hard error, not a silent downgrade
+tags: workflow
+---
+
+# A workflow step goes through the queue only if its function opts in, and there is no inline fallback
+
+`dispatchStep` in `pikku-workflow-service.ts` decides queued-vs-inline purely
+from the step function's `workflowQueued` flag in function meta, which defaults
+to false. If the flag is not set the method returns false and the caller runs
+the step inline. If it IS set and no queue service is configured, that is a hard
+error naming the step and the function — never a quiet downgrade to inline
+execution, because a function marked `workflowQueued` was marked that way for a
+reason (isolation, a long tail latency, a resource limit) that inline execution
+does not honour.
+
+Inline execution is not merely a degraded queue path. `runInlineRetryLoop` wraps
+the same `running → result` / `fail → retry-attempt → backoff → retry`
+scaffolding around a step-specific body and stays O(K) — no suspend, no replay —
+which is what makes an inline run cheap. Its optional `onError` hook exists for
+terminal errors that must NOT retry (RPC-not-found suspends the run for
+redeploy); if the hook throws, the loop exits immediately without recording a
+step error or retrying.
+
+**What this rules out:** inferring "should queue" from the presence of a queue
+service, falling back to inline when the queue is missing, and reusing
+`runInlineRetryLoop` for anything that needs to suspend between attempts.