@pikku/core 0.12.143 → 0.12.144

package/knowledge/decisions/internals/workflow-retries-are-owned-by-the-workflow-not-the-queue.md

@@ -1,31 +0,0 @@
----
-type: decision
-title: Workflow step retries are owned by the workflow, never by the queue
-description: A step's retry count is resolved once and always passed to the queue as `attempts`, so the queue can never apply its own default
-tags: workflow
----
-
-# Workflow step retries are owned by the workflow, never by the queue
-
-A step's retry policy comes from the step itself, falling back to
-`DEFAULT_STEP_RETRIES` (5) when unset. The default is deliberately greater than
-zero so a transient failure — a DB blip, a downstream restart, a deploy — is
-ridden out without the author asking for it; that is safe only because every
-step gets a stable `invocationId` to dedupe on. An explicit `retries: 0` means
-exactly once and must be honoured.
-
-`resolveStepJobOptions` in `pikku-workflow-service.ts` therefore ALWAYS emits
-`attempts`, even when it is 1. Backoff defaults to exponential whenever at least
-one retry remains, so retries ride out an outage instead of firing instantly; a
-concrete `retryDelay` (`15000`, `'15s'`) selects fixed backoff, and only the
-literal `'exponential'` selects exponential explicitly. `rpcStep` resolves the
-policy once, before both persistence and dispatch, so the value stored on the
-step row — which drives `retriesExhausted` — is the same number the queue turns
-into `attempts`. `queueGraphNode` in `graph/graph-runner.ts` defaults node
-retries to `DEFAULT_STEP_RETRIES` for the same reason.
-
-**What this rules out:** dropping `attempts` when it equals 1 "because that is
-the default anyway", resolving retries separately at the persistence and
-dispatch sites, or letting the queue adapter's own `retry_limit` decide. Any of
-those lets the queue re-run a step the workflow said to run once, or lets the
-engine believe retries are exhausted while the queue keeps retrying.

package/knowledge/decisions/internals/workflow-run-capabilities-are-extensions-not-subclasses.md

@@ -1,39 +0,0 @@
----
-type: decision
-title: Workflow run capabilities are extensions, not subclasses
-description: Scenario support lives in a separate module behind `setRunExtension` because a bundler drops an unused module but never an unused class member
-tags: workflow
----
-
-# Workflow run capabilities are extensions, not subclasses
-
-`PikkuWorkflowService` names nothing about what a `WorkflowRunExtension` is for.
-An extension is installed with `setRunExtension(create)` and receives a narrow
-`WorkflowRunEngine` handle — `inlineStep`, `updateRunStatus`,
-`onChildWorkflowFailed`, `verifyStepName` — so recording a durable step stays
-available to it without becoming public API on every workflow service a
-production app instantiates.
-
-The reason it is not a subclass is bundle size: a bundler drops an unused
-_module_ but never an unused class member. Anything declared on
-`PikkuWorkflowService` ships in every server built on Pikku, along with
-everything it imports. `PikkuScenarioService` (`pikku-scenario-service.ts`) is
-the one implementation today — steps, virtual users, lifecycle hooks, the browser
-provider and the assertion wire members — and scenarios only ever run from
-`pikku scenario run`, so the whole surface stays behind an import that only the
-runner makes. It is not a workflow service in its own right because a scenario
-is not a different kind of run; it is the same durable run with a step
-vocabulary on top. `scenario-service.test.ts` asserts that none of those members
-leak onto the base class.
-
-`createScenarioRunner` in the same file bundles the two lines
-`pikku scenario run` needs so no caller has to remember the capability is
-installed rather than inherited. It pairs the extension with
-`InMemoryWorkflowService`, which is the right engine because a scenario run is a
-single external process driving a deployed app over its real transport: there
-is nothing to persist and no second worker to resume it.
-
-**What this rules out:** moving scenario steps, virtual users, hooks or the browser
-provider onto `PikkuWorkflowService`, making `PikkuScenarioService` extend it,
-or widening `WorkflowRunEngine` into "just pass the service" — each one puts the
-scenario runtime, and its transitive imports, into every deployed Pikku server.

package/knowledge/decisions/internals/workflow-run-mirror-is-never-a-source-of-truth.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: The workflow run mirror is an observability sink, never a second source of truth
-description: Every mirrored write happens after the authoritative write lands, and a mirror failure can never fail the workflow
-tags: workflow
----
-
-# The workflow run mirror is an observability sink, never a second source of truth
-
-`WorkflowRunMirror` lets an executor shadow every state write to an external
-read store — typically a DB the console UI queries while the run itself lives in
-a Durable Object or Redis. Both properties that make it safe follow from the
-single shape of `PikkuWorkflowService.mirrored()` in
-`pikku-workflow-service.ts`: the mirror is only ever told about a write that has
-already landed in the canonical store, and a mirror that is down or throwing is
-caught, logged at warn, and otherwise invisible to the workflow. Even the log
-call is wrapped, because singleton services may not be initialised yet.
-
-Every public write method is a thin `mirrored(() => …Impl(...), (mirror) => …)`
-pair over a `protected abstract` implementation. That pairing is the reason a
-mirror method added to the interface but never wired into the service would
-write nothing at runtime — `workflow-mirror.test.ts` spells out the full method
-list to catch exactly that.
-
-**What this rules out:** reading run or step state back from the mirror,
-awaiting the mirror before returning the authoritative result, letting a mirror
-rejection propagate, or writing to the mirror first so the two "stay in sync" —
-any of which turns an index into a second, divergent source of truth that can
-take the workflow down with it.

package/knowledge/decisions/internals/workflow-run-polling-backs-off-to-the-callers-ceiling.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: Workflow run polling starts short and backs off to the caller's ceiling
-description: `pollIntervalMs` is a ceiling, not a cadence, and the wait lives in its own method so the schedule can be asserted without the clock
-tags: workflow
----
-
-# Workflow run polling starts short and backs off to the caller's ceiling
-
-`awaitRunEnd` in `pikku-workflow-service.ts` reads a run until it reaches an end
-state, starting at `WORKFLOW_POLL_MIN_MS` (10ms) and multiplying by
-`WORKFLOW_POLL_FACTOR` (1.6) up to the caller's `maxIntervalMs`. A fixed
-interval is wrong at both ends: it makes a workflow that finished in
-milliseconds wait out the whole interval anyway, and it keeps reading a
-long-running one at full rate for its entire life. Backing off returns quick
-runs promptly while a slow run's read cost grows logarithmically rather than
-linearly with duration. So `runToCompletion`'s `pollIntervalMs` is a ceiling,
-not a cadence.
-
-An inline sub-workflow uses a lower ceiling, `WORKFLOW_CHILD_POLL_MAX_MS`
-(500ms), because the parent step is blocked on it: every wait there is added
-latency in the middle of a workflow rather than at its edge.
-
-`waitBeforeNextRead` exists as its own method purely so the schedule can be
-asserted directly (`workflow-run-polling.test.ts`). Timing a poll loop by the
-clock measures the host's scheduler as much as the policy — `setTimeout(40)`
-routinely returns late on a loaded CI runner — which makes the obvious test both
-slow and flaky.
-
-**What this rules out:** replacing the backoff with a fixed `pollIntervalMs`
-sleep, reading `pollIntervalMs` as the first wait, giving child runs the
-top-level ceiling, or inlining `waitBeforeNextRead` back into the loop as a bare
-`setTimeout`.

package/knowledge/decisions/internals/workflow-run-timeline-is-a-pure-fold-over-durable-history.md

@@ -1,37 +0,0 @@
----
-type: decision
-title: The workflow run timeline is a pure fold over durable history, with the row's status as the authority
-description: No IO in the fold keeps time-travel transport-independent; the terminal event comes from `status`, not from a timestamp every backend populates
-tags: workflow
----
-
-# The workflow run timeline is a pure fold over durable history, with the row's status as the authority
-
-`run-timeline.ts` turns `getRunHistory` — one row per step _attempt_, each with
-lifecycle timestamps — into a flat, chronologically ordered event stream, and
-folds that stream up to any point to recover what the run "knew" then: the same
-step cache a replay would hold, plus the walked path. Both functions are pure,
-with no IO, so they are trivially testable and the same fold works for the
-Redis, Kysely and in-memory stores alike.
-
-The terminal event is driven by the row's authoritative `status`, falling back
-to `updatedAt` when the specific stamp is absent, because the lifecycle
-timestamps are not populated by every backend — Kysely leaves
-`succeededAt`/`runningAt` null. The intermediate `scheduled` and `running`
-events are optional enrichment, emitted only when the backend recorded them; the
-`pending` event always exists and is the one that carries provenance
-(`fromStepName`).
-
-Ordering is defensive: events sort by timestamp, then by `LIFECYCLE_ORDER`, then
-by original index, so rows sharing an instant stay deterministic across
-backends. In the fold, a retry's `pending` event reopens the step and drops the
-prior result and error.
-
-The index conventions are fixed and callers depend on them: `TimelineEvent.seq`
-is a monotonic 0-based position, `attempt` is 1-based, and
-`reconstructStateAt(at)` is inclusive whether `at` is a seq or a `Date` — a
-point before the first event yields the empty initial state with `seq` of `-1`.
-
-**What this rules out:** reading state inside the fold, deriving the terminal
-event from `succeededAt`/`failedAt` alone, trusting history to arrive sorted, or
-letting a retry's reopening event keep the previous attempt's outcome.

package/knowledge/decisions/internals/workflow-scenario-assertions-never-retry-and-record-one-step.md

@@ -1,54 +0,0 @@
----
-type: decision
-title: Scenario steps default to no retries, and a whole poll is one durable step
-description: Retrying a failed assertion is wrong for a test primitive; recording the poll as one step means replay returns the outcome, not the loop
-tags: workflow
----
-
-# Scenario steps default to no retries, and a whole poll is one durable step
-
-`ScenarioStepOptions.retries` defaults to 0, unlike an ordinary workflow step
-which inherits `DEFAULT_STEP_RETRIES`. `PikkuScenarioService.scenarioStep`
-applies that default explicitly (`options?.retries ?? 0`). Retrying a failed
-assertion is the wrong behaviour for a test primitive: it converts a real
-failure into a slow flake and hides the very race the scenario was written to
-catch.
-
-`expectEventually` is the sanctioned way to wait. The entire poll — invoke,
-check the predicate, sleep, repeat until `within` elapses — runs inside a single
-`inlineStep`, so it is ONE recorded step and a replay returns the cached
-outcome rather than re-polling. `expectError` and `expectService` are the same
-shape: one durable step whose body contains the whole assertion, with a failure
-message that names the step, the target, and what was actually seen.
-
-`pollUntil` in `scenario-poll.ts` is the step-level equivalent, and its
-`undefined` convention is deliberate: `undefined` means "not yet" and nothing
-else, because `false`, `0` and `''` are all real answers — a probe asking
-whether something happened reports `false` when it did not. It returns
-`undefined` at the deadline rather than throwing, leaving the error to the
-caller, who is the only one who knows what was being waited for. Its own
-defaults are shorter than the assertion wrappers': `within` 15s, `interval`
-250ms.
-
-`requireScenarioEnv` (`scenario-step-guards.ts`) exists for the mirror-image
-reason: `env` is optional on the step wire because most steps need nothing from
-it, so the narrowing happens in one place with a message that says what to do,
-instead of every step file writing its own guard. The virtual user is not narrowed at
-all — a step that runs as somebody declares `virtualUser: true` (or a `browser`
-binding, which cannot be provisioned without a window to open), and the runner
-injects `wire.virtualUser` non-optionally into every binding and refuses to dispatch
-the step without one. A wire member can be required per binding; a property of
-one cannot, which is why it is not on `scenarioStep`. `scenarioStep`'s `verifyStepName` call doubles as the guard for `then`
-being a wire member — an accidental `await scenario` calls it with a resolve
-function, which lands as a loud named error instead of a silent hang.
-
-The assertion options are lenient by design so a scenario reads as intent
-rather than as an exact-match harness: `matches` is a substring test when it is
-a string and a full match only when it is a `RegExp`; `calledWith` deep-equals
-the first argument only; `times` means at-least-once unless a count is given;
-`within` defaults to `'30s'` and `interval` to `'1s'`.
-
-**What this rules out:** giving scenario steps the workflow retry default,
-recording each poll iteration as its own step, treating a falsy `pollUntil`
-result as "not yet", making `pollUntil` throw on timeout, or narrowing `virtualUser`
-by hand inside individual step files.

package/knowledge/decisions/internals/workflow-scenario-hooks-are-a-scenario-only-affordance.md

@@ -1,43 +0,0 @@
----
-type: decision
-title: Scenario lifecycle hooks are a scenario-only affordance and never mask the failure they follow
-description: A durable workflow replays, so a callback that reruns each replay has no honest meaning there
-tags: workflow
----
-
-# Scenario lifecycle hooks are a scenario-only affordance and never mask the failure they follow
-
-`PikkuScenarioService.scenarioHooks` (`pikku-scenario-service.ts`) returns hooks
-only when `workflowMeta.source === 'scenario'`. A plain workflow is durable and
-resumable, so a `before`/`after` callback that reran on every replay would have
-no honest meaning — hooks exist for scenarios because a scenario run is a single
-pass by a single external process.
-
-A hook is not a pikku function: it has no id, no meta and no schema, so it
-cannot go through `runPikkuFunc` and the runner records nothing for it. It gets
-exactly what the scenario body gets — the same wire (which is how it reaches the
-app through `virtualUsers`) and singleton services composed with this invocation's
-wire services — and nothing else. `ScenarioHookError` keeps the original error
-as `cause`, so the failure that actually happened is never lost behind the label
-saying which phase it happened in.
-
-`onAfterRunFunc` returns early on the `interrupted` outcome, because the run is
-suspended or waiting and teardown would fire mid-flight. When the scenario has
-already failed for its own reason, an `after`-hook failure is attached as
-`cause` and logged rather than replacing the headline; only a teardown failure
-after a _passing_ scenario fails the run.
-
-At the feature level (`workflow.types.ts`, `CoreFeature`), hooks run once around
-the whole group — `before → a → b → c → after` — not per scenario. That is the
-one thing a feature deliberately cannot express: gherkin's `Background:` runs
-per scenario, and per-scenario setup is the scenario's own `before`.
-
-`setScenarioEnvironment` on the same service is per-service, not per-run, for a
-related reason: a runner process targets exactly one environment for every
-scenario it executes, so threading it through each run would only create ways
-for two runs in one process to disagree.
-
-**What this rules out:** offering hooks on plain workflows, routing a hook
-through `runPikkuFunc` so it gets recorded as a step, running `after` on an
-interrupted run, letting a teardown failure overwrite the scenario's own
-failure, or reinterpreting feature hooks as per-scenario `Background:`.

package/knowledge/decisions/internals/workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md

@@ -1,32 +0,0 @@
----
-type: decision
-title: Scenario prose is rendered out of typed calls, not parsed into them
-description: A readable report with no regex step registry to maintain
-tags: workflow
----
-
-# Scenario prose is rendered out of typed calls, not parsed into them
-
-`scenario-prose.ts` renders the English sentence a reporter shows for a scenario
-step. Instead of parsing English into a call
-through a registry of regexes, the call is typed and the English is rendered out
-of it. The readable report survives without anyone maintaining a step-definition
-registry, and a step that no longer exists cannot leave a dangling phrase behind.
-
-`renderScenarioProse` fills a step's `template` from the input the step was
-actually called with, so the sentence names the values under test — "sees
-@pikku/addon-todos" rather than "sees an addon in the gallery" three times over.
-A placeholder with no recorded value renders as nothing and the surrounding
-whitespace collapses, so an omitted optional input reads as a shorter sentence
-rather than leaking a literal `{state}` into the report. `template` is
-deliberately distinct from `description`: `description` documents what the step
-does, `template` is what a reader of the report sees, and it falls back to
-`description` when absent.
-
-It lives in `@pikku/core` rather than in the CLI so the CLI reporter and the
-console render the same sentence for the same step.
-
-**What this rules out:** adding a gherkin parser or regex step registry,
-rendering prose in the CLI reporter or console instead of core (the two would
-drift), collapsing `template` into `description`, or making a missing
-placeholder value render as the raw placeholder.

package/knowledge/decisions/internals/workflow-scenario-quarantine-reason-lives-in-code.md

@@ -1,18 +0,0 @@
----
-type: decision
-title: A quarantined scenario states its reason in code, not in a CI invocation
-description: `skip` carries the why next to the scenario it applies to, and naming the scenario explicitly still runs it
-tags: workflow
----
-
-# A quarantined scenario states its reason in code, not in a CI invocation
-
-`WorkflowsMeta`'s `skip` field (`workflow.types.ts`) is a string, not a boolean.
-A scenario held out of a default run has to say why, and stating the reason in
-code keeps the quarantine next to the scenario it applies to rather than buried
-in a CI invocation nobody reads. A skipped scenario is still runnable — naming
-it explicitly with `--flows` runs it regardless — so quarantine is a default,
-not a disablement.
-
-**What this rules out:** turning `skip` into a boolean flag, moving the skip
-list into CI configuration, or making a skipped scenario unrunnable.

package/knowledge/decisions/internals/workflow-scenario-step-targets-are-string-literals-for-the-inspector.md

@@ -1,34 +0,0 @@
----
-type: decision
-title: Scenario step targets are string literals so the inspector can read them statically
-description: `step/given/when/then` mirror `do`'s RPC shape because the extractor reads a literal, not an imported symbol
-tags: workflow
----
-
-# Scenario step targets are string literals so the inspector can read them statically
-
-`ScenarioStepInvocation` in `dsl/workflow-dsl.types.ts`, and the `step`,
-`given`, `when` and `then` members of `PikkuScenarioWire`, all take
-`(stepName, stepFunc: string, data?, options?)` — deliberately the same shape as
-`WorkflowWireDoRPC`. The target is a string, not an imported symbol, because
-the Pikku inspector is static analysis: it reads the argument as a literal and
-does not resolve identifiers. Type safety comes back at the edges — the
-generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
-
-`given`/`when`/`then` are pure sugar over `step`; the phase only changes the
-prose a reporter renders (`scenario-prose.ts`), never what executes.
-
-The prose direction is itself the decision: rather than parsing English into a
-call through a regex registry, `composeStepProse` renders English out of a typed
-call, so a readable report survives without a regex registry paying for it. It
-lives in core so the CLI reporter and the console render the same sentence for
-the same step, and `renderStepTemplate` fills `{placeholders}` from the input
-the step was actually called with — "sees @pikku/addon-todos" rather than the
-same generic sentence three times. A placeholder with no recorded value renders
-as nothing and the surrounding whitespace collapses, so an omitted optional
-input reads as a shorter sentence rather than leaking a literal `{state}`.
-
-**What this rules out:** changing `stepFunc` to accept the imported step config,
-reordering the arguments away from `do`'s shape, giving `given`/`when`/`then`
-behaviour of their own, or moving prose rendering into the CLI where the console
-would drift from it.

package/knowledge/decisions/internals/workflow-step-compensation-runs-as-its-own-durable-step.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: A step's compensation runs as a durable step of its own, declared on the function
-description: A refund or rollback must not fire twice on replay, so it is recorded as `<step>:compensate`; `onError` is gone
-tags: workflow
----
-
-# A step's compensation runs as a durable step of its own, declared on the function
-
-A function declares `compensate` inline on `pikkuFunc`. When a workflow unwinds,
-`driveUnwind` (`workflow-compensation.ts`) runs it as the step
-`<step>:compensate` through the same RPC path as a forward step. Durability is
-the point: a compensation is typically a refund or a rollback, and a bare invoke
-would fire again on every replay. Recorded as a step, a second pass finds it
-`succeeded` and returns the cached result. It uses the forward step's retry
-defaults, and a compensation cannot itself be compensated.
-
-`runPikkuFunc` and the RPC resolver derive the `<id>:compensate` function from
-the forward config lazily, so nothing extra is registered, and it is never
-exposed. What to undo, and in what order, is decided by the pure `planUnwind`
-from the recorded step rows — never from in-memory state, so a crash mid-unwind
-resumes at the next compensation.
-
-`onError` (DSL option and graph node field) was removed. Graph nodes recover
-with `recover`, which takes precedence over compensation.
-
-**What this rules out:** invoking the compensation inline "since it's just
-cleanup", compensating a compensation, a second unwind of a settled run, and
-swallowing the original failure because a handler succeeded.

package/knowledge/decisions/internals/workflow-step-dispatch-failure-is-transient-not-a-run-failure.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: A failed workflow step dispatch is transient infrastructure, not a run failure
-description: Queue-unreachable errors leave the run running and the step pending so the orchestrator replays; marking the run failed loses it
-tags: workflow
----
-
-# A failed workflow step dispatch is transient infrastructure, not a run failure
-
-`WorkflowDispatchException` (`pikku-workflow-service.ts`) means the queue itself
-could not accept the job — pg-boss momentarily down, the transport unreachable —
-not that the step's own logic failed. Everywhere it surfaces (`dispatchStep`,
-`sleepStep`, `startWorkflow`, `orchestrateWorkflow`) the run is left untouched:
-the step stays `pending`, the run stays `running`, and the orchestrator job is
-rethrown so the queue redelivers it and the workflow replays from its snapshot.
-
-The ordering inside `rpcStep` and `sleepStep` is load-bearing: dispatch happens
-BEFORE the step is marked `scheduled`. If the step were marked `scheduled`
-first and the dispatch then failed, the next replay would see `scheduled`,
-pause, and wait forever for a job that was never enqueued.
-
-Redelivery is always safe because an orchestrator job is idempotent: it replays
-the workflow from the snapshot and every already-completed step returns its
-cached result rather than running again. The per-job `attempts` that
-`resolveStepJobOptions` always emits is what makes redelivery happen at all — it
-overrides a queue configured with `retry_limit 0`, so the workflow's retry
-policy survives a conservative queue configuration.
-
-**What this rules out:** folding `WorkflowDispatchException` into the generic
-catch that calls `updateRunStatus(runId, 'failed', ...)`, swallowing it so the
-run silently stalls, or reordering `setStepScheduled` above `dispatchStep` /
-`scheduleSleep` to "keep the status writes together". Each strands or kills a
-run that a redelivered orchestrator tick would have recovered on its own.

package/knowledge/decisions/internals/workflow-step-lock-is-held-only-to-claim-the-step.md

@@ -1,34 +0,0 @@
----
-type: decision
-title: A workflow step lock is held only to claim the step, never across its execution
-description: Holding the step lock across step work exhausted the connection pool and self-deadlocked when it was an advisory lock; it stays claim-only on leases
-tags: workflow
----
-
-# A workflow step lock is held only to claim the step, never across its execution
-
-`executeWorkflowStep` in `pikku-workflow-service.ts` takes `withStepLock` for an
-atomic check-and-mark-running only: it reads the step, returns `null` if the
-step already `succeeded` or is already `running` (another worker owns it),
-starts a fresh attempt if it `failed`, and otherwise marks it `running`. The
-lock is then released, and the actual work plus result persistence run outside
-it.
-
-The guard is what makes that safe — once a step is `running`, any concurrent
-worker returns early. The alternative was tried and failed: holding the
-then-advisory lock, and therefore its pooled connection, across
-`executeGraphStep` (network I/O plus further pool queries) let concurrent steps
-exhaust the connection pool and self-deadlock.
-
-`withStepLock` is now a lease on the app's `leaseService`
-(`workflow-step:<runId>:<step>`), so it pins no connection. It still stays
-claim-only: a lease held across the work would have to outlive it, and a taken
-step lease already means "another dispatch owns it", so the claim answers
-`null`. Kysely and MongoDB claim with a status-guarded conditional update and do
-not take it at all.
-
-**What this rules out:** widening the `withStepLock` callback to cover RPC
-invocation, child-workflow start, `setStepResult` or `resumeWorkflow` — the
-"obviously safer" refactor that reintroduces the deadlock. If a stronger
-guarantee is ever needed it has to come from the claim itself, not from a longer
-lock hold.

package/knowledge/decisions/internals/workflow-step-rpc-name-is-provenance-only.md

@@ -1,34 +0,0 @@
----
-type: decision
-title: A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it
-description: It exists so a reader can join a runtime step row back to the declaration that produced it, especially when the durable name was built in a loop
-tags: workflow
----
-
-# A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it
-
-`insertStepState` and `inlineStep` in `pikku-workflow-service.ts` record the
-name a step was dispatched by: an RPC for a `workflow.do` step, a step function
-for a scenario step, `null` for a closure. Nothing in the engine dispatches off
-that value — it is stored so a reader can join a step back to the function that
-ran it.
-
-It earns its keep when the durable step name was built at runtime. A scenario
-step called in a loop reaches the run as, say, `sees @pikku/addon-todos` while
-it was declared as `sees ${packageName}`; the recorded step-function name is
-then the only way to join that row back to its declaration. `inlineStep` also
-records the `data` the step was called with for the same reason: a reporter
-renders each step's prose from it, so two calls to one step stay
-distinguishable by what they were asked to check.
-
-Step lineage is recorded alongside it. `fromStepName` is the predecessor that
-scheduled a step — the walked transition — captured by `rpcStep`/`inlineStep`
-_before_ `nextStepKey` advances the lineage, and surfaced to a step as
-`fromInvocationId`. In a cyclic graph `a → b → a → c`, the second `a` therefore
-carries `b`'s id, which is what lets the walked path be reconstructed from the
-chain alone.
-
-**What this rules out:** treating the recorded name as the dispatch target,
-dropping it for closure steps "since it is always null", capturing
-`lastStepName` after `nextStepKey` has run, or omitting `data` on inline steps —
-each breaks either the join back to source or the reconstructed path.

package/knowledge/decisions/internals/workflow-suspend-and-approval-reasons-are-durable-step-identities.md

@@ -1,38 +0,0 @@
----
-type: decision
-title: A suspend or approval `reason` is the step's durable identity, not just a message
-description: The reason is namespaced and used raw as the step key, so it must be derived deterministically across replays
-tags: workflow
----
-
-# A suspend or approval `reason` is the step's durable identity, not just a message
-
-`getSuspendStepName` and `getApprovalStepName` in `pikku-workflow-service.ts`
-derive a step key from the `reason` string — `__workflow_suspend:<reason>` and
-`__workflow_approval:<reason>`. Each distinct reason is therefore its own step
-row, which is what lets one workflow hold several independent suspends
-(wait-for-build, then wait-for-approval) and lets a dynamic reason inside a loop
-work exactly like a dynamic `do()` step name. The two prefixes are separate
-namespaces so a suspend, an approval, and a `do`/`sleep` step of the same name
-cannot collide.
-
-Because the reason IS the identity, it must be derived deterministically: the
-same replay must produce the same reason at the same point, or the run mints a
-new suspend instead of finding the one it is waiting on. This is the same
-contract as `do()` and `sleep()` step names.
-
-An approval additionally stores its record under a run-state key built by
-`approvalStateKey`, which hex-encodes the step name. The Mongo backend restricts
-state keys to `/^[a-zA-Z0-9_]+$/` while a reason is arbitrary human text, and
-one key per gate means two gates resolving concurrently cannot clobber each
-other through a read-modify-write.
-
-One consequence to know about: `approveStep`'s optional `reason` argument
-addresses the _first_ reach of a gate only. If a gate is reached again on a
-later loop iteration, `nextStepKey` gives that row a `#N` suffix, and there is
-currently no way for a caller to name it.
-
-**What this rules out:** deriving a reason from a timestamp, a random id or
-anything else that varies between replays; sharing one namespace (or one
-run-state key) between suspends and approvals; and storing the reason raw as a
-run-state key, which breaks on any backend that constrains key characters.

package/knowledge/decisions/internals/workflow-suspended-runs-keep-their-in-process-context.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: A suspended workflow run keeps its in-process context; only terminal runs release it
-description: `suspended` is absent from the terminal set on purpose, and a context is dropped only when nothing is holding it open
-tags: workflow
----
-
-# A suspended workflow run keeps its in-process context; only terminal runs release it
-
-`WORKFLOW_TERMINAL_STATES` in `pikku-workflow-service.ts` is
-`completed | failed | cancelled`. `suspended` is deliberately absent: a
-suspended run stops a poll loop but can still be resumed, so anything the
-process holds for it — the run context, an extension's per-run state such as a
-scenario's live virtual user clients — has to survive. `WORKFLOW_END_STATES`, which
-`awaitRunEnd` uses to stop reading, does include `suspended`, because a poller
-should not wait on a run that needs an external nudge. The two sets are not
-interchangeable.
-
-`releaseContext` drops a `RunContext` only when neither `inline` nor `replay`
-still holds it open, so an inline run mid-replay is never torn out from under
-itself. `updateRunStatus` releases on a terminal status because queued runs
-never pass through the inline path that would otherwise do it — without that,
-their context would be held for the life of the process. A long-lived server
-orchestrates many runs, so anything kept per run has to be released when that
-run stops executing here (`workflow-run-context.test.ts`).
-
-**What this rules out:** adding `suspended` to `WORKFLOW_TERMINAL_STATES`,
-collapsing the two state sets into one, or making `releaseContext`
-unconditional — the first two discard state a resume still needs, the third
-frees a context that an in-flight replay is still walking.

package/knowledge/decisions/security/a-bearer-token-checked-against-a-secret-reads-it-per-request.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: A bearer token checked against a secret is read per request, and an unreadable secret means no session
-description: The secretId form of authBearer reads the secret on every request; a missing or failing read leaves the request without a session rather than raising an error
-tags: core, middleware, auth
----
-
-# A bearer token checked against a secret is read per request, and an unreadable secret means no session
-
-In `packages/core/src/middleware/auth-bearer.ts:57-70`, a token given as a
-literal `value` is compared directly (`:59-60`). A token given a `secretId` is
-read from the secret service on each request (`:63-64`). A failed read is caught
-and becomes `undefined` (`:65`), and the code comments that an unset secret means
-the feature is off, never a request error (`:62`).
-
-An undefined expected value skips the comparison (`:68`). `userSession` stays
-null, and `setSession` is not called (`:55`, `:75-77`). A malformed scheme is a
-different case: it throws `InvalidSessionError` (`:50-53`).
-
-The static and JWT branches of this middleware are covered by the existing
-questions `a-bearer-jwt-with-no-identity-becomes-a-session.md` and
-`should-a-wrong-bearer-token-be-anonymous-or-refused.md`.
-
-**What this rules out:** turning a missing or unreadable signing secret into a
-server error, and caching the secret value across requests in the middleware
-closure.

package/knowledge/decisions/security/a-call-without-a-session-raises-missing-session-not-forbidden.md

@@ -1,20 +0,0 @@
----
-type: decision
-title: A call without a session raises MissingSessionError, and a missing scope raises MissingScopeError
-description: The function runner separates the no-session refusal from the scope and permission refusals, so a caller can tell a missing login from a denied grant
-tags: core, errors, sessions, scopes
----
-
-# A call without a session raises MissingSessionError, and a missing scope raises MissingScopeError
-
-`resolveSession` in `packages/core/src/function/function-runner.ts` (line 64) loads a stored session when there is a user id. It throws nothing.
-
-The refusal is in `executeFunction`. A sessionless function requires a session only when its wiring, its own config, or the addon says `auth: true` (`function-runner.ts:385-395`). That refusal throws `MissingSessionError` (`function-runner.ts:392`). A `pikkuFunc` with no session throws the same error unconditionally (`function-runner.ts:402`). The class is at `packages/core/src/errors/errors.ts:36`.
-
-Scope checks use a different error. `verifyScopes` throws `MissingScopeError` (`packages/core/src/scopes.ts:84-86`, class at `packages/core/src/errors/errors.ts:118`).
-
-Permission checks use `ForbiddenError` with the message `Permission denied` (`packages/core/src/permissions.ts:155`, `:166`, class at `packages/core/src/errors/errors.ts:57`).
-
-So the three refusals are distinct: no login, a missing scope, and a failed permission function.
-
-**What this rules out:** reporting a call with no session as a `ForbiddenError`, and reading a `ForbiddenError` from the runner as proof that a session exists but lacks a grant.

package/knowledge/decisions/security/a-caller-cookie-wins-over-the-jar-for-the-same-name.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: A cookie the caller sets wins over the jar's copy of the same name
-description: createCookieJar sends the caller's cookie for a name and drops the jar's copy of that name, so one request never carries the same cookie twice
-tags: core, scenario, cookies
----
-
-# A cookie the caller sets wins over the jar's copy of the same name
-
-In `createCookieJar` (`packages/core/src/services/scenario-cookie-jar.ts`)
-the jar builds the outgoing `cookie` header from the caller's own header and the
-jar's held cookies. A held cookie is left out when the caller's header already
-names it. The code comment says a request that already carries a session "is
-stating which one it means, and emitting the jar's copy alongside it sends the
-same name twice."
-
-The rule is per name, not per request. Cookies the caller did not name still go
-out from the jar. The jar's `Set-Cookie` handling, which replaces a reissued
-cookie rather than sending both, is covered by
-[Scenario sessions are isolated per virtual user and reset between scenarios](workflow-scenario-sessions-are-isolated-per-virtual-user-and-per-scenario.md).
-
-**What this rules out:** sending two values of one cookie name in a request, and
-letting the jar's held session override a session the caller has chosen to send.