Four kinds of writing live here. They are separated on purpose: a reader who wants to know what a program means should never have to read what a benchmark did on someone’s laptop, and an experiment that later turned out wrong should never be able to quietly change the language.
specification/What the language is. Normative. If the compiler disagrees with it, one of the two is a bug and the disagreement gets recorded.
std, the diagnostics contract.The three parts follow one language standard,
specification/STYLE.md: the rule, then its
consequence — nothing else. A page carries no ADR references, no rationale, no
history and no implementation status; those live in the decision records, the
changelog and the roadmap, and are not repeated there.
specification/adr/Why the language is that way. One decision per record, numbered D1…Dn so
it can be cited, with the reasoning that settles it and, where a number decided
it, that number. A record states the decision as it stands today: no story
of how it was reached, no version that built it, no progress.
Start at the ADR index: every live record, what
it decides, and whether it is built (yes, no, or partly: with what is
missing).
When a later decision changes a record, the record is updated in place: the
rule is rewritten to what holds now, with a one-line Changed by ADR-MMM Dn
note under it. A decision withdrawn altogether is removed, with one sentence
saying what is done instead. When a group of records is replaced by one
record that states all their decisions in their current form, the old records
move to history/adr/ and no live file cites them
(scripts/check-adr-refs.py enforces it).
The route to a decision is history: the archive’s
README maps each archived decision to the live one,
git log shows how a live record changed, and
../CHANGELOG.md and the notes below hold what was built,
tried and measured.
What was tried, measured and learned. The laboratory notebook. Nothing here is normative and nothing may depend on it to know what a program means.
scripts/speed.sh).Bug for
anything false — in the compiler, a specification page or an ADR — Feature,
Task), a label says where (language, libraries, tools, targets,
selfhosting, compiler, spec), exactly one status label says what can
be done with it - ready (decided; can be built now), decision (needs the
owner first), blocked (waits on another issue being built, named in it),
note (a hint, a measurement still to take, or an issue that only collects
others) - and Priority and Effort give the order. Big pieces are issues with sub-issues. A closed issue stays: every entry the old open-work.md ever carried, closed ones included, is an issue, and the citations of its §N.M numbers in the CHANGELOG, the ADRs and code comments name the issue they mean. “The former backlog file” in old text means that file as a whole.decision:
each says what is blocked by it, the options, and a recommendation, and is
closed when an ADR answers it.handoff.md — how to work on the parser backend: testing a
change against Nikaia, what the upstream patch does, and what was tried and
must not be redone. A guide; the open work that was in it is in
the issue tracker.error-corpus.md — twenty-six broken .nika files and
what the compiler says about each, before and after.stored-views.md — the E0621 a stored naked view used to
produce, the two increments of the analysis that replaced it, and what the full
tether lattice would have to track that they do not: the seven things it needs,
the two the compiler has, and the measurement showing that building the
reachable half first refuses a program in examples/ that works today.spec-promises.md — every construct and command the
specification names, run against the compiler one probe at a time; the
evidence behind the Status notes in Parts I–III.language-review.md — the surface language read as a
newcomer would read it: where it contradicts its own promise, where a program
can be silently wrong, where the syntax will make people curse, and the order
in which turning it inside out would pay. Every claim reproduced with a probe
or quoted from the page.solver-workload.md — what the prover asks its
solver and where the time goes: 1 697 queries of at most four variables,
83 % of them bounds on single variables or differences, 4.2 µs each, and
the one pattern - an equality with a coefficient - behind every query it
cannot answer. The numbers ADR-270 D9 rests on.subprocess-cost.md — what invoking rustc as a child
process costs, against the codegen it wraps: 0.64 % of a compile, which is what
the text interface of ADR-004 D1 is paid for with.mutex-floor.md — what an always-Mutex floor for
Locked would cost against Part II 12.2’s no-pausing rule: why blocking is
not pausing in this language, the one ledger line the answer turns on, and
the 11 ns an uncontended acquisition costs where it can never be contended.lock-free.md — whether ADR-281’s open door is worth
walking through: what a compare-and-swap loop would buy over the shipped
crossing door, the 3.7× defect the measurement uncovered on the way, and
§6’s finding that what decides it is not the saving but whether a real program
shares a word-sized value across threads at all.unique-ownership.md — an idea, not a measurement:
extending the ledger with a proof that a mutable value is reachable from
exactly one task at a time, so a door over it would need no lock. Why it is in
character (ADR-037 D7 already picks Rc against Arc per value by proving a
reachability property), the five things the first afternoon would run into,
and the one that would kill it.automatic-clone.md — why having the compiler insert the
.clone() a detached task makes necessary is not a convenience: it adds an
owner and so moves a cleanup point, which is the observable change ADR-037 D3
refused to infer and ADR-005 §3 already rejected outright, so the proposal has
to answer those records rather than appeal to typing saved.toolchain_architecture.md — how the crates in
the workspace stack up.project_status_and_roadmap.md — what runs
today and what is next.upstream/ — findings and patches handed to dependencies.This is the right home for the detail the specification must not carry: the method, the machine, the false starts, the measurement that overturned an intuition.
history/The same notebook, kept but no longer current. A note moves here once its question is answered (the ADR it fed now carries the decision) or its subject is withdrawn — never for age by itself. The method and the measurement are still true and still cited by ADR number from wherever they are used; only the question the page was written to answer is no longer open.
mitigation-hurdles.md — four hurdles of
the Rust to Nikaia move; three are built (ADR-283 D25-D26, ADR-010 D10), the
fourth lives in #581 and ADR-010 D9.staging-candidates.md — the survey of
where compile-time staging would pay; every candidate is closed
(ADR-178).from-for-throws-and-touches.md —
whether ADR-288 D15’s sync = "from(f)" argument carries to the other two
effect columns; answered, and the syntax it was written against is
superseded.std-sysroot.md — what std’s build graph cost
when std had the compiler as a build dependency; that dependency is gone.nightly-cost.md — what the pinned nightly
toolchain cost and bought; withdrawn, per ../CHANGELOG.md.runtime-cost.md — what a pair of operations
costs on a running runtime; the evidence behind ADR-303 and ADR-292 D6,
both decided.break-continue-cost.md — break and
continue, priced before ADR-276 decided
them.rc-or-arc.md — what an atomic reference count
costs; the question ADR-037 D3 left open, closed by ADR-037 D6–D8.fixed-map-lookup.md — a fixed map’s lookup,
match against a perfect hash; the crossover
ADR-311 D9 rests on.zero-copy-send.md — what it costs to answer a
request with a file; ADR-289’s evidence.foreign-runtime.md — a Nikaia program that
starts hyper; the finding changed no decision under
ADR-303 D7.technical_notes.md — compiler-internals
findings from the rustc_ast path; that path is withdrawn.withdrawn-one-way-down.md — what the
nightly toolchain, the Bridge-IR backend and the rustc_ast path were, and
why they were withdrawn.../CHANGELOG.mdWhat changed, when, and what it cost. Per release. A correction to an earlier claim is recorded here as well as in the record it corrects.
If deleting a sentence would change what a correct Nikaia program is, it belongs in the specification. If it would only change whether you agree with the language, it belongs in an ADR. If it would only change how much you trust the number, it belongs in the notes.