Bitfield Docs

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.

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 and 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:

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?

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

Read Comparison guardrails, then check the exact rows in the Claim ledger.

Speed claims

Updates

Measurement methodology

The categories

Why warm local read is allowed to be tiny

Why the non-claims matter

How docs should present numbers

Measurement envelope

Publishability test

Common failures

Next

​The categories

​Why warm local read is allowed to be tiny

​Why the non-claims matter

​How docs should present numbers

​Measurement envelope

​Publishability test

​Common failures

​Next

The categories

Why warm local read is allowed to be tiny

Why the non-claims matter

How docs should present numbers

Measurement envelope

Publishability test

Common failures

Next