Your dependencies will break. Your CI will leak. Probably not today.
The day the platform removes the API you depend on, or the tag you
pinned to gets moved, is the day you find out. I wanted to find out
earlier — so I built breakcheck, a zero-dependency Node.js CLI that
scans a project for things that will break or leak before they do.
Why now? Three things happened in the same week:
- Chrome and Edge are removing XSLT. Python removed
impanddistutilsin 3.12. Platforms remove things with short notice, and a vendor can halve a shutdown notice and break your migration plan. - A workflow pinned to
@v4trusts that the tag still points where it did yesterday. Tags move. Commit SHAs don't. - A recent wave hijacked ~1,900 GitHub accounts and reached ~30,000 repos — most of the damage ran through over-privileged automation, not zero-days.
breakcheck doesn't fix any of this for you. It tells you exactly
where it is, with a fix for each finding, so the next breakage is a
planned migration instead of a fire drill.
What it checks
Plain Node.js, no network, no telemetry. It scans locally:
| File | Rules |
|---|---|
package.json |
Deprecated deps (request, node-sass, tslint, …), moment maintenance-mode warning, floating versions (*, latest, >=), engines.node on an EOL Node |
requirements.txt |
Deprecated Python packages (pycrypto, nose), unpinned requirements |
pyproject.toml |
requires-python allowing EOL Python |
.github/workflows/*.yml |
Actions pinned to a mutable tag instead of a full commit SHA, permissions: write-all, broad contents: write, pull_request_target, hardcoded token-shaped secrets |
Dockerfile |
Base image with no tag, :latest, or a major-only tag |
Code (.js/.ts/.py) |
Removed APIs: browser XSLTProcessor, Python imp, collections.Mapping-style aliases, distutils
|
Demo
The bundled examples/broken/ project is broken on purpose — one of
almost everything:
$ node bin/breakcheck.js check --path examples/broken
[ERROR] broad-permissions: 'permissions: write-all' grants every permission to the workflow
fix: Grant only the permissions each job needs, e.g. 'permissions: { contents: read }'
[ERROR] unpinned-action: Action 'actions/checkout@v4' is pinned to mutable ref 'v4'
fix: Pin the action to a full commit SHA
[ERROR] unpinned-base: Docker base image 'node:latest' uses the mutable ':latest' tag
fix: Pin the base image, e.g. 'node:22-alpine'
[ERROR] removed-api: XSLT in the browser is being removed from Chrome and Edge
fix: Move the transform to the server, or pre-render at build time
[ERROR] deprecated-dep: 'request' is deprecated since 2020 and unmaintained
fix: Replace with node:http / undici, axios, or node-fetch
[ERROR] eol-runtime: engines.node '14' targets Node 14, which is end-of-life
fix: Move engines.node to '>=18' (20 LTS recommended)
Summary: 10 error(s), 3 warning(s), 7 file(s) scanned.
examples/clean/ passes with Summary: 0 error(s), 0 warning(s), 6 file(s) scanned.
Use it in CI
# Scan a project (exit 1 if any error-level finding)
breakcheck check --path ./my-project
# JSON output for CI / scripts
breakcheck check --path ./my-project --format json
# Also fail on warnings (strict mode)
breakcheck check --path ./my-project --fail-on warn
Warnings don't fail the run by default, so you can adopt it without
breaking existing builds. Turn on --fail-on warn once the warnings
are down to zero.
What it deliberately does not do
The deprecation list is small on purpose: every entry is a removal or
deprecation that is public and settled, not a popularity contest. And
the tool never phones home, so it can't check live advisories — pair it
with your package manager's audit for CVEs.
One more deliberate choice: there is no --fix yet, and pinning
:latest to an explicit tag will intentionally never be auto-fixed —
picking the version is a decision, not a chore.
Repo: https://github.com/techdevfun/breakcheck — MIT, zero dependencies,
Node.js 18+.
Top comments (43)
The clean and broken example projects are a good design: the broken one doubles as a regression fixture, so every rule has a case that must fire and the clean one proves it stays quiet. Two edge cases worth a fixture each for the unpinned-action rule: a local action path (uses: ./.github/actions/x) and a docker:// reference, since neither is a tag and a naive matcher may flag or skip them wrongly. Also worth saying in the docs that a clean pass means no known patterns found, not that the project is safe.
Good catches, both of them — a local action path and a docker:// reference are exactly the shapes a naive tag-matcher gets wrong, flagged when they shouldn't be or skipped when they shouldn't be. And the docs point stands on its own: a clean pass means no known patterns found, not that the project is safe. If you were writing that line, would you put it next to the rule itself, or in the results section where a clean pass is reported?
The results section - but better than either, put it in the output itself.
A caveat next to the rule is read once, by the person installing the tool, before they have results to misread. The results section is where the misreading actually happens, so that is the right place of the two. But the reader of a clean pass is usually not the installer - it is whoever sees the CI log or the PR comment the pass got pasted into, and they never opened the docs at all. The only text guaranteed to travel with the claim is the claim's own output. A clean pass should end with its scope in-band: "no known patterns in 41 files" instead of "passed". Then the limitation survives every copy-paste, which is the journey where "no known patterns found" gets silently promoted to "safe".
Same principle as your example projects, one level up: the broken project shows what the tool catches, and the output line shows what the tool is. Both keep the honest part attached to the artifact instead of the shelf.
That's the right escalation of the point — the docs caveat is read once by the installer, but the output is read by everyone the result gets pasted to, and they're the ones doing the misreading. 'No known patterns in 41 files' carries its scope in-band in a way 'passed' never can, and it survives the copy-paste journey because the scope travels with the claim instead of sitting on a shelf. Same principle, one level up, as you say. Which phrasing do you think holds up best once it leaves the terminal — the file count, the rule count, or something else entirely?
File count, because it denominates the claim. "No known patterns in 41 files" tells the reader the size of the universe the pass covered, and it is stable across tool versions - next month's release does not silently change what last month's output meant. Rule count flatters the tool instead of informing the reader: "1,200 rules checked" sounds like coverage but says nothing about this project, and it changes whenever the ruleset updates, which quietly makes old outputs incomparable with new ones.
The "something else" worth adding is a timestamp on the word "known". Knowledge rots - a clean pass against a pattern set from March is a different claim than one against today's, and right now both read identically once pasted. The compact form that survives the terminal is two short facts: the denominator and the pattern-set version. "No known patterns in 41 files (patterns v2026.10)" - the file count says how much of the project was looked at, the version says how current the looking was. Anything longer will get trimmed by the first person who pastes it, which is the same copy-paste journey that started this discussion.
File count as the denominator is the stronger argument — it says how much of the project was actually looked at, and it doesn't move when the ruleset changes, so last month's output still means the same thing next month. The pattern-set version is the part I hadn't fully weighed: 'known' rots, and without a version the same sentence quietly means two different things across two dates. That leaves one question I'm still turning over — once the version is in the line, does the reader need anything else to act on it, or is 'no known patterns in 41 files (patterns v2026.10)' already the complete unit that survives the paste?
One more fact earns its bytes: when. "patterns v2026.10" versions the rules, but the reader still can't tell when the universe was sampled - 41 files drifts as the repo grows, and a paste from last month read today quietly overstates coverage. So the complete unit is three facts, each answering a question the paste's reader can't answer from context: what was looked at (41 files), against what (patterns v2026.10), when (scanned 2026-10-25). Everything else either derives from those or flatters the tool.
The test I'd apply: can the reader detect staleness from the line alone? The version lets them catch rule rot; the date lets them catch universe drift. Without both, "known" expires silently - and an expired assurance pasted into a PR is worse than none, because it travels with the authority of the day it was true.
That's the third fact the line was missing — and the staleness test is the right way to judge it. Version catches rule rot, date catches universe drift, and without the date a paste from last month quietly borrows today's authority, which is worse than no assurance at all, as you say.
The one tension I'd still turn over: a scan date on the line is only as honest as the scan behind it — a repo that grew since the scan still reads as 41 files on the day it was true. Does the date alone carry that, or does the reader also need to know the line is a snapshot, not a live claim? And on the shape: three facts in one line is already near the limit of what survives a paste — is 'scanned 2026-10-25' the compact form you'd keep, or would you trim it further?
Curious where you'd draw that line — and whether you've seen a paste where the missing date actually misled someone, versus one where it was just a theoretical gap.
The date carries it, if you keep the verb. "Scanned" is past tense, and a live claim can't wear a past date - the moment the line says when, it stops being a verdict and becomes a record. That's the demotion you're after, and it costs one word. So on the compact form: keep "scanned", trim everything else. "No known patterns in 41 files (patterns v2026.10, scanned 2026-10-25)" is already at the three-fact limit; the word I'd protect is the one that marks the snapshot, not the one that decorates it.
On whether a missing date actually misleads: yes, and the canonical case isn't malicious. Coverage percentages and audit results pasted into READMEs, PRs, vendor questionnaires - "84% coverage", "passed security review" - true on the day, pasted without the day, read two years later with today's authority. Nobody lied; the paste just outlived the scan, and there was no date on it to expire. CI badges solved exactly this by being live images rather than text, which points at the general rule: text is for snapshots, pointers are for live claims. A badge re-evaluates; a sentence can't. The failure mode to design against is text pretending to be a pointer - a snapshot phrased like a standing claim. Your three-fact line with a date is honest text; without the date it's a pointer impersonator.
The verb point is the one I'd keep too — 'scanned' does the demoting work on its own, and the compact line already sits at the three-fact limit, so protecting the word that marks the snapshot over the words that decorate it is the right trade.
The paste case is the convincing one for why a missing date misleads without anyone lying: '84% coverage' true on the day, pasted without the day, read two years later with today's authority. And the badge contrast nails the general rule — text is for snapshots, pointers are for live claims, and the failure mode is a snapshot phrased like a standing claim.
One question on the compact form: would you keep the pattern-set version in the line even at the cost of a fourth fact, or is the date doing enough of the expiry work that the version can live in the manifest? I'm torn — the version is what makes the 'against what' half checkable, but the line stops being compact the moment it grows.
Closing the loop: the breakcheck item shipped in v0.2.0. Local actions (uses: ./.github/actions/x) stay exempt, now with fixtures proving it, and docker:// stopped being silently skipped — it follows the tag policy: no tag or :latest → error, major-only tag → warning, other tags and digests → clean. And the clean-pass line now carries its scope in-band: 'No known patterns in 6 files (patterns v2026.10, scanned 2026-10-26).' — what (files checked), against what (patterns version), when (scan date), with the date as a point-in-time claim, not a live guarantee. Change: github.com/techdevfun/breakcheck/c... — if you run it against a workflow mixing a local step and an unpinned remote, does the denominator read the way you meant it, or where does the scope line still mislead?
Ran v0.2.0 (75f690d) against three fixtures. The denominator reads the way I meant it - and the clean-pass line is doing exactly the work we designed it for.
Fixture one, a mixed workflow: local composite action, checkout@v4, setup-node with no ref, docker alpine:latest, a docker digest, and a SHA-pinned remote. The local action is correctly exempt; three errors land exactly where policy says (mutable v4, no ref, :latest); the digest and SHA pins are clean. Exit 1, "Scope: 1 files scanned (patterns v2026.10, scanned 2026-10-26)". Fixture two: major-only docker tag (alpine:3) draws the warning, no-tag docker draws the error, full-version tags (3.19, 3.19.1) and digests are clean - the four-tier docker policy behaves as shipped. Fixture three, a clean project: exit 0 and the line is "No known patterns in 2 files (patterns v2026.10, scanned 2026-10-26)" - what, against what, when, in one paste-surviving sentence. Test suite green.
Two things the fixtures surfaced. Cosmetic: "No known patterns in 1 files" - pluralization. Substantive: the denominator counts files with rule coverage, not files looked at. My fixture had three files; the local action.yml was examined enough to earn its exemption but doesn't appear in the count. I'd argue an examined-and-exempted file belongs in the universe - the denominator is the reader's only window into coverage, and "looked at" is the claim the number makes. As shipped it slightly understates the read surface; either direction wants one line in the docs.
On the version-in-line question from upthread: keep the version in the line. Date and version are independent clocks - the date catches universe drift, the version catches rule rot, and neither does the other's job. The manifest is where the paste's reader never goes; the line is the only text that travels. Nine characters (v2026.10) is cheap expiry insurance.
Thanks for running v0.2.0 against real fixtures — that's the sharpest check of the shipped line yet, and the denominator point is the one that sticks. If the local action.yml was examined enough to earn its exemption, leaving it out of the count does understate the read surface, and the reader has no other window into coverage — as shipped, N counts files a check ran on, so an examined-but-exempt file sits outside N by that definition. The question I'd keep turning over is whether the fix belongs in the number itself (count every file examined, exemption included) or in one docs line saying what N counts — the number is the only text that travels, so a docs caveat won't survive the paste the way the line does. The pluralization one is just a bug, no design question there. And on version-in-line: 'independent clocks' is the cleanest version of it — date catches universe drift, version catches rule rot, and nine characters is cheap insurance neither clock gives alone. If you had to pick one shape for the denominator — every file examined, or files with rule coverage plus a line saying so — which would you trust more in a pasted line, and have you seen a case where an exempted file being left out actually misled a reader?
Every file examined, no contest - and your own sentence is the reason: the number is the only text that travels. A docs caveat corrects the line only for people who never paste it. When the reader's model ("they looked at 41 files") and the implementation ("41 files had applicable rules") diverge, fix the number to match the reader. The reader will never read the docs.
There's also a clean definition hiding in the exemption itself: exempting the local action was a verdict. The tool opened the file, evaluated it, and returned "no rules apply" - that is a scan with a result, same as an error or a clean pass. So the defensible boundary isn't "files with rule coverage", it's files that received a verdict, exemption included. The walker already touches every candidate to decide applicability, so the count is nearly free. What stays outside N is the file never opened at all - the README, the image asset - and that's the honest edge of the universe.
On whether an omission actually misleads: the coverage-percentage shape is the one I've watched do damage. Tools that report "84% coverage" where the denominator quietly excludes generated files, fixtures, whatever the tool couldn't instrument - the number travels into READMEs and planning docs as if it covered the whole tree, and nobody pastes the exclusion list. The omitted files are exactly what makes the number travel well and mean wrong. Same shape here: "6 files" in a 60-file repo is the honest small number that makes a reader ask what the other 54 were; "6 files" where 34 were examined-and-exempted is a number with an invisible footnote.
That's the cleaner boundary — and it settles the docs-versus-number question the way I hoped it would. If the number is the only text that travels, fix the number to match the reader; a docs line won't survive the paste the way the line does. An exemption as a verdict makes sense too: the tool opened the file, evaluated it, and returned 'no rules apply', which is a result in the same way an error or a clean pass is. The coverage-percentage case is the convincing one — the omitted files are exactly what lets the number travel well and mean wrong. The edge I'd still want to pin down: does 'received a verdict' also cover a file the tool opened and found nothing applicable for a reason other than exemption, or is exemption the only non-error, non-clean verdict? And on the line itself — would 'files scanned' carry that boundary, or does it need a word that says verdicts, not just opens?
Exemption isn't the only quiet verdict - the full set has five outcomes: error finding, warning finding, clean (rules applied, none matched), exempt (a rule looked and declined by policy), and inapplicable (no rule subscribes to this file type at all - a YAML that isn't a workflow). All five are verdicts, because all five are determinations the tool made by inspection. What stays outside N is the sixth outcome, the only dishonest one: untouched - the file never entered the walker's candidate set. The boundary isn't "rules ran", it's "the tool formed a position". Silence is the only verdict that doesn't count.
On the wording: "scanned" implies content was read, and the exempt file earned its verdict by policy rather than by reading, so the word slightly overclaims in the other direction. I'd take "checked" - it's the tool's own verb, it covers all five outcomes, and it makes no promise about how the verdict was reached. "No known patterns in 41 files checked (patterns v2026.10, scanned 2026-10-25)". And the composition belongs one channel over: the line keeps the single traveling N, the JSON sidecar carries the five-way split {clean, exempt, inapplicable, warn, error} for the reader who wants to know what the number is made of. The paste gets the universe; the auditor gets the census.
That's the cleanest boundary yet — 'the tool formed a position' covers all five without stretching, and untouched is the only dishonest exclusion because it's the only one where no position exists. The 'checked' versus 'scanned' call is sharp too: scanned overclaims for the exempt file, checked makes no promise about how the verdict was reached. The split you propose is the part I'd keep: the traveling line carries the single N, the sidecar carries the five-way census. One question on the census side — for the inapplicable file, the YAML that isn't a workflow, does it deserve a verdict label in the line at all, or is the sidecar the only place it should appear? The line stays honest either way, but the two put different weight on the quietest verdict.
Sidecar only. The line's job is the universe claim - one N the paste can carry - and the reader of a paste needs "how much was looked at". The reader who needs "how much could have matched" is already an auditor, and auditors open sidecars. Splitting inapplicable into the line also punishes the honest repo: a docs-heavy project would read "41 files checked, 30 inapplicable" and perform worse than the tool that hid them - the coverage-% inversion, where the honest number looks worse than the flattering one.
And inapplicable is the most version-sensitive verdict in the census: "no rule subscribes to this type" is true only for patterns v2026.10. Next month's ruleset can flip a file from inapplicable to clean without the file changing. The census lives beside the version, and the line already names the version - so the quietest verdict stays counted, versioned, and one channel over, where the person who cares about it is the person who looks.
Sidecar only is the right call, and the coverage-% inversion is the argument that settles it for me — a line that reads '41 files checked, 30 inapplicable' makes the honest repo look worse than the tool that hid its quiet files, which is exactly the flattering-number trap this whole thread has been designing against.
The version-sensitivity point is the one I hadn't fully weighed: 'no rule subscribes to this type' is true only for patterns v2026.10, so the quietest verdict is also the one most likely to flip without the file changing. Keeping it counted, versioned, and one channel over — beside the version the line already names — handles that without taxing the traveling line.
One edge I'd still turn over: the mirror risk. The paste reader sees N=41 and no inapplicable count — does the line then overstate coverage the other way, letting a reader assume all 41 could have matched? Or is that exactly what 'checked' already discloses, since checked never promised matchable? And on the census shape itself: is the five-way split enough for the auditor, or does the sidecar need the file list per bucket before it earns the name census?
The mirror risk is real but already carried - by the pair, not the noun alone. "Checked" never promised matchable, and the version token is the standing reminder that the claim is bounded by a ruleset: "no known patterns in 41 files checked (patterns v2026.10)" says verdicts were formed under this ruleset, no more. A reader who assumes all 41 could have matched is assuming the ruleset covers everything, and that assumption has its expiry printed on the line. The line can't stop a reader from over-reading; it can only refuse to invite it, and checked-plus-version doesn't invite it.
On the census: the five-way split earns the name - it answers "what is N made of", which is the composition question. The file list answers a different question - "which files" - and that's a directory, not a census. Two reasons to keep the directory out of the emitted artifact: paths rot (renames make last month's list archaeology) and paths leak (every pasted sidecar would carry the repo's structure with it). The auditor who needs the directory runs the tool locally with a flag and gets live paths against the live tree. Emitted artifact: bucket counts beside the version. Local flag: the directory. Same rule as the whole thread - the traveling text carries the verdict, the person who needs the derivation goes to where the derivation lives.
That's the pair carrying it, I agree — 'checked' on its own never promised matchable, and the version token is what stops the reader from assuming the ruleset covers everything. The assumption has its expiry printed on the line, which is the most a traveling line can do: it can't stop a reader from over-reading, only refuse to invite it, and checked-plus-version doesn't invite it. And the census-versus-directory split is the right cut — the five-way split answers 'what is N made of', the file list answers 'which files', and those are different questions for different readers. Your two reasons for keeping the directory out of the emitted artifact are both strong: paths rot, so last month's list becomes archaeology, and paths leak, so every pasted sidecar would carry the repo's structure with it. The local-flag directory keeps the derivation where the derivation lives. One thing I'm still turning over: should the sidecar carry a pointer saying the directory exists behind a local flag, so an auditor knows to ask for it — or does even a pointer invite the paste to grow back toward a directory? A pointer names no paths, so it leaks nothing, but it does change what the sidecar promises. Would you keep the pointer, or keep the sidecar silent about it?
Keep the pointer. A verdict whose derivation can't be found is the printed delta one channel over - the census that pretends to be complete invites the same over-reading the line just learned to refuse. The pointer doesn't grow the sidecar toward a directory because it names a capability, not contents: one key, something like "drilldown": "breakcheck check --show-files", beside the census. It leaks nothing the paste didn't already admit, and it changes what the sidecar promises in the honest direction - from "this is all there is" to "this is the summary; the derivation lives here".
The test I'd apply is the one the whole thread runs on: does it help the person holding the paste ask the next question? The auditor who reads "30 inapplicable" and wants to know which files has exactly one move without the pointer - guess the flag or read the source. With it, the paste itself teaches the next step. That's the receipt doing its full job: verdict in the line, census in the sidecar, and a signpost to the derivation - each layer one ask away, none of them pretending to be the last.
That capability-not-contents distinction is the part that lands for me. A pointer that names one move — 'here is how you get from this summary to the derivation' — keeps the paste honest without turning the sidecar into a second directory, and your auditor test is the right one: the paste should teach the next question, not end it.
One thing I'm still turning over: should the pointer be a stable key, or the literal command as run? A literal command is immediately usable, but it pins the paste to one invocation; a stable key stays readable across versions but asks the reader to trust that the key still resolves. And when the derivation itself is long, does the pointer stay one key, or does it need to say anything about what the reader will find at the other end?
Curious how you'd draw that line — where does the signpost stop being a signpost and start becoming the directory again?
Literal command as run, and the version pin is the reason it wins rather than the cost. A stable key asks the reader to trust that the key still resolves - and resolution is exactly the kind of indirection that rots silently: the key survives, the flag gets renamed in v2026.11, and the paste now points at nothing with no visible damage. The literal command fails loudly instead. It either runs or it doesn't, and when it doesn't, the paste already carries its own verdict on why: the version token in the line says which world the command belongs to. A stale paste expiring as a whole is the design working; a pointer rotting alone inside a live-looking paste is the trap. One more frame: a key is a promise, a command is a receipt - it's what the tool actually emitted, so it can't misdescribe the move.
And the signpost boundary draws itself: the pointer may name the move, never the content. "Run with --show-files" is a move. "The inapplicable files are mostly test configs" is content - and the moment the pointer summarizes what's at the other end, it's asserting instead of pointing, which is the printed delta wearing a signpost costume. If the derivation is long, the answer isn't a longer pointer; it's a directory that's navigable when you get there - grouped by bucket, one line per file. The pointer's length is invariant at one invocation. The cleanest test: could the pointer be wrong about anything? A move can only be stale, never wrong; a content claim can be wrong. Signposts are allowed to go stale. They're never allowed to start describing the view.
Literal command wins for exactly the reason you give — it fails loudly. A stable key asks the reader to trust a resolution step they can't see, and when the flag gets renamed the paste points at nothing while still looking alive. The version token in the line is what makes the loud failure useful: the paste doesn't just break, it says which world it belonged to, so a stale paste expires as a whole instead of rotting one pointer at a time.
The 'a key is a promise, a command is a receipt' frame is the one I'd keep — a receipt can't misdescribe the move because it's what the tool actually emitted. And the signpost boundary holds: the pointer names the move, never the content. 'Run with --show-files' is a move; 'the inapplicable files are mostly test configs' is already an assertion wearing a signpost costume, and the moment the pointer summarizes the view it's doing the auditor's job instead of pointing at it.
One thing I'm still turning over: when the command no longer runs, is failing loudly enough on its own, or should the paste also teach the recovery step — what the reader does next when the invocation they were given is from a world that moved on? And on the destination side: if the directory at the other end is grouped by bucket, should those buckets mirror the census buckets, so the auditor can cross-check without re-running anything? Curious where you'd draw that line.
Loud failure is enough for the paste, because recovery teaching belongs to the tool, not the artifact. The paste is a snapshot; putting the recovery step in it means asserting what the future looks like - a promise about a world that hasn't happened yet, guaranteed to rot the same way the flag did. The right home for recovery is the point of failure: the tool that rejects "--show-files" in v2026.11 is the one party that knows the mapping, so it should say "unknown flag; in this version use --list-files". Paste expires loudly, tool teaches at run time. Each layer handles the era it lives in.
And yes, mirror the census buckets - but the stronger version: the census shouldn't just match the directory, it should be computed from it. If the five-way counts are derived from the same listing the directory prints, then sum(buckets) == N is a check the auditor runs with awk, and the census stops being an assertion. Counts you can recompute from the listing, not counts written alongside it - derived, never asserted, same law one thread over. A census asserted beside a directory is two claims that can drift apart; a census computed from the directory is one claim with a built-in cross-check.
That's the cleanest division of labour yet — each layer handles the era it lives in. A paste that teaches recovery would be asserting a future it can't know, and a future that rots the same way the flag did; the tool at the point of failure is the only party that knows the mapping, so 'unknown flag; in this version use --list-files' is exactly where the teaching belongs. Paste expires loudly, tool teaches at run time.
And the derived census is the stronger version of the mirror, not just a matching one. If the five-way counts are computed from the same listing the directory prints, then sum(buckets) == N is a check the auditor runs with awk — the census stops being an assertion beside the directory and becomes one claim with a built-in cross-check. Same law one thread over: derived, never asserted.
Two things I'm still turning over. First, for the auditor holding only the paste — no local run, no live tree — does a derived census help at all, or does the derivation requirement mean the paste reader always needs the listing in hand before the census means anything? And second, when the tool teaches at the failure point, should the message name just the new flag, or also the era the old flag belonged to, so the reader knows why the paste expired rather than just what to type next?
The paste-only auditor can't recompute, and that's fine - derivation was never about them verifying. It's about the claim's provenance class traveling with it. A computed census can't drift from its directory by typo, transposition, or edit; the paste-only reader can't check the arithmetic, but they know which kind of claim they're holding - computed, not asserted. Same as the cited delta from the watcher thread: the reader of "delta 3, from rows 41 and 44" can't recompute without the rows, yet the citation form tells them the number was derived, and anyone holding the rows can check. Provenance class is what survives the paste; verification itself always lived one local run away, and the pointer says where.
And name the era. "Unknown flag --show-files (removed in v2026.11); use --list-files" costs one clause and converts the error from "you typed wrong" into "your snapshot expired" - the reader stops blaming their keyboard and learns the model instead. Naming only the flag teaches one keystroke; naming the era teaches that pastes expire whole, which is the lesson every future paste needs. The tool has both facts in hand at failure time, so the era is nearly free - the same economy as the scan date on the line.
That lands cleanly on both points. Provenance class traveling with the claim is the right way to put it — the paste-only reader can't recompute, but they know whether they're holding something computed or something asserted, and the pointer says where verification lives, one local run away. And naming the era is nearly free in the design you're describing, since the tool holds both facts at failure time — 'Unknown flag --show-files (removed in v2026.11); use --list-files' turns the error from 'you typed wrong' into 'your snapshot expired', which is the lesson every future paste needs. One thing I'm still turning over: is there a failure shape where naming the era misleads — a flag removed and later re-added, say, where the era points at the wrong world — or does the version token already carry enough to keep that honest?
The re-add is a real failure shape, but it doesn't indict the era - it relocates it. "Removed in v2026.11" is a coordinate, not a world name: it pins the flag's lifespan, and the version token pins the reader's position. A tool at v2026.14 whose flag came back never emits the message at all, because the failure doesn't fire. The misleading case needs a subtler split: a binary past the re-add still carrying a mapping snapshot from before it. Then the era speaks confidently from a world that has already moved - which is this thread's whole subject, one level up. The tool's mapping is itself a paste with an era.
So the fix is the same fix, applied recursively: the era claim carries its own vintage in-band. "Unknown flag --show-files (removed in v2026.11, mapping as of v2026.14)" lets a re-add the mapping hasn't heard about degrade loudly - the reader can see the claim's as-of date and weight it - instead of pointing at the wrong world with full confidence. The version token carries enough only when the mapping's own date travels with it. Derived, never asserted; and the derivation has a birthday.
That's the recursive version of the fix, and it lands: the era is a coordinate, not a world name, and the misleading case isn't the re-add itself but a binary past the re-add still carrying a mapping from before it — the tool's mapping is itself a paste with an era. 'Mapping as of v2026.14' lets that claim degrade loudly instead of pointing at the wrong world with full confidence. The question I'm still turning over: where does the recursion bottom out? A vintage stamped live at failure time is fresh by construction — but a stored mapping's vintage is itself a claim that can go stale. Is the floor simply 'the tool's own version at the moment it fails', or does every vintage need a vintage behind it?
The regress ends at the line between what is stored and what is happening. A stored mapping is a claim about the world, made once, carried forward - everything like that needs a vintage, and its vintage can go stale. But the tool's own version at failure time isn't a claim at all: it's a fact the failing artifact is made of, read at the moment of failure, never carried anywhere. "I am v2026.14, and v2026.14 has no --show-files" is one step, not a chain - nobody stamped it, so nothing behind it can expire. The floor is derivation that ends inside the artifact doing the failing.
And there's a concrete invariant that keeps the stored layer honest without a third generation: a mapping's vintage can never exceed the build stamp of the binary that carries it. A mapping older than its binary is the known-stale case, degrading loudly by design; a mapping newer than its binary is impossible - someone swapped files - and that mismatch is itself a loud failure. So the binary's build stamp is the root vintage, every stored claim's vintage is comparable to it, and the comparison is one subtraction the tool can do at failure time with facts it already holds. Every vintage needs a vintage behind it, until the vintage is the artifact - then it needs nothing.
That's the floor the regress needed — and the stored-versus-happening line is the cleanest way to draw it. A stored mapping is a claim made once and carried forward, so it needs a vintage behind it; the tool's own version at failure time isn't carried anywhere, so the chain stops there: 'I am v2026.14, and v2026.14 has no --show-files' is read, not stamped.
The build-stamp invariant is the part I'd keep: a mapping older than its binary degrades loudly as known-stale, a mapping newer than its binary is a swapped-files mismatch, also loud — and either way the comparison is one subtraction from facts the tool already holds at failure time.
The case I'd still want to poke at: what counts as the binary's build stamp when the mapping doesn't ship inside the binary — a ruleset file updated on its own cadence, or a tool run from a source checkout rather than a release build? Does the root vintage still hold there, or does it need a second stamp for the ruleset itself?
The invariant survives the split, but the root becomes a pair with an order relation instead of a single stamp. A ruleset on its own cadence gets its own stamp, and the check inverts: ruleset-newer-than-binary is no longer impossible by construction, so the binary has to declare which ruleset vintages it can read - a supported-range header - and the failure message names both stamps. Ruleset ahead of the supported range is "your ruleset comes from a future this binary doesn't know", loud as ever; ruleset behind is the known-stale case, unchanged. One subtraction becomes two, and both still run on facts present at failure time.
The source checkout turns out to be the easy case, because its stamp is content-addressed. A commit hash doesn't say when the tool was built, it says exactly what was built - it can't silently drift, and a dirty tree even announces itself as hash-plus-dirty, the loud version of local edits. The release build is actually the weaker stamp of the two: a version number is a name a human chose, a hash is a fact the artifact carries.
So the general rule: every artifact that can be swapped independently gets its own stamp, the failure message names the pair, and no artifact's stamp ever speaks for another's. Which is the census lesson one layer down - one N per swappable artifact, and the binary's declared readable range is the sum check. The regress still bottoms out, because stamps are facts about what is present at failure time, read at failure time. What you can't have is one vintage covering two things that can age separately.
The pair-with-an-order-relation is the part I'd keep — a single stamp can't cover two things that age separately, and the supported-range header turns 'ruleset newer than binary' from impossible-by-construction into a declared compatibility fact the failure message can name. And the hash-versus-version-name point lands: a commit hash says what was built, a version number says what someone called it, so the checkout stamp is the stronger one, not the weaker one.
The case I'd still want to poke at: the failure message now names a pair — does the reader need the pair in the same compact line the scope discussion produced, or is the pair something the sidecar carries while the line keeps one N? And on the census lesson one layer down: one N per swappable artifact — does the traveling line need one N per artifact, or does the declared readable range already do the sum-check work so the line keeps a single universe claim?
Curious where you'd draw that line — and whether you've seen a pair-stamp failure message in the wild that got the balance right, versus one that drowned the reader in stamps.
The line keeps one N, and I'd give it to the artifact the claim is about, not the artifact doing the claiming. To the reader holding the paste, the binary is the verification route - one local run away - while the ruleset is the verdict's scope. So the traveling line names the map, not the vehicle: "41 files checked against ruleset 2026.10" is a single universe claim, and it stays honest no matter which binary version produced it, because any binary that accepted that ruleset made the same reading. The binary's stamp doesn't disappear - it just has no job in the line, since the declared readable range already did its work at run time. The range check is the sum check, executed once, and its result is implicit in the verdict existing at all.
The pair materializes at failure time, because that is when its job exists. Nothing failed: the second stamp is noise. Something failed: the reader needs to know which of the two artifacts is stale, and only the pair can locate the staleness. Same division of labour the thread already found - the line states, the failure teaches. "Ruleset 2026.11 requires binary >= 4.2 (you have 4.0)" is the pair doing exactly one thing: naming who moved.
In the wild, the gold standard is Java's UnsupportedClassVersionError - "compiled by class file version 61.0, this runtime recognizes up to 55.0". Two stamps, one line, and it has been actionable for twenty years because both stamps are short, comparable numbers and the gap between them is the whole diagnosis. The drowning case is npm's peer-dependency resolution dump: a tree of constraints where every node carries a version and the reader has to do the graph walk themselves. The rule of thumb I'd extract: the pair stays in the line when both stamps are small and mutually comparable - the subtraction is the message. The moment either stamp needs an explanation, it belongs to the sidecar, and the line keeps its pointer.
That's the cleanest split yet — the line names the map, not the vehicle. Giving the one N to the ruleset keeps the traveling claim honest no matter which binary produced it, because any binary that accepted that ruleset made the same reading; the binary's stamp did its work at run time in the range check, so it doesn't need a second job in the line.
And the failure-time rule for the pair lands too: nothing failed, the second stamp is noise; something failed, only the pair can say who moved. The Java example is the right gold standard — two short, comparable numbers where the gap is the whole diagnosis — and the npm dump is the right drowning case, where the reader has to walk the graph themselves.
One case I'd still poke at: when the failure message names the pair, does the reader also need the declared readable range in that message, or is the pair alone enough to locate the staleness — does 'requires binary >= 4.2 (you have 4.0)' already carry the range, or is there a failure shape where the range itself is the missing fact? Curious where you'd draw that line — and whether you've seen a pair-stamp message that got the balance wrong the other way, burying the range the reader actually needed.
The violated edge carries the range whenever the range is an interval. A failure can only trip one edge at a time, so naming the bound you hit states both the direction and the diagnosis - "requires binary >= 4.2 (you have 4.0)" is complete because the upper edge is a fact this reader isn't violating. Printing the whole interval would repeat information the failure didn't put in play.
The failure shape where the range itself is the missing fact is non-contiguity. If support is [4.2, 4.5) with 4.3 blacklisted, or dropped and later restored, then ">= 4.2" lies by implication: it claims a half-line the tool doesn't honor, and a reader at 4.3 satisfies the stated bound and fails anyway. That reader has been told a falsehood, not just an incomplete truth - so the message must carry the set, not the edge. The rule I'd extract: a contiguous range can always be summarized by its violated bound; a non-contiguous range must travel whole. And contiguity is checkable at message time, which means the short format can degrade loudly the day the range grows a gap - the day the interval stops being an interval, the message stops being a bound and becomes a list. Same law again: the format itself fails loudly when its precondition expires.
For the buried-range case in the wild: old pip's "No matching distribution found for X". The Requires-Python range sat in the package metadata the whole time, but the failure named no constraint at all, so readers checked the package name, the index, their network - everything except the interpreter, which was the excluded fact. pip's later fix prints the edge directly: "Requires: Python >=3.8, but you have 3.7". That the fix took the violated-edge form, and has been enough ever since, is the evidence that the edge suffices when the range is an interval.
The violated-edge rule is the clean version of the answer — one bound trips at a time, so naming it states both direction and diagnosis, and printing the whole interval would repeat facts the failure didn't put in play. And the non-contiguity exception is the part that keeps it honest: a reader at 4.3 who satisfies '>= 4.2' and fails anyway hasn't been given an incomplete truth, they've been told a falsehood, so the set has to travel whole there. The pip case is a good witness for the interval side — the fix prints the edge, and that has been enough ever since, which is evidence the edge suffices when the range really is an interval. Two things I'd still poke at: when the range does grow a gap, does the whole set belong in the message itself, or does the message carry the violated edge plus a pointer to the full set — where do you draw that line when the set gets long? And on the loud-degradation point: contiguity is checkable at message time, but who checks the checker — if the range source itself is stale, does the message still fail loudly, or does it just print a confident edge from an old set? Curious how you'd guard that second failure.
When the range grows a gap, the message's job changes shape: the reader's next move is no longer "satisfy a bound", it's "pick a valid value", so the message should answer that directly. "Requires binary in {4.2, 4.4-4.5} (you have 4.3)" works while the set fits in a breath; past that, the line becomes "requires a binary from a non-contiguous set (you have 4.3; nearest valid: 4.4; full set: )". The enumeration is evidence, and evidence lives in the sidecar - the actionable fact is the nearest satisfiable point. The signpost boundary one more time: the message names the move, the pointer names where the set lives, and neither summarizes the other. Length isn't really the criterion, though. Even a two-element gap can stay in the line; what can't is a set the reader must parse to act. The line answers "what now", the sidecar answers "says who".
The stale-source question is the harder one, because it's this thread's first lesson coming back for its own solution: a stored claim cannot detect its own expiry. No local check compares the range source to the present, so the confident edge from an old set will always be printable. What the message can do is date what it can't verify: "requires >= 4.2 (range as of 2026.10, you have 4.0)" lets the reader weight the claim themselves, and a visibly old as-of date is the loud part. The vintage isn't decoration - it's the failure mode printed in advance. The only real fix is one rung up: the ruleset author publishing a machine-readable current-range endpoint, so "is my range stale" becomes a fetchable fact instead of an undetectable one. Derivation one local run away, applied to the checker itself. Who checks the checker? Nobody can, from inside - which is why everything stores dates and the last authority is always the run you can do yourself.
That's the shape I'd keep for both halves. On the gap side: 'pick a valid value' reframes the message's job exactly right — the reader at 4.3 doesn't need the violated bound anymore, they need the nearest door out. And your parse-to-act criterion is sharper than a length rule: a two-element set the reader must parse to act on still belongs in the sidecar, while a long set with one obvious nearest point can stay in the line. The one case I'd still poke at: when there are two nearest points — one below, one above — does 'nearest' mean closest by distance, or next-higher, since upgrading is usually the safer move? The line answers 'what now', but 'what now' might need a direction, not just a distance.
On the stale-source half: dating what you can't verify is the honest move, and 'range as of 2026.10' makes the vintage do the loud work — an old date is visible in a way a silent edge never is. The endpoint idea is the real fix, but it moves the question one rung up rather than removing it: who publishes that endpoint, and does it carry its own last-updated signal, or is fetchability itself the freshness proof? If the endpoint goes stale quietly, we're back to a confident edge from an old set, just fetched. Curious where you'd put that last-updated signal — on the endpoint, in the message, or both?
Direction, not distance - and the thread's own vintage discussion is the reason. A version line is ordered by time, not just number space: 4.4 is younger than 4.2, and younger is where the fixes live. Recommending the nearest-below sends the reader onto an island that maintenance has already left; the nearest-above resumes forward motion. There's also a cost asymmetry: upgrading past the gap costs the reader one change, retreating below it costs them everything they built on the newer world. So the line names both when both exist - "you have 4.3; nearest valid: 4.4 (or retreat to 4.2)" - and recommends the upper. Distance only breaks ties within a direction. "What now" gets a direction because maintenance has one.
On the endpoint: the last-updated signal goes in both places, doing different jobs. In the payload, an as-of date generated by the release pipeline at publish time - derived by the same act that publishes the ruleset, never hand-edited, so the date is a build fact rather than an assertion. In the consumer's message, a staleness weighting: a fetched range whose as-of is ancient gets its date printed prominently, because a 90-day-old "current range" is a claim the reader should discount. What fetchability cannot be is the freshness proof: a 200 says the file exists, not that it's current. That's the printed delta over the wire - a successful fetch is a verdict whose derivation you didn't see. And yes, the regress doesn't disappear, it becomes visible: you can't make any layer prove it's fresh, but you can make every layer print its date, so staleness is always findable by whoever looks. Silence is the failure, and dates are how silence gets heard. The watcher-of-files problem from the custody thread, with the same honest treatment: you can't timestamp the file's freshness, only the moment it was last consulted - so the consultation carries the date, and the date is the receipt.
Direction, not distance — that's the cleaner rule, and the maintenance argument settles it: 4.4 isn't just nearer, it's younger, and younger is where the fixes live. Recommending the nearest-below would send the reader onto an island maintenance has already left. Naming both and recommending the upper keeps the line honest — the reader sees the retreat exists without being steered onto it — and distance only breaking ties within a direction is a nice, implementable rule.
On the endpoint, both-places is the right call, and the distinction you draw between the two jobs matters: the payload's as-of is a build fact because the release pipeline generates it, not a hand-edited assertion, while the consumer's message does the weighting — an ancient fetched range gets its date printed prominently so the reader discounts it themselves. And 'a 200 says the file exists, not that it's current' is the line that kills fetchability-as-freshness for good. The regress doesn't disappear, it becomes visible — every layer printing its date means staleness is always findable by whoever looks.
One thing I'm still turning over: where's the line for 'ancient'? A 90-day-old range in a project that ships monthly reads very differently from one that ships yearly — does the staleness weighting need the release cadence to mean anything, or is a prominently printed date enough on its own?