@reticlehq/server 3.5.0 → 3.7.0

package/dist/judgement/capsule/causal-summary.js

@@ -1,5 +1,6 @@
 import { EventType, PerfMetric, isDevToolingUrl } from '@reticlehq/core';
 import { routeOfEvent } from '@reticlehq/engine/question/predicate/predicate-route.js';
+import { isCacheBookkeepingDiff } from '@reticlehq/engine/evidence/state-bookkeeping.js';
 /**
  * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the
  * app did. A verdict travels in the same payload as its evidence, so an unbounded evidence field is
@@ -57,12 +58,34 @@ function stateSettle(diffs) {
     const spread = Math.max(...times) - Math.min(...times);
     return spread > 0 ? { stateSettleMs: spread } : {};
 }
+/** `METHOD /path STATUS` — what an agent recognises a call by. */
+function requestLine(data) {
+    const raw = 'string' === typeof data['url'] ? data['url'] : '';
+    let path;
+    try {
+        path = new URL(raw, 'http://local.invalid').pathname;
+    }
+    catch {
+        path = raw.split('?')[0] ?? raw;
+    }
+    const method = 'string' === typeof data['method'] ? data['method'].toUpperCase() : 'GET';
+    const status = 'number' === typeof data['status'] ? String(data['status']) : 'pending';
+    return `${method} ${path} ${status}`;
+}
+/** The first line of a console error, capped. */
+function firstLine(data) {
+    const text = ['message', 'text', 'error'].map((k) => data[k]).find((v) => 'string' === typeof v);
+    const line = ('string' === typeof text ? text : 'console error').split('\n')[0] ?? '';
+    return truncate(line);
+}
 export function causalSummary(events, context = {}) {
     let netTotal = 0;
     let netErrors = 0;
     let ignoredDevTooling = 0;
     let headline;
     let consoleErrors = 0;
+    let firstConsoleError;
+    const requests = [];
     const statePathsChanged = [];
     const storageKeysChanged = [];
     const stateDiffs = [];
@@ -72,6 +95,7 @@ export function causalSummary(events, context = {}) {
     const fieldsChanged = [];
     let layoutShift;
     let longTasks = 0;
+    let ignoredBookkeeping = 0;
     for (const event of events) {
         const data = event.data;
         switch (event.type) {
@@ -82,6 +106,7 @@ export function causalSummary(events, context = {}) {
                 }
                 netTotal += 1;
                 const status = data['status'];
+                requests.push(requestLine(data));
                 const failed = false === data['ok'] || ('number' === typeof status && status >= 400);
                 if (failed) {
                     netErrors += 1;
@@ -93,6 +118,7 @@ export function causalSummary(events, context = {}) {
             case EventType.CONSOLE_ERROR:
             case EventType.ERROR_UNCAUGHT:
                 consoleErrors += 1;
+                firstConsoleError ??= firstLine(data);
                 break;
             case EventType.STATE_CHANGE: {
                 pushUnique(statePathsChanged, data['name']);
@@ -103,6 +129,10 @@ export function causalSummary(events, context = {}) {
                 const hasAfter = 'value' in data || 'new' in data;
                 if ('string' === typeof path && path.length > 0 && ('old' in data || hasAfter)) {
                     const after = 'value' in data ? data['value'] : data['new'];
+                    if (isCacheBookkeepingDiff(data['old'], after)) {
+                        ignoredBookkeeping += 1;
+                        break;
+                    }
                     stateDiffs.push({
                         path,
                         from: capValue(data['old']),
@@ -160,9 +190,12 @@ export function causalSummary(events, context = {}) {
             ...(headline === undefined ? {} : { headline }),
         },
         consoleErrors,
+        ...(firstConsoleError === undefined ? {} : { firstConsoleError }),
+        ...(0 === requests.length ? {} : { requests: cap(requests, 'requests', elided) }),
         statePathsChanged: cap(statePathsChanged, 'statePathsChanged', elided),
         storageKeysChanged: cap(storageKeysChanged, 'storageKeysChanged', elided),
         stateDiffs: cap(stateDiffs, 'stateDiffs', elided),
+        ...(0 === ignoredBookkeeping ? {} : { ignoredBookkeeping }),
         ...settle,
         storageDiffs: cap(storageDiffs, 'storageDiffs', elided),
         ...(route === undefined ? {} : { route }),

package/dist/judgement/runs/artifact/build-verification-run.d.ts

@@ -25,7 +25,7 @@ export type VerificationRunInput = Omit<ReticleVerificationRun, 'schemaVersion'
  * reason those two values now survive into the artifact instead of being dropped at its door.
  * Confidence: nothing ran → LOW; an oracle-backed flow or any check ran → HIGH; only smoke → MEDIUM.
  */
-export declare function computeVerdict(input: VerificationRunInput): RunVerdict;
+export declare function computeVerdict(raw: VerificationRunInput): RunVerdict;
 /**
  * Assemble the final, schema-valid ReticleVerificationRun. Stamps schemaVersion + createdAt (injected
  * clock) and computes the verdict; the result is parsed through the protocol schema so a malformed

package/dist/judgement/runs/artifact/build-verification-run.js

@@ -8,6 +8,7 @@
  */
 import { ReticleVerificationRunSchema, RUN_FILE_VERSION, Verified, RunConfidence, RunFlowStatus, VerdictStatus, } from '@reticlehq/core';
 import { redactForProfile } from './profile-redact.js';
+import { supersededChecks } from '@reticlehq/engine/evidence/superseded-checks.js';
 /**
  * Compute the verdict deterministically from the run's flows, checks, and risks.
  * Rules (in order): a gated risk blocks → FAIL; mixed pass+fail → PARTIAL; any fail → FAIL;
@@ -18,11 +19,23 @@ import { redactForProfile } from './profile-redact.js';
  * reason those two values now survive into the artifact instead of being dropped at its door.
  * Confidence: nothing ran → LOW; an oracle-backed flow or any check ran → HIGH; only smoke → MEDIUM.
  */
-export function computeVerdict(input) {
+export function computeVerdict(raw) {
+    // A passive check that read too early is superseded by the same claim holding later: the one
+    // rule every fold applies (superseded-checks.ts).
+    const superseded = supersededChecks(raw.checks.map((c) => ({
+        key: c.predicate,
+        passive: false === c.declaredBeforeActing,
+        held: Verified.YES === c.status,
+        failed: Verified.NO === c.status,
+    })));
+    const input = { ...raw, checks: raw.checks.filter((_, at) => !superseded.has(at)) };
     const passes = input.flows.filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
         .length + input.checks.filter((c) => c.status === Verified.YES).length;
     const fails = input.flows.filter((f) => f.status === RunFlowStatus.FAIL).length +
         input.checks.filter((c) => c.status === Verified.NO).length;
+    const skippedFlows = input.flows.filter((f) => f.status === RunFlowStatus.SKIPPED).length;
+    // Ran and decided nothing, as the agent's own result block counts them: never part of a pass.
+    const undecidedChecks = input.checks.filter((c) => c.status !== Verified.YES && c.status !== Verified.NO).length;
     const blockingRisks = input.risks.filter((r) => r.gated).length;
     const reasons = [];
     for (const f of input.flows) {
@@ -31,6 +44,9 @@ export function computeVerdict(input) {
                 ? `flow ${f.name}: ${f.failureReason}`
                 : `flow ${f.name} failed`);
         }
+        else if (f.status === RunFlowStatus.SKIPPED && f.failureReason !== undefined) {
+            reasons.push(`flow ${f.name}: ${f.failureReason}`);
+        }
     }
     for (const c of input.checks) {
         if (c.status === Verified.NO)
@@ -43,10 +59,16 @@ export function computeVerdict(input) {
     let status;
     if (blockingRisks > 0)
         status = VerdictStatus.FAIL;
-    else if (fails > 0 && passes > 0)
-        status = VerdictStatus.PARTIAL;
+    // A failure beside things that passed is a fail, not a partial: the result block, the CLI and the
+    // platform's grade all call it that, and a "partial" beside "Reticle result: failed" was one run
+    // with two verdicts. A partial is only ever a pass with something skipped or undecided beside it.
     else if (fails > 0)
         status = VerdictStatus.FAIL;
+    else if ((skippedFlows > 0 || undecidedChecks > 0) && passes > 0) {
+        status = VerdictStatus.PARTIAL;
+        if (0 < undecidedChecks)
+            reasons.push(`${String(undecidedChecks)} check(s) undecided`);
+    }
     else if (0 === passes) {
         // Nothing passed and nothing failed, so nothing was proved -- an empty run, or one whose every
         // flow was skipped. Reporting that as PASS is the false green this whole file exists to prevent:

package/dist/judgement/runs/artifact/gap-summary.d.ts

@@ -1,21 +1,3 @@
-/**
- * The gap, as a number the person who ran the session can see.
- *
- * Reticle's whole claim is that it measures the distance between what an agent believed happened
- * and what did. It measures that on every verdict, writes the answer into the journal, and shows it
- * to nobody: the counts exist, the reasons exist, the contradictions exist, and no surface anywhere
- * says "you made 14 claims, 9 held, 2 were false, 3 could not be decided, and here is who owns each
- * of those three". The value of the product is the one thing it never reports.
- *
- * A FOLD over the journal, never a second store — the rule `run-context.ts` next door states, for
- * the same reason: two ways to compute one number is worse than one way, because the day they
- * disagree the disagreement lands inside a verdict and a user finds it before we do.
- *
- * Nothing here sends anything anywhere, and that is deliberate rather than incidental. This is the
- * LOCAL half. Whether a fleet-wide version of the same number is worth collecting is a separate
- * decision with a separate owner, and building the local one first is what makes that decision
- * answerable from something other than a guess.
- */
 import { VerifiedReason, VerdictAttribution, type JournalAction } from '@reticlehq/core';
 /** One claim that did not hold, in the words it was made and the engine's reason for refusing it. */
 export interface GapFailure {

package/dist/judgement/runs/artifact/gap-summary.js

@@ -16,6 +16,7 @@
  * decision with a separate owner, and building the local one first is what makes that decision
  * answerable from something other than a guess.
  */
+import { supersededChecks } from '@reticlehq/engine/evidence/superseded-checks.js';
 import { JournalVerdictEffectSchema, Verified, VerifiedReason, VerdictAttribution, verdictAttributionOf, } from '@reticlehq/core';
 /**
  * The reason, as the engine's own enum, or undefined.
@@ -48,9 +49,17 @@ export function gapSummary(actions) {
         falseGreensCaught: 0,
         failures: [],
     };
-    for (const action of actions) {
-        const verdict = verdictOf(action);
-        if (verdict === undefined)
+    const verdicts = actions.map(verdictOf).filter((v) => v !== undefined);
+    // A passive check that read too early is not counted: the one rule every fold applies
+    // (superseded-checks.ts), so this block and the run's verdict cannot disagree.
+    const superseded = supersededChecks(verdicts.map((v) => ({
+        key: v.claim,
+        passive: false === v.declaredBeforeActing,
+        held: Verified.YES === v.verified,
+        failed: Verified.NO === v.verified,
+    })));
+    for (const [at, verdict] of verdicts.entries()) {
+        if (superseded.has(at))
             continue;
         summary.claims += 1;
         switch (verdict.verified) {

package/dist/judgement/runs/artifact/replay-mapping.d.ts

@@ -5,7 +5,7 @@
  * "why" is lifted from the replay's decision envelope (or its error) into failureReason.
  */
 import { ReplayStatus, RunFlowStatus, type FlowFile, type FlowReplayResult, type RunFlowResult } from '@reticlehq/core';
-/** OK → PASS; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
+/** OK → PASS; UNVERIFIABLE → SKIPPED; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export declare function runFlowStatusOf(status: ReplayStatus): RunFlowStatus;
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
 export declare function mapReplayToFlowResult(replay: FlowReplayResult, durationMs: number, flow?: FlowFile): RunFlowResult;

package/dist/judgement/runs/artifact/replay-mapping.js

@@ -6,9 +6,13 @@
  */
 import { ReplayStatus, RUN_RECORDING_MAX_BYTES, RUN_STEP_RESULTS_MAX, RUN_TEXT_MAX, RunFlowStatus, } from '@reticlehq/core';
 import { SUCCESS_STEP_TOOL } from '../../../language/flows/flow-success.js';
-/** OK → PASS; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
+/** OK → PASS; UNVERIFIABLE → SKIPPED; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export function runFlowStatusOf(status) {
-    return status === ReplayStatus.OK ? RunFlowStatus.PASS : RunFlowStatus.FAIL;
+    if (status === ReplayStatus.OK)
+        return RunFlowStatus.PASS;
+    if (status === ReplayStatus.UNVERIFIABLE)
+        return RunFlowStatus.SKIPPED;
+    return RunFlowStatus.FAIL;
 }
 const clip = (text) => text.length > RUN_TEXT_MAX ? `${text.slice(0, RUN_TEXT_MAX - 1)}…` : text;
 /** One step as synced: what it did, where, and whether it held. */
@@ -37,25 +41,47 @@ function recordingOf(flow) {
         ? { recordingOmitted: true }
         : { recording };
 }
+/** The first contradiction a replay recorded, on a step or across them. */
+function firstContradiction(replay) {
+    for (const step of replay.steps) {
+        const found = step.contradictions?.[0];
+        if (found !== undefined)
+            return found;
+    }
+    return replay.crossStep?.[0];
+}
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
 export function mapReplayToFlowResult(replay, durationMs, flow) {
-    // A replay that could not start returns OK with no steps. Nothing ran, so it is SKIPPED — which
-    // every reader of a run (the verdict, the gate) already refuses to count as a pass.
-    const status = replay.unverifiable === undefined ? runFlowStatusOf(replay.status) : RunFlowStatus.SKIPPED;
+    // A replay that could not start or complete returns UNVERIFIABLE (or carries an unverifiable caveat).
+    // Nothing was verified, so it is SKIPPED — which every reader of a run (the verdict, the gate)
+    // refuses to count as a pass.
+    // A pass whose channels disagreed is the suite's `unverifiable`, and the run says the same: the
+    // CLI printed "unverifiable" and exited 1 while the dashboard listed the run as Passed.
+    const disagreed = replay.status === ReplayStatus.OK ? firstContradiction(replay) : undefined;
+    const status = replay.status === ReplayStatus.UNVERIFIABLE ||
+        replay.unverifiable !== undefined ||
+        disagreed !== undefined
+        ? RunFlowStatus.SKIPPED
+        : runFlowStatusOf(replay.status);
     const failureReason = replay.unverifiable !== undefined
         ? replay.unverifiable.reason
-        : status === RunFlowStatus.FAIL
-            ? (replay.decision?.whatChanged ??
-                replay.decision?.summary ??
-                replay.error?.message ??
-                'flow failed')
-            : undefined;
+        : disagreed !== undefined
+            ? clip(`a channel disagreed (${disagreed.kind}): ${disagreed.counter} — ${disagreed.detail}`)
+            : status === RunFlowStatus.FAIL
+                ? (replay.decision?.whatChanged ??
+                    replay.decision?.summary ??
+                    replay.error?.message ??
+                    'flow failed')
+                : status === RunFlowStatus.SKIPPED
+                    ? 'flow could not be graded'
+                    : undefined;
     // A flow with a success oracle gets a synthetic 'success' step appended by replay; surface its label
     // as the run's `oracle` so the verdict counts this flow as consequence-backed (→ HIGH confidence),
     // not a bare smoke click. Without this, an oracle-backed pass reads as MEDIUM and undersells itself.
     const oracle = replay.steps.find((s) => s.tool === SUCCESS_STEP_TOOL)?.anchor;
     return {
         name: replay.name,
+        ...(flow?.template === undefined ? {} : { template: flow.template }),
         status,
         steps: replay.steps.length,
         durationMs,

package/dist/judgement/runs/artifact/run-store.d.ts

@@ -5,7 +5,7 @@
  * individual run to a deploy. The run is already clock-stamped by buildVerificationRun, so the store
  * needs no clock.
  */
-import { RunReadError, type ReticleVerificationRun, type RunId } from '@reticlehq/core';
+import { RunReadError, type ReticleVerificationRun, type RunId, type RunScreenshot } from '@reticlehq/core';
 import type { FileSystemPort } from '../../../memory/project/fs/fs-port.js';
 /** Never-throws read result (mirrors ReadProjectResult). */
 export type ReadRunResult = {
@@ -38,7 +38,7 @@ export declare class RunStore {
      * Guards runId as a safe path segment BEFORE building the path — a runId can originate from a caller
      * (an OEM may set it), so an unsafe value must never escape .reticle/runs/ (mirrors the read guard).
      */
-    write(run: ReticleVerificationRun): Promise<void>;
+    write(given: ReticleVerificationRun): Promise<void>;
     /** Never throws. Invalid id / missing → MISSING; bad JSON or failed schema → MALFORMED. */
     read(runId: RunId): Promise<ReadRunResult>;
     /** List run ids on disk (filenames minus.json). Empty when the runs dir is absent. */
@@ -51,4 +51,16 @@ export declare class RunStore {
      */
     latestTwo(): Promise<[ReticleVerificationRun, ReticleVerificationRun] | undefined>;
 }
+/** Remember a capture that has not landed yet, so a run written now can wait for it. */
+export declare function noteLanding(dir: string, land: Promise<void>): void;
+/** Wait for this run's screenshots still landing, so a run written now can list them. Bounded. */
+export declare function shotsLanded(root: string, runId: string): Promise<void>;
+/** Every screenshot a run has landed, in the order they were taken (by seq). Never throws. */
+export declare function readStepShots(fs: FileSystemPort, root: string, runId: string): Promise<RunScreenshot[]>;
+/**
+ * The run with its screenshots: every one in `screenshots`, each replayed step's pinned to that
+ * step (matched as `<flow>#<step>`), and each verdict's to its check. Pure. A run with none comes
+ * back unchanged.
+ */
+export declare function withScreenshots(run: ReticleVerificationRun, taken: readonly RunScreenshot[]): ReticleVerificationRun;
 export {};

package/dist/judgement/runs/artifact/run-store.js

@@ -5,11 +5,17 @@
  * individual run to a deploy. The run is already clock-stamped by buildVerificationRun, so the store
  * needs no clock.
  */
-import { asRunId, ReticleVerificationRunSchema, RUN_RETENTION, RUN_RETENTION_SLACK, RunReadError, } from '@reticlehq/core';
-import { reticleDirPaths, isValidRunId, runPath } from '../../../memory/project/dir/reticle-dir.js';
+import { asRunId, ReticleVerificationRunSchema, RUN_RETENTION, RUN_RETENTION_SLACK, RunReadError, RunScreenshotSchema, STEP_SCREENSHOT, } from '@reticlehq/core';
+import { PromptContextSchema } from '@reticlehq/core/artifacts';
+import { reticleDirPaths, isValidRunId, runPath, stepShotDir, } from '../../../memory/project/dir/reticle-dir.js';
+import { join } from 'node:path';
 const JSON_INDENT = 2;
 const JSON_EXT = '.json';
 const TMP_EXT = '.tmp';
+/** A request older than this is about some other task, not the run being written now. */
+const REQUEST_RELEVANT_MS = 6 * 60 * 60 * 1000;
+/** Which run a recorded request was attached to, written into the request file. */
+const REQUEST_RUN_KEY = 'answeredByRun';
 export class RunStore {
     #fs;
     #root;
@@ -28,11 +34,18 @@ export class RunStore {
      * Guards runId as a safe path segment BEFORE building the path — a runId can originate from a caller
      * (an OEM may set it), so an unsafe value must never escape .reticle/runs/ (mirrors the read guard).
      */
-    async write(run) {
+    async write(given) {
+        let run = given;
         if (!isValidRunId(run.runId)) {
             throw new Error(`refusing to write run with unsafe runId: ${JSON.stringify(run.runId)}`);
         }
         await this.#fs.mkdir(reticleDirPaths(this.#root).runs);
+        const context = run.context ?? (await this.#recentRequest(run.createdAt, run.runId));
+        if (context !== undefined)
+            run = { ...run, context };
+        // The step screenshots taken for this run, the last of which may still be landing.
+        await shotsLanded(this.#root, run.runId);
+        run = withScreenshots(run, await readStepShots(this.#fs, this.#root, run.runId));
         // Atomic publish: write a temp file then rename, so a crash mid-write never leaves a half-written
         // artifact (a partial.json would otherwise read back as MALFORMED).
         const path = runPath(this.#root, run.runId);
@@ -49,6 +62,32 @@ export class RunStore {
         }
         await this.#pruneOld();
     }
+    /**
+     * The user's request this run answers, when the agent relayed one recently enough to be about it.
+     * Read from .reticle/intent/request.json (written by `reticle_intent { declare, request }`).
+     */
+    async #recentRequest(at, runId) {
+        try {
+            const path = reticleDirPaths(this.#root).request;
+            const raw = JSON.parse(await this.#fs.readFile(path));
+            const parsed = PromptContextSchema.safeParse(raw);
+            if (!parsed.success)
+                return undefined;
+            const given = parsed.data.at;
+            if (given === undefined || at - given < 0 || REQUEST_RELEVANT_MS < at - given)
+                return undefined;
+            // The first run written for a request answers it; a later run (the next agent session in the
+            // same tab) inherited it and showed a goal it never had. Its own rewrite keeps it.
+            const answeredBy = raw[REQUEST_RUN_KEY];
+            if ('string' === typeof answeredBy)
+                return answeredBy === runId ? parsed.data : undefined;
+            await this.#fs.writeFile(path, `${JSON.stringify({ ...raw, [REQUEST_RUN_KEY]: runId }, null, JSON_INDENT)}\n`);
+            return parsed.data;
+        }
+        catch {
+            return undefined; // no request recorded: the common case
+        }
+    }
     /**
      * Keep .reticle/runs/ bounded. Only acts once the count exceeds RUN_RETENTION + SLACK, then deletes the
      * oldest (by createdAt) back down to RUN_RETENTION — so the read-all is amortized, not per-write.
@@ -148,3 +187,156 @@ export class RunStore {
         return [previous, current];
     }
 }
+/*
+ * A run's step screenshots, as its artifact records them. The images are written beside the run
+ * (`.reticle/visual/runs/<runId>/`) with one record line each in `shots.jsonl` by
+ * `features/visual/step-shots.ts`; this is the reading half.
+ */
+/** How long a run write waits for screenshots still landing. A capture is never worth a stuck run. */
+const LANDING_WAIT_MS = 10_000;
+/** Captures still landing, per run directory. */
+const landing = new Map();
+/** Remember a capture that has not landed yet, so a run written now can wait for it. */
+export function noteLanding(dir, land) {
+    const pending = landing.get(dir) ?? new Set();
+    landing.set(dir, pending);
+    pending.add(land);
+    void land.finally(() => pending.delete(land));
+}
+/** Wait for this run's screenshots still landing, so a run written now can list them. Bounded. */
+export async function shotsLanded(root, runId) {
+    if (!isValidRunId(runId))
+        return;
+    const pending = landing.get(stepShotDir(root, runId));
+    if (pending === undefined || 0 === pending.size)
+        return;
+    let timer;
+    await Promise.race([
+        Promise.allSettled([...pending]),
+        new Promise((resolve) => {
+            timer = setTimeout(resolve, LANDING_WAIT_MS);
+        }),
+    ]);
+    if (timer !== undefined)
+        clearTimeout(timer);
+}
+/** One line of a run's record, read back; anything malformed is skipped. */
+function parseLine(line) {
+    try {
+        const parsed = RunScreenshotSchema.safeParse(JSON.parse(line));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every screenshot a run has landed, in the order they were taken (by seq). Never throws. */
+export async function readStepShots(fs, root, runId) {
+    if (!isValidRunId(runId))
+        return [];
+    try {
+        const text = await fs.readFile(join(stepShotDir(root, runId), STEP_SCREENSHOT.MANIFEST_FILE));
+        return (text
+            .split('\n')
+            .filter((line) => line.length > 0)
+            .map(parseLine)
+            .filter((shot) => shot !== undefined)
+            // In the order they were TAKEN: captures land in whatever order they finish.
+            .sort((a, b) => a.seq - b.seq));
+    }
+    catch {
+        return [];
+    }
+}
+/** The four facts a step records about its picture, out of the run-wide entry. */
+function stepShotOf(shot) {
+    const { file, source, width, height, sha256 } = shot;
+    return { file, source, width, height, sha256 };
+}
+/** An id that occurs once in the list; a repeated one (a reload restarts the count) pairs nothing. */
+function uniqueIds(ids) {
+    const seen = new Map();
+    for (const id of ids)
+        if (id !== undefined)
+            seen.set(id, (seen.get(id) ?? 0) + 1);
+    return new Set([...seen].filter(([, n]) => 1 === n).map(([id]) => id));
+}
+/**
+ * Pair by the journal action each was taken for, when both sides name it. A check that took no
+ * picture (a `steps` call, an answer refused as an error) then costs only its own picture, where the
+ * ordinal pairing below lost every picture in the run.
+ */
+function pairByAction(run, shots) {
+    const verdictShots = shots.filter((shot) => true === shot.verdict && shot.actionId !== undefined);
+    if (0 === verdictShots.length || run.checks.every((check) => check.actionId === undefined))
+        return undefined;
+    const okChecks = uniqueIds(run.checks.map((check) => check.actionId));
+    const okShots = uniqueIds(verdictShots.map((shot) => shot.actionId));
+    const shotOf = new Map(verdictShots.flatMap((shot) => shot.actionId !== undefined && okShots.has(shot.actionId) && okChecks.has(shot.actionId)
+        ? [[shot.actionId, shot]]
+        : []));
+    const checkIdOf = new Map();
+    const checks = run.checks.map((check) => {
+        const shot = check.actionId === undefined ? undefined : shotOf.get(check.actionId);
+        if (shot === undefined)
+            return check;
+        if (check.checkId !== undefined)
+            checkIdOf.set(shot, check.checkId);
+        return { ...check, screenshot: stepShotOf(shot) };
+    });
+    return {
+        checks,
+        shots: shots.map((shot) => {
+            const checkId = checkIdOf.get(shot);
+            return checkId === undefined ? shot : { ...shot, checkId };
+        }),
+    };
+}
+/**
+ * Pair each verdict's picture with the check it produced: the n-th verdict picture is the n-th check,
+ * because both are written in the order the verdicts were given. Only when the counts agree — a
+ * verdict this run did not fold, or one taken while the capture failed, would shift every pairing
+ * after it, and an unpaired picture is better than one shown beside the wrong check.
+ */
+function pairWithChecks(run, shots) {
+    const byAction = pairByAction(run, shots);
+    if (byAction !== undefined)
+        return byAction;
+    const verdictShots = shots.filter((shot) => true === shot.verdict);
+    if (0 === verdictShots.length ||
+        verdictShots.length !== run.checks.length ||
+        run.checks.some((check) => check.checkId === undefined))
+        return { checks: run.checks, shots: [...shots] };
+    const checkIdOf = new Map(verdictShots.map((shot, i) => [shot, run.checks[i]?.checkId]));
+    return {
+        checks: run.checks.map((check, i) => {
+            const shot = verdictShots[i];
+            return shot === undefined ? check : { ...check, screenshot: stepShotOf(shot) };
+        }),
+        shots: shots.map((shot) => {
+            const checkId = checkIdOf.get(shot);
+            return checkId === undefined ? shot : { ...shot, checkId };
+        }),
+    };
+}
+/**
+ * The run with its screenshots: every one in `screenshots`, each replayed step's pinned to that
+ * step (matched as `<flow>#<step>`), and each verdict's to its check. Pure. A run with none comes
+ * back unchanged.
+ */
+export function withScreenshots(run, taken) {
+    if (0 === taken.length)
+        return run;
+    const { checks, shots } = pairWithChecks(run, taken);
+    const byStep = new Map(shots.flatMap((shot) => (shot.step === undefined ? [] : [[shot.step, shot]])));
+    const flows = run.flows.map((flow) => flow.stepResults === undefined
+        ? flow
+        : {
+            ...flow,
+            stepResults: flow.stepResults.map((result) => {
+                const shot = byStep.get(`${flow.name}#${String(result.step)}`);
+                return shot === undefined ? result : { ...result, screenshot: stepShotOf(shot) };
+            }),
+        });
+    return { ...run, checks, flows, screenshots: shots };
+}