scenescout 3.2.0 → 3.4.0

package/dist/engine/browser.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
 import { AUTH_LOSS_PREFIX, JOURNEY_END, JOURNEY_START, MemoryStore, TASK_SET } from "./memory.js";
 import { normalizeTask } from "./task.js";
+import { CLAIM_SCAN_SCRIPT, findContradictions } from "./claims.js";
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
 import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, } from "./collector.js";
@@ -11,6 +12,8 @@ import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
 import { framePath, RECORD_MAX_FRAMES } from "./replay.js";
+import { keepWatchingUrl, normalizePace, SETTLE_TICK_MS, shouldKeepWaiting } from "./settle.js";
+import { buildRequestScript, formatReplay, replaySignature, requestHeaders, resolveMethod, resolveRequestUrl, toReplayResult } from "./request.js";
 import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, } from "../browsers.js";
 import { revealedLines } from "./hover.js";
 import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
@@ -220,6 +223,69 @@ export class BrowserEngine {
     framesKept = 0;
     /** How many frames could not be written. The first one says so in the log; the rest are counted. */
     framesFailed = 0;
+    /**
+     * The Authorization header the app itself last sent, replayed by
+     * scout_request so a call with the UI bypassed carries the same credential
+     * as a click. Nothing here parses it: whatever scheme the app uses is
+     * whatever gets replayed.
+     */
+    lastAuthHeader = null;
+    rememberAuthHeader(headers) {
+        const value = headers["authorization"] ?? headers["Authorization"];
+        if (value && value.trim())
+            this.lastAuthHeader = value;
+    }
+    /**
+     * Call the app's own API as this session, with the UI bypassed.
+     *
+     * The fetch runs IN the page, so it passes through the same interception the
+     * write policy is enforced on: a safe-write session cannot reach past the
+     * policy by calling an endpoint instead of clicking it. The refusal comes
+     * back as the policy's own error, exactly as it would for a click.
+     */
+    async apiRequest(input) {
+        const page = this.requirePage();
+        const method = resolveMethod(input.method);
+        if ("problem" in method)
+            return `REFUSED: ${method.problem}`;
+        const target = resolveRequestUrl(this.baseUrl, input.path);
+        if ("problem" in target)
+            return `REFUSED: ${target.problem}`;
+        const script = buildRequestScript({
+            url: target.url,
+            method: method.method,
+            body: input.body,
+            headers: requestHeaders({ given: input.headers, auth: this.lastAuthHeader, body: input.body }),
+        });
+        let raw;
+        try {
+            raw = (await page.evaluate(script));
+        }
+        catch (err) {
+            // A blocked request rejects the fetch inside the page. That is the write
+            // policy doing its job, not an app fault, and it is reported as such.
+            const message = err instanceof Error ? err.message : String(err);
+            this.logAction({ action: "request", target: `${method.method} ${input.path}`, url: page.url(), result: `blocked: ${message.split("\n")[0]}` });
+            return `${method.method} ${input.path} — the request did not complete: ${message.split("\n")[0]}\nIn a write-limited mode this is usually the policy refusing it, which is the engine's safety net and not a finding about the app.`;
+        }
+        const result = toReplayResult(raw);
+        this.logAction({
+            action: "request",
+            target: `${method.method} ${input.path}`,
+            url: page.url(),
+            result: replaySignature(method.method, result.url, result.status),
+        });
+        return formatReplay(method.method, result);
+    }
+    /**
+     * The frame field for a log entry, or nothing. Spread into logAction so a
+     * caller that is not going through afterAction can still record what the
+     * page looked like: `...(await this.frameFor("crawl"))`.
+     */
+    async frameFor(action) {
+        const frame = await this.recordFrame(action);
+        return frame ? { frame } : {};
+    }
     /**
      * The frame for the step just taken, as a path relative to the memory
      * directory, or undefined when this run is not recorded. Failing to write
@@ -266,16 +332,26 @@ export class BrowserEngine {
      * until it is replaced — a batch costs a few words, not one per click.
      */
     currentTask = null;
-    /** Set what this session is doing now. An empty value clears it. */
-    setTask(text) {
+    /**
+     * Set what this session is doing now. An empty value clears it.
+     *
+     * `stated` is false for the placeholder attach puts up so a fresh card is
+     * not blank. It shows on the board but does NOT satisfy the requirement that
+     * an agent say what it is doing before it acts — otherwise every session
+     * would run for an hour under "Attaching and taking stock", which is the
+     * guard's whole purpose defeated by its own convenience.
+     */
+    setTask(text, stated = true) {
         const clean = normalizeTask(text);
         if (!clean) {
             this.currentTask = null;
             return;
         }
-        if (this.currentTask?.text === clean)
+        if (this.currentTask?.text === clean && this.currentTask.stated === stated)
+            return;
+        this.currentTask = { text: clean, since: Date.now(), stated };
+        if (!stated)
             return;
-        this.currentTask = { text: clean, since: Date.now() };
         // Logged so the feed can group the actions that follow under it, the way
         // it groups a journey's — the trail is where a watcher reads what
         // happened, and an ungrouped one says nothing about why.
@@ -283,7 +359,7 @@ export class BrowserEngine {
     }
     /** Whether anything is standing that the live view could show as the task. */
     get hasTask() {
-        return this.journey !== null || this.currentTask !== null;
+        return this.journey !== null || (this.currentTask?.stated ?? false);
     }
     /**
      * Begin measuring a user JOURNEY — the interaction cost of completing one
@@ -333,6 +409,15 @@ export class BrowserEngine {
     engineName = "chromium";
     /** Non-GET requests fired since the last action — surfaces silent state mutation in read-only runs (timestamped for attribution). */
     mutationRequests = [];
+    /**
+     * Every request answered since the last action, with its status. The HTTP
+     * oracle sees each 4xx as it happens and reports it on its own; this ledger
+     * exists so the contradiction rules can ask the DIFFERENT question of whether
+     * the page then agreed with the refusal. Capped, because a page that polls
+     * would otherwise grow it without bound.
+     */
+    watchedResponses = [];
+    static MAX_WATCHED_RESPONSES = 60;
     /**
      * Requests the write policy aborted, by identity. The request event fires for
      * every non-GET the page ATTEMPTS, before the route handler decides its fate,
@@ -374,6 +459,52 @@ export class BrowserEngine {
      * element on the current page? Runs wherever violations are drained, so the
      * finding reaches the agent in the result of the action that revealed it.
      */
+    /** Record one answered request for the contradiction rules. Policy-aborted ones are marked, never dropped: the rules need to know they were ours. */
+    watchResponse(req, status) {
+        if (this.watchedResponses.length >= BrowserEngine.MAX_WATCHED_RESPONSES)
+            return;
+        this.watchedResponses.push({
+            method: req.method(),
+            url: req.url(),
+            status,
+            resourceType: req.resourceType(),
+            blockedByPolicy: this.abortedByPolicy.has(req),
+        });
+    }
+    /**
+     * Did the page agree with what the network just did? Runs in the same slot
+     * as the injection scan, so it sees the DOM the action settled on.
+     *
+     * The ledger is cleared whether or not anything is found: these are facts
+     * about ONE action, and carrying a refusal forward would blame the next
+     * action's page for the previous action's request.
+     */
+    async scanForContradictions() {
+        const requests = this.watchedResponses;
+        this.watchedResponses = [];
+        const page = this.page;
+        if (!page || page.isClosed() || requests.length === 0)
+            return;
+        if (!requests.some((r) => r.status === null || r.status >= 400))
+            return;
+        const url = page.url();
+        let state;
+        try {
+            state = (await page.evaluate(CLAIM_SCAN_SCRIPT));
+        }
+        catch {
+            // A page mid-navigation has no DOM to ask.
+            return;
+        }
+        for (const found of findContradictions(requests, state)) {
+            if (this.contradictionsReported.has(found.evidence))
+                continue;
+            this.contradictionsReported.add(found.evidence);
+            this.oracles.noteContradiction(found, url);
+        }
+    }
+    /** Contradiction signatures already reported this session — the same refused endpoint on every page must not flood the run. */
+    contradictionsReported = new Set();
     async scanForInjections() {
         const page = this.page;
         if (!page || page.isClosed() || this.probes.length === 0)
@@ -406,6 +537,9 @@ export class BrowserEngine {
         }
         this.mode = opts.mode ?? "read-only";
         this.sessionObjective = (opts.objective ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
+        // An agent-supplied task counts as stated; the placeholder does not.
+        this.setTask(opts.task ?? "Attaching and taking stock", opts.task !== undefined);
+        this.setPace(opts.paceMs);
         this.recording = opts.record === true;
         // A re-attached engine starts a new recording: numbering from where the
         // last one stopped would run into the cap with frames it never took.
@@ -413,6 +547,8 @@ export class BrowserEngine {
         this.framesFailed = 0;
         this.headed = opts.headed ?? false;
         this.blockedRequests = [];
+        this.watchedResponses = [];
+        this.contradictionsReported = new Set();
         this.pendingCreations = new Set();
         this.baseUrl = opts.url.replace(/\/$/, "");
         // Ownership (ownedIds/createdResources) deliberately NOT reset here: it
@@ -476,7 +612,19 @@ export class BrowserEngine {
         if (this.page)
             watchSockets(this.page);
         this.context.on("page", watchSockets);
+        this.context.on("requestfinished", () => {
+            this.inFlight = Math.max(0, this.inFlight - 1);
+        });
+        this.context.on("requestfailed", (req) => {
+            this.inFlight = Math.max(0, this.inFlight - 1);
+            this.watchResponse(req, null);
+        });
+        this.context.on("response", (res) => {
+            this.watchResponse(res.request(), res.status());
+        });
         this.context.on("request", (req) => {
+            this.inFlight += 1;
+            this.lastRequestStart = Date.now();
             const type = req.resourceType();
             if (type === "xhr" || type === "fetch")
                 this.xhrCount += 1;
@@ -522,6 +670,7 @@ export class BrowserEngine {
                     return route.continue();
                 const url = req.url();
                 const pathname = pathnameOf(url);
+                this.rememberAuthHeader(req.headers());
                 const destructiveWire = isDestructiveWire(pathname, req.postData());
                 // Auth/session flows must work in every mode — but never a destructive
                 // one, and in observe only the requests a login itself needs.
@@ -615,17 +764,30 @@ export class BrowserEngine {
         // is all this used to do — reads as success and names the very file that
         // just failed, so a run would proceed for hundreds of calls against a
         // logged-out browser. The file existing was the only thing ever checked.
-        const authFailed = Boolean(opts.storageStatePath) && this.authLoss.isLoginRedirect(normalizePath(opts.url), this.page.url(), this.baseUrl);
+        // Whether a bounce verdict can matter later: only a session carrying
+        // credentials has any to lose, and only it pays for watching the URL on
+        // every navigation. An anonymous crawl keeps its full speed.
+        this.watchesForBounce = Boolean(opts.storageStatePath);
+        const landed = await this.stableUrl();
+        const authFailed = Boolean(opts.storageStatePath) && this.authLoss.isLoginRedirect(normalizePath(opts.url), landed, this.baseUrl);
+        // An earlier run may have written down how this app's login state is
+        // regenerated. "Regenerate it" is advice the reader already had; the
+        // command that worked last time is the part worth keeping.
+        const recipe = authFailed ? this.memory.setupRecipe() : [];
         const authWarning = authFailed
             ? `\n⚠ AUTH FAILED — the storage state at ${opts.storageStatePath} did not produce a signed-in session: ` +
-                `attaching landed on ${this.page.url()}, a login page. Regenerate it (its token has most likely expired) and re-attach. ` +
-                `Continuing now tests a logged-out app.`
+                `attaching landed on ${landed}, a login page. Regenerate it (its token has most likely expired) and re-attach. ` +
+                `Continuing now tests a logged-out app.` +
+                (recipe.length > 0
+                    ? `\n  Recorded by an earlier run under setup:\n${recipe.map((line) => `    · ${line}`).join("\n")}`
+                    : `\n  Nothing is recorded about how this app's login state is made. Once the user tells you, write it down with scout_note { section: "setup" } so the next run is told instead of asking.`)
             : "";
         return (`Attached to ${this.page.url()} (mode=${this.mode}` +
             `${this.engineName === "chromium" ? "" : `, browser=${this.engineName}, service workers blocked because their requests cannot be intercepted here`}` +
             `${focusAdvanceKey(this.engineName, process.platform) === "Tab" ? "" : `, keyboard: Tab stops only at text fields in this browser — press Alt+Tab to reach buttons and links`}` +
             `${opts.storageStatePath ? `, auth=${opts.storageStatePath}` : ""}). ` +
             `Memory: ${this.memory.dir}.${this.memory.loadWarning ? ` WARNING: ${this.memory.loadWarning}` : ""}` +
+            (this.memory.prunedStates > 0 ? ` Trimmed ${this.memory.prunedStates} old page state(s) from the history; coverage is unchanged.` : "") +
             `${this.memory.legacyDirNote ? ` ${this.memory.legacyDirNote}` : ""}` +
             `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""} Call scout_snapshot to see the current state.` +
             authWarning);
@@ -651,11 +813,80 @@ export class BrowserEngine {
     async settle() {
         const page = this.requirePage();
         await page.waitForLoadState("domcontentloaded").catch(() => { });
-        // A fixed floor, deliberately: waitForLoadState("networkidle") is latched
-        // once reached and resolves instantly forever after, so it cannot be used
-        // to wait out in-flight requests here — and draining oracles before a
-        // just-fired request lands would misattribute its violations.
-        await page.waitForTimeout(SETTLE_MS);
+        // Wait on what is actually in flight rather than a flat sleep. The rule is
+        // in settle.ts so it can be table-tested; the reasoning for not using
+        // networkidle is there too.
+        const started = Date.now();
+        for (;;) {
+            const state = {
+                inFlight: this.inFlight,
+                sinceLastStartMs: Date.now() - this.lastRequestStart,
+                elapsedMs: Date.now() - started,
+                paceMs: this.paceMs,
+            };
+            if (!shouldKeepWaiting(state))
+                return;
+            await page.waitForTimeout(SETTLE_TICK_MS).catch(() => { });
+            if (this.page !== page)
+                return;
+        }
+    }
+    /**
+     * The URL once it has stopped changing.
+     *
+     * Only called where a bounce verdict is about to be made. A client-side auth
+     * guard redirects on a timer and issues no request until it does, so the
+     * request-based settle has nothing to wait on and the page is read while it
+     * is still, briefly, the page it was asked for.
+     */
+    async stableUrl() {
+        const page = this.page;
+        if (!page || page.isClosed())
+            return page ? page.url() : "";
+        const started = Date.now();
+        let url = page.url();
+        let changedAt = started;
+        for (;;) {
+            if (!keepWatchingUrl({ sinceChangeMs: Date.now() - changedAt, elapsedMs: Date.now() - started }))
+                return url;
+            await page.waitForTimeout(SETTLE_TICK_MS).catch(() => { });
+            if (this.page !== page || page.isClosed())
+                return url;
+            const now = page.url();
+            if (now !== url) {
+                url = now;
+                changedAt = Date.now();
+            }
+        }
+    }
+    /**
+     * Where a navigation landed. Watched for a late client-side guard only when
+     * this session has credentials to lose. The page is passed in rather than
+     * read off the engine so a session torn down mid-navigation still reports
+     * the last URL it was on, which is what the outcome is recorded against.
+     */
+    async landedUrl(page) {
+        return this.watchesForBounce ? await this.stableUrl() : page.url();
+    }
+    /** Set at attach: this session was given credentials, so a bounce to a login page is a verdict worth waiting for. */
+    watchesForBounce = false;
+    /** Requests started and not yet finished or failed, from the context's own events. */
+    inFlight = 0;
+    /** When the most recent request started, so a page that fires one late is not read too early. */
+    lastRequestStart = 0;
+    /**
+     * A floor between actions this session was asked for, so a person watching
+     * can follow along. Zero means as fast as the page allows, which is the
+     * default and what every run wants unless somebody is reading it live.
+     */
+    paceMs = 0;
+    /** Set the deliberate pace. Returns what it became, clamped. */
+    setPace(paceMs) {
+        this.paceMs = normalizePace(paceMs);
+        return this.paceMs;
+    }
+    get pace() {
+        return this.paceMs;
     }
     /** Collect the current page's interactables into SnapshotElements with stable refs. */
     async collect() {
@@ -788,8 +1019,13 @@ export class BrowserEngine {
         this.currentFingerprint = fp;
         const isNew = memory.visitState(fp, url, route, elements.map((el) => el.key));
         memory.recordRoleAccess(this.role, route, "reached");
-        this.logAction({ action: "snapshot", url, result: fp });
+        // A snapshot is what an agent takes when it wants to LOOK at something, so
+        // it is the frame a reader most wants beside the step. Recording only the
+        // actions that go through afterAction kept 9 frames out of 67 in a real
+        // run, and none of them from the routes a crawl had just swept.
+        this.logAction({ action: "snapshot", url, result: fp, ...(await this.frameFor("snapshot")) });
         await this.scanForInjections();
+        await this.scanForContradictions();
         const line = (el) => {
             const dup = el.key.match(/~(\d+)$/);
             const flags = [
@@ -949,6 +1185,7 @@ export class BrowserEngine {
         const frame = await this.recordFrame(action);
         this.logAction({ action, target, url, ...(frame ? { frame } : {}) });
         await this.scanForInjections();
+        await this.scanForContradictions();
         const violations = this.oracles.drain();
         const mutations = this.drainMutations() + this.drainBlocked() + this.drainCreated();
         const navigated = this.snapshotUrl !== "" && url !== this.snapshotUrl;
@@ -1639,14 +1876,14 @@ export class BrowserEngine {
             settled = await this.afterAction("navigate", url);
         }
         catch (err) {
-            this.recordNavigationOutcome(url, page.url());
+            this.recordNavigationOutcome(url, await this.landedUrl(page));
             const notice = this.authLoss.take();
             if (!notice)
                 throw err;
             const msg = err instanceof Error ? err.message : String(err);
             throw new Error(`${notice}${msg}`);
         }
-        this.recordNavigationOutcome(url, page.url());
+        this.recordNavigationOutcome(url, await this.landedUrl(page));
         return this.authLoss.take() + settled;
     }
     /** Where did we ASK to go, where did we END UP, and does that count as coverage? */
@@ -1767,8 +2004,9 @@ export class BrowserEngine {
             // an attempt with the status satisfies the contract.
             if (typeof status === "number" && status >= 400)
                 memory.markAttempted(requestedRoute, `status:${status}`, this.role);
-            this.logAction({ action: "crawl", target: path, url: finalUrl });
+            this.logAction({ action: "crawl", target: path, url: finalUrl, ...(await this.frameFor("crawl")) });
             await this.scanForInjections();
+            await this.scanForContradictions();
             const violations = this.oracles.drain();
             const deadEnd = elements.length === 0;
             const unnamed = elements.filter((el) => !el.name).length;
@@ -1940,7 +2178,11 @@ export class BrowserEngine {
                     }
                 }
                 await this.settle();
-                this.logAction({ action: `plan:${step.action}`, target: step.target ?? step.value, url: page.url() });
+                // A plan is the RECOMMENDED way to run a mechanical sequence, so its
+                // steps are where most of a recorded run actually happens. Leaving
+                // them unframed reproduced, inside run_plan, the same hole that crawl
+                // had: a form filled and submitted with no picture of any of it.
+                this.logAction({ action: `plan:${step.action}`, target: step.target ?? step.value, url: page.url(), ...(await this.frameFor(`plan-${step.action}`)) });
                 // Plans must feed coverage like ref-based actions do: record the
                 // state and mark the acted-on element class as exercised.
                 // Hover is deliberately excluded: a hover is a look, not an
@@ -1985,6 +2227,7 @@ export class BrowserEngine {
                     }
                 }
                 await this.scanForInjections();
+                await this.scanForContradictions();
                 const violations = this.oracles.drain();
                 const mutations = this.drainMutations() + this.drainBlocked() + this.drainCreated();
                 // Abort only on NEW violations: a known-failing endpoint repeating on
@@ -2048,7 +2291,7 @@ export class BrowserEngine {
             this.memory?.setPageScore(route, { ...score, at: new Date().toISOString(), url: page.url() });
             this.memory?.markRouteFact(route, { audited: true });
         }
-        this.logAction({ action: "design-audit", url: page.url(), result: score ? `score:${score.overall}` : undefined });
+        this.logAction({ action: "design-audit", url: page.url(), result: score ? `score:${score.overall}` : undefined, ...(await this.frameFor("design-audit")) });
         return `URL: ${page.url()}\n` + report;
     }
     /**

package/dist/engine/calibration.js

@@ -0,0 +1,217 @@
+/**
+ * Whether a lane's confidence means anything.
+ *
+ * `lane.ts` tells every lane its confidence must be calibrated — "0.5 means a
+ * coin flip, 0.95 means you would bet on it" — and then the number was
+ * averaged into one line and thrown away. Nothing was stored, so nothing could
+ * ever be checked, and a confidence nobody checks is decoration. Decision-only
+ * models report an expected calibration error for exactly this reason; asking
+ * for calibration without measuring it is the half of the idea that costs
+ * nothing and buys nothing.
+ *
+ * WHAT THIS MEASURES, precisely, because the number is easy to over-read: a
+ * lane says "defect" about an observation and attaches a machine signature.
+ * The run either went on to file a finding carrying that signature or it did
+ * not. That is agreement between the lane and the bar the run actually
+ * applied — NOT ground truth about the app. A lane can be perfectly calibrated
+ * against a planner that files the wrong things. Where a finding has since
+ * been re-tested through `scout_verify`, the verdict is reported beside it,
+ * and that IS evidence about the app.
+ *
+ * Pure, so every rule here is table-tested.
+ */
+import { failingSignatures } from "./memory.js";
+/**
+ * Upper edge of each confidence bucket. Five is enough to see a shape and few
+ * enough that each holds a usable count on a run of a few dozen decisions;
+ * twenty buckets of one decision each measure nothing.
+ */
+export const BUCKET_EDGES = [0.2, 0.4, 0.6, 0.8, 1.0];
+/**
+ * Which bucket a confidence falls in. The top bucket is closed so 1.0 has
+ * somewhere to go.
+ *
+ * A value that is not a number lands in the LOWEST bucket, not the highest.
+ * The schema refuses those, but stored history is read back without one, and
+ * falling through the comparisons put a NaN in the 0.8–1.0 bucket — a
+ * confidence nobody stated, reported as near-certainty.
+ */
+export function bucketOf(confidence) {
+    if (!Number.isFinite(confidence))
+        return 0;
+    const c = Math.min(1, Math.max(0, confidence));
+    for (let i = 0; i < BUCKET_EDGES.length; i += 1) {
+        if (c <= BUCKET_EDGES[i])
+            return i;
+    }
+    return BUCKET_EDGES.length - 1;
+}
+export function bucketLabel(i) {
+    const low = i === 0 ? 0 : BUCKET_EDGES[i - 1];
+    return `${low.toFixed(1)}–${BUCKET_EDGES[i].toFixed(1)}`;
+}
+/**
+ * The keys a piece of evidence can be joined on, or nothing when it cannot be
+ * joined at all.
+ *
+ * Findings MERGE: the store treats `GET /api/things/3 500` and
+ * `GET /api/things/7 500` as one bug, because the path normalises to
+ * `/api/things/:id`. Joining on the literal string reported five lane
+ * decisions about one endpoint as one filed and four dropped — the lanes
+ * understated fivefold, and the number read as a finding about them rather
+ * than a bug in this join. So the join uses the store's own rule.
+ *
+ * Evidence carrying no failure signature returns NOTHING rather than falling
+ * back to its literal text. That fallback looked harmless and was the single
+ * worst thing here: `500 on GET /api/r0` — ordinary English, and whichever
+ * agent wrote the finding chose the word order — produced a key that matched
+ * nothing, and a lane that was right about a bug that WAS filed published an
+ * expected calibration error of 0.90. An unjoinable decision is now counted
+ * and disclosed as unjoinable, not scored as a lane being wrong.
+ */
+export function joinKeys(evidence) {
+    return failingSignatures(evidence);
+}
+/** A confidence as stored may be anything; the schema guards the wire, not the file. */
+function usableConfidence(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1 ? value : null;
+}
+/**
+ * Join lane decisions to what the run filed.
+ *
+ * Only a "defect" carrying a signature has a checkable outcome. An "unsure" is
+ * a request to look closer rather than a claim, and a decision with no
+ * signature cannot be joined to anything — counting either would measure the
+ * lane's willingness to attach evidence, not its judgement.
+ */
+export function calibrate(decisions, findings) {
+    const filedKeys = new Map();
+    for (const f of findings) {
+        if (!f.evidence)
+            continue;
+        // A finding verified as still present is the most informative match, so it
+        // wins a key two findings share; otherwise first write wins and the result
+        // does not depend on the order findings came back in.
+        for (const key of joinKeys(f.evidence)) {
+            const prev = filedKeys.get(key);
+            if (!prev || (f.verdict && f.verifiedAt && !(prev.verdict && prev.verifiedAt)))
+                filedKeys.set(key, f);
+        }
+    }
+    const claims = decisions.filter((d) => d.verdict === "defect" && d.evidence !== null);
+    const checkable = claims.filter((d) => usableConfidence(d.confidence) !== null && joinKeys(d.evidence).size > 0);
+    const unjoinable = claims.length - checkable.length;
+    if (checkable.length === 0)
+        return unjoinable > 0 ? { checkable: 0, filed: 0, stated: 0, buckets: [], ece: 0, verified: { present: 0, gone: 0, changed: 0 }, unjoinable } : null;
+    const buckets = BUCKET_EDGES.map(() => ({ n: 0, conf: 0, hits: 0 }));
+    const verified = { present: 0, gone: 0, changed: 0 };
+    const matched = new Map();
+    let filed = 0;
+    let stated = 0;
+    for (const d of checkable) {
+        let match;
+        for (const key of joinKeys(d.evidence)) {
+            match = filedKeys.get(key);
+            if (match)
+                break;
+        }
+        const hit = match !== undefined;
+        const confidence = usableConfidence(d.confidence);
+        const b = buckets[bucketOf(confidence)];
+        b.n += 1;
+        b.conf += confidence;
+        if (hit)
+            b.hits += 1;
+        if (hit)
+            filed += 1;
+        stated += confidence;
+        // By finding, not by decision: several decisions can match one finding,
+        // and this sentence counts findings.
+        if (match)
+            matched.set(match.id, match);
+    }
+    for (const f of matched.values()) {
+        // A verdict read from disk is not guaranteed to be one of the three.
+        if (f.verifiedAt && f.verdict && f.verdict in verified)
+            verified[f.verdict] += 1;
+    }
+    const n = checkable.length;
+    let ece = 0;
+    const out = [];
+    buckets.forEach((b, i) => {
+        if (b.n === 0)
+            return;
+        const meanConf = b.conf / b.n;
+        const rate = b.hits / b.n;
+        ece += (b.n / n) * Math.abs(meanConf - rate);
+        out.push({ label: bucketLabel(i), decisions: b.n, stated: meanConf, filed: rate });
+    });
+    return { checkable: n, filed, stated: stated / n, buckets: out, ece, verified, unjoinable };
+}
+const pct = (x) => `${Math.round(x * 100)}%`;
+/**
+ * The report section. It leads with what the number is not, because "ECE 0.24"
+ * above a table of percentages reads as a verdict on the app rather than on
+ * the lanes that judged it.
+ */
+export function formatCalibration(c) {
+    if (!c)
+        return [];
+    if (c.checkable < MIN_FOR_A_VERDICT) {
+        // Suppress the NUMBER, not the fact. A run that recorded seven decisions
+        // and a run that recorded none look identical when the section simply
+        // vanishes, and the reader concludes the feature is broken — which is this
+        // project's own definition of a silent path.
+        const had = c.checkable + c.unjoinable;
+        if (had === 0)
+            return [];
+        return [
+            `## How well the lanes judged`,
+            ``,
+            `Not enough to say yet: ${c.checkable} lane decision(s) could be checked${c.unjoinable > 0 ? ` (and ${c.unjoinable} could not be looked up at all)` : ""}, ` +
+                `and ${MIN_FOR_A_VERDICT} are needed before a calibration figure survives one of them changing.`,
+            ``,
+        ];
+    }
+    const lines = [
+        `## How well the lanes judged`,
+        ``,
+        `${c.checkable} lane decision(s) called a defect on an endpoint that failed; ${c.filed} of them match a finding this project holds (${pct(c.filed / c.checkable)}), ` +
+            `against a mean stated confidence of ${c.stated.toFixed(2)}.`,
+        ``,
+        `**What this is not.** It covers the project's whole history, not this run, and it measures agreement between the lanes and the bar this project applies — not whether the app is broken. ` +
+            `A lane can be perfectly calibrated against a planner that files the wrong things. Two things also count against a lane through no fault of its own: a defect filed with no machine signature, ` +
+            `and a finding whose signature was dropped when the store merged it into another. Read the figure as an ordering, not a measurement.`,
+        ``,
+        `| Stated confidence | Decisions | Said | Filed |`,
+        `|---|---:|---:|---:|`,
+    ];
+    for (const b of c.buckets) {
+        lines.push(`| ${b.label} | ${b.decisions} | ${b.stated.toFixed(2)} | ${pct(b.filed)} |`);
+    }
+    lines.push(``, `Expected calibration error **${c.ece.toFixed(2)}** — the gap between what the lanes said and what happened, weighted by bucket. ${readEce(c.ece)}`);
+    if (c.unjoinable > 0) {
+        lines.push(``, `${c.unjoinable} further decision(s) called a defect but named no failing endpoint, so nothing could be looked up for them. They are excluded above rather than counted as wrong.`);
+    }
+    const seen = c.verified.present + c.verified.gone + c.verified.changed;
+    if (seen > 0) {
+        lines.push(``, `${seen} of the findings those decisions matched ${seen === 1 ? "has" : "have"} since been re-tested with \`scout_verify\`: ${c.verified.present} still present, ${c.verified.gone} gone, ${c.verified.changed} changed. ` +
+            `Those verdicts are evidence about the app, unlike the table above. Findings no lane decision matched are not counted here, so this will not agree with the re-tested column elsewhere in the report.`);
+    }
+    lines.push(``);
+    return lines;
+}
+/** Below this, the number swings on a single decision and is worse than no number. */
+export const MIN_FOR_A_VERDICT = 8;
+/**
+ * What the figure suggests, hedged on purpose. The join loses decisions it
+ * cannot key and findings whose signature a merge discarded, and both push the
+ * error upward — so a confident "these numbers are wrong" can itself be wrong.
+ */
+function readEce(ece) {
+    if (ece <= 0.05)
+        return "The lanes' numbers track what happened closely.";
+    if (ece <= 0.15)
+        return "Close enough to compare lanes by.";
+    return "Far enough apart that a lane's confidence is worth reading as an ordering rather than a rate — after checking the exclusions above, which push this upward.";
+}