Skip to content

docs: add the claim ledger, and register what iris-guard costs as C0001 - #66

Merged
tamnd merged 1 commit into
mainfrom
docs/claim-ledger
Sep 4, 2026
Merged

docs: add the claim ledger, and register what iris-guard costs as C0001#66
tamnd merged 1 commit into
mainfrom
docs/claim-ledger

Conversation

@tamnd

@tamnd tamnd commented Sep 4, 2026

Copy link
Copy Markdown
Owner

Adds docs/CLAIMS.md and registers the first claim in it.

Why this exists before #27

Issue #27 is to generate the ledger from the results store rather than maintain it by hand, and it is written on the premise that a hand maintained ledger drifts within weeks in the flattering direction. That premise needs a hand maintained ledger to exist. The store is a stub, iris has a measurement that needs an identifier to cite today, and the alternative to a file somebody edits is a number in the iris design notes with nothing behind it.

So this is the interim, it says so at the top in its own section, and it names #27 as what replaces it. Every entry cites the artifact its numbers came from, so the drift #27 exists to prevent is at least checkable against something in the meantime.

C0001, what iris-guard costs

Registered against a three band rule that was fixed in the first commit of the iris repository, ec37026, and in tamnd/iris issue #17. Measured today. The ordering is checkable rather than asserted, which is the whole point of the pre-registration section in METHODOLOGY.md.

The verdict is over fifteen percent on the string shape on all four platforms, which by the rule means the guard stays on and its cost becomes a design problem. Everything else lands under seven percent.

The entry also records the part of the claim that came out wrong. It was registered on the expectation that encoded arrays would be the cheap case, on the reasoning that less data is less to walk. A dictionary of 256 values behind 8192 keys is half the bytes of the column it stands for and costs 28 to 86 times more to check, because a key is a position into something else and every one has to be looked at, while a plain column of fixed width values is one multiplication. The guard charges for indirection rather than for bytes.

Recording that is not a footnote. A ledger that only carries the parts of a claim that held is the failure mode this repository exists to argue against.

What is deliberately not in here

The M0 numbers from iris. They were taken before this file existed, and back-dating a registration is exactly the move pre-registration is supposed to prevent, so they get re-run against a registered claim under B1 rather than written up from the runs that already happened. The ledger says that rather than leaving the absence to be noticed.

Machine class

The rows are hosted continuous integration runners, so they carry shares rather than quotable durations, and the entry says so. The publishable number comes from the i9-13900K in MACHINES.md through the Fleet workflow in iris.

The ledger is maintained by hand and says so. Issue #27 replaces it with a generated one, and that issue is written on the premise that a hand maintained ledger drifts, which needs a hand maintained ledger to exist first.

C0001 is registered against a rule that was fixed in the first commit of the iris repository and measured today, and it is recorded with the part of it that came out wrong. The claim was registered expecting encoded arrays to be the cheap case and the measurement says they cost 28 to 86 times more, because the guard charges for indirection rather than for bytes.
@tamnd tamnd added type: docs Documentation, specifications and written method area: store Result storage and the claim ledger labels Sep 4, 2026
@tamnd
tamnd merged commit c056af5 into main Sep 4, 2026
17 checks passed
@tamnd
tamnd deleted the docs/claim-ledger branch September 4, 2026 17:50
@tamnd tamnd mentioned this pull request Sep 4, 2026
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: store Result storage and the claim ledger type: docs Documentation, specifications and written method

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant