@pikku/core 0.12.84 → 0.12.88

package/knowledge/decisions/internals/cli-option-names-are-camelcase-in-state-and-kebab-on-the-command-line.md

@@ -19,7 +19,7 @@ the conversion happens. The parser normalises every incoming `--from-plan` to
 `fromPlan` on the way in, and both `formatOptions` (help text) and the
 "Missing required option" / "Invalid value for" errors render back to kebab on
 the way out. `suggestOption` deliberately compares the typed string against
-*both* forms, so `--autoApply` and `--auto-apply` both find `autoApply`.
+_both_ forms, so `--autoApply` and `--auto-apply` both find `autoApply`.
 
 **What this rules out:** storing option keys kebab-cased anywhere in CLI state or
 metadata — the schema pluck would then match nothing and every option would be

package/knowledge/decisions/internals/cli-parse-errors-are-routed-by-message-prefix.md

@@ -18,7 +18,7 @@ mistake (show the help text) or a value mistake (print the errors) by
 This is why the parser pushes `Missing subcommand: <path>` for a group command
 that has subcommands but no `pikkuFuncId` of its own, rather than simply
 returning the command meta and letting the runner discover it is unrunnable. The
-message *is* the routing signal. Rewording any of those three strings, or
+message _is_ the routing signal. Rewording any of those three strings, or
 localising them, silently turns "show me the subcommands" into a raw error dump.
 
 **What this rules out:** editing those error message prefixes without updating

package/knowledge/decisions/internals/cli-unknown-long-options-warn-instead-of-failing.md

@@ -18,7 +18,7 @@ The reason is forward compatibility: a script or wrapper written against a newer
 command version may pass options an older installed binary does not know, and
 failing hard there turns a harmless extra flag into a broken pipeline.
 `RESERVED_OPTIONS` exempts flags the runner handles itself (`help`) from the
-warning. Unknown *short* flags are treated differently — they go to
+warning. Unknown _short_ flags are treated differently — they go to
 `result.errors` and do fail — because a bundled short-flag cluster like `-abc`
 cannot be reliably attributed, and a typo'd short flag is far more likely than a
 version skew.

package/knowledge/decisions/internals/core-column-form-is-an-axis-of-its-own.md

@@ -15,13 +15,13 @@ value leave the process?".
 The two axes were one field before this, with `security: 'encrypted'` sitting
 alongside `secret` as though they were alternatives. They are not, and the
 conflation made the field unanswerable: a token hash and a live bearer token are
-both `secret`, one must never be encrypted — the digest *is* the lookup key —
+both `secret`, one must never be encrypted — the digest _is_ the lookup key —
 and the other must always be. Nothing in a single enum could tell them apart, so
 nothing could check either.
 
 ## Why `wrapped` and `sealed` rather than `encrypted`
 
-Sealed values *are* encrypted, so an `encrypted` member sitting beside `sealed`
+Sealed values _are_ encrypted, so an `encrypted` member sitting beside `sealed`
 would be a supertype posing as a sibling, and every new column would be an
 even-odds guess. What actually separates them is who can read the value back:
 `wrapped` is symmetric and the application holds the key; `sealed` is asymmetric
@@ -64,7 +64,7 @@ it would buy nothing — feeding in the wrong string already fails at the AEAD t
 — while forcing a cast into every path that reads ciphertext out of a row or off
 the wire, which is where casts are least reviewable.
 
-The brand proves *provenance*, not correctness. It cannot know a value was
+The brand proves _provenance_, not correctness. It cannot know a value was
 wrapped under the right key, and making it know would mean phantom-typing key
 ids per scope, which the multi-recipient path would fight constantly.
 
@@ -75,7 +75,7 @@ error. Every project predating the axis has such columns, and failing their next
 `db migrate` would be a breaking change for a diagnosis they have not had a
 chance to act on. `pikku db --fail-on-warn` is how a project opts into the
 ratchet. An explicit `form: 'plain'` silences it — that is the acknowledgement
-that reading the row is *meant* to yield a usable credential.
+that reading the row is _meant_ to yield a usable credential.
 
 **What this rules out:** collapsing `wrapped` and `sealed` back into one
 `encrypted`; making the form brands optional (they would enforce nothing);

package/knowledge/decisions/internals/core-data-classification-brand-is-an-optional-property.md

@@ -16,7 +16,7 @@ A required property would make a plain value unassignable to a branded column: a
 `string` could no longer be passed where `Private<string>` is expected, which
 breaks every ordinary Kysely query operand — `where('email', '=', someString)`,
 inserts, and `.set(...)`. Making it optional keeps the brand structurally present
-so static analysis still sees it, while letting plain values flow *in*. The
+so static analysis still sees it, while letting plain values flow _in_. The
 asymmetry is the point: the brand constrains what comes out of a query, not what
 goes into one.
 

package/knowledge/decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md

@@ -9,7 +9,7 @@ tags: core
 
 `runPikkuFunc` in `packages/core/src/function/function-runner.ts` does not build a
 fresh wire per call. Nested invocations — an RPC from inside a function, an addon
-sibling call, a workflow step — reuse the *same* wire object the outer transport
+sibling call, a workflow step — reuse the _same_ wire object the outer transport
 created. So before it runs, the runner captures `functionId`, `audit`,
 `addonNamespace` and the property descriptor for `rpc`, overwrites them for the
 duration of this function, and restores or `delete`s them in a `finally`. Both
@@ -18,7 +18,7 @@ inner call would leave its identity on the wire and every subsequent outer step
 would be attributed to the wrong function.
 
 The same reuse is why the audit binding is re-gated inside `executeFunction`
-rather than trusted from `createWireServices`. The audit *gate* is per-function
+rather than trusted from `createWireServices`. The audit _gate_ is per-function
 but the `auditLog` wire service is created per-transport-invocation. A nested or
 exposed-RPC call would otherwise inherit an `auditLog` built while the outer
 wire's audit config was unset (the generated `rpcCaller` declares none), and
@@ -32,7 +32,7 @@ then the auth/readonly checks, then `verifyScopes` — all of which depend only
 the session — and only then `await data()`, schema defaults, coercion, validation
 and `runPermissions`. A request denied by scope never pays to parse or validate
 its body. `rpc` is installed as a lazily-evaluating accessor that replaces itself
-with the resolved value on first read, capturing the *caller's* package name in
+with the resolved value on first read, capturing the _caller's_ package name in
 the closure so an addon's RPCs resolve in its own namespace.
 
 **What this rules out:** dropping the save/restore blocks as duplicated

package/knowledge/decisions/internals/core-hot-reload-merges-generated-meta-never-replaces-it.md

@@ -22,7 +22,7 @@ workflow job fails with `Function meta not found: pikkuWorkflowOrchestrator`.
 `dev/reload-meta.test.ts` pins this. Meta maps that only codegen ever writes
 (`http`, `rpc`, `agent`) are assigned outright.
 
-Two limits are inherent rather than incidental. Routes registered by a *new*
+Two limits are inherent rather than incidental. Routes registered by a _new_
 `wireHTTP` file are not picked up here — those modules were never imported — which
 is why `hot-reload.ts` keeps a `postCodegenQueue` and exposes `reimportPending()`
 for the dev server to drain after codegen, so registrations that were skipped for
@@ -35,5 +35,5 @@ entry stranded until a restart.
 `pikkuState(null, 'function', 'meta', functionsMeta)` assignments on the grounds
 that codegen output is authoritative — it is authoritative only for what codegen
 emits. It also rules out folding `reimportPending()` back into the debounced
-reload (the whole point is that it runs *after* codegen), and dropping
+reload (the whole point is that it runs _after_ codegen), and dropping
 `reconcileAddonRegistry` as dead code.

package/knowledge/decisions/internals/core-hot-reload-owns-its-module-registry.md

@@ -23,7 +23,7 @@ edits, and eventually OOMs a long editing session. `dev/module-runner.test.ts`
 asserts both the single-slot guarantee and bounded heap growth.
 
 Two details keep the mechanism honest. `import`s inside the user file are
-delegated to `createRequire`, whose resolution matches the native loader *and*
+delegated to `createRequire`, whose resolution matches the native loader _and_
 returns the same live singletons (Node and Bun share the require/import cache) —
 that is what lets a reloaded file's top-level `wireHTTP` side effects mutate the
 services the running server is already using. And esbuild is invoked with no
@@ -37,6 +37,6 @@ code.
 import(url + '?t=' + Date.now())` or any fresh-URL variant, and turning
 sourcemaps back on for nicer stack traces (`filename` already anchors traces to
 the user file). It also rules out swapping `createRequire` for a fresh `import()`
-inside the compiled module — resolution would produce a *distinct* copy of every
+inside the compiled module — resolution would produce a _distinct_ copy of every
 dependency, and the reloaded file would then wire itself into services nobody is
 serving from.

package/knowledge/decisions/internals/core-middleware-order-is-scope-then-priority.md

@@ -19,7 +19,7 @@ finally passed through `freezeDedupe` and cached in `middlewareCache` keyed by
 wire type and wire id.
 
 Two properties fall out of that and both are load-bearing. Because the sort is
-stable, priority is a coarse band and registration order breaks ties *within* a
+stable, priority is a coarse band and registration order breaks ties _within_ a
 band, so declaration order still means something. And because the result is
 deduped by function identity, a middleware reachable through both a tag group and
 a direct wire registration runs exactly once — a fact several tests assert

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