@pikku/core 0.12.83 → 0.12.86

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/speech-synthesis-picks-a-voice-per-sentence-and-warns-once.md

@@ -2,7 +2,7 @@
 type: decision
 title: Speech synthesis picks a voice per sentence but announces a limitation once
 description: A bilingual reply should speak the half it can, and repeating the notice for every sentence would bury the reply itself
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # Speech synthesis picks a voice per sentence, and warns once per reply

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-agent-done-event-goes-through-the-middleware-and-is-awaited.md

@@ -2,7 +2,7 @@
 type: decision
 title: The agent `done` event goes through the middleware and is awaited
 description: `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
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # The agent `done` event goes through the middleware and is awaited

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-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md

@@ -24,6 +24,6 @@ same call.
 
 **What this rules out:** adding a per-call `model` parameter, collapsing
 `embedDocuments` and `embedQuery` into one `embed`, and pointing a vector store
-at `AIAgentRunnerService.embed` / `embedMany` instead — those take a per-call
+at `AgentRunnerService.embed` / `embedMany` instead — those take a per-call
 model on purpose and drag in the whole agent-runner tool loop, and they give back
 neither guarantee.

package/knowledge/decisions/internals/the-per-invocation-rpc-view-is-a-class.md

@@ -11,16 +11,16 @@ tags: core, rpc, performance
 an object literal, and that literal declared `get agent()` so the agent facade
 stayed lazy — most requests never touch it, and reading it builds five closures.
 
-The laziness is right. Declaring the accessor *on the literal* was not: a
+The laziness is right. Declaring the accessor _on the literal_ was not: a
 literal containing an accessor needs a real property descriptor per instance,
 which takes it off V8's fast object-literal construction path and slows the
 whole object, not just the accessor.
 
 Measured with `benchmarks/bench-profile-granular.ts`, three runs each:
 
-| shape | per call |
-| --- | --- |
-| object literal with `get agent()` | 1.106 / 1.433 / 1.147 µs |
+| shape                               | per call                 |
+| ----------------------------------- | ------------------------ |
+| object literal with `get agent()`   | 1.106 / 1.433 / 1.147 µs |
 | class with `agent` on the prototype | 0.523 / 0.461 / 0.525 µs |
 
 Roughly 2.4×, well outside the run-to-run variance, on a path every request
@@ -28,7 +28,7 @@ takes. On the same machine a full `fetchData` measures 12–19µs, so this was o
 the order of a tenth of a request spent constructing one object.
 
 The obvious alternative is worse. Making `agent` an eager property removes the
-accessor but builds those five closures unconditionally, and measured *slower*
+accessor but builds those five closures unconditionally, and measured _slower_
 than the original at 1.967µs. A prototype accessor is the only shape that keeps
 the laziness and the fast construction path.
 

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-transcript-event-is-sent-ahead-of-the-run.md

@@ -2,7 +2,7 @@
 type: decision
 title: A voice turn's transcript is sent before the run starts, on the raw channel
 description: The client does not know what it said, and an answer starts streaming within a few hundred milliseconds — a question arriving after its answer reads as the wrong question
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # A voice turn's transcript is sent ahead of the run
@@ -10,7 +10,7 @@ tags: core, ai-agent
 A voice client sends audio, so it does not know what it said. Until the
 transcript reaches it, its own message renders as a blank bubble.
 
-The event is sent *before* the run rather than alongside it because the answer
+The event is sent _before_ the run rather than alongside it because the answer
 begins streaming within a few hundred milliseconds. Sent concurrently, the
 transcript routinely lands after the first tokens of its own answer — and a
 question that appears beneath its answer reads as a question about something

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/thread-history-records-the-transcript-not-the-audio.md

@@ -2,7 +2,7 @@
 type: decision
 title: Thread history records what the model was asked, which for a spoken turn is the transcript
 description: The wire carried a base64 audio blob; persisting it writes megabytes of unreadable data and loses the only readable record of the turn
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # Thread history records the transcript, not the audio that arrived
@@ -13,7 +13,7 @@ carried a base64 audio blob, and `voiceInput` replaced it with a transcript
 before the model ever saw it.
 
 Persisting the blob would write megabytes of unreadable data into the history
-*and* discard the only readable record of what was said — the worst of both.
+_and_ discard the only readable record of what was said — the worst of both.
 
 Both the streaming and non-streaming paths do this, and both check identity
 rather than assuming: a middleware is free to rewrite the message list into

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/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md

@@ -2,7 +2,7 @@
 type: decision
 title: Only an explicit `false` silences a spoken reply
 description: The key being absent means no voice input is wired and nothing reported either way, so those callers keep the behaviour they had before the option existed
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # Only an explicit `false` silences a spoken reply

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/{ai-agent-approval-forwarding-requires-a-symbol-brand.md → agent-approval-forwarding-requires-a-symbol-brand.md}

@@ -2,16 +2,16 @@
 type: decision
 title: Only a Symbol-branded framework result can request tool approval
 description: Approval markers are trusted from the APPROVAL_REQUIRED Symbol on a forwardsApproval tool, never from a JSON key an LLM could emit
-tags: ai-agent
+tags: agent
 ---
 
 # Only a Symbol-branded framework result can request tool approval
 
 `checkForApprovals` in
-`packages/core/src/wirings/ai-agent/ai-agent-stream.ts` honours a forwarded
+`packages/core/src/wirings/agent/agent-stream.ts` honours a forwarded
 approval only when both hold: the tool declares `forwardsApproval` (set solely by
 framework code on the sub-agent delegating tools built in
-`ai-agent-prepare.ts`), and its result carries the `APPROVAL_REQUIRED` unique
+`agent-prepare.ts`), and its result carries the `APPROVAL_REQUIRED` unique
 Symbol. The companion `__approvalRequired` string key exists for transport, but
 is never what the decision reads.
 

package/knowledge/decisions/security/{ai-agent-credential-requests-are-symbol-branded.md → agent-credential-requests-are-symbol-branded.md}

@@ -2,14 +2,14 @@
 type: decision
 title: Credential requests are trusted only when Symbol-branded
 description: The string key is a wire field; the Symbol is the capability, and only core can mint it
-tags: ai-agent
+tags: agent
 ---
 
 # Credential requests are trusted only when Symbol-branded
 
 A tool result asking the run to suspend and prompt for a credential is honoured
 only when it carries the `CREDENTIAL_REQUIRED` Symbol minted in
-`ai-agent-prepare.ts`. `checkForCredentialRequests` in `ai-agent-stream.ts`
+`agent-prepare.ts`. `checkForCredentialRequests` in `agent-stream.ts`
 tests for that Symbol, never for the `__credentialRequired` string key that
 travels beside it on the wire.
 
@@ -24,7 +24,7 @@ primitive inside the product's own UI. This mirrors the `APPROVAL_REQUIRED`
 brand, which exists for the identical reason one function over.
 
 The brand survives because the object is passed by reference the whole way —
-core's `buildToolDefs` wrapper returns it, the Vercel adapter's `aiTool` hands
+core's `buildToolDefs` wrapper returns it, the Vercel adapter's `agentTool` hands
 it back verbatim, and the AI SDK puts the raw value on the stream part rather
 than the JSON form it builds separately for the model.
 
@@ -33,5 +33,5 @@ result` for convenience, or introducing any path where a credential request is
 reconstructed from parsed JSON rather than passed by reference — either one
 silently converts the gate into a formality. Note the inverse holds for the
 `credentialFilteredChannel` suppression later in the same file: that one
-deliberately matches the *string* key, because it hides tool results from the
+deliberately matches the _string_ key, because it hides tool results from the
 client and a broader match leaks less, not more.

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

@@ -2,18 +2,18 @@
 type: decision
 title: An agent requires a session only when auth is true, but always enforces scopes and permissions
 description: Agents follow pikkuSessionlessFunc semantics so crons and queue workers can run them; scopes are an AND gate checked before any permission I/O
-tags: ai-agent
+tags: agent
 ---
 
 # An agent requires a session only when auth is true, but always enforces scopes and permissions
 
 `assertAgentAuthorized` in
-`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` enforces, in order:
-session presence (only when `CoreAIAgent.auth === true`), then `scopes`, then
+`packages/core/src/wirings/agent/agent-prepare.ts` enforces, in order:
+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

package/knowledge/decisions/security/{ai-agent-ownership-failures-never-echo-the-resource.md → agent-ownership-failures-never-echo-the-resource.md}

@@ -2,13 +2,13 @@
 type: decision
 title: An agent ownership failure never echoes the resource it refused
 description: assertResourceOwner throws a bare ForbiddenError so the error cannot be used as an existence oracle, at the cost of thinner debugging output
-tags: ai-agent
+tags: agent
 ---
 
 # An agent ownership failure never echoes the resource it refused
 
 `assertResourceOwner` in
-`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` compares a stored
+`packages/core/src/wirings/agent/agent-prepare.ts` compares a stored
 thread/run `resourceId` against the caller's composed owner key and throws
 `ForbiddenError('Not authorized to access this thread' | '… run')` on a
 mismatch. The message deliberately carries no id.