@pikku/core 0.12.80 → 0.12.82

package/knowledge/decisions/internals/index.md

@@ -22,6 +22,7 @@ caller is entitled to assume.
 - [The actor-flow conversation engine only sees a transport-agnostic target driver](actor-flow-drives-the-target-through-a-transport-seam.md) — The engine never imports the agent runner; the target is injected as run/approve, so scenarios exercise the real wire path
 - [An actor-flow verdict is the persona's self-evaluation, not an assertion](actor-flow-verdicts-are-llm-self-evaluations.md) — The engine returns what the actor judged plus the transcript; deterministic checks stay with the caller
 - [Addon package roots resolve by walking node module search paths](addon-package-roots-resolve-by-walking-node-module-search-paths.md) — LocalMetaService finds an addon's directory by scanning resolve.paths, not by require.resolve, because addon packages expose no main entry
+- [An addon's .pikku meta ships at the package root or under dist, and readers probe both](addon-pikku-meta-ships-at-the-package-root-or-under-dist.md) — The layout depends on the addon's build and files field, so a consumer resolving the directory by path must try `<pkg>/.pikku` and `<pkg>/dist/.pikku` before concluding an addon declares nothing
 - [Addon singleton services are cached per namespace, not per package](addon-singleton-services-are-cached-per-namespace-not-per-package.md) — Each wireAddon instance gets its own services built from its own overrides, at the cost of one service graph per wired instance
 - [Bare workflow names from inside an addon are prefixed with the consumer's namespace](addon-workflow-names-are-prefixed-with-the-consumer-namespace.md) — The addon's workflowService is proxied so an addon never has to hardcode the name its consumer chose
 - [Loading agent context waits for a tool result that may still be landing](agent-context-waits-for-a-tool-result-still-being-written.md) — An interrupted run's tool can still be writing to the thread, and in voice the next turn arrives within seconds — soon enough to load context missing what it is about to be asked about
@@ -39,6 +40,7 @@ caller is entitled to assume.
 - [A tool's execute() failure is logged before the AI SDK swallows it](ai-agent-tool-execute-failures-are-logged-unconditionally.md) — Every agent tool is wrapped in a logging try/catch, because a thrown tool error otherwise becomes a conversational reply and is invisible server-side
 - [Voice input transcribes audio parts sequentially and in place](ai-agent-voice-input-transcribes-audio-parts-in-place.md) — Each audio part is replaced by its text where it sat, one at a time, bounding concurrent downloads and preserving content order
 - [Working memory is persisted only when the merged value validates](ai-agent-working-memory-is-persisted-only-when-valid.md) — A failed schema check logs and drops the update rather than saving it, because invalid state poisons every later read
+- [An addon's scope root loses to a root the host app already declares](an-addon-scope-root-loses-to-a-root-the-host-already-declares.md) — loadAddonFunctionsMeta merges addon scope trees by root name, first declaration wins, so an addon sharing a root with its host contributes nothing — silently
 - [An interrupt is not a failure, and the non-streaming path throws rather than returning](an-agent-interrupt-is-not-a-failure.md) — It skips the onError hooks and never becomes an errorMessage; with no partial reply to hand back, a typed throw is what distinguishes it from a provider outage
 - [An interrupt for a run owned by another instance says so, rather than returning false](an-agent-run-owned-by-another-instance-says-so.md) — A bare false is indistinguishable from "already finished", which is the one deployment shape the in-process registry cannot cover
 - [A wrapped agent-stream send must return the inner send's promise](an-agent-stream-send-must-return-the-inner-sends-promise.md) — Middleware runs asynchronously, so dropping the returned promise turns every awaited channel.send upstream into a no-op
@@ -54,11 +56,15 @@ caller is entitled to assume.
 - [CLI parse errors are routed by message prefix](cli-parse-errors-are-routed-by-message-prefix.md) — The CLI runners decide between printing help and printing errors by string-matching the prefixes the parser writes, so those message strings are an interface
 - [CLI stdout is reserved for machine-readable output](cli-stdout-is-reserved-for-machine-readable-output.md) — The default renderer emits single-line NDJSON, diagnostics go to stderr, and --json only hijacks rendering for commands that declared a renderer
 - [CLI unknown long options warn instead of failing](cli-unknown-long-options-warn-instead-of-failing.md) — Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
+- [A column's at-rest form is an axis of its own](core-column-form-is-an-axis-of-its-own.md) — How a value is stored is independent of how sensitive it is, so form carries a required nominal brand on writes while classification stays optional on reads
+- [The data-classification brand is an optional property](core-data-classification-brand-is-an-optional-property.md) — Making __classification__ required would break ordinary Kysely operands, so the brand only constrains values flowing out
 - [The function runner restores the wire fields it overwrites](core-function-runner-restores-the-wire-fields-it-overwrites.md) — One wire object is reused across nested calls, so functionId, audit, addonNamespace and rpc are saved and put back in a finally
 - [Hot reload merges generated meta and never replaces it](core-hot-reload-merges-generated-meta-never-replaces-it.md) — Reloading codegen output must preserve runtime-registered meta, which no generated JSON contains
 - [Hot reload owns its module registry instead of re-importing](core-hot-reload-owns-its-module-registry.md) — Dev reload transpiles to CJS and runs modules through vm.compileFunction, because the native ESM loader map cannot be evicted
 - [Middleware order is resolution scope first, then priority](core-middleware-order-is-scope-then-priority.md) — Middleware is collected global to function, then stably sorted by priority, deduped, frozen and cached per wire
+- [Schema defaults are applied on every transport, not just HTTP](core-schema-defaults-apply-on-every-transport.md) — Defaults belong to the schema rather than the call's encoding, so they run unconditionally and are cloned per request
 - [Scopes are an AND gate, separate from permissions](core-scopes-are-an-and-gate-separate-from-permissions.md) — Every declared scope must be held, so adding one can only narrow access — permissions OR, and can only widen it
+- [Pikku state is a global map written only at registration time](core-state-is-a-global-map-written-only-at-registration-time.md) — A symbol-keyed globalThis map holds the wiring registry; nothing per-request may ever be written to it
 - [Email meta is read uncached because codegen rewrites it mid-session](email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md) — getEmailMeta re-reads its file on every call, unlike every other meta accessor, because the file appears and changes during a long-lived session
 - [Gateway adapters resolve lazily and are promise-cached](gateway-adapters-resolve-lazily-and-are-promise-cached.md) — wireGateway accepts an adapter factory because real adapters need boot-time secrets, which forces the webhook GET route to be registered unconditionally
 - [Gateway middleware sees wire.rpc on webhook and websocket, but not on listener](gateway-listener-middleware-runs-without-an-rpc-on-the-wire.md) — The listener transport invokes its handler directly, so middleware runs outside any runPikkuFunc call and the lazily-attached rpc is absent
@@ -68,22 +74,27 @@ caller is entitled to assume.
 - [Hot reload writes into the function map captured at startup, not pikkuState's current one](hot-reload-writes-into-the-function-map-captured-at-startup.md) — A dev-server watcher may have swapped in a codegen-scoped map whose writes are discarded on restore, and schemas are deliberately left alone
 - [HTTP request bodies are read once and shared between consumers](http-request-bodies-are-read-once-and-shared.md) — The fetch request wrapper memoises the single-use body and builds web Requests lazily, at the cost of holding the whole body in memory
 - [HTTP route groups cascade config in a fixed, per-field order](http-route-groups-cascade-config-in-a-fixed-order.md) — basePath concatenates, tags and middleware merge outward-in, auth is overridden by the innermost group
+- [The HTTP router matches normalized paths but returns the registered path](http-router-matches-normalized-paths-but-returns-registered-ones.md) — Matching normalizes the leading slash while the match result carries the original key, because pikkuState is keyed by the registered string
+- [The HTTP runner logs through a trace-scoped logger, functions do not](http-runner-logs-through-a-trace-scoped-logger-functions-do-not.md) — Only runner-internal logging is scoped to the request id; functions keep the singleton logger for compatibility
+- [Set-Cookie headers are appended individually, never joined](http-set-cookie-headers-are-appended-never-joined.md) — Every cookie gets its own header line, because Set-Cookie is the one header comma-joining corrupts
+- [HTTP SSE streams flush headers only after middleware has run](http-sse-streams-flush-headers-only-after-middleware.md) — SSE responses defer the header flush and register with the eventHub, at the cost of a stricter ordering the runner must preserve
 - [HTTP wiring without generated metadata is skipped, not fatal](http-wiring-without-metadata-is-skipped-not-fatal.md) — wireHTTP warns and returns when a route has no metadata, so partial deploy units still boot
 - [In a scenario a 4xx is data, not an exception](in-a-scenario-a-4xx-is-data-not-an-exception.md) — postScenarioJson and invokeRaw report the status instead of throwing, because a refusal is the expected outcome of a permissions scenario
 - [In-memory workflow history aliases the live step object](in-memory-workflow-history-aliases-the-live-step-object.md) — stepHistory pushes the same StepState reference that steps holds, so later mutations to a step are visible in its history entry
 - [Istanbul statement counts attach to the start line only](istanbul-statement-counts-attach-to-the-start-line-only.md) — The istanbul coverage reader credits a statement's hits to its first line, so an enclosing multi-line statement cannot mask an unexecuted inner one
 - [Local trigger and gateway services assume a single process](local-trigger-and-gateway-services-assume-a-single-process.md) — InMemoryTriggerService and LocalGatewayService start every listener unconditionally with no distributed claiming, so a second instance duplicates every event
 - [Node-only builtins are imported dynamically](node-only-builtins-are-imported-dynamically.md) — V8CoverageService imports node:inspector inside start() so the module stays loadable on runtimes that have no such builtin
-- [One project-shape check, called by both validators](one-project-shape-check-two-validators.md) — workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts
+- [One project-shape check, called by both validators](one-project-shape-check-two-validators.md) — workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and fabric validate is that plus the deploy-shaped checks
 - [Only functions marked `expose: true` enter a virtual user's catalogue](only-exposed-functions-enter-a-virtual-user-catalogue.md) — Absent is not permissive — an unexposed function 404s over rpc, so offering one spends a step to learn nothing about the product
 - [Queue group concurrency keeps one shared queue fair](queue-group-concurrency-keeps-one-shared-queue-fair.md) — Per-group slot caps let many producers share a single queue instead of one queue each, at the cost of a cap that must stay under batchSize
 - [Queue jobs always carry an explicit attempts count](queue-jobs-always-carry-an-explicit-attempts-count.md) — resolveJobOptions always passes attempts so a queue backend can never apply its own retry default, and an explicit retries of 0 is honoured
 - [Remote addons dispatch over HTTP instead of through local function meta](remote-addons-dispatch-over-http-instead-of-local-meta.md) — wireRemoteAddon ships the addon as a devDependency and posts to the host, so there is deliberately no local handler to resolve
+- [Bare RPC names resolve through the caller's package scope before root](rpc-names-resolve-through-package-scope-before-root.md) — An addon's own functions win over root RPC meta for bare names, and the resolving scope is returned so it can be threaded into runPikkuFunc
 - [Scenario agent calls sign in on 401 only](scenario-agent-calls-sign-in-on-401-only.md) — postAgent sends the first request with whatever session it holds and logs in only if refused, so an actor can converse with a no-auth agent with no sign-in wiring
 - [`given` and `when` are sugar for each other; `then` is not](scenario-given-and-when-are-sugar-but-then-is-not.md) — The phase decides whether a step's bindings are alternatives or witnesses, so the same step function called as `when` and as `then` runs differently
 - [Scenario meta lives apart from app meta but merges when read off disk](scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md) — Scenarios generate into .pikku/scenarios so no app module imports them, yet MetaService folds them back into the workflow and function meta
 - [Scenario steps return drained response records](scenario-steps-return-drained-response-records.md) — A scenario step hands back ScenarioHttpResponse rather than a Response, because the body stream reads once and the return value crosses into the run record
-- [Scenarios, steps and personas live in files named for them](scenarios-live-in-files-named-for-them.md) — pikkuScenario/pikkuScenarioStep must be in *.scenario.ts/*.steps.ts and definePersonas in *.virtual-user.ts, an error because the mixing is only cheap to undo while it is one file
+- [Scenarios, steps and personas live in files named for them, and validate errors when they do not](scenarios-live-in-files-named-for-them.md) — pikkuScenario/pikkuFeature/pikkuScenarioStep must be in *.scenario.ts, *.scenarios.ts or *.steps.ts, and definePersonas/runVirtualUser in *.virtual-user.ts or *.vu.ts — an error, because the mixing is only cheap to undo while it is one file
 - [Scope roots may be co-declared by an addon and its host app](scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md) — flattenScopeDefinitions dedupes ids because the same root can legitimately be declared twice, and every consumer requires one entry per scope
 - [Serverless channel disconnect must tolerate a missing channel](serverless-channel-disconnect-must-tolerate-a-missing-channel.md) — A failed channel lookup on disconnect returns quietly, because serverless runtimes deliver disconnect more than once
 - [sideEffects is an allowlist, because core genuinely has some](side-effects-are-an-allowlist-not-a-boolean.md) — The error registry is built by addError calls that run on import, so claiming sideEffects:false would let a bundler drop it and leave getErrorResponse unable to find any error
@@ -106,7 +117,8 @@ caller is entitled to assume.
 - [Thread history records what the model was asked, which for a spoken turn is the transcript](thread-history-records-the-transcript-not-the-audio.md) — The wire carried a base64 audio blob; persisting it writes megabytes of unreadable data and loses the only readable record of the turn
 - [Trigger declaration is split from trigger source](trigger-declaration-is-split-from-trigger-source.md) — Triggers are declared everywhere but subscribed only in the trigger worker, so app processes never open the underlying subscription
 - [TypedSecretService caches for the process lifetime](typed-secret-service-caches-for-the-process-lifetime.md) — Resolved secrets are cached with no TTL, so a secret rotated out of band is not picked up until restart — tracked as pikkujs/pikku#964
-- [Both validators check personas through one shared module, and a persona counts from either the meta or the source](validate-checks-personas-through-a-shared-module.md) — workspace validate and fabric validate are separate implementations, so the persona/actor/knowledge checks live in persona-checks.ts and are called by both
+- [Both validators check personas through one shared module, and a persona counts from either the meta or the source](validate-checks-personas-through-a-shared-module.md) — workspace validate and fabric validate are separate implementations, so the persona/actor/knowledge checks live in persona-checks.ts and are called by both — and a persona is counted from the generated meta or a definePersonas() source scan, whichever answers first
+- [pikku validate runs every applicable check, it does not detect a project kind](validate-runs-checks-by-precondition.md) — one `pikku validate` replaces `pikku workspace validate`; checks declare a precondition and run wherever it holds, because the repos that matter are an app and a pile of addons at the same time
 - [A scenario's step order for a virtual user is insertion order, not a graph traversal](virtual-user-step-order-comes-from-insertion-order.md) — 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
 - [Only an explicit `false` silences a spoken reply](voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md) — 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
 - [Webhook delivery history records every attempt, best effort](webhook-delivery-history-records-every-attempt-best-effort.md) — The webhook worker persists each attempt before it throws, and a failure to persist is logged rather than allowed to mask the delivery result
@@ -116,14 +128,29 @@ caller is entitled to assume.
 - [Workflow approval expiry is decided from a recorded deadline, not from a timer firing](workflow-approval-expiry-is-decided-from-a-recorded-deadline.md) — The wake-up job is best-effort liveness; losing, duplicating or delaying it cannot change the gate's answer
 - [Core declares the scenario browser surface structurally and never imports a driver](workflow-core-never-imports-a-browser-driver.md) — `@pikku/core` must stay dependency-free for edge runtimes, so playwright augments the interface instead of being imported by it
 - [Workflow DSL meta keeps runtime expressions in their own field, apart from literal values](workflow-dsl-meta-separates-runtime-expressions-from-literals.md) — A string `value` regenerates as a string literal; an `expression` regenerates as code, so the two can never share a field
+- [A feature resolves its scenarios by object identity, never by name or shape](workflow-features-resolve-scenarios-by-object-identity.md) — An unregistered scenario comes back explicitly unresolved rather than silently running as something else
 - [Inline and queued workflow graph runs share one transition planner](workflow-graph-inline-and-queued-runs-share-one-planner.md) — A second, weaker inline traversal would lose joins, cycle revisits and step provenance that the queued path has
 - [Workflow graph node notes are non-semantic and excluded from the graph hash](workflow-graph-node-notes-are-excluded-from-the-graph-hash.md) — Documentation on a node must not count as a topology change, or editing a comment redeploys the workflow
+- [An inline workflow run reports its run id the moment it exists, because a failure throws instead of returning](workflow-inline-runs-report-their-run-id-before-they-can-fail.md) — `onRunCreated` is the only moment guaranteed to happen whether the run passes, fails or suspends
 - [`invocationId` is a workflow step's dedupe key; `stepId` is store-specific and must never be used as one](workflow-invocation-id-is-the-dedupe-key-not-step-id.md) — The invocation id is a frozen UUIDv5 of runId + stepName, identical across retries on every backend
+- [A workflow step goes through the queue only if its function opts in, and there is no inline fallback](workflow-queued-step-dispatch-requires-an-explicit-opt-in.md) — `workflowQueued: true` is the whole decision; a missing queue service is a hard error, not a silent downgrade
 - [Workflows get their own queues by default, and queue names are resolved from queue meta](workflow-queues-are-per-workflow-by-default.md) — Per-workflow queues stop one slow step head-of-line-blocking every other workflow; `shared-groups` trades that for one set of pollers
+- [A workflow step name repeated in one run gets an ordinal suffix, and the first reach stays bare](workflow-repeated-step-names-get-an-ordinal-suffix.md) — `name`, `name#1`, `name#2` keys each reach separately without changing the durable key of any existing run
+- [A workflow replay reads its steps once and caches only the run's immutable half](workflow-replay-reads-its-steps-once-and-caches-only-the-immutable-half.md) — The per-replay snapshot collapses O(N^2) step reads to one, but caching mutable run fields would make the replay read a lie
 - [Workflow step retries are owned by the workflow, never by the queue](workflow-retries-are-owned-by-the-workflow-not-the-queue.md) — A step's retry count is resolved once and always passed to the queue as `attempts`, so the queue can never apply its own default
 - [Workflow run capabilities are extensions, not subclasses](workflow-run-capabilities-are-extensions-not-subclasses.md) — Scenario support lives in a separate module behind `setRunExtension` because a bundler drops an unused module but never an unused class member
+- [The workflow run mirror is an observability sink, never a second source of truth](workflow-run-mirror-is-never-a-source-of-truth.md) — Every mirrored write happens after the authoritative write lands, and a mirror failure can never fail the workflow
 - [Workflow run polling starts short and backs off to the caller's ceiling](workflow-run-polling-backs-off-to-the-callers-ceiling.md) — `pollIntervalMs` is a ceiling, not a cadence, and the wait lives in its own method so the schedule can be asserted without the clock
+- [The workflow run timeline is a pure fold over durable history, with the row's status as the authority](workflow-run-timeline-is-a-pure-fold-over-durable-history.md) — No IO in the fold keeps time-travel transport-independent; the terminal event comes from `status`, not from a timestamp every backend populates
 - [Scenario steps default to no retries, and a whole poll is one durable step](workflow-scenario-assertions-never-retry-and-record-one-step.md) — Retrying a failed assertion is wrong for a test primitive; recording the poll as one step means replay returns the outcome, not the loop
+- [Scenario lifecycle hooks are a scenario-only affordance and never mask the failure they follow](workflow-scenario-hooks-are-a-scenario-only-affordance.md) — A durable workflow replays, so a callback that reruns each replay has no honest meaning there
 - [Scenario prose is rendered out of typed calls, not parsed into them](workflow-scenario-prose-is-rendered-from-typed-calls-not-parsed-from-english.md) — The inversion of cucumber — a readable report with no regex step registry to maintain
+- [A quarantined scenario states its reason in code, not in a CI invocation](workflow-scenario-quarantine-reason-lives-in-code.md) — `skip` carries the why next to the scenario it applies to, and naming the scenario explicitly still runs it
 - [Scenario step targets are string literals so the inspector can read them statically](workflow-scenario-step-targets-are-string-literals-for-the-inspector.md) — `step/given/when/then` mirror `do`'s RPC shape because the extractor reads a literal, not an imported symbol
+- [A step's compensation handler runs as a durable step of its own, and never compensates itself](workflow-step-compensation-runs-as-its-own-durable-step.md) — A refund or rollback must not fire twice on replay, so `onError` is recorded as `<step>:onError` with retries disabled
+- [A failed workflow step dispatch is transient infrastructure, not a run failure](workflow-step-dispatch-failure-is-transient-not-a-run-failure.md) — Queue-unreachable errors leave the run running and the step pending so the orchestrator replays; marking the run failed loses it
+- [A workflow step lock is held only to claim the step, never across its execution](workflow-step-lock-is-held-only-to-claim-the-step.md) — Holding the advisory lock — and its pooled connection — across step work exhausted the connection pool and self-deadlocked
+- [A workflow step's recorded `rpcName` is provenance only — nothing dispatches off it](workflow-step-rpc-name-is-provenance-only.md) — 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
+- [A suspend or approval `reason` is the step's durable identity, not just a message](workflow-suspend-and-approval-reasons-are-durable-step-identities.md) — The reason is namespaced and used raw as the step key, so it must be derived deterministically across replays
+- [A suspended workflow run keeps its in-process context; only terminal runs release it](workflow-suspended-runs-keep-their-in-process-context.md) — `suspended` is absent from the terminal set on purpose, and a context is dropped only when nothing is holding it open
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/internals/validate-runs-checks-by-precondition.md

@@ -0,0 +1,115 @@
+---
+type: decision
+title: pikku validate runs every applicable check, it does not detect a project kind
+description: one `pikku validate` replaces `pikku workspace validate`; checks declare a precondition and run wherever it holds, because the repos that matter are an app and a pile of addons at the same time
+tags: cli, validate, addons
+---
+
+# pikku validate runs every applicable check, it does not detect a project kind
+
+`pikku workspace validate` was named after one of the things a repo can be.
+Adding a second — "is this addon publishable" — invited a second command,
+`pikku addon validate`, and that is where the naming falls apart: the addons
+repo is a workspace *containing* 217 publishable addons. Standing at its root,
+`pikku addon validate` would have to refuse or sweep every package, at which
+point it is doing the workspace thing anyway. The two nouns were never
+alternatives.
+
+So there is one command, and it does not detect a kind and dispatch. Each check
+declares the condition under which it means anything, and runs wherever that
+condition holds:
+
+- `app-project` — a `pikku.config.json` with no `types/application-types.d.ts`
+  beside it. The marker matters: an addon carries a `pikku.config.json` too, and
+  the app-shaped checks would report every app convention it has no reason to
+  follow, starting with a `packages/functions/` it will never have.
+- `addon-package` — a non-private package that ships generated pikku output.
+  Having a `.pikku` directory is not enough on its own: an app's
+  `packages/functions` has one, and it is codegen for that app rather than
+  something anyone installs. The signal is a `files`/`exports` that carries it
+  into the tarball.
+
+Detection-as-dispatch fails on the first repo that is two things at once.
+Detection-as-precondition composes: the addons repo plans 217 addon checks and
+no app check; the online-shop template plans one app check and no addon check;
+a repo that is both plans both.
+
+## Targets come from walking, not from `workspaces`
+
+The field is an array in one repo and `{ packages: [...] }` in the next, spells
+the same layout as `packages/**` or as six explicit globs, and a package that is
+real but unlisted is exactly the kind of thing worth validating. So discovery
+walks the tree for `package.json` files and lets the preconditions decide.
+Over-collecting targets is free; guessing the glob dialect is not.
+
+## A run that checked nothing must not print a tick
+
+The failure mode of auto-detection is that finding nothing looks exactly like
+finding everything and liking it. When no check applies, the renderer says so
+and names what it looked for, rather than reporting success.
+
+## The check the addon case exists for
+
+Every relative import in a shipped generated file must resolve to a file that is
+itself shipped — stated as a property, not as "the build script must copy
+`types/`". The build script is not the only way to get this wrong and will not
+always be a `cp`; the generated files already declare what they need.
+
+That property was false in all 217 published addons. `cp -r .pikku dist/`
+shipped the generated output but not the `types/application-types.d.ts` it
+imports, and `tsc` never emits a hand-written `.d.ts` to `outDir`, so nothing
+put it in `dist`. Consumers got 8 unresolved-module errors plus 6
+`RequiredServices does not satisfy CoreSecretlessSingletonServices` follow-ons
+inside `node_modules`, for merely depending on an addon. The scaffold template
+had been right the whole time — `templates/function-addon` copies `types/` —
+and the published packages had drifted from it with nothing watching.
+
+## The check walks whichever generated directory a package ships
+
+`dist/.pikku` is the target shape (below), but the check cannot assume it: the
+shape is what this work moved addons *to*, and a package that has not moved —
+or was published before it did — still carries `.pikku` at the root, listed in
+`files` and mapped by `exports` as `./.pikku/*`. There it is a public entry
+point rather than build input, and its imports climb one level fewer — to
+`<pkg>/src` and `<pkg>/types` — where the copy under `dist` reaches
+`<pkg>/dist/src` and `<pkg>/dist/types`. Two roots, two ways to fall outside
+the tarball, so the check walks whichever ones are actually shipped rather than
+the one it would prefer to find.
+
+`exports` and `imports` get the same treatment one level up: a target outside
+the published file set is the same defect, and the one the import walk cannot
+see, because nothing inside `dist/.pikku` mentions it. That is how a `#pikku`
+still pointing at `./.pikku/pikku-types.gen.ts` hides.
+
+## An addon's entry points all resolve under dist
+
+Everything an installed package reaches for lives under `dist`; the addon's own
+build resolves `#pikku` through tsconfig `paths`, so nothing in `exports` or
+`imports` has to point into the source tree, and `files` is just `["dist"]`.
+The alternative — shipping `src/` and `types/` at the root so the existing paths
+resolve as written — publishes TypeScript source and a second copy of
+everything `dist` already has.
+
+Checking only `dist` is what let the root `.pikku` stay broken through the first
+round of fixes: in the published `@pikku/addon-assemblyai@0.1.4` tarball, `.pikku`
+ships `.gen.ts` files importing a `../../src/` and `../types/` that the tarball
+does not contain, and the `pikku-bootstrap.gen.js` that consumers import through
+that subpath exists only under `dist`. Everything resolved locally through the
+workspace link and none of it resolved on install.
+
+## Only a package that publishes gets the dist shape
+
+The shape describes a tarball, so it means nothing for a `private` package —
+and applying it there actively breaks: `exports` *is* enforced across a
+workspace link, so repointing a private fixture at `dist` makes every consumer
+demand a directory that only a build produces. The three `verifiers/db-schema`
+and `verifiers/addon-registry` fixtures have no build script at all, so `dist`
+never exists for them; the five `e2e/packages` addons build, but their metadata
+is read straight from the source tree before any build has run. Repointing all
+eight left the db-schema verifier unable to resolve
+`dist/.pikku/db/pikku-db-meta.gen.json` and every e2e addon reporting "no
+function metadata".
+
+`isAddonPackage` already draws this line — it returns false for `private` — so
+the checks and the shape agree: a package the registry never sees is consumed
+from source.

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

@@ -0,0 +1,37 @@
+---
+type: decision
+title: A function never receives the secret service
+description: Every function-, permission- and auth-facing services type is bounded by SecretlessServices, so reaching for `secrets` in a function body is a type error rather than a lint
+tags: services
+---
+
+# A function never receives the secret service
+
+`SecretlessServices<Services>` is `Omit<Services, 'secrets'>`
+(`packages/core/src/types/core.types.ts`), and
+`CoreSecretlessSingletonServices` built from it is the constraint every
+function-, permission- and auth-facing type is bounded by
+(`packages/core/src/function/functions.types.ts`). Destructuring `secrets`
+inside a `pikkuFunc` body does not lint — it does not compile.
+
+The rule itself is older than the type: a function holding a `SecretService` can
+read every secret in the vault, which makes its blast radius the whole vault
+rather than the one credential it needs, and makes "which secrets does this
+function depend on?" unanswerable. `[PKU950]` enforces the same confinement for
+a `SecretService` reaching a function under an alias, because a rename does not
+change what it is. Encoding it in the type is what makes the honest mistake
+impossible rather than merely reported: secrets are resolved where things are
+constructed — `pikkuServices`, `pikkuWireServices`, addon service factories,
+middleware — and the function is handed the configured client.
+
+The cost is that a function which needs to *ask about* a secret rather than read
+one — "is this key set?", for a readiness or provisioning check — cannot do it
+directly either. It goes through a service that holds `secrets` and exposes only
+that question, which is how `@pikku/addon-console` checks whether an installed
+addon's declared secrets are present.
+
+**What this rules out:** widening a function's services type back to
+`CoreServices` for a function that "only needs one secret", and passing the
+secret service through under another name — the type follows the shape and
+`[PKU950]` follows the type. It also rules out treating the absence as an
+oversight to be patched with a cast.

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

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

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

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

package/knowledge/decisions/security/index.md

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

package/knowledge/questions/index.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.80",
+  "version": "0.12.82",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -22,6 +22,7 @@
     "./dist/errors/errors.js",
     "./dist/wirings/rpc/rpc-runner.js",
     "./dist/wirings/rpc/remote-addon-auth.js",
+    "./dist/wirings/workflow/workflow-approval-policy.js",
     "./dist/wirings/workflow/workflow-errors.js",
     "./dist/wirings/workflow/workflow-run-ownership.js",
     "./dist/wirings/workflow/pikku-scenario-service.js"
@@ -49,6 +50,7 @@
     "./node-host-resolver": "./dist/utils/node-host-resolver.js",
     "./mcp": "./dist/wirings/mcp/index.js",
     "./ai-agent": "./dist/wirings/ai-agent/index.js",
+    "./ai-scorer": "./dist/wirings/ai-scorer/index.js",
     "./gateway": "./dist/wirings/gateway/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/command-parser": "./dist/wirings/cli/command-parser.js",