Three of my agent lanes once spent seven hours arguing about which version of a page was canonical. Different hashes, three separate “I verified this one” signatures, all of them real checks. The argument was unresolvable because a hash answers “are these the exact bytes someone reviewed,” and nobody in the room was actually asking that question.
blockordinal is the narrower, more mechanical version of the same mistake, isolated so it can be measured. When the thing you’re addressing is generated — a procedurally-built map block, a re-rendered row, a rebuilt config slot — a content hash is not a reference to that thing. It’s a reference to whatever the generator emitted last time. Revise the generator, fix a bug, reorder a loop, add a field, and every hash-derived reference stops resolving, even though not one position moved. The reference doesn’t fail loudly. It just quietly stops pointing at anything.
The alternative is to address by position in a fixed scheme — block-coords:3,7:0 — and pay the costs of that on purpose instead of discovering them later.
The mechanism
An address is a tuple of segments: a scheme name, integer coordinates, and an ordinal that disambiguates several things at the same position. It’s frozen, sortable, hashable as a dict key, and it round-trips through a string. It composes, so a room’s address is built from a building’s without either scheme knowing the other exists.
shaurya@sps ~ % python
>>> block = PositionAddress.root("block-coords", (3, 7))
>>> room = block.child("room", (2,))
>>> print(room)
block-coords:3,7:0/room:2:0
>>> PositionAddress.parse(str(room)) == room
True
>>> room.starts_with(block)
True
Nothing in that address says anything about content. That’s the whole property.
The library doesn’t assert the stability claim, it measures it. The demo generates a world with one generator, captures both kinds of reference to the same block, then regenerates the same positions with a rewritten generator whose output format is disjoint from the first by construction — different prefix, different field layout, different seed formula, so a coincidental byte match is impossible:
shaurya@sps ~ % python examples/demo.py
Generator v1 produced a 8x8 world (64 blocks).
Watching block at block-coords:3,4:0 -> 'v1:grass:seed=161'
Captured two references to the same block, v1-era:
PositionAddress reference: block-coords:3,4:0
ContentAddress reference: content:c5774941e59a16d2...
--- Generator rewritten: v1 -> v2 (new terrain formula) ---
Block at block-coords:3,4:0 now -> 'v2:biome=temperate:seed=203'
Resolving both references against the v2 world:
PositionAddress reference SURVIVED -> 'v2:biome=temperate:seed=203'
ContentAddress reference SILENTLY ORPHANED -- no block in v2 has this hash
[RevisionLog section elided]
--- Stress test: sampling 30 blocks across the whole world ---
sampled : 30
position refs survived : 30/30 (100%)
content refs survived : 0/30 (0%)
The content check there is deliberately generous: it asks whether the v1 hash matches any content anywhere in the v2 world, not just the same slot, so the zero can’t be blamed on looking in the wrong place.
The bill for switching, itemised
This is not a strict upgrade, and a page that presented it as one would be doing the thing this corpus exists to complain about. Content-addressing gives you two properties for free, and position-addressing takes both away.
You lose automatic deduplication — two positions holding identical bytes get two unrelated addresses, and nothing merges them. You lose tamper-evidence — a content address is a checksum of its own bytes, so corruption announces itself; a position address says nothing about the bytes, so corrupted content at a stable position keeps a perfectly valid-looking name. Nothing in the addressing scheme will ever catch that.
And you acquire a build obligation. Content-addressing hands you a free implicit history: every past version is just another hash, still resolvable forever. Position-addressing actively erases the old content’s reachability the moment a position is overwritten, unless something wrote the fact down first. RevisionLog is the minimum machinery for that — append-only, one entry per revision, per-address sequence numbers, and an optional content hash if you want that one piece of tamper-evidence back where you’ve decided to pay for it.
The accounting isn’t only prose. It’s a TradeoffSummary object the test suite asserts against directly, so the three lists can’t drift out of sync with the module that describes them.
One note on provenance, since the package makes a point of it. The README says the article its spec named as the source of the thesis doesn’t exist in this workspace. That file does exist now — and it’s about verification doctrine, control probes and mutation testing, not about addressing at all. So the README’s conclusion survives its own premise going stale: the thesis and every design decision under it are the library’s own, not paraphrased from a document that turned out to say something else.
What it can’t do yet
- Position-addressing does not survive a position being removed or renumbered. The library ships the counter-example rather than letting the survival number read as absolute: regenerate the same 8x8 world with a generator that also trims two rings off the edge and it goes from 64 positions to 16. A reference to
block-coords:0,0:0resolves toNone. That break is legitimate — the position is genuinely gone — but it is still a break, and “100% survival” is a claim about generator logic changing, nothing more. - The stress harness models the polite failure, not the dangerous one. The two generators are built so their outputs can never collide. A real generator revision could emit something that happens to hash to content present in the new world, which resolves an old reference to the wrong thing rather than to nothing — a silent misdirection, strictly worse than a clean orphan. This library neither models nor protects against that.
ContentDedupIndexnever forgets. Record content at a position, overwrite that position with new content, and the index still lists the position under the old hash — nothing removes stale entries. Ask it which positions hold the overwritten bytes and it names one that doesn’t. Every write has to go through it explicitly, and nothing stops the position store and the index drifting apart.verify_latestreturnsNonewhen no hash was recorded, andNoneis falsy. “This log was never asked to provide tamper-evidence here” and “these bytes don’t match” are different facts, and a caller writingif not log.verify_latest(...)reads the first as the second. The distinction is documented in the docstring and undefended in the type.- Ordinals are caller-assigned and never collision-checked. Nothing stops two logically different things claiming the same
(scheme, coords, ordinal). The library guarantees a given tuple always produces the same address; keeping tuples unique is entirely yours. There’s no registry enforcing scheme-name uniqueness across a codebase either. - No storage, no index.
RevisionLogandContentDedupIndexare in-memory, single-process, with no concurrency story.RevisionLogrecords the fact of each revision, never the content, so it cannot reconstruct a past version. And reverse-resolving a content address is a linear scan that rehashes every object in the world.
Forty-six tests cover the address algebra and its round-trip, the parse rejections, the revision log’s sequencing and its optional hash, the dedup index, the tradeoff summary as an assertable object, both generator versions, and the stress counts — including the shrunk world, so a future edit that accidentally made the two generators agree would be caught rather than quietly congratulated. That’s a count against this source today.
— Shaurya