@pikku/core 0.12.78 → 0.12.80

package/knowledge/decisions/internals/the-middleware-resolution-cache-is-deliberately-unbounded.md

@@ -0,0 +1,40 @@
+---
+type: decision
+title: The middleware resolution cache is deliberately unbounded
+description: Its keyspace is the set of registered wires, not request traffic, and middleware is dynamic — so eviction would buy nothing and cost the dedupe guarantee
+tags: core, middleware
+---
+
+# The middleware resolution cache is deliberately unbounded
+
+`middlewareCache` in `packages/core/src/middleware-runner.ts` is a plain
+`Record<PikkuWiringTypes, Record<string, readonly CorePikkuMiddleware[]>>` with
+no size limit and no eviction. That reads like an unbounded-growth bug and is
+not one.
+
+**The keyspace is finite by construction.** The cache is keyed by wire type and
+wire id, and wire ids come from registration, not from traffic — an HTTP route
+pattern, a channel name, a queue name. A million requests to the same route
+produce one entry. Nothing a caller sends creates a key: a channel message key
+is `${channel}:${routingProperty}:${routerValue}`, and `routerValue` is only
+reached after matching `routes[routerValue]`, so an unregistered value never
+gets that far.
+
+**Middleware is dynamic, and the cache is invalidated rather than aged out.**
+`addGlobalMiddleware` and `addTagMiddleware` can run after startup, and dev
+hot-reload rewires wholesale — so correctness comes from `clearMiddlewareCache()`
+at the points where the middleware set actually changes, not from entries
+expiring. An LRU would evict entries that are still current while doing nothing
+about entries that are stale.
+
+**Eviction would also weaken the chain itself.** `combineMiddleware` returns a
+`freezeDedupe`d array, and dedupe is by function identity — a middleware
+reachable through both a tag group and a direct wire registration runs exactly
+once. Callers hold that array. Recomputing it under memory pressure hands out a
+second array for the same wire, which is churn at best and, for anything
+comparing chains by identity, a silent behaviour change.
+
+**What this rules out:** adding a `MIDDLEWARE_CACHE_MAX` with LRU eviction as a
+denial-of-service mitigation. There is no traffic-driven growth to mitigate. If
+a future change ever keys this cache by something a caller controls, that is the
+bug — bound the key, not the cache.

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

@@ -0,0 +1,40 @@
+---
+type: decision
+title: The per-invocation rpc view is a class, because an object literal with a getter is slow to build
+description: An accessor declared on an object literal is defined per instance, which drops the literal off V8's fast construction path — measured at 1.15µs against 0.47µs, on every request
+tags: core, rpc, performance
+---
+
+# The per-invocation rpc view is a class
+
+`getContextRPCService` builds `wire.rpc` once per invocation. It used to return
+an object literal, and that literal declared `get agent()` so the agent facade
+stayed lazy — most requests never touch it, and reading it builds five closures.
+
+The laziness is right. Declaring the accessor *on the literal* was not: a
+literal containing an accessor needs a real property descriptor per instance,
+which takes it off V8's fast object-literal construction path and slows the
+whole object, not just the accessor.
+
+Measured with `benchmarks/bench-profile-granular.ts`, three runs each:
+
+| shape | per call |
+| --- | --- |
+| object literal with `get agent()` | 1.106 / 1.433 / 1.147 µs |
+| class with `agent` on the prototype | 0.523 / 0.461 / 0.525 µs |
+
+Roughly 2.4×, well outside the run-to-run variance, on a path every request
+takes. On the same machine a full `fetchData` measures 12–19µs, so this was on
+the order of a tenth of a request spent constructing one object.
+
+The obvious alternative is worse. Making `agent` an eager property removes the
+accessor but builds those five closures unconditionally, and measured *slower*
+than the original at 1.967µs. A prototype accessor is the only shape that keeps
+the laziness and the fast construction path.
+
+**What this rules out:** "simplifying" `ContextRPCView` back to an object
+literal. It reads as the plainer option and costs double. It also rules out
+trusting a synthetic microbenchmark here — a standalone benchmark of these
+shapes pointed at the eager version, because its stand-in for the agent getter
+was too cheap to represent the real one. The numbers above come from the
+profiler running the real code.

package/knowledge/decisions/internals/the-persona-runtime-is-exported-from-the-persona-entry-point.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: The persona runtime is exported from @pikku/core/persona, never from services
+description: Those values reach the actor-flow and agent runners, which no production server runs — and an unbundled deploy loads whatever the import graph names
+tags: core, services
+---
+
+# The persona runtime lives on `@pikku/core/persona`
+
+`HttpPersona`, `createHttpPersonas`, `readScenarioHttpResponse` and
+`postScenarioJson` are exported from `@pikku/core/persona`, not from
+`@pikku/core/services`. Their *types* are re-exported freely — TypeScript erases
+those and they cost a bundle nothing.
+
+The values are different. They reach `http-personas`, which reaches the
+actor-flow conversation runner, which reaches the agent runner: an entire
+scenario and virtual-user runtime that no production server executes. An
+unbundled Node or Lambda deploy does no tree-shaking — it loads whatever the
+import graph names — so exporting one value from the services barrel pulls all
+of it into every application that imports a service.
+
+This is enforced, not merely intended: `production-barrels-stay-lean.test.ts`
+walks the value-import graph from `services/index.ts` and
+`wirings/workflow/index.ts` and fails if any of those modules is reachable.
+
+**What this rules out:** re-exporting a persona value from the services barrel
+for convenience, and "just one small helper" — the graph is transitive, and one
+value is enough to pull the whole runtime.

package/knowledge/decisions/internals/the-transcript-event-is-sent-ahead-of-the-run.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A voice turn's transcript is sent before the run starts, on the raw channel
+description: The client does not know what it said, and an answer starts streaming within a few hundred milliseconds — a question arriving after its answer reads as the wrong question
+tags: core, ai-agent
+---
+
+# A voice turn's transcript is sent ahead of the run
+
+A voice client sends audio, so it does not know what it said. Until the
+transcript reaches it, its own message renders as a blank bubble.
+
+The event is sent *before* the run rather than alongside it because the answer
+begins streaming within a few hundred milliseconds. Sent concurrently, the
+transcript routinely lands after the first tokens of its own answer — and a
+question that appears beneath its answer reads as a question about something
+else entirely.
+
+It goes on the raw channel rather than through the stream middleware because it
+is not part of the reply: it is what the user said, and the stream hooks are
+built to transform what the agent says.
+
+**What this rules out:** folding the transcript into the run's event stream for
+uniformity. Ordering is the whole point, and the stream is where ordering is
+least under this code's control.

package/knowledge/decisions/internals/the-virtual-user-catalogue-is-the-only-gate-on-what-may-be-called.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: The catalogue is the only gate on what a virtual user may call
+description: Narrowing happens once at derivation, so there is no second check in the run loop that could drift out of step with it
+tags: core, virtual-user
+---
+
+# The catalogue is the only gate on what a virtual user may call
+
+What a virtual user may invoke is decided once, when the catalogue is narrowed
+for its disposition: a read-only disposition is never offered a mutation, and an
+approval-gated endpoint is never offered at all.
+
+The run loop then indexes into that catalogue and calls what it finds. There is
+deliberately no second permission check at call time, because a second check is
+a second thing to keep correct — and the failure mode of the two disagreeing is
+that one of them silently stops mattering.
+
+**What this rules out:** adding a "defence in depth" guard in the run loop. It
+would not be defence in depth; it would be a duplicate of the derivation rules,
+maintained separately, and the one that runs first wins.

package/knowledge/decisions/internals/the-worker-disposition-is-the-one-that-is-not-testing.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: The worker disposition is the only one not testing anything
+description: It is doing the job, so it abandons rarely, runs cool, and is told to stop and say so rather than guess
+tags: core, virtual-user
+---
+
+# The worker disposition is the only one not testing anything
+
+Every other disposition exists to probe the product. The worker exists to *use*
+it, which changes every parameter: it abandons rarely, runs at a low temperature,
+and is instructed to stop and report rather than guess its way past an obstacle.
+
+The failure mode being guarded against is different too. For the probing
+dispositions the risk is a missed bug. For this one it is a wrong action nobody
+asked for — a real mutation performed because the model improvised when it
+should have stopped.
+
+**What this rules out:** tuning this disposition toward the others for
+consistency, in particular raising its temperature or its tolerance for
+guessing. Those settings are what make the others useful and what would make this
+one dangerous.

package/knowledge/decisions/internals/thread-history-records-the-transcript-not-the-audio.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Thread history records what the model was asked, which for a spoken turn is the transcript
+description: The wire carried a base64 audio blob; persisting it writes megabytes of unreadable data and loses the only readable record of the turn
+tags: core, ai-agent
+---
+
+# Thread history records the transcript, not the audio that arrived
+
+What goes into thread history is what the model was actually asked. For a typed
+turn that is what arrived over the wire. For a spoken turn it is not: the wire
+carried a base64 audio blob, and `voiceInput` replaced it with a transcript
+before the model ever saw it.
+
+Persisting the blob would write megabytes of unreadable data into the history
+*and* discard the only readable record of what was said — the worst of both.
+
+Both the streaming and non-streaming paths do this, and both check identity
+rather than assuming: a middleware is free to rewrite the message list into
+something with no relation to this turn, and in that case there is no transcript
+to substitute and the list is persisted as-is.
+
+**What this rules out:** persisting the inbound message verbatim on the grounds
+that it is the ground truth. For voice it is the least useful representation
+available, and the substitution is exactly what makes the history readable.

package/knowledge/decisions/internals/virtual-user-step-order-comes-from-insertion-order.md

@@ -0,0 +1,21 @@
+---
+type: decision
+title: A scenario's step order for a virtual user is insertion order, not a graph traversal
+description: The CLI writes nodes in declaration order, so following `next` would buy an ordering that is already true and cost a traversal that has to interpret branches
+tags: core, virtual-user
+---
+
+# Step order comes from insertion order, not a graph traversal
+
+When a scenario becomes catalogue entries, its steps are read in the order the
+nodes appear — which is the order the CLI wrote them, which is the order the
+scenario declares them.
+
+Following `next` edges instead would produce the same ordering in the ordinary
+case, and in the branching case it would force a decision nobody needs: which
+arm of a branch to present to a reader who will never take one. The traversal
+costs work to reproduce a fact that already holds.
+
+**What this rules out:** "correcting" this to a topological walk because a graph
+is present. The graph describes execution; the catalogue describes what the
+scenario *says*, and those are read in declaration order.

package/knowledge/decisions/internals/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: Only an explicit `false` silences a spoken reply
+description: The key being absent means no voice input is wired and nothing reported either way, so those callers keep the behaviour they had before the option existed
+tags: core, ai-agent
+---
+
+# Only an explicit `false` silences a spoken reply
+
+`voiceOutput` speaks a reply unless the turn is explicitly marked as not having
+arrived by voice. The distinction is between three states, not two:
+
+- `true` — `voiceInput` handled this turn and it carried speech.
+- `false` — `voiceInput` handled this turn and a real user really typed it.
+- absent — no voice input is wired at all, so nothing reported either way.
+
+Treating absent as `false` would silence every caller who wired `voiceOutput`
+without `voiceInput`, changing behaviour that worked before the option existed.
+Treating absent as `true` would speak replies to typists on any stack where the
+flag never gets set.
+
+**What this rules out:** normalising the flag to a boolean at any point between
+`voiceInput` and `voiceOutput` — that collapses absent into one of the other two
+and picks a wrong answer for somebody.

package/knowledge/decisions/internals/wiring-registries-erase-the-generics-their-wire-functions-capture.md

@@ -0,0 +1,35 @@
+---
+type: decision
+title: Wiring registries erase the generics their wire* functions capture
+description: A registry is typed at unknown so every wiring shares one map; storing a generic config in it needs an assertion, because function parameters are contravariant
+tags: core
+---
+
+# Wiring registries erase the generics their `wire*` functions capture
+
+Every `wire*` entry point — `wireTrigger`, `wireTriggerSource`, `wireChannel`,
+`wireQueueWorker`, and the rest — is generic in the shape a caller declares, so
+the caller gets a checked `func`. The registry each one writes to is not:
+`pikkuState(null, 'trigger', 'triggers')` is a
+`Map<string, CoreTriggerSource>` where `CoreTriggerSource` fixes input and
+output at `unknown`, because one map has to hold every trigger in the app.
+
+Handing `CoreTriggerSource<TInput, TOutput>` to a slot typed
+`CoreTriggerSource<unknown, unknown>` is not an upcast. `func` takes its input
+as a *parameter*, and parameters are contravariant: a function that accepts
+`TInput` cannot stand in for one that accepts `unknown`, since `unknown` admits
+values `TInput` does not. TypeScript is right to reject it, and no variance
+annotation makes it go away — the registry genuinely holds functions whose input
+types it cannot name.
+
+The runtime is nonetheless sound, because the only thing that ever invokes a
+registered `func` is the function runner, which validates the incoming data
+against that function's own generated schema before the call. The type the
+registry lost is re-established at the call boundary by the schema, not by the
+type system.
+
+**What this rules out:** deleting these assertions as if they were noise — the
+code does not compile without them. It equally rules out `as any` in their
+place: `as any` discards the target type too, so a genuinely wrong config would
+also slip through. Assert to the registry's own element type and let everything
+except the erased generic stay checked.

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-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,34 @@
+---
+type: decision
+title: A workflow run is read and approved by its owner
+description: A run started through a session records that user and only that user may read it or answer its approval gates; a run with no recorded owner has no ownership to enforce
+tags: workflow
+---
+
+# A workflow run is read and approved by its owner
+
+`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 one check
+both paths share. `approveStep` takes the caller's session and asserts it, and
+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" — `WorkflowApprovalOptions` still
+carries no approver, role or permission, and a second approver on someone else's
+run is still a matter for the route's own `permissions`.
+
+**What this rules out:** treating a run id as a capability, and adding a new run
+read path that does not take a session. It does not rule out a richer approver
+model on `WorkflowApprovalOptions` later; that would narrow this gate, never
+replace it.

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-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/gateway-handlers-run-through-the-function-runner-gate.md

@@ -17,7 +17,16 @@ runner's gate is the only thing that evaluates a function's declared `auth`,
 `scopes` and `permissions`; a direct call runs the handler with none of them
 checked.
 
-The handler is registered with `sessionless: true`. Gateway inbound traffic is
+The synthetic registration **inherits the wired function's own metadata** —
+`sessionless`, input and output schema names, `scopes`, tag middleware — read
+back from `pikkuState(null, 'gateway', 'meta')[name].pikkuFuncId`, which the
+inspector already records. The synthetic id exists so the gate runs; it is not a
+licence to run the handler under metadata its author never wrote. A handler
+declared with `pikkuFunc` says session-required in meta rather than through an
+`auth` property, and that declaration is honoured.
+
+When nothing was declared — no inspector entry, as when a gateway is wired by
+hand — the handler falls back to `sessionless: true`. Gateway inbound traffic is
 authenticated by the platform adapter (webhook signature verification, platform
 tokens), not by a user session, so defaulting to session-required would reject
 every legitimate webhook. `CoreGateway.auth` and the handler's own `auth: true`
@@ -26,6 +35,7 @@ whenever declared, session or not.
 
 **What this rules out:** invoking `config.func` directly from any gateway
 transport as an optimisation, and "simplifying" the synthetic function
-registration away. It also rules out flipping the sessionless default to
-session-required as a hardening measure — that breaks every webhook rather than
+registration away. It also rules out fabricating the handler's metadata rather
+than inheriting it, and flipping the _fallback_ to session-required as a
+hardening measure — that breaks every webhook that declared nothing, rather than
 securing it; require auth per gateway via `CoreGateway.auth` instead.

package/knowledge/decisions/security/index.md

@@ -10,6 +10,11 @@ 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 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 and approved by its owner](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 or answer its approval gates; 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 +29,10 @@ 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 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.