Benchmark numbers are only useful when you know what job was measured.
A new proof row is about to be published. Before the number goes public, it must name the category, included work, excluded work, and claim-ledger row.Classify
Pick the benchmark category before writing copy.
→
Bound
Name what the measurement includes and what it does not include.
→
Ledger
Put the value, unit, category, mechanism, and non-claims in the claim ledger.
The categories
| Category | What it means | What to compare it to |
|---|---|---|
| Warm local read | The data is local, the needed pages are warm, and Bitfield has the read address. | Other warm local reads with a similar access shape. |
| Cold local read | The data is local, but setup or fetch work is included. | Other cold local reads on similar hardware. |
| Content address lookup | Bitfield resolves a content identity before reading. | Other local lookup paths, not exact-position reads. |
| Durable batch write | Many writes are grouped, then the cost is divided across written items. | Other batch writes with the same durability boundary. |
| Runtime call | App code asks a Bitfield target to do work through Runtime Kit. | Other runtime request and reply paths. |
| Network command | Data crosses a network before the app gets an answer. | Other networked systems in the same deployment shape. |
Why warm local read is allowed to be tiny
Warm means the operating system already has the needed file pages available. Local means the read does not cross a network. Known position means Bitfield is not asking a separate database process to parse, plan, and search for the answer.That does not break physics. It names the physics being measured.Why the non-claims matter
The headline number is never the whole truth. The non-claims tell you where the number stops.If a number says warm local read, do not read it as cold disk, network request, every possible query, or every possible write.
How docs should present numbers
Every public speed row needs:- The number.
- The unit.
- The measured category.
- The mechanism.
- A list of what the number is not claiming.
Measurement envelope
Every public benchmark claim needs this envelope before it appears in a page:| Field | Required public answer |
|---|---|
| Category | What job was measured, such as warm local read, content address lookup, durable batch write, or runtime call. |
| Unit | What the number counts, such as nanoseconds per read, lookup, request, or written item. |
| Cache and setup state | Whether the needed bytes are warm, cold, local, remote, preloaded, or fetched during the measurement. |
| Included work | The exact public work boundary: read, lookup, durable batch write, runtime request, or network command. |
| Excluded work | The work the number does not include, such as cold storage, internet latency, server scheduling, unrelated query planning, or isolated write latency. |
| Repetition and statistic | The public statistic used for the row. If this is not ready to publish, the row is not ready to publish. |
| Claim row | The public claim entry that owns the value, unit, category, mechanism, and non-claims. |
| Source family | The public proof source family connected to the page. |
| Pages that repeat it | The public pages allowed to repeat the row. |
Publishability test
Before a number ships, answer these questions in order:- Can a reader tell what job was measured without asking us?
- Can a reader tell which work was excluded?
- Can a skeptical engineer compare it only to the same category?
- Can generated summaries find the claim row and avoid stretching it?
- Can the page explain the public mechanism without exposing private implementation details?
Common failures
| Failure | Why it is wrong | Fix |
|---|---|---|
| Publishing without a category | The number cannot be compared | Add the measured job first |
| Publishing without non-claims | The number becomes too broad | Add explicit exclusions |
| Mixing warm, cold, and network paths | The measurement identity changes | Split the categories |
| Publishing private work logs | The docs leak the wrong source material | Curate public claim rows instead |