@pikku/core 0.12.74 → 0.12.78

package/dist/wirings/virtual-user/virtual-user-run-store.d.ts

@@ -0,0 +1,90 @@
+import type { VirtualUserDisposition, VirtualUserFinding, VirtualUserTally } from './virtual-user.types.js';
+/**
+ * One recorded run: who ran, what they were told, and what came back.
+ *
+ * A run is dispatched and answered for later, so the record is created before
+ * the work starts and is the thing the returned `runId` addresses.
+ *
+ * This record is a run's ONLY trace. A virtual user is not a workflow — it
+ * explores, so no two attempts take the same steps and there is nothing to
+ * replay — and it is not queued either, because the record already carries the
+ * progress a queue would only be holding on the way here.
+ *
+ * The cost of that is the one thing to know when reading `status`: a restart
+ * mid-run leaves a record at `running` with nothing left to finish it. A run
+ * older than its budget window and still `running` is dead, not working.
+ */
+export interface VirtualUserRunRecord {
+    runId: string;
+    persona: string;
+    disposition: VirtualUserDisposition;
+    /** What makes a run replayable at all — a finding without it is an anecdote. */
+    seed: number;
+    /**
+     * `running` until the engine returns. Not derived from `finishedAt` being
+     * unset: a crashed run has no finish time either, and the two are not the
+     * same result.
+     */
+    status: 'running' | 'completed' | 'failed';
+    /** The caller's situational goals, run alongside the derived intents. */
+    goals: string[];
+    /**
+     * Ids and slugs the user carried in, and whatever it learned on the way out.
+     * Kept because a finding only reproduces alongside the notes that produced it.
+     */
+    memory: Record<string, string>;
+    findings: VirtualUserFinding[];
+    tally: VirtualUserTally | null;
+    /** Which budget or stopping rule ended the run. */
+    stoppedBy: string | null;
+    /**
+     * Why the run itself failed, as opposed to what it found. A run that could
+     * not start has no findings and is not a clean empty result.
+     */
+    error: string | null;
+    /** The session that started it, where the host tracks one. */
+    startedBy: string | null;
+    createdAt: Date;
+    finishedAt: Date | null;
+}
+/** What a run is created with — everything else is filled in by the outcome. */
+export interface VirtualUserRunStart {
+    persona: string;
+    disposition: VirtualUserDisposition;
+    seed: number;
+    goals?: readonly string[];
+    memory?: Record<string, string>;
+    startedBy?: string | null;
+}
+/** The outcome of a run that reached the end of its budget without throwing. */
+export interface VirtualUserRunOutcome {
+    findings: readonly VirtualUserFinding[];
+    tally: VirtualUserTally;
+    memory: Record<string, string>;
+    stoppedBy: string | null;
+}
+/**
+ * Where runs are kept. Declared here rather than in a database package so the
+ * scaffolded RPCs depend on the shape and not on kysely — `@pikku/kysely` ships
+ * one implementation, and an app with its own store satisfies this instead.
+ *
+ * SECURITY: findings from an `adversarial` run are working exploits carrying
+ * live ids. An implementation is a privileged store; the scaffold gates every
+ * read behind a scope for that reason, and a host exposing these records more
+ * widely is publishing its own exploits.
+ */
+export interface VirtualUserRunStore {
+    /** Records a run as `running` and returns its id. */
+    start(run: VirtualUserRunStart): Promise<string>;
+    /** Marks a run `completed` and stores what it found. */
+    complete(runId: string, outcome: VirtualUserRunOutcome): Promise<void>;
+    /** Marks a run `failed`. The run itself broke; it has no findings. */
+    fail(runId: string, error: string): Promise<void>;
+    get(runId: string): Promise<VirtualUserRunRecord | null>;
+    /** Newest first. `persona` narrows to one persona's history. */
+    list(options?: {
+        persona?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<VirtualUserRunRecord[]>;
+}

package/dist/wirings/virtual-user/virtual-user-run-store.js

@@ -0,0 +1 @@
+export {};

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

@@ -62,7 +62,7 @@ export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(stepName: string,
  */
 export type WorkflowWireDoInline = <T>(stepName: string, fn: () => Promise<T> | T, options?: WorkflowStepOptions) => Promise<T>;
 /**
- * Type signature for scenario.step/given/when/then - used by inspector.
+ * Type signature for scenario.given/when/then - used by inspector.
  *
  * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
  * an imported symbol, so the extractor reads it as a literal.
@@ -181,7 +181,7 @@ export interface RpcStepMeta {
     expectEventually?: boolean;
 }
 /**
- * Scenario step metadata — a call to `scenario.step/given/when/then`.
+ * Scenario step metadata — a call to `scenario.given/when/then`.
  *
  * Distinct from RpcStepMeta on purpose: a step runs locally through
  * runPikkuFunc and must never be treated as dispatchable on the queue/replay
@@ -194,7 +194,7 @@ export interface ScenarioStepMeta {
     stepName: string;
     /** Registered name of the step function being run */
     stepFunc: string;
-    /** Which keyword the reporter prefixes — given/when/then, or none for `step` */
+    /** Which keyword the reporter prefixes — Given, When or Then */
     phase: ScenarioStepPhase;
     /** Output variable name (if assigned) */
     outputVar?: string;
@@ -484,18 +484,22 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     /** Stub-assertion step: asserts `service.method` was called on the target server */
     expectService: (stepName: string, serviceMethod: string, options?: WorkflowExpectServiceOptions) => Promise<void>;
     /**
-     * Run a registered scenario step. Shaped exactly like `do`'s RPC form —
-     * `(stepName, target, data, options)` — so the inspector reads the target as
-     * a string literal rather than resolving an imported symbol.
+     * Run a registered scenario step, as the setup the scenario starts from.
+     *
+     * Shaped exactly like `do`'s RPC form — `(stepName, target, data, options)` —
+     * so the inspector reads the target as a string literal rather than resolving
+     * an imported symbol.
      *
      * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
      */
-    step(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "Given" prefix in the rendered prose */
     given(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "When" prefix in the rendered prose */
+    /** `when`: the same call as `given`, rendered as the action under test */
     when(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
-    /** `step` with a "Then" prefix in the rendered prose */
+    /**
+     * `then`: a claim about what the action left behind. Unlike `given`/`when`
+     * this is not prose alone — the step's bindings become witnesses, so every
+     * declared surface is observed and the observations must agree.
+     */
     then(stepName: string, stepFunc: string, data?: any, options?: ScenarioStepOptions): Promise<any>;
     runScheduledTask: (name: string) => Promise<unknown>;
 }

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -452,12 +452,11 @@ export class PikkuScenarioService {
                 }, options);
             },
             // Scenario steps: a named `pikkuScenarioStep` run as one durable step.
-            // `given`/`when`/`step` are sugar for each other, differing only in the
+            // `given`/`when` are sugar for each other, differing only in the
             // prose a reporter renders. `then` is not: the phase is what decides
             // whether the step's bindings are alternatives or witnesses, so the same
             // step function called two ways runs differently. See
             // {@link resolveScenarioSurfaces}.
-            step: (stepName, stepFunc, data, options) => this.scenarioStep('step', scenarioStepContext(), stepName, stepFunc, data, options),
             given: (stepName, stepFunc, data, options) => this.scenarioStep('given', scenarioStepContext(), stepName, stepFunc, data, options),
             when: (stepName, stepFunc, data, options) => this.scenarioStep('when', scenarioStepContext(), stepName, stepFunc, data, options),
             then: (stepName, stepFunc, data, options) => this.scenarioStep('then', scenarioStepContext(), stepName, stepFunc, data, options),

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -168,6 +168,41 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         source: string;
     } | null>;
     resumeWorkflow(runId: string, workflowName?: string): Promise<void>;
+    /**
+     * Ids of runs that are stalled: still `running`, with no step in a state that
+     * something is expected to complete (`running`, `scheduled`, `suspended`),
+     * and no step activity since `before`.
+     *
+     * Returns nothing by default so a store that cannot express the query keeps
+     * working unchanged; a store that overrides it gains crash recovery through
+     * `recoverStalledRuns`.
+     */
+    protected findStalledRunIds(_before: Date, _limit: number): Promise<string[]>;
+    /**
+     * Re-drive runs whose next move was lost, and report which were resumed.
+     *
+     * Arming a step is two writes to two systems — the step row, then the queue
+     * or scheduler job — so a process that dies between them leaves a run that is
+     * `running` with nothing in flight. Nothing notices: the run parks on a step
+     * that will never complete and never error, so it neither finishes nor fails.
+     * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
+     * step's insert and its timer, parking the run permanently.)
+     *
+     * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted
+     * step state, and every settled step is memoized, so resuming a run that was
+     * not actually stuck costs an orchestration pass and changes nothing. That
+     * idempotence is what makes an idle-time heuristic safe here; a run that is
+     * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+     *
+     * This is not self-starting. Call it from a scheduled task at whatever
+     * interval suits the workload.
+     */
+    recoverStalledRuns(options?: {
+        stalledAfterMs?: number;
+        limit?: number;
+    }): Promise<{
+        resumed: string[];
+    }>;
     protected resolveStepJobOptions(stepOptions?: WorkflowStepOptions): JobOptions;
     queueStepWorker(runId: string, stepName: string, rpcName: string, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<void>;
     executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -142,6 +142,10 @@ const WORKFLOW_TERMINAL_STATES = new Set([
     'failed',
     'cancelled',
 ]);
+/** Idle window before a `running` run with nothing in flight is treated as stalled. */
+const DEFAULT_STALLED_RUN_MS = 5 * 60_000;
+/** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
+const DEFAULT_STALLED_RUN_LIMIT = 100;
 const WORKFLOW_POLL_MIN_MS = 10;
 const WORKFLOW_POLL_FACTOR = 1.6;
 const WORKFLOW_CHILD_POLL_MAX_MS = 500;
@@ -435,6 +439,53 @@ export class PikkuWorkflowService {
             group: this.getJobGroup(workflowName),
         });
     }
+    /**
+     * Ids of runs that are stalled: still `running`, with no step in a state that
+     * something is expected to complete (`running`, `scheduled`, `suspended`),
+     * and no step activity since `before`.
+     *
+     * Returns nothing by default so a store that cannot express the query keeps
+     * working unchanged; a store that overrides it gains crash recovery through
+     * `recoverStalledRuns`.
+     */
+    async findStalledRunIds(_before, _limit) {
+        return [];
+    }
+    /**
+     * Re-drive runs whose next move was lost, and report which were resumed.
+     *
+     * Arming a step is two writes to two systems — the step row, then the queue
+     * or scheduler job — so a process that dies between them leaves a run that is
+     * `running` with nothing in flight. Nothing notices: the run parks on a step
+     * that will never complete and never error, so it neither finishes nor fails.
+     * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
+     * step's insert and its timer, parking the run permanently.)
+     *
+     * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted
+     * step state, and every settled step is memoized, so resuming a run that was
+     * not actually stuck costs an orchestration pass and changes nothing. That
+     * idempotence is what makes an idle-time heuristic safe here; a run that is
+     * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+     *
+     * This is not self-starting. Call it from a scheduled task at whatever
+     * interval suits the workload.
+     */
+    async recoverStalledRuns(options) {
+        const before = new Date(Date.now() - (options?.stalledAfterMs ?? DEFAULT_STALLED_RUN_MS));
+        const runIds = await this.findStalledRunIds(before, options?.limit ?? DEFAULT_STALLED_RUN_LIMIT);
+        const resumed = [];
+        for (const runId of runIds) {
+            try {
+                await this.resumeWorkflow(runId);
+                resumed.push(runId);
+            }
+            catch (err) {
+                // One unresumable run must not stop the sweep from recovering the rest.
+                getSingletonServices()?.logger?.error(`Failed to resume stalled workflow run ${runId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return { resumed };
+    }
     resolveStepJobOptions(stepOptions) {
         const retries = stepOptions?.retries ?? DEFAULT_STEP_RETRIES;
         const retryDelay = stepOptions?.retryDelay;

package/dist/wirings/workflow/scenario-prose.js

@@ -15,7 +15,7 @@ const formatValue = (value) => {
     return String(value);
 };
 export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
-    const keyword = phase === 'step' ? '' : capitalise(phase);
+    const keyword = capitalise(phase);
     const subject = actor ? `the ${actor}` : '';
     const rendered = template ? renderStepTemplate(template, input) : description;
     const sentence = [subject, rendered].filter(Boolean).join(' ');

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -3,14 +3,20 @@ import type { ScenarioPersona } from '../../services/personas-service.js';
  * Scenario steps: named, typed units of scenario behaviour.
  *
  * A step's body is an ordinary pikku function, so it may drive a browser, call
- * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
- * `step` — they only change the prose the reporter renders.
+ * an RPC as its actor, or run a workflow. `given` and `when` differ only in the
+ * prose the reporter renders; `then` also changes what runs, because its
+ * bindings are witnesses — every declared surface is observed and the
+ * observations must agree. See {@link ScenarioSurfaceResolution}.
  */
 /**
- * Which Gherkin-style keyword the reporter prefixes this step with. `step`
- * renders no prefix at all.
+ * Which Gherkin-style keyword the reporter prefixes this step with.
+ *
+ * Every step takes one. A scenario is read by people deciding whether it
+ * describes the behaviour they wanted, and a step that says only what it does
+ * without saying whether it is setup, action or claim is the one nobody can
+ * check — which is also why PKU680 can tell a scenario that never asserts.
  */
-export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then';
+export type ScenarioStepPhase = 'given' | 'when' | 'then';
 /**
  * Who acts in a step.
  *
@@ -41,7 +47,7 @@ export declare const SCENARIO_SURFACES: readonly ScenarioSurface[];
 /**
  * How a step's declared surfaces resolve for one run.
  *
- * `given`/`when`/`step` bindings are **alternatives** — clicking Buy and calling
+ * `given`/`when` bindings are **alternatives** — clicking Buy and calling
  * `createOrder` are two ways to cause one effect, so exactly one runs.
  *
  * `then` bindings are **witnesses** — "the order row says paid" and "the
@@ -73,7 +79,7 @@ export type ScenarioSurfaceResolution = {
     unwitnessed: boolean;
 };
 /**
- * Options accepted by `scenario.step/given/when/then`.
+ * Options accepted by `scenario.given/when/then`.
  *
  * Note the retry default differs from an ordinary workflow step: retrying a
  * failed assertion is the wrong behaviour for a test primitive, so steps

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

@@ -188,6 +188,13 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     dsl?: boolean;
     expose?: boolean;
     scenario?: boolean;
+    /**
+     * The flow asserts through an expectation helper — `expectService`,
+     * `expectError`, `expectEventually` — rather than a `then` step. Those are
+     * inline steps and carry no phase, so without this PKU680 reads a scenario
+     * whose only witness is a recorded service call as asserting nothing.
+     */
+    asserts?: boolean;
     skip?: string;
     actors?: string[];
 }>;

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md

@@ -0,0 +1,48 @@
+---
+type: decision
+title: A virtual user run is not a workflow and not a queued job
+description: runVirtualUser writes its record, dispatches the run without awaiting it, and returns the id — because an exploratory run has nothing to replay and the record already carries what a queue would be holding
+tags: virtual-user, storage
+---
+
+# A virtual user run is not a workflow and not a queued job
+
+`runVirtualUser` — the RPC `scaffold.virtualUser` generates — does three things
+in order: writes a `VirtualUserRunStore` record, dispatches
+`executeVirtualUserRun` **without awaiting it**, and returns the `runId`. There
+is no workflow, no queue, and no worker.
+
+Both of the alternatives are the obvious ones, and both are wrong for this.
+
+**A workflow** is a replayable step graph: its value is that a run can be
+resumed at the step it died on, and that the same input reaches the same step.
+A virtual user is the opposite by construction — it is an LLM deciding what to
+try next, so no two attempts take the same steps, and there is no step to resume
+*to*. Recording a run as a workflow puts entries in the workflow store that can
+never be replayed, and gives every operator reading that store a row that lies
+about what it is. The seed makes a run *reproducible* — run it again and it
+explores the same way — which is a different property from resumable, and one
+the record already carries.
+
+**A queue** buys durability across a restart and a retry on failure. It costs a
+broker dependency in every application that turns the scaffold on, plus a worker
+whose progress cannot be read anyway: the run's state lives in the store, not in
+the queue entry. The queue would be holding a copy of what the record already
+has, on the way to the same place.
+
+So the record is the run's only trace, and that is what `VirtualUserRunStore`
+exists for. It is also why `fail()` is a method rather than an absence: a run
+that crashed and a run that found nothing are different answers, and a record
+left at `running` is neither.
+
+The cost is real and is stated on the type: **a restart mid-run strands a record
+at `running` with nothing left to finish it.** A run older than its budget
+window and still `running` is dead, not working — that is a read-side rule, and
+it is cheaper than the two dependencies avoided. Nothing retries; a stranded run
+is started again, with its seed if the caller wants the same exploration.
+
+**What this rules out:** dispatching the run through `startWorkflow`; a
+scaffolded queue worker; awaiting the engine inside the request (a run takes
+minutes and survives neither a rollout nor a proxy timeout); and inferring
+`status` from `finishedAt` being unset, which cannot separate a crash from a run
+still going.

package/knowledge/decisions/internals/core-column-form-is-an-axis-of-its-own.md

@@ -0,0 +1,84 @@
+---
+type: decision
+title: A column's at-rest form is an axis of its own
+description: 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
+tags: core
+---
+
+# A column's at-rest form is an axis of its own
+
+`ColumnForm` in `packages/core/src/data-classification.ts` is a second,
+independent annotation on a column: `plain | hashed | wrapped | sealed`. It
+answers "how are these bytes held?", where `Classification` answers "may this
+value leave the process?".
+
+The two axes were one field before this, with `security: 'encrypted'` sitting
+alongside `secret` as though they were alternatives. They are not, and the
+conflation made the field unanswerable: a token hash and a live bearer token are
+both `secret`, one must never be encrypted — the digest *is* the lookup key —
+and the other must always be. Nothing in a single enum could tell them apart, so
+nothing could check either.
+
+## Why `wrapped` and `sealed` rather than `encrypted`
+
+Sealed values *are* encrypted, so an `encrypted` member sitting beside `sealed`
+would be a supertype posing as a sibling, and every new column would be an
+even-odds guess. What actually separates them is who can read the value back:
+`wrapped` is symmetric and the application holds the key; `sealed` is asymmetric
+and the application holds only the public half. Writing one where the other
+belongs produces a row nobody can ever open, which is why the type system is
+made to know the difference.
+
+## Why these brands are required when `Secret<T>` is optional
+
+`WrappedValue`, `SealedValue` and `HashedValue` are `string & { readonly [sym]:
+true }` with a `unique symbol` — nominal, and **required**, which
+[the classification-brand decision](core-data-classification-brand-is-an-optional-property.md)
+explicitly rules out for `Private`/`Pii`/`Secret`. That decision still stands and
+this does not weaken it. It applies to a different side of a different set of
+columns:
+
+- `Secret<T>` brands **every** classified column's SELECT type. A required brand
+  there would break `where('email', '=', someString)` in every downstream
+  project.
+- A form brands **only** the INSERT/UPDATE type, and only on the columns that
+  opt in by declaring a form. There is nothing to break, because a column
+  without a form generates exactly what it generated before.
+
+The brands compose rather than compete: a wrapped secret column selects as
+`Secret<WrappedValue>`, so the inspector's PKU910 check still finds
+`__classification__`, while a row read back is already a `WrappedValue` and
+flows into a rewrap or re-seal without a cast.
+
+Each brand widens to `string`, so query operands, serialization and template
+literals are unaffected. The constraint is on **construction**: the only way to
+produce one is `envelopeEncrypt`/`envelopeRewrap`/`wrapDEK` (wrapped) or
+`hashToken` (hashed), or the deliberately-named `unsafeAs*` assertions in
+`column-form.ts` for the three cases a bare string legitimately arrives —
+backfill migrations, test fixtures, and values sealed by another service.
+
+## What is deliberately NOT enforced
+
+`envelopeDecrypt` and `unwrapDEK` take plain `string`, not the brand. Requiring
+it would buy nothing — feeding in the wrong string already fails at the AEAD tag
+— while forcing a cast into every path that reads ciphertext out of a row or off
+the wire, which is where casts are least reviewable.
+
+The brand proves *provenance*, not correctness. It cannot know a value was
+wrapped under the right key, and making it know would mean phantom-typing key
+ids per scope, which the multi-recipient path would fight constantly.
+
+## The plain-secret diagnostic
+
+A `secret` column with no declared form raises **PKU483** as a warning, not an
+error. Every project predating the axis has such columns, and failing their next
+`db migrate` would be a breaking change for a diagnosis they have not had a
+chance to act on. `pikku db --fail-on-warn` is how a project opts into the
+ratchet. An explicit `form: 'plain'` silences it — that is the acknowledgement
+that reading the row is *meant* to yield a usable credential.
+
+**What this rules out:** collapsing `wrapped` and `sealed` back into one
+`encrypted`; making the form brands optional (they would enforce nothing);
+re-declaring them in generated schema files, since a local `unique symbol` is a
+distinct nominal type and core's own ciphertext would not be assignable to the
+column it belongs in — `db-codegen` imports them from `@pikku/core` instead.

package/knowledge/decisions/internals/core-data-classification-brand-is-an-optional-property.md

@@ -22,10 +22,17 @@ goes into one.
 
 The consumer is `@pikku/inspector`, whose `findPiiPaths` reads the level union
 directly and whose PKU910 output check detects the brand on a function's return
-type. The brands are populated from `-- @private` / `-- @secret` / `-- @public`
-SQL comment annotations via `pikku db migrate`, which regenerates
+type. The brands are populated from the hand-authored `db/annotations.ts`
+(`DbClassificationMap`) via `pikku db migrate`, which regenerates
 `outDir/db/schema.d.ts` and `outDir/db/classification.gen.ts`.
 
+A column's **at-rest form** is a separate axis making the opposite trade — see
+[form is an axis of its own](core-column-form-is-an-axis-of-its-own.md). Its
+brands are nominal and required, which is safe precisely because they land on
+the INSERT/UPDATE side of the columns that opt in, rather than on the SELECT
+side of every classified column. That is not an exception to the rule below; it
+is a different rule about a different side.
+
 **What this rules out:** making `__classification__` required to get stronger
 guarantees, or replacing the optional property with a unique symbol / nominal
 brand that behaves like a required one. Either change compiles here and then

package/knowledge/decisions/internals/index.md

@@ -38,6 +38,7 @@ 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
@@ -77,8 +78,11 @@ caller is entitled to assume.
 - [The in-memory workflow service is inline-only and single-process](the-in-memory-workflow-service-is-inline-only-and-single-process.md) — InMemoryWorkflowService wires no queues and implements withRunLock/withStepLock as pass-throughs, because inline execution has no second holder to exclude
 - [The KEK salt is scoped to the key version, not the secret](the-kek-salt-is-scoped-to-the-key-version.md) — One stored salt per key version means N secrets cost one derivation, which is the point of envelope encryption
 - [The schema service is never stubbed, or tests validate nothing](the-schema-service-is-never-stubbed.md) — createStubProxy returns undefined for the schema property so the real schema service is built — a stubbed one turns validation into a silent no-op
+- [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
+- [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
 - [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
 - [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
 - [Webhook service collaborators are constructor args, not locator lookups](webhook-service-collaborators-are-constructor-args-not-locator-lookups.md) — QueueWebhookService takes its queue as a constructor parameter so a project wiring webhooks without a queue fails to compile instead of at first send
 - [Whether a run is inline is read from the run record](whether-a-run-is-inline-is-read-from-the-run-record.md) — The runContexts map is a read-through cache over WorkflowRun.inline and a lifetime for replay ordinals, never the answer to what a run is

package/knowledge/decisions/internals/one-project-shape-check-two-validators.md

@@ -0,0 +1,53 @@
+---
+type: decision
+title: One project-shape check, called by both validators
+description: 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
+tags: cli, validate, fabric
+---
+
+# One project-shape check, called by both validators
+
+`pikku workspace validate` and `pikku fabric validate` read like one command
+with a flag. They were two implementations — 495 lines and 2026 — that walked
+the same project and emitted sixteen identical findings. `functions-dir-missing`
+existed character for character in both files. All sixteen already agreed on
+severity, which is the only reason the duplication was invisible.
+
+What the duplication cost was not the lines. It was that each validator carried
+checks the other lacked for no reason anyone could name, and nobody noticed
+because nobody read them side by side:
+
+- fabric validate never checked that `packages/functions` declares zod v4, or
+  that it has a `package.json` at all — while it did check that six other
+  dependencies are present.
+- workspace validate never checked the four scaffold flags beyond `console`,
+  though the console it requires is useless without `rpc`.
+- fabric validate swallowed a JSON parse error and reported
+  `pikku-config-missing` for a file sitting right there.
+
+Two of workspace validate's own checks were not merely absent from fabric — they
+had never run anywhere:
+
+- the auth checks were gated on a middleware instance with `definitionId ===
+  'betterAuthSession'`, but the CLI wires `betterAuthStatelessSession` whenever
+  `session.cookieCache` is on, which is the configuration Fabric asks for. So
+  they skipped precisely the apps most likely to have auth.
+- they looked for migrations in `packages/functions/db/`, and for tables named
+  `app_user` and `auth_verification_token`. `pikku db migrate` reads migrations
+  from `<root>/db/<engine>/`, and those two table names appear nowhere else in
+  pikku or in any template. Had the gate ever opened, the check would have been
+  wrong for every project it fired on.
+
+`shared-checks.ts` is now the half that is true of any pikku project regardless
+of where it deploys. Workspace validate is exactly that module; fabric validate
+is that module plus the deploy-shaped checks — themes, frontends, the
+Cloudflare adapter, the `.gitignore` contract, the frontend type-check.
+
+Fabric's fix hints won where the two differed: they are multi-line and show the
+config block to paste, and there was no reason workspace users were getting the
+one-line version.
+
+**What this rules out:** adding a check to one validator and not the other;
+`pikku fabric validate` reporting a corrupt config as a missing one; asserting
+auth table names no scaffold generates; and reading migrations from anywhere
+other than where `pikku db migrate` reads them.

package/knowledge/decisions/internals/scenarios-live-in-files-named-for-them.md

@@ -0,0 +1,48 @@
+---
+type: decision
+title: Scenarios, steps and personas live in files named for them, and validate errors when they do not
+description: 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
+tags: cli, validate, scenarios, personas
+---
+
+# Scenarios, steps and personas live in files named for them, and validate errors when they do not
+
+A `pikkuScenario` declared beside the functions it exercises reads as more of
+the same file. The wiring, the function, and the test of the function arrive in
+one scroll, and the scenario is the part that gets lost — you cannot tell from
+a directory listing which files ship and which files test.
+
+So `validate` requires the declaration to be in a file named for what it is:
+
+| declaration | file |
+| --- | --- |
+| `pikkuScenario`, `pikkuFeature` | `*.scenario.ts`, `*.scenarios.ts` |
+| `pikkuScenarioStep` and its platform/addon variants | `*.steps.ts` (or the above) |
+| `definePersonas`, `runVirtualUser` | `*.virtual-user.ts`, `*.vu.ts` |
+
+Three suffixes for scenarios rather than one, because the split that matters is
+scenarios apart from application code, not a particular spelling — `.steps.ts`
+holds the steps, `.scenarios.ts` holds the scenarios that call them, and a
+project that already made that split does not have to rename anything.
+
+**Error, not warning.** The mixing is cheap to undo while it is one file and
+expensive once it is thirty, and a warning is exactly the signal a project
+learns to scroll past. This is the one place where the scenario checks are
+strict: everything else `validate` says about scenarios (no personas declared,
+no actor sign-in, no environments) is a warning, because those describe an
+under-tested project rather than an unreadable one.
+
+**Personas are the virtual-user file** because there is no `defineVirtualUsers`
+to look for. That name was retired in favour of `definePersonas`: a virtual user
+is derived rather than authored — the function meta becomes its catalogue, the
+scenario meta becomes its intents, the declared personas become its identities.
+The persona list is the only part a project writes, so it is the part that has
+to be findable by filename.
+
+Matching is on the call (`\bpikkuScenario\s*\(`), not the import, so an aliased
+import cannot slip past and a mention in a comment or a string does not trip it.
+Generated files are exempt — codegen puts things where it likes.
+
+**What this rules out:** a scenario in a function file; a step in a wiring file;
+personas in a general-purpose `personas.ts`; and reporting any of these as a
+warning that a project can carry indefinitely.