@pikku/core 0.12.83 → 0.12.86

package/knowledge/decisions/internals/{ai-agent-onerror-hooks-cannot-change-the-failure.md → agent-onerror-hooks-cannot-change-the-failure.md}

@@ -1,15 +1,15 @@
 ---
 type: decision
-title: An aiMiddleware onError hook cannot change how a run fails
+title: An agentMiddleware onError hook cannot change how a run fails
 description: Hook throws are swallowed so observability code can never convert, mask, or replace the original error
-tags: ai-agent
+tags: agent
 ---
 
-# An aiMiddleware onError hook cannot change how a run fails
+# An agentMiddleware onError hook cannot change how a run fails
 
-Every `onError` invocation on the agent failure paths — in `streamAIAgent` and
-`continueAfterToolResult` (`ai-agent-stream.ts`) and in `runAIAgent` and
-`continueAfterToolResultSync` (`ai-agent-runner.ts`) — is wrapped in its own
+Every `onError` invocation on the agent failure paths — in `streamAgent` and
+`continueAfterToolResult` (`agent-stream.ts`) and in `runAgent` and
+`continueAfterToolResultSync` (`agent-runner.ts`) — is wrapped in its own
 `try/catch` that discards whatever the hook throws. The run is then marked
 `failed` with the original error message, and the original error propagates.
 

package/knowledge/decisions/internals/{ai-agent-runner-methods-must-keep-their-receiver.md → agent-runner-methods-must-keep-their-receiver.md}

@@ -2,18 +2,18 @@
 type: decision
 title: AI runner methods must be called on the runner, never as detached references
 description: Implementations use this internally, so grabbing transcribe or generateSpeech as a bare function loses the receiver and throws at runtime
-tags: ai-agent
+tags: agent
 ---
 
 # AI runner methods must be called on the runner, never as detached references
 
 The voice middlewares in `voice-input.ts` and `voice-output.ts` invoke
-`aiAgentRunner.transcribe(...)` and `aiAgentRunner.generateSpeech?.(...)` as
+`agentRunner.transcribe(...)` and `agentRunner.generateSpeech?.(...)` as
 method calls on the service object, and only ever test them for presence.
 
-`AIAgentRunnerService` is an interface implemented by classes — the reference
+`AgentRunnerService` is an interface implemented by classes — the reference
 implementation's `transcribe` calls `this.getModel(...)`. Extracting the method
-into a local (`const { transcribe } = services.aiAgentRunner`) type-checks
+into a local (`const { transcribe } = services.agentRunner`) type-checks
 cleanly and then fails at runtime with `this` undefined. The regression is
 pinned by a runner in `voice-input.test.ts` whose `transcribe` deliberately reads
 instance state through `this`.

package/knowledge/decisions/internals/agent-speech-travels-as-a-custom-agui-event.md

@@ -2,7 +2,7 @@
 type: decision
 title: Agent speech travels as a CUSTOM AG-UI event rather than being dropped
 description: AG-UI has no speech event, and dropping it makes a voice agent reached over HTTP silently inaudible while the provider still bills for the audio
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # Agent speech travels as a CUSTOM AG-UI event

package/knowledge/decisions/internals/{ai-agent-stream-persistence-is-best-effort.md → agent-stream-persistence-is-best-effort.md}

@@ -2,15 +2,15 @@
 type: decision
 title: Persisting an agent stream from send is best-effort and must never reject
 description: The persisting channel flushes fire-and-forget because send is synchronous; a storage failure degrades the transcript instead of killing the process
-tags: ai-agent
+tags: agent
 ---
 
 # Persisting an agent stream from send is best-effort and must never reject
 
 `createPersistingChannel` in
-`packages/core/src/wirings/ai-agent/ai-agent-stream.ts` accumulates step text,
+`packages/core/src/wirings/agent/agent-stream.ts` accumulates step text,
 tool calls and tool results, and writes them via `flushDetached` on the `usage`
-and `done` events. `AIStreamChannel.send` is synchronous, so it cannot await the
+and `done` events. `AgentStreamChannel.send` is synchronous, so it cannot await the
 write. An unawaited rejection has nothing to propagate to and surfaces as an
 `unhandledRejection`, which takes the whole server process down — a model
 reusing a `toolCallId`, which is a primary key in AI storage, is enough to
@@ -18,7 +18,7 @@ trigger it. `flushDetached` therefore catches and logs, and the run carries on.
 
 The awaited `flush()` on the suspend paths (`handleApprovals`,
 `handleCredentialRequests`) is the seam that still surfaces persistence failures
-to a caller. The regression test lives in `ai-agent-stream.test.ts`; because the
+to a caller. The regression test lives in `agent-stream.test.ts`; because the
 floating promise settles on a later macrotask, the assertion has to wait a real
 timer before checking that no `unhandledRejection` fired.
 

package/knowledge/decisions/internals/{ai-agent-sub-agents-inherit-the-parent-context-block.md → agent-sub-agents-inherit-the-parent-context-block.md}

@@ -2,14 +2,14 @@
 type: decision
 title: A delegated sub-agent inherits the parent run's context block
 description: The sub-agent tool schema carries only message and session, so the parent's identifier block is forwarded rather than re-typed by the model
-tags: ai-agent
+tags: agent
 ---
 
 # A delegated sub-agent inherits the parent run's context block
 
 `buildSubAgentRunInput` in
-`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` forwards the parent
-run's `AIAgentInput.context` — the "Current context" identifier block with
+`packages/core/src/wirings/agent/agent-prepare.ts` forwards the parent
+run's `AgentInput.context` — the "Current context" identifier block with
 organization, project and stage ids — into every delegated sub-agent run, on
 both the streaming and non-streaming paths. `buildToolDefs` threads it down as
 `parentContext` for the same reason.

package/knowledge/decisions/internals/{ai-agent-tool-execute-failures-are-logged-unconditionally.md → agent-tool-execute-failures-are-logged-unconditionally.md}

@@ -2,12 +2,12 @@
 type: decision
 title: A tool's execute() failure is logged before the AI SDK swallows it
 description: Every agent tool is wrapped in a logging try/catch, because a thrown tool error otherwise becomes a conversational reply and is invisible server-side
-tags: ai-agent
+tags: agent
 ---
 
 # A tool's execute() failure is logged before the AI SDK swallows it
 
-`buildToolDefs` in `packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`
+`buildToolDefs` in `packages/core/src/wirings/agent/agent-prepare.ts`
 wraps every tool it builds — RPC tools, sub-agent delegations and workflow tools
 alike — in a `try/catch` that logs through `singletonServices.logger` and
 rethrows.
@@ -18,7 +18,7 @@ and turns it into a conversational "tool error" reply to the model. The exceptio
 never reaches pikku's own logger, so without this wrapper a consistently failing
 tool is undiagnosable from the server side — the only symptom is an agent that
 keeps apologising. The wrapper is applied unconditionally, not only when an
-`aiMiddleware` `afterToolCall` hook happens to be registered.
+`agentMiddleware` `afterToolCall` hook happens to be registered.
 
 **What this rules out:** folding the logging into the optional middleware
 wrapper below it, and relying on the AI SDK's own error reporting for tool

package/knowledge/decisions/internals/{ai-agent-voice-input-transcribes-audio-parts-in-place.md → agent-voice-input-transcribes-audio-parts-in-place.md}

@@ -2,13 +2,13 @@
 type: decision
 title: Voice input transcribes audio parts sequentially and in place
 description: Each audio part is replaced by its text where it sat, one at a time, bounding concurrent downloads and preserving content order
-tags: ai-agent
+tags: agent
 ---
 
 # Voice input transcribes audio parts sequentially and in place
 
 The `voiceInput` middleware in
-`packages/core/src/wirings/ai-agent/voice-input.ts` walks the last user
+`packages/core/src/wirings/agent/voice-input.ts` walks the last user
 message's content parts in order and swaps each audio part for a text part at the
 same index, awaiting one transcription before starting the next.
 

package/knowledge/decisions/internals/{ai-agent-working-memory-is-persisted-only-when-valid.md → agent-working-memory-is-persisted-only-when-valid.md}

@@ -2,13 +2,13 @@
 type: decision
 title: Working memory is persisted only when the merged value validates
 description: A failed schema check logs and drops the update rather than saving it, because invalid state poisons every later read
-tags: ai-agent
+tags: agent
 ---
 
 # Working memory is persisted only when the merged value validates
 
 `createWorkingMemoryMiddleware` in
-`packages/core/src/wirings/ai-agent/ai-agent-memory.ts` parses the model's
+`packages/core/src/wirings/agent/agent-memory.ts` parses the model's
 `<working_memory>` block, deep-merges it into the stored value, validates the
 merge against the agent's working-memory schema when one is declared, and calls
 `saveWorkingMemory` only if the merge is valid. An invalid merge is logged as a

package/knowledge/decisions/internals/an-addon-scope-root-loses-to-a-root-the-host-already-declares.md

@@ -24,7 +24,7 @@ permissions bug rather than a merge that dropped.
 This is a different rule from
 [scope roots may be co-declared by an addon and its host
 app](scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md): that one
-is about `flattenScopeDefinitions` deduping ids *within* a build where both
+is about `flattenScopeDefinitions` deduping ids _within_ a build where both
 declarations are present and identical. This one is about the addon's copy never
 arriving. The consequence for addon authors is the same either way — own a root
 outright, named for the package or vendor, and nest everything under it. It is

package/knowledge/decisions/internals/an-agent-interrupt-is-not-a-failure.md

@@ -2,7 +2,7 @@
 type: decision
 title: An interrupt is not a failure, and the non-streaming path throws rather than returning
 description: It skips the onError hooks and never becomes an errorMessage; with no partial reply to hand back, a typed throw is what distinguishes it from a provider outage
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # An interrupt is not a failure
@@ -14,7 +14,7 @@ that did not happen.
 
 The streaming and non-streaming paths then diverge, because what they can hand
 back differs. A stream has already delivered part of the reply, so it returns
-that fragment. `runAIAgent` has delivered nothing — there is no partial answer to
+that fragment. `runAgent` has delivered nothing — there is no partial answer to
 return — so it throws a typed error instead. A caller can tell that apart from a
 provider outage, which returning an empty result would not allow.
 

package/knowledge/decisions/internals/an-agent-run-owned-by-another-instance-says-so.md

@@ -2,12 +2,12 @@
 type: decision
 title: An interrupt for a run owned by another instance says so, rather than returning false
 description: A bare false is indistinguishable from "already finished", which is the one deployment shape the in-process registry cannot cover
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # An interrupt for a run owned by another instance says so
 
-`interruptAIAgent` resolves a run through `aiRunState`, then tries to abort it
+`interruptAgent` resolves a run through `agentRunState`, then tries to abort it
 via the in-process registry. A run still marked `running` that this process has
 no abort handle for is executing on another instance.
 
@@ -19,7 +19,7 @@ the condition instead.
 
 **What this rules out:** collapsing the two outcomes into one boolean because
 the caller "only cares whether it stopped". The caller cares a great deal about
-the difference between *stopped* and *cannot be stopped from here*.
+the difference between _stopped_ and _cannot be stopped from here_.
 
 The fix for the underlying gap is `signalRunInterrupt`, which fans the interrupt
 out over `eventHub` so every instance tries locally.

package/knowledge/decisions/internals/an-agent-stream-send-must-return-the-inner-sends-promise.md

@@ -2,12 +2,12 @@
 type: decision
 title: A wrapped agent-stream send must return the inner send's promise
 description: Middleware runs asynchronously, so dropping the returned promise turns every awaited channel.send upstream into a no-op
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # A wrapped agent-stream send must return the inner send's promise
 
-`streamAIAgent` wraps the caller's channel so every event passes through the
+`streamAgent` wraps the caller's channel so every event passes through the
 stream middleware. That wrapper's `send` returns whatever the inner `send`
 returns, and it must: the middleware chain is asynchronous, so a wrapper that
 calls the inner `send` and returns `undefined` resolves immediately while the

package/knowledge/decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md

@@ -2,7 +2,7 @@
 type: decision
 title: A message with nothing to say carries no text part at all
 description: An attachment on its own is a real turn, and providers are entitled to reject an empty text part sitting beside it
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # A message with nothing to say carries no text part

package/knowledge/decisions/internals/an-empty-transcript-is-not-recorded.md

@@ -2,7 +2,7 @@
 type: decision
 title: A transcript is recorded only when something was actually heard
 description: Recording an empty string sends a transcript event saying the user said nothing, which renders as an empty bubble rather than a pending one
-tags: core, ai-agent
+tags: core, agent
 ---
 
 # A transcript is recorded only when something was actually heard

package/knowledge/decisions/internals/channel-message-handlers-accept-three-config-shapes.md

@@ -14,7 +14,7 @@ things a caller may put on `onMessage` or inside `onMessageWiring`:
 - a direct function config, where `onMessage.func` is a plain `Function`;
 - a wrapper, where `onMessage.func` is itself a `CorePikkuFunctionConfig` and so
   has its own nested `.func`;
-- a simple wrapper, which carries a plain `Function` under `func` *and* a
+- a simple wrapper, which carries a plain `Function` under `func` _and_ a
   sibling `middleware` array.
 
 The `isWrapper` check tests exactly that: an object with `func`, where either

package/knowledge/decisions/internals/channel-middleware-caches-only-statically-resolved-middleware.md

@@ -19,7 +19,7 @@ user's stream and growing memory run over run. It is therefore appended fresh on
 every call, after the cached inherited slice.
 
 The `uid` matters as much as the cache split. `processMessageHandlers` in
-`channel-handler.ts` builds it from the channel name *plus* the routing property
+`channel-handler.ts` builds it from the channel name _plus_ the routing property
 and router value (`${name}:${routingProperty}:${routerValue}`, or
 `${name}:default`), because several message routes on one channel may point at
 the same function — a key based on the function alone would serve one route's

package/knowledge/decisions/internals/channel-user-id-is-persisted-after-onconnect-middleware-runs.md

@@ -10,7 +10,7 @@ tags: channel
 `runChannelConnect` in
 `packages/core/src/wirings/channel/serverless/serverless-channel-runner.ts`
 reads `userSession.getPikkuUserId()` and calls `channelStore.setPikkuUserId`
-*after* `runChannelLifecycleWithMiddleware` has executed the `onConnect`
+_after_ `runChannelLifecycleWithMiddleware` has executed the `onConnect`
 lifecycle, not before.
 
 Auth middleware runs as part of that lifecycle — it is what inspects the upgrade

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