> ## Documentation Index > Fetch the complete documentation index at: https://docs.bitfield.so/llms.txt > Use this file to discover all available pages before exploring further. # Measurement methodology > How to read Bitfield benchmark numbers without comparing unlike jobs.

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 Measured job

Pick the benchmark category before writing copy.

→
Bound Included and excluded work

Name what the measurement includes and what it does not include.

→
Ledger Public claim row

Put the value, unit, category, mechanism, and non-claims in the claim ledger.

No number should ship as a slogan. It should ship as a bounded claim. The wrong way to read a benchmark is to take one number from one category and compare it to a different number from another category. A warm local read, a cold local read, a content address lookup, a durable batch write, a runtime call, and a network command are different jobs. ## 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. That is why the [benchmark ledger](/proof/benchmark-ledger) and [claim ledger](/reference/claim-ledger) exist. ## 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: 1. Can a reader tell what job was measured without asking us? 2. Can a reader tell which work was excluded? 3. Can a skeptical engineer compare it only to the same category? 4. Can generated summaries find the claim row and avoid stretching it? 5. Can the page explain the public mechanism without exposing private implementation details? If any answer is no, the number is not ready for public docs. ## 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 | ## Next Read [Comparison guardrails](/proof/comparison-guardrails), then check the exact rows in the [Claim ledger](/reference/claim-ledger).