staysfixed 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,9 +4,162 @@ All notable changes to this project are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the version
 numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.0] — 2026-08-30
 
-Nothing yet.
+The second sweep for silences, done the same way as the first: read all of
+`src/v2` looking for anything that can drop something and then report nothing
+found. Five more were there, and two of them were in the safety machinery
+itself — the gate that decides what an agent may never wave through, and the
+proof that decides whether a change explains a break.
+
+Every fix below has a test that fails against yesterday's code and passes
+against today's. That was checked by putting the old behaviour back, one line at
+a time, in a copy of the repository, and watching each test go red.
+
+### Fixed — silences, second sweep
+
+- **Only the first 80 differences of a finding were read when deciding whether it
+  was one of the five things nobody may wave through.** A cluster can hold
+  hundreds of addresses; a refund sitting at address 150 of 300 was classified
+  ordinary, which means an agent could waive it and it would never reach a
+  person. Every difference is read now. A cap on the one gate that cannot have
+  one is not a performance decision, it is a hole.
+- **The causal proof re-checked five addresses and then spoke for all of them.**
+  A finding of three hundred where the first five went away came back "caused by
+  that change" — a machine-checked reason for an agent to close a break it had
+  only half explained. It re-checks every address now, and when a change explains
+  part of a finding and not the rest it says exactly that, with both numbers. It
+  costs nothing: the journeys were already re-walked and each extra address is one
+  lookup.
+- **A wobble big enough to swallow the comparison was still subtracted, and the
+  run came back clean.** If the second run of the new build falls over, or the
+  product writes hash-named files, or stamps a fresh id on every line, most of its
+  addresses are unsteady, nearly every difference is dropped before anything is
+  compared, and the verdict reads "nothing that already worked has changed". A
+  build that disagrees with itself about more than half of its own addresses now
+  gets **no verdict**: the summary opens with `NO ANSWER FROM THIS RUN`, the
+  reason is a named hole in the coverage, and `ok` is false. No number here
+  decides whether any difference is real — it decides only whether the run has
+  earned the word clean.
+- **Two facts written at one address lost one of them, silently.** Every index in
+  the engine keeps the first observation at a path, so a second one is never
+  compared with anything and a door that broke behind it is invisible. The
+  detector for this was written on the first day of v2 and nothing ever called it.
+  Every walk is checked now and each clash is named — which address, and what the
+  ignored answer was. Identical repeats are not reported, because they hide
+  nothing.
+- **The route reader skipped a folder it could not open, and every route behind
+  it, without a word.** This is the same bug as the one fixed yesterday in the
+  file walk, in a second function that the first fix did not touch. It names the
+  folder now.
+
+### Added
+
+- A twelfth case in the self-check corpus, and a third kind of expectation with
+  it: a product so unsteady that the comparison is thrown away before it happens,
+  where the only honest answer is that the run says nothing. Confirmed to fail
+  against 0.5.0 and pass against this. Measured after the change: twelve of
+  twelve, three times running, with the project's own suite in parallel and the
+  machine's load average between 208 and 343.
+- Six more tests in `test/v2/silences.test.js`, one per fix above, each confirmed
+  red against the previous code.
+
+### Changed
+
+- `readFileRoutes(root)` returns `{ doors, problems }` rather than an array. The
+  problems are folders it could not open, and they are reported as missing
+  coverage by every caller.
+
+### Known, and written down rather than fixed
+
+- What a normalisation rule rubbed out is not itemised per run. The receipt
+  exists in the code and nothing calls it. The rules are in your repository and
+  the capture is stamped with which set it used, so a comparison across a rule
+  change is announced — but a broad rule is still how you go blind on purpose.
+- Ranking reads up to 4,000 source files of up to 400KB. Past that a finding is
+  still reported and still counted; it may just not sort where it deserves to.
+  Nothing is dropped for being far from the change.
+
+## [0.5.0] — 2026-08-30
+
+The release about the one way this tool can be catastrophically wrong: reporting
+nothing while something is broken. Five separate places could do that, and one of
+them could do it permanently.
+
+### Fixed — silences
+
+Each of these produced a clean-looking run while something was invisible.
+
+- **A `git diff` too big to read was treated as no diff at all**, so a large
+  uncommitted change was fingerprinted as a clean checkout of the commit it sat
+  on. If that commit was the reference, the check was comparing the build against
+  itself, and a comparison of a build with itself can only ever come back clean.
+  The diff is now streamed into a hash with no ceiling, and a git command that
+  fails is refused loudly rather than read as "nothing has changed".
+- **A folder with no git in it** gave every build the same identity, with the same
+  consequence, quietly and for ever. It is now refused, with a sentence saying
+  why.
+- **The two ends of a huge output were kept with only a rough size**, so a break
+  in the middle that was thrown away left a byte-identical record. The exact byte
+  count is kept now, and a truncated value is reported as missing coverage rather
+  than passed over.
+- **An adapter that threw while listing what it would walk had its journeys
+  dropped in silence** — a whole surface disappearing from a run whose verdict
+  then read "nothing that worked has changed". It is recorded as a hole, by name.
+- **A folder the source reader could not open was skipped without a word**, taking
+  every door behind it. It is named now, along with any file still too big to read.
+- **The normalisation-rule stamp on a stored capture was written and never read.**
+  Comparing a record tidied up under one set of rules against a run tidied up
+  under another produces differences that are about the rules; the run now says so.
+
+### Changed — how long something took is recorded and never compared
+
+A stopwatch on a shared machine measures how busy the machine is at least as much
+as it measures the product. Measured on the corpus's own fixture: thirty runs of
+the same one-line program on an idle Mac took 48ms to 96ms, against a bucket
+boundary at 100ms — four milliseconds of headroom, so any load at all crossed it.
+That is what made the self-check come back "1 of 9 wrong" one busy evening and
+then pass five times in a row on a quiet machine.
+
+Durations are still measured and still shown, in the sentence beside the address,
+where a person can read them. They are no longer differenced, on any platform.
+**Stays Fixed will not tell you your product got slower.** A build that hangs is
+still caught, because it is stopped for taking too long and how it finished is
+compared exactly, and every counter that comes from the product rather than from
+the clock is compared exactly as before.
+
+### Added
+
+- **Two more cases in the self-check corpus**, eleven in total: a break buried in
+  the middle of an output too big to store, and a build ten times slower that must
+  stay silent. Both were confirmed to fail against the previous code and pass
+  against this one.
+- **The corpus re-runs a case before accusing the engine.** Fail twice and it is a
+  real failure. Behave the second time and it is reported as *could not tell* —
+  not a pass, not a failure, exit code 2 — with the machine's load beside it.
+  Measured after the change: eleven of eleven, three times running, with the
+  project's own test suite in parallel and load average between 227 and 334.
+- `test/v2/silences.test.js`, holding each of the above shut.
+
+## [0.4.0] — 2026-08-30
+
+The difference engine, published. Seven observation channels flattened into one
+address space; the new build run twice so the product's own wobble is measured
+and subtracted rather than guessed at; differences clustered, ranked by distance
+from the changed code, and their cause proven by reverting the suspect change and
+running again. The reference is cut by saying ship, and an agent may waive within
+four gates but can never decide what "working" means. Adapters for processes,
+HTTP, source reading, the web, Electron, Android, iOS and Windows, and a
+self-check corpus of deliberately broken builds.
+
+## [0.3.0] — 2026-08-29
+
+Checks tick off live as they run, and guards show what they assert.
+
+## [0.2.0] — 2026-08-29
+
+Pictures you can look at, motion, and a report that says what was checked rather
+than only how long it took.
 
 ## [0.1.0] — 2026-08-29
 
@@ -57,5 +210,8 @@ not been used by many people yet.
 - No phone or tablet simulators.
 - No hosted service, no dashboard, no accounts.
 
-[Unreleased]: https://github.com/asadev/staysfixed/compare/v0.1.0...HEAD
+[0.5.0]: https://github.com/asadev/staysfixed/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/asadev/staysfixed/compare/v0.3.1...v0.4.0
+[0.3.0]: https://github.com/asadev/staysfixed/compare/v0.2.3...v0.3.0
+[0.2.0]: https://github.com/asadev/staysfixed/compare/v0.1.1...v0.2.0
 [0.1.0]: https://github.com/asadev/staysfixed/releases/tag/v0.1.0

package/README.md

@@ -149,7 +149,7 @@ pretend otherwise.
 | The coverage ledger — every door counted, the unopened ones named, and the sentence saying so on every reply | **Works.** See [what it did not check](#what-it-did-not-check). |
 | Aiming a check at one kind of product, and refusing by name rather than checking something else | **Works.** |
 | Android APKs on an emulator | **The adapter is here.** It reads everything the APK declares with nothing installed and no Java, and where there is an emulator it installs one build at a time and walks it. Whether *this* machine can run one is a separate question, and `doctor` asks the adapter itself rather than keeping a second opinion — most of what it wants installs with a command; accepting Google's licence, once, needs a person. Two emulator snapshots restoring byte-identically is unproven, so Android compares against the stored record and says which mode it used. |
-| The iOS simulator | Not yet. `doctor` says so rather than reporting a green run that never touched the phone. |
+| The iOS simulator | **The adapter is here.** It reads what the app bundle declares with nothing running, and where Xcode and a simulator runtime are present it installs one build at a time, boots it and reads what is on the screen. It is new. Paired running costs two `xcodebuild` passes, so it is for before a release rather than for every edit, and like Android it compares against the stored record and says which mode it used. Ask `doctor` what it is actually covering on your machine before trusting a clean run. |
 | Native Windows GUI (a real Win32 app, not an Electron one) | **The probe is here**, driven over ssh to any machine that reaches a Windows desktop — a WSL shell on one counts, and nothing is installed on it. Windows shows one desktop, so two builds can never run at once: the comparison is genuinely weaker here than anywhere else. |
 
 `staysfixed check` is the front door for both. Version 1's flags still mean
@@ -210,7 +210,7 @@ evidence for something another channel already found.
 | `complaints` | What the product complained about: console messages, errors, crashes, the code it exited with. |
 | `results` | What the product gave back: what it printed, what it answered, what it offers other code. |
 | `contract` | The doors the source says exist: routes, exported functions, message channels. Read without running anything. Free, and exact. |
-| `counters` | Rough counts and rough timings. Deliberately rough — precise timing is noise, not information. |
+| `counters` | Rough counts — files written, calls made, doors answered. Compared exactly. How long something took is **recorded and never compared**: see [what it will never do](#what-it-will-never-do). |
 | `pixels` | What it looked like. Used to show a person a problem another channel already found. |
 
 An address reads left to right, widest thing first:
@@ -321,6 +321,27 @@ verdict reading *nothing that worked has changed*. It is arithmetically true and
 it would let a real regression through. That run comes back as **`NOTHING WAS
 ACTUALLY COMPARED`**, it is not a pass, and it exits non-zero.
 
+### The silences that were found and closed
+
+Every one of these produced a clean-looking run while something was invisible.
+They are listed because a tool like this earns trust by naming the ways it has
+been wrong, not by claiming it never was. All five were found on 2026-08-29 and
+2026-08-30 by reading the whole engine looking for the same shape as the first
+one, and each has a case in the corpus or a test holding it shut.
+
+| It used to | Now |
+| --- | --- |
+| Skip any source file over 2MB **without a word**, then report that it had found no source at all — so a desktop app whose main process is one 3.5MB bundle had all 452 of its message channels silently unread | Reads up to 24MB, and names any file it still cannot open |
+| Skip a folder it could not open, and every door behind it, silently | Names the folder and the reason, as missing coverage |
+| Keep the two ends of a huge output and a **rough** size, so a break in the discarded middle left a byte-identical record | Keeps the exact byte count, and says out loud that only the ends were compared |
+| Drop a whole adapter's journeys when it threw while listing them — a surface disappears and the verdict reads "nothing has changed" | Records it as a hole, by name, in the coverage |
+| Treat a `git diff` too big to read as **no diff**, so a large uncommitted change was fingerprinted as a clean checkout — and if that commit was the reference, the check compared the build against itself and could only ever come back clean | Streams the diff into a hash with no ceiling, and refuses outright rather than guessing. A folder with no git in it is refused for the same reason |
+| Read only the first **80** differences of a cluster when deciding whether it is one of the five things nobody may wave through — so a refund at address 150 of 300 was classified ordinary, and an agent could waive the lot | Reads every difference in the finding. There is no ceiling on the one gate that cannot have one |
+| Re-check the first **five** addresses of a finding when proving whose change caused it, then say "caused by that change" about all three hundred — a machine-checked reason for an agent to close a break it had only half explained | Re-checks every address, and says in words when a change explains part of a finding and not the rest. It costs nothing: the walk already happened |
+| Subtract the new build's own wobble even when the wobble had swallowed the comparison — a second run that fell over makes almost every address unsteady, everything is dropped before it is compared, and the run ends "nothing that already worked has changed" | A build that disagrees with itself about most of its own addresses gets **no verdict**: the run says NO ANSWER FROM THIS RUN, in those words, and is not a pass |
+| Keep the **first** of two facts written at one address and ignore the second, so a door that broke behind a duplicated address could never be compared with anything. The detector for this was written on day one and never called | Every walk is checked for it, and each clash is named in the coverage: which address, and what the ignored answer was |
+| Skip a folder it could not open **while looking for routes**, and every route behind it — the same bug as the one above, in a second place, still silent | Names the folder, and the routes behind it are reported as unread rather than as absent |
+
 ---
 
 ## Aiming a check at one thing
@@ -601,10 +622,32 @@ of it is in [docs/how-v2-works.md](docs/how-v2-works.md).
 A tool that reports "nothing changed" looks exactly like a tool that is broken,
 and there is no way to tell the two apart from the outside. So:
 
-**It has to prove it still catches things.** `staysfixed check --selfcheck` runs
-a corpus of deliberately broken builds and requires the engine to catch every
-one. If it misses any, it says so, and until that is fixed a clean check means
-nothing.
+**It has to prove it still catches things.** `staysfixed check --selfcheck`
+builds twelve tiny products — each a real repository with a working commit and an
+uncommitted change on top, which is the shape an agent actually points this tool
+at — and requires the engine to behave on every one. Eight are breaks it must
+catch. Three are the other half of the same promise: pairs that must produce **no
+findings at all**, because a tool that cries wolf gets switched off, and a tool
+that is switched off catches nothing. The twelfth is the third kind, added on
+2026-08-30: a product so unsteady that the comparison is thrown away before it
+happens, where the only correct answer is that this run says **nothing** — and
+saying "nothing changed" there is the worst thing the tool can do.
+
+**And it has to be honest when it cannot tell.** A case that misbehaves is built
+again from scratch and run again before that becomes an accusation. Fail twice
+and it is reported as a real failure. Behave the second time and it is reported
+as *could not tell* — not a pass, not a failure, exit code 2, with the machine's
+load printed beside it. This exists because the corpus once came back "1 of 9
+wrong" with a test suite running alongside it and then passed five times in a row
+on a quiet machine, and a corpus that can be perturbed by a busy laptop is worth
+nothing on a busy laptop. The cause was found and removed — see
+[what it will never do](#what-it-will-never-do) — and the re-run stayed, so that
+the next machine-shaped thing to creep in lands as "nobody knows" rather than as
+a false accusation people learn to ignore. Measured on 2026-08-30: eleven of
+eleven, three times running, with the project's own suite running in parallel and
+the machine's load average between 227 and 334; and after the second sweep of
+silences, twelve of twelve, three times running, with the suite in parallel again
+and the load average between 208 and 343.
 
 **The unstable app.** `fixtures/unstable-app` is a page built to be impossible to
 observe consistently: a clock ticking ten times a second, an endless spinner, a
@@ -633,6 +676,40 @@ Honestly, so you know before you invest an afternoon.
   by design and permanently. A refusal is reported as a gap in coverage, never as
   a pass.
 - **A migration that destroys data is refused, not run twice.**
+- **It will not tell you your product got slower.** How long something took is
+  recorded and shown to you, and it is never compared. A stopwatch on a shared
+  machine measures how busy the machine is at least as much as it measures the
+  product: measured here, thirty runs of the same one-line program on an idle Mac
+  took between 48ms and 96ms, against a bucket boundary at 100ms. Comparing that
+  invents a slowdown nobody caused every time the machine is busy, and a tool that
+  cries wolf gets switched off. A build that **hangs** is still caught — it gets
+  stopped for taking too long, and how it finished is compared exactly.
+- **A change buried in the middle of a huge output can be missed.** Anything a
+  product prints over 64KB has its two ends kept and compared, plus the exact
+  number of bytes thrown away — so a middle that grew or shrank is caught. A
+  middle that changed without changing its length is not, the whole text is
+  written to the evidence folder either way, and the run says out loud that it
+  only compared the ends.
+- **A build that will not answer the same way twice gets no verdict at all.**
+  Differences at addresses the new build cannot hold steady are dropped — that is
+  the whole design, and it has one failure shape. If the second run falls over,
+  or the product writes hash-named files, or stamps a fresh id on every line, then
+  most of its addresses are unsteady, almost everything is dropped before it is
+  compared, and what is left is not an answer. A run in that state now says **NO
+  ANSWER FROM THIS RUN**, in those words, and is not a pass. Fix it by writing a
+  normalisation rule for whatever is moving, not by trusting the clean-looking run
+  underneath it.
+- **What normalisation rubbed out is not itemised on every run.** The rules are in
+  your repository, they are listed by `staysfixed rules`, and the capture is
+  stamped with which set was used — a run comparing against a record tidied by a
+  different set says so. What it does not yet do is print, per run, every value a
+  rule rewrote. Anything a rule covers is not being watched, and that is the point
+  of the rule; just know that adding a broad one is how you go blind on purpose.
+- **Ranking reads your source, and it gives up on very large trees.** Distance
+  from the code you just changed is what sorts the list, and it reads up to 4,000
+  files of up to 400KB each to work it out. Past that a finding is still reported
+  and still counted — it just may not sort where it deserves to. Nothing is
+  dropped for being far away.
 - **A race that already existed will not show.** Subtracting the wobble floor
   actively hides intermittent bugs. Running the new build twice recovers half of
   this by flagging anything newly unstable. Only half. That is the sharpest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers — as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",

package/src/v2/adapters/contract.js

@@ -46,7 +46,7 @@ export { CHANNELS };
  * Why a thing was not observed. Short vocabulary on purpose: the engine counts these and
  * reports them as holes, and a free-text reason cannot be counted.
  *
- * @typedef {'irreversible'|'missing tool'|'refused'|'too big'|'timed out'|'not supported here'|'crashed'|'needs a sample'} NotCoveredReason
+ * @typedef {'irreversible'|'missing tool'|'refused'|'too big'|'timed out'|'not supported here'|'crashed'|'needs a sample'|'measures the machine'} NotCoveredReason
  */
 
 /** @type {Record<NotCoveredReason, string>} */
@@ -59,6 +59,8 @@ export const NOT_COVERED_MEANING = Object.freeze({
   'not supported here': 'this platform cannot be observed this way, and saying so is the honest answer',
   crashed: 'the thing being observed fell over before it could be read',
   'needs a sample': 'a real value has to be supplied before this can be tried at all',
+  'measures the machine':
+    'a stopwatch measures how busy this machine was at least as much as it measures the product, so the number is recorded and never compared',
 });
 
 // ---------------------------------------------------------------------------
@@ -465,6 +467,61 @@ export function timeBucket(ms) {
   return 'over five minutes';
 }
 
+/**
+ * How long something took, recorded and DELIBERATELY NOT COMPARED.
+ *
+ * This used to be an ordinary observation whose value was the bucket the run landed in, and
+ * it was the single worst thing in the tool, for a reason that is arithmetic rather than
+ * theoretical. A wall clock on a shared machine measures how busy the machine is at least as
+ * much as it measures the product. Two runs of identical code, one while a test suite is
+ * running and one on a quiet laptop, land on different rungs of any ladder you care to draw
+ * — and the tool then reported a difference nobody caused, or worse, reported the address as
+ * "newly unpredictable", which is its sharpest accusation.
+ *
+ * Measured on this Mac on 2026-08-30, on the self-check corpus's own fixture: thirty runs of
+ * the same one-line program, machine idle, ran 48ms to 96ms — with the first rung boundary at
+ * 100ms. Four milliseconds of headroom. Anything at all happening on the machine crosses it,
+ * and that is exactly what happened the night the self-check came back "1 of 9 wrong" while
+ * the test suite ran alongside it, and passed five times in a row afterwards.
+ *
+ * The fix is not a wider bucket — every ladder has a boundary and every boundary has this
+ * problem — and it is certainly not a tolerance, which this tool does not have and will not
+ * grow. It is to stop claiming something a stopwatch cannot tell you. The number is still
+ * recorded, in the sentence, where a person can read it. It is never differenced.
+ *
+ * WHAT THIS GIVES UP, said plainly: Stays Fixed will not tell you your product got slower.
+ * WHAT IT DOES NOT GIVE UP: a build that hangs is still caught, because it gets killed for
+ * taking too long and how it finished IS compared; and every counter that comes from the
+ * product rather than from the clock — files written, calls made, doors answered — is still
+ * compared exactly.
+ *
+ * @param {object} spec
+ * @param {Channel} spec.channel
+ * @param {string|(string|number)[]} spec.path
+ * @param {number} spec.ms                What it actually took, for the sentence.
+ * @param {string} spec.what              What was being timed, in the reader's words.
+ * @param {string} [spec.andAlso]         Anything else worth saying in the same breath.
+ * @param {string} [spec.journey]
+ * @returns {Observation}
+ */
+export function howLongItTook(spec) {
+  return observation({
+    channel: spec.channel,
+    path: spec.path,
+    // One fixed string, so this address is identical in every capture of every build and can
+    // never become a difference. The measurement lives in the sentence, which is never compared.
+    value: `not compared — ${NOT_COVERED_MEANING['measures the machine']}`,
+    says:
+      `${spec.what} took ${timeBucket(spec.ms)}. That is recorded and NOT compared: a stopwatch on a shared machine ` +
+      `measures the machine as much as the product, so a busy laptop would otherwise invent a slowdown that nobody caused. ` +
+      `A build that hangs is still caught — it gets stopped for taking too long, and how it finished is compared.` +
+      (spec.andAlso ? ` ${spec.andAlso}` : ''),
+    covered: false,
+    reason: 'measures the machine',
+    journey: spec.journey,
+  });
+}
+
 /**
  * Sizes, on the same principle as time. A response body that grew by two bytes is not news;
  * one that doubled is.
@@ -542,10 +599,12 @@ export function undoOurFootprint(text, footprint) {
 /**
  * Keep a piece of text at a size worth storing.
  *
- * Anything longer gets its head and tail kept — the two ends are where the interesting
- * lines are — plus a fingerprint of the whole, so a change in the middle still shows as a
- * difference even though the middle itself was never stored. The caller writes the full
- * text to the evidence folder and points at it.
+ * Anything longer gets its head and tail kept — the two ends are where the interesting lines
+ * are — plus the EXACT number of bytes left out, so a middle that grew or shrank still shows
+ * as a difference. A middle that changed without changing length does NOT, and that hole is
+ * stated rather than hidden: the caller marks the observation as not fully covered and writes
+ * the whole text to the evidence folder. See the comment in the body for why a digest of the
+ * whole text cannot be used here.
  *
  * @param {string} text
  * @param {number} [limit] bytes
@@ -557,8 +616,27 @@ export function trimForStorage(text, limit = 64 * 1024) {
   const keep = Math.floor(limit / 2);
   const head = text.slice(0, keep);
   const tail = text.slice(-keep);
+  // The marker used to carry a COARSE size bucket, and the doc above it claimed a fingerprint
+  // of the whole that was never actually computed. Both halves of that were wrong, and the
+  // result was the worst thing this tool can produce: a change that happened entirely in the
+  // discarded middle of a large output left a byte-identical stored value, so the comparison
+  // saw nothing and the run reported that nothing had changed. A silence that reads like an
+  // all-clear.
+  //
+  // The exact byte count goes in instead. A digest of the whole text would be strictly
+  // better AND IT CANNOT GO HERE: normalisation runs after the adapter, on the head and the
+  // tail, so a digest taken now would include every timestamp and every id the rules exist to
+  // rub out — the address would then disagree with itself on every run, be measured as wobble,
+  // and get subtracted, which would switch off the comparison of large outputs altogether.
+  // An exact length survives normalisation, because almost everything volatile (a timestamp,
+  // a uuid, a hex id) has a fixed width.
+  //
+  // What is left uncovered is real and it is named rather than hidden: a change confined to
+  // the middle that keeps the length identical is not seen. The caller marks the observation
+  // as not fully covered, the coverage ledger states the hole, and the whole text is written
+  // to the evidence folder so anybody can look.
   return {
-    text: `${head}\n... ${sizeBucket(bytes - keep * 2)} left out of the middle ...\n${tail}`,
+    text: `${head}\n... exactly ${bytes - keep * 2} bytes left out of the middle of ${bytes} ...\n${tail}`,
     truncated: true,
     bytes,
   };

package/src/v2/adapters/electron.js

@@ -51,8 +51,8 @@ import { connect } from '../../drive/cdp.js';
 import { resolveElectronBinary } from '../../drive/find.js';
 import { splitPath } from '../observation.js';
 import {
-  countBucket, defineAdapter, joinPath, notCovered, observation, sizeBucket, timeBucket,
-  trimForStorage, undoOurFootprint,
+  countBucket, defineAdapter, howLongItTook, joinPath, notCovered, observation, sizeBucket,
+  timeBucket, trimForStorage, undoOurFootprint,
 } from './contract.js';
 import { compareTrees, snapshotTree } from './process.js';
 import {
@@ -1172,11 +1172,11 @@ export function describeApp(input) {
       : `What this journey did, in order: ${did.join('; ')}.`,
     journey: id,
   }));
-  out.push(observation({
+  out.push(howLongItTook({
     channel: 'counters',
     path: joinPath('count', id, 'time to open'),
-    value: timeBucket(app.openedInMs),
-    says: `The app took ${timeBucket(app.openedInMs)} to open and show a window. Deliberately rough: exact timings differ every run.`,
+    ms: app.openedInMs,
+    what: 'Opening the app and getting a window on screen',
     journey: id,
   }));
   if (reading?.helpers) {

package/src/v2/adapters/http.js

@@ -34,7 +34,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import {
   defineAdapter, joinPath, notCovered, observation, sizeBucket, stableValue,
-  timeBucket, trimForStorage, undoOurFootprint,
+  howLongItTook, timeBucket, trimForStorage, undoOurFootprint,
 } from './contract.js';
 import {
   compareTrees, copyForScratch, frozenEnvironment, readWatcher, snapshotTree, watcherScript,
@@ -306,7 +306,7 @@ export const httpAdapter = defineAdapter({
       .find((name) => name in dependencies);
 
     const reading = await readContract({ root: project.root });
-    const routes = [...reading.doors.filter((d) => d.kind === 'route'), ...await readFileRoutes(project.root)];
+    const routes = [...reading.doors.filter((d) => d.kind === 'route'), ...(await readFileRoutes(project.root)).doors];
 
     if (!config.start) {
       missing.push({
@@ -355,7 +355,7 @@ export const httpAdapter = defineAdapter({
     const config = project.config ?? {};
     const samples = config.samples ?? {};
     const reading = await readContract({ root: project.root });
-    const routes = [...reading.doors.filter((d) => d.kind === 'route'), ...await readFileRoutes(project.root)];
+    const routes = [...reading.doors.filter((d) => d.kind === 'route'), ...(await readFileRoutes(project.root)).doors];
 
     /** @type {Map<string, import('./contract.js').Journey>} */
     const journeys = new Map();
@@ -722,11 +722,12 @@ export function describeRequest(input) {
     }));
   }
 
-  out.push(observation({
+  out.push(howLongItTook({
     channel: 'counters',
     path: joinPath('count', id, 'duration'),
-    value: timeBucket(ms),
-    says: `${asked} took ${timeBucket(ms)}. Deliberately rough: exact timings differ on every run and would drown everything else.`,
+    ms,
+    what: asked,
+    journey: id,
   }));
 
   return out;

package/src/v2/adapters/process.js

@@ -40,7 +40,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import {
-  defineAdapter, joinPath, notCovered, observation, sizeBucket, timeBucket,
+  defineAdapter, howLongItTook, joinPath, notCovered, observation, sizeBucket,
   trimForStorage, undoOurFootprint,
 } from './contract.js';
 
@@ -768,9 +768,17 @@ export async function describeRun(input) {
       value: kept.text,
       says: text === ''
         ? `"${journey.describe}" ${nothing}.`
-        : `What "${journey.describe}" ${sentence}${kept.truncated ? `, with the middle left out — the whole of it is ${sizeBucket(kept.bytes)}` : ''}.`,
+        : `What "${journey.describe}" ${sentence}${
+            kept.truncated
+              ? `. It is ${sizeBucket(kept.bytes)}, so only the two ends were kept and compared. A change confined to the middle that does not change its length would NOT be seen here; the whole of it is in the evidence file`
+              : ''
+          }.`,
       evidence,
       journey: id,
+      // Truncation is missing coverage and has to be counted as such. Left unsaid, a break
+      // buried in the middle of a big output is a silence that reads like an all-clear.
+      covered: kept.truncated ? false : undefined,
+      reason: kept.truncated ? 'too big' : undefined,
     }));
   }
 
@@ -852,12 +860,15 @@ export async function describeRun(input) {
     }));
   }
 
-  // ---- how long, coarsely
-  out.push(observation({
+  // ---- how long. Recorded, never compared. See howLongItTook in contract.js for the
+  // measurement that settled this: on an idle machine these fixtures run 48-96ms against a
+  // rung boundary at 100ms, so any load at all crossed it and invented a difference.
+  out.push(howLongItTook({
     channel: 'counters',
     path: joinPath('count', id, 'duration'),
-    value: timeBucket(result.ms),
-    says: `"${journey.describe}" took ${timeBucket(result.ms)}. Deliberately rough: exact timings differ on every run and would drown everything else.`,
+    ms: result.ms,
+    what: `"${journey.describe}"`,
+    journey: id,
   }));
 
   return out;