@pikku/core 0.12.71 → 0.12.74

package/knowledge/decisions/internals/workflow-suspended-runs-keep-their-in-process-context.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: A suspended workflow run keeps its in-process context; only terminal runs release it
+description: `suspended` is absent from the terminal set on purpose, and a context is dropped only when nothing is holding it open
+tags: workflow
+---
+
+# A suspended workflow run keeps its in-process context; only terminal runs release it
+
+`WORKFLOW_TERMINAL_STATES` in `pikku-workflow-service.ts` is
+`completed | failed | cancelled`. `suspended` is deliberately absent: a
+suspended run stops a poll loop but can still be resumed, so anything the
+process holds for it — the run context, an extension's per-run state such as a
+scenario's live actor clients — has to survive. `WORKFLOW_END_STATES`, which
+`awaitRunEnd` uses to stop reading, does include `suspended`, because a poller
+should not wait on a run that needs an external nudge. The two sets are not
+interchangeable.
+
+`releaseContext` drops a `RunContext` only when neither `inline` nor `replay`
+still holds it open, so an inline run mid-replay is never torn out from under
+itself. `updateRunStatus` releases on a terminal status because queued runs
+never pass through the inline path that would otherwise do it — without that,
+their context would be held for the life of the process. A long-lived server
+orchestrates many runs, so anything kept per run has to be released when that
+run stops executing here (`workflow-run-context.test.ts`).
+
+**What this rules out:** adding `suspended` to `WORKFLOW_TERMINAL_STATES`,
+collapsing the two state sets into one, or making `releaseContext`
+unconditional — the first two discard state a resume still needs, the third
+frees a context that an in-flight replay is still walking.

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

@@ -0,0 +1,26 @@
+---
+type: decision
+title: A dropped audit write is always logged
+description: The no-op audit service falls back to the singleton logger when the wire carries none, so an unconfigured audit call is never silent
+tags: services
+---
+
+# A dropped audit write is always logged
+
+The no-op `AuditService` in `packages/core/src/services/audit-service.ts` is what
+a function gets when it calls `audit.write()` without `audit: true` set on it.
+Its `write` discards the event — but before it does, it warns once, and it looks
+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.
+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
+once per instance so it cannot flood a hot path.
+
+**What this rules out:** narrowing the logger lookup to a single source,
+downgrading the warning to `debug`, or removing it as noise from a service whose
+whole job is to do nothing. If this class stops warning, an unconfigured audit
+call becomes undetectable.

package/knowledge/decisions/security/actor-flow-missing-approval-decisions-default-to-denied.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: An actor's missing approval decision defaults to denied
+description: 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
+tags: actor-flow
+---
+
+# An actor's missing approval decision defaults to denied
+
+`decideApprovals` in
+`packages/core/src/wirings/actor-flow/run-conversation.ts` maps over the
+target agent's `pendingApprovals`, not over the decisions the persona LLM
+returned. Any `toolCallId` the model omitted, hallucinated, or renamed resolves
+to `approved: false`.
+
+The persona's decision comes from a structured LLM call, and structured output
+is not guaranteed to be complete. Iterating the model's array instead would make
+an omission indistinguishable from silence — and silence would let a scenario
+approve a destructive tool call nobody decided on, then pass.
+
+**What this rules out:** building the decision list from the LLM's `decisions`
+array, and defaulting an unmatched call to `true` to keep a conversation moving.

package/knowledge/decisions/security/actor-sign-in-is-proven-by-set-cookie-not-a-non-empty-jar.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: Actor sign-in is proven by Set-Cookie, not a non-empty jar
+description: HttpScenarioActor tracks its own signedIn flag and requires the sign-in response itself to set a cookie, because a populated jar proves nothing
+tags: services
+---
+
+# Actor sign-in is proven by Set-Cookie, not a non-empty jar
+
+`HttpScenarioActor` (`packages/core/src/services/http-scenario-actors.ts`) keeps
+a private `signedIn` boolean rather than inferring the session from its cookie
+jar, and `login()` throws when the sign-in response carries no `Set-Cookie`
+header even though the response was a 2xx.
+
+A cookie jar cannot answer "did sign-in happen". A target app may set a cookie on
+any request — a CSRF token, an anonymous session, a locale — so a non-empty jar
+after a failed or skipped sign-in looks exactly like a successful one. What
+actually proves a session was established is *this* response setting a cookie. A
+2xx alone is not enough either: an endpoint that returns 200 while quietly
+declining to issue a session would leave the actor running every subsequent
+request unauthenticated, and the scenario would report the resulting refusals as
+genuine permission failures.
+
+**What this rules out:** replacing `signedIn` with a `jar.isEmpty()` check,
+dropping the `getSetCookie().length === 0` guard as redundant with `res.ok`, and
+treating `signOut()` as jar-clearing only — it must reset the flag too, or the
+next call proceeds believing it has a session.

package/knowledge/decisions/security/actor-sign-in-only-works-for-actor-flagged-users.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: Actor sign-in only works for actor-flagged users
+description: The scenario actor secret mints sessions for user rows flagged actor and nothing else, so holding it never impersonates a real user
+tags: services
+---
+
+# Actor sign-in only works for actor-flagged users
+
+`HttpScenarioActorsConfig.secret`
+(`packages/core/src/services/http-scenario-actors.ts`) is a shared impersonation
+secret: `HttpScenarioActor.login` POSTs `{ email, name, secret }` to
+`/auth/sign-in/actor` and gets back a session. That looks like a master key, and
+it deliberately is not one.
+
+The Better Auth actor plugin on the other end upserts and signs in only user rows
+flagged `actor: true`. Presenting the secret with a real customer's email does not
+mint that customer's session — it is refused. The `actor` flag also flows into the
+minted session, so audits and analytics can tell scenario traffic from human
+traffic after the fact. The blast radius of a leaked actor secret is therefore the
+synthetic actor population, not the user table.
+
+**What this rules out:** widening the sign-in endpoint to accept any email "so
+scenarios can test as a real user", and treating the actor secret as equivalent to
+a session-signing key. It also rules out dropping the `actor` flag from the minted
+session — the audit trail's ability to separate synthetic from real activity
+depends on it.

package/knowledge/decisions/security/addon-auth-and-tags-only-tighten.md

@@ -0,0 +1,43 @@
+---
+type: decision
+title: Addon auth and tags only tighten, and resolve where the function runs
+description: wireAddon auth and tags are applied in runPikkuFunc like scopes, but auth:false is ignored and tags resolve against the consuming app's tag groups rather than the addon package's
+tags: addon, auth, tags, authorization
+---
+
+# Addon auth and tags only tighten, and resolve where the function runs
+
+`wireAddon({ auth, tags })` was read only by `resolveAddonFunction` in
+`rpc-runner.ts`, which covers the `namespace:function` RPC form alone. Every
+direct wiring — the inspector writes the addon's package name onto http,
+channel, schedule, queue, cli, trigger, gateway and mcp wirings — reached
+`runPikkuFunc` with a `packageName` and neither value. That is the same hole
+[addon scopes](./addon-scopes-are-resolved-where-the-function-runs.md) had, and
+it is closed the same way: `runPikkuFunc` resolves both from the addon config.
+
+`auth` merges as an OR and `auth: false` is ignored. The RPC path treats it as a
+default (`addonConfig?.auth ?? options.requiresAuth`) because there the addon
+config is the only statement of intent. On a direct wiring the route already
+carries its own `auth`, so honouring `false` would let an addon *weaken* a gate
+the app wrote — the inverse of what a wiring-level declaration should be able to
+do. An addon may require a session the wiring did not; it may never waive one
+the wiring did.
+
+Tags resolve against the **root** tag groups, not the addon package's. A tag on
+`wireAddon` is written by the consuming app, and `addTagMiddleware('admin', …)`
+in that app registers under the root package. `combineMiddleware` looks tag
+metadata up under the `packageName` it is given, which for an addon function is
+the addon's own namespace — where the app's middleware does not exist. Resolving
+addon tags to concrete middleware before the call and passing them as
+`wireMiddleware` is what keeps `wireAddon({ tags: ['admin'] })` from being
+silently inert, which is the failure mode the whole gate exists to avoid.
+
+A function's own tags are unaffected: the inspector already emits them as
+`{ type: 'tag' }` entries on the function and wiring meta, resolved under the
+package that declared them. The `tags` argument `runPikkuFunc` accepts is
+separate and still unused on every path.
+
+**What this rules out:** honouring `auth: false` from an addon on a direct
+wiring; resolving addon tags under the addon's `packageName`; and folding addon
+tags into `funcInheritedMiddleware`, which would resolve them in the wrong
+namespace and double-apply the function's own tags.

package/knowledge/decisions/security/addon-config-gates-apply-only-at-the-namespaced-rpc-boundary.md

@@ -0,0 +1,52 @@
+---
+type: decision
+title: Addon auth and tag gates apply wherever the function runs, including inside the addon
+description: wireAddon's auth and tags moved from the namespaced RPC boundary into runPikkuFunc, so they also apply to direct wirings and to bare intra-addon calls
+tags: rpc, addon, auth
+---
+
+# Addon auth and tag gates apply wherever the function runs, including inside the addon
+
+`ContextAwareRPCService.invokeAddonFunction` used to be the only place that
+applied an addon's `addonConfig.auth` and `addonConfig.tags`, making them a
+perimeter control on `rpc('namespace:fn')`. That perimeter had a hole in it: the
+inspector writes the addon's package name onto http, channel, schedule, queue,
+cli, trigger, gateway and mcp wirings, and every one of those runners calls
+`runPikkuFunc` directly without resolving a namespace. A consumer who wrote
+`wireAddon({ auth: true })` and then wired an addon function to a route got no
+gate at all.
+
+Both values now resolve in `runPikkuFunc`, the one point every path shares —
+the same move, for the same reason, as
+[addon scopes](./addon-scopes-are-resolved-where-the-function-runs.md). See
+[addon auth and tags only tighten](./addon-auth-and-tags-only-tighten.md) for
+the merge rules.
+
+This replaces a consequence an earlier decision accepted: a bare `rpc('fn')`
+made from inside an addon now re-applies the gate, because it reaches
+`runPikkuFunc` with the addon's `packageName` like any other call. The earlier
+reasoning — that the perimeter had already been passed, so re-checking would
+gate internal calls on a consumer-facing setting — held only while the perimeter
+was real. Once a direct wiring could enter the addon without passing any gate,
+"already inside" stopped being something the runtime could infer, and the choice
+became re-checking or trusting an entry that may never have happened.
+
+In practice an intra-addon call inherits the entry point's session, so the auth
+check passes wherever the entry was itself authenticated. What it does break is
+an addon that wires `auth: true` and also runs its own sessionless internal
+work — a scheduled task or queue worker inside the addon calling a sibling. Such
+an addon should carry authorization on the function via
+`pikkuFunc({ permissions })`, which has always been enforced on every path,
+rather than on the consumer-facing `wireAddon` setting.
+
+Re-checking was chosen over provenance because the marker that would make
+"already inside" knowable — set by the runtime, unsettable by any caller outside
+the process, threaded through all eight runners — is a design problem of its
+own, and shipping it inside a security fix would have meant landing an untested
+trust signal alongside the gate that depends on it. Adding that marker is
+tracked separately; until it exists, re-checking is the only option that does
+not trust an entry which may never have happened.
+
+**What this rules out:** treating `addonConfig.auth` as a perimeter-only
+control; and inferring "already inside the addon" from the wire, which a direct
+wiring does not set.

package/knowledge/decisions/security/addon-scopes-are-resolved-where-the-function-runs.md

@@ -0,0 +1,46 @@
+---
+type: decision
+title: Addon scopes are resolved where the function runs
+description: wireAddon scopes are merged inside runPikkuFunc rather than at namespace resolution, because most wirings reach an addon function without ever resolving a namespace
+tags: addon, scopes, authorization
+---
+
+# Addon scopes are resolved where the function runs
+
+`wireAddon({ scopes })` names scopes every function in the addon's package
+requires. `runPikkuFunc` calls `resolveAddonScopes(packageName,
+addonInstance?.namespace)` and unions the result with the function's own
+`scopes` before `verifyScopes`.
+
+The obvious home for this is `resolveAddonFunction` in `rpc-runner.ts`, next to
+where `auth` and `tags` are already merged from the addon config — but that
+covers only the `namespace:function` RPC form. An addon function is reachable
+without any namespace resolution: the inspector's `resolveAddonName` writes the
+addon's package name onto the wiring meta whenever a wiring's `func` is an
+identifier imported from a wired addon, and every runner (`http-runner`,
+`mcp-runner`, channel, scheduler, queue, cli, trigger, gateway) then passes that
+`packageName` straight to `runPikkuFunc`. `refHTTP` / `refChannel` / `refCLI`
+contracts do the same through `registerHTTPRouteMeta`. A gate at namespace
+resolution would leave every one of those doors open while reading as complete,
+which is worse than no gate. `runPikkuFunc` is the one point all of them share.
+
+Merging is a union, not an override, because `firstUnsatisfied` in `scopes.ts`
+requires every listed scope. An addon scope is therefore an additional
+requirement and can only narrow access — an addon can never weaken a function
+that declares stricter scopes of its own. `ref('namespace:fn')` routes are
+gated for the same reason from the other direction: the generated wrapper is a
+local function that calls `rpc.invoke`, so the addon's scopes attach on the
+inner call rather than the route.
+
+When the caller carries an `addonInstance`, its namespace selects that
+instance's scopes exactly. The direct-wiring paths know only a package name, so
+`resolveAddonScopes` unions the scopes of every namespace the package is wired
+under. One package wired twice with different scopes is rare; taking the
+stricter reading keeps the unnamed path from becoming the weak one.
+
+**What this rules out:** gating addon functions in `resolveAddonFunction`,
+`resolveNamespace`, or any per-wiring runner; treating addon scopes as a
+default that a function's own `scopes` replaces; resolving a package's scopes
+by first matching namespace, the way `findAddonNamespaceForPackage` resolves
+services; and reusing this for `wireRemoteAddon`, whose functions execute on the
+host and are gated there.

package/knowledge/decisions/security/ai-agent-approval-forwarding-requires-a-symbol-brand.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: Only a Symbol-branded framework result can request tool approval
+description: Approval markers are trusted from the APPROVAL_REQUIRED Symbol on a forwardsApproval tool, never from a JSON key an LLM could emit
+tags: ai-agent
+---
+
+# Only a Symbol-branded framework result can request tool approval
+
+`checkForApprovals` in
+`packages/core/src/wirings/ai-agent/ai-agent-stream.ts` honours a forwarded
+approval only when both hold: the tool declares `forwardsApproval` (set solely by
+framework code on the sub-agent delegating tools built in
+`ai-agent-prepare.ts`), and its result carries the `APPROVAL_REQUIRED` unique
+Symbol. The companion `__approvalRequired` string key exists for transport, but
+is never what the decision reads.
+
+A tool result is attacker-influenceable — a retrieved document, a third-party API
+response, or a sub-agent's LLM-shaped `result.object`. All of those are plain
+JSON, and plain JSON cannot carry a Symbol. Trusting the string key would let any
+ordinary tool conjure a suspension and an approval prompt showing a tool name and
+arguments of its choosing.
+
+**What this rules out:** checking `'__approvalRequired' in result` as the
+condition; replacing the Symbol with a string or numeric sentinel so results
+survive JSON serialization; and setting `forwardsApproval` from user-supplied
+tool configuration rather than from framework code.

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

@@ -0,0 +1,37 @@
+---
+type: decision
+title: Credential requests are trusted only when Symbol-branded
+description: The string key is a wire field; the Symbol is the capability, and only core can mint it
+tags: ai-agent
+---
+
+# Credential requests are trusted only when Symbol-branded
+
+A tool result asking the run to suspend and prompt for a credential is honoured
+only when it carries the `CREDENTIAL_REQUIRED` Symbol minted in
+`ai-agent-prepare.ts`. `checkForCredentialRequests` in `ai-agent-stream.ts`
+tests for that Symbol, never for the `__credentialRequired` string key that
+travels beside it on the wire.
+
+The distinction is the whole security property. Tool results are frequently
+attacker-influenceable — a retrieved document, an echo from a third-party API,
+LLM-authored content round-tripping through a tool — and any of those can carry
+a string key. None can carry a Symbol, because a Symbol has no literal form and
+does not survive JSON. Without the brand, an influenced tool result could
+suspend the run and push a `credential-request` event with an attacker-chosen
+`connectUrl`, which the client renders as a "Connect" button: a phishing
+primitive inside the product's own UI. This mirrors the `APPROVAL_REQUIRED`
+brand, which exists for the identical reason one function over.
+
+The brand survives because the object is passed by reference the whole way —
+core's `buildToolDefs` wrapper returns it, the Vercel adapter's `aiTool` hands
+it back verbatim, and the AI SDK puts the raw value on the stream part rather
+than the JSON form it builds separately for the model.
+
+**What this rules out:** widening the check to `'__credentialRequired' in
+result` for convenience, or introducing any path where a credential request is
+reconstructed from parsed JSON rather than passed by reference — either one
+silently converts the gate into a formality. Note the inverse holds for the
+`credentialFilteredChannel` suppression later in the same file: that one
+deliberately matches the *string* key, because it hides tool results from the
+client and a broader match leaks less, not more.

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

@@ -0,0 +1,31 @@
+---
+type: decision
+title: An agent requires a session only when auth is true, but always enforces scopes and permissions
+description: Agents follow pikkuSessionlessFunc semantics so crons and queue workers can run them; scopes are an AND gate checked before any permission I/O
+tags: ai-agent
+---
+
+# An agent requires a session only when auth is true, but always enforces scopes and permissions
+
+`assertAgentAuthorized` in
+`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` enforces, in order:
+session presence (only when `CoreAIAgent.auth === true`), then `scopes`, then
+`permissions`. The ordering mirrors the function runner — scopes AND together so
+they can only narrow access, and a missing scope short-circuits before any
+permission function does I/O. Declared `scopes` are narrowed to the generated
+`ScopeId` union in a project's `pikku-types.gen.ts`, so an undeclared scope is a
+compile error.
+
+`auth` defaults to `false` (i.e. `pikkuSessionlessFunc`, not `pikkuFunc`) because
+an agent is normally reached from a function that already enforced its own auth,
+and is also run from genuinely sessionless contexts such as crons and queue
+workers. Requiring a session by default would reject those without adding a real
+gate. Global permissions are evaluated here too rather than assumed to have
+already run, because an agent is reachable from entry points that never pass
+through the function runner; re-evaluating an AND gate of side-effect-free
+predicates is idempotent.
+
+**What this rules out:** making `auth: true` the default; checking permissions
+before scopes; skipping globals on the assumption a caller already ran them; and
+moving the gate into the individual run/stream/resume entry points, where a new
+entry point would silently miss it.

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

@@ -0,0 +1,23 @@
+---
+type: decision
+title: An agent ownership failure never echoes the resource it refused
+description: assertResourceOwner throws a bare ForbiddenError so the error cannot be used as an existence oracle, at the cost of thinner debugging output
+tags: ai-agent
+---
+
+# An agent ownership failure never echoes the resource it refused
+
+`assertResourceOwner` in
+`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` compares a stored
+thread/run `resourceId` against the caller's composed owner key and throws
+`ForbiddenError('Not authorized to access this thread' | '… run')` on a
+mismatch. The message deliberately carries no id.
+
+Including the id would turn the endpoint into an existence oracle: a caller
+enumerating thread ids could tell "exists but is not yours" apart from "does not
+exist", which leaks the shape of other tenants' data even though no content is
+returned.
+
+**What this rules out:** improving the error message by interpolating the
+`threadId`, `runId`, or owner key into it, and distinguishing not-found from
+not-authorized on the read paths.

package/knowledge/decisions/security/ai-agent-resume-re-runs-the-authorization-gate.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Resuming a suspended agent run re-runs the agent's authorization gate
+description: Ownership of the run is not enough — a grant revoked while the run was suspended must block the approval
+tags: ai-agent
+---
+
+# Resuming a suspended agent run re-runs the agent's authorization gate
+
+Both `resumeAIAgent` (`ai-agent-stream.ts`) and `resumeAIAgentSync`
+(`ai-agent-runner.ts`) call `assertAgentAuthorized` after asserting run
+ownership and before touching `aiRunState.resolveApproval`.
+
+Ownership proves the run belongs to the caller, not that the caller may still
+act on it: a suspension can outlive the permission that created it, and the whole
+point of an approval gate is that the person approving is authorized at the
+moment of approval. Resolving an approval is a persisted side effect, so the
+gate must run before it, not after.
+
+**What this rules out:** treating the ownership assertion as the complete
+authorization check on the resume paths, and moving `assertAgentAuthorized`
+below `resolveApproval` for convenience.

package/knowledge/decisions/security/ai-agent-sessionless-deployments-have-no-thread-ownership.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: Agent thread ownership fails closed when there is no principal
+description: A sessionless caller gets an ephemeral owner and reaches no stored thread, rather than reaching all of them
+tags: ai-agent
+---
+
+# Agent thread ownership fails closed when there is no principal
+
+`canAccessThread` returns `false` and `threadOwnerConstraint` returns `[]` when
+the session carries neither `userId` nor `orgId`
+(`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`).
+`resolveOwnerResourceId` never accepts the client-supplied `resourceId` as an
+ownership key; without a principal it mints an ephemeral `anon-<uuid>` owner
+memoized on the request's params object.
+
+Agent wirings default to `auth: false`, so "no session" is the common case
+rather than an exotic one. Treating it as "no ownership model to enforce" made
+every ownership check vacuous: a caller named any `resourceId` and reached that
+thread, and because `undefined` on `AgentRunService.listThreads` means *no
+filter* rather than *no rows*, a sessionless `getAgentThreads` returned every
+thread in the deployment. The ephemeral owner is what keeps one-shot
+conversations working while denying continuity — it is unguessable, so nothing
+stored can be reached, and it is stable within a request, so a sub-agent
+re-entering `resolveOwnerResourceId` reuses its parent's thread.
+
+Memoizing on the params object rather than a module-level Map is what keeps this
+serverless-safe: the identity dies with the request and is never shared between
+instances. `canAccessThread` stays a predicate rather than an assertion so it can
+back a `pikkuPermission` — authorization belongs in a function's `permissions`
+field, never in its body.
+
+**What this rules out:** returning `undefined` from `threadOwnerConstraint` for
+any caller; deriving `owners` from request input instead of the session; reading
+`auth: false` as permission to skip ownership on a *stored* thread; and
+persisting the anonymous owner anywhere, which would turn an ephemeral identity
+into a forgeable one. Cross-request thread continuity without a session is not
+available by design — wire a session to get it back. See
+[[an-empty-owners-constraint-matches-nothing]].

package/knowledge/decisions/security/ai-agent-thread-ownership-composes-the-session-principal.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: An agent thread key is always prefixed with the trusted principal
+description: Ownership keys are composed as principal:resourceId, so a client id can sub-divide its own boundary but never widen it
+tags: ai-agent
+---
+
+# An agent thread key is always prefixed with the trusted principal
+
+`resolveOwnerResourceId` in `packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`
+composes the ownership key for a thread or run as `principal:resourceId`. The
+principal is the trusted one — `session.userId` for the default `'user'`
+`SessionScope`, `session.orgId` for `'org'` — and the client-supplied
+`resourceId` is only ever a sub-partition inside it. Composition is idempotent:
+a value already inside the caller's namespace (top-level re-entry, sub-agent
+recursion, resume — all of which pass an already-composite id) is returned
+unchanged rather than composed twice.
+
+`'org'` scope with no org on the session throws `ForbiddenError` instead of
+falling back to a bare or shared key, because a shared key leaks threads across
+organizations. A sessionless `'user'` wiring has no trusted principal at all and
+falls back to the requested `resourceId` as a best-effort partition.
+`isOwnedByPrincipal` requires the `:` separator when matching sub-partitions so
+that a principal `alice` does not match a lookalike `alice-evil:…` key.
+
+**What this rules out:** storing threads under the client's `resourceId`
+directly; making the composition non-idempotent (resume and sub-agent recursion
+would double-prefix and lose their own threads); testing ownership with a bare
+`startsWith(principal)` that omits the separator; and letting `'org'` scope
+degrade to a shared key when the session carries no organization.

package/knowledge/decisions/security/ai-agent-tool-filtering-reads-the-live-function-config.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: Agent tool permission filtering reads the live function config, not the metadata
+description: The pikkuAuth brand survives only on live permission objects, so a metadata-driven check would silently admit every gated tool
+tags: ai-agent
+---
+
+# Agent tool permission filtering reads the live function config, not the metadata
+
+`buildToolDefs` in `packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`
+decides which tools and sub-agents to expose to the model by calling
+`checkAuthPermissions` against the permission objects held in the live function
+(or agent) config in `pikkuState`, using the metadata only to learn that a
+permission exists at all.
+
+The `pikkuAuth` brand that marks a permission as an authorization gate exists
+only on those live objects. The metadata's by-name permission registry is never
+populated, so resolving names through it collects no predicates — and a filter
+that collects no predicates admits everything. The failure is silent: every gated
+tool would be handed to the model for any session.
+
+**What this rules out:** simplifying the filter to read
+`fnMeta.permissions` / `subMeta.permissions` directly, and caching a
+name-to-predicate map derived from metadata.

package/knowledge/decisions/security/an-empty-owners-constraint-matches-nothing.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: An empty owners constraint matches nothing
+description: owners is an authorization boundary, so every storage backend must treat [] as no rows rather than no filter
+tags: ai-agent, storage
+---
+
+# An empty owners constraint matches nothing
+
+Every `AgentRunService.listThreads` implementation returns `[]` immediately when
+`owners` is present and empty — `kysely-ai-agent-run-service.ts`,
+`redis-agent-run-service.ts`, `mongodb-agent-run-service.ts`. The conformance
+suite in `packages/core/src/testing/service-tests.ts` pins it, so a new backend
+inherits the requirement instead of rediscovering it.
+
+`owners` is an authorization boundary, not an optional filter. The natural way
+to write a query builder is to skip a clause when its list is empty, which
+silently converts "this caller may see nothing" into "this caller may see
+everything" — the failure is invisible in review because the omitted clause
+looks like an optimization. Placing the guard before the query is built, in
+every backend, means the dangerous shape never exists.
+
+This is what makes the sessionless `[]` from `threadOwnerConstraint` safe to
+return; the two decisions only hold together.
+
+**What this rules out:** folding the empty case into the query builder's normal
+`if (owners)` path; treating `owners: []` as equivalent to `owners: undefined`
+at any layer; and adding a backend without the conformance suite.
+
+See [[ai-agent-sessionless-deployments-have-no-thread-ownership]].

package/knowledge/decisions/security/an-exposed-ungated-function-is-a-codegen-warning.md

@@ -0,0 +1,49 @@
+---
+type: decision
+title: An exposed function with no gate is reported at codegen, not at boot
+description: 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
+tags: authorization, inspector, addon, rpc
+---
+
+# An exposed function with no gate is reported at codegen, not at boot
+
+The generated `POST /rpc/:rpcName` dispatcher forwards to `rpc.exposed`, which
+refuses anything without `expose: true`. That makes the reachable set small and
+deliberate — someone typed it. What it does not do is check whether the target
+is gated, because a dispatcher cannot know what it is dispatching to. The
+console shipped ~54 privileged functions through exactly this gap, and nothing
+in the toolchain said so.
+
+The check belongs next to `validateAuthSessionless`, in the inspector, for one
+reason: it needs two sources that only meet there.
+
+`sessionless` records the baseline — a `pikkuFunc` always requires a session —
+but a `pikkuSessionlessFunc` may still tighten itself with `auth: true`, which
+the inspector previously discarded. It is now recorded on function meta, so
+"sessionless and ungated" is distinguishable from "sessionless and
+self-gated" without running anything.
+
+The second source is `wireAddon`. Its `scopes` and `auth` apply to every
+function in the package on every wiring path (see
+[addon scopes](./addon-scopes-are-resolved-where-the-function-runs.md)), so a
+function with no gate of its own may still be fully covered. The inspector
+already parsed `wireAddon` for its endpoint and its secret, variable and
+credential overrides, and dropped `scopes`, `auth` and `tags` — the addon's
+plumbing was recorded in full and its authorization was not. Reading function
+meta alone would have reported every console function as open.
+
+An addon whose gates are not statically knowable — a spread, a const reference —
+is recorded as absent, and absent is read as **gated**. This is deliberately the
+wrong way round from how a runtime gate fails: a false negative costs one
+missing warning, while a false positive on a correctly-secured addon costs
+confidence in every warning the tool emits, which is worth more than the one
+case it would catch.
+
+Severity is `warn`, not `critical`. `expose: true` on an ungated sessionless
+function is legitimate for a genuinely public endpoint — a health check, a
+sign-up — so this cannot block a build without breaking correct programs. It
+fails a build only under `--fail-on-warn`.
+
+**What this rules out:** checking at boot, where the report arrives after
+deployment; checking in `pikku validate` from `.pikku` JSON, which does not
+carry `wireAddon` at all; and treating an unparseable addon gate as no gate.