@pikku/core 0.12.80 → 0.12.83

package/dist/wirings/workflow/workflow-approval.d.ts

@@ -1,4 +1,5 @@
 import type { ApprovalOutcome, StepState, WorkflowApprovalOptions } from './workflow.types.js';
+import type { ApprovalDecider } from './dsl/workflow-dsl.types.js';
 /** The durable step name an approval point is recorded under. */
 export declare const approvalStepNameFor: (reason: string) => string;
 /**
@@ -9,6 +10,20 @@ export declare const approvalStepNameFor: (reason: string) => string;
  * shadow, another key.
  */
 export declare const approvalStateKey: (stepName: string) => string;
+/**
+ * An answer to an approval gate, as the audit trail sees it.
+ *
+ * `denied` covers both a submission refused at the door and a decision cleared
+ * on replay — from the trail's point of view they are the same event, someone
+ * tried to answer a gate they could not.
+ */
+export type ApprovalAuditEvent = {
+    runId: string;
+    reason: string;
+    outcome: 'success' | 'denied';
+    decidedBy?: ApprovalDecider;
+    refusal?: string;
+};
 /** What the approval gate needs from the workflow service. */
 export type ApprovalStore = {
     getStepState: (runId: string, stepName: string) => Promise<StepState>;
@@ -19,6 +34,8 @@ export type ApprovalStore = {
     updateRunState: (runId: string, key: string, value: unknown) => Promise<void>;
     resumeWorkflow: (runId: string) => Promise<void>;
     scheduleRunWake: (runId: string, delay: number) => Promise<void>;
+    getRunOwner: (runId: string) => Promise<string | undefined>;
+    auditApproval: (event: ApprovalAuditEvent) => Promise<void>;
 };
 /**
  * Record a decision against an approval point and wake the run.
@@ -26,8 +43,14 @@ export type ApprovalStore = {
  * A decision arriving for an already-settled approval is refused rather than
  * overwriting it: the run has moved on, and a second answer would be recorded
  * against a gate nobody is waiting at.
+ *
+ * The decider is recorded rather than judged here, for the same reason the
+ * payload is: the gate's policy is a value on the workflow, and a decision can
+ * legitimately arrive before the run has ever reached the gate. Where the run
+ * has already published its policy, it is applied eagerly so a caller who
+ * cannot answer is told so rather than left waiting.
  */
-export declare const recordApprovalDecision: (store: ApprovalStore, runId: string, reason: string, decision: unknown) => Promise<void>;
+export declare const recordApprovalDecision: (store: ApprovalStore, runId: string, reason: string, decision: unknown, decidedBy?: ApprovalDecider) => Promise<void>;
 /**
  * Evaluate an approval gate on replay.
  *
@@ -35,5 +58,10 @@ export declare const recordApprovalDecision: (store: ApprovalStore, runId: strin
  * schema is a value on the workflow and only the workflow has it. A payload
  * that fails validation is cleared and the run suspends again, so a bad
  * submission cannot settle the gate.
+ *
+ * The decider is judged here for the same reason, and for one more: a decision
+ * can be recorded before the run has ever reached the gate, so submission time
+ * is not a point at which the policy is reliably knowable. Judging on replay is
+ * what makes the policy hold in every ordering.
  */
 export declare const evaluateApprovalStep: (store: ApprovalStore, runId: string, reason: string, approvalStepName: string, fromStepName: string | undefined, options: WorkflowApprovalOptions) => Promise<ApprovalOutcome<unknown>>;

package/dist/wirings/workflow/workflow-approval.js

@@ -1,5 +1,6 @@
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { WorkflowApprovalResolvedError, WorkflowSuspendedException, } from './workflow-errors.js';
+import { approvalPolicyRefusal, WorkflowApprovalForbiddenError, } from './workflow-approval-policy.js';
 /** The durable step name an approval point is recorded under. */
 export const approvalStepNameFor = (reason) => `__workflow_approval:${reason}`;
 /**
@@ -22,8 +23,14 @@ export const approvalStateKey = (stepName) => {
  * A decision arriving for an already-settled approval is refused rather than
  * overwriting it: the run has moved on, and a second answer would be recorded
  * against a gate nobody is waiting at.
+ *
+ * The decider is recorded rather than judged here, for the same reason the
+ * payload is: the gate's policy is a value on the workflow, and a decision can
+ * legitimately arrive before the run has ever reached the gate. Where the run
+ * has already published its policy, it is applied eagerly so a caller who
+ * cannot answer is told so rather than left waiting.
  */
-export const recordApprovalDecision = async (store, runId, reason, decision) => {
+export const recordApprovalDecision = async (store, runId, reason, decision, decidedBy) => {
     const stepName = approvalStepNameFor(reason);
     const stateKey = approvalStateKey(stepName);
     let resolved;
@@ -39,12 +46,27 @@ export const recordApprovalDecision = async (store, runId, reason, decision) =>
     }
     const state = await store.getRunState(runId);
     const record = (state[stateKey] ?? {});
+    if (record.policy) {
+        const refusal = approvalPolicyRefusal(record.policy, await store.getRunOwner(runId), decidedBy);
+        if (refusal) {
+            await store.auditApproval({
+                runId,
+                reason,
+                outcome: 'denied',
+                decidedBy,
+                refusal,
+            });
+            throw new WorkflowApprovalForbiddenError(reason, refusal);
+        }
+    }
     await store.updateRunState(runId, stateKey, {
         ...record,
         decision,
         decidedAt: new Date().toISOString(),
+        decidedBy,
         error: undefined,
     });
+    await store.auditApproval({ runId, reason, outcome: 'success', decidedBy });
     await store.resumeWorkflow(runId);
 };
 /**
@@ -54,9 +76,19 @@ export const recordApprovalDecision = async (store, runId, reason, decision) =>
  * schema is a value on the workflow and only the workflow has it. A payload
  * that fails validation is cleared and the run suspends again, so a bad
  * submission cannot settle the gate.
+ *
+ * The decider is judged here for the same reason, and for one more: a decision
+ * can be recorded before the run has ever reached the gate, so submission time
+ * is not a point at which the policy is reliably knowable. Judging on replay is
+ * what makes the policy hold in every ordering.
  */
 export const evaluateApprovalStep = async (store, runId, reason, approvalStepName, fromStepName, options) => {
-    const insert = () => store.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', { reason, expiry: options.expiry }, undefined, fromStepName);
+    const insert = () => store.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', {
+        reason,
+        expiry: options.expiry,
+        approvers: options.approvers,
+        approverScope: options.approverScope,
+    }, undefined, fromStepName);
     let stepState;
     try {
         stepState = await store.getStepState(runId, approvalStepName);
@@ -72,8 +104,13 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
     }
     const stateKey = approvalStateKey(approvalStepName);
     let record = ((await store.getRunState(runId))[stateKey] ?? {});
+    const policy = {
+        approvers: options.approvers,
+        approverScope: options.approverScope,
+    };
     if (stepState.status === 'pending') {
         await store.setStepRunning(stepState.stepId);
+        record = { ...record, policy };
         if (options.expiry !== undefined && !record.expiresAt) {
             const expiry = getDurationInMilliseconds(options.expiry);
             record = {
@@ -83,14 +120,36 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
             await store.updateRunState(runId, stateKey, record);
             await store.scheduleRunWake(runId, expiry);
         }
+        else {
+            await store.updateRunState(runId, stateKey, record);
+        }
     }
     if (record.decision !== undefined) {
+        const refusal = approvalPolicyRefusal(policy, await store.getRunOwner(runId), record.decidedBy);
+        if (refusal) {
+            await store.updateRunState(runId, stateKey, {
+                ...record,
+                decision: undefined,
+                decidedAt: undefined,
+                decidedBy: undefined,
+                error: [{ message: refusal }],
+            });
+            await store.auditApproval({
+                runId,
+                reason,
+                outcome: 'denied',
+                decidedBy: record.decidedBy,
+                refusal,
+            });
+            throw new WorkflowSuspendedException(runId, reason);
+        }
         const validation = await options.schema['~standard'].validate(record.decision);
         if (validation.issues) {
             await store.updateRunState(runId, stateKey, {
                 ...record,
                 decision: undefined,
                 decidedAt: undefined,
+                decidedBy: undefined,
                 error: validation.issues.map((issue) => ({
                     message: issue.message,
                     path: issue.path?.map((segment) => typeof segment === 'object' ? segment.key : segment),
@@ -98,9 +157,13 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
             });
             throw new WorkflowSuspendedException(runId, reason);
         }
+        // Spread rather than assigned, so a gate answered without a session keeps
+        // the shape it had before there was anything to record.
         const outcome = {
             status: 'decided',
             data: validation.value,
+            ...(record.decidedBy ? { decidedBy: record.decidedBy } : {}),
+            ...(record.decidedAt ? { decidedAt: record.decidedAt } : {}),
         };
         await store.setStepResult(stepState.stepId, outcome);
         return outcome;

package/dist/wirings/workflow/workflow-run-ownership.d.ts

@@ -6,7 +6,8 @@ export declare class WorkflowRunForbiddenError extends ForbiddenError {
 }
 /**
  * A run started through a session records that session's user as its owner, and
- * only that user may read it or answer its approval gates.
+ * only that user may read it. Who may *answer* a run's approval gates is the
+ * gate's own declaration — see `approvers` on `workflow.approval()`.
  *
  * A run with no recorded owner — started by a trigger, a scheduler, or a route
  * wired without auth — has nobody to compare a caller against, so ownership is

package/dist/wirings/workflow/workflow-run-ownership.js

@@ -11,7 +11,8 @@ addError(WorkflowRunForbiddenError, {
 });
 /**
  * A run started through a session records that session's user as its owner, and
- * only that user may read it or answer its approval gates.
+ * only that user may read it. Who may *answer* a run's approval gates is the
+ * gate's own declaration — see `approvers` on `workflow.approval()`.
  *
  * A run with no recorded owner — started by a trigger, a scheduler, or a route
  * wired without auth — has nobody to compare a caller against, so ownership is

package/dist/wirings/workflow/workflow.types.d.ts

@@ -1,9 +1,8 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
-import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
-export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, PikkuBrowserWire, ScenarioBrowserProvider, } from './scenario-step.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -141,40 +140,6 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     middleware?: PikkuFunctionConfig['middleware'];
     tags?: string[];
 };
-export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
-    scenario: CorePikkuFunctionConfig<any, any, any>;
-    data: unknown;
-};
-export type CoreFeature = {
-    name: string;
-    description?: string;
-    tags?: string[];
-    scenarios: readonly CoreFeatureScenario[];
-    before?: CorePikkuFunctionHook;
-    after?: CorePikkuFunctionHook;
-};
-export type FeatureMetaEntry = {
-    scenario: string;
-    data?: unknown;
-};
-export type FeatureMeta = {
-    id: string;
-    name: string;
-    description?: string;
-    tags: string[];
-    entries: FeatureMetaEntry[];
-    unresolvedEntries: number;
-    hasBefore: boolean;
-    hasAfter: boolean;
-};
-export type FeaturesMeta = Record<string, FeatureMeta>;
-export type FeaturePlanEntry = {
-    featureId: string;
-    featureName: string;
-    scenarioName: string;
-    data?: unknown;
-    tags: string[];
-};
 export interface PikkuWorkflow {
     start: <I>(input: I) => Promise<{
         runId: string;

package/knowledge/decisions/internals/addon-pikku-meta-ships-at-the-package-root-or-under-dist.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: An addon's .pikku meta ships at the package root or under dist, and readers probe both
+description: 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
+tags: services
+---
+
+# An addon's .pikku meta ships at the package root or under dist, and readers probe both
+
+An addon generates `.pikku/` at its project root, and whether that directory
+reaches the published tarball at the root or inside `dist/` depends on the
+addon's own `tsconfig` and `files` — both layouts are in the wild and both are
+supported. The published `exports` map hides the difference for anyone
+resolving by specifier: `"./.pikku/*"` points at wherever it landed, so
+`require.resolve('<pkg>/.pikku/scopes/pikku-scopes-meta.gen.json')` works for
+either shape, and that is the resolution every consumer should prefer.
+
+Code that builds the path itself must probe both. `addonPikkuDir`
+(`packages/addon/pikku-console/src/lib/derive-instance-overrides.ts`) tries
+`<pkg>/.pikku` then `<pkg>/dist/.pikku` and returns `null` when neither exists.
+The reason to say so out loud is the failure mode: a reader that assumes the
+root finds nothing under a `dist`-shipping addon and cannot distinguish that
+from an addon that declares no secrets, variables or scopes at all. Both answers
+are "empty", and the wrong one is indistinguishable from a correct one until
+something downstream reports an addon as ready when its secrets were never
+checked.
+
+**What this rules out:** hardcoding either path in a consumer, and treating a
+missing directory as evidence an addon declares nothing without having tried
+both. It also rules out normalising the layout by making the CLI move the
+directory at publish time — the export map already makes the layout private to
+the package, and the addons shipping each shape are already published.

package/knowledge/decisions/internals/an-addon-scope-root-loses-to-a-root-the-host-already-declares.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: An addon's scope root loses to a root the host app already declares
+description: loadAddonFunctionsMeta merges addon scope trees by root name, first declaration wins, so an addon sharing a root with its host contributes nothing — silently
+tags: services
+---
+
+# An addon's scope root loses to a root the host app already declares
+
+`loadAddonFunctionsMeta`
+(`packages/inspector/src/utils/load-addon-functions-meta.ts`) reads each wired
+addon's `pikku-scopes-meta.gen.json` and pushes its entries into
+`state.scopes.definitions`, skipping any whose root name is already present. The
+host app's own declarations were inspected first, so the host always wins.
+
+The skip is per **root**, not per node. An addon declaring `admin.console.*` in
+an app that declares `admin` contributes none of it — not the root it shares,
+and not the branch the app never declared. Nothing errors: the scopes simply do
+not exist, so `ScopeId` never gains them, no role can be granted one, and every
+addon function requiring one denies everybody. The failure surfaces as a
+`MissingScopeError` against a scope that cannot be granted, which reads as a
+permissions bug rather than a merge that dropped.
+
+This is a different rule from
+[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): that one
+is about `flattenScopeDefinitions` deduping ids *within* a build where both
+declarations are present and identical. This one is about the addon's copy never
+arriving. The consequence for addon authors is the same either way — own a root
+outright, named for the package or vendor, and nest everything under it. It is
+why `@pikku/addon-console` declares `pikku:console:*` rather than
+`admin:console:*`.
+
+**What this rules out:** shipping an addon whose scopes hang off a root a host
+is likely to declare, and deep-merging the two trees here so both survive. A
+merge would have to reconcile conflicting descriptions and display names for the
+shared nodes, and would let an addon graft capabilities onto the host's `admin`
+tree — where a role granting `admin` would pick them up without anyone having
+asked for them.

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.