@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/setup/findings.js

@@ -0,0 +1,948 @@
+// The SCAN FINDINGS STORE (spec "Findings"): every finding
+// a scan has reported, keyed by its fingerprint — file + lens + kind + a hash
+// of the anchored code, whitespace-normalised (scan.ts findingFingerprint).
+//
+// Recognition across re-scans is two steps, and only the second
+// costs judgement:
+//
+//   * EXACT MATCH FIRST. A finding whose fingerprint is already stored is the
+//     same finding: its last sighting and wording are refreshed, and its
+//     state — `new`, `promoted`, `dismissed` — is kept, so nothing is ever
+//     triaged twice. (A `fixed` finding seen again has come back: it is
+//     `new` again — or still `promoted` while its ticket is open.)
+//   * THE COMPANION JUDGES THE REST. After a run, `reconcile` finds the
+//     stored findings the re-scan no longer reports: their file was read
+//     again at other content — the content the run's tree holds (the ledger
+//     says so) — and no exact match came back, or their file is gone from
+//     the tree. One that no fresh finding of a lens that raised it (in its
+//     unit, or of its kind) could possibly be is
+//     `fixed` at once. The rest are held with those fresh candidates in ONE
+//     pending MATCH QUESTION, which the companion answers whole (`match`,
+//     quoting the question's key): the pairs it names are the same finding —
+//     the old one keeps its state and history and takes the new wording,
+//     position and fingerprint (the old fingerprint kept as an alias) — and
+//     every old finding it did not pair is `fixed`. Nothing is ever fixed on
+//     a guess, and nothing waits on the companion that an exact rule settles.
+//   * A DISMISSAL IS STICKY. The operator's triage is never
+//     overwritten by a scan: a dismissed finding every rule above would fix
+//     stays `dismissed`, stamped `unreported` (the run and sha) for audit, and
+//     is out of play until a scan reports it again — which clears the stamp
+//     and keeps the dismissal (no scan reopens it; the operator's promote is
+//     the only way out). One settle, `settleUnreported`, serves every path.
+//     A legacy store's finding fixed FROM dismissed reads back as dismissed
+//     (scanreport.ts `parseFindingsFile`).
+//   * `fixed` NEEDS CHANGED CONTENT. Only a re-read of OTHER
+//     content can settle a finding fixed. A later reading of the SAME content
+//     it was last seen at that does not report it again (a narrower stage-2
+//     row, a re-run — model variance) leaves it open and stamps
+//     `not_reproduced`: how many such readings, and the latest — once per
+//     reading, cleared by the next sighting. Triage can still dismiss it; a
+//     promoted one's ticket stays open, because only `fixed` closes one.
+//   * `fixed` RECORDS WHERE. The run and sha that stopped reporting it, and
+//     the state it was fixed from — what a promoted finding's ticket is
+//     closed with.
+//   * "MAY NOT BE VALID" IS A FLAG, NOT A STATE. A finding the validator
+//     doubted is stored with its `doubt` (word and reason) and shown as such;
+//     a finding no validator looked at is `validated: false`. Neither is
+//     dropped.
+//   * EVERY JUDGED FINDING HAS A VALIDITY TIER (the scan validator is the
+//     skeptic). `confirmed` — the skeptic traced a concrete
+//     scenario (kept in `scenario`); `likely` — a real mechanism whose
+//     reachability it could not trace all the way; `doubtful` — refuted,
+//     class-matched, or anything it would have killed, carried in `doubt`
+//     (word, reason, and the false-positive class when one matched). A
+//     finding no skeptic judged — the validator off or failed, or stored
+//     before tiers existed — has none and reads as UNKNOWN (scanreport.ts
+//     `validityOf`), never a guessed tier. The tier travels with the finding
+//     through an exact match (the latest JUDGED sighting wins — an unjudged
+//     re-sighting of the same code keeps the judgement it has), an alias and
+//     a near-duplicate fold (the best-supported sighting wins, and the doubt
+//     follows the tier it chose, so a finding never reads doubtful with no
+//     reason nor confirmed while flagged "may not be valid").
+//   * Individual findings never become memory (spec "Scan memory") — this
+//     store is the PC-side record, in the state home, never shipped.
+//   * TRIAGE (triage.ts drives it): a DISMISSED finding carries its
+//     reason and whether its memory note was written; a PROMOTED one carries
+//     its TICKET — where it was filed (the issue tracker or a markdown file)
+//     and, once a re-scan found it fixed, when that ticket was closed. The
+//     ticket record is what makes a finding never filed twice: it survives a
+//     match (the new fingerprint inherits it), a fix and a return.
+//   * NEAR-DUPLICATES COLLAPSE. The fingerprint hashes the lens
+//     and the anchored code, so one defect raised by two lenses — or by two
+//     rows of one lens anchored a few lines apart — arrives under two
+//     fingerprints. A fresh finding (no exact or alias match) that is the
+//     same file, the same kind, within NEAR_LINES of a live finding the SAME
+//     run sighted and says the same thing (`nearDuplicate`: same subject, stemmed token
+//     overlap at CLAIM_SIMILARITY) is folded into it: the stored one keeps
+//     its identity, wording and triage, takes the higher severity, lists the
+//     lens in `lenses`, the absorbed sighting in `merged`, and its
+//     fingerprint in `aliases` — so the next run's exact match, triage by
+//     fingerprint and ticket stamps all still find it. Deterministic and
+//     deliberately under-merging: different kinds, far ranges, different
+//     subjects, a fixed finding or one the match question holds never fold,
+//     and a later run's look-alike of an older sighting is the companion's
+//     match question, never a fold. `reconcile` runs the same fold once more
+//     over the run's fresh findings (`collapseRun`), for a duplicate whose
+//     case ran before the sighting it duplicates. A collapsed finding's
+//     severity is the highest its sightings' LATEST reports give, and it is
+//     unreported (fixed, or put to the match question) only once every lens
+//     that raised it has re-read other content.
+//
+// Persistence: `<state home>/scan/findings.json`. An unreadable store is
+// reported and refuses writes, like the ledger and the unit cut.
+import { createHash } from "node:crypto";
+import { readings } from "./ledger.js";
+import { SEVERITIES } from "./scan.js";
+import { FINDING_STATES, FINDINGS_FILE, FINDINGS_VERSION, VALIDITY_ORDER, dismissedLookalike, goneDismissal, lookalikeRank, parseFindingsFile, validityOf, } from "./scanreport.js";
+export { FINDINGS_FILE, FINDINGS_VERSION, dismissedLookalike, lookalikeRank };
+export { FINDING_STATES };
+// ---- near-duplicate collapse ----
+/** How far apart (lines between the two ranges) two sightings of one defect
+ * may be anchored — one real pair sat 81 lines apart. */
+export const NEAR_LINES = 100;
+/** The stemmed-token Jaccard two claims must reach to be one defect. */
+export const CLAIM_SIMILARITY = 0.4;
+const STOPWORDS = new Set(("the a an of to in on at is are be by for and or not than rather but its it this that with from as into instead " +
+    "being has have was were can could may when which while every only their them then there these those does did do").split(" "));
+/** A claim's content tokens, in order: lower-cased words of 3+ characters,
+ * stopwords out, each stemmed to its first five characters (so
+ * authorization/authority, validate/validation, refresh/refreshed agree;
+ * words of five characters or fewer stay whole, so read/reads do not). */
+function claimStems(claim) {
+    return (claim.toLowerCase().match(/[a-z0-9]+/g) ?? [])
+        .filter((w) => w.length >= 3 && !STOPWORDS.has(w))
+        .map((w) => w.slice(0, 5));
+}
+/** Most severe first: `SEVERITIES`' own order. */
+const severityRank = (s) => SEVERITIES.indexOf(s);
+const higher = (a, b) => severityRank(b) < severityRank(a) ? b : a;
+/**
+ * Are `a` and `b` the same defect reported twice? Same file, same kind,
+ * ranges overlapping or at most NEAR_LINES apart, the same subject (first
+ * content stem — "Inline-comment reads…" and "Issue-comment reads…" are one
+ * pattern in two places, not one defect) and claims whose stemmed tokens
+ * overlap at CLAIM_SIMILARITY or more. Pure; symmetric.
+ */
+export function nearDuplicate(a, b) {
+    if (a.path !== b.path || a.kind !== b.kind)
+        return false;
+    const gap = Math.max(a.start, b.start) - Math.min(a.end, b.end);
+    if (gap > NEAR_LINES)
+        return false;
+    const sa = claimStems(a.claim);
+    const sb = claimStems(b.claim);
+    if (sa.length === 0 || sb.length === 0 || sa[0] !== sb[0])
+        return false;
+    const A = new Set(sa);
+    const B = new Set(sb);
+    let common = 0;
+    for (const t of A)
+        if (B.has(t))
+            common++;
+    return common / (A.size + B.size - common) >= CLAIM_SIMILARITY;
+}
+/**
+ * The dismissed finding `r` resembles, and why it was dismissed — or null.
+ * The dedup's own test (`nearDuplicate`) against every DISMISSED finding,
+ * its own sighting and each near-duplicate collapsed into it, first in
+ * store order. A new finding's wording can shift between runs, so an exact
+ * fingerprint never catches a re-raise of what the operator already
+ * dismissed; this says so. It decides nothing: the caller only flags.
+ */
+function resemblingDismissal(stored, r) {
+    for (const d of stored) {
+        if (d.state !== "dismissed" || d.fingerprint === r.fingerprint)
+            continue;
+        const sightings = [d, ...(d.merged ?? []).map((m) => ({ ...m, path: d.path, kind: d.kind }))];
+        if (sightings.some((s) => nearDuplicate(s, r))) {
+            return { fingerprint: d.fingerprint, reason: d.dismissal?.reason ?? "(no reason recorded)" };
+        }
+    }
+    return null;
+}
+/** A validated survivor with no doubt, of the two, clears the flag. */
+function combinedDoubt(a, b) {
+    if ((a.validated && a.doubt === null) || (b.validated && b.doubt === null))
+        return null;
+    return a.doubt ?? b.doubt;
+}
+/** Better supported ranks higher — the display order (confirmed first,
+ * unknown last) read backwards. */
+const validityRank = (v) => VALIDITY_ORDER.length - VALIDITY_ORDER.indexOf(v);
+/** Two sightings of one defect: the best-supported tier wins (a confirmed
+ * sighting outranks a doubt, as a clean survivor clears the doubt flag), and
+ * its scenario with it. Unknown only when neither was judged. */
+function combinedValidity(a, b) {
+    const best = validityRank(validityOf(b)) > validityRank(validityOf(a)) ? b : a;
+    const v = validityOf(best);
+    return { validity: v === "unknown" ? null : v, scenario: best.scenario ?? null };
+}
+/** The doubt and tier of two sightings, told as ONE story: when either was
+ * tiered, the tier decides and the doubt follows it (a doubtful tier keeps
+ * its doubt, a confirmed/likely one clears it) — so a finding never reads
+ * doubtful with no reason, nor confirmed while flagged "may not be valid".
+ * With no tier on either side, the pre-tier doubt rule stands. */
+function combinedJudgement(a, b) {
+    const tiered = combinedValidity(a, b);
+    if (tiered.validity === null || tiered.validity === undefined)
+        return { doubt: combinedDoubt(a, b), ...tiered };
+    if (tiered.validity !== "doubtful")
+        return { doubt: null, ...tiered };
+    // Neither side ranks above doubtful here, so at least one IS doubtful.
+    const src = validityOf(b) === "doubtful" ? b : a;
+    return { doubt: src.doubt ?? a.doubt ?? b.doubt, ...tiered };
+}
+/** A sighting nobody judged (the skeptic off or failed) says nothing about
+ * the finding's validity: an exact re-sighting of the SAME code keeps the
+ * judgement it already has rather than dropping a confirmed tier — or a
+ * doubt — to unknown. Any judged sighting replaces it (the latest wins). */
+function judgementOf(known, r) {
+    if (r.validated || validityOf(r) !== "unknown") {
+        return {
+            validated: r.validated,
+            doubt: r.doubt,
+            validity: r.validity ?? null,
+            scenario: r.scenario ?? null,
+        };
+    }
+    return {
+        validated: known.validated,
+        doubt: known.doubt,
+        validity: known.validity ?? null,
+        scenario: known.scenario ?? null,
+    };
+}
+/** Can a fresh near-duplicate fold into `f`? Only a live finding this very
+ * run has sighted — a sighting in a LATER run that merely resembles an old
+ * one is the companion's match question, never a silent fold —
+ * and never one the pending question holds. */
+function collapsible(f, run, held) {
+    return f.state !== "fixed" && f.last_seen.run === run && !held.has(f.fingerprint);
+}
+/** Fold stored finding `f` (fresh this run) into `into`, its own collapsed
+ * sightings and aliases with it. `f` becomes a sighting at ITS OWN latest
+ * severity — its aggregate already counts the sightings folded into it,
+ * which come along as their own merged entries, so a later re-sighting of
+ * one of them can still lower the whole. */
+function absorbFinding(into, f) {
+    const once = absorb(into, { ...f, ...f.own_judgement, severity: f.own_severity ?? f.severity });
+    const merged = [
+        ...once.merged,
+        ...(f.merged ?? []).filter((m) => !once.merged.some((x) => x.fingerprint === m.fingerprint)),
+    ];
+    return {
+        ...once,
+        severity: aggregateSeverity(once.own_severity, merged),
+        ...aggregateJudgements(once.own_judgement ?? judgementOf(once, once), merged),
+        lenses: [...new Set([...once.lenses, ...(f.lenses ?? [])])],
+        merged,
+        aliases: [...new Set([...once.aliases, ...(f.aliases ?? [])])],
+    };
+}
+/**
+ * The end-of-run pass: a finding first seen this run, untriaged, that is a
+ * near-duplicate of another finding this run sighted folds into it — what
+ * report-time collapse misses when the duplicate's case ran before the
+ * sighting it duplicates. Mutates `byFp`; returns how many folded.
+ */
+function collapseRun(byFp, run, held) {
+    let folded = 0;
+    const all = [...byFp.values()];
+    for (const f of all) {
+        if (!byFp.has(f.fingerprint))
+            continue;
+        const fresh = f.state === "new" &&
+            f.first_seen.run === run &&
+            !f.ticket &&
+            !f.dismissal &&
+            !held.has(f.fingerprint);
+        if (!fresh)
+            continue;
+        const into = [...byFp.values()].find((o) => o.fingerprint !== f.fingerprint && collapsible(o, run, held) && nearDuplicate(o, f));
+        if (!into)
+            continue;
+        const cur = byFp.get(f.fingerprint);
+        byFp.delete(f.fingerprint);
+        byFp.set(into.fingerprint, absorbFinding(into, cur));
+        folded++;
+    }
+    return folded;
+}
+function sightingOf(r) {
+    return {
+        fingerprint: r.fingerprint,
+        lens: r.lens,
+        start: r.start,
+        end: r.end,
+        severity: r.severity,
+        claim: r.claim,
+        validated: r.validated,
+        doubt: r.doubt,
+        validity: r.validity ?? null,
+        scenario: r.scenario ?? null,
+    };
+}
+function aggregateJudgements(own, merged) {
+    return merged.reduce((current, sighting) => {
+        if (sighting.validated === undefined)
+            return current;
+        const next = {
+            validated: sighting.validated,
+            doubt: sighting.doubt ?? null,
+            validity: sighting.validity ?? null,
+            scenario: sighting.scenario ?? null,
+        };
+        return { validated: current.validated || next.validated, ...combinedJudgement(current, next) };
+    }, own);
+}
+/** The highest of a finding's own latest severity and each merged
+ * sighting's latest. */
+function aggregateSeverity(own, merged) {
+    return merged.reduce((s, m) => higher(s, m.severity), own);
+}
+/** Fold reported near-duplicate `r` into stored `into`. It is a sighting at
+ * the content `r` read, so the content hash moves with it. */
+function absorb(into, r) {
+    const lenses = [...new Set([...lensesOf(into), r.lens])];
+    const merged = [
+        ...(into.merged ?? []).filter((m) => m.fingerprint !== r.fingerprint),
+        sightingOf({
+            ...r,
+            ...judgementOf((into.merged ?? []).find((m) => m.fingerprint === r.fingerprint && m.validated !== undefined) ?? { validated: false, doubt: null }, r),
+        }),
+    ];
+    const ownJudgement = into.own_judgement ?? judgementOf(into, into);
+    // Before anything collapsed into it, its severity IS its own; a record
+    // stored before `own_severity` existed falls back to its aggregate.
+    const own = into.own_severity ?? into.severity;
+    return {
+        ...into,
+        ...(r.blob !== undefined ? { blob: r.blob } : {}),
+        own_severity: own,
+        severity: aggregateSeverity(own, merged),
+        own_judgement: ownJudgement,
+        ...aggregateJudgements(ownJudgement, merged),
+        lenses,
+        merged,
+        aliases: [...new Set([...(into.aliases ?? []), r.fingerprint])],
+    };
+}
+/** Every lens that raised `f` — a collapsed finding's all of them. */
+const lensesOf = (f) => f.lenses ?? [f.lens];
+/** Do `a` and `b` share a lens that raised them? */
+function shareLens(a, b) {
+    const la = lensesOf(a);
+    return lensesOf(b).some((l) => la.includes(l));
+}
+/** Could fresh finding `n` be old finding `o`, moved or reworded? A lens in
+ * common (any lens a collapsed finding holds — its silent primary lens is
+ * not the only one that can report it again), and the same unit or the
+ * same kind. */
+function mightBe(o, n) {
+    return shareLens(o, n) && (o.unit === n.unit || o.kind === n.kind);
+}
+/** The state a `fixed` finding takes when a scan reports it again: promoted
+ * stays promoted while its ticket is still open (nothing closed it yet);
+ * anything else, including a promoted one whose ticket was closed, is `new`
+ * again — the ticket record stays, so a re-promote never files twice.
+ * (A dismissed finding is never fixed at all — `settleUnreported`.) */
+function returnedState(f) {
+    if (f.fixed?.from === "promoted" && f.ticket && !f.ticket.closed)
+        return "promoted";
+    return "new";
+}
+export { goneDismissal } from "./scanreport.js";
+/** Is `f` already settled — fixed, or a gone dismissal? A settled finding is
+ * out of play until a scan reports it again. */
+export const settled = (f) => f.state === "fixed" || goneDismissal(f);
+/**
+ * Settle a finding a re-scan no longer reports — the ONE place every path
+ * (reconcile, a report that shrinks the question, the companion's match)
+ * settles one. A DISMISSED finding stays dismissed (a re-scan never
+ * overwrites the operator's triage), stamped `unreported` for audit;
+ * any other becomes `fixed` (a promoted one's ticket then closes).
+ * `null` when there was nothing to settle.
+ */
+function settleUnreported(f, at) {
+    if (f.state === "fixed" || settled(f))
+        return null;
+    const where = { run: at.run, sha: at.sha, at: at.at };
+    if (f.state === "dismissed")
+        return { finding: { ...f, unreported: where, not_reproduced: null }, as: "dismissed" };
+    return {
+        finding: {
+            ...f,
+            state: "fixed",
+            fixed: { ...where, from: f.state },
+            unreported: null,
+            not_reproduced: null,
+        },
+        as: "fixed",
+    };
+}
+/** The question over `unreported` × `fresh`, or null when nothing waits. */
+function questionOf(unreported, fresh, at) {
+    if (unreported.length === 0)
+        return null;
+    const u = [...new Set(unreported)].sort();
+    const f = [...new Set(fresh)].sort();
+    const key = createHash("sha256")
+        .update(JSON.stringify({ u, f, run: at.run }))
+        .digest("hex")
+        .slice(0, 16);
+    return { key, run: at.run, sha: at.sha, at: at.at, unreported: u, fresh: f };
+}
+/**
+ * Settle a question's two sides against `byFp`: an old finding with no
+ * fresh candidate left is fixed now; a fresh one no old finding could be
+ * leaves the question (it is simply new). Mutates `byFp`; returns the
+ * question that still waits and how many it fixed.
+ */
+function settleQuestion(byFp, unreported, fresh, at) {
+    const live = (fp) => {
+        const f = byFp.get(fp);
+        return f && !settled(f) ? f : null;
+    };
+    const olds = [...new Set(unreported)].map(live).filter((f) => f !== null);
+    const oldSet = new Set(olds.map((f) => f.fingerprint));
+    const news = [...new Set(fresh)]
+        .map(live)
+        .filter((f) => f !== null && !oldSet.has(f.fingerprint));
+    let fixed = 0;
+    let dismissed = 0;
+    const waiting = [];
+    for (const o of olds) {
+        if (news.some((n) => mightBe(o, n)))
+            waiting.push(o.fingerprint);
+        else {
+            const s = settleUnreported(o, at);
+            byFp.set(o.fingerprint, s.finding);
+            if (s.as === "fixed")
+                fixed++;
+            else
+                dismissed++;
+        }
+    }
+    const held = olds.filter((o) => waiting.includes(o.fingerprint));
+    const candidates = news.filter((n) => held.some((o) => mightBe(o, n))).map((n) => n.fingerprint);
+    return { question: questionOf(waiting, candidates, at), fixed, dismissed };
+}
+/** The lines each lens raised `f` at: its own anchor for its own lens, and
+ * each collapsed sighting's for that sighting's lens. A lens with no sighting
+ * of its own (one a match carried over) answers for the finding's anchor. */
+function sightingsByLens(f) {
+    const out = [{ lens: f.lens, start: f.start, end: f.end }];
+    for (const m of f.merged ?? [])
+        out.push({ lens: m.lens, start: m.start, end: m.end });
+    for (const lens of lensesOf(f))
+        if (!out.some((o) => o.lens === lens))
+            out.push({ lens, start: f.start, end: f.end });
+    return out;
+}
+/**
+ * The latest reading that re-read `f`'s lines at the very content it was
+ * last seen at, by another run since, with EVERY lens that raised it — and
+ * did not report it (a reading that did would have moved its last sighting).
+ * Null when some lens has no such row. A ranged row counts only when its
+ * range holds the lines THAT lens raised it at — a collapsed sighting's own
+ * lines, not the finding's anchor.
+ */
+function silentReread(f, rows, current) {
+    if (f.blob == null || (current !== undefined && current !== f.blob))
+        return null;
+    let latest = null;
+    for (const s of sightingsByLens(f)) {
+        let best = null;
+        for (const r of rows) {
+            if (r.lens !== s.lens || r.path !== f.path || r.blob !== f.blob)
+                continue;
+            if (r.run === f.last_seen.run || r.at < f.last_seen.at)
+                continue;
+            if (r.range && (r.range.start > s.start || r.range.end < s.end))
+                continue;
+            if (best === null || r.at > best.at)
+                best = r;
+        }
+        if (best === null)
+            return null;
+        if (latest === null || best.at > latest.at)
+            latest = best;
+    }
+    return latest;
+}
+export class FindingsStore {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    loadFile() {
+        const empty = { version: FINDINGS_VERSION, findings: [], question: null };
+        let text;
+        try {
+            text = this.state.read(FINDINGS_FILE);
+        }
+        catch (err) {
+            return {
+                file: empty,
+                error: `${FINDINGS_FILE} in ${this.state.location} cannot be read: ${String(err)}`,
+            };
+        }
+        if (text === null)
+            return { file: empty, error: null };
+        try {
+            return { file: parseFindingsFile(text), error: null };
+        }
+        catch (err) {
+            return {
+                file: empty,
+                error: `${FINDINGS_FILE} in ${this.state.location} is not a findings store this version reads (${String(err)}) — ` +
+                    "nothing will overwrite it; move it aside to start over",
+            };
+        }
+    }
+    write(findings, question) {
+        const file = { version: FINDINGS_VERSION, findings: [...findings], question };
+        this.state.write(FINDINGS_FILE, `${JSON.stringify(file, null, 1)}\n`);
+    }
+    load() {
+        const { file, error } = this.loadFile();
+        return { findings: file.findings, error };
+    }
+    /**
+     * Record what one case reported. Exact fingerprint match first: a known
+     * finding keeps its state and first sighting; an unknown one is `new`.
+     * A known finding the pending match question held as unreported has been
+     * reported again, so it leaves the question. An unknown one that is a
+     * near-duplicate of a stored live finding is collapsed into it
+     * (`nearDuplicate`). Returns how many were new, how many matched (by
+     * fingerprint or alias) and how many were collapsed. Throws when the stored file cannot be read — never
+     * writes over it.
+     */
+    report(reported, seen) {
+        const { file, error } = this.loadFile();
+        if (error !== null)
+            throw new Error(error);
+        const byFp = new Map(file.findings.map((f) => [f.fingerprint, f]));
+        // Every alias names the finding that carries it: an absorbed
+        // near-duplicate's fingerprint, and a fingerprint the finding had before
+        // the companion matched it to a moved or reworded sighting.
+        const aliasOf = new Map();
+        for (const f of file.findings) {
+            for (const a of f.aliases ?? [])
+                aliasOf.set(a, f.fingerprint);
+            for (const a of f.merged ?? [])
+                aliasOf.set(a.fingerprint, f.fingerprint);
+        }
+        const held = new Set(file.question?.unreported ?? []);
+        let added = 0;
+        let matched = 0;
+        let merged = 0;
+        const back = new Set();
+        for (const r of reported) {
+            const ownFp = byFp.has(r.fingerprint) ? r.fingerprint : aliasOf.get(r.fingerprint);
+            const known = ownFp === undefined ? undefined : byFp.get(ownFp);
+            if (known && ownFp !== undefined) {
+                // The same sighting twice (one case reporting a duplicate) counts once.
+                const again = known.last_seen.run === seen.run && known.last_seen.sha === seen.sha;
+                const state = known.state === "fixed" ? returnedState(known) : known.state;
+                const history = {
+                    state,
+                    fixed: null,
+                    unreported: null,
+                    not_reproduced: null,
+                    first_seen: known.first_seen,
+                    last_seen: seen,
+                    seen: again ? known.seen : known.seen + 1,
+                };
+                if (!(known.merged ?? []).some((m) => m.fingerprint === r.fingerprint)) {
+                    // Its own fingerprint, or one it carried before a match: a sighting
+                    // of the finding itself, stored under the identity it already has.
+                    // A collapsed finding carries the highest severity its sightings now
+                    // give — its own latest and each absorbed one's latest, never a
+                    // stale maximum a re-scan has since lowered.
+                    const severity = aggregateSeverity(r.severity, known.merged ?? []);
+                    const ownJudgement = judgementOf(known.own_judgement ?? known, r);
+                    byFp.set(ownFp, {
+                        ...known,
+                        ...r,
+                        fingerprint: ownFp,
+                        ...aggregateJudgements(ownJudgement, known.merged ?? []),
+                        severity,
+                        ...(known.merged ? { own_severity: r.severity, own_judgement: ownJudgement } : {}),
+                        ...history,
+                    });
+                }
+                else {
+                    // A sighting of an absorbed near-duplicate: the finding keeps its own
+                    // wording and position; the alias's record and the severity move.
+                    byFp.set(ownFp, { ...absorb(known, r), ...history });
+                }
+                // An untriaged finding's resemblance is re-read at every sighting: a
+                // dismissal made (or undone) since is reflected, never a stale flag.
+                const now = byFp.get(ownFp);
+                if (now.state === "new") {
+                    const { resembles_dismissed: _was, ...rest } = now;
+                    const lookalike = resemblingDismissal(byFp.values(), now);
+                    byFp.set(ownFp, lookalike ? { ...rest, resembles_dismissed: lookalike } : rest);
+                }
+                back.add(ownFp);
+                matched++;
+                continue;
+            }
+            const twin = [...byFp.values()].find((f) => collapsible(f, seen.run, held) && nearDuplicate(f, r));
+            if (twin) {
+                byFp.set(twin.fingerprint, absorb(twin, r));
+                aliasOf.set(r.fingerprint, twin.fingerprint);
+                merged++;
+            }
+            else {
+                const lookalike = resemblingDismissal(byFp.values(), r);
+                byFp.set(r.fingerprint, {
+                    ...r,
+                    state: "new",
+                    first_seen: seen,
+                    last_seen: seen,
+                    seen: 1,
+                    ...(lookalike ? { resembles_dismissed: lookalike } : {}),
+                });
+                added++;
+            }
+        }
+        let question = file.question ?? null;
+        if (question !== null && question.unreported.some((fp) => back.has(fp))) {
+            const q = question;
+            question = settleQuestion(byFp, q.unreported.filter((fp) => !back.has(fp)), q.fresh, { run: q.run, sha: q.sha, at: q.at }).question;
+        }
+        this.write(byFp.values(), question);
+        return { added, matched, merged };
+    }
+    /**
+     * After a run: find the stored findings a re-scan no longer reports and
+     * settle what an exact rule can. A finding is UNREPORTED when its file is
+     * gone from the run's tree, or when the ledger's newest row for its lens
+     * and file is a later run's reading of other content — so a run the
+     * companion never finished is still counted by the next one. Unreported
+     * findings with no possible fresh counterpart are fixed now; the rest join
+     * the one pending match question, with the fresh findings (first seen by
+     * the runs that re-read those files) that might be them.
+     */
+    reconcile(args) {
+        const { file, error } = this.loadFile();
+        if (error !== null)
+            throw new Error(error);
+        const byFp = new Map(file.findings.map((f) => [f.fingerprint, f]));
+        // Each file's newest reading per lens — only a COMPLETE one: a file read
+        // in line ranges whose ranges are not all back yet has not been re-read,
+        // and the findings in its unread ranges must not read as fixed.
+        const newest = new Map();
+        for (const lens of new Set(args.rows.map((r) => r.lens))) {
+            for (const [path, r] of readings(args.rows, lens))
+                if (r.complete)
+                    newest.set(`${lens}\0${path}`, r);
+        }
+        const prior = file.question ?? null;
+        collapseRun(byFp, args.run.run, new Set([...(prior?.unreported ?? []), ...(prior?.fresh ?? [])]));
+        const pending = new Set((prior?.unreported ?? []).filter((fp) => {
+            const finding = byFp.get(fp);
+            const current = finding ? args.blobs?.get(finding.path) : undefined;
+            return current === undefined || finding?.blob == null || current !== finding.blob;
+        }));
+        const rereadBy = new Set([args.run.run]);
+        const unreported = [];
+        let notReproduced = 0;
+        for (const f of [...byFp.values()]) {
+            if (settled(f) || pending.has(f.fingerprint))
+                continue;
+            if (!args.tree.has(f.path)) {
+                unreported.push(f.fingerprint);
+                // Wherever it moved may have been read by a run the companion never
+                // finished: every run of its lenses since its last sighting is one
+                // whose fresh findings might be it.
+                const lenses = lensesOf(f);
+                for (const r of args.rows) {
+                    if (r.run !== f.last_seen.run && r.at >= f.last_seen.at && lenses.includes(r.lens))
+                        rereadBy.add(r.run);
+                }
+                continue;
+            }
+            const current = args.blobs?.get(f.path);
+            // A collapsed finding is unreported only when EVERY lens that raised
+            // it has re-read other content since — one lens's silence is not the
+            // other's, and a single-lens run must not settle what it never read.
+            const readingsOf = lensesOf(f).map((l) => newest.get(`${l}\0${f.path}`));
+            const reread = readingsOf.every((reading) => {
+                const row = reading?.newest;
+                return (row !== undefined &&
+                    row.run !== f.last_seen.run &&
+                    row.at >= f.last_seen.at &&
+                    !(f.blob != null && row.blob === f.blob) &&
+                    (current === undefined || row.blob === current));
+            });
+            if (!reread) {
+                // Only OTHER content can have fixed it: a later reading of
+                // the content it was last seen at, over its lines, that did not
+                // report it again is not a fix — it stays open, stamped, once per
+                // reading. A dismissed one is already triaged: nothing to stamp or
+                // count (the count asks for triage).
+                const silent = f.state === "dismissed" ? null : silentReread(f, args.rows, current);
+                if (silent !== null && !(f.not_reproduced && f.not_reproduced.at >= silent.at)) {
+                    byFp.set(f.fingerprint, {
+                        ...f,
+                        not_reproduced: {
+                            run: silent.run,
+                            sha: silent.sha,
+                            at: silent.at,
+                            count: (f.not_reproduced?.count ?? 0) + 1,
+                        },
+                    });
+                    notReproduced++;
+                }
+                continue;
+            }
+            unreported.push(f.fingerprint);
+            // Every run of each reading re-read the file: a ranged reading finished
+            // by a later run keeps the earlier run's findings as candidates.
+            for (const reading of readingsOf)
+                for (const r of reading.runs)
+                    rereadBy.add(r);
+        }
+        const fresh = [...byFp.values()]
+            .filter((f) => f.state !== "fixed" && rereadBy.has(f.first_seen.run))
+            .map((f) => f.fingerprint);
+        const at = args.run;
+        const settledNow = settleQuestion(byFp, [...pending, ...unreported], [...(prior?.fresh ?? []), ...fresh], at);
+        // A run that changed nothing about the question leaves it as it was: its
+        // key must not move under a companion that is judging it right now.
+        const same = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+        const question = prior !== null &&
+            settledNow.question !== null &&
+            same(settledNow.question.unreported, prior.unreported) &&
+            same(settledNow.question.fresh, prior.fresh)
+            ? prior
+            : settledNow.question;
+        this.write(byFp.values(), question);
+        return {
+            fixed: settledNow.fixed,
+            pending: settledNow.question?.unreported.length ?? 0,
+            not_reproduced: notReproduced,
+            dismissed_unreported: settledNow.dismissed,
+        };
+    }
+    /** The pending match question with both sides expanded, or null. */
+    question() {
+        const { file, error } = this.loadFile();
+        const q = file.question ?? null;
+        if (q === null)
+            return { question: null, error };
+        const byFp = new Map(file.findings.map((f) => [f.fingerprint, f]));
+        const expand = (fps) => fps.map((fp) => byFp.get(fp)).filter((f) => f !== undefined);
+        return {
+            question: {
+                key: q.key,
+                run: q.run,
+                sha: q.sha,
+                unreported: expand(q.unreported),
+                fresh: expand(q.fresh),
+            },
+            error,
+        };
+    }
+    /**
+     * The companion's answer to the pending question, whole: `pairs` are the
+     * same finding (one-to-one, a lens in common); every unreported finding it does
+     * not pair is fixed; every fresh one it does not pair stays new. Refused —
+     * all of it — on a stale key, an unknown fingerprint, a reused one, a
+     * lens mismatch, or a pair whose two sides carry different tickets.
+     */
+    match(args) {
+        const { file, error } = this.loadFile();
+        if (error !== null)
+            return { ok: false, errors: [error] };
+        const q = file.question ?? null;
+        if (q === null)
+            return { ok: false, errors: ["no match question is pending — nothing to judge"] };
+        if (args.key !== q.key) {
+            return {
+                ok: false,
+                errors: [
+                    `the question moved since you read it (key ${String(args.key)}, now ${q.key}) — read it again`,
+                ],
+            };
+        }
+        if (args.pairs !== undefined && !Array.isArray(args.pairs))
+            return { ok: false, errors: ["`pairs` must be a list of {old, new}"] };
+        const byFp = new Map(file.findings.map((f) => [f.fingerprint, f]));
+        const pairs = [];
+        const errors = [];
+        const usedOld = new Set();
+        const usedNew = new Set();
+        for (const raw of (args.pairs ?? [])) {
+            const p = raw;
+            const o = typeof p?.old === "string" ? p.old : "";
+            const n = typeof p?.new === "string" ? p.new : "";
+            if (!q.unreported.includes(o))
+                errors.push(`${JSON.stringify(o)} is not an unreported finding of this question`);
+            else if (usedOld.has(o))
+                errors.push(`${o.slice(0, 12)} is paired twice`);
+            if (!q.fresh.includes(n))
+                errors.push(`${JSON.stringify(n)} is not a fresh finding of this question`);
+            else if (usedNew.has(n))
+                errors.push(`${n.slice(0, 12)} is paired twice`);
+            const of = byFp.get(o);
+            const nf = byFp.get(n);
+            if (of && nf && !shareLens(of, nf))
+                errors.push(`${o.slice(0, 12)} and ${n.slice(0, 12)} are different lenses' findings`);
+            // Each side's ticket is a filed work item: a pair that would keep only
+            // one of two different tickets would orphan the other.
+            else if (of?.ticket && nf?.ticket && of.ticket.ref !== nf.ticket.ref) {
+                errors.push(`${o.slice(0, 12)} (${of.ticket.ref}) and ${n.slice(0, 12)} (${nf.ticket.ref}) each carry their own ticket — pairing would orphan one; leave them unpaired (the old one then settles as fixed and its ticket closes, the fresh one keeps its own)`);
+            }
+            usedOld.add(o);
+            usedNew.add(n);
+            pairs.push({ old: o, new: n });
+        }
+        if (errors.length > 0)
+            return { ok: false, errors };
+        const at = { run: q.run, sha: q.sha, at: q.at };
+        let matched = 0;
+        for (const { old, new: nfp } of pairs) {
+            const o = byFp.get(old);
+            const n = byFp.get(nfp);
+            if (!o || !n)
+                continue;
+            byFp.delete(old);
+            // The triage travels with the finding: a matched promoted finding
+            // keeps its ticket (never filed twice), a dismissed one its reason —
+            // and a fresh one promoted or dismissed while the question waited
+            // keeps its own when the old side has none.
+            const triaged = o.ticket ? o : n.ticket ? n : o.dismissal ? o : n.dismissal ? n : o;
+            // The sightings each side had collapsed come along, and the severity is
+            // the highest of the fresh finding's own and theirs — the invariant a
+            // report keeps, never the fresh record's alone.
+            const merged = o.merged || n.merged ? [...(o.merged ?? []), ...(n.merged ?? [])] : null;
+            const own = n.own_severity ?? n.severity;
+            const ownJudgement = n.own_judgement ?? judgementOf(n, n);
+            byFp.set(nfp, {
+                ...n,
+                ...(merged
+                    ? {
+                        own_severity: own,
+                        severity: aggregateSeverity(own, merged),
+                        own_judgement: ownJudgement,
+                        ...aggregateJudgements(ownJudgement, merged),
+                    }
+                    : {}),
+                state: triaged.state,
+                fixed: null,
+                first_seen: o.first_seen,
+                seen: o.seen + n.seen,
+                aliases: [...new Set([...(o.aliases ?? []), old, ...(n.aliases ?? [])])],
+                ...(o.lenses || n.lenses ? { lenses: [...new Set([...lensesOf(o), ...lensesOf(n)])] } : {}),
+                ...(merged ? { merged } : {}),
+                dismissal: o.dismissal ?? n.dismissal ?? null,
+                ticket: triaged.ticket ?? null,
+            });
+            matched++;
+        }
+        let fixed = 0;
+        let dismissed = 0;
+        for (const fp of q.unreported) {
+            if (usedOld.has(fp))
+                continue;
+            const f = byFp.get(fp);
+            const s = f ? settleUnreported(f, at) : null;
+            if (s) {
+                byFp.set(fp, s.finding);
+                if (s.as === "fixed")
+                    fixed++;
+                else
+                    dismissed++;
+            }
+        }
+        this.write(byFp.values(), null);
+        return {
+            ok: true,
+            matched,
+            fixed,
+            new: q.fresh.filter((fp) => !usedNew.has(fp)).length,
+            dismissed_unreported: dismissed,
+        };
+    }
+    /** The stored findings the filter keeps, most severe first — a finding
+     * flagged as resembling a dismissed one below the rest of its severity —
+     * then by file. */
+    list(filter = {}) {
+        const { findings, error } = this.load();
+        const rank = severityRank;
+        const kept = findings
+            .filter((f) => (filter.state === undefined || f.state === filter.state) &&
+            (filter.lens === undefined ||
+                f.lens === filter.lens ||
+                (f.lenses ?? []).includes(filter.lens)) &&
+            (filter.unit === undefined || f.unit === filter.unit) &&
+            (filter.severity === undefined || f.severity === filter.severity) &&
+            (filter.doubted === undefined || (f.doubt !== null) === filter.doubted) &&
+            (filter.validity === undefined || validityOf(f) === filter.validity))
+            .sort((a, b) => rank(a.severity) - rank(b.severity) ||
+            lookalikeRank(a) - lookalikeRank(b) ||
+            (a.path < b.path ? -1 : a.path > b.path ? 1 : a.start - b.start));
+        return { findings: kept, error };
+    }
+    // -- triage (the rules are triage.ts's, the record is here) --
+    /**
+     * The one stored finding `ref` names: a full fingerprint, an alias (a
+     * fingerprint it carried before a match), or an unambiguous prefix of at
+     * least 12 hex characters — what `scan_findings` shows.
+     */
+    find(ref) {
+        const { findings, error } = this.load();
+        if (error !== null)
+            return { ok: false, errors: [error] };
+        const want = ref.trim().toLowerCase();
+        if (!/^[0-9a-f]{12,64}$/.test(want))
+            return {
+                ok: false,
+                errors: [`${JSON.stringify(ref)} is not a fingerprint (12+ hex characters)`],
+            };
+        const exact = findings.find((f) => f.fingerprint === want || (f.aliases ?? []).includes(want));
+        if (exact)
+            return { ok: true, finding: exact };
+        const hits = findings.filter((f) => f.fingerprint.startsWith(want) || (f.aliases ?? []).some((a) => a.startsWith(want)));
+        if (hits.length === 1)
+            return { ok: true, finding: hits[0] };
+        return {
+            ok: false,
+            errors: [
+                hits.length === 0
+                    ? `no stored finding has fingerprint ${want}`
+                    : `${want} matches ${hits.length} findings — give more of the fingerprint`,
+            ],
+        };
+    }
+    /**
+     * Rewrite ONE finding, by its current fingerprint, under a fresh load —
+     * refused (nothing written) when the store cannot be read or the finding
+     * is gone (a match renamed it since the caller looked). `change` returns
+     * the new record, or an error string to refuse.
+     */
+    update(fingerprint, change) {
+        const { file, error } = this.loadFile();
+        if (error !== null)
+            return { ok: false, errors: [error] };
+        const i = file.findings.findIndex((f) => f.fingerprint === fingerprint);
+        if (i < 0)
+            return {
+                ok: false,
+                errors: [
+                    `finding ${fingerprint.slice(0, 12)} is no longer stored under that fingerprint — list the findings again`,
+                ],
+            };
+        const next = change(file.findings[i]);
+        if (typeof next === "string")
+            return { ok: false, errors: [next] };
+        file.findings[i] = next;
+        this.write(file.findings, file.question ?? null);
+        return { ok: true, finding: next };
+    }
+}
+//# sourceMappingURL=findings.js.map