The Shared-Quantity Register: how we hunt the bug class that type systems cannot catch

Most security writing is about categories of vulnerability: reentrancy, oracle manipulation, access control. Those matter, and they are also the part every auditor already looks for. The defects that actually survived into this codebase's review history were none of them. They were, overwhelmingly, one thing: a quantity computed in two places, by two pieces of code that were both correct in isolation, which disagreed.

That class has a property that makes it particularly nasty. A type system cannot see it, because both values have the same type. A unit test rarely sees it, because each site passes its own test. An auditor reading one file cannot see it at all, because the disagreement only exists between files. What sees it is enumeration — writing down every quantity that has more than one producer or more than one consumer, and stating, for each, the mechanism that keeps them from drifting apart. That enumeration is a file in the repository, and this article is what it is for.

The measurement that started it

The register exists because the defect distribution was measured rather than assumed. Of the findings that survived verification in one review pass, seven were of the form 'two producers of one quantity, no pin'; three were of the form 'unproven caller data reaching shared state'; and everything else was zero. Not 'few' — zero. When a distribution is that lopsided, the honest response is not to keep hunting the same way with more effort. It is to build the instrument the distribution points at.

The instrument is a register with one row per shared quantity. Each row names the quantity, states the QUESTION it answers in plain language, lists every producer and consumer, and records the status of the mechanism that binds them. The question column carries more weight than it looks: two sites can read the same constant and be asking different questions, and where two questions differ without something pinning them together, that is exactly where the next defect lands.

The rule, and the four states

The rule is short. A quantity with more than one producer must either collapse to a single producer, with a CI guard forbidding copies, or keep its producers and carry a named test that asserts they agree. A row records which — and when the answer is neither, it says so out loud.

Four states express that. SINGLE: collapsed to one producer, with a build-failing guard if a copy reappears. PINNED: multiple producers and a named test asserting agreement — and the test must NAME the quantity, not merely exercise it. WEAK: a pin exists but does not fully bind, because it is tolerance-based, or because it pins a neighbouring primitive rather than the one actually consumed. OPEN: no pin at all, carrying a finding id where one exists.

Why WEAK is the dangerous one

The ordering most people would guess is wrong. OPEN looks worst — no protection at all — and WEAK looks like partial credit. It is the other way round, and the register says so in one line that governs how the whole file is read: an OPEN row is a known hole; a WEAK row is a hole with a green test in front of it.

A known hole gets attention. It appears in triage, it accumulates urgency, someone eventually closes it. A hole with a passing test in front of it gets none of that, because every dashboard reports it as covered. The test runs, the light is green, the reviewer moves on — and the disagreement it was supposed to catch walks straight through the tolerance band or past the primitive the test actually pinned. That is why the register grades pins rather than counting them, and why 'a named test exists' is not enough to earn PINNED: the test has to bind the quantity that is genuinely consumed.

The same reasoning explains a rule this project applies elsewhere: a guard that cannot fire is worse than no guard. Both are instances of one principle — a protection you believe in is more dangerous than one you know you lack, because belief is what stops you from looking.

What a row costs, and what it buys

Maintaining the register is real work. Every time a quantity gains a consumer, someone has to write down the question that consumer is asking and decide whether the existing pin still binds it. That is deliberately manual, because the hard part is not mechanical: deciding whether two sites ask the same question requires understanding what each is for, and no scanner can infer intent from source.

What it buys is that the manual judgement happens ONCE per quantity, and everything after that is mechanical. Once a row declares that a defence must be constant across a set of interchangeable sites, a grep can assert the count and fail the build when a future edit re-splits it. The register is the semantic half; CI is the syntactic half. Neither is sufficient alone — a scanner cannot discover the orbits, and a document cannot enforce itself — and together they close the loop.

Why we publish that the method exists

Two things are worth separating. The METHOD is published because a protocol asking to be verified rather than trusted should show how it hunts its own defects; a reader can weigh a project by whether it knows its own defect distribution or merely asserts diligence. The register's live contents are a different matter: rows carrying open finding ids are a map, and a map published before the ground is fixed serves exactly one kind of reader. Those stay in the repository's private records and in the disclosure programme, which pays researchers precisely so that map has a market price and a responsible destination.

The distinction is not a hedge. It is the same standard applied twice: publish what a reader can act on to evaluate the protocol, and withhold what only an attacker can act on. Everything the register enforces reaches the public surface anyway — as a CI gate, as a named regression test, or as a constant a reader can grep. The rows are the working notes; the guarantees are the product.

The generalisation

One line of this method transfers to any codebase, in any language, with no adaptation: find the quantities that are computed in more than one place, write down the question each site is asking, and where two questions differ with nothing pinning them together, look there first. It costs an afternoon and it points at the class of defect that survives type checking, unit testing and file-local review — the class that, when measured here, accounted for most of what external researchers found.

The deeper claim behind it is the one this protocol keeps returning to. Code that believes is attack surface; code that measures is defence. A shared quantity is the place where belief hides best, because both sides believe the same number for good reasons and neither is asked to check the other.

Related engineering

• Metrological Design: the theory behind a contract that measures instead of believing ›
• The enforced invariants: INV-1 to INV-22, properties that hold in every reachable state ›
• The Fidelity Matrix: preview against delivery, measured to 0–1 bps on four chains ›
• Invariant-driven design: how a codebase can make an AI stop guessing ›
• Measured, not nominal: why a protocol must never trust the number it passed to a token ›