@pikku/core 0.12.84 → 0.12.86

package/knowledge/decisions/internals/core-schema-defaults-apply-on-every-transport.md

@@ -21,7 +21,7 @@ generated TypeScript type declares as present — the worst shape a mismatch can
 take: validation permits the omission, the type promises the value, the body
 reads `undefined`.
 
-It is deliberately *not* gated on the `coerceDataFromSchema` flag that guards
+It is deliberately _not_ gated on the `coerceDataFromSchema` flag that guards
 `coerceTopLevelDataFromSchema`. That flag is about decoding transport-encoded
 values — a query string's `"1,2"` into an array, an ISO string into a `Date` —
 and is set only by transports that need it. Defaults are a property of the

package/knowledge/decisions/internals/core-scopes-are-an-and-gate-separate-from-permissions.md

@@ -14,8 +14,8 @@ closed: a session without a `scopes` field, or no session at all, satisfies
 nothing. An empty `required` is the only thing anything satisfies.
 
 This is deliberately the opposite composition from `permissions`, whose groups OR
-together. Because permissions OR, adding a permission group can only *widen*
-access; because scopes AND, adding a scope can only *narrow* it. That is the
+together. Because permissions OR, adding a permission group can only _widen_
+access; because scopes AND, adding a scope can only _narrow_ it. That is the
 whole reason the two are separate mechanisms and separate code paths rather than
 one merged authorization step, and it is why a passing global or function
 permission must never be allowed to satisfy a scope.
@@ -24,7 +24,7 @@ Satisfaction itself is hierarchical, computed by `satisfyingGrants`: a grant
 matches when it is the scope itself, a plain ancestor (`admin` covers
 `admin:invoices:create`), a wildcard at or above it (`admin:*`, or the bare `*`),
 or a wildcard directly beneath it. Narrower never satisfies broader —
-`admin:invoices` does not grant `admin`. Core only ever *reads*
+`admin:invoices` does not grant `admin`. Core only ever _reads_
 `session.scopes`; whoever builds the session populates it (better-auth's
 `mapSession` resolving through a `ScopeService`, for instance), and the runner
 never fetches. `hasScopes` is the non-throwing counterpart of `verifyScopes`, for

package/knowledge/decisions/internals/gateway-adapters-resolve-lazily-and-are-promise-cached.md

@@ -13,7 +13,7 @@ platform adapters (WhatsApp Cloud API, Slack, …) need both, so
 `resolveGatewayAdapter` in
 `packages/core/src/wirings/gateway/gateway-runner.ts` invokes the factory on the
 first inbound request (webhook/websocket) or on gateway start (listener). The
-`resolvedAdapters` WeakMap caches the *promise*, not the resolved adapter, so
+`resolvedAdapters` WeakMap caches the _promise_, not the resolved adapter, so
 concurrent first requests share one construction instead of racing to build two
 adapters — which for a stateful adapter would mean two platform connections.
 

package/knowledge/decisions/internals/gateway-listener-middleware-runs-without-an-rpc-on-the-wire.md

@@ -10,8 +10,8 @@ tags: core, gateway
 `runPikkuFunc` in `packages/core/src/function/function-runner.ts` attaches `rpc`
 to the invocation wire with `Object.defineProperty`, as a lazy getter that
 replaces itself on first read — and restores the previous descriptor in its
-`finally`. `rpc` therefore exists on a wire *only for the duration of a function
-invocation*. That is why `PikkuRawWire` is `Omit<PikkuWire, 'rpc'>`: it is the
+`finally`. `rpc` therefore exists on a wire _only for the duration of a function
+invocation_. That is why `PikkuRawWire` is `Omit<PikkuWire, 'rpc'>`: it is the
 wire as a runner constructs it, before the function runner adds `rpc`.
 
 The three gateway transports reach middleware differently:
@@ -22,7 +22,7 @@ The three gateway transports reach middleware differently:
   same invocation — `wire.rpc` is live.
 - **listener** has no such wrapper. `createListenerMessageHandler` is handed
   straight to `adapter.init()` by the `GatewayService`, builds
-  `const wire: PikkuRawWire = {}` itself, and runs `config.middleware` *before*
+  `const wire: PikkuRawWire = {}` itself, and runs `config.middleware` _before_
   `invoke()` reaches `runPikkuFunc`. There is no invocation in progress, so
   `wire.rpc` is `undefined`.
 
@@ -34,7 +34,7 @@ off `CorePikkuMiddleware`, whose wire parameter is `PikkuWire`.
 **What this rules out:** treating the assertion at that call as noise to be
 deleted. It is naming a real gap. It also rules out "just widen
 `CorePikkuMiddleware` to accept `PikkuRawWire`" as a free fix — that would make
-`rpc` optional for *every* middleware in the framework, pushing the problem onto
+`rpc` optional for _every_ middleware in the framework, pushing the problem onto
 every consumer to satisfy one transport.
 
 **Still open:** whether the listener path should wrap its handler in a

package/knowledge/decisions/internals/gateway-wiring-is-a-meta-wiring-over-http-and-channels.md

@@ -18,7 +18,7 @@ followed by `httpRouter.reset()` because the router caches its match table.
 The wrapper functions and routes created here look like they are missing their
 metadata. They are not: the inspector projects a `wireGateway` call into the
 generated HTTP and function meta at build time, so only the handler
-*implementations* register at runtime — the same split every other wire uses.
+_implementations_ register at runtime — the same split every other wire uses.
 This is why `wireWebhookGateway` writes route entries but no `CommonWireMeta`,
 and why the websocket path sets `channels.set(name, …)` with empty
 `onConnect`/`onMessage` stubs while the real handlers live under the

package/knowledge/decisions/internals/http-router-matches-normalized-paths-but-returns-registered-ones.md

@@ -11,7 +11,7 @@ tags: http
 normalizes every route and every incoming path to a leading `/` before matching,
 so a route registered as `'todos'` still answers a request for `/todos`. The
 `route` field it stores alongside each matcher and static entry is the
-*un-normalized* original, and that is what `MatchResult.route` returns.
+_un-normalized_ original, and that is what `MatchResult.route` returns.
 
 That asymmetry is load-bearing. `getMatchingRoute` in `http-runner.ts` takes the
 returned route and uses it as a key into `pikkuState(null, 'http', 'routes')` and

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

@@ -12,7 +12,7 @@ tags: services
 `invoke` throws, and it throws with a truncated body — which is why a scenario
 asserting on a refusal must use `invokeRaw`.
 
-A permissions or scopes scenario *expects* the 403. The status is the assertion,
+A permissions or scopes scenario _expects_ the 403. The status is the assertion,
 and the body usually names the scope that was missing, so both have to survive as
 data rather than being reduced to a thrown `Error`. These helpers also exist
 because every scenario reaching past an actor was hand-writing the same

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

@@ -9,7 +9,7 @@ tags: services
 
 `InMemoryWorkflowService` (`packages/core/src/services/in-memory-workflow-service.ts`)
 stores each step twice: in `steps`, keyed `${runId}:${stepName}`, and appended to
-`stepHistory` for the run. Both hold the *same object*. `createStepImpl` and
+`stepHistory` for the run. Both hold the _same object_. `createStepImpl` and
 `createRetryAttemptImpl` push the reference they just put into `steps`, not a
 copy.
 

package/knowledge/decisions/internals/index.md

@@ -10,6 +10,7 @@ A rule about how core behaves: what runs where, in what order, and what a
 caller is entitled to assume.
 
 <!-- pikku:knowledge-index -->
+
 - [A non-streaming agent run registers with aiRunState on the same terms as a streaming one](a-non-streaming-agent-run-registers-with-airunstate-too.md) — Otherwise interruptAIAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
 - [A resumed turn is as interruptible as the first one](a-resumed-agent-turn-is-as-interruptible-as-the-first.md) — It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
 - [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
@@ -57,7 +58,7 @@ caller is entitled to assume.
 - [CLI stdout is reserved for machine-readable output](cli-stdout-is-reserved-for-machine-readable-output.md) — The default renderer emits single-line NDJSON, diagnostics go to stderr, and --json only hijacks rendering for commands that declared a renderer
 - [CLI unknown long options warn instead of failing](cli-unknown-long-options-warn-instead-of-failing.md) — Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
 - [A column's at-rest form is an axis of its own](core-column-form-is-an-axis-of-its-own.md) — How a value is stored is independent of how sensitive it is, so form carries a required nominal brand on writes while classification stays optional on reads
-- [The data-classification brand is an optional property](core-data-classification-brand-is-an-optional-property.md) — Making __classification__ required would break ordinary Kysely operands, so the brand only constrains values flowing out
+- [The data-classification brand is an optional property](core-data-classification-brand-is-an-optional-property.md) — Making **classification** required would break ordinary Kysely operands, so the brand only constrains values flowing out
 - [The function runner restores the wire fields it overwrites](core-function-runner-restores-the-wire-fields-it-overwrites.md) — One wire object is reused across nested calls, so functionId, audit, addonNamespace and rpc are saved and put back in a finally
 - [Hot reload merges generated meta and never replaces it](core-hot-reload-merges-generated-meta-never-replaces-it.md) — Reloading codegen output must preserve runtime-registered meta, which no generated JSON contains
 - [Hot reload owns its module registry instead of re-importing](core-hot-reload-owns-its-module-registry.md) — Dev reload transpiles to CJS and runs modules through vm.compileFunction, because the native ESM loader map cannot be evicted
@@ -103,7 +104,7 @@ caller is entitled to assume.
 - [The agent `done` event goes through the middleware and is awaited](the-agent-done-event-goes-through-the-middleware-and-is-awaited.md) — `done` is the only end-of-reply signal a stream hook gets, and buffering hooks flush on it — sending it raw discards work already paid for
 - [The API report pins members, because the export list only pins names](the-api-report-pins-members-not-just-names.md) — public-surface.json catches an export appearing or vanishing; it cannot see a method added to an interface, which is the change that breaks a consumer's build
 - [The dev queue copies prod timing and serialization semantics](the-dev-queue-copies-prod-timing-and-serialization-semantics.md) — InMemoryQueueService dispatches via setTimeout, retries with backoff, and JSON round-trips every payload so dev behaviour matches a real backend
-- [The ecosystem entry point carries the adapter surface, so the root can promise stability](the-ecosystem-entry-point-carries-the-adapter-surface.md) — runPikkuFunc and the singleton-service accessors are what a runtime adapter reaches for; their signatures move, and the package root should not promise otherwise
+- [One door per name — the ecosystem tier and the package root are both gone](the-ecosystem-entry-point-carries-the-adapter-surface.md) — the adapter surface was split onto @pikku/core/ecosystem to keep a stability promise at the root; publishing every module twice cost more than the promise was worth, so both the facades and the root barrel were deleted
 - [The embedding model is pinned per service and doc/query embedding is split](the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md) — AIEmbeddingService fixes its model at construction so index and query share a vector space, and separates embedDocuments from embedQuery for asymmetric models
 - [The in-memory workflow service is inline-only and single-process](the-in-memory-workflow-service-is-inline-only-and-single-process.md) — InMemoryWorkflowService wires no queues and implements withRunLock/withStepLock as pass-throughs, because inline execution has no second holder to exclude
 - [The KEK salt is scoped to the key version, not the secret](the-kek-salt-is-scoped-to-the-key-version.md) — One stored salt per key version means N secrets cost one derivation, which is the point of envelope encryption
@@ -153,4 +154,5 @@ caller is entitled to assume.
 - [A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it](workflow-step-rpc-name-is-provenance-only.md) — It exists so a reader can join a runtime step row back to the declaration that produced it, especially when the durable name was built in a loop
 - [A suspend or approval `reason` is the step's durable identity, not just a message](workflow-suspend-and-approval-reasons-are-durable-step-identities.md) — The reason is namespaced and used raw as the step key, so it must be derived deterministically across replays
 - [A suspended workflow run keeps its in-process context; only terminal runs release it](workflow-suspended-runs-keep-their-in-process-context.md) — `suspended` is absent from the terminal set on purpose, and a context is dropped only when nothing is holding it open
+
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/internals/istanbul-statement-counts-attach-to-the-start-line-only.md

@@ -9,7 +9,7 @@ tags: services
 
 `IstanbulCoverageService` (`packages/core/src/services/istanbul-coverage-service.ts`)
 reads instrumented counters off the `__coverage__` global and, when turning
-statement maps into line hits, credits each statement's count to its *start* line
+statement maps into line hits, credits each statement's count to its _start_ line
 and no other line it spans.
 
 This is istanbul's own semantics, and the reason matters: statements nest. An

package/knowledge/decisions/internals/one-project-shape-check-two-validators.md

@@ -29,7 +29,7 @@ Two of workspace validate's own checks were not merely absent from fabric — th
 had never run anywhere:
 
 - the auth checks were gated on a middleware instance with `definitionId ===
-  'betterAuthSession'`, but the CLI wires `betterAuthStatelessSession` whenever
+'betterAuthSession'`, but the CLI wires `betterAuthStatelessSession` whenever
   `session.cookieCache` is on, which is the configuration Fabric asks for. So
   they skipped precisely the apps most likely to have auth.
 - they looked for migrations in `packages/functions/db/`, and for tables named

package/knowledge/decisions/internals/queue-jobs-always-carry-an-explicit-attempts-count.md

@@ -10,7 +10,7 @@ tags: services
 `QueueWebhookService.resolveJobOptions`
 (`packages/core/src/services/queue-webhook-service.ts`) resolves retries as
 per-call `retries` → `config.webhook.retries` → `DEFAULT_WEBHOOK_RETRIES`, then
-*always* puts `attempts: retries + 1` on the job options. It mirrors the workflow
+_always_ puts `attempts: retries + 1` on the job options. It mirrors the workflow
 service's policy resolution. Backoff is exponential unless a concrete
 `retryDelay` selects a fixed one.
 

package/knowledge/decisions/internals/remote-addons-dispatch-over-http-instead-of-local-meta.md

@@ -15,7 +15,7 @@ handlers run on the host at `serverUrl`. `pikku verify` enforces the
 devDependency placement.
 
 `ContextAwareRPCService.invokeAddonFunction` in `rpc-runner.ts` therefore checks
-`resolved.addonConfig?.remote` *before* it looks for local function meta, and
+`resolved.addonConfig?.remote` _before_ it looks for local function meta, and
 routes to `invokeRemoteAddonFunction`. That method POSTs the addon's own function
 name — the bare name, not the namespaced `ns:fn` form, optionally remapped by
 `remoteName` — to `${serverUrl}/remote/rpc/:rpcName`, authenticating as a client

package/knowledge/decisions/internals/rpc-names-resolve-through-package-scope-before-root.md

@@ -15,7 +15,7 @@ throws `RPCNotFoundError`. It returns the resolving package alongside the
 `runPikkuFunc` without a second lookup.
 
 The package-first order exists because RPC meta only ever lives in root: addon
-packages register their handlers under their own package name as *function* meta,
+packages register their handlers under their own package name as _function_ meta,
 never as RPC meta. Without the package probe, a bare `rpc('doThing')` made from
 inside an addon would skip that addon's own `doThing` and either resolve to an
 unrelated root function of the same name or fail outright. The versioned retry

package/knowledge/decisions/internals/scenario-given-and-when-are-sugar-but-then-is-not.md

@@ -12,8 +12,8 @@ All three run a named `pikkuScenarioStep` as one durable step. `given` and
 identically either way.
 
 `then` is a different operation. The phase is what decides how a step's surface
-bindings are treated: for an action, the bindings are *alternatives* and one is
-chosen; for an assertion, they are *witnesses* and every applicable one runs and
+bindings are treated: for an action, the bindings are _alternatives_ and one is
+chosen; for an assertion, they are _witnesses_ and every applicable one runs and
 must agree. So the same step function invoked as `when` and as `then` executes a
 different number of times against a different number of surfaces.
 

package/knowledge/decisions/internals/scenarios-live-in-files-named-for-them.md

@@ -14,11 +14,11 @@ a directory listing which files ship and which files test.
 
 So `validate` requires the declaration to be in a file named for what it is:
 
-| declaration | file |
-| --- | --- |
-| `pikkuScenario`, `pikkuFeature` | `*.scenario.ts`, `*.scenarios.ts` |
-| `pikkuScenarioStep` and its platform/addon variants | `*.steps.ts` (or the above) |
-| `definePersonas`, `runVirtualUser` | `*.virtual-user.ts`, `*.vu.ts` |
+| declaration                                         | file                              |
+| --------------------------------------------------- | --------------------------------- |
+| `pikkuScenario`, `pikkuFeature`                     | `*.scenario.ts`, `*.scenarios.ts` |
+| `pikkuScenarioStep` and its platform/addon variants | `*.steps.ts` (or the above)       |
+| `definePersonas`, `runVirtualUser`                  | `*.virtual-user.ts`, `*.vu.ts`    |
 
 Three suffixes for scenarios rather than one, because the split that matters is
 scenarios apart from application code, not a particular spelling — `.steps.ts`

package/knowledge/decisions/internals/the-actor-prompt-says-json-because-of-json-object-mode.md

@@ -8,7 +8,7 @@ tags: core, actor-flow
 # The actor's instructions say the word "json"
 
 Every call the actor makes wants a schema'd object back. A gateway that cannot
-accept a JSON *schema* degrades to OpenAI's `json_object` response mode, and
+accept a JSON _schema_ degrades to OpenAI's `json_object` response mode, and
 that mode refuses the request outright — a hard API error, not a bad answer —
 unless the literal word "json" appears somewhere in the prompt.
 

package/knowledge/decisions/internals/the-api-report-pins-members-not-just-names.md

@@ -9,7 +9,7 @@ tags: core, api
 
 `public-surface.json` records `Object.keys(module)` for every entry point. That
 is a real guard — it caught a new `./node-host-resolver` subpath and five
-renames during a rebase — but it only sees *names*.
+renames during a rebase — but it only sees _names_.
 
 It cannot see:
 

package/knowledge/decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md

@@ -1,11 +1,49 @@
 ---
 type: decision
-title: The ecosystem entry point carries the adapter surface, so the root can promise stability
-description: runPikkuFunc and the singleton-service accessors are what a runtime adapter reaches for; their signatures move, and the package root should not promise otherwise
+title: One door per name — the ecosystem tier and the package root are both gone
+description: the adapter surface was split onto @pikku/core/ecosystem to keep a stability promise at the root; publishing every module twice cost more than the promise was worth, so both the facades and the root barrel were deleted
 tags: core, api
 ---
 
-# The ecosystem entry point carries the adapter surface
+# One door per name
+
+**Reversed.** The section below records why `@pikku/core/ecosystem` existed; it
+is kept because the stability argument that produced it is still true and still
+constrains what the subpaths may promise. What changed is the mechanism.
+
+## What holds now
+
+Every name lives on the subpath that owns the module it comes from, and every
+import carries that subpath: `@pikku/core/http`, `@pikku/core/services`,
+`@pikku/core/errors`, `@pikku/core/types`. There is no second specifier for the
+same module and no package root — `.` resolves to a bootstrap shim, not an entry
+point.
+
+The facades did not survive contact with their own premise. `ecosystem/http`
+re-exported `./http`, so a name was reachable through either door; every
+addition had to be made twice, they drifted (25 names had accumulated in the
+facade tier with no raw home, and about 26 more sat under a different area than
+the module they came from), and a consumer's import told you nothing about what
+it used. The package root was the same failure at a larger scale: 206 names in
+one barrel that no bundler could take apart.
+
+The stability distinction the split was built to express is now carried by
+`public-surface.json` and `api-report.md`, which pin what each entry point
+exports. Moving a symbol across an area boundary is still a visible diff; it
+just no longer requires a parallel tree of re-export files to be visible.
+
+Two modules survive at the old specifiers and are not entry points:
+`bootstrap-compat/root.ts` and `bootstrap-compat/ecosystem.ts` exist because
+`packages/cli` is generated by the published CLI pinned in its `build.sh`, which
+still emits `@pikku/core/ecosystem` and a bare `@pikku/core`. A test pins their
+exact contents so neither can grow, and both go when the pin moves to a CLI
+released from this branch.
+
+**What this rules out:** re-introducing any specifier that re-exports another
+subpath's names. A curated facade over a module that is already published is the
+thing that was tried; adding a name to two places is how it decays.
+
+## Why the split existed (superseded)
 
 `@pikku/core` has two kinds of consumer. An **application** writes functions and
 wires them: `pikkuFunc`, `wireHTTP`, `PikkuWire`, the error catalogue. A
@@ -40,19 +78,5 @@ i.e. _the real API_, which is the opposite of the intended signal, and
 `packages/runtimes/*` already claims the word while `packages/cli` is the
 largest consumer here at 22 files.
 
-`/ecosystem` says the true thing: you are building a package in the Pikku
-ecosystem — a runtime, a service, an addon, the CLI. `/internal` remains as an
-alias to the same module because the pinned bootstrap CLI still emits it.
-
-Nothing was deleted. What stayed public is what applications actually
-hand-write: `addTagMiddleware` (8 files), `addGlobalPermission`, `fetch` (31),
-`wireAddon`, and the authoring helpers.
-
-**What this rules out:** re-exporting anything from `/internal` at the package
-root for convenience. The split is the whole point — `/internal` may change in
-any release, and the root may not. It also rules out treating `/internal` as
-private: it is a published entry point that runtime authors are expected to use,
-just without the compatibility guarantee.
-
-`public-surface.json` pins both, so moving a symbol across the line is a visible
-diff rather than an accident.
+`/ecosystem` said the true thing: you are building a package in the Pikku
+ecosystem — a runtime, a service, an addon, the CLI.

package/knowledge/decisions/internals/the-persona-runtime-is-exported-from-the-persona-entry-point.md

@@ -9,7 +9,7 @@ tags: core, services
 
 `HttpPersona`, `createHttpPersonas`, `readScenarioHttpResponse` and
 `postScenarioJson` are exported from `@pikku/core/persona`, not from
-`@pikku/core/services`. Their *types* are re-exported freely — TypeScript erases
+`@pikku/core/services`. Their _types_ are re-exported freely — TypeScript erases
 those and they cost a bundle nothing.
 
 The values are different. They reach `http-personas`, which reaches the

package/knowledge/decisions/internals/the-worker-disposition-is-the-one-that-is-not-testing.md

@@ -7,7 +7,7 @@ tags: core, virtual-user
 
 # The worker disposition is the only one not testing anything
 
-Every other disposition exists to probe the product. The worker exists to *use*
+Every other disposition exists to probe the product. The worker exists to _use_
 it, which changes every parameter: it abandons rarely, runs at a low temperature,
 and is instructed to stop and report rather than guess its way past an obstacle.
 

package/knowledge/decisions/internals/validate-runs-checks-by-precondition.md

@@ -10,7 +10,7 @@ tags: cli, validate, addons
 `pikku workspace validate` was named after one of the things a repo can be.
 Adding a second — "is this addon publishable" — invited a second command,
 `pikku addon validate`, and that is where the naming falls apart: the addons
-repo is a workspace *containing* 217 publishable addons. Standing at its root,
+repo is a workspace _containing_ 217 publishable addons. Standing at its root,
 `pikku addon validate` would have to refuse or sweep every package, at which
 point it is doing the workspace thing anyway. The two nouns were never
 alternatives.
@@ -67,7 +67,7 @@ and the published packages had drifted from it with nothing watching.
 ## The check walks whichever generated directory a package ships
 
 `dist/.pikku` is the target shape (below), but the check cannot assume it: the
-shape is what this work moved addons *to*, and a package that has not moved —
+shape is what this work moved addons _to_, and a package that has not moved —
 or was published before it did — still carries `.pikku` at the root, listed in
 `files` and mapped by `exports` as `./.pikku/*`. There it is a public entry
 point rather than build input, and its imports climb one level fewer — to
@@ -100,7 +100,7 @@ workspace link and none of it resolved on install.
 ## Only a package that publishes gets the dist shape
 
 The shape describes a tarball, so it means nothing for a `private` package —
-and applying it there actively breaks: `exports` *is* enforced across a
+and applying it there actively breaks: `exports` _is_ enforced across a
 workspace link, so repointing a private fixture at `dist` makes every consumer
 demand a directory that only a build produces. The three `verifiers/db-schema`
 and `verifiers/addon-registry` fixtures have no build script at all, so `dist`

package/knowledge/decisions/internals/virtual-user-step-order-comes-from-insertion-order.md

@@ -18,4 +18,4 @@ costs work to reproduce a fact that already holds.
 
 **What this rules out:** "correcting" this to a topological walk because a graph
 is present. The graph describes execution; the catalogue describes what the
-scenario *says*, and those are read in declaration order.
+scenario _says_, and those are read in declaration order.

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

@@ -9,7 +9,7 @@ tags: services
 
 `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.
+`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.
 

package/knowledge/decisions/internals/wiring-registries-erase-the-generics-their-wire-functions-capture.md

@@ -16,7 +16,7 @@ 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
+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

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

@@ -14,7 +14,7 @@ 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
+`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

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

@@ -20,7 +20,7 @@ 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
+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.
 

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

@@ -18,7 +18,7 @@ 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
+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.

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

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

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

@@ -15,7 +15,7 @@ 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
+_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, actors, lifecycle hooks, the browser

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

@@ -7,7 +7,7 @@ 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
+`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,

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

@@ -30,11 +30,15 @@ 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.
 
-`requireActor` and `requireScenarioEnv` (`scenario-step-guards.ts`) exist for
-the mirror-image reason: `actor` and `env` are optional on the step wire because
-a pure assertion step needs neither, so the narrowing happens in one place with
-a message that says what to do, instead of every step file writing its own
-guard. `scenarioStep`'s `verifyStepName` call doubles as the guard for `then`
+`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 actor is not narrowed at
+all — a step that runs as somebody declares `actor: true` (or a `browser`
+binding, which cannot be provisioned without a window to open), and the runner
+injects `wire.actor` 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.
 

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

@@ -25,7 +25,7 @@ saying which phase it happened in.
 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.
+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

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

@@ -15,7 +15,7 @@ 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
+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
@@ -23,7 +23,7 @@ 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
+_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.

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

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

package/knowledge/decisions/security/a-function-never-receives-the-secret-service.md

@@ -24,7 +24,7 @@ impossible rather than merely reported: secrets are resolved where things are
 constructed — `pikkuServices`, `pikkuWireServices`, addon service factories,
 middleware — and the function is handed the configured client.
 
-The cost is that a function which needs to *ask about* a secret rather than read
+The cost is that a function which needs to _ask about_ a secret rather than read
 one — "is this key set?", for a readiness or provisioning check — cannot do it
 directly either. It goes through a service that holds `secrets` and exposes only
 that question, which is how `@pikku/addon-console` checks whether an installed

package/knowledge/decisions/security/a-step-runs-the-function-the-workflow-dispatched-it-with.md

@@ -11,7 +11,7 @@ tags: workflow
 off the queue message and hands it to `executeWorkflowStep`. That call runs as
 the run's owner — `invokeStepRpc` copies `run.wire.pikkuUserId` onto the wire —
 and `rpcWithWire` does not apply the `expose` gate that the public `/rpc` route
-applies. So the message decided both *what* ran and *as whom*.
+applies. So the message decided both _what_ ran and _as whom_.
 
 The claim in `executeWorkflowStepInner` read the step's status and nothing else;
 there was no stored function name to compare against. `StepState` now carries

package/knowledge/decisions/security/a-virtual-user-is-never-offered-a-step-that-would-forge-its-own-oracle.md

@@ -11,11 +11,10 @@ tags: core, virtual-user
 platform and addon steps, from what a virtual user may call.
 
 For scenario bodies the argument is only efficiency: they are held out of every
-deployed unit and are not network-callable, so offering one wastes a turn on a
-404.
+deployed unit and are not network-callable, so offering one wastes a turn on a 404.
 
 For a platform or addon step the argument is the oracle itself. A virtual user's
-findings are worth something *because* it cannot manufacture the outcomes it is
+findings are worth something _because_ it cannot manufacture the outcomes it is
 meant to discover. A user that could invoke "Stripe's webhook arrives" forges its
 own payment success, and every finding downstream of that forgery is worthless —
 not merely unreliable, but actively misleading, because it looks like evidence.

package/knowledge/decisions/security/actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md

@@ -15,7 +15,7 @@ header even though the response was a 2xx.
 A cookie jar cannot answer "did sign-in happen". A target app may set a cookie on
 any request — a CSRF token, an anonymous session, a locale — so a non-empty jar
 after a failed or skipped sign-in looks exactly like a successful one. What
-actually proves a session was established is *this* response setting a cookie. A
+actually proves a session was established is _this_ response setting a cookie. A
 2xx alone is not enough either: an endpoint that returns 200 while quietly
 declining to issue a session would leave the actor running every subsequent
 request unauthenticated, and the scenario would report the resulting refusals as

package/knowledge/decisions/security/addon-auth-and-tags-only-tighten.md

@@ -18,7 +18,7 @@ it is closed the same way: `runPikkuFunc` resolves both from the addon config.
 `auth` merges as an OR and `auth: false` is ignored. The RPC path treats it as a
 default (`addonConfig?.auth ?? options.requiresAuth`) because there the addon
 config is the only statement of intent. On a direct wiring the route already
-carries its own `auth`, so honouring `false` would let an addon *weaken* a gate
+carries its own `auth`, so honouring `false` would let an addon _weaken_ a gate
 the app wrote — the inverse of what a wiring-level declaration should be able to
 do. An addon may require a session the wiring did not; it may never waive one
 the wiring did.

package/knowledge/decisions/security/agent-gate-requires-a-session-only-when-auth-is-true.md

@@ -13,7 +13,7 @@ session presence (only when `CoreAgent.auth === true`), then `scopes`, then
 `permissions`. The ordering mirrors the function runner — scopes AND together so
 they can only narrow access, and a missing scope short-circuits before any
 permission function does I/O. Declared `scopes` are narrowed to the generated
-`ScopeId` union in a project's `pikku-types.gen.ts`, so an undeclared scope is a
+`ScopeId` union in a project's `#pikku/scopes`, so an undeclared scope is a
 compile error.
 
 `auth` defaults to `false` (i.e. `pikkuSessionlessFunc`, not `pikkuFunc`) because