staysfixed 0.9.1 → 0.11.0

package/src/v2/reference.js

@@ -55,6 +55,7 @@ import { StaysFixedError } from '../core/errors.js';
 import { safeName } from '../core/paths.js';
 import { setReference, referencePointer, loadBuild, listBuilds, listCaptures, loadCapture, ensureStore } from './store.js';
 import { measureWobble } from './observation.js';
+import { isAnswer, answeredAnything, CHANNELS_ONLY_A_RUNNING_PRODUCT_FILLS } from './refusal.js';
 
 /** @typedef {import('./types.js').Store} Store */
 /** @typedef {import('./types.js').Capture} Capture */
@@ -142,7 +143,7 @@ const MAX_CHECK_LOG = 40;
  *
  * @typedef {object} CutDecision
  * @property {boolean} ok
- * @property {'clean'|'accounted-for'|'already-the-reference'|'never-checked'|'broken'|'blocked'|'not-stored'} state
+ * @property {'clean'|'accounted-for'|'already-the-reference'|'never-checked'|'broken'|'blocked'|'not-stored'|'nothing-observed'} state
  * @property {string} why             Plain English, whichever way it went.
  * @property {string} [refusal]       The full refusal, present only when `ok` is false.
  * @property {boolean} needsForce     True when only `force: true` would get past this.
@@ -309,6 +310,48 @@ async function withLock(lock, work) {
   }
 }
 
+/**
+ * Which journeys of a build actually saw the product, and which only ever met a refusal.
+ *
+ * `contract` and `counters` are deliberately not counted: those are doors read out of the
+ * SOURCE, and a door read is not a door opened — which is coverage.js's own rule, one notch
+ * further along. Only the channels a running product fills can prove it ran.
+ *
+ * @param {Store} store
+ * @param {string} buildId
+ * @returns {Promise<{walked: string[], refused: string[]}>}
+ */
+async function whatWasActuallyObserved(store, buildId) {
+  /** @type {string[]} */
+  const walked = [];
+  /** @type {string[]} */
+  const refused = [];
+  try {
+    const { listCaptures, latestCapture } = await import('./store.js');
+    const refs = await listCaptures(store, { buildId });
+    for (const journey of [...new Set(refs.map((/** @type {any} */ r) => r.journey))].sort()) {
+      const capture = await latestCapture(store, { buildId, journey });
+      if (!capture) continue;
+      const fromTheProduct = (capture.observations ?? []).filter((/** @type {any} */ o) =>
+        CHANNELS_ONLY_A_RUNNING_PRODUCT_FILLS.has(o.channel),
+      );
+      if (fromTheProduct.length === 0) continue;
+      // Decided on the VALUE now, not on `meta.refused`. The two are different questions and
+      // this one was reading the wrong one: `meta.refused` is also stamped on an observation
+      // holding a REAL value that was only partly read — a stdout too big to keep whole — so
+      // a journey whose only product-channel observation was a truncated one was filed as
+      // having refused, and a healthy release could be blocked by a large log file. What
+      // matters here is whether there is an answer in the capture at all.
+      if (answeredAnything(capture)) walked.push(journey);
+      else refused.push(journey);
+    }
+  } catch {
+    // What could not be read is left out rather than guessed at in either direction: this
+    // gate must never refuse a healthy release because the store would not open.
+  }
+  return { walked, refused };
+}
+
 /**
  * A sortable, file-safe id for one cut.
  * @param {Date} [now]
@@ -382,6 +425,10 @@ export async function measureStability(store, buildId) {
   let paths = 0;
   let steady = 0;
   let measuredJourneys = 0;
+  // Addresses the product could not answer at, which used to be counted as steady. Kept as
+  // its own number so the note can say what came off rather than showing a smaller total
+  // with no explanation.
+  let refusedPaths = 0;
 
   for (const journey of journeys) {
     const looked = await twoRunsOf(store, buildId, journey);
@@ -420,9 +467,25 @@ export async function measureStability(store, buildId) {
     }
 
     measuredJourneys++;
-    const seen = wobble.steady + wobble.unstable.length;
+    // A REFUSAL IS NOT AN ADDRESS THAT ANSWERED THE SAME WAY TWICE.
+    //
+    // `measureWobble` compares the two stored runs as values, and two refusals are equal
+    // values, so every address the product could not answer at came back inside
+    // `wobble.steady`. That number is what `staysfixed ship` prints as its headline, and on
+    // 2026-08-31 it printed "All 7 addresses it was watched at answered the same way twice"
+    // about a command that threw on its first line and had answered at none of them. The
+    // sentence was true and meant nothing, and it is the sentence that made a refusal the
+    // definition of working. Refusals are subtracted from `steady` here so the reference
+    // records how much really held still, and the count of them is kept so the note can say
+    // what was taken off rather than quietly showing a smaller number.
+    const refusedHere = pair.a.observations.filter(
+      (o) => CHANNELS_ONLY_A_RUNNING_PRODUCT_FILLS.has(o.channel) && !isAnswer(o.value),
+    ).length;
+    const steadyAnswers = Math.max(0, wobble.steady - refusedHere);
+    refusedPaths += refusedHere;
+    const seen = steadyAnswers + wobble.unstable.length;
     paths += seen;
-    steady += wobble.steady;
+    steady += steadyAnswers;
     for (const p of wobble.unstable) unstablePaths.push(p);
 
     /** @type {JourneyStability} */
@@ -430,7 +493,7 @@ export async function measureStability(store, buildId) {
       journey,
       measured: true,
       paths: seen,
-      steady: wobble.steady,
+      steady: steadyAnswers,
       unstableCount: wobble.unstable.length,
       unstable: wobble.unstable.slice(0, MAX_UNSTABLE_LISTED),
       runs: wobble.runs,
@@ -451,7 +514,7 @@ export async function measureStability(store, buildId) {
     unstable: unstablePaths.length,
     unstablePaths: listed,
     byJourney,
-    note: stabilityNote(measured, journeys.length, measuredJourneys, steady, unstablePaths.length),
+    note: stabilityNote(measured, journeys.length, measuredJourneys, steady, unstablePaths.length, refusedPaths),
   };
 }
 
@@ -464,9 +527,10 @@ export async function measureStability(store, buildId) {
  * @param {number} measuredJourneys
  * @param {number} steady
  * @param {number} unstable
+ * @param {number} [refused]  Addresses the product could not answer at, which are not steady.
  * @returns {string}
  */
-function stabilityNote(measured, journeys, measuredJourneys, steady, unstable) {
+function stabilityNote(measured, journeys, measuredJourneys, steady, unstable, refused = 0) {
   if (journeys === 0) {
     return 'Nothing has ever been walked against this build, so this reference has no record of what it does or how steady it is.';
   }
@@ -477,11 +541,22 @@ function stabilityNote(measured, journeys, measuredJourneys, steady, unstable) {
     measuredJourneys < journeys
       ? ` ${journeys - measuredJourneys} of its ${journeys} ${plural(journeys, 'journey', 'journeys')} ran only once and carry no steadiness record.`
       : '';
+  // Said out loud, always, when there were any. The headline of `staysfixed ship` is built
+  // from this sentence, and on 2026-08-31 it read "all 7 addresses it was watched at
+  // answered the same way twice" about a product that answered at none of them — the
+  // refusals were being counted as steady, and two refusals do agree with each other.
+  const held =
+    refused > 0
+      ? ` ${refused} further ${plural(refused, 'address', 'addresses')} ${plural(refused, 'was', 'were')} not counted at all: the product refused there, and a refusal is not an answer that held still.`
+      : '';
+  if (steady === 0 && unstable === 0) {
+    return `Measured across ${measuredJourneys} ${plural(measuredJourneys, 'journey', 'journeys')}: NOT ONE address answered. Everything this build was asked came back a refusal, so this reference records what could not be read rather than what the product does.${held}${partial}`;
+  }
   if (unstable === 0) {
-    const all = steady === 1 ? 'the one address it was watched at' : `all ${steady} addresses`;
-    return `Measured across ${measuredJourneys} ${plural(measuredJourneys, 'journey', 'journeys')}: ${all} answered the same way twice.${partial}`;
+    const all = steady === 1 ? 'the one address it answered at' : `all ${steady} addresses it answered at`;
+    return `Measured across ${measuredJourneys} ${plural(measuredJourneys, 'journey', 'journeys')}: ${all} answered the same way twice.${held}${partial}`;
   }
-  return `Measured across ${measuredJourneys} ${plural(measuredJourneys, 'journey', 'journeys')}: ${steady} ${plural(steady, 'address', 'addresses')} answered the same way twice and ${unstable} did not. ${unstable === 1 ? 'That one was' : `Those ${unstable} were`} already unpredictable when this shipped, so a later run must not blame a change for ${plural(unstable, 'it', 'them')}.${partial}`;
+  return `Measured across ${measuredJourneys} ${plural(measuredJourneys, 'journey', 'journeys')}: ${steady} ${plural(steady, 'address', 'addresses')} answered the same way twice and ${unstable} did not. ${unstable === 1 ? 'That one was' : `Those ${unstable} were`} already unpredictable when this shipped, so a later run must not blame a change for ${plural(unstable, 'it', 'them')}.${held}${partial}`;
 }
 
 /**
@@ -879,6 +954,43 @@ export async function shouldCut(store, product, build) {
     };
   }
 
+  // AND: did the product actually do anything while it was watched?
+  //
+  // The three questions above — was there a check, was it blocked, did it leave anything
+  // unaccounted for — are all answered by a run in which EVERY journey refused exactly the
+  // way a healthy run answers them. It was not blocked: it ran to the end. It found no
+  // differences: there was nothing to differ. So `ship` blessed a product that cannot start,
+  // and every later check then compared refusal against refusal, found them equal, and
+  // reported "Nothing that worked has changed" about a server that throws on the first line.
+  // Measured 2026-08-31, and the recovery was worse than the lie: fixing the product produced
+  // thirteen findings nobody caused.
+  //
+  // The same gate lives in ship.js, where it was written. It belongs here too, because
+  // `cutReference` is exported and the ship command is not its only caller — a gate one
+  // caller deep is a gate the next caller walks around.
+  const saw = await whatWasActuallyObserved(store, buildId);
+  if (saw.walked.length === 0 && saw.refused.length > 0) {
+    return {
+      ok: false,
+      state: 'nothing-observed',
+      needsForce: true,
+      buildId,
+      checkedAt: check.at,
+      findings: check.unaccounted,
+      why: `Nothing was actually observed of ${name}.`,
+      // The same sentence ship.js uses, deliberately word for word. Two gates that catch the
+      // same thing must not describe it two ways: whichever one fires, the person reads the
+      // same explanation.
+      refusal: [
+        `Refusing to make ${name} the standard for ${product}: the run behind it never got the product to do anything.`,
+        `All ${saw.refused.length} of the ${saw.refused.length === 1 ? 'journey' : 'journeys'} on record for this build came back refused — it did not start, or could not be reached — so what would be written down as "working" is the words "could not be read": ${saw.refused.slice(0, 4).join(', ')}${saw.refused.length > 4 ? ', and more' : ''}.`,
+        'A standard made of refusals is a standard that says nothing: there is no answer on either side of any address, so a later check watches none of it. It no longer comes back looking clean — it says so in its coverage list, on every run, for as long as this reference stands.',
+        RUBBER_STAMP,
+        'Get the product running, run `staysfixed check`, and ship again.',
+      ].join(' '),
+    };
+  }
+
   if (check.unaccounted > 0) {
     const sealed = check.sealed ?? 0;
     return {
@@ -1046,12 +1158,19 @@ function summarise(cut, name, decision) {
   else parts.push('Nothing was being compared against before this — from now on it is.');
 
   if (cut.stability.measured) {
+    // "WATCHED AT" WAS THE WRONG WORD and it mattered. A build was watched at every address
+    // it was asked about, including every one it refused to answer, and two refusals do
+    // answer the same way twice — so this line said "all 7 addresses it was watched at
+    // answered the same way twice" about a command that threw on its first line and answered
+    // at none of them (measured 2026-08-31). It counts answers now, and it says so.
     parts.push(
-      cut.stability.unstable === 0
-        ? cut.stability.steady === 1
-          ? 'The one address it was watched at answered the same way twice.'
-          : `All ${cut.stability.steady} addresses it was watched at answered the same way twice.`
-        : `${cut.stability.unstable} of the ${cut.stability.paths} ${plural(cut.stability.paths, 'address', 'addresses')} it was watched at ${plural(cut.stability.unstable, 'was', 'were')} already unpredictable, and that is written down so nothing blames a future change for ${plural(cut.stability.unstable, 'it', 'them')}.`
+      cut.stability.steady === 0 && cut.stability.unstable === 0
+        ? 'NOT ONE address it was asked about gave an answer, so this reference records what could not be read rather than what the product does.'
+        : cut.stability.unstable === 0
+          ? cut.stability.steady === 1
+            ? 'The one address it answered at answered the same way twice.'
+            : `All ${cut.stability.steady} addresses it answered at answered the same way twice.`
+          : `${cut.stability.unstable} of the ${cut.stability.paths} ${plural(cut.stability.paths, 'address', 'addresses')} it answered at ${plural(cut.stability.unstable, 'was', 'were')} already unpredictable, and that is written down so nothing blames a future change for ${plural(cut.stability.unstable, 'it', 'them')}.`
     );
   } else {
     parts.push('It carries no steadiness record, so "this used to be steady and now it wobbles" cannot be reported against it.');

package/src/v2/refusal.js

@@ -0,0 +1,389 @@
+/**
+ * "The question could not be answered" is not an answer.
+ *
+ * This file exists because of one measurement, taken on 2026-08-31 against a Node command
+ * that threw on its first line. `staysfixed check` recorded what it saw, `staysfixed ship`
+ * blessed it, and from that moment on the tool reported a product that could not start as
+ * one where nothing had changed. Three separate wrongs came out of one cause, and all three
+ * were reproduced end to end before a line of this was written:
+ *
+ *   1. TWO REFUSALS COMPARE EQUAL. A refusal was stored as an ordinary value — the words
+ *      "not checked — the thing being observed fell over before it could be read", or a
+ *      crash record, or nothing at all — and two of those are the same string. So the diff
+ *      found no difference and the run ended "Nothing that worked has changed. 7 addresses
+ *      checked", about a product whose entire output had been rewritten in between.
+ *   2. SHIP BLESSED IT. The stability record said "all 7 addresses it was watched at
+ *      answered the same way twice", which was true and meant nothing: two refusals do
+ *      answer the same way twice. A refusal became the definition of working.
+ *   3. FIXING THE PRODUCT PRODUCED FINDINGS NOBODY CAUSED. The day it started answering,
+ *      every real value differed from the stored refusal. Four of them on the tiny fixture,
+ *      thirteen on the three-route server, and one of them landed in the money class, which
+ *      no agent may wave through — so a phantom went to a person and stayed there.
+ *
+ * THE RULE, and it is one rule. A refusal is a DIFFERENT KIND OF THING from a value. It is
+ * never compared with a value, never compared with another refusal as if both were answers,
+ * and never written down as what "working" means. It is a hole, with the reason attached,
+ * exactly the way this tool already treats a guard that timed out.
+ *
+ * WHY A MARKED OBJECT AND NOT A SPECIAL STRING. A product's own output is a string, and any
+ * sentinel string a product could print by accident is a sentinel that stops working the day
+ * somebody prints it. An observed value can already be a plain object, so a plain object with
+ * a reserved key costs nothing on disk, survives the JSONL store untouched, and cannot be
+ * produced by a product talking about itself. `meta.refused` is not enough on its own either:
+ * meta is never compared, and it is also set on observations that hold a REAL value that was
+ * only partly read — a truncated stdout is still an answer, and treating it as a refusal
+ * would throw away a comparison that works.
+ *
+ * TWO KINDS LIVE HERE, because there are two ways an address can be incomparable and only
+ * one of them is a hole:
+ *
+ *   NO ANSWER      the adapter was asked and could not answer. A hole. Counted, reported,
+ *                  and refused at ship.
+ *   NEVER COMPARED the tool has an answer and has decided on purpose never to compare it —
+ *                  how long something took, which measures the machine as much as the
+ *                  product. Not a hole; the coverage list already explains it. It still must
+ *                  never become a difference, and on 2026-08-31 it did: `count.pay.duration`
+ *                  APPEARED where the reference had no record of that journey at all, and
+ *                  the finding came back classed as money.
+ */
+
+import { diffCaptures, indexByPath, splitPath } from './observation.js';
+
+/**
+ * @typedef {import('./types.js').Observation} Observation
+ * @typedef {import('./types.js').ObservedValue} ObservedValue
+ * @typedef {import('./types.js').Capture} Capture
+ * @typedef {import('./types.js').Difference} Difference
+ * @typedef {import('./types.js').Channel} Channel
+ */
+
+/**
+ * The reserved key. An at-sign leads it because no path segment, no header name and no
+ * JSON body a product prints has ever started one of its own keys that way, and because it
+ * reads as "this is the tool talking, not the product" to anyone who opens the store.
+ */
+export const NO_ANSWER_KEY = '@no-answer';
+
+/**
+ * The two sentences the adapters have been writing since before this file existed.
+ *
+ * They are recognised rather than left behind, for two reasons. Every store on every machine
+ * already holds them — a reference cut last week is made of these strings, and a fix that
+ * only understands the new shape would report that whole reference as changed the first time
+ * it ran. And `notCovered` lives in the adapter contract, which this lane does not own; until
+ * that one line is changed, this is what a refusal arrives as.
+ */
+export const NOT_CHECKED_PREFIX = 'not checked — ';
+export const NEVER_COMPARED_PREFIX = 'not compared — ';
+
+/** What a value is, for the one purpose of deciding whether it may be compared. */
+/** @typedef {'answer'|'no-answer'|'never-compared'} Comparability */
+
+/**
+ * The channels a running product has to fill. A door read out of the source is not a door
+ * opened, so `contract` and `counters` prove nothing about whether anything ran — which is
+ * the same line `shouldCut` and `ship` already draw, written here once so all three cannot
+ * come to disagree about it.
+ *
+ * @type {Set<Channel>}
+ */
+export const CHANNELS_ONLY_A_RUNNING_PRODUCT_FILLS = new Set(
+  /** @type {Channel[]} */ (['meaning', 'effects', 'complaints', 'results', 'pixels']),
+);
+
+/**
+ * A refusal, as a value.
+ *
+ * @param {string} reason  Short and machine-readable: `crashed`, `refused`, `irreversible`.
+ * @param {string} why     One plain sentence a person reads.
+ * @returns {ObservedValue}
+ */
+export function noAnswer(reason, why) {
+  return { [NO_ANSWER_KEY]: String(reason || 'refused'), why: String(why || '') };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * What kind of thing is this value?
+ *
+ * Everything that is not explicitly one of the two incomparable kinds is an answer. That
+ * direction of default is deliberate: mistaking an answer for a refusal loses a real
+ * comparison silently, which is the failure this whole tool exists to prevent, so the new
+ * kind has to be claimed rather than guessed at.
+ *
+ * @param {unknown} value
+ * @returns {Comparability}
+ */
+export function comparability(value) {
+  if (isPlainObject(value) && typeof value[NO_ANSWER_KEY] === 'string') {
+    return value[NO_ANSWER_KEY] === 'measures the machine' ? 'never-compared' : 'no-answer';
+  }
+  if (typeof value === 'string') {
+    if (value.startsWith(NOT_CHECKED_PREFIX)) return 'no-answer';
+    if (value.startsWith(NEVER_COMPARED_PREFIX)) return 'never-compared';
+  }
+  return 'answer';
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isNoAnswer(value) {
+  return comparability(value) === 'no-answer';
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isNeverCompared(value) {
+  return comparability(value) === 'never-compared';
+}
+
+/**
+ * May these two values be put side by side at all?
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isAnswer(value) {
+  return comparability(value) === 'answer';
+}
+
+/**
+ * Why there is no answer here, in the words the adapter used.
+ *
+ * @param {unknown} value
+ * @param {Observation} [observation]  Its meta carries a longer reason when the adapter set one.
+ * @returns {string}
+ */
+export function whyNoAnswer(value, observation) {
+  if (isPlainObject(value) && typeof value.why === 'string' && value.why) return value.why;
+  if (typeof value === 'string' && value.startsWith(NOT_CHECKED_PREFIX)) {
+    return value.slice(NOT_CHECKED_PREFIX.length);
+  }
+  if (typeof value === 'string' && value.startsWith(NEVER_COMPARED_PREFIX)) {
+    return value.slice(NEVER_COMPARED_PREFIX.length);
+  }
+  const meta = /** @type {{refusedWhy?: string}|undefined} */ (observation?.meta);
+  return meta?.refusedWhy ?? 'no reason was recorded';
+}
+
+/**
+ * Turn the old string form into the marked form, leaving everything else exactly as it is.
+ *
+ * Used on the way OUT of the store, so that one shape reaches the comparison, the reference
+ * and the report however old the file it came from. It is not a migration and it never
+ * rewrites anything on disk: the stored line stays as it was written, and this is what the
+ * reader hands on.
+ *
+ * @param {ObservedValue} value
+ * @returns {ObservedValue}
+ */
+export function asMarkedValue(value) {
+  const kind = comparability(value);
+  if (kind === 'answer') return value;
+  if (isPlainObject(value)) return value;
+  const text = String(value);
+  const prefix = kind === 'no-answer' ? NOT_CHECKED_PREFIX : NEVER_COMPARED_PREFIX;
+  const why = text.slice(prefix.length);
+  return { [NO_ANSWER_KEY]: kind === 'never-compared' ? 'measures the machine' : 'refused', why };
+}
+
+/**
+ * The observations of a capture, or the list itself when that is what was handed over.
+ * @param {Capture|Observation[]} x
+ * @returns {Observation[]}
+ */
+function observationsOf(x) {
+  return Array.isArray(x) ? x : x.observations;
+}
+
+/**
+ * The addresses an adapter uses to say, in one place, whether the product was reached at all.
+ *
+ * `cli.<journey>.ran at all` and `api.<journey>.answered at all` are a convention that
+ * predates this file — `cluster.js` groups them and `check.js` reads them — and it is exactly
+ * the sentence needed here. An adapter is the only thing that knows whether it got to the
+ * product, and this is where it already says so.
+ */
+const REACHED_THE_PRODUCT_AT_ALL = ['ran at all', 'answered at all'];
+
+/**
+ * Did this walk get the product to say anything at all?
+ *
+ * Three ways to answer no, and the first one is the one that needs an adapter's word for it:
+ *
+ *   1. The adapter said outright that it never reached the product — a refusal at
+ *      `<surface>.<journey>.ran at all`. This is the case a channel count cannot see. A
+ *      command that throws on its first line still fills the complaints channel with a real
+ *      stack trace and a real exit code, and those ARE facts, and they are facts about a
+ *      crash rather than about the product. Two builds that crash identically then agree at
+ *      every address, and on 2026-08-31 that agreement came back as "Nothing that worked has
+ *      changed" over a product whose entire output had been rewritten in between.
+ *   2. Every product-channel observation it has is a refusal. The adapter was asked and said
+ *      it could not.
+ *   3. Nothing else. A walk with no product-channel observations at all — the source reader,
+ *      which only lists doors it has read — is neither evidence that the product ran nor
+ *      evidence that it would not, so it answers `true` and is left to the coverage ledger,
+ *      which is where a door nobody walked through is already counted.
+ *
+ * @param {Capture|Observation[]} capture
+ * @returns {boolean}
+ */
+export function answeredAnything(capture) {
+  const all = observationsOf(capture);
+  const journey = Array.isArray(capture) ? undefined : capture.journey;
+  for (const o of all) {
+    if (!isNoAnswer(o.value)) continue;
+    if (!REACHED_THE_PRODUCT_AT_ALL.some((tail) => o.path.endsWith(`.${tail}`))) continue;
+    // THIS journey's own address, not any address shaped like one. The adapters build it as
+    // `<surface>.<journey name>.ran at all`, so the second segment names whose walk it is.
+    // Without this check one refusal shaped like the sentence would take down a walk it says
+    // nothing about, and every real difference in that walk would go with it — the whole
+    // point of the change is to stop losing comparisons, not to lose more of them.
+    if (journey === undefined || splitPath(o.path)[1] === journey) return false;
+  }
+  const fromTheProduct = all.filter((o) => CHANNELS_ONLY_A_RUNNING_PRODUCT_FILLS.has(o.channel));
+  if (fromTheProduct.length === 0) return true;
+  return fromTheProduct.some((o) => isAnswer(o.value));
+}
+
+/**
+ * The refusals in a list, so a caller can name them rather than count them.
+ * @param {Capture|Observation[]} capture
+ * @returns {Observation[]}
+ */
+export function refusalsIn(capture) {
+  return observationsOf(capture).filter((o) => isNoAnswer(o.value));
+}
+
+/**
+ * One address that could not be put side by side, and which side was missing.
+ *
+ * @typedef {object} Uncompared
+ * @property {string} path
+ * @property {Channel} channel
+ * @property {'lost'|'recovered'|'never-answered'} kind
+ *   `lost`        — the standard has an answer here and this build has none. Coverage this
+ *                   build took away, and the one shape of this that is bad news.
+ *   `recovered`   — the standard has no answer here and this build does. Good news, and the
+ *                   thing that used to arrive as a pile of findings nobody caused.
+ *   `never-answered` — neither side answered. Silent until today; the comparison covered
+ *                   nothing here and said nothing about it.
+ * @property {string} why
+ * @property {string} [journey]
+ * @property {string} [describe]
+ */
+
+/**
+ * Compare two captures, putting only answers beside answers.
+ *
+ * This is `diffCaptures` with the one rule this file exists for wrapped around it: an address
+ * where either side holds a refusal is not compared at all, and comes back in the second list
+ * instead of the first. Nothing is lost by that — a refusal never carried a fact about the
+ * product — and what is gained is that the tool stops turning "I could not look" into either
+ * "it is fine" or "you broke it", which are the only two things it could say before.
+ *
+ * @param {Capture|Observation[]} reference
+ * @param {Capture|Observation[]} candidate
+ * @returns {{differences: Difference[], uncompared: Uncompared[]}}
+ */
+export function compareAnswers(reference, candidate) {
+  const refIndex = indexByPath(observationsOf(reference));
+  const candIndex = indexByPath(observationsOf(candidate));
+  const journey = Array.isArray(candidate)
+    ? Array.isArray(reference)
+      ? undefined
+      : reference.journey
+    : candidate.journey;
+
+  /** @type {Uncompared[]} */
+  const uncompared = [];
+  // Every address that is incomparable on EITHER side, so it can be taken out of BOTH before
+  // anything is diffed. Filtering only the side that holds the refusal is not enough and was
+  // the first way this was written: drop the reference's refusal and the candidate's real
+  // answer at the same address has nothing opposite it, so it comes back as an address that
+  // has just APPEARED — which is the phantom finding, arriving by a new road.
+  /** @type {Set<string>} */
+  const notComparable = new Set();
+
+  for (const path of new Set([...refIndex.keys(), ...candIndex.keys()])) {
+    const was = refIndex.get(path);
+    const now = candIndex.get(path);
+    const before = was ? comparability(was.value) : 'absent';
+    const after = now ? comparability(now.value) : 'absent';
+    if (before === 'answer' && after === 'answer') continue;
+    if (before === 'answer' && after === 'absent') continue; // vanished — a real finding
+    if (before === 'absent' && after === 'answer') continue; // appeared — a real finding
+    notComparable.add(path);
+    // A value the tool has decided never to compare is not a hole and never a difference,
+    // in any direction. This is the branch that stops `count.<journey>.duration` arriving
+    // as a money-class finding the first time a refused journey starts running.
+    if (before === 'never-compared' || after === 'never-compared') continue;
+
+    /** @type {Uncompared['kind']} */
+    let kind;
+    if (before === 'answer') kind = 'lost';
+    else if (after === 'answer') kind = 'recovered';
+    else kind = 'never-answered';
+
+    const holder = kind === 'lost' ? now : kind === 'recovered' ? was : (now ?? was);
+    const why =
+      kind === 'lost'
+        ? whyNoAnswer(now?.value, now)
+        : kind === 'recovered'
+          ? whyNoAnswer(was?.value, was)
+          : whyNoAnswer(now?.value ?? was?.value, now ?? was);
+
+    /** @type {Uncompared} */
+    const entry = {
+      path,
+      channel: (now ?? was)?.channel ?? 'results',
+      kind,
+      why,
+    };
+    if (journey) entry.journey = journey;
+    const describe = holder?.meta?.describe;
+    if (describe) entry.describe = describe;
+    uncompared.push(entry);
+  }
+
+  uncompared.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+  // Only answers go into the arithmetic. Filtering here rather than inside `diffCaptures`
+  // keeps the one comparison in the tool exactly where the design put it, in observation.js,
+  // and keeps this rule readable in one place instead of threaded through it.
+  const differences = diffCaptures(
+    onlyAnswers(reference, refIndex, notComparable),
+    onlyAnswers(candidate, candIndex, notComparable),
+  );
+
+  return { differences, uncompared };
+}
+
+/**
+ * The same capture with every incomparable address taken out of it, keeping the journey name
+ * so a difference can still say which walk it came from.
+ *
+ * The address list is shared between the two sides on purpose: an address is comparable only
+ * when BOTH sides hold an answer at it, so both sides have to lose it together or the
+ * surviving one reads as having appeared or vanished.
+ *
+ * @param {Capture|Observation[]} capture
+ * @param {Map<string, Observation>} index
+ * @param {Set<string>} notComparable
+ * @returns {Capture|Observation[]}
+ */
+function onlyAnswers(capture, index, notComparable) {
+  const kept = [...index.values()].filter((o) => isAnswer(o.value) && !notComparable.has(o.path));
+  if (Array.isArray(capture)) return kept;
+  return { ...capture, observations: kept };
+}