xcheck

Reconcile independent measurements — and refuse to trust a single source.

A tiny, dependency-free library for the moment you need to ask "is this number actually true?" — and answer it the only honest way: by checking it against other, independent sources.

Why this exists

It came out of a real incident. An internal counter reported a value that was off from the real, settled truth by thousands — silently, for days — because every dashboard downstream read the same single source. Nothing was lying on purpose; there was just no second opinion.

The fix wasn't a better counter. It was to stop trusting one number. Read the value from independent places — the source of record, a third-party API, your own internal state — compare them against explicit tolerances, and fail loud the instant they disagree.

xcheck is that pattern, extracted and generalized. It's useful anywhere you have more than one way to measure the same thing:

• on-chain balance vs. a venue API vs. an internal counter
• a database vs. its cache vs. a search index document count
• two accounting ledgers that must tie out
• a metric pipeline's input count vs. its output count

Verdicts

xcheck returns exactly one of three answers:

Verdict	Meaning	Exit code
CONSISTENT	Every comparison is within its threshold	0
DIVERGED	At least one comparison exceeds its threshold	1
INCOMPLETE	A source needed by a comparison was silent or missing	2

The load-bearing rule: "A and B agree, C is silent" is INCOMPLETE, not CONSISTENT. You haven't verified anything until every source you chose to trust has actually answered. A divergence outranks an incomplete (a measurable disagreement is the most actionable signal); an incomplete outranks a clean pass (never declare all-good while a source stayed silent).

Install

pip install -e .          # from a clone
# or vendor src/xcheck/core.py directly — it's one file, zero deps

Library usage

Sources are callables, so a flaky network read becomes a silent source (INCOMPLETE) instead of a crash that hides the disagreement:

from xcheck import Source, Rule, reconcile

sources = [
    Source("onchain_rpc",      lambda: balance_from_chain()),
    Source("venue_api",        lambda: requests.get(".../value").json()["value"]),
    Source("internal_counter", lambda: my_bot.cash),   # the one most likely to lie
]

rules = [
    Rule("onchain_rpc", "venue_api",        threshold=1.0, label="chain vs venue"),
    Rule("onchain_rpc", "internal_counter", threshold=5.0, label="chain vs counter"),
]

report = reconcile(sources, rules)
print(report.render())
if report.verdict is not report.verdict.CONSISTENT:
    raise SystemExit(report.exit_code())   # 1 diverged, 2 incomplete

Readings:
  onchain_rpc              309.47
  venue_api                309.47
  internal_counter         250.1

Comparisons:
  [ok] chain vs venue                CONSISTENT  drift 0 <= 1
  [!!] chain vs counter              DIVERGED    |309.47 - 250.1| = 59.37 > 5

VERDICT: DIVERGED

CLI / CI guard

For already-measured values, point the CLI at a JSON file — the exit code drops straight into a CI step or a cron tripwire:

xcheck examples/reconcile.json; echo "exit: $?"

{
  "sources": { "onchain_rpc": 309.47, "venue_api": 309.47, "internal_counter": 250.10 },
  "rules": [
    ["onchain_rpc", "venue_api", 1.0, "chain vs venue API"],
    ["onchain_rpc", "internal_counter", 5.0, "chain vs internal counter"]
  ]
}

A null source value models a silent source. See examples/ for both styles.

Design notes

• Zero dependencies. Standard library only. core.py is a single file you can vendor.
• Failures are data. A source that raises is captured as silent, never re-raised — the report still renders, and the verdict reflects the gap.
• Thresholds are explicit and per-comparison. Two sources that should tie to the cent get threshold=0.0; a noisier pair gets room. No magic global epsilon.
• Boundary is inclusive of agreement: drift is flagged only when it is strictly greater than the threshold.

License

MIT © John Fodchuk