@pikku/core 0.12.143 → 0.12.145

package/knowledge/decisions/internals/virtual-users-are-declared-in-one-definevirtualusers-call-per-codebase.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: Virtual users are declared in exactly one defineVirtualUsers call per codebase
-description: defineVirtualUsers is a no-op declaration that the inspector reads statically, and a second call anywhere in the codebase fails the build
-tags: core, inspector, virtual-users, declaration
----
-
-# Virtual users are declared in exactly one defineVirtualUsers call per codebase
-
-`defineVirtualUsers` in `packages/core/src/wirings/virtual-user/define-virtual-users.ts`
-is a no-op (`define-virtual-users.ts:33`). The CLI reads the call by AST and
-generates a `VirtualUserId` union and `virtual-users.gen.json` from it
-(`define-virtual-users.ts:3-8`). The doc comment states the rule: "Exactly one
-`defineVirtualUsers(...)` is allowed per codebase, so there is one place to read the
-cast from and one place to add to. A second call — even in the same file — fails
-the build" (`define-virtual-users.ts:14-16`).
-
-The inspector enforces it. `addVirtualUsers` requires an inline object literal and
-refuses anything else (`packages/inspector/src/add/add-virtual-users.ts:163-170`),
-then claims the single declaration (`add-virtual-users.ts:174-181`, error
-`DUPLICATE_VIRTUAL_USERS_DEFINITION`). `claimSingleDeclaration` in
-`packages/inspector/src/utils/single-declaration.ts` refuses a second call in the
-same file or another one (`single-declaration.ts:44-56`). Generated `.gen.ts` files
-are exempt and never claim the slot (`single-declaration.ts:40-42`).
-
-**What this rules out:** a second `defineVirtualUsers` call, including in the same
-file, and splitting the cast across several declarations. The rule is about where a
-person adds a virtual user, so it applies to hand-written files only.
-
-**Related:** [scenario and virtual-user files are named for what they hold](scenarios-live-in-files-named-for-them.md)

package/knowledge/decisions/internals/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md

@@ -1,24 +0,0 @@
----
-type: decision
-title: Only an explicit `false` silences a spoken reply
-description: The key being absent means no voice input is wired and nothing reported either way, so those callers keep the behaviour they had before the option existed
-tags: core, agent
----
-
-# Only an explicit `false` silences a spoken reply
-
-`voiceOutput` speaks a reply unless the turn is explicitly marked as not having
-arrived by voice. The distinction is between three states, not two:
-
-- `true` — `voiceInput` handled this turn and it carried speech.
-- `false` — `voiceInput` handled this turn and a real user really typed it.
-- absent — no voice input is wired at all, so nothing reported either way.
-
-Treating absent as `false` would silence every caller who wired `voiceOutput`
-without `voiceInput`, changing behaviour that worked before the option existed.
-Treating absent as `true` would speak replies to typists on any stack where the
-flag never gets set.
-
-**What this rules out:** normalising the flag to a boolean at any point between
-`voiceInput` and `voiceOutput` — that collapses absent into one of the other two
-and picks a wrong answer for somebody.

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

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

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

@@ -1,58 +0,0 @@
----
-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/wiring-registries-erase-the-generics-their-wire-functions-capture.md

@@ -1,35 +0,0 @@
----
-type: decision
-title: Wiring registries erase the generics their wire* functions capture
-description: A registry is typed at unknown so every wiring shares one map; storing a generic config in it needs an assertion, because function parameters are contravariant
-tags: core
----
-
-# Wiring registries erase the generics their `wire*` functions capture
-
-Every `wire*` entry point — `wireTrigger`, `wireTriggerSource`, `wireChannel`,
-`wireQueueWorker`, and the rest — is generic in the shape a caller declares, so
-the caller gets a checked `func`. The registry each one writes to is not:
-`pikkuState(null, 'trigger', 'triggers')` is a
-`Map<string, CoreTriggerSource>` where `CoreTriggerSource` fixes input and
-output at `unknown`, because one map has to hold every trigger in the app.
-
-Handing `CoreTriggerSource<TInput, TOutput>` to a slot typed
-`CoreTriggerSource<unknown, unknown>` is not an upcast. `func` takes its input
-as a _parameter_, and parameters are contravariant: a function that accepts
-`TInput` cannot stand in for one that accepts `unknown`, since `unknown` admits
-values `TInput` does not. TypeScript is right to reject it, and no variance
-annotation makes it go away — the registry genuinely holds functions whose input
-types it cannot name.
-
-The runtime is nonetheless sound, because the only thing that ever invokes a
-registered `func` is the function runner, which validates the incoming data
-against that function's own generated schema before the call. The type the
-registry lost is re-established at the call boundary by the schema, not by the
-type system.
-
-**What this rules out:** deleting these assertions as if they were noise — the
-code does not compile without them. It equally rules out `as any` in their
-place: `as any` discards the target type too, so a genuinely wrong config would
-also slip through. Assert to the registry's own element type and let everything
-except the erased generic stay checked.

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

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

@@ -1,42 +0,0 @@
----
-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: `resolveScenarioVirtualUsers` in
-`pikku-scenario-service.ts` imports the HTTP virtual user client lazily, so even a
-runner bundle only pays for the AI virtual user conversation loop when a scenario
-actually signs a virtual user 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 virtual-user-client import
-static.

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

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

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

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

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

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

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

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

package/knowledge/decisions/internals/workflow-queues-are-per-workflow-by-default.md

@@ -1,42 +0,0 @@
----
-type: decision
-title: Workflows get their own queues by default, and queue names are resolved from queue meta
-description: Per-workflow queues stop one slow step head-of-line-blocking every other workflow; `shared-groups` trades that for one set of pollers
-tags: workflow
----
-
-# Workflows get their own queues by default, and queue names are resolved from queue meta
-
-`WorkflowQueueOptions.queueStrategy` defaults to `'per-workflow'`: each workflow
-gets its own `wf-orchestrator-*` and `wf-step-*` queue. That gives complete
-isolation and is what lets serverless providers deploy one unit per workflow,
-at the cost of one set of pollers per queue — which adds up on pull-based
-backends. `'shared-groups'` puts every workflow on the shared orchestrator and
-step-worker queues and keeps them isolated with a per-group concurrency cap, so
-there is one set of pollers for the whole system. It is only for single-process
-runtimes; a per-unit serverless deploy needs the per-workflow queues to route to
-its units. The options are passed to the service constructor rather than read
-from `config.workflow` because the queues are wired during construction, before
-singleton services — and so before `config` — exist.
-
-Under `'shared-groups'`, `getJobGroup` returns a group keyed by workflow name
-(steps group by step function, mirroring how per-step queues split them). It
-returns `undefined` under `'per-workflow'`, because the queue name already
-isolates the workflow and a group would cap it inside its own dedicated queue.
-The group tier repeats the id so a workflow can be given its own limit purely
-from config; note tiers can only lower a limit, never raise it above `default`,
-because the backend applies its pre-fetch exclusion per group using `default`
-alone.
-
-`getOrchestratorQueueName` and `getStepWorkerQueueName` read `queue.meta`, which
-is always populated globally, rather than `queue.registrations`, which only
-covers queues this unit consumes. In a per-unit deploy the orchestrator unit
-produces to the per-step queues without consuming them, so registrations would
-miss them. `wireQueueWorkers` warns loudly when workflows exist but no
-`wf-orchestrator-*` queue is in meta: everything still "works" via the shared
-fallback, but the isolation is gone and one slow step head-of-line-blocks every
-other workflow — invisible until a queue starves.
-
-**What this rules out:** defaulting to `'shared-groups'`, returning a job group
-under `'per-workflow'`, resolving queue names from `queue.registrations`, or
-dropping the wiring-time warning as noise.

package/knowledge/decisions/internals/workflow-repeated-step-names-get-an-ordinal-suffix.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: A workflow step name repeated in one run gets an ordinal suffix, and the first reach stays bare
-description: `name`, `name#1`, `name#2` keys each reach separately without changing the durable key of any existing run
-tags: workflow
----
-
-# A workflow step name repeated in one run gets an ordinal suffix, and the first reach stays bare
-
-`nextStepKey` in `pikku-workflow-service.ts` turns a logical step name into the
-physical, replay-stable key for the Nth time the run reaches it: the bare name
-for ordinal 0, `name#N` for repeats. Keeping the first reach unsuffixed is what
-makes the scheme backward compatible — existing runs and their persisted step
-rows are untouched — while still letting the same literal step name be invoked
-several times (a loop, a helper called twice) without the rows clobbering each
-other.
-
-The counters live in the per-replay `RunContext.replay.ordinals` and are reset
-by `beginReplay` on every orchestrator tick. That reset is what makes the keys
-deterministic: given a deterministic workflow body, the second replay assigns
-exactly the same key to the same reach and therefore finds the cached row rather
-than minting `name#1` for a step that already succeeded. `nextStepKey` also
-records the key it just produced as `replay.lastStep`, which is how the next
-step learns its predecessor (`fromStepName`).
-
-Graph runs use the same convention for cycle revisits, and
-`stripInstanceOrdinal` / `executeWorkflowStep` map `node#N` back to the logical
-node id, which is not a literal key in the graph's `nodes` map.
-
-**What this rules out:** suffixing the first reach too (it re-keys every step of
-every existing run), advancing the ordinal counters anywhere other than a fresh
-replay pass, deriving step keys from a non-deterministic source, or treating a
-physical step key as a graph node id without stripping the ordinal.

package/knowledge/decisions/internals/workflow-replay-reads-its-steps-once-and-caches-only-the-immutable-half.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: A workflow replay reads its steps once and caches only the run's immutable half
-description: The per-replay snapshot collapses O(N^2) step reads to one, but caching mutable run fields would make the replay read a lie
-tags: workflow
----
-
-# A workflow replay reads its steps once and caches only the run's immutable half
-
-A DSL replay walks the workflow body from the top, and each step it passes asks
-for its own row — so a run of N steps costs N reads per replay and O(N^2) over
-its lifetime. `beginReplay` in `pikku-workflow-service.ts` opens a pass by
-calling `listStepStates`, which backends able to answer in a single query
-override; `loadOrCreateStep` then serves every step from that snapshot. This is
-safe because a pass reaches each step key at most once and the steps it replays
-past are `succeeded`, and therefore immutable.
-
-`getRunIdentity` caches the run for the same pass, but only for its immutable
-half — which workflow it is, the wire it was started on, its input. Anything
-needing `status`, `output`, `error` or `state` must call `getRun`: those move
-while the run executes and a cached copy would be a lie. The `replay` half of
-`RunContext` is rebuilt from scratch on every orchestrator tick and torn down by
-`endReplay`.
-
-`loadOrCreateStep` also handles a concurrent replay creating the row after the
-snapshot was taken: if `create()` throws, it re-reads the step, and only if that
-read also fails does it rethrow the original — because in that case the insert
-failed for its own reasons and that error is the one worth seeing.
-
-**What this rules out:** widening the snapshot to cover mutable run fields,
-keeping it across orchestrator ticks, or removing the re-read fallback in
-`loadOrCreateStep` on the grounds that a duplicate insert "cannot happen".