@pikku/core 0.12.143 → 0.12.145

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

@@ -1,25 +0,0 @@
----
-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: agent
----
-
-# Working memory is persisted only when the merged value validates
-
-`createWorkingMemoryMiddleware` in
-`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
-warning and discarded.
-
-Working memory is read back into the system prompt on every subsequent run of the
-thread, so a bad write is not a one-turn mistake — it is a permanently malformed
-prompt that the model then has to reason around, and which the model itself
-cannot repair. Dropping the update is recoverable; the next turn simply tries
-again.
-
-**What this rules out:** saving first and validating on read, persisting the raw
-model output before the merge, and treating a validation failure as fatal to the
-run.

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

@@ -1,39 +0,0 @@
----
-type: decision
-title: An addon's scope root loses to a root the host app already declares
-description: loadAddonFunctionsMeta merges addon scope trees by root name, first declaration wins, so an addon sharing a root with its host contributes nothing — silently
-tags: services
----
-
-# An addon's scope root loses to a root the host app already declares
-
-`loadAddonFunctionsMeta`
-(`packages/inspector/src/utils/load-addon-functions-meta.ts`) reads each wired
-addon's `pikku-scopes-meta.gen.json` and pushes its entries into
-`state.scopes.definitions`, skipping any whose root name is already present. The
-host app's own declarations were inspected first, so the host always wins.
-
-The skip is per **root**, not per node. An addon declaring `admin.console.*` in
-an app that declares `admin` contributes none of it — not the root it shares,
-and not the branch the app never declared. Nothing errors: the scopes simply do
-not exist, so `ScopeId` never gains them, no role can be granted one, and every
-addon function requiring one denies everybody. The failure surfaces as a
-`MissingScopeError` against a scope that cannot be granted, which reads as a
-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
-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
-why `@pikku/addon-console` declares `pikku:console:*` rather than
-`admin:console:*`.
-
-**What this rules out:** shipping an addon whose scopes hang off a root a host
-is likely to declare, and deep-merging the two trees here so both survive. A
-merge would have to reconcile conflicting descriptions and display names for the
-shared nodes, and would let an addon graft capabilities onto the host's `admin`
-tree — where a role granting `admin` would pick them up without anyone having
-asked for them.

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

@@ -1,23 +0,0 @@
----
-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, agent
----
-
-# An interrupt is not a failure
-
-Interrupting a run skips the `onError` hooks entirely and never becomes an
-`errorMessage`. Someone asked the agent to stop and it stopped; that is the
-feature working, and running failure handlers over it would report an incident
-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. `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.
-
-**What this rules out:** unifying the two paths on "return whatever you have".
-For the non-streaming path that is an empty string, and an empty string is
-indistinguishable from a model that answered with nothing.

package/knowledge/decisions/internals/an-agent-is-offered-under-its-registry-key-and-only-within-the-virtual-users-scopes.md

@@ -1,27 +0,0 @@
----
-type: decision
-title: A reachable agent is offered by its registry key, filtered by the virtual user's scopes
-description: reachableAgents offers an agent to a virtual user under the key it is registered with, and only when the virtual user holds the agent's declared scopes; the server still enforces access
-tags: core, virtual-users, agents, scopes
----
-
-# A reachable agent is offered by its registry key, filtered by the virtual user's scopes
-
-`packages/core/src/wirings/virtual-user/virtual-user-agents.ts` decides which agents
-a virtual user is told about.
-
-An agent with no declared scopes is offered to everybody (`virtual-user-agents.ts:54-55`).
-The doc comment says undeclared is not the same as denied (`virtual-user-agents.ts:45-46`).
-Otherwise the agent is offered only when the virtual user's scopes satisfy the agent's
-scopes (`virtual-user-agents.ts:57`, `hasScopes`).
-
-The name offered is the registry key, not the agent's display name. The code uses
-`name: id` (`virtual-user-agents.ts:59-60`), and the doc comment says the display
-name "is frequently something else entirely", and offering it makes the run die
-on a 500 (`virtual-user-agents.ts:30-37`).
-
-The doc comment says this filter narrows only what is offered. The server decides
-who may talk to which agent (`virtual-user-agents.ts:39-44`).
-
-**What this rules out:** offering an agent name the server cannot resolve, and
-treating the offer list as the access check.

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

@@ -1,25 +0,0 @@
----
-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, agent
----
-
-# An interrupt for a run owned by another instance says so
-
-`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.
-
-Returning a bare `false` there is indistinguishable from "the run already
-finished" — the ordinary, uninteresting outcome. So the single deployment shape
-the in-process registry does not cover, multi-instance, fails silently: an agent
-that will not stop talking, and nothing in the logs to say why. The call reports
-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 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

@@ -1,22 +0,0 @@
----
-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, agent
----
-
-# A wrapped agent-stream send must return the inner send's promise
-
-`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
-event is still in flight.
-
-Every `await channel.send(...)` upstream then becomes a no-op that resolves
-before the thing it is waiting for has happened. The one that matters is the
-final flush — a buffering hook such as `voiceOutput` is still synthesizing audio
-when the awaited send resolves, and the `close()` that follows discards it.
-
-**What this rules out:** writing the wrapper as a fire-and-forget `(msg) => {
-inner.send(msg) }`, which reads as equivalent and is not.

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

@@ -1,20 +0,0 @@
----
-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, agent
----
-
-# A message with nothing to say carries no text part
-
-When a turn has no text, the text part is omitted rather than included as an
-empty string.
-
-An attachment on its own is a legitimate turn — a spoken one carries audio and
-no text whatsoever — so "no text" is a normal state, not a degenerate one.
-Providers are entitled to reject a message part with empty content, and that
-rejection would land on a caller who never wrote any text to begin with.
-
-**What this rules out:** normalising the text to `''` for a uniform message
-shape. Uniformity here buys nothing and costs a provider error on the one turn
-type that most needs to work.

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

@@ -1,22 +0,0 @@
----
-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, agent
----
-
-# A transcript is recorded only when something was actually heard
-
-A turn can carry audio that reads entirely as non-speech and still have content
-— an image with a silent caption clip — so there is nothing above to throw.
-`voiceInput` records the transcript only when speech was found.
-
-Writing `''` instead would emit a transcript event asserting that the user said
-nothing. A client that distinguishes "not transcribed yet" from "transcribed"
-by whether the key is present would then render that turn as a permanently
-empty bubble rather than a pending one — a worse outcome than showing nothing,
-because it looks settled.
-
-**What this rules out:** defaulting the transcript to an empty string for a
-uniform event shape. Absence and emptiness mean different things to the client,
-and only absence is recoverable.

package/knowledge/decisions/internals/an-oauth2-credential-implies-an-optional-app-secret.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: An OAuth2 credential implies its app client secret, optional and overridable by declaration
-description: deriveOAuth2AppSecrets creates the app client id and secret for each OAuth2 credential, marked optional, unless the project already declares that secret id
-tags: core, secrets, credentials, oauth2
----
-
-# An OAuth2 credential implies its app client secret, optional and overridable by declaration
-
-`packages/core/src/wirings/secret/derive-oauth2-app-secrets.ts` adds the app's
-client id and secret for each OAuth2 credential a project declares. The doc comment
-says the pair has the same shape every time, so writing it by hand "bought nothing"
-and was often skipped (`derive-oauth2-app-secrets.ts:7-12`).
-
-- A secret id that is already declared is skipped, so an explicit declaration
-  wins and keeps its own description or `docsUrl` (`derive-oauth2-app-secrets.ts:25`,
-  `31`, and the comment at `derive-oauth2-app-secrets.ts:14-15`).
-- The derived secret has `optional: true` (`derive-oauth2-app-secrets.ts:38-39`).
-  The comment says an addon that also authenticates by API key "must still deploy
-  without an OAuth app configured" (`derive-oauth2-app-secrets.ts:17-19`).
-- The OAuth2 settings (token secret, URLs, scopes, PKCE, extra params) are copied
-  from the credential (`derive-oauth2-app-secrets.ts:41-49`).
-
-**What this rules out:** requiring a deployment to configure an OAuth app for a
-credential that is not used, and a derived secret overriding one the author
-declared.

package/knowledge/decisions/internals/an-unref-d-timer-cannot-be-awaited-under-node-test.md

@@ -1,66 +0,0 @@
----
-type: decision
-title: An unref'd timer cannot be awaited under node:test
-description: The channel RPC registry unrefs its timeout so a pending call never holds a process open, which makes that timeout unawaitable in a test and silently cancels the rest of the file
-tags: core, channel, testing
----
-
-# An unref'd timer cannot be awaited under node:test
-
-`ChannelRPCRegistry.register()` schedules the call's timeout and then unrefs it:
-
-```ts
-// Never hold the process open waiting on a peer that may not answer.
-timer?.unref?.()
-```
-
-That is correct, and should stay. A server shutting down must not be held open
-for up to 30 seconds per in-flight reverse RPC.
-
-It also means the timeout can never fire in a test that awaits it. An unref'd
-timer does not keep the event loop alive, so when the pending call is the only
-thing left the loop drains first, and node:test reports:
-
-```
-Promise resolution is still pending but the event loop has already resolved
-```
-
-The damage is not local. That one test hangs, the runner cancels the **file**,
-and every later test in it is reported `cancelledByParent` — 32 of them in
-`channel-rpc.test.ts`, of which only two were the actual problem. Worse, the
-count moves: under a full-suite run other ref'd handles sometimes keep the loop
-alive long enough for the timer to land, so the file reported `32 cancelled` or
-`1 fail + 31 cancelled` depending on timing. Two of the "failures" were tests
-that pass perfectly well on their own.
-
-Reproducible with no project code at all — a bare `node --test` file where one
-test awaits a ref'd timer and one awaits an unref'd one passes the first and
-cancels the second.
-
-**The fix belongs in the test, not the registry.** Use the test-scoped mock
-clock and drive it by hand:
-
-```ts
-test('times out instead of hanging forever', async (t) => {
-  t.mock.timers.enable({ apis: ['setTimeout'] })
-  const registry = new ChannelRPCRegistry(10)
-  const call = registry.register()
-
-  const rejected = assert.rejects(call.promise, ...)  // attach BEFORE ticking
-  t.mock.timers.tick(10)
-  await rejected
-})
-```
-
-`t.mock.timers` is scoped to the test and resets itself, so tests that want a
-real clock are unaffected. Attach the rejection handler before ticking, or the
-rejection lands unhandled.
-
-**What this rules out:** dropping the `unref` to make the tests pass. That
-trades a test-only annoyance for a production one — every in-flight call would
-then pin the process during shutdown. Also rules out reading a cancelled count
-in this file as a count of broken tests; check which test actually hangs first,
-because the rest are collateral.
-
-Related: [[the-api-report-pins-members-not-just-names]] for the other case where
-a measurement in this repo counted the wrong thing convincingly.

package/knowledge/decisions/internals/analytics-identity-resolvers-run-in-declared-order.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: Analytics identity resolvers run in declared order so consent is read before a cookie is minted
-description: composeAnalyticsIdentity threads each resolver's output into the next, so a cookie-minting resolver sees the consent that an earlier resolver read
-tags: core, analytics, consent
----
-
-# Analytics identity resolvers run in declared order so consent is read before a cookie is minted
-
-`composeAnalyticsIdentity` in `packages/core/src/analytics/compose-analytics-identity.ts:22-35`
-runs the resolvers in the order given. Each one receives the accumulated result of
-the ones before it (`:26`, `:29`), and its output is merged over that result (`:31-33`).
-
-The doc comment at `:8-15` states the ordering rule: a resolver that mints a cookie
-may do so only once consent has been read, so the consent reader has to come first.
-A later resolver wins a key it sets (`:17-18`).
-
-The cookie-side rule is in `a-first-party-cookie-is-written-only-after-its-purposes-consent.md`.
-That note does not record the order in which the resolvers are composed.
-
-**What this rules out:** running a cookie-minting resolver ahead of the consent
-reader, and merging independent resolver results so that no resolver sees another's output.

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

@@ -1,30 +0,0 @@
----
-type: decision
-title: Channel message handlers accept three config shapes
-description: onMessage may be a function config, a wrapper with middleware, or a wrapper around a function config — the runtime discriminates structurally
-tags: channel
----
-
-# Channel message handlers accept three config shapes
-
-`processMessageHandlers` in
-`packages/core/src/wirings/channel/channel-handler.ts` has to tell apart three
-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
-  sibling `middleware` array.
-
-The `isWrapper` check tests exactly that: an object with `func`, where either
-`func` is an object that itself has `func`, or the object also has `middleware`.
-Only a wrapper contributes message-level middleware; a direct config contributes
-none. `wireChannel` in `channel-runner.ts` performs the mirror-image unwrapping
-when registering the function, using `(handler as any).func instanceof Function`
-to decide whether to register the handler or its inner `func`.
-
-**What this rules out:** narrowing on a single property (`'middleware' in
-onMessage` alone misclassifies a nested function config; `'func' in onMessage`
-alone misclassifies a direct config), and reducing the accepted shapes without
-updating both this discriminator and the registration path in `wireChannel`.

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

@@ -1,31 +0,0 @@
----
-type: decision
-title: Channel middleware caching covers only statically resolved middleware
-description: Inherited tag/named middleware is cached per uid; per-run closures are appended fresh every call, at the cost of re-allocating the array
-tags: channel
----
-
-# Channel middleware caching covers only statically resolved middleware
-
-`combineChannelMiddleware` in
-`packages/core/src/wirings/channel/channel-middleware-runner.ts` caches only the
-`wireInheritedChannelMiddleware` slice — the tag groups and named middleware
-resolved out of `pikkuState` — under the key `${wireType}:${uid}`. That slice is
-deterministic for a given `uid`. `wireChannelMiddleware` is not: it is a per-run
-set of closures, such as an AI agent's per-invocation stream middleware holding
-that run's thread and session state. Caching it would let a later run of the same
-`uid` reuse an earlier run's closures, leaking that run's state into a different
-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
-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
-middleware chain to another. Ordering within the combined chain is also fixed:
-channel-level `middleware` runs before message-level `middleware`.
-
-**What this rules out:** extending the cache key's value to include
-`wireChannelMiddleware`, memoising the whole combined array, or simplifying the
-cache key down to the channel or function name.

package/knowledge/decisions/internals/channel-state-accessors-are-unsound-generics-that-every-implementation-asserts.md

@@ -1,33 +0,0 @@
----
-type: decision
-title: `getState<T>()` lets the caller name any type, so every implementation asserts
-description: The type parameter appears only in the return position with nothing to infer from, so it is a caller-chosen claim rather than a checked fact
-tags: core, channel
----
-
-# `getState<T>()` lets the caller name any type, so every implementation asserts
-
-`PikkuChannel` declares its per-connection scratch state as:
-
-```ts
-setState<T>(state: T): Promise<void> | void
-getState<T>(): Promise<T | undefined> | T | undefined
-```
-
-`T` on `getState` appears only in the return position, with no parameter to
-infer it from. So `T` is whatever the caller writes, and the call site gets that
-type back with nothing having checked it. `setState<T>` is separately generic,
-so the two are not even tied to each other — a channel can be written with one
-shape and read as another and neither call complains.
-
-Every implementation therefore holds its state in a concrete variable and
-asserts on the way out. The SSE channel in `http-runner.ts` and the CLI channel
-in `cli-runner.ts` both do exactly that, and the assertion is unavoidable: no
-concrete value is assignable to a type the caller has not yet chosen.
-
-**What this rules out:** deleting the assertions in the implementations — they
-are forced by the signature, not by sloppiness. Fixing this properly means
-making the channel generic in its state type (`PikkuChannel<Opening, Out,
-Remote, State>`) so `setState` and `getState` agree and inference has something
-to work from, which changes the type of every channel in every app. Until that
-is worth doing, the assertions stay and this note explains why they exist.

package/knowledge/decisions/internals/channel-state-is-per-socket-session-state-is-per-user.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: Channel state is per-socket, session state is per-user
-description: ChannelStore holds connection-scoped scratch data keyed by channelId, deliberately separate from the pikkuUserId-keyed SessionStore
-tags: channel
----
-
-# Channel state is per-socket, session state is per-user
-
-`ChannelStore.setState` / `getState` / `clearState` in
-`packages/core/src/wirings/channel/channel-store.ts` are keyed by `channelId` and
-hold scratch data that belongs to one socket: a per-connection subscription
-filter, the current step of a connection-bound state machine, the last command
-this socket sent. The store clears it when the channel is removed. `SessionStore`
-is keyed by `pikkuUserId` and holds the user session, which is shared across HTTP
-and channel transports and outlives any one connection.
-
-The two are separate stores because their lifetimes and their scopes differ. One
-user may hold several sockets at once; writing socket-local data into the session
-would let those sockets overwrite each other and would leak connection state into
-HTTP requests. The serverless runner in `serverless/serverless-channel-runner.ts`
-rebinds `channel.setState/getState/clearState` onto the `ChannelStore` on every
-connect, message and disconnect precisely because there is no in-process channel
-object to hang the state off between invocations.
-
-**What this rules out:** backing `channel.setState` with the session store, or
-merging the two stores behind one interface "since both are key-value". Also
-rules out assuming channel state survives a reconnect — a new socket is a new
-`channelId` and starts empty.

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

@@ -1,28 +0,0 @@
----
-type: decision
-title: A channel's user id is persisted only after onConnect middleware has run
-description: The channelId to pikkuUserId mapping is written post-onConnect, because auth middleware is what establishes the session
-tags: channel
----
-
-# A channel's user id is persisted only after onConnect middleware has run
-
-`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`
-lifecycle, not before.
-
-Auth middleware runs as part of that lifecycle — it is what inspects the upgrade
-request's cookie or token and calls `setSession`. Before it runs there is no
-`pikkuUserId` to store, so an earlier write would persist `undefined` and the
-channel would stay anonymous for its whole life. That mapping is what
-`runChannelMessage` and `runChannelDisconnect` later use to rehydrate the session
-from the `sessionStore` on each subsequent invocation, since serverless keeps
-nothing in memory between them.
-
-**What this rules out:** moving the `setPikkuUserId` call up next to
-`channelStore.addChannel` to group the store writes together, and assuming a
-session exists on the wire before `onConnect` has completed. It also means an
-`onConnect` handler that throws leaves the channel with no user mapping — the
-error path deliberately does not persist one.

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

@@ -1,27 +0,0 @@
----
-type: decision
-title: CLI option names are camelCase in state and kebab-case on the command line
-description: Option keys match the function's input field names so they can be plucked by schema, and are converted to kebab only for display and parsing
-tags: cli
----
-
-# CLI option names are camelCase in state and kebab-case on the command line
-
-Every option key in `CLIOptions`, `CLICommandMeta.options` and the parsed
-`ParsedCommand.options` is camelCase, because it must line up with a field name
-on the command function's input type — that is what makes
-`pluckCLIData` in `packages/core/src/wirings/cli/cli-runner.ts` able to select
-fields by schema property name. Users type kebab-case.
-
-`toCamelCase` and `toKebabCase` in
-`packages/core/src/wirings/cli/command-parser.ts` are the only two points where
-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`.
-
-**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
-dropped. It also rules out emitting camelCase in help text or error messages,
-which would tell users to type a flag spelling that works only by accident.

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

@@ -1,28 +0,0 @@
----
-type: decision
-title: CLI parse errors are routed by message prefix
-description: The CLI runners decide between printing help and printing errors by string-matching the prefixes the parser writes, so those message strings are an interface
-tags: cli
----
-
-# CLI parse errors are routed by message prefix
-
-`parseCLIArguments` in `packages/core/src/wirings/cli/command-parser.ts` returns
-a flat `string[]` of errors. It has no error codes and no error types. The
-consumers — `executeCLI` in `cli-runner.ts` and `handleRawCLI` in
-`channel/cli-raw-channel-runner.ts` — decide whether the user made a routing
-mistake (show the help text) or a value mistake (print the errors) by
-`error.startsWith(...)` against three literals: `'Unknown command:'`,
-`'Command not found:'` and `'Missing subcommand:'`.
-
-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
-localising them, silently turns "show me the subcommands" into a raw error dump.
-
-**What this rules out:** editing those error message prefixes without updating
-every `startsWith` site, and adding a new "this is a routing problem" parse error
-without registering its prefix in both runners. If this needs to grow, replace
-the whole scheme with a discriminated error type in one change — do not add a
-fourth magic prefix.

package/knowledge/decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md

@@ -1,34 +0,0 @@
----
-type: decision
-title: CLI stdout is reserved for machine-readable output
-description: The default renderer emits single-line NDJSON, diagnostics go to stderr, and --json only hijacks rendering for commands that declared a renderer
-tags: cli
----
-
-# CLI stdout is reserved for machine-readable output
-
-`defaultJSONRenderer` in `packages/core/src/wirings/cli/cli-runner.ts` (and its
-twin in `channel/cli-channel-runner.ts`) calls `JSON.stringify` without an
-indent argument. That is not laziness: one result per line is NDJSON, which stays
-parseable when a command streams multiple results through the CLI channel.
-Pretty-printing spreads one record over many lines and breaks every line-oriented
-consumer downstream.
-
-Two rules follow from the same principle in `executeCLI`. Parse warnings —
-non-fatal by design, see the unknown-options decision — are written with
-`console.error`, so they never interleave into a command's machine-readable
-stdout. And `--json` / `--output json` only substitutes `defaultJSONRenderer`
-when the command declared its own `render`; a command with no renderer is one
-that prints inline as it works, and forcing its return value through the JSON
-renderer would append a stray record after output that was never structured to
-begin with. The `commandRenderer !== undefined` guard in the render block is what
-enforces that.
-
-Error formatting follows too: `isExpectedError(error)` prints `error.message`
-alone with no `Error:` prefix, because an expected `PikkuError` (a build gate
-tripping, a validation failure) has a message written to be read as the whole
-output. Anything else is logged as an object so its stack survives.
-
-**What this rules out:** adding an indent argument to `defaultJSONRenderer`,
-routing warnings or progress messages to stdout, and dropping the
-`commandRenderer !== undefined` condition so `--json` applies uniformly.

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

@@ -1,29 +0,0 @@
----
-type: decision
-title: CLI unknown long options warn instead of failing
-description: Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
-tags: cli
----
-
-# CLI unknown long options warn instead of failing
-
-`warnUnknownOption` in `packages/core/src/wirings/cli/command-parser.ts` pushes
-onto `ParsedCommand.warnings`, not `ParsedCommand.errors`, so an unrecognised
-`--long` option does not abort the command. The value is still parsed into
-`optionArgs`, but `pluckCLIData` in `cli-runner.ts` drops anything absent from
-the function's input schema — so the option is silently ignored at execution
-time. The warning exists precisely so that dropping is not silent.
-
-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
-`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.
-
-**What this rules out:** promoting unknown long options to errors "for
-strictness", and removing the warning on the grounds that the schema pluck
-already handles it — that restores the silent drop this was added to end. It also
-rules out making unknown short flags non-fatal for symmetry.