staysfixed 0.7.2 → 0.9.0

package/src/v2/cluster.js

@@ -27,14 +27,6 @@ import { splitPath, sameValue } from './observation.js';
 /** @typedef {import('./types.js').Channel} Channel */
 /** @typedef {import('./types.js').ObservedValue} ObservedValue */
 
-/** How much of a cluster a finding carries with it. Enough to orient, not enough to bury. */
-const KEEP_NEAR_FILES = 5;
-
-/**
- * How many of a cluster's addresses travel with the finding. `count` always says how
- * many there really are, so a long cluster cannot hide its size behind a short list.
- */
-const KEEP_PATHS = 20;
 
 /**
  * How each channel introduces itself. This is the first half of every sentence
@@ -55,8 +47,25 @@ const CHANNEL_WORDS = {
 /**
  * Last segments too vague to identify anything alone. When an address ends in
  * one of these, the segment before it comes along for the ride.
+ *
+ * WHAT PUTS A WORD IN HERE. Every address ends either in something the PRODUCT
+ * named — an exported function, a route, a control, a field — or in a word this
+ * tool wrote to say what was being asked about it. The first kind identifies
+ * something on its own. The second kind is the same word on every journey, every
+ * door and every screen in the product, so a sentence built out of it names
+ * nothing: `"declared" is gone` was a real title, about a route that had been
+ * renamed, and the route was sitting one segment to the left the whole time.
+ * That sentence is not only read by an agent — it goes verbatim into the block a
+ * person reads in the closing summary, and the owner of this tool is not a coder.
+ *
+ * So this holds the words the tool writes, checked against the addresses the
+ * adapters actually produce rather than guessed at. `smartLeaf names the half a
+ * reader can act on` in the tests sweeps one real address of every shape through
+ * here; a new adapter that ends an address in a shared word belongs in that list
+ * and in this set on the same day.
  */
 const VAGUE = new Set([
+  // What was asked about a thing: the thing itself is one segment to the left.
   'value',
   'text',
   'name',
@@ -64,14 +73,45 @@ const VAGUE = new Set([
   'label',
   'title',
   'count',
+  'size',
+  'reason',
   'enabled',
   'visible',
   'status',
   'type',
   'id',
   'body',
+  'shape',
   'result',
   'exit',
+  // Doors, which all end the same way whatever the door is: a route, a command,
+  // an IPC channel, a named control on a phone.
+  'declared',
+  'registered',
+  'reached',
+  // What happened when we asked, on every surface there is.
+  'asked',
+  'answered',
+  'answered at all',
+  'ran at all',
+  'opened at all',
+  'walked',
+  'read',
+  'typed',
+  'pressed',
+  'done',
+  'started',
+  'finished',
+  'refused',
+  'settled',
+  'held still',
+  'looks like',
+  'written',
+  'still running',
+  'stdout',
+  'stderr',
+  'controls',
+  'picture',
 ]);
 
 /**
@@ -146,20 +186,75 @@ export function findRenames(differences) {
 
   /** @type {Map<Difference, {from: string, to: string}>} */
   const found = new Map();
+  /** @type {{was: string, now: string, from: string, to: string}[]} */
+  const moves = [];
   for (const place of places.values()) {
     if (place.gone.length !== 1 || place.came.length !== 1) continue;
     const gone = place.gone[0];
     const came = place.came[0];
-    if (!sameValue(gone.reference, came.candidate)) continue;
     const from = leafOf(gone.path);
     const to = leafOf(came.path);
     if (from === to) continue;
+    // "The values must match" is right for a thing addressed by its position, and wrong for
+    // one addressed by its own words. A heading lives at `heading:Nine Bakers` and its value
+    // reads `a heading called "Nine Bakers"` — rename it and BOTH move, so the values never
+    // match and the rename was never spotted. Measured 2026-08-30: renaming one heading on a
+    // page came back as five separate findings, one thing vanishing and a different thing
+    // appearing, with nothing anywhere saying "renamed". So a value that changed in exactly
+    // the same way the name did counts as the same value. Anything else is still two edits
+    // that happened to land side by side, which is what this test exists to keep out.
+    if (!sameValue(gone.reference, came.candidate) && !movedWithItsName(gone.reference, came.candidate, from, to)) continue;
     found.set(gone, { from, to });
     found.set(came, { from, to });
+    moves.push({ was: gone.path, now: came.path, from, to });
+  }
+
+  // A rename takes its children with it. Everything under the old address goes away and the
+  // same things arrive under the new one — true, and not a second piece of news. Renaming one
+  // heading on a page reported the heading AND the two halves of its own `level`, so one edit
+  // a person would describe in four words arrived as four findings. Anything that moved with
+  // it, unchanged, belongs to the rename that moved it.
+  for (const move of moves) {
+    for (const gone of differences) {
+      if (gone.kind !== 'vanished' || found.has(gone)) continue;
+      if (!gone.path.startsWith(`${move.was}.`)) continue;
+      const wanted = move.now + gone.path.slice(move.was.length);
+      const came = differences.find(
+        (d) => d.kind === 'appeared' && !found.has(d) && d.path === wanted && d.channel === gone.channel && sameValue(gone.reference, d.candidate),
+      );
+      if (!came) continue;
+      found.set(gone, { from: move.from, to: move.to });
+      found.set(came, { from: move.from, to: move.to });
+    }
   }
   return found;
 }
 
+/**
+ * Did the value change in exactly the way the name did?
+ *
+ * Only for two addresses naming the same KIND of thing — `heading:X` and `heading:Y`, never
+ * `heading:X` and `button:Y` — because the part before the colon is what the thing IS, and a
+ * heading becoming a button is not a rename.
+ *
+ * @param {unknown} before
+ * @param {unknown} after
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+function movedWithItsName(before, after, from, to) {
+  if (typeof before !== 'string' || typeof after !== 'string') return false;
+  const wasNamed = /^([^:]+):(.+)$/.exec(from);
+  const nowNamed = /^([^:]+):(.+)$/.exec(to);
+  if (!wasNamed || !nowNamed) return false;
+  if (wasNamed[1] !== nowNamed[1]) return false;
+  const was = wasNamed[2];
+  const now = nowNamed[2];
+  if (!was || was === now) return false;
+  return before.split(was).join(now) === after;
+}
+
 /**
  * The grouping key: channel, shape of change, what the address ends in, and the
  * move from one value to another.
@@ -194,7 +289,15 @@ export function journeysOf(finding) {
  */
 function buildFinding(signature, members, rename, sources) {
   const head = members[0];
-  const nearFiles = unique(members.map((m) => sources[m.path])).slice(0, KEEP_NEAR_FILES);
+  // EVERY source file this finding touches, not the first five. The short list was written
+  // as "enough to orient, not enough to bury", and the things reading it are not orienting.
+  // `sealed.js` searches these names for the words nobody may wave through, so a finding
+  // whose sixth file was src/billing/refund.js was classified ordinary and became waivable;
+  // `intent.js` matches them against what the agent declared it was changing, and `cause.js`
+  // uses them to work out which edit caused what. A cap on the input to the one gate that
+  // cannot have a ceiling is the same bug that was closed for differences. Everything that
+  // DISPLAYS this list already cuts it itself and says "and N more" when it does.
+  const nearFiles = unique(members.map((m) => sources[m.path]));
   const evidence = members.find((m) => typeof m.evidence === 'string' && m.evidence.length > 0)?.evidence;
   // Half the differences in a rename are the "vanished" side, so the count of
   // places is the count of pairs, not of rows.
@@ -225,7 +328,16 @@ function buildFinding(signature, members, rename, sources) {
     // everything downstream — the MCP reply lists them, and the self-check corpus
     // matches its patterns against them — so they are filled in here rather than
     // left for each reader to dig out of `differences` in its own way.
-    paths: members.map((m) => m.path).slice(0, KEEP_PATHS),
+    // EVERY address, not the first twenty. The short list was there to keep a finding small,
+    // and it was buying nothing: the finding already carries `differences`, which holds the
+    // same addresses AND both values at each of them, so cutting this list saved a fraction
+    // of what was being stored anyway. What it cost was real. A waiver is pinned partly to
+    // this list, so two three-hundred-address findings that agreed about their first twenty
+    // pinned to the same thing; and the reply an agent reads prints the length of this list
+    // under the heading "every address that moved", which was a count of twenty about a
+    // finding with three hundred. Readers that want a short list still cut it themselves,
+    // and every one of them says "and N more" when it does.
+    paths: members.map((m) => m.path),
     sample: head,
   };
   if (nearFiles.length > 0) finding.nearFiles = nearFiles;
@@ -259,8 +371,23 @@ export function describe(d, count, rename, identical = true) {
   if (rename) return `${where}, "${rename.from}" is now called "${rename.to}".${spread}`;
 
   switch (d.kind) {
-    case 'changed':
-      return `${where}, "${name}" is now ${describeValue(d.candidate)} where it was ${describeValue(d.reference)}.${spread}`;
+    case 'changed': {
+      const now = describeValue(d.candidate);
+      const was = describeValue(d.reference);
+      if (now !== was) return `${where}, "${name}" is now ${now} where it was ${was}.${spread}`;
+      // BOTH SIDES CAME OUT IN THE SAME WORDS, so this sentence would say nothing changed
+      // while sitting on top of a difference. It is what happens whenever the two values
+      // are summarised by their SHAPE and the shape held still: an invoice line that went
+      // from "£49.99" to "49.99 GBP" read "is now a set of details (one field: line) where
+      // it was a set of details (one field: line)" — twice the same words, on the tool's own
+      // flagship example, in the paragraph a person reads rather than an agent. So the
+      // summary is put down and the thing that actually moved is named instead.
+      const moved = whatMoved(d.reference, d.candidate);
+      if (!moved) return `${where}, "${name}" changed, and both versions of it read the same at this length.${spread}`;
+      return moved.what === ''
+        ? `${where}, "${name}" now reads ${moved.now} where it read ${moved.was}.${spread}`
+        : `${where}, "${name}" now has "${moved.what}" reading ${moved.now} where it read ${moved.was}.${spread}`;
+    }
     case 'appeared':
       return `${where}, "${name}" is there now and was not before. It says ${describeValue(d.candidate)}.${spread}`;
     case 'vanished':
@@ -354,7 +481,86 @@ export function describeValue(value) {
   if (Array.isArray(value)) return `a list of ${value.length}`;
   const keys = Object.keys(/** @type {object} */ (value));
   if (keys.length === 0) return 'an empty set of details';
-  return `a set of details (${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ', and more' : ''})`;
+  // The field names are quoted and counted. Bare, they run into the sentence around them and
+  // stop looking like names at all: a shape whose fields are the words "a list of" and "each
+  // one" came out as "a set of details (a list of, each one)", which is not a thing anybody
+  // can picture. Quoted, it reads as what it is.
+  const shown = keys.slice(0, 4).map((k) => JSON.stringify(k)).join(', ');
+  return `a set of details (${keys.length === 1 ? 'one field' : `${keys.length} fields`}: ${shown}${keys.length > 4 ? ', and more' : ''})`;
+}
+
+/**
+ * The smallest thing that actually moved between two values.
+ *
+ * Only reached when a summary of the two whole values comes out identical, which is exactly
+ * when a summary is the wrong thing to print. It walks in until it finds the one field, or
+ * the one stretch of text, that is not the same, and hands back that piece with a name for
+ * it. `sameValue` is the tool's one comparison, so what counts as "not the same" here is
+ * what counts as a difference everywhere else.
+ *
+ * @param {ObservedValue|undefined} reference
+ * @param {ObservedValue|undefined} candidate
+ * @param {string[]} [trail]
+ * @returns {{what: string, was: string, now: string}|null}
+ */
+function whatMoved(reference, candidate, trail = []) {
+  if (isSetOfDetails(reference) && isSetOfDetails(candidate)) {
+    for (const key of [...new Set([...Object.keys(reference), ...Object.keys(candidate)])].sort()) {
+      const a = /** @type {Record<string, any>} */ (reference)[key];
+      const b = /** @type {Record<string, any>} */ (candidate)[key];
+      if (sameValue(a, b)) continue;
+      return whatMoved(a, b, [...trail, key]);
+    }
+    return null;
+  }
+  if (Array.isArray(reference) && Array.isArray(candidate)) {
+    for (let i = 0; i < Math.max(reference.length, candidate.length); i += 1) {
+      if (sameValue(reference[i], candidate[i])) continue;
+      return whatMoved(reference[i], candidate[i], [...trail, `number ${i + 1}`]);
+    }
+    return null;
+  }
+  const what = trail.join(' / ');
+  if (typeof reference === 'string' && typeof candidate === 'string') {
+    // Two long strings summarise to their first sixty-odd characters, so if they agree that
+    // far they read the same however differently they end. A window round the first place
+    // they part company says what neither summary can.
+    const spot = firstDifference(reference, candidate);
+    return { what, was: JSON.stringify(spot.was), now: JSON.stringify(spot.now) };
+  }
+  const was = describeValue(reference);
+  const now = describeValue(candidate);
+  return was === now ? null : { what, was, now };
+}
+
+/**
+ * A window round the first character two pieces of text stop agreeing at, with enough either
+ * side to recognise the place.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {{was: string, now: string}}
+ */
+function firstDifference(a, b) {
+  // Short enough to read whole, so read it whole. A window round the difference is only
+  // worth its ellipses when there is genuinely too much text to print.
+  if (a.length <= 70 && b.length <= 70) return { was: a, now: b };
+  let at = 0;
+  while (at < a.length && at < b.length && a[at] === b[at]) at += 1;
+  const from = Math.max(0, at - 20);
+  /** @param {string} text */
+  const window = (text) => `${from > 0 ? '…' : ''}${text.slice(from, at + 40)}${at + 40 < text.length ? '…' : ''}`;
+  return { was: window(a), now: window(b) };
+}
+
+/**
+ * A value made of named fields, as opposed to a list, a number, or a piece of text.
+ *
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isSetOfDetails(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
 /**

package/src/v2/coverage.js

@@ -98,7 +98,14 @@ import { listBuilds, listCaptures, loadCapture, referencePointer } from './store
  * @property {string} [buildId]
  * @property {string[]} paths                 Non-contract observation addresses, and every
  *                                            prefix of each, so a lookup is one set hit.
- * @property {string[]} [doors]               Door keys the journey's steps name. See doorKey.
+ * @property {string[]} [doors]               Door keys the journey's steps name, for steps that
+ *                                            named a door with nothing to tell apart from
+ *                                            another of the same name. See doorKey.
+ * @property {string[]} [doorAddresses]       Full door addresses, for steps that were specific
+ *                                            enough to build one. A route step knows its verb,
+ *                                            and GET /x and POST /x are two doors that share a
+ *                                            doorKey — so a step that knows which one it knocked
+ *                                            on lands here instead, and the other stays shut.
  * @property {string[]} [touchedFiles]
  * @property {string[]} [touchedFunctions]    'file:name', from the suite's own coverage.
  * @property {number} [functionsNotListed]    Functions that ran and were cut from the list to
@@ -412,9 +419,21 @@ export function walkFromCapture(capture, journey) {
     paths: touched.paths,
   };
   if (journey?.steps) {
-    walk.doors = journey.steps
-      .filter((s) => typeof s.door === 'string' && typeof s.kind === 'string')
-      .map((s) => doorKey({ kind: String(s.kind), name: String(s.door) }));
+    // Two lists, because a doorKey is kind and name only. That is right for an IPC channel or
+    // an exported name, where the name IS the door; it is wrong for a route, where GET /basket
+    // and POST /basket share a key and are two different doors. A step that knows which one it
+    // knocked on says so with `doorDetail`, and goes in the exact list — otherwise walking GET
+    // would report POST as walked too, which is the coverage ledger lying in the one direction
+    // it must never lie in.
+    const named = journey.steps.filter((s) => typeof s.door === 'string' && typeof s.kind === 'string');
+    const exact = named.filter((s) => typeof s.doorDetail === 'string' && s.doorDetail !== '');
+    const byName = named.filter((s) => typeof s.doorDetail !== 'string' || s.doorDetail === '');
+    if (byName.length > 0) walk.doors = byName.map((s) => doorKey({ kind: String(s.kind), name: String(s.door) }));
+    if (exact.length > 0) {
+      walk.doorAddresses = exact.map((s) =>
+        doorAddress({ kind: String(s.kind), name: String(s.door), detail: String(s.doorDetail), file: typeof s.doorFile === 'string' ? s.doorFile : undefined }),
+      );
+    }
   }
   if (journey?.touched?.files) walk.touchedFiles = journey.touched.files;
   if (journey?.touched?.functions) walk.touchedFunctions = journey.touched.functions;
@@ -442,7 +461,7 @@ const ADDRESS_RULE = new Set(['ipc', 'route', 'export', 'env']);
  * @returns {{state: 'opened'|'reached', how: string}|null}
  */
 export function whatTheWalkDid(door, walk, paths) {
-  if (walk.doors?.includes(doorKey(door))) {
+  if (walk.doorAddresses?.includes(door.address) || walk.doors?.includes(doorKey(door))) {
     return { state: 'opened', how: `"${walk.journey}" has a step that knocks on it directly.` };
   }
   if (ADDRESS_RULE.has(door.kind)) {
@@ -783,172 +802,6 @@ export async function ledger(store, product, opts = {}) {
   });
 }
 
-/**
- * The same picture, for one run.
- *
- * A verdict does not carry its observations, so on its own this can only report totals — and
- * it says `knows: 'counts only'` rather than pretending to a per-door answer it does not
- * have. Hand it the doors and the walks from that run and it upgrades to the full ledger.
- *
- * @param {Verdict} verdict
- * @param {{doors?: (Door|DoorFact)[], walks?: Walk[]}} [opts]
- * @returns {Ledger}
- */
-export function coverageOf(verdict, opts = {}) {
-  /** @type {Coverage} */
-  const coverage = verdict.coverage ?? { paths: 0, journeys: 0, byChannel: {}, gaps: [] };
-  if (opts.doors && opts.walks) {
-    const doors = opts.doors.map((d) => ('address' in d ? d : doorFact(d)));
-    return buildLedger({
-      product: verdict.product,
-      doors,
-      walks: opts.walks,
-      byChannel: coverage.byChannel,
-      captures: opts.walks.length,
-      builds: 1,
-      at: verdict.startedAt,
-      caveats: [`This is one run — ${nameRun(verdict)} — not everything this tool has ever walked.`],
-      gaps: coverage.gaps ?? [],
-    });
-  }
-
-  const doors = coverage.doorsKnown ?? 0;
-  const opened = coverage.doorsWalked ?? 0;
-  /** @type {string[]} */
-  const caveats = [
-    `This is one run — ${nameRun(verdict)} — not everything this tool has ever walked.`,
-    'A verdict carries totals rather than addresses, so this cannot name which doors were left shut. Call ledger(store, product) for that.',
-  ];
-  if (verdict.mode === 'stored-record') {
-    caveats.push(
-      verdict.modeWarning
-        ?? 'The old build was not booted. This run was compared against observations stored the last time it ran, which lets back in every difference that comes from the day being different.',
-    );
-  }
-  if (doors === 0) {
-    caveats.push('Nothing counted the doors on this run, so there is no denominator, and "nothing changed" here means only "nothing I looked at changed".');
-  }
-
-  return {
-    product: verdict.product,
-    at: verdict.startedAt,
-    knows: 'counts only',
-    doors,
-    opened,
-    reached: 0,
-    never: Math.max(0, doors - opened),
-    unwalkable: 0,
-    work: Math.max(0, doors - opened),
-    irreversible: 0,
-    entries: [],
-    byKind: {},
-    journeys: coverage.journeys ?? 0,
-    byJourneySource: {},
-    byChannel: coverage.byChannel ?? {},
-    captures: coverage.journeys ?? 0,
-    builds: 1,
-    caveats,
-    gaps: coverage.gaps ?? [],
-  };
-}
-
-/**
- * @param {Verdict} verdict
- * @returns {string}
- */
-function nameRun(verdict) {
-  const candidate = verdict.candidate?.version || verdict.candidate?.id || 'this build';
-  return `${candidate}, ${verdict.mode === 'paired' ? 'against the old build booted live' : 'against the stored record'}`;
-}
-
-// ---------------------------------------------------------------------------
-// Saying it out loud
-// ---------------------------------------------------------------------------
-
-/**
- * The ledger in plain English, honest and specific, one line each.
- *
- * The headline is the number nobody wants to publish, and it goes first on purpose:
- * "452 doors, 61 opened, 391 never opened. A clean result says nothing about those 391."
- *
- * There is no percentage anywhere in here, and that is not an oversight. A percentage
- * invites a target, a target invites gaming, and a gamed coverage number is worse than none
- * because somebody believes it.
- *
- * @param {Ledger} led
- * @returns {string[]} join with a space for a paragraph, or a newline for a list
- */
-export function describeCoverage(led) {
-  /** @type {string[]} */
-  const lines = [];
-
-  if (led.doors === 0) {
-    lines.push('Nothing here knows how many doors this product has, so there is no honest way to say how much of it was checked.');
-  } else {
-    const parts = [count(led.doors, 'door'), `${led.opened} opened`];
-    if (led.reached > 0) parts.push(`${led.reached} in code that ran but never addressed`);
-    parts.push(`${led.never} never opened`);
-    lines.push(`${parts.join(', ')}.`);
-    if (led.never > 0) lines.push(`A clean result says nothing about those ${led.never}.`);
-  }
-
-  if (led.unwalkable > 0) {
-    const permanent = led.irreversible > 0
-      ? `${led.irreversible} that would spend money, send a message or destroy something and are stopped at the call on purpose`
-      : 'doors there is nothing to knock on';
-    lines.push(
-      `Of those ${led.never}, ${led.unwalkable} can never be opened from here — settings that are read rather than called, names built while the program runs, and ${permanent}. That leaves ${led.work} that could be covered and are not.`,
-    );
-  } else if (led.work > 0 && led.doors > 0) {
-    lines.push(`All ${led.work} of the unopened ones could be covered.`);
-  }
-
-  // Every kind, not the worst four. There are five kinds of door in the whole tool, so
-  // cutting the list saved one line and dropped a whole category of the product out of the
-  // only sentence that says how much of it is covered.
-  const kinds = Object.entries(led.byKind)
-    .filter(([, k]) => k.doors > 0)
-    .sort((a, b) => b[1].never - a[1].never)
-    .map(([kind, k]) => `${k.opened} of ${k.doors} ${k.doors === 1 ? KIND_ONE[kind] ?? kind : KIND_MANY[kind] ?? kind}`);
-  if (kinds.length > 0) lines.push(`By kind: ${kinds.join(', ')}.`);
-
-  if (led.journeys === 0) {
-    lines.push('No journey has ever been walked against this product, so nothing here rests on anything.');
-  } else {
-    const sources = Object.entries(led.byJourneySource)
-      .filter(([, n]) => n > 0)
-      .sort((a, b) => b[1] - a[1])
-      .map(([source, n]) => `${n} ${SOURCE_PHRASE[source] ?? source}`);
-    lines.push(
-      `${count(led.journeys, 'journey')} produced ${count(led.captures, 'capture')}${sources.length > 0 ? ` — ${sources.join(', ')}` : ''}.`,
-    );
-  }
-
-  for (const caveat of led.caveats) lines.push(caveat);
-  if (led.gaps.length > 0) {
-    lines.push(`${count(led.gaps.length, 'other thing')} could not be looked at, and each one says what would fix it.`);
-  }
-  return lines;
-}
-
-/** @type {Record<string, string>} */
-const SOURCE_PHRASE = {
-  code: 'read out of the code',
-  suite: "harvested from the project's own tests",
-  recorded: 'recorded from a real session',
-  explored: 'found by an agent exploring',
-  unknown: 'of unrecorded origin',
-};
-
-/**
- * @param {number} n
- * @param {string} noun
- * @returns {string}
- */
-function count(n, noun) {
-  return `${n} ${noun}${n === 1 ? '' : 's'}`;
-}
-
 // ---------------------------------------------------------------------------
 // The work queue
 // ---------------------------------------------------------------------------
@@ -958,7 +811,7 @@ function count(n, noun) {
  * @property {number} [worst]              How many jobs to hand back. Default 12.
  * @property {boolean} [includeUnwalkable] Include doors nothing here could ever open. Off:
  *                                         they belong in the honest total, not in a queue,
- *                                         and describeCoverage names them anyway.
+ *                                         and the ledger counts them either way.
  * @property {number} [minDoors]           Ignore families smaller than this. Default 1.
  */
 
@@ -1108,11 +961,25 @@ export function toCoverage(led, opts = {}) {
   const out = [...led.gaps];
   if (led.doors > 0 && led.never > 0) {
     out.push({
-      what: `${led.never} of this product's ${led.doors} doors have never been opened by this tool.`,
-      why: 'No journey reaches them, so a break behind one of them would not show up in any run — clean or otherwise.',
+      // A product with one door read "1 of this product's 1 doors have never been opened",
+      // which is the sentence a reader stops believing the rest of the report over. The count
+      // is the whole point of the line, so it is worth the four words it costs to say it in
+      // English.
+      what: led.doors === 1
+        ? "This product's only door has never been opened by this tool."
+        : led.never === 1
+          ? `1 of this product's ${led.doors} doors has never been opened by this tool.`
+          : `${led.never} of this product's ${led.doors} doors have never been opened by this tool.`,
+      why: led.never === 1
+        ? 'No journey reaches it, so a break behind it would not show up in any run — clean or otherwise.'
+        : 'No journey reaches them, so a break behind one of them would not show up in any run — clean or otherwise.',
       unlockedBy: led.work > 0
-        ? `${led.work} of them could be covered by journeys that reach them — read out of your source, or named by hand in a journeys file.`
-        : 'Nothing. Every one of them is a door this tool cannot open from here, and each says why.',
+        ? led.work === 1
+          ? 'It could be covered by a journey that reaches it — read out of your source, or named by hand in a journeys file.'
+          : `${led.work} of them could be covered by journeys that reach them — read out of your source, or named by hand in a journeys file.`
+        : led.never === 1
+          ? 'Nothing. It is a door this tool cannot open from here, and it says why.'
+          : 'Nothing. Every one of them is a door this tool cannot open from here, and each says why.',
       channel: 'contract',
       doors: led.never,
     });