scenescout 3.14.1 → 3.16.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,47 @@ 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;
+/**
+ * A finding's judged merges that are well formed. The file is read back
+ * without a schema, and the report prints each of these, so a hand-edited
+ * entry that is not one is dropped, not trusted.
+ */
+export function judgedMergesOf(f) {
+    if (!Array.isArray(f.judgedMerges))
+        return [];
+    return f.judgedMerges.filter((m) => !!m &&
+        typeof m === "object" &&
+        typeof m.title === "string" &&
+        typeof m.category === "string" &&
+        typeof m.at === "string" &&
+        ["high", "medium", "low"].includes(m.severity) &&
+        typeof m.pSame === "number" &&
+        Number.isFinite(m.pSame) &&
+        (m.evidence === undefined || typeof m.evidence === "string"));
+}
 /**
  * Whether a finding is in the "worth a look" tier. Anything else a file holds
  * reads as a defect: a finding is never taken out of the defect count on a
@@ -34,23 +83,36 @@ export const FINDING_CATEGORIES = [
 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
@@ -181,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.
  *
@@ -202,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];
@@ -209,14 +307,21 @@ 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,
                 // Keep whichever action was actually recorded; ours wins a tie.
                 ...((el.lastAction ?? prev?.lastAction) ? { lastAction: el.lastAction ?? prev?.lastAction } : {}),
                 absentStreak: Math.min(prev?.absentStreak ?? 0, el.absentStreak ?? 0),
+                // Ours is the latest reading of whether a user can act on it.
+                ...(el.inert ? { inert: true } : {}),
             };
         }
         out.states[fp] = {
@@ -224,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();
@@ -245,12 +351,33 @@ 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);
         Object.assign(withoutTier(merged), tier);
         if (!isWorthALook(merged) && isWorthALook(newer))
             merged.severity = older.severity;
+        // Each side's judged merges are a record of filings, not later knowledge: kept from both.
+        const trail = unionJudgedMerges(f, other);
+        if (trail)
+            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()];
@@ -278,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 };
@@ -305,8 +443,28 @@ 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. */
+function unionJudgedMerges(a, b) {
+    const all = [...judgedMergesOf(b), ...judgedMergesOf(a)];
+    if (all.length === 0)
+        return undefined;
+    const byKey = new Map();
+    for (const m of all)
+        byKey.set(`${m.at}\u0000${m.title}`, m);
+    return [...byKey.values()].sort((x, y) => x.at.localeCompare(y.at)).slice(-MAX_JUDGED_MERGES);
+}
 /** Most routes kept per lane. A lane report carries at most a few hundred; this keeps a long-lived project's file small. */
 export const MAX_LANE_ROUTES = 255;
 /**
@@ -337,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
@@ -350,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.
@@ -374,6 +580,10 @@ function findingJaccard(a, b) {
     const union = new Set([...a, ...b]).size;
     return union === 0 ? 0 : inter / union;
 }
+/** How alike two titles are, 0 to 1, by the token overlap the rule's last tier uses. Orders the dedup judge's candidates. */
+export function titleSimilarity(a, b) {
+    return findingJaccard(findingTokens(a), findingTokens(b));
+}
 /**
  * Distinctive literals — quoted or parenthesized fragments like
  * `"(role not recorded)"` or `"Document not found"`. Two findings on the same
@@ -611,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;
@@ -809,7 +1031,58 @@ export class MemoryStore {
         this.auditsThisRun = 0;
         this.selectChoices.clear();
         this.emptySubmits.clear();
+        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
+     * alone. Per run, like the probes: the server sets it when a session
+     * attaches, and a run that never asks for it dedups by the rule only.
+     */
+    dedupJudge = null;
+    /** What an attach of this run asked for by name; unset means the server's environment decides. */
+    dedupChoice;
+    /** Why the judge this run asked for could not be set up (no key), for the report; unset when it was not asked for or is on. */
+    dedupOff;
     /**
      * Each dropdown's options and the ones chosen in THIS run, by any session,
      * keyed by route and element. A select counts as exercised after one choice,
@@ -821,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)];
@@ -835,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. */
@@ -862,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
@@ -887,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);
@@ -953,6 +1243,13 @@ export class MemoryStore {
                 dupOf.runs += f.runs;
                 if (!dupOf.evidence && f.evidence)
                     dupOf.evidence = f.evidence;
+                // Each copy's judged merges are filings: folding the copies keeps them all.
+                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);
@@ -1070,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 ?? {};
@@ -1200,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 ?? {};
@@ -1221,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);
@@ -1265,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.`;
@@ -1435,8 +1822,25 @@ export class MemoryStore {
         this.actionLog.push(full);
         fs.appendFileSync(this.sessionLogPath, JSON.stringify(full) + "\n");
     }
-    /** Record a visit to a state; returns whether it was new. */
-    visitState(fingerprint, url, route, elementKeys) {
+    /**
+     * 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 = [], 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) {
@@ -1445,11 +1849,25 @@ 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) {
             if (!rec.elements[key])
                 rec.elements[key] = { exercised: false };
             rec.elements[key].absentStreak = 0;
+            if (inert.has(key))
+                rec.elements[key].inert = true;
+            else
+                delete rec.elements[key].inert;
         }
         // Prune ghosts: dynamic elements (list rows, ordinal-suffixed duplicates)
         // that vanish for 3 consecutive visits would otherwise make coverage
@@ -1464,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)
@@ -1490,11 +1925,73 @@ 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) {
-        // Redact BEFORE the id is derived, so a re-found finding whose quoted
-        // secret differs by a character still hashes to the same id.
-        const f = {
+        const f = this.redacted(input);
+        const id = findingId(f);
+        const existing = this.data.findings.find((x) => isDuplicateFinding(x, f));
+        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
+     * the rule keeps the filing apart from everything stored. The rule decides
+     * first, exactly as addFinding: a merge the rule makes is never put to the
+     * model, so the judge can only add merges, never undo one, and the rule's
+     * merge at the next load (retroMerge) cannot split what the judge joined.
+     * Without a judge this is addFinding.
+     */
+    async fileFinding(input) {
+        const f = this.redacted(input);
+        const id = findingId(f);
+        const byRule = this.data.findings.find((x) => isDuplicateFinding(x, f));
+        if (byRule)
+            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 };
+        const before = new Set(this.data.findings.map((x) => x.id));
+        let verdict = null;
+        let judgeError;
+        try {
+            verdict = await judge.judge(f, [...this.data.findings]);
+        }
+        catch (err) {
+            judgeError = err instanceof Error ? err.message : String(err);
+        }
+        const extra = judgeError ? { judgeError } : {};
+        // The list may have changed while the judge was asked. A filing that
+        // landed meanwhile is compared by the rule, as it would have been with no
+        // judge; the finding the judge chose is looked up again by id, since a
+        // 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, ...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
+            ? this.data.findings.find((x) => x.id === verdict.sameAs && x.status !== "resolved" && x.state.split("#")[0] === route)
+            : undefined;
+        if (chosen && verdict) {
+            const judged = { pSame: verdict.pSame };
+            return { finding: chosen, isNew: false, ...this.mergeInto(chosen, f, id, judged), judged, ...extra };
+        }
+        return { finding: this.append(f, id), isNew: true, promoted: false, ...extra };
+    }
+    /**
+     * The filing with secrets redacted. BEFORE the id is derived, so a re-found
+     * finding whose quoted secret differs by a character still hashes to the
+     * same id; and before the dedup judge is shown it.
+     */
+    redacted(input) {
+        return {
             ...input,
             title: redactSecrets(input.title),
             detail: redactSecrets(input.detail),
@@ -1503,37 +2000,84 @@ export class MemoryStore {
             url: redactSecrets(input.url),
             evidence: input.evidence ? redactSecrets(input.evidence) : input.evidence,
         };
-        const id = findingId(f);
-        const existing = this.data.findings.find((x) => isDuplicateFinding(x, f));
-        if (existing) {
+    }
+    /**
+     * Fold a filing into the finding it duplicates. Returns whether a
+     * worth-a-look was promoted to a defect by it. `judged`: the dedup judge
+     * made this merge, so the filing is kept on the finding (judgedMerges).
+     */
+    mergeInto(existing, f, id, judged) {
+        // 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.foundAt = new Date().toISOString();
-            if (!existing.evidence && f.evidence)
-                existing.evidence = f.evidence;
-            // 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);
-            Object.assign(withoutTier(existing), tier);
-            if (promoted)
-                existing.severity = f.severity;
-            // Re-finding a RESOLVED finding is a regression — reopen it loudly
-            // rather than letting it hide in the report's completed section. But a
-            // FUZZY match must never resurrect a fixed bug: telling someone a
-            // regression landed when it did not is far more costly than carrying a
-            // visible duplicate, and it corrupts the one signal that says whether a
-            // fix held. Demand an exact identity match (same category+title+route) or
-            // an identical evidence signature before reopening.
-            const exactMatch = existing.id === id ||
-                (!!existing.evidence &&
-                    !!f.evidence &&
-                    existing.evidence.toLowerCase().replace(/\s+/g, " ").trim() === f.evidence.toLowerCase().replace(/\s+/g, " ").trim());
-            if (existing.status === "resolved" && exactMatch) {
-                existing.status = "open";
-                existing.regressedAt = existing.foundAt;
+        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, 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");
             }
-            this.flush();
-            return [existing, false, promoted];
         }
+        Object.assign(withoutTier(existing), tier);
+        if (promoted)
+            existing.severity = f.severity;
+        // Re-finding a RESOLVED finding is a regression — reopen it loudly
+        // rather than letting it hide in the report's completed section. But a
+        // FUZZY match must never resurrect a fixed bug: telling someone a
+        // regression landed when it did not is far more costly than carrying a
+        // visible duplicate, and it corrupts the one signal that says whether a
+        // fix held. Demand an exact identity match (same category+title+route) or
+        // an identical evidence signature before reopening.
+        const exactMatch = existing.id === id ||
+            (!!existing.evidence &&
+                !!f.evidence &&
+                existing.evidence.toLowerCase().replace(/\s+/g, " ").trim() === f.evidence.toLowerCase().replace(/\s+/g, " ").trim());
+        if (existing.status === "resolved" && exactMatch) {
+            existing.status = "open";
+            existing.regressedAt = existing.foundAt;
+        }
+        if (judged) {
+            const entry = {
+                title: f.title,
+                category: f.category,
+                severity: f.severity,
+                ...(f.evidence ? { evidence: f.evidence } : {}),
+                pSame: judged.pSame,
+                at: existing.foundAt,
+            };
+            existing.judgedMerges = [...(existing.judgedMerges ?? []), entry].slice(-MAX_JUDGED_MERGES);
+        }
+        this.flush();
+        return { promoted, merge };
+    }
+    /** Store a filing as a new finding, with its repro trace. */
+    append(f, id) {
         // Repro trace scoped to the finding's route: everything since the action
         // that landed there, not 12 lines of unrelated cross-module noise.
         const routeOf = (url) => {
@@ -1566,10 +2110,11 @@ 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();
-        return [finding, true, false];
+        return finding;
     }
     get findings() {
         return this.data.findings;
@@ -1582,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
@@ -1597,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.
@@ -1625,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 });
         }
@@ -1640,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.
@@ -1674,18 +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);
+            }
+            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);
             }
-            for (const [key, v] of Object.entries(rec.elements)) {
-                route.set(key, (route.get(key) ?? false) || v.exercised);
+        }
+        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;
+                elements.set(key, exercised.get(route)?.has(key) ?? false);
             }
+            byRoute.set(route, elements);
         }
         return byRoute;
     }