scenescout 3.15.0 → 3.17.0

package/dist/engine/memory.js

@@ -1,7 +1,15 @@
 import fs from "node:fs";
+import crypto from "node:crypto";
 import path from "node:path";
 import { laneRoutePaths, normalizePath, shortHash, stripRouteQuery } from "./fingerprint.js";
 import { isFormBookkeeping } from "./forms.js";
+import { addReading, addVerdict, MAX_TICKETS_KEPT, mergeTicketData } from "./tickets.js";
+/**
+ * The element-name rule current keys are made under. 2: a link or button with
+ * no text is named by its image content (an <img>'s alt text, an <svg>'s
+ * aria-label or <title>) before its title attribute.
+ */
+export const NAME_RULE = 2;
 /**
  * The kinds a finding can be. One list: scout_finding's input schema, the lane
  * report a parallel agent hands back, and the skill text all read it from
@@ -26,6 +34,27 @@ export const FINDING_CATEGORIES = [
     "missing-testid",
     "other",
 ];
+/** Most other routes one finding records it was seen on; the oldest go first. */
+export const MAX_SEEN_ON = 20;
+/** The route class a finding was filed on: its state before the `#`. */
+export const findingRoute = (f) => f.state.split("#")[0];
+/** A finding's other routes that are well formed: the file is read back without a schema. */
+export function seenOnOf(f) {
+    return Array.isArray(f.seenOn) ? f.seenOn.filter((r) => typeof r === "string" && r.length > 0) : [];
+}
+/**
+ * `f`'s other routes with `routes` added: each once, never its own route,
+ * oldest first, at most MAX_SEEN_ON. Undefined when there are none, so a
+ * finding seen on one route keeps no empty field. Idempotent.
+ */
+function withSeenOn(f, routes) {
+    const own = findingRoute(f);
+    const out = [];
+    for (const r of [...seenOnOf(f), ...routes])
+        if (r && r !== own && !out.includes(r))
+            out.push(r);
+    return out.length > 0 ? out.slice(-MAX_SEEN_ON) : undefined;
+}
 /** Most judged merges one finding keeps; the oldest go first. */
 export const MAX_JUDGED_MERGES = 10;
 /**
@@ -54,23 +83,36 @@ export function judgedMergesOf(f) {
 export function isWorthALook(f) {
     return f.tier === "worth_a_look";
 }
-/**
- * The tier a finding keeps when it is found again. A defect wins: a finding
- * someone filed as a defect is a decision about the project's convention, and
- * a later "worth a look" for the same thing does not undo it. A worth-a-look
- * filed again as a defect is promoted, and loses its convention. Two
- * worth-a-looks keep the first convention unless it had none.
- */
+/** The sentence a merged filing's result adds about what it changed, or "" when the two filings agreed. */
+export function describeMerge(note, convention) {
+    const parts = [];
+    if (note.seenOn)
+        parts.push(` Your page, ${note.seenOn}, is recorded as another route it was seen on.`);
+    if (note.updated.length > 0) {
+        const what = note.updated.map((f) => (f === "convention" ? `its convention is now "${convention ?? ""}"` : "its detail is now yours")).join(" and ");
+        parts.push(` Taken as a correction of your own filing: ${what}.`);
+    }
+    if (note.kept.length > 0) {
+        const what = note.kept.map((f) => (f === "convention" ? `convention ("${convention ?? ""}")` : "detail")).join(" and ");
+        parts.push(` The first filing's ${what} ${note.kept.length === 1 ? "was" : "were"} kept: a re-filing replaces them only when it comes from the session that filed it, in the same run.`);
+    }
+    return parts.join("");
+}
+/** A fresh run identity: unique per process and per run within it. */
+function newRunId() {
+    return `${process.pid}-${Date.now().toString(36)}-${crypto.randomBytes(4).toString("hex")}`;
+}
 /** Drops a finding's tier and convention in place, so a merged tier can be assigned onto it. */
 function withoutTier(f) {
     delete f.tier;
     delete f.convention;
     return f;
 }
-export function mergeTier(existing, incoming) {
+export function mergeTier(existing, incoming, prefer = "existing") {
     if (!isWorthALook(existing) || !isWorthALook(incoming))
         return {};
-    return { tier: "worth_a_look", convention: existing.convention || incoming.convention };
+    const convention = prefer === "incoming" ? incoming.convention || existing.convention : existing.convention || incoming.convention;
+    return { tier: "worth_a_look", convention };
 }
 /**
  * Most states a route may keep. A route accumulates one state per distinct
@@ -201,12 +243,41 @@ export function redactSecrets(text) {
     }
     return hits > 0 ? `${out} [${hits} secret${hits === 1 ? "" : "s"} redacted]` : out;
 }
+/**
+ * Routes are links the app printed, and a link can carry a token
+ * (`?reset=…`, `?api_key=…`). Evidence is redacted where issues are built;
+ * this does the same for every route string before anything is written.
+ */
+export function redactRoute(route) {
+    // The trailing "[n secrets redacted]" note belongs to prose; in a route it would read as part of the path.
+    return redactSecrets(route).replace(/ \[\d+ secrets? redacted\]$/, "");
+}
 /** The action-log lines that open and close a journey (scout_journey). The feed reads them to tell which goal an action served. */
 export const JOURNEY_START = "journey:start";
 export const JOURNEY_END = "journey:end";
 /** Logged when a session states the task it is starting, so the feed can group the actions that follow under it. */
 export const TASK_SET = "task";
+/** The most pages, and endpoints per page, the refused-POST record keeps. */
+const MAX_REFUSED_POST_ROUTES = 50;
+const MAX_REFUSED_POSTS_PER_ROUTE = 5;
 const EMPTY = { version: 1, states: {}, findings: [] };
+/**
+ * A state's elements under current keys: each key the route's aliases name
+ * (earlier key → current key) is moved, all at once, so two keys that swap
+ * places do not chain. Where two entries land on one key, exercised is kept
+ * from either.
+ */
+export function rekeyed(elements, aliases) {
+    if (!aliases)
+        return elements;
+    const out = {};
+    for (const [raw, entry] of Object.entries(elements)) {
+        const key = Object.hasOwn(aliases, raw) ? aliases[raw] : raw;
+        const prev = out[key];
+        out[key] = prev ? { ...prev, ...entry, exercised: prev.exercised || entry.exercised } : entry;
+    }
+    return out;
+}
 /**
  * Fold another process's memory into ours, losing nothing from either side.
  *
@@ -222,6 +293,13 @@ const EMPTY = { version: 1, states: {}, findings: [] };
  */
 export function mergeMemory(mine, theirs) {
     const out = { ...theirs, ...mine, version: 1 };
+    out.keyAliases = { ...(theirs.keyAliases ?? {}) };
+    for (const [route, aliases] of Object.entries(mine.keyAliases ?? {})) {
+        // The first reading stands (MemoryStore learnAliases): what is already on disk wins.
+        out.keyAliases[route] = { ...aliases, ...(out.keyAliases[route] ?? {}) };
+    }
+    if (Object.keys(out.keyAliases).length === 0)
+        delete out.keyAliases;
     out.states = { ...theirs.states };
     for (const [fp, ours] of Object.entries(mine.states)) {
         const other = theirs.states[fp];
@@ -229,8 +307,13 @@ export function mergeMemory(mine, theirs) {
             out.states[fp] = ours;
             continue;
         }
-        const elements = { ...other.elements };
-        for (const [key, el] of Object.entries(ours.elements)) {
+        const nameRule = Math.max(ours.nameRule ?? 0, other.nameRule ?? 0);
+        // When one side is under the current name rule and the other is not, the
+        // other's keys are moved to current ones before the union, as a revisit
+        // moves them (MemoryStore visitState).
+        const current = (side) => nameRule >= NAME_RULE && (side.nameRule ?? 1) < NAME_RULE ? rekeyed(side.elements, out.keyAliases?.[routeIdentity(side.route)]) : side.elements;
+        const elements = { ...current(other) };
+        for (const [key, el] of Object.entries(current(ours))) {
             const prev = elements[key];
             elements[key] = {
                 exercised: (prev?.exercised ?? false) || el.exercised,
@@ -246,6 +329,7 @@ export function mergeMemory(mine, theirs) {
             firstSeen: ours.firstSeen < other.firstSeen ? ours.firstSeen : other.firstSeen,
             visits: Math.max(ours.visits, other.visits),
             elements,
+            ...(nameRule ? { nameRule } : {}),
         };
     }
     const byId = new Map();
@@ -267,6 +351,15 @@ export function mergeMemory(mine, theirs) {
             evidence: newer.evidence ?? older.evidence,
             regressedAt: newer.regressedAt ?? older.regressedAt,
         };
+        // A picture and its shot travel together, from whichever side has one, the newer first.
+        const pictured = newer.picture ? newer : older.picture ? older : null;
+        delete merged.picture;
+        delete merged.pictureShot;
+        if (pictured?.picture) {
+            merged.picture = pictured.picture;
+            if (pictured.pictureShot)
+                merged.pictureShot = pictured.pictureShot;
+        }
         // The tier is not "later knowledge wins": a defect on either side is a decision
         // about the convention, and a store still holding the worth-a-look must not undo it.
         const tier = mergeTier(older, newer);
@@ -279,6 +372,12 @@ export function mergeMemory(mine, theirs) {
             merged.judgedMerges = trail;
         else
             delete merged.judgedMerges;
+        // So are the routes each side saw it on.
+        const seenOn = withSeenOn(older, seenOnOf(newer));
+        if (seenOn)
+            merged.seenOn = seenOn;
+        else
+            delete merged.seenOn;
         byId.set(f.id, merged);
     }
     out.findings = [...byId.values()];
@@ -306,6 +405,17 @@ export function mergeMemory(mine, theirs) {
     }
     if (Object.keys(out.routeFacts).length === 0)
         delete out.routeFacts;
+    // Per endpoint, the later of the two: a clear in one process outlasts an older refusal in another.
+    out.observeRefusedPosts = { ...(theirs.observeRefusedPosts ?? {}) };
+    for (const [route, endpoints] of Object.entries(mine.observeRefusedPosts ?? {})) {
+        const merged = { ...(out.observeRefusedPosts[route] ?? {}) };
+        for (const [endpoint, rec] of Object.entries(endpoints))
+            if (!merged[endpoint] || rec.at >= merged[endpoint].at)
+                merged[endpoint] = rec;
+        out.observeRefusedPosts[route] = merged;
+    }
+    if (Object.keys(out.observeRefusedPosts).length === 0)
+        delete out.observeRefusedPosts;
     out.roleAccess = { ...(theirs.roleAccess ?? {}) };
     for (const [role, routes] of Object.entries(mine.roleAccess ?? {})) {
         out.roleAccess[role] = { ...(out.roleAccess[role] ?? {}), ...routes };
@@ -333,6 +443,16 @@ export function mergeMemory(mine, theirs) {
     }
     if (Object.keys(out.laneRoutes).length === 0)
         delete out.laneRoutes;
+    // Lanes record criterion verdicts in their own processes too.
+    const ticketData = mergeTicketData(mine, theirs);
+    if (ticketData.tickets)
+        out.tickets = ticketData.tickets;
+    else
+        delete out.tickets;
+    if (ticketData.criterionVerdicts)
+        out.criterionVerdicts = ticketData.criterionVerdicts;
+    else
+        delete out.criterionVerdicts;
     return out;
 }
 /** Two findings' judged merges as one list, each filing once, oldest first, at most MAX_JUDGED_MERGES. Idempotent. */
@@ -375,11 +495,54 @@ function unionRoutes(a, b) {
 function decisionKey(d) {
     return [d.lane, d.observation, d.verdict, d.severity ?? "", d.category ?? "", d.confidence, d.evidence ?? ""].join("|");
 }
+/** Route identity of a stored route, memoised: states written before an id shape collapsed fold into today's form. */
+const routeIdentityCache = new Map();
+export function routeIdentity(route) {
+    let out = routeIdentityCache.get(route);
+    if (out === undefined) {
+        out = normalizePath(route);
+        if (routeIdentityCache.size > 10_000)
+            routeIdentityCache.clear();
+        routeIdentityCache.set(route, out);
+    }
+    return out;
+}
+/** A route's base: its path, without the UI-state query naming a tab or section of it. */
+export function baseRoute(route) {
+    return route.split("?")[0] || "/";
+}
 /**
- * Most lane decisions kept. Calibration wants a few dozen; a long-lived
- * project would otherwise accumulate every decision ever made and re-serialise
- * them on each save, which is what made an old history slow to open.
+ * Whether a contract route was reached, given the routes states were recorded
+ * on: the route itself, by today's route identity, or, for a base path, one of
+ * its tabs or sections (`/things/:id?section=history` reaches `/things/:id`).
+ * One rule for the "never visited" list and the gap ledger, so a route is not
+ * both reached and never visited.
+ */
+export function reachedRoutes(stateRoutes) {
+    const visited = new Set();
+    for (const r of stateRoutes)
+        visited.add(routeIdentity(r));
+    const bases = new Set([...visited].map(baseRoute));
+    return (route) => {
+        const n = routeIdentity(route);
+        return visited.has(n) || (!n.includes("?") && bases.has(n));
+    };
+}
+/**
+ * Link-discovered routes re-keyed by today's route identity. A memory written
+ * before an id shape collapsed holds one route per record (`/things/AB-1001`,
+ * `/things/AB-1002`); folded, they are the one route they always were, and
+ * the first example seen stays its navigable path.
  */
+export function renormalizeRoutes(map) {
+    const out = {};
+    for (const [route, example] of Object.entries(map)) {
+        const key = routeIdentity(route);
+        if (!(key in out))
+            out[key] = example;
+    }
+    return out;
+}
 /**
  * Whether a coverage key belongs to a control inside another site's frame:
  * those keys carry the frame's origin (collector.ts frameElementKey), where
@@ -388,6 +551,11 @@ function decisionKey(d) {
 export function isEmbedKey(key) {
     return /^frame:https?:\/\//.test(key);
 }
+/**
+ * Most lane decisions kept. Calibration wants a few dozen; a long-lived
+ * project would otherwise accumulate every decision ever made and re-serialise
+ * them on each save, which is what made an old history slow to open.
+ */
 export const MAX_LANE_DECISIONS = 1000;
 /**
  * Most options a dropdown may have and still be tracked for unchosen options.
@@ -653,12 +821,24 @@ function sameFinding(a, b) {
     // that answered 2xx counts too — a false success names one — so the same bug
     // described once by its page load and once by its failing call stays as two
     // findings: a visible duplicate, the direction ADR 4 accepts.
+    //
+    // And when both findings carry evidence (and it differs, or it would have
+    // matched above), the detail does not count: the literal must be in the
+    // other finding's title or evidence, the two places a finding states what
+    // it is about. A filter option's label ("Last 7 days") quoted in one title
+    // and in passing in the other finding's detail names the control both
+    // defects were found through, not one defect: an undated row listed under
+    // the wrong group and four widgets ignoring the filter shared only that
+    // label, and the second filing was lost to the first. Without evidence on
+    // one side the detail still counts — nothing machine-written says they
+    // differ.
     if (sameFamily(a.category, b.category) && !requestsDisagree(a.evidence, b.evidence)) {
         const aTitleLits = findingLiterals(a.title);
         const bTitleLits = findingLiterals(b.title);
         if (aTitleLits.size > 0 || bTitleLits.size > 0) {
-            const aAll = findingLiterals(a.title, a.detail, a.evidence);
-            const bAll = findingLiterals(b.title, b.detail, b.evidence);
+            const bothEvidenced = !!(aEv && bEv);
+            const aAll = findingLiterals(a.title, bothEvidenced ? undefined : a.detail, a.evidence);
+            const bAll = findingLiterals(b.title, bothEvidenced ? undefined : b.detail, b.evidence);
             for (const lit of aTitleLits)
                 if (bAll.has(lit))
                     return true;
@@ -854,6 +1034,44 @@ export class MemoryStore {
         this.dedupJudge = null;
         this.dedupChoice = undefined;
         this.dedupOff = undefined;
+        this.sessionRoutes.clear();
+        this.sessionStates.clear();
+        this.runStates.clear();
+        this.runId = newRunId();
+    }
+    /**
+     * This run's identity. A finding remembers the last run that filed it, so
+     * "seen in N runs" counts runs and not filings: a lane re-filing the same
+     * finding minutes later in the same run is one run. A new store (a new
+     * process) and every endRun start a new one.
+     */
+    runId = newRunId();
+    /**
+     * The routes each session reached this run, so scout_coverage can give a
+     * lane in a parallel run its own remaining work rather than every lane's.
+     * Per run, like the other per-run tallies.
+     */
+    sessionRoutes = new Map();
+    /**
+     * The state fingerprints each session recorded this run. A route's states
+     * differ by who looked: an admin's table and a viewer's access-denied alert
+     * are two states of one route, and a session's own coverage lists only the
+     * controls on the states it saw.
+     */
+    sessionStates = new Map();
+    /** Every state fingerprint recorded this run, by any session: the gap ledger's default scope. */
+    runStates = new Set();
+    /** The states this session recorded this run. */
+    statesVisitedBy(session) {
+        return this.sessionStates.get(session) ?? new Set();
+    }
+    /** Routes this session reached this run, in the order first reached. */
+    routesVisitedBy(session) {
+        return this.sessionRoutes.get(session) ?? new Set();
+    }
+    /** The sessions that reached this route this run. */
+    sessionsOnRoute(route) {
+        return [...this.sessionRoutes].filter(([, routes]) => routes.has(route)).map(([session]) => session);
     }
     /**
      * The dedup judge filings go through (fileFinding), or null for the rule
@@ -876,7 +1094,12 @@ export class MemoryStore {
      * one reported.
      */
     selectChoices = new Map();
-    recordSelectChoice(fingerprint, key, options, chosen) {
+    /**
+     * `loaded` names the options already selected before the choice: the value
+     * the page loaded with has already been asked of the server, so it is not
+     * owed a choice.
+     */
+    recordSelectChoice(fingerprint, key, options, chosen, loaded = []) {
         const route = fingerprint.split("#")[0];
         const id = `${route}\u0000${key}`;
         const distinct = [...new Set(options)];
@@ -890,6 +1113,9 @@ export class MemoryStore {
             entry.options = distinct;
         if (chosen)
             entry.chosen.add(chosen);
+        for (const label of loaded)
+            if (label)
+                entry.chosen.add(label);
         this.selectChoices.set(id, entry);
     }
     /** Dropdowns with options no session chose this run, in the order they were first used. */
@@ -917,10 +1143,12 @@ export class MemoryStore {
      * takes it off the list for good: the page refuses the empty submit itself,
      * and no one could clear an entry whose submit cannot be pressed.
      */
-    recordForm(fingerprint, key, guarded = false) {
+    recordForm(fingerprint, key, guarded = false, session) {
         const entry = this.formEntry(fingerprint, key);
         if (entry && guarded)
             entry.guarded = true;
+        if (entry && session)
+            entry.seenBy.add(session);
     }
     /**
      * A submit of a form already seen; `empty` when every text field was blank
@@ -942,14 +1170,21 @@ export class MemoryStore {
         const id = `${route}\u0000${key}`;
         let entry = this.emptySubmits.get(id) ?? null;
         if (!entry && create) {
-            entry = { route, key, triedEmpty: false };
+            entry = { route, key, triedEmpty: false, seenBy: new Set() };
             this.emptySubmits.set(id, entry);
         }
         return entry;
     }
-    /** Forms seen this run that no session has submitted empty, in the order they were first seen. */
-    formsNeverSubmittedEmpty() {
-        return [...this.emptySubmits.values()].filter((f) => !f.triedEmpty && !f.guarded).map(({ route, key }) => ({ route, key }));
+    /**
+     * Forms seen this run that no session has submitted empty, in the order they
+     * were first seen, each with the sessions that saw it. Given a session, only
+     * the forms that session saw: in a parallel run another lane's form may sit
+     * on a route this one never opens, or behind a role it does not have.
+     */
+    formsNeverSubmittedEmpty(session) {
+        return [...this.emptySubmits.values()]
+            .filter((f) => !f.triedEmpty && !f.guarded && (session === undefined || f.seenBy.has(session)))
+            .map(({ route, key, seenBy }) => ({ route, key, seenBy: [...seenBy] }));
     }
     constructor(projectDir) {
         this.dir = path.join(projectDir, MEMORY_DIRNAME);
@@ -1012,6 +1247,9 @@ export class MemoryStore {
                 const trail = unionJudgedMerges(dupOf, f);
                 if (trail)
                     dupOf.judgedMerges = trail;
+                const seenOn = withSeenOn(dupOf, [findingRoute(f), ...seenOnOf(f)]);
+                if (seenOn)
+                    dupOf.seenOn = seenOn;
                 if (f.status === "resolved")
                     dupOf.status = "resolved";
                 const promoted = isWorthALook(dupOf) && !isWorthALook(f);
@@ -1129,6 +1367,45 @@ export class MemoryStore {
     get routeFacts() {
         return this.data.routeFacts ?? {};
     }
+    /** Record that observe refused a script's POST to `endpoint` on `route`. Deduplicated; saved only when something changed. */
+    noteObserveRefusedPost(route, endpoint, now = Date.now()) {
+        const all = this.data.observeRefusedPosts ?? {};
+        const forRoute = all[route] ?? {};
+        const rec = forRoute[endpoint];
+        if (rec && !rec.cleared)
+            return;
+        if (!rec && !all[route] && Object.keys(all).length >= MAX_REFUSED_POST_ROUTES)
+            return;
+        if (!rec && Object.keys(forRoute).length >= MAX_REFUSED_POSTS_PER_ROUTE)
+            return;
+        forRoute[endpoint] = { at: now };
+        all[route] = forRoute;
+        this.data.observeRefusedPosts = all;
+        this.save();
+    }
+    /** Clear every open refusal whose endpoint `went` says has since gone out. Saved only when something changed. */
+    clearObserveRefusedPosts(went, now = Date.now()) {
+        let changed = false;
+        for (const endpoints of Object.values(this.data.observeRefusedPosts ?? {}))
+            for (const [endpoint, rec] of Object.entries(endpoints))
+                if (!rec.cleared && went(endpoint)) {
+                    endpoints[endpoint] = { at: now, cleared: true };
+                    changed = true;
+                }
+        if (changed)
+            this.save();
+    }
+    /** Pages with a POST observe refused and nothing has since let out, for the gap ledger. */
+    get observeRefusedPosts() {
+        return Object.entries(this.data.observeRefusedPosts ?? {})
+            .map(([route, endpoints]) => ({
+            route,
+            endpoints: Object.entries(endpoints)
+                .filter(([, rec]) => !rec.cleared)
+                .map(([endpoint]) => endpoint),
+        }))
+            .filter((p) => p.endpoints.length > 0);
+    }
     /** Record that `role` reached (or was denied) `route`. Denials never overwrite a recorded "reached" — flaky redirects must not erase real access. */
     recordRoleAccess(role, route, outcome) {
         const all = this.data.roleAccess ?? {};
@@ -1259,6 +1536,45 @@ export class MemoryStore {
         // every call after the first reported nothing kept — while storing fine.
         return Math.min(added, MAX_LANE_DECISIONS);
     }
+    /** Every ticket the project has been given, oldest reading first. */
+    get tickets() {
+        return this.data.tickets ?? [];
+    }
+    /** Every verdict recorded on a criterion, oldest first. */
+    get criterionVerdicts() {
+        return this.data.criterionVerdicts ?? [];
+    }
+    /**
+     * Keep tickets read in this run. A ticket read again replaces its earlier
+     * reading (see addReading). Titles and criteria are redacted like any other
+     * stored text: a ticket is pasted by a person and may carry a credential.
+     * Returns the tickets as stored, with the ids to judge them by.
+     */
+    addTickets(parsed) {
+        const clean = parsed.map((t) => ({
+            ...t,
+            title: redactSecrets(t.title),
+            criteria: t.criteria.map((c) => ({ ...c, text: redactSecrets(c.text) })),
+        }));
+        const all = this.tickets;
+        const thisRun = all.filter((t) => t.loadedAt >= this.sessionStart);
+        const { tickets, added } = addReading(thisRun, clean, new Date().toISOString());
+        const ids = new Set(tickets.map((t) => t.id));
+        this.data.tickets = [...all.filter((t) => t.loadedAt < this.sessionStart && !ids.has(t.id)), ...tickets].slice(-MAX_TICKETS_KEPT);
+        this.flush();
+        return added;
+    }
+    /** Record one session's verdict on a criterion, replacing that session's earlier verdict on it. */
+    addCriterionVerdict(record) {
+        this.data.criterionVerdicts = addVerdict(this.criterionVerdicts, { ...record, reason: redactSecrets(record.reason) });
+        this.flush();
+    }
+    /** What this run answers: the tickets read in it, or judged in it, and this run's verdicts. */
+    ticketsThisRun() {
+        const verdicts = this.criterionVerdicts.filter((v) => v.at >= this.sessionStart);
+        const judged = new Set(verdicts.map((v) => v.ticket));
+        return { tickets: this.tickets.filter((t) => t.loadedAt >= this.sessionStart || judged.has(t.id)), verdicts };
+    }
     /** The routes each lane's report said it covered. Empty on a project that has never run one. */
     get laneRoutes() {
         return this.data.laneRoutes ?? {};
@@ -1280,6 +1596,16 @@ export class MemoryStore {
         this.flush();
         return added;
     }
+    /** Keep a finding's picture: its path relative to .scenescout/, and what it shows. Returns the finding, or null when there is no such id. */
+    setPicture(id, picture, shot) {
+        const f = this.data.findings.find((x) => x.id === id);
+        if (!f)
+            return null;
+        f.picture = picture;
+        f.pictureShot = shot;
+        this.flush();
+        return f;
+    }
     /** Mark a finding resolved; returns it or null. */
     resolveFinding(id) {
         const f = this.data.findings.find((x) => x.id === id);
@@ -1324,6 +1650,8 @@ export class MemoryStore {
                     raw.states = kept;
                     this.prunedStates = dropped;
                 }
+                if (raw.discoveredRoutes)
+                    raw.discoveredRoutes = renormalizeRoutes(raw.discoveredRoutes);
                 return raw;
             }
             this.loadWarning = `memory.json has unknown version ${String(raw.version)} — starting fresh.`;
@@ -1498,8 +1826,21 @@ export class MemoryStore {
      * Record a visit to a state; returns whether it was new. `inertKeys` are the
      * listed keys a user cannot act on (collector inertKeys): they stay known,
      * so a click on one still registers, but coverage does not count them.
+     * `session` names who visited, for this run's per-session coverage.
+     * `aliases` maps a listed key to the key the same control had under the
+     * earlier name rule (fingerprint.ts keyAliases); the route keeps them so
+     * states written before the rule changed are read under current keys.
      */
-    visitState(fingerprint, url, route, elementKeys, inertKeys = []) {
+    visitState(fingerprint, url, route, elementKeys, inertKeys = [], session, aliases = {}) {
+        this.runStates.add(fingerprint);
+        if (session) {
+            const routes = this.sessionRoutes.get(session) ?? new Set();
+            routes.add(route);
+            this.sessionRoutes.set(session, routes);
+            const states = this.sessionStates.get(session) ?? new Set();
+            states.add(fingerprint);
+            this.sessionStates.set(session, states);
+        }
         let rec = this.data.states[fingerprint];
         const isNew = !rec;
         if (!rec) {
@@ -1508,6 +1849,15 @@ export class MemoryStore {
         }
         rec.visits += 1;
         rec.lastSeen = new Date().toISOString();
+        this.learnAliases(route, aliases);
+        // A record written under the earlier rule can be reached again under the
+        // same fingerprint with its keys renamed: the fingerprint hashes the set
+        // of base keys, so a rename that only moves ordinals (an image button
+        // named like a text button beside it) leaves it unchanged. Its keys are
+        // moved to the current ones before it is marked current.
+        if ((rec.nameRule ?? 1) < NAME_RULE)
+            rec.elements = rekeyed(rec.elements, this.data.keyAliases?.[routeIdentity(route)]);
+        rec.nameRule = NAME_RULE;
         const present = new Set(elementKeys);
         const inert = new Set(inertKeys);
         for (const key of elementKeys) {
@@ -1532,6 +1882,23 @@ export class MemoryStore {
         this.save();
         return isNew;
     }
+    /**
+     * Keep each earlier key → current key the route has not learned yet. The
+     * first reading stands: a later snapshot of another state of the route can
+     * hand out ordinals differently, and the states written under the earlier
+     * rule do not change, so neither should what their keys are read as.
+     */
+    learnAliases(route, aliases) {
+        const pairs = Object.entries(aliases);
+        if (pairs.length === 0)
+            return;
+        const byRoute = (this.data.keyAliases ??= {});
+        const id = routeIdentity(route);
+        const known = (byRoute[id] ??= {});
+        for (const [key, prior] of pairs)
+            if (!Object.hasOwn(known, prior))
+                known[prior] = key;
+    }
     markExercised(fingerprint, key, action) {
         const rec = this.data.states[fingerprint];
         if (!rec)
@@ -1558,14 +1925,20 @@ export class MemoryStore {
      *    across sessions rarely reuses the exact words — Jaccard catches it).
      * Returns [finding, isNew].
      */
-    /** Returns the finding, whether it is new, and whether an existing worth-a-look was just promoted to a defect by it. */
+    /**
+     * Returns the finding, whether it is new, whether an existing worth-a-look
+     * was just promoted to a defect by it, and how a merge treated what the two
+     * filings disagree on (MergeNote).
+     */
     addFinding(input) {
         const f = this.redacted(input);
         const id = findingId(f);
         const existing = this.data.findings.find((x) => isDuplicateFinding(x, f));
-        if (existing)
-            return [existing, false, this.mergeInto(existing, f, id)];
-        return [this.append(f, id), true, false];
+        if (existing) {
+            const { promoted, merge } = this.mergeInto(existing, f, id);
+            return [existing, false, promoted, merge];
+        }
+        return [this.append(f, id), true, false, { sameRun: false, updated: [], kept: [] }];
     }
     /**
      * File a finding, asking the dedup judge when one is set (dedupJudge) and
@@ -1580,7 +1953,7 @@ export class MemoryStore {
         const id = findingId(f);
         const byRule = this.data.findings.find((x) => isDuplicateFinding(x, f));
         if (byRule)
-            return { finding: byRule, isNew: false, promoted: this.mergeInto(byRule, f, id) };
+            return { finding: byRule, isNew: false, ...this.mergeInto(byRule, f, id) };
         const judge = this.dedupJudge;
         if (!judge)
             return { finding: this.append(f, id), isNew: true, promoted: false };
@@ -1600,7 +1973,7 @@ export class MemoryStore {
         // merge with another process's memory may have replaced its object.
         const landed = this.data.findings.find((x) => !before.has(x.id) && isDuplicateFinding(x, f));
         if (landed)
-            return { finding: landed, isNew: false, promoted: this.mergeInto(landed, f, id), ...extra };
+            return { finding: landed, isNew: false, ...this.mergeInto(landed, f, id), ...extra };
         // Only what a judge may answer is taken: an open finding on the filing's page, called the same at better than even.
         const route = f.state.split("#")[0];
         const chosen = verdict && verdict.pSame >= 0.5
@@ -1608,7 +1981,7 @@ export class MemoryStore {
             : undefined;
         if (chosen && verdict) {
             const judged = { pSame: verdict.pSame };
-            return { finding: chosen, isNew: false, promoted: this.mergeInto(chosen, f, id, judged), judged, ...extra };
+            return { finding: chosen, isNew: false, ...this.mergeInto(chosen, f, id, judged), judged, ...extra };
         }
         return { finding: this.append(f, id), isNew: true, promoted: false, ...extra };
     }
@@ -1634,13 +2007,43 @@ export class MemoryStore {
      * made this merge, so the filing is kept on the finding (judgedMerges).
      */
     mergeInto(existing, f, id, judged) {
-        existing.runs += 1;
+        // Counted once per run: a lane filing the same thing again minutes
+        // later is not the bug recurring.
+        const sameRun = existing.lastRun === this.runId;
+        if (!sameRun)
+            existing.runs += 1;
+        existing.lastRun = this.runId;
         existing.foundAt = new Date().toISOString();
         if (!existing.evidence && f.evidence)
             existing.evidence = f.evidence;
+        // A filing from another page is another place the defect shows.
+        const route = findingRoute(f);
+        const knew = route === findingRoute(existing) || seenOnOf(existing).includes(route);
+        const seenOn = withSeenOn(existing, [route]);
+        if (seenOn)
+            existing.seenOn = seenOn;
+        // The same session filing it again in the same run is correcting its
+        // own filing: its newer convention and detail are taken. Anyone else's
+        // filing is a second sighting, which keeps the first wording. A merge the
+        // dedup judge made is never a correction: the judge saw two filings.
+        const correction = !judged && sameRun && !!f.session && existing.session === f.session;
+        const merge = { sameRun, updated: [], kept: [], ...(knew ? {} : { seenOn: route }) };
         // A worth-a-look filed again as a defect is promoted, at the severity the defect was filed at.
         const promoted = isWorthALook(existing) && !isWorthALook(f);
-        const tier = mergeTier(existing, f);
+        const tier = mergeTier(existing, f, correction ? "incoming" : "existing");
+        // A convention filled in where there was none is not a disagreement, so it says nothing.
+        if (isWorthALook(existing) && isWorthALook(f) && f.convention && existing.convention && f.convention !== existing.convention) {
+            (correction ? merge.updated : merge.kept).push("convention");
+        }
+        if (f.detail && f.detail !== existing.detail) {
+            if (correction) {
+                existing.detail = f.detail;
+                merge.updated.push("detail");
+            }
+            else {
+                merge.kept.push("detail");
+            }
+        }
         Object.assign(withoutTier(existing), tier);
         if (promoted)
             existing.severity = f.severity;
@@ -1671,7 +2074,7 @@ export class MemoryStore {
             existing.judgedMerges = [...(existing.judgedMerges ?? []), entry].slice(-MAX_JUDGED_MERGES);
         }
         this.flush();
-        return promoted;
+        return { promoted, merge };
     }
     /** Store a filing as a new finding, with its repro trace. */
     append(f, id) {
@@ -1707,6 +2110,7 @@ export class MemoryStore {
                 .map((a) => `${a.action}${a.target ? ` ${a.target}` : ""} @ ${a.url}`),
             foundAt: new Date().toISOString(),
             runs: 1,
+            lastRun: this.runId,
         };
         this.data.findings.push(finding);
         this.flush();
@@ -1723,9 +2127,15 @@ export class MemoryStore {
      * rendered in 30 states of one route is one set of elements, not 30. An
      * element counts as exercised when it was exercised in ANY state of the
      * route. (`state` in the result therefore holds a route.)
+     *
+     * `scope.routes` narrows the routes counted; `scope.states` narrows the
+     * elements listed to the ones those states hold (a session's own states, or
+     * this run's), while whether one was exercised still comes from every state
+     * of the route.
      */
-    coverage() {
+    coverage(scope) {
         const byRoute = this.elementsByRoute();
+        const listed = scope?.states ? this.elementsByRoute(scope.states) : byRoute;
         // Shared layout CHROME (sidebar nav, header, breadcrumbs) is one set of
         // components, not one set per route — clicking "nav-documents" on /admin is
         // the same click as on /. Counting it per route inflated the denominator by
@@ -1738,8 +2148,14 @@ export class MemoryStore {
         let elementsTotal = 0;
         let elementsExercised = 0;
         const unexercised = [];
+        const perRoute = new Map();
         const embeds = { total: 0, exercised: 0 };
-        for (const [route, elements] of byRoute) {
+        for (const [route, elements] of listed) {
+            // A scope narrows what is counted, never what counts as chrome: that is
+            // decided over every route, so a lane on two pages does not see the
+            // project's sidebar as those pages' own controls.
+            if (scope?.routes && !scope.routes.has(route))
+                continue;
             const own = [];
             // The route's OWN element count — deduped across states and with shared
             // chrome removed, i.e. exactly the denominator `own` is a subset of.
@@ -1766,6 +2182,7 @@ export class MemoryStore {
                 else
                     own.push(key);
             }
+            perRoute.set(route, { total: ownTotal, exercised: ownTotal - own.length });
             if (own.length > 0)
                 unexercised.push({ state: route, keys: own, total: ownTotal });
         }
@@ -1781,7 +2198,10 @@ export class MemoryStore {
         if (chromeLeft.length > 0) {
             unexercised.push({ state: SHARED_CHROME_ROUTE, keys: chromeLeft, total: chrome.size });
         }
-        return { states: Object.keys(this.data.states).length, elementsTotal, elementsExercised, unexercised, embeds };
+        const states = scope
+            ? Object.entries(this.data.states).filter(([fp, st]) => (!scope.routes || scope.routes.has(routeIdentity(st.route))) && (!scope.states || scope.states.has(fp))).length
+            : Object.keys(this.data.states).length;
+        return { states, elementsTotal, elementsExercised, unexercised, perRoute, embeds };
     }
     /**
      * Remember which styled-element signatures the design audit saw on a route.
@@ -1815,21 +2235,55 @@ export class MemoryStore {
                 keys.add(sig);
         return keys;
     }
-    /** Element keys folded per route, exercised-in-any-state. */
-    elementsByRoute() {
-        const byRoute = new Map();
-        for (const rec of Object.values(this.data.states)) {
-            let route = byRoute.get(rec.route);
-            if (!route) {
-                route = new Map();
-                byRoute.set(rec.route, route);
+    /**
+     * Element keys folded per route, exercised-in-any-state. With `only`, the
+     * keys listed are the ones those states hold; exercised still reads every
+     * state of the route.
+     *
+     * A key is not a control when ANY state of the route recorded it as inert.
+     * Whether a user can act on an element depends on the element, not on the
+     * state it was seen in, and states recorded before the flag existed carry
+     * an unflagged copy that would otherwise keep a wrapper in the count until
+     * that exact state is visited again.
+     *
+     * Routes are re-read through route identity, so states recorded under an
+     * older form of a route (before an id shape collapsed) fold into it.
+     */
+    elementsByRoute(only) {
+        const inert = new Map();
+        const exercised = new Map();
+        const listed = new Map();
+        const bucket = (map, route) => {
+            let set = map.get(route);
+            if (!set) {
+                set = new Set();
+                map.set(route, set);
             }
-            for (const [key, v] of Object.entries(rec.elements)) {
-                // Not a control: nothing to exercise, so not counted as a gap or a total.
+            return set;
+        };
+        for (const [fp, rec] of Object.entries(this.data.states)) {
+            const route = routeIdentity(rec.route);
+            const keys = only && !only.has(fp) ? null : bucket(listed, route);
+            // A state written under an earlier name rule is read under current keys.
+            const elements = (rec.nameRule ?? 1) < NAME_RULE ? rekeyed(rec.elements, this.data.keyAliases?.[route]) : rec.elements;
+            for (const [key, v] of Object.entries(elements)) {
                 if (v.inert)
+                    bucket(inert, route).add(key);
+                if (v.exercised)
+                    bucket(exercised, route).add(key);
+                keys?.add(key);
+            }
+        }
+        const byRoute = new Map();
+        for (const [route, keys] of listed) {
+            const elements = new Map();
+            for (const key of keys) {
+                // Not a control: nothing to exercise, so not counted as a gap or a total.
+                if (inert.get(route)?.has(key))
                     continue;
-                route.set(key, (route.get(key) ?? false) || v.exercised);
+                elements.set(key, exercised.get(route)?.has(key) ?? false);
             }
+            byRoute.set(route, elements);
         }
         return byRoute;
     }