@pikku/core 0.12.72 → 0.12.77

package/knowledge/decisions/internals/workflow-scenario-hooks-are-a-scenario-only-affordance.md

@@ -0,0 +1,43 @@
+---
+type: decision
+title: Scenario lifecycle hooks are a scenario-only affordance and never mask the failure they follow
+description: A durable workflow replays, so a callback that reruns each replay has no honest meaning there
+tags: workflow
+---
+
+# Scenario lifecycle hooks are a scenario-only affordance and never mask the failure they follow
+
+`PikkuScenarioService.scenarioHooks` (`pikku-scenario-service.ts`) returns hooks
+only when `workflowMeta.source === 'scenario'`. A plain workflow is durable and
+resumable, so a `before`/`after` callback that reran on every replay would have
+no honest meaning — hooks exist for scenarios because a scenario run is a single
+pass by a single external process.
+
+A hook is not a pikku function: it has no id, no meta and no schema, so it
+cannot go through `runPikkuFunc` and the runner records nothing for it. It gets
+exactly what the scenario body gets — the same wire (which is how it reaches the
+app through `actors`) and singleton services composed with this invocation's
+wire services — and nothing else. `ScenarioHookError` keeps the original error
+as `cause`, so the failure that actually happened is never lost behind the label
+saying which phase it happened in.
+
+`onAfterRunFunc` returns early on the `interrupted` outcome, because the run is
+suspended or waiting and teardown would fire mid-flight. When the scenario has
+already failed for its own reason, an `after`-hook failure is attached as
+`cause` and logged rather than replacing the headline; only a teardown failure
+after a *passing* scenario fails the run.
+
+At the feature level (`workflow.types.ts`, `CoreFeature`), hooks run once around
+the whole group — `before → a → b → c → after` — not per scenario. That is the
+one thing a feature deliberately cannot express: gherkin's `Background:` runs
+per scenario, and per-scenario setup is the scenario's own `before`.
+
+`setScenarioEnvironment` on the same service is per-service, not per-run, for a
+related reason: a runner process targets exactly one environment for every
+scenario it executes, so threading it through each run would only create ways
+for two runs in one process to disagree.
+
+**What this rules out:** offering hooks on plain workflows, routing a hook
+through `runPikkuFunc` so it gets recorded as a step, running `after` on an
+interrupted run, letting a teardown failure overwrite the scenario's own
+failure, or reinterpreting feature hooks as per-scenario `Background:`.

package/knowledge/decisions/internals/workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: Scenario prose is rendered out of typed calls, not parsed into them
+description: The inversion of cucumber — a readable report with no regex step registry to maintain
+tags: workflow
+---
+
+# Scenario prose is rendered out of typed calls, not parsed into them
+
+`scenario-prose.ts` renders the English sentence a reporter shows for a scenario
+step. It is the inversion of cucumber: instead of parsing English into a call
+through a registry of regexes, the call is typed and the English is rendered out
+of it. The readable report survives without anyone maintaining a step-definition
+registry, and a step that no longer exists cannot leave a dangling phrase behind.
+
+`renderScenarioProse` fills a step's `template` from the input the step was
+actually called with, so the sentence names the values under test — "sees
+@pikku/addon-todos" rather than "sees an addon in the gallery" three times over.
+A placeholder with no recorded value renders as nothing and the surrounding
+whitespace collapses, so an omitted optional input reads as a shorter sentence
+rather than leaking a literal `{state}` into the report. `template` is
+deliberately distinct from `description`: `description` documents what the step
+does, `template` is what a reader of the report sees, and it falls back to
+`description` when absent.
+
+It lives in `@pikku/core` rather than in the CLI so the CLI reporter and the
+console render the same sentence for the same step.
+
+**What this rules out:** adding a gherkin parser or regex step registry,
+rendering prose in the CLI reporter or console instead of core (the two would
+drift), collapsing `template` into `description`, or making a missing
+placeholder value render as the raw placeholder.

package/knowledge/decisions/internals/workflow-scenario-quarantine-reason-lives-in-code.md

@@ -0,0 +1,18 @@
+---
+type: decision
+title: A quarantined scenario states its reason in code, not in a CI invocation
+description: `skip` carries the why next to the scenario it applies to, and naming the scenario explicitly still runs it
+tags: workflow
+---
+
+# A quarantined scenario states its reason in code, not in a CI invocation
+
+`WorkflowsMeta`'s `skip` field (`workflow.types.ts`) is a string, not a boolean.
+A scenario held out of a default run has to say why, and stating the reason in
+code keeps the quarantine next to the scenario it applies to rather than buried
+in a CI invocation nobody reads. A skipped scenario is still runnable — naming
+it explicitly with `--flows` runs it regardless — so quarantine is a default,
+not a disablement.
+
+**What this rules out:** turning `skip` into a boolean flag, moving the skip
+list into CI configuration, or making a skipped scenario unrunnable.

package/knowledge/decisions/internals/workflow-scenario-step-targets-are-string-literals-for-the-inspector.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: Scenario step targets are string literals so the inspector can read them statically
+description: `step/given/when/then` mirror `do`'s RPC shape because the extractor reads a literal, not an imported symbol
+tags: workflow
+---
+
+# Scenario step targets are string literals so the inspector can read them statically
+
+`ScenarioStepInvocation` in `dsl/workflow-dsl.types.ts`, and the `step`,
+`given`, `when` and `then` members of `PikkuScenarioWire`, all take
+`(stepName, stepFunc: string, data?, options?)` — deliberately the same shape as
+`WorkflowWireDoRPC`. The target is a string, not an imported symbol, because
+the Pikku inspector is static analysis: it reads the argument as a literal and
+does not resolve identifiers. Type safety comes back at the edges — the
+generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
+
+`given`/`when`/`then` are pure sugar over `step`; the phase only changes the
+prose a reporter renders (`scenario-prose.ts`), never what executes.
+
+The prose direction is itself the decision: rather than parsing English into a
+call the way cucumber does, `composeStepProse` renders English out of a typed
+call, so a readable report survives without a regex registry paying for it. It
+lives in core so the CLI reporter and the console render the same sentence for
+the same step, and `renderStepTemplate` fills `{placeholders}` from the input
+the step was actually called with — "sees @pikku/addon-todos" rather than the
+same generic sentence three times. A placeholder with no recorded value renders
+as nothing and the surrounding whitespace collapses, so an omitted optional
+input reads as a shorter sentence rather than leaking a literal `{state}`.
+
+**What this rules out:** changing `stepFunc` to accept the imported step config,
+reordering the arguments away from `do`'s shape, giving `given`/`when`/`then`
+behaviour of their own, or moving prose rendering into the CLI where the console
+would drift from it.

package/knowledge/decisions/internals/workflow-step-compensation-runs-as-its-own-durable-step.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: A step's compensation handler runs as a durable step of its own, and never compensates itself
+description: A refund or rollback must not fire twice on replay, so `onError` is recorded as `<step>:onError` with retries disabled
+tags: workflow
+---
+
+# A step's compensation handler runs as a durable step of its own, and never compensates itself
+
+`runStepCompensation` in `pikku-workflow-service.ts` invokes a failed step's
+`onError` RPC through `rpcStep` under the name `<stepName>:onError` rather than
+calling it directly. Durability is the point: a compensation handler is
+typically a refund or a rollback, and a bare invoke would fire again on every
+replay that walks past the failed step. Recorded as a step, the second replay
+finds it `succeeded` and returns the cached result.
+
+It runs with `{ retries: 0 }` and its own `onError` is deliberately not
+forwarded — a compensation handler cannot itself compensate. `onError` mirrors a
+graph node's: the handler receives `{ error: { message } }`, and the original
+error is still thrown afterwards, so the workflow fails either way. This is
+compensation, not recovery.
+
+**What this rules out:** invoking the `onError` RPC inline "since it's just
+cleanup", giving it the workflow's default retry count, chaining a second
+`onError` onto it, or swallowing the original error because the handler
+succeeded.

package/knowledge/decisions/internals/workflow-step-dispatch-failure-is-transient-not-a-run-failure.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: A failed workflow step dispatch is transient infrastructure, not a run failure
+description: Queue-unreachable errors leave the run running and the step pending so the orchestrator replays; marking the run failed loses it
+tags: workflow
+---
+
+# A failed workflow step dispatch is transient infrastructure, not a run failure
+
+`WorkflowDispatchException` (`pikku-workflow-service.ts`) means the queue itself
+could not accept the job — pg-boss momentarily down, the transport unreachable —
+not that the step's own logic failed. Everywhere it surfaces (`dispatchStep`,
+`sleepStep`, `startWorkflow`, `orchestrateWorkflow`) the run is left untouched:
+the step stays `pending`, the run stays `running`, and the orchestrator job is
+rethrown so the queue redelivers it and the workflow replays from its snapshot.
+
+The ordering inside `rpcStep` and `sleepStep` is load-bearing: dispatch happens
+BEFORE the step is marked `scheduled`. If the step were marked `scheduled`
+first and the dispatch then failed, the next replay would see `scheduled`,
+pause, and wait forever for a job that was never enqueued.
+
+Redelivery is always safe because an orchestrator job is idempotent: it replays
+the workflow from the snapshot and every already-completed step returns its
+cached result rather than running again. The per-job `attempts` that
+`resolveStepJobOptions` always emits is what makes redelivery happen at all — it
+overrides a queue configured with `retry_limit 0`, so the workflow's retry
+policy survives a conservative queue configuration.
+
+**What this rules out:** folding `WorkflowDispatchException` into the generic
+catch that calls `updateRunStatus(runId, 'failed', ...)`, swallowing it so the
+run silently stalls, or reordering `setStepScheduled` above `dispatchStep` /
+`scheduleSleep` to "keep the status writes together". Each strands or kills a
+run that a redelivered orchestrator tick would have recovered on its own.

package/knowledge/decisions/internals/workflow-step-lock-is-held-only-to-claim-the-step.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: A workflow step lock is held only to claim the step, never across its execution
+description: Holding the advisory lock — and its pooled connection — across step work exhausted the connection pool and self-deadlocked
+tags: workflow
+---
+
+# A workflow step lock is held only to claim the step, never across its execution
+
+`executeWorkflowStep` in `pikku-workflow-service.ts` takes `withStepLock` for an
+atomic check-and-mark-running only: it reads the step, returns `null` if the
+step already `succeeded` or is already `running` (another worker owns it),
+starts a fresh attempt if it `failed`, and otherwise marks it `running`. The
+lock is then released, and the actual work plus result persistence run outside
+it.
+
+The guard is what makes that safe — once a step is `running`, any concurrent
+worker returns early. The alternative was tried and failed: holding the advisory
+lock, and therefore its pooled connection, across `executeGraphStep` (network
+I/O plus further pool queries) let concurrent steps exhaust the connection pool
+and self-deadlock.
+
+**What this rules out:** widening the `withStepLock` callback to cover RPC
+invocation, child-workflow start, `setStepResult` or `resumeWorkflow` — the
+"obviously safer" refactor that reintroduces the deadlock. If a stronger
+guarantee is ever needed it has to come from the claim itself, not from a longer
+lock hold.

package/knowledge/decisions/internals/workflow-step-rpc-name-is-provenance-only.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it
+description: It exists so a reader can join a runtime step row back to the declaration that produced it, especially when the durable name was built in a loop
+tags: workflow
+---
+
+# A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it
+
+`insertStepState` and `inlineStep` in `pikku-workflow-service.ts` record the
+name a step was dispatched by: an RPC for a `workflow.do` step, a step function
+for a scenario step, `null` for a closure. Nothing in the engine dispatches off
+that value — it is stored so a reader can join a step back to the function that
+ran it.
+
+It earns its keep when the durable step name was built at runtime. A scenario
+step called in a loop reaches the run as, say, `sees @pikku/addon-todos` while
+it was declared as ``sees ${packageName}``; the recorded step-function name is
+then the only way to join that row back to its declaration. `inlineStep` also
+records the `data` the step was called with for the same reason: a reporter
+renders each step's prose from it, so two calls to one step stay
+distinguishable by what they were asked to check.
+
+Step lineage is recorded alongside it. `fromStepName` is the predecessor that
+scheduled a step — the walked transition — captured by `rpcStep`/`inlineStep`
+*before* `nextStepKey` advances the lineage, and surfaced to a step as
+`fromInvocationId`. In a cyclic graph `a → b → a → c`, the second `a` therefore
+carries `b`'s id, which is what lets the walked path be reconstructed from the
+chain alone.
+
+**What this rules out:** treating the recorded name as the dispatch target,
+dropping it for closure steps "since it is always null", capturing
+`lastStepName` after `nextStepKey` has run, or omitting `data` on inline steps —
+each breaks either the join back to source or the reconstructed path.

package/knowledge/decisions/internals/workflow-suspend-and-approval-reasons-are-durable-step-identities.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: A suspend or approval `reason` is the step's durable identity, not just a message
+description: The reason is namespaced and used raw as the step key, so it must be derived deterministically across replays
+tags: workflow
+---
+
+# A suspend or approval `reason` is the step's durable identity, not just a message
+
+`getSuspendStepName` and `getApprovalStepName` in `pikku-workflow-service.ts`
+derive a step key from the `reason` string — `__workflow_suspend:<reason>` and
+`__workflow_approval:<reason>`. Each distinct reason is therefore its own step
+row, which is what lets one workflow hold several independent suspends
+(wait-for-build, then wait-for-approval) and lets a dynamic reason inside a loop
+work exactly like a dynamic `do()` step name. The two prefixes are separate
+namespaces so a suspend, an approval, and a `do`/`sleep` step of the same name
+cannot collide.
+
+Because the reason IS the identity, it must be derived deterministically: the
+same replay must produce the same reason at the same point, or the run mints a
+new suspend instead of finding the one it is waiting on. This is the same
+contract as `do()` and `sleep()` step names.
+
+An approval additionally stores its record under a run-state key built by
+`approvalStateKey`, which hex-encodes the step name. The Mongo backend restricts
+state keys to `/^[a-zA-Z0-9_]+$/` while a reason is arbitrary human text, and
+one key per gate means two gates resolving concurrently cannot clobber each
+other through a read-modify-write.
+
+One consequence to know about: `approveStep`'s optional `reason` argument
+addresses the *first* reach of a gate only. If a gate is reached again on a
+later loop iteration, `nextStepKey` gives that row a `#N` suffix, and there is
+currently no way for a caller to name it.
+
+**What this rules out:** deriving a reason from a timestamp, a random id or
+anything else that varies between replays; sharing one namespace (or one
+run-state key) between suspends and approvals; and storing the reason raw as a
+run-state key, which breaks on any backend that constrains key characters.

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.