@pikku/core 0.12.79 → 0.12.82

package/knowledge/decisions/security/a-dropped-audit-write-is-always-logged.md

@@ -13,8 +13,10 @@ Its `write` discards the event — but before it does, it warns once, and it loo
 for a logger in two places: the wire's own, then the singleton passed to the
 constructor.
 
-The fallback is the point. Wires frequently do not carry a logger, and with only
-`this.wire.logger` the warning would itself be dropped whenever the wire is bare.
+The fallback is the point. `wire.logger` is an optional hook for a host that
+wants invocation-scoped logging — core never sets it, so on every path core
+itself drives, the singleton is the only source there is. With only
+`this.wire.logger` the warning would be dropped every time.
 An audit call that silently does nothing is the worst available outcome: the
 function believes it is producing an audit trail, the trail does not exist, and
 nothing anywhere says so. The warning names the function and the fix, and fires

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

@@ -0,0 +1,37 @@
+---
+type: decision
+title: A function never receives the secret service
+description: Every function-, permission- and auth-facing services type is bounded by SecretlessServices, so reaching for `secrets` in a function body is a type error rather than a lint
+tags: services
+---
+
+# A function never receives the secret service
+
+`SecretlessServices<Services>` is `Omit<Services, 'secrets'>`
+(`packages/core/src/types/core.types.ts`), and
+`CoreSecretlessSingletonServices` built from it is the constraint every
+function-, permission- and auth-facing type is bounded by
+(`packages/core/src/function/functions.types.ts`). Destructuring `secrets`
+inside a `pikkuFunc` body does not lint — it does not compile.
+
+The rule itself is older than the type: a function holding a `SecretService` can
+read every secret in the vault, which makes its blast radius the whole vault
+rather than the one credential it needs, and makes "which secrets does this
+function depend on?" unanswerable. `[PKU950]` enforces the same confinement for
+a `SecretService` reaching a function under an alias, because a rename does not
+change what it is. Encoding it in the type is what makes the honest mistake
+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
+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
+addon's declared secrets are present.
+
+**What this rules out:** widening a function's services type back to
+`CoreServices` for a function that "only needs one secret", and passing the
+secret service through under another name — the type follows the shape and
+`[PKU950]` follows the type. It also rules out treating the absence as an
+oversight to be patched with a cast.

package/knowledge/decisions/security/a-graph-run-starts-at-an-entry-node-the-graph-declared.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: A graph run starts at an entry node the graph declared
+description: startNode may only name a node in meta.entryNodeIds, and no generated route offers it, because otherwise a caller picks which half of the graph to skip
+tags: workflow
+---
+
+# A graph run starts at an entry node the graph declared
+
+`runWorkflowGraph` in
+`packages/core/src/wirings/workflow/graph/graph-runner.ts` takes an optional
+`startNode`. It used to accept any node id the graph contained, validated only
+by `validateGraphReferences` (does the node exist) and `areDependenciesSatisfied`
+(does its input reference another node). A node whose input is a literal or comes
+from the trigger passes both — including a node that is only ever reached after a
+validation, payment or approval node. Choosing it as the start does not skip the
+gate so much as never reach it.
+
+`startNode` is now checked against `meta.entryNodeIds`, the set the graph itself
+declared, and the generated `POST /workflow/:workflowName/graph/:nodeId` route
+that offered it to HTTP callers is gone.
+
+The parameter stays, because it has a real internal user: `PikkuTriggerService`
+(`packages/core/src/wirings/trigger/pikku-trigger-service.ts`) passes a target's
+`startNode` when a trigger fires. That caller names a node the graph declared, so
+the restriction costs it nothing.
+
+**What this rules out:** re-exposing entry-node choice on a generated route, and
+"validating" a `startNode` by existence or by dependency satisfaction — neither
+says the graph meant that node to be an entry point. It does not rule out a graph
+declaring several entry nodes; that is exactly how a graph says which starts are
+legitimate. If a graph needs a start that is not an entry node, the answer is to
+declare it as one, not to widen the check.

package/knowledge/decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: A permission gets a wire it cannot reply on
+description: The permission wire is typed with Out = never so a permission cannot send on the channel; that narrowing is not a subtype, so the call site asserts
+tags: core, permissions
+---
+
+# A permission gets a wire it cannot reply on
+
+`CorePikkuPermission` in `packages/core/src/function/functions.types.ts` types
+its wire as `PikkuWire<In, never, false, any, PikkuRPC, never, never>`. The
+second parameter is `Out`, and `never` there is deliberate: it makes
+`wire.channel` a `PikkuChannel<unknown, never, …>`, whose `send` accepts
+nothing. A permission is a gate — it answers `true` or `false` — and must not
+be able to write a reply to the caller it is deciding about. A permission that
+could `send` would be able to leak the very data the gate exists to withhold,
+and it would do so before the function it guards has run.
+
+`runPikkuFunc` holds an ordinary `PikkuWire`, whose default `Out` is `unknown`.
+`unknown` is not assignable to `never`, and `send` is contravariant in its
+argument, so the narrowing cannot be expressed as a subtype relation — the call
+into `runPermissions` asserts to the exact permission-wire type rather than
+relying on assignability.
+
+**What this rules out:** widening `Out` on the permission wire to `unknown` to
+delete the assertion. That silently hands every permission function a working
+`channel.send`. It equally rules out replacing the assertion with `as any`,
+which erases the target type and hides the fact that a specific, intentional
+narrowing is happening.
+
+The same reasoning explains the `never` in the fifth and sixth positions
+(`MCPTools`, `IsChannel`): a permission is not an MCP tool host and does not own
+the channel lifecycle.

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

@@ -0,0 +1,37 @@
+---
+type: decision
+title: A step runs the function the workflow dispatched it with
+description: StepState records the step's function name so the worker can reject a queue message naming a different one, because the step executes under the run owner's identity
+tags: workflow
+---
+
+# A step runs the function the workflow dispatched it with
+
+`pikkuWorkflowStepWorker` (`workflow-queue-workers.ts`) takes `rpcName` straight
+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*.
+
+The claim in `executeWorkflowStepInner` read the step's status and nothing else;
+there was no stored function name to compare against. `StepState` now carries
+`rpcName`, written by `insertStepState` (which already received it) and returned
+by every backend, and the claim rejects a message naming anything else with
+`WorkflowStepFunctionMismatchError` — before any status is mutated, so a forged
+message leaves the run untouched. The graph path takes the same value from
+`nodes[nodeId].rpcName` rather than from the message.
+
+`rpcName: undefined` means a store that never recorded one and cannot be
+compared; `null` is a step with no function of its own. Only a recorded value is
+checked.
+
+**Reachability, stated plainly:** the step-worker queue is not reachable from the
+public `/rpc/:rpcName` route — the worker is registered without `expose`. The
+exposure this closes is write access to the queue backend, and any in-process
+caller reaching `executeWorkflowStep` directly.
+
+**What this rules out:** trusting a queue payload to name the function it
+executes, here or in any future worker, and dropping `rpcName` from `StepState`
+as redundant with the step data — the comparison is the only thing standing
+between queue-write access and running any registered function as the run's
+owner.

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

@@ -0,0 +1,28 @@
+---
+type: decision
+title: A virtual user is never offered a scenario, platform or addon step
+description: Being able to invoke "the webhook arrives" lets the user manufacture the outcome it exists to discover, which invalidates every finding downstream
+tags: core, virtual-user
+---
+
+# A virtual user is never offered a scenario, platform or addon step
+
+`deriveVirtualUserCatalogue` excludes scenario bodies and their steps, and
+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.
+
+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
+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.
+
+This is the same class of argument as `allowApprovalRequired` defaulting to
+false, and it is enforced here at derivation rather than left to convention.
+
+**What this rules out:** exposing platform steps behind a flag "for
+convenience", or filtering them later in the run loop where a caller could skip
+the filter.

package/knowledge/decisions/security/a-workflow-run-is-read-and-approved-by-its-owner.md

@@ -0,0 +1,50 @@
+---
+type: decision
+title: A workflow run is read by its owner, and answered by whoever its gate declares
+description: A run started through a session records that user and only that user may read it; who may answer an approval gate is the gate's own declaration, and a run with no recorded owner has no ownership to enforce
+tags: workflow
+---
+
+# A workflow run is read by its owner, and answered by whoever its gate declares
+
+`WorkflowRunWire.pikkuUserId` has always been recorded on every run started
+through a session — `RPCService.startWorkflow` copies it off the wire — and
+nothing read it back. Run ids were the only secret protecting both the status
+routes (which stream `output` and `error`) and `approveStep`, which took no
+session at all and rejected only an already-resolved gate.
+
+`assertWorkflowRunOwner`
+(`packages/core/src/wirings/workflow/workflow-run-ownership.ts`) is the check the
+**read** paths share: the generated status routes assert it against the run they
+were already reading.
+
+**A run with no recorded owner is not gated.** Triggers, schedulers and routes
+wired without auth start runs with no `pikkuUserId`; there is nobody to compare a
+caller against, and inventing one would reject the framework's own callers rather
+than secure anything. Gate those at the entrypoint with `auth` or `permissions`.
+
+This is ownership, not an approver model. It answers "is this your run", not "are
+you entitled to approve this particular gate".
+
+## Approving is a separate question, and the gate answers it
+
+`approveStep` originally shared `assertWorkflowRunOwner`, which made "only the
+initiator may answer" the one available rule. That is right for "confirm your own
+action" and exactly wrong for four-eyes sign-off, where the initiator is the one
+person who must not sign. Which applies is a property of the decision, so it is
+declared on the gate — `approvers` (`'any' | 'owner' | 'not-initiator'`) and
+`approverScope` on `WorkflowApprovalOptions`.
+
+It is enforced wherever the policy is known. Reaching the gate publishes the
+policy into the run state, so a decision submitted after that is judged by the
+approve entrypoint and refused with a 403. A decision can legitimately be
+recorded before the run has reached the gate, and that one has no policy to be
+judged against yet — it is judged on replay instead, alongside payload
+validation, and discarded if it fails.
+
+The default is therefore `any`: a gate is a pause for a decision, not an
+authorization boundary, and a route that needs one has `auth`/`permissions`.
+
+**What this rules out:** treating a run id as a capability, adding a new run read
+path that does not take a session, and re-deriving who may approve from who
+started the run.

package/knowledge/decisions/security/an-agent-approval-is-claimed-before-the-tool-runs.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: An agent approval is claimed before the tool runs
+description: resolveApproval is a compare-and-swap returning whether this caller won, because the read that precedes it is not a claim and ten concurrent approvals would otherwise mean ten refunds
+tags: ai-agent
+---
+
+# An agent approval is claimed before the tool runs
+
+Resuming a suspended agent run read the run, checked `status === 'suspended'`,
+snapshotted `pendingApprovals`, called `resolveApproval`, executed the tool, and
+only then wrote `status: 'running'`. Nothing spanned that sequence — no
+transaction, no row lock, no conditional update — so concurrent approvals of the
+same tool call all observed `suspended`, all snapshotted the same list, and all
+reached `execute`. `resolveApproval` returned `void`, so a loser could not even
+tell.
+
+`resolveApproval` is now the claim, and returns whether *this* caller made it.
+The stores implement it as a compare-and-swap: Kysely updates the run row only
+while `status = 'suspended'` and `pendingApprovals` still equals the list it
+read; the tool-call stores move the row off `approvalStatus = 'pending'` and
+count the rows they changed. Both resume paths run the tool only for the ids they
+claimed, and a caller that claimed nothing gets an error rather than a silent
+re-run.
+
+The claim is per tool call, not per run, so concurrent approvals of *different*
+tool calls on one run all proceed — which is the case that made a run-level
+`claimSuspendedRun` the worse fit.
+
+**What this rules out:** treating `getRun` as a claim, adding a resume path that
+executes a tool without a `true` from `resolveApproval`, and implementing
+`resolveApproval` as a read-modify-write in any new store — the return value is
+a promise about atomicity, not a convenience.

package/knowledge/decisions/security/an-approval-answer-outlives-the-run-it-answered.md

@@ -0,0 +1,59 @@
+---
+type: decision
+title: An approval answer outlives the run it answered
+description: Run state holds a decision only while the gate is open, so the settled answer carries decidedBy/decidedAt into the step result and every attempt is written to the audit sink, which has no foreign key to the run
+tags: workflow, audit
+---
+
+# An approval answer outlives the run it answered
+
+An approval gate is asked for so it can be answered for afterwards. "Who
+released the funds" is the entire point of four-eyes sign-off, and until this
+change none of it was kept.
+
+Run state is where a decision *waits*, not where it is kept. The record under
+`workflowRuns.state.__approval_<hex>` is overwritten by the next write to that
+key, and cleared outright — `decidedBy: undefined` included — whenever a
+decision is refused on replay. A trail that erases exactly the events worth
+keeping is not a trail.
+
+So the answer is recorded twice, in two places with different lifetimes.
+
+## The settled decision keeps its provenance
+
+`ApprovalOutcome<T>` carries `decidedBy` and `decidedAt` alongside `data`, so
+the answer reaches `workflowStep.result` and, through it,
+`workflowStepHistory` — append-only, and already the per-step event log. Both
+are spread in only when present, so a gate answered without a session keeps the
+shape it had before there was anything to record.
+
+## The audit sink is what survives deletion
+
+`deleteRun` cascades: `workflowStep` is `onDelete('cascade')` from
+`workflowRuns`, and `workflowStepHistory` from `workflowStep`. Deleting a run
+therefore deletes the sign-off with it — and a *refused* attempt never reaches a
+step at all, so it was never in that trail to begin with.
+
+Every answer — accepted, refused at submission, or cleared on replay — is
+written to the `AuditService` as `workflow.approval.decided`, with
+`outcome: 'success' | 'denied'`, the decider under `userIdentity.pikkuUserId`,
+and the run, reason, scopes and refusal in `metadata`. The `audit` table holds
+no foreign key to any workflow table, which is precisely why it is the right
+home.
+
+`auditApprovalDecision`
+(`packages/core/src/wirings/workflow/workflow-approval-audit.ts`) is a module of
+its own rather than a method on `PikkuWorkflowService`: the trail is a separate
+concern from running the workflow, and the service is already at the 2000-line
+limit `source-files-stay-composable.test.ts` enforces.
+
+**A sink that fails is logged, never thrown.** The trail must not be the reason a
+decision is lost. A project with no `audit` service wired records nothing and is
+otherwise unaffected — the sink is opt-in, and `auditSchema` is deliberately not
+in `pikkuSchemas`.
+
+**What this rules out:** a dedicated `workflowApprovals` table. It would have to
+be implemented in all seven backends and would still be deleted with the run
+unless it deliberately broke the cascade — at which point it is the audit table
+with extra steps. If approvals later need to be *queried* as a first-class
+entity rather than read back from the trail, that is when to revisit.

package/knowledge/decisions/security/an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: An upload is counted as it arrives, not buffered and then measured
+description: Reading the whole body before checking its size hands an unauthenticated caller a way to spend the server's memory
+tags: core, content
+---
+
+# An upload is counted as it arrives, not buffered and then measured
+
+The local content request handler accumulates the request body chunk by chunk,
+tracking the running total, and abandons the read the moment it crosses the
+limit. An oversized upload therefore costs the limit, not its own size.
+
+The obvious alternative — `await request.arrayBuffer()` and then check
+`byteLength` — has to hold the entire body in memory before it can decide the
+body is too large. For an endpoint reachable before authentication that is a
+way to spend the server's memory for the price of one request, and no size limit
+configured anywhere prevents it.
+
+`readRequestBody` in the node HTTP server aborts on the same terms, for the same
+reason.
+
+**What this rules out:** replacing the streaming accumulation with a single
+buffered read because the limit check "still happens".

package/knowledge/decisions/security/index.md

@@ -10,6 +10,12 @@ A rule about who may do what, and which way it fails when it is unsure.
 
 <!-- pikku:knowledge-index -->
 - [A dropped audit write is always logged](a-dropped-audit-write-is-always-logged.md) — The no-op audit service falls back to the singleton logger when the wire carries none, so an unconfigured audit call is never silent
+- [A function never receives the secret service](a-function-never-receives-the-secret-service.md) — Every function-, permission- and auth-facing services type is bounded by SecretlessServices, so reaching for `secrets` in a function body is a type error rather than a lint
+- [A graph run starts at an entry node the graph declared](a-graph-run-starts-at-an-entry-node-the-graph-declared.md) — startNode may only name a node in meta.entryNodeIds, and no generated route offers it, because otherwise a caller picks which half of the graph to skip
+- [A permission gets a wire it cannot reply on](a-permission-gets-a-wire-it-cannot-reply-on.md) — The permission wire is typed with Out = never so a permission cannot send on the channel; that narrowing is not a subtype, so the call site asserts
+- [A step runs the function the workflow dispatched it with](a-step-runs-the-function-the-workflow-dispatched-it-with.md) — StepState records the step's function name so the worker can reject a queue message naming a different one, because the step executes under the run owner's identity
+- [A virtual user is never offered a scenario, platform or addon step](a-virtual-user-is-never-offered-a-step-that-would-forge-its-own-oracle.md) — Being able to invoke "the webhook arrives" lets the user manufacture the outcome it exists to discover, which invalidates every finding downstream
+- [A workflow run is read by its owner, and answered by whoever its gate declares](a-workflow-run-is-read-and-approved-by-its-owner.md) — A run started through a session records that user and only that user may read it; who may answer an approval gate is the gate's own declaration, and a run with no recorded owner has no ownership to enforce
 - [An actor's missing approval decision defaults to denied](actor-flow-missing-approval-decisions-default-to-denied.md) — Every pending tool call gets an explicit decision; an id the persona LLM omitted is denied, so a dropped field can never read as consent
 - [Actor sign-in is proven by Set-Cookie, not a non-empty jar](actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md) — HttpScenarioActor tracks its own signedIn flag and requires the sign-in response itself to set a cookie, because a populated jar proves nothing
 - [Actor sign-in only works for actor-flagged users](actor-sign-in-only-works-for-actor-flagged-users.md) — The scenario actor secret mints sessions for user rows flagged actor and nothing else, so holding it never impersonates a real user
@@ -24,8 +30,11 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [Agent thread ownership fails closed when there is no principal](ai-agent-sessionless-deployments-have-no-thread-ownership.md) — A sessionless caller gets an ephemeral owner and reaches no stored thread, rather than reaching all of them
 - [An agent thread key is always prefixed with the trusted principal](ai-agent-thread-ownership-composes-the-session-principal.md) — Ownership keys are composed as principal:resourceId, so a client id can sub-divide its own boundary but never widen it
 - [Agent tool permission filtering reads the live function config, not the metadata](ai-agent-tool-filtering-reads-the-live-function-config.md) — The pikkuAuth brand survives only on live permission objects, so a metadata-driven check would silently admit every gated tool
+- [An agent approval is claimed before the tool runs](an-agent-approval-is-claimed-before-the-tool-runs.md) — resolveApproval is a compare-and-swap returning whether this caller won, because the read that precedes it is not a claim and ten concurrent approvals would otherwise mean ten refunds
+- [An approval answer outlives the run it answered](an-approval-answer-outlives-the-run-it-answered.md) — Run state holds a decision only while the gate is open, so the settled answer carries decidedBy/decidedAt into the step result and every attempt is written to the audit sink, which has no foreign key to the run
 - [An empty owners constraint matches nothing](an-empty-owners-constraint-matches-nothing.md) — owners is an authorization boundary, so every storage backend must treat [] as no rows rather than no filter
 - [An exposed function with no gate is reported at codegen, not at boot](an-exposed-ungated-function-is-a-codegen-warning.md) — The check runs in the inspector where function meta and every wireAddon declaration are both in hand, because neither source alone can tell a gated function from an ungated one
+- [An upload is counted as it arrives, not buffered and then measured](an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md) — Reading the whole body before checking its size hands an unauthenticated caller a way to spend the server's memory
 - [The console addon's privileged functions gate themselves](console-addon-privileged-functions-gate-themselves.md) — Thread listing is owner-scoped unless the caller holds admin, and addon installation requires an admin session, rather than trusting the host to register a global permission
 - [Core's SSRF guard matches host literals because edge runtimes have no DNS](core-safe-fetch-blocks-ssrf-by-host-literal-not-dns.md) — safeFetch rejects internal address literals and re-validates every redirect hop; it cannot stop DNS rebinding
 - [Core secrets are encrypted with a per-secret DEK wrapped by a KEK](core-secrets-use-a-per-secret-dek-wrapped-by-a-kek.md) — Envelope encryption keeps ciphertext untouched during key rotation, at the cost of storing two blobs per secret

package/knowledge/questions/channel-middleware-accepts-bare-factories-that-nothing-resolves.md

@@ -0,0 +1,35 @@
+---
+type: question
+title: A channel's middleware list accepts bare factories that nothing ever resolves
+description: CoreChannel.channelMiddleware admits CorePikkuChannelMiddlewareFactory, but no runner calls one, so a bare factory would stall the chain
+tags: core, channel
+---
+
+# A channel's middleware list accepts bare factories that nothing resolves
+
+`CoreChannel.channelMiddleware` is typed as
+`(CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory)[]`, but
+`runPikkuFunc`'s `wireChannelMiddleware` parameter admits only
+`CorePikkuChannelMiddleware[]`. The two call sites that bridge them —
+`channel-common.ts` and `channel-handler.ts` — assert across the gap.
+
+A factory is `(input: In) => CorePikkuChannelMiddleware`: the author is meant to
+*call* it at wiring time and put the result in the array.
+`combineChannelMiddleware` contains no factory-resolution branch, and neither
+does `combineMiddleware` for ordinary middleware — that is consistent and
+deliberate. So a bare, uncalled factory in `channelMiddleware` would be pushed
+into the chain and then invoked as if it were middleware: it would receive
+`(services, channel, next)` as its single `input` argument, return a middleware
+function that nothing runs, and never call `next` — stalling the chain silently.
+
+Nothing in this repository puts a bare factory there, so the failure is
+hypothetical today. The type is what invites it.
+
+**What would settle it:** deciding whether `channelMiddleware` should accept
+only resolved middleware — in which case the union is simply wrong and should
+lose its factory arm, and both assertions disappear — or whether the runner
+should resolve factories, in which case `combineChannelMiddleware` needs a
+branch and the ordinary middleware path probably needs the matching one.
+
+Until then the assertions name the exact target type rather than `as any`, so
+the gap is visible at both call sites.

package/knowledge/questions/index.md

@@ -11,5 +11,6 @@ currently makes a choice that nobody has defended — the choice stays, the doub
 gets recorded.
 
 <!-- pikku:knowledge-index -->
-_Nothing here yet._
+- [A channel's middleware list accepts bare factories that nothing ever resolves](channel-middleware-accepts-bare-factories-that-nothing-resolves.md) — CoreChannel.channelMiddleware admits CorePikkuChannelMiddlewareFactory, but no runner calls one, so a bare factory would stall the chain
+- [An unauthorized channel reply is sent outside the channel's declared Out type](unauthorized-channel-replies-escape-the-declared-out-type.md) — processMessageHandlers sends a bare string on auth failure, which no generated client type admits — nobody has decided what the typed shape should be
 <!-- /pikku:knowledge-index -->

package/knowledge/questions/unauthorized-channel-replies-escape-the-declared-out-type.md

@@ -0,0 +1,44 @@
+---
+type: question
+title: An unauthorized channel reply is sent outside the channel's declared Out type
+description: processMessageHandlers sends a bare string on auth failure, which no generated client type admits — nobody has decided what the typed shape should be
+tags: core, channel
+---
+
+# An unauthorized channel reply is sent outside the channel's declared Out type
+
+When a message arrives on a channel route that requires a session and none is
+attached, `processMessageHandlers` in
+`packages/core/src/wirings/channel/channel-handler.ts` logs the failure and then
+sends the client a bare string:
+
+```ts
+channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`)
+```
+
+That compiles only because `processMessageHandlers` takes
+`PikkuChannelHandler`, whose generics default to `<unknown, unknown>`, so `send`
+accepts anything at this call site. The channel the application actually
+declared has a concrete `Out`, and the generated client is typed from it. A
+client can therefore receive a value its own types say is impossible, and no
+`@pikku/client-websocket` consumer has a branch for it.
+
+The alternatives were never worked through:
+
+- **Widen every channel's `Out`** to `Out | ChannelError`, so the error is part
+  of the contract. Honest, but it forces a discriminated union on every consumer
+  including channels that can never fail auth.
+- **Send on a reserved envelope** the way `channel-rpc` does, and let the client
+  library surface it out-of-band rather than as a message. Keeps `Out` clean,
+  but adds a second framing that every runtime adapter has to honour.
+- **Send nothing** and let the close code carry it. Simplest, and loses the
+  route name that makes the failure debuggable.
+
+Until one is chosen the string stays, because dropping it silently is worse: a
+client that is quietly ignored has no way to tell "unauthorized" from "the
+server is slow".
+
+**What would settle it:** deciding whether channel-level errors belong in `Out`
+at all, which is the same question `channel-rpc` already answered for RPC frames
+by giving them their own envelope. If the answer is "same as RPC", this becomes
+a decision note and the string becomes an envelope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.79",
+  "version": "0.12.82",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -15,8 +15,18 @@
     "test": "bash run-tests.sh",
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "yarn build",
+    "api-report": "tsx scripts/generate-api-report.mts"
   },
+  "sideEffects": [
+    "./dist/errors/errors.js",
+    "./dist/wirings/rpc/rpc-runner.js",
+    "./dist/wirings/rpc/remote-addon-auth.js",
+    "./dist/wirings/workflow/workflow-approval-policy.js",
+    "./dist/wirings/workflow/workflow-errors.js",
+    "./dist/wirings/workflow/workflow-run-ownership.js",
+    "./dist/wirings/workflow/pikku-scenario-service.js"
+  ],
   "exports": {
     ".": "./dist/index.js",
     "./middleware": "./dist/middleware/index.js",
@@ -40,6 +50,7 @@
     "./node-host-resolver": "./dist/utils/node-host-resolver.js",
     "./mcp": "./dist/wirings/mcp/index.js",
     "./ai-agent": "./dist/wirings/ai-agent/index.js",
+    "./ai-scorer": "./dist/wirings/ai-scorer/index.js",
     "./gateway": "./dist/wirings/gateway/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/command-parser": "./dist/wirings/cli/command-parser.js",
@@ -62,7 +73,8 @@
     "./services/temporary-file-service": "./dist/services/temporary-file-service.js",
     "./crypto-utils": "./dist/crypto-utils.js",
     "./hmac": "./dist/utils/hmac.js",
-    "./internal": "./dist/internal.js",
+    "./ecosystem": "./dist/ecosystem.js",
+    "./internal": "./dist/ecosystem.js",
     "./schema": "./dist/schema.js",
     "./testing": "./dist/testing/index.js",
     "./dev": "./dist/dev/hot-reload.js"

package/scripts/generate-api-report.d.mts

@@ -0,0 +1 @@
+export {};

package/scripts/generate-api-report.mjs

@@ -0,0 +1,89 @@
+/**
+ * Emits `api-report.md`: every entry point's exported symbols with their full
+ * type signatures.
+ *
+ * `public-surface.json` pins the *names* a consumer can reach. That catches an
+ * export appearing or disappearing and nothing else — adding a method to
+ * `MetaService`, or making a field on `ChannelMeta` required, sails straight
+ * past it. Those are the changes that break a consumer's build, and there are
+ * far more of them: 130 exported classes carry 543 members between them, and
+ * 268 exported interfaces carry 1,385.
+ *
+ * So this walks the type checker instead and writes what each symbol actually
+ * *is*. The report is committed, and `api-report.test.ts` fails when the two
+ * disagree — so a member-level change is a reviewable diff rather than a
+ * surprise in someone else's CI.
+ *
+ * Run: yarn api-report
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf-8'));
+const entryPoints = Object.entries(pkg.exports).map(([subpath, dist]) => ({
+    subpath,
+    file: resolve(packageRoot, dist.replace('./dist/', './src/').replace(/\.js$/, '.ts')),
+}));
+const program = ts.createProgram(entryPoints.map((e) => e.file), {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.Node16,
+    moduleResolution: ts.ModuleResolutionKind.Node16,
+    strict: true,
+    skipLibCheck: true,
+});
+const checker = program.getTypeChecker();
+/** One line per symbol: how it is declared, flattened and stripped of noise. */
+const signature = (exported) => {
+    // A re-export is an alias; the declaration that matters is the target's, so
+    // an interface re-exported through a barrel still reports its members.
+    const symbol = exported.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(exported)
+        : exported;
+    const declaration = symbol.declarations?.[0];
+    if (!declaration)
+        return exported.getName();
+    if (ts.isInterfaceDeclaration(declaration) ||
+        ts.isClassDeclaration(declaration) ||
+        ts.isTypeAliasDeclaration(declaration) ||
+        ts.isEnumDeclaration(declaration)) {
+        // The declaration itself, so member changes show up in the diff.
+        return declaration
+            .getText()
+            .replace(/\/\*\*[\s\S]*?\*\//g, '')
+            .replace(/\/\/[^\n]*/g, '')
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .join(' ');
+    }
+    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+    return `${exported.getName()}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`;
+};
+const sections = [
+    '# @pikku/core API report',
+    '',
+    'Generated by `yarn api-report`. Every exported symbol with its full',
+    'signature, so a member-level change is a reviewable diff. Do not edit.',
+    '',
+];
+for (const { subpath, file } of entryPoints) {
+    const source = program.getSourceFile(file);
+    if (!source)
+        continue;
+    const moduleSymbol = checker.getSymbolAtLocation(source);
+    if (!moduleSymbol)
+        continue;
+    const exports = checker
+        .getExportsOfModule(moduleSymbol)
+        .map((s) => [s.getName(), signature(s)])
+        .sort(([a], [b]) => a.localeCompare(b));
+    sections.push(`## ${subpath}`, '');
+    sections.push('```ts');
+    for (const [, sig] of exports)
+        sections.push(sig);
+    sections.push('```', '');
+}
+writeFileSync(resolve(packageRoot, 'api-report.md'), sections.join('\n'));
+console.log(`api-report.md written for ${entryPoints.length} entry points`);