@pikku/core 0.12.84 → 0.12.88

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

@@ -1,4 +1,5 @@
-import type { CoreUserSession, SerializedError } from '../../types/core.types.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.js';
 import type { PikkuWorkflowWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
@@ -104,12 +105,12 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      *
      * Returns nothing by default so a store that cannot express the query keeps
      * working unchanged — and, because it does not opt in, gains no re-dispatches
-     * either. A store must have an atomic `withStepLock` before overriding this,
-     * or no concurrency for one to exclude: the relay makes duplicate dispatch
-     * routine, and the claim in `executeWorkflowStepInner` is what keeps a
-     * duplicate from becoming a second execution. `kysely-postgres` and
-     * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
-     * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+     * either. A store must have an atomic `claimStepForExecution` before
+     * overriding this, or no concurrency for one to exclude: the relay makes
+     * duplicate dispatch routine, and the claim is what keeps a duplicate from
+     * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
+     * status-guarded claim, `in-memory` on being inline and single-process;
+     * `mongodb` still qualifies on neither.
      */
     protected findUndispatchedSteps(_before: Date, _limit: number): Promise<Array<{
         runId: string;
@@ -175,6 +176,20 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     protected onChildWorkflowFailed(childRun: WorkflowRun, error: Error): Promise<void>;
     private runVersionMismatchFallback;
     executeWorkflowStep(runId: string, stepName: string, rpcName: string, data: any, rpcService: PikkuRPC): Promise<void>;
+    /**
+     * Take sole ownership of a step before it runs, returning the state to run
+     * under — or `null` when another dispatch already owns it.
+     *
+     * Dispatch is at-least-once by design: the relay re-dispatches steps it
+     * believes were dropped, and a queue can redeliver a job it already handed
+     * out. This is the one place that keeps a duplicate dispatch from becoming a
+     * second execution of a side-effecting step, so it is only as strong as the
+     * exclusion it is built on — and `withStepLock` excludes nothing unless the
+     * store backs it with a real primitive. A store able to express the decision
+     * as one conditional write should override this rather than reach for a lock,
+     * which is what `@pikku/kysely` does with a status-guarded `UPDATE`.
+     */
+    protected claimStepForExecution(runId: string, stepName: string, rpcName: string): Promise<StepState | null>;
     private executeWorkflowStepInner;
     orchestrateWorkflow(runId: string, rpcService: PikkuRPC): Promise<void>;
     private verifyQueueService;

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

@@ -1,7 +1,7 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-import { ChildWorkflowStartedException, continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
+import { ChildWorkflowStartedException, continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, stripInstanceOrdinal, } from './graph/graph-runner.js';
 import { isExpectedError } from '../../errors/error-handler.js';
 import { PikkuMissingMetaError } from '../../errors/errors.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
@@ -9,13 +9,14 @@ import { deriveInvocationId } from './workflow-invocation-id.js';
 import { approvalDeciderFrom } from './workflow-approval-policy.js';
 import { buildRunTimeline, reconstructStateAt, } from './run-timeline.js';
 import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, } from './workflow-constants.js';
-import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepFunctionMismatchError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
+import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
 import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
 import { jobGroupFor, orchestratorQueueName, resolveWorkflowConfig, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
 import { wireWorkflowQueueWorkers } from './workflow-queue-wiring.js';
 import { approvalStepNameFor, evaluateApprovalStep, recordApprovalDecision, } from './workflow-approval.js';
 import { auditApprovalDecision } from './workflow-approval-audit.js';
 import { recordSuspension, suspendStepNameFor } from './workflow-suspend.js';
+import { claimStepByReadThenWrite } from './workflow-step-claim.js';
 import { RedispatchBackoff, sweepStalledRuns, sweepUndispatchedSteps, } from './workflow-recovery.js';
 export class PikkuWorkflowService {
     runExtension;
@@ -261,12 +262,12 @@ export class PikkuWorkflowService {
      *
      * Returns nothing by default so a store that cannot express the query keeps
      * working unchanged — and, because it does not opt in, gains no re-dispatches
-     * either. A store must have an atomic `withStepLock` before overriding this,
-     * or no concurrency for one to exclude: the relay makes duplicate dispatch
-     * routine, and the claim in `executeWorkflowStepInner` is what keeps a
-     * duplicate from becoming a second execution. `kysely-postgres` and
-     * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
-     * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+     * either. A store must have an atomic `claimStepForExecution` before
+     * overriding this, or no concurrency for one to exclude: the relay makes
+     * duplicate dispatch routine, and the claim is what keeps a duplicate from
+     * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
+     * status-guarded claim, `in-memory` on being inline and single-process;
+     * `mongodb` still qualifies on neither.
      */
     async findUndispatchedSteps(_before, _limit) {
         return [];
@@ -697,25 +698,24 @@ export class PikkuWorkflowService {
             this.exitExecution(runId);
         }
     }
+    /**
+     * Take sole ownership of a step before it runs, returning the state to run
+     * under — or `null` when another dispatch already owns it.
+     *
+     * Dispatch is at-least-once by design: the relay re-dispatches steps it
+     * believes were dropped, and a queue can redeliver a job it already handed
+     * out. This is the one place that keeps a duplicate dispatch from becoming a
+     * second execution of a side-effecting step, so it is only as strong as the
+     * exclusion it is built on — and `withStepLock` excludes nothing unless the
+     * store backs it with a real primitive. A store able to express the decision
+     * as one conditional write should override this rather than reach for a lock,
+     * which is what `@pikku/kysely` does with a status-guarded `UPDATE`.
+     */
+    async claimStepForExecution(runId, stepName, rpcName) {
+        return this.withStepLock(runId, stepName, () => claimStepByReadThenWrite(this, runId, stepName, rpcName));
+    }
     async executeWorkflowStepInner(runId, stepName, rpcName, data, rpcService) {
-        const claimed = await this.withStepLock(runId, stepName, async () => {
-            const stepState = await this.getStepState(runId, stepName);
-            // knowledge: decisions/security/a-step-runs-the-function-the-workflow-dispatched-it-with.md
-            if (stepState.rpcName !== undefined &&
-                stepState.rpcName !== (rpcName ?? null)) {
-                throw new WorkflowStepFunctionMismatchError(runId, stepName);
-            }
-            if (stepState.status === 'succeeded' || stepState.status === 'running') {
-                return null;
-            }
-            if (stepState.status === 'failed') {
-                return this.createRetryAttempt(stepState.stepId, 'running');
-            }
-            if (stepState.status === 'pending' || stepState.status === 'scheduled') {
-                await this.setStepRunning(stepState.stepId);
-            }
-            return stepState;
-        });
+        const claimed = await this.claimStepForExecution(runId, stepName, rpcName);
         if (!claimed) {
             return;
         }
@@ -735,9 +735,8 @@ export class PikkuWorkflowService {
                     graphNodeId = stepName;
                 }
                 else {
-                    const hash = stepName.lastIndexOf('#');
-                    const base = hash > 0 ? stepName.slice(0, hash) : undefined;
-                    if (base && base in workflowMeta.nodes)
+                    const base = stripInstanceOrdinal(stepName);
+                    if (base !== stepName && base in workflowMeta.nodes)
                         graphNodeId = base;
                 }
             }

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

@@ -1,4 +1,4 @@
-import type { SerializedError } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { StepState, StepStatus } from './workflow.types.js';
 export interface RunTimelineEvent {
     seq: number;

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

@@ -0,0 +1,171 @@
+/**
+ * What one `pikku scenario run` leaves behind.
+ *
+ * A run is history: the scenarios it selected, the sentences they were made of,
+ * and the images and footage they produced. The sentences are snapshotted into
+ * the record rather than looked up later, because a scenario is code and the
+ * code moves — a run from last week describes a suite that no longer exists,
+ * and re-deriving its ladder from today's source would quietly rewrite it.
+ *
+ * Everything here is plain serialisable data. That is what lets one record be
+ * a JSON file on disk in OSS and a row in Postgres on a hosted project, read
+ * back by the same console screen either way.
+ */
+import type { ScenarioBrowserFailure } from './scenario-step.types.js';
+/** What a run filed, in the order it filed it. */
+export type ScenarioArtifactKind = 'screenshot' | 'failure' | 'video';
+/**
+ * One image or recording a scenario produced.
+ *
+ * `path` is relative to the run's artifact root and always uses forward
+ * slashes: it is a content key, not a filesystem path. Locally it resolves
+ * under the run's directory; on a hosted project it is the object key in a
+ * bucket, and the same record works unchanged.
+ */
+export interface ScenarioArtifact {
+    /** The scenario label this belongs to, as the report names it. */
+    scenario: string;
+    kind: ScenarioArtifactKind;
+    path: string;
+    /** Whose window it was — a two-actor scenario produces two of everything. */
+    actor?: string;
+    /** The caption the scenario author took a screenshot under. */
+    name?: string;
+}
+/** One step of a run, already joined to the prose that declared it. */
+export interface ScenarioStepRow {
+    sentence: string;
+    status: string;
+    durationMs?: number;
+    error?: string;
+}
+/** Everything known about why one scenario failed. */
+export interface ScenarioFailureDetail {
+    /** The rendered sentence of the failing step; absent if no step failed. */
+    sentence?: string;
+    message: string;
+    stack?: string;
+    /**
+     * True when the failure was a deliberate one (a PikkuError). Its message is
+     * the whole story, so the stack is noise.
+     */
+    expected?: boolean;
+    browser?: ScenarioBrowserFailure[];
+}
+export interface ScenarioResult {
+    name: string;
+    status: 'passed' | 'failed';
+    durationMs: number;
+    output?: unknown;
+    error?: string;
+    steps?: ScenarioStepRow[];
+    failure?: ScenarioFailureDetail;
+    /** The scenario registration this ran, which the label alone does not give. */
+    scenarioName?: string;
+    /** The feature that grouped it, when one did. */
+    feature?: string;
+    tags?: string[];
+    /** Images and footage this scenario produced, filed under the run. */
+    artifacts?: ScenarioArtifact[];
+}
+/** One scenario that was not run, and why. */
+export interface ScenarioSkip {
+    name: string;
+    reason: string;
+}
+export interface ScenarioRunReport {
+    environment: string;
+    results: ScenarioResult[];
+    /**
+     * Scenarios not run at all, each carrying why. A skip is only useful if the
+     * reader can tell a browser scenario held back by `--no-browser` from one the
+     * project itself quarantined, so the reason travels with the name rather than
+     * being assumed by the formatter.
+     */
+    skipped: ScenarioSkip[];
+    /** Feature-level hook failures, which belong to no single scenario. */
+    hookFailures: string[];
+}
+export type ScenarioRunStatus = 'running' | 'passed' | 'failed';
+/**
+ * A whole run, as it is stored and read back.
+ *
+ * `status` is `running` from the moment the run is created until it finishes,
+ * so a console watching a run in progress can tell "still going" from "nothing
+ * came back" — and a run killed halfway stays `running` forever, which is the
+ * honest record of what happened to it.
+ */
+export interface ScenarioRunRecord extends ScenarioRunReport {
+    runId: string;
+    status: ScenarioRunStatus;
+    /** The surface the run targeted: `default`, `browser`, … */
+    surface: string;
+    startedAt: string;
+    finishedAt?: string;
+}
+/** Enough of a run to list it without loading its steps and stacks. */
+export interface ScenarioRunSummary {
+    runId: string;
+    environment: string;
+    surface: string;
+    status: ScenarioRunStatus;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    /** Whether anything is there to watch, so a list can say so without a second read. */
+    artifacts: number;
+}
+/**
+ * Where runs are kept.
+ *
+ * Deliberately not the workflow service: a scenario run is a workflow run under
+ * the hood, but its history has a different lifetime, a different audience, and
+ * a different home — a JSON file beside the project locally, a project-scoped
+ * table and an object store when hosted.
+ *
+ * Written progressively rather than at the end, so a suite that dies on its
+ * fortieth scenario still leaves the thirty-nine behind.
+ */
+export interface ScenarioRunStore {
+    /** Open a run. Called before the first scenario, with `status: 'running'`. */
+    start(record: ScenarioRunRecord): Promise<void>;
+    /** Append one finished scenario to an open run. */
+    recordScenario(runId: string, result: ScenarioResult): Promise<void>;
+    /**
+     * File the run's artifacts against the scenarios that produced them.
+     *
+     * Separate from `recordScenario` because a scenario's video does not exist
+     * when the scenario ends — it is finalised by the next scenario's reset, and
+     * renamed again when the run closes. Artifacts are matched to a result by the
+     * label the report knows it under.
+     */
+    attachArtifacts(runId: string, artifacts: ScenarioArtifact[]): Promise<void>;
+    /** Close a run, settling everything only known once every scenario has run. */
+    finish(runId: string, outcome: Pick<ScenarioRunRecord, 'status' | 'finishedAt' | 'skipped' | 'hookFailures'>): Promise<void>;
+    /**
+     * The bytes of one artifact, by the `path` its record carries.
+     *
+     * Reading goes through the store because only the store knows where a run's
+     * files actually are — a directory beside the project, or an object store
+     * behind a bucket. Absent when the run or the path is unknown, which is also
+     * the answer for a path that tries to leave the run.
+     *
+     * The bytes are backed by their own `ArrayBuffer` so they can be handed
+     * straight to a `Response` — a view onto a pooled or shared buffer is not a
+     * valid body.
+     */
+    readArtifact(runId: string, path: string): Promise<{
+        body: Uint8Array<ArrayBuffer>;
+        contentType: string;
+    } | undefined>;
+    /** Most recent first. */
+    list(options?: {
+        limit?: number;
+    }): Promise<ScenarioRunSummary[]>;
+    get(runId: string): Promise<ScenarioRunRecord | undefined>;
+    /** Forget a run and everything it filed. */
+    remove(runId: string): Promise<void>;
+}

package/dist/wirings/workflow/scenario-run.types.js

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

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

@@ -1,3 +1,2 @@
 import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
-export declare const requireActor: <TActor>(scenarioStep: PikkuScenarioStepWire<TActor> | undefined) => TActor;
-export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire<unknown> | undefined) => ScenarioEnvironment;
+export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -1,11 +1,3 @@
-export const requireActor = (scenarioStep) => {
-    const actor = scenarioStep?.actor;
-    if (!actor) {
-        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' was called without an actor. ` +
-            `Pass { actor: actors.<name> } so it runs as that persona.`);
-    }
-    return actor;
-};
 export const requireScenarioEnv = (scenarioStep) => {
     const env = scenarioStep?.env;
     if (!env) {

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

@@ -1,4 +1,4 @@
-import type { ScenarioPersona } from '../../services/personas-service.js';
+import type { ScenarioArtifact } from './scenario-run.types.js';
 /**
  * Scenario steps: named, typed units of scenario behaviour.
  *
@@ -86,7 +86,10 @@ export type ScenarioSurfaceResolution = {
  * default to no retries.
  */
 export interface ScenarioStepOptions {
-    /** The actor this step runs as. Required for steps declaring a `browser` binding. */
+    /**
+     * The actor this step runs as. Required for a step that declares `actor: true`
+     * or a `browser` binding; the runner refuses to dispatch one without it.
+     */
     actor?: unknown;
     /** Overrides the step's own `description` for this call site only. */
     description?: string;
@@ -107,11 +110,12 @@ export interface ScenarioEnvironment {
 /**
  * The `scenarioStep` wire, present on every scenario step invocation.
  *
- * `TActor` is the project's own actor type, so a step reaches only the RPCs its
- * actors can actually call. It defaults to the open `ScenarioPersona` for a
- * project that declares no registry.
+ * The persona a step runs as is not here: it arrives as `wire.actor`, injected
+ * by the runner and typed as present exactly on the bindings that declared they
+ * need one. Keeping it off this interface is what makes that possible — a wire
+ * member can be required per binding, a property of one cannot.
  */
-export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
+export interface PikkuScenarioStepWire {
     /** Registered step name (also its pikkuFuncId) */
     name: string;
     /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
@@ -123,12 +127,6 @@ export interface PikkuScenarioStepWire<TActor = ScenarioPersona> {
      * per witness, so its body sees this change between invocations.
      */
     surface: ScenarioSurface;
-    /**
-     * The actor this step runs as, when one was given. Call RPCs through it
-     * (`actor.invoke(...)`) so they run against the target environment as that
-     * persona.
-     */
-    actor?: TActor;
     /**
      * The environment this run targets. A step runs in the CLI process, where
      * there is no `variables` service — this is how a raw-HTTP step learns the
@@ -218,11 +216,28 @@ export interface ScenarioBrowserProvider {
      * folder — findable only by timestamp.
      */
     beginScenario?(scenario: string): void;
+    /**
+     * Report how the scenario that just ran finished.
+     *
+     * Called after each scenario, and separate from `reset()` because artifacts
+     * that only exist once a window closes — a video — are produced by the NEXT
+     * scenario's reset, long after the outcome that decides whether to keep them.
+     */
+    endScenario?(outcome: 'passed' | 'failed'): void;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must
      * not replace the failure being captured.
      */
     captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>;
+    /**
+     * Everything the run filed, each entry naming the scenario it belongs to.
+     *
+     * Reported by the driver rather than discovered by scanning the directory:
+     * only the driver knows which window produced a file and under what caption,
+     * and a video's final name is not settled until the run closes. Read after
+     * `close()`, which is the first moment the answer is complete.
+     */
+    artifacts?(): ScenarioArtifact[];
     close(): Promise<void>;
 }

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

@@ -103,7 +103,8 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
         return stepState.result;
     }
     const stateKey = approvalStateKey(approvalStepName);
-    let record = ((await store.getRunState(runId))[stateKey] ?? {});
+    let record = ((await store.getRunState(runId))[stateKey] ??
+        {});
     const policy = {
         approvers: options.approvers,
         approverScope: options.approverScope,

package/dist/wirings/workflow/workflow-run-engine.types.d.ts

@@ -1,4 +1,5 @@
-import type { PikkuRawWire, SerializedError } from '../../types/core.types.js';
+import type { PikkuRawWire } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
 import type { CoreWorkflow, PikkuWorkflowWire, StepState, WorkflowRun, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
 export interface RunLifecycleContext {
     runId: string;

package/dist/wirings/workflow/workflow-step-claim.d.ts

@@ -0,0 +1,16 @@
+import type { StepState } from './workflow.types.js';
+/** What claiming a step needs from the workflow service. */
+export type StepClaimStore = {
+    getStepState(runId: string, stepName: string): Promise<StepState>;
+    setStepRunning(stepId: string): Promise<void>;
+    createRetryAttempt(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+};
+/**
+ * Decide whether this dispatch owns the step, by reading its state and then
+ * writing it — which only excludes a concurrent dispatch when the caller holds
+ * a lock that genuinely excludes one.
+ *
+ * A store that can express the whole decision as a single conditional write
+ * should do that instead of calling this.
+ */
+export declare const claimStepByReadThenWrite: (store: StepClaimStore, runId: string, stepName: string, rpcName: string) => Promise<StepState | null>;

package/dist/wirings/workflow/workflow-step-claim.js

@@ -0,0 +1,27 @@
+import { WorkflowStepFunctionMismatchError } from './workflow-errors.js';
+/**
+ * Decide whether this dispatch owns the step, by reading its state and then
+ * writing it — which only excludes a concurrent dispatch when the caller holds
+ * a lock that genuinely excludes one.
+ *
+ * A store that can express the whole decision as a single conditional write
+ * should do that instead of calling this.
+ */
+export const claimStepByReadThenWrite = async (store, runId, stepName, rpcName) => {
+    const stepState = await store.getStepState(runId, stepName);
+    // knowledge: decisions/security/a-step-runs-the-function-the-workflow-dispatched-it-with.md
+    if (stepState.rpcName !== undefined &&
+        stepState.rpcName !== (rpcName ?? null)) {
+        throw new WorkflowStepFunctionMismatchError(runId, stepName);
+    }
+    if (stepState.status === 'succeeded' || stepState.status === 'running') {
+        return null;
+    }
+    if (stepState.status === 'failed') {
+        return store.createRetryAttempt(stepState.stepId, 'running');
+    }
+    if (stepState.status === 'pending' || stepState.status === 'scheduled') {
+        await store.setStepRunning(stepState.stepId);
+    }
+    return stepState;
+};

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

@@ -1,4 +1,5 @@
-import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
+import type { CommonWireMeta } from '../../types/core.types.js';
+import type { SerializedError } from '../../errors/serialized-error.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';

package/knowledge/decisions/index.md

@@ -14,6 +14,8 @@ here first — several of these exist because the obvious simplification was tri
 and broke something.
 
 <!-- pikku:knowledge-index -->
+
 - [internals](internals/index.md) — a rule about how it works under the hood, and why
 - [security](security/index.md) — a rule about who may do what
+
 <!-- /pikku:knowledge-index -->

package/knowledge/decisions/internals/a-scenario-step-template-is-offered-unfilled.md

@@ -14,7 +14,7 @@ A reporter fills those placeholders from a run that already happened. There is
 no run yet at derivation time, so there is nothing to fill them from. More
 importantly, filling them would answer the wrong question: "invites {email}"
 tells the user to choose someone, where "invites ada@example.com" tells it whom
-— and *whom* is the scenario author's answer, not something the virtual user
+— and _whom_ is the scenario author's answer, not something the virtual user
 worked out.
 
 **What this rules out:** substituting example or fixture values to make the

package/knowledge/decisions/internals/a-secret-that-fails-to-decrypt-fails-the-whole-read.md

@@ -37,7 +37,7 @@ that turn that into a one-line fix, and they are known at the catch site and
 nowhere after it.
 
 This matters most at exactly the moment it is least convenient: a change to
-`deriveKEK` makes *every* previously stored secret undecryptable at once. Loud
+`deriveKEK` makes _every_ previously stored secret undecryptable at once. Loud
 failure names the first one; silence produces an empty map and a support ticket.
 
 **What this rules out:** a `getSecrets` that skips unreadable rows; returning

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

@@ -18,9 +18,9 @@ Both of the alternatives are the obvious ones, and both are wrong for this.
 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
+_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
+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.
 

package/knowledge/decisions/internals/a-wall-clock-threshold-is-a-load-test-in-disguise.md

@@ -13,11 +13,11 @@ per secret turns a 10ms operation into a 4-second one.
 
 It guarded it with `assert.ok(elapsed < 50)`. Measured on this machine:
 
-| | |
-| --- | --- |
-| one `deriveKEK` | ~86ms |
-| 50 `envelopeDecrypt` | 10.8ms |
-| the old 50ms threshold | 4.6x headroom |
+|                               |                                 |
+| ----------------------------- | ------------------------------- |
+| one `deriveKEK`               | ~86ms                           |
+| 50 `envelopeDecrypt`          | 10.8ms                          |
+| the old 50ms threshold        | 4.6x headroom                   |
 | the failure it guards against | ~4281ms — a **396x** separation |
 
 So the assertion had 4.6x of margin to detect a 396x regression. Everything
@@ -37,7 +37,7 @@ suite grows or CI moves to a noisier runner. Any assertion of the form
 ratio against something measured alongside it.
 
 Worth knowing: `envelopeDecrypt(kek: CryptoKey, …)` takes the derived key as a
-parameter, so it *cannot* derive one — the property is already enforced by the
+parameter, so it _cannot_ derive one — the property is already enforced by the
 signature, and [[the-api-report-pins-members-not-just-names]] would catch a
 change to it. The test is defence in depth, which is a reason to make it cheap
 and quiet rather than to delete it.

package/knowledge/decisions/internals/a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md

@@ -18,7 +18,7 @@ pikkuUserId: rpcService.wire?.pikkuUserId,
 ```
 
 `PikkuRPC` has no `wire`. Neither does the object `getContextRPCService`
-actually returns — `ContextAwareRPCService` holds its wire *privately* and
+actually returns — `ContextAwareRPCService` holds its wire _privately_ and
 exposes `invoke`, `remote`, `exposed`, `startWorkflow`, `agent` and
 `rpcWithWire`, and nothing else. Every one of those reads was `undefined`, and
 the `rpcService: any` parameter type is what kept the compiler quiet about it.

package/knowledge/decisions/internals/addon-singleton-services-are-cached-per-namespace-not-per-package.md

@@ -17,7 +17,7 @@ One package may be wired twice — the same payments addon against a live and a
 sandbox account, say — with different secret and variable names. Caching by
 package name would build the service graph once, from whichever instance called
 first, and silently hand the other instance the wrong credentials. Because the
-overrides have to be visible to the addon's *own* `createSingletonServices`, they
+overrides have to be visible to the addon's _own_ `createSingletonServices`, they
 are applied by wrapping the parent `secrets` and `variables` services
 (`aliasSecretService`, `aliasVariablesService`) so that every logical name the
 addon reads is remapped to the real project name before resolution. A call with

package/knowledge/decisions/internals/addon-workflow-names-are-prefixed-with-the-consumer-namespace.md

@@ -15,7 +15,7 @@ instance namespace when known and otherwise the package's sole namespace via
 `findAddonNamespaceForPackage`.
 
 Workflows declared by an addon are registered under the addon's package scope,
-but the namespace they answer to is chosen by the *consumer* in `wireAddon`.
+but the namespace they answer to is chosen by the _consumer_ in `wireAddon`.
 Without the proxy, `runToCompletion('myWorkflow')` written inside the addon
 resolves against root meta, misses, and throws `WorkflowNotFoundError` — leaving
 the addon author no option but to hardcode the consumer-defined namespace, which

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

@@ -24,7 +24,7 @@ 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
+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

package/knowledge/decisions/internals/channel-message-handlers-accept-three-config-shapes.md

@@ -14,7 +14,7 @@ things a caller may put on `onMessage` or inside `onMessageWiring`:
 - a direct function config, where `onMessage.func` is a plain `Function`;
 - a wrapper, where `onMessage.func` is itself a `CorePikkuFunctionConfig` and so
   has its own nested `.func`;
-- a simple wrapper, which carries a plain `Function` under `func` *and* a
+- a simple wrapper, which carries a plain `Function` under `func` _and_ a
   sibling `middleware` array.
 
 The `isWrapper` check tests exactly that: an object with `func`, where either

package/knowledge/decisions/internals/channel-middleware-caches-only-statically-resolved-middleware.md

@@ -19,7 +19,7 @@ user's stream and growing memory run over run. It is therefore appended fresh on
 every call, after the cached inherited slice.
 
 The `uid` matters as much as the cache split. `processMessageHandlers` in
-`channel-handler.ts` builds it from the channel name *plus* the routing property
+`channel-handler.ts` builds it from the channel name _plus_ the routing property
 and router value (`${name}:${routingProperty}:${routerValue}`, or
 `${name}:default`), because several message routes on one channel may point at
 the same function — a key based on the function alone would serve one route's

package/knowledge/decisions/internals/channel-user-id-is-persisted-after-onconnect-middleware-runs.md

@@ -10,7 +10,7 @@ tags: channel
 `runChannelConnect` in
 `packages/core/src/wirings/channel/serverless/serverless-channel-runner.ts`
 reads `userSession.getPikkuUserId()` and calls `channelStore.setPikkuUserId`
-*after* `runChannelLifecycleWithMiddleware` has executed the `onConnect`
+_after_ `runChannelLifecycleWithMiddleware` has executed the `onConnect`
 lifecycle, not before.
 
 Auth middleware runs as part of that lifecycle — it is what inspects the upgrade