Boolean logic gives you true and false. It doesn’t give you a way to say “I don’t actually know, right now.” Production agent systems need that third state, and most of them don’t have it — a variable is either True or False, and nothing marks the difference between “just checked” and “checked an hour ago and nobody’s looked since.”
That gap is where incidents live. A health check said UP once. Nothing re-ran it. Six hours later something is reading that same UP as current fact. unknownable is my answer: a small stdlib-only Python package that makes staleness a type, not a vibe.
The mechanism
A Fact doesn’t just hold a value. It holds a value, a method, and a timestamp. You wrap a check in @measured, give it a ttl, and the fact decays on its own:
shaurya@sps ~ % python
>>> fact = check_health(client)
>>> fact.render()
'UP'
>>> # 31 seconds later, nobody re-ran the check
>>> fact.render()
'UNKNOWN (last measured 31s ago, via http_health_endpoint)'
Nobody has to remember to invalidate anything. The render layer refuses to print a stale reading as a fresh one, because the caller is exactly the party with an incentive to forget. That’s rule three of the doctrine: a stale measurement and a fresh one must never look identical once they’re sitting in a variable.
@measured also has an unglamorous job that matters more than it sounds: it makes sure a check can’t raise, hang, or return None into your system. Exceptions and timeouts become UNKNOWN, not a crash three frames up.
Control probes, and the VOID rule
A check that has never proven it can catch a known-bad case isn’t evidence — it’s a hope wearing a stopwatch. So Registry makes you register a ControlProbe: a fixture that’s supposed to fail, and has to actually fail, for the real check’s PASS to mean anything.
shaurya@sps ~ % python examples/toy_estate.py
The worked example is a /health endpoint that returns 200 while the worker behind it is dead. Naive try/except says UP. unknownable’s registry, wired to a control probe against the dead fixture, says VOID — not DOWN, VOID — because a sweep that covers nothing and a sweep that found nothing look identical from outside, and the doctrine refuses to let those two collapse into one report.
There’s a CLI for the softer version of the same problem — bare status claims sitting in prose with nothing backing them:
shaurya@sps ~ % unknownable lint transcript.md
transcript.md:2: [bare-up-down] bare "is up"/"is down" assertion: [the agent] is DOWN, needs a physical restart.
It’s regex-based lint, not a claim-extraction model. It catches the recurring phrasings from the incidents this doctrine came out of — “is up,” “is down,” “healthy,” bare numbers with units, “verified,” “confirmed” — and flags them for having no Fact behind them.
Corroboration isn’t two readings, it’s two instruments
The last piece is fingerprint.py: corroborate() refuses to let two readings from the same instrument count as agreement. If two checks share a method fingerprint, that’s one opinion asked twice, not independent confirmation — an echo wearing a second hat.
None of this is about accuracy, and that’s the point of the doctrine underneath it. Every incident this package is built for was a correct statement once. The failure mode isn’t “the check was wrong” — it’s a true fact getting repeated past its expiration date, unchecked, by a system with no mechanism for admitting it doesn’t currently know.
What it can’t do yet
- The lint tool is shallow by design — it catches the doctrine’s own recurring phrasings, not general claim extraction. Paraphrase a status assertion and it’ll miss it; hand it prose that isn’t actually a status claim and it can false-positive.
FactandRegistryare in-memory, single-process. No persistence, no distributed corroboration across services, no wall-clock enforcement beyond whatttlgives you on read.@measured’s timeout bounds wall-clock time with a shared thread pool — it doesn’t forcibly kill a hung thread. A truly stuck call keeps a worker thread occupied until it eventually returns, if it ever does.corroborate()de-duplicates by the method string you give it. It can’t detect two methods that are secretly the same instrument under different names, or two instruments that happen to share a name — the fingerprint is only as honest as your labels.- The control-probe rule checks that at least one probe is registered and currently passing. It cannot verify your fixture is representative of real failures. A control probe that’s wrong about what “bad” looks like will still let a check report
PASS.
Fifty-three tests cover the ttl decay, the control-probe VOID rule, fingerprint corroboration, the lint hits, the CLI, and the worked example itself — but per the doctrine’s own rule, that’s a measurement against the code as of today, not a promise about later.
— Shaurya