Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How it works

The book develops the model through named definitions, rules, theorems, and examples. Each unit carries its explanation in Markdown and mathematics and links to the corresponding named part of Lean. The mathematical account stands on its own; a Rendered/Lean selector lets the reader inspect its formalization. The reading order introduces concepts before the rules that use them.

Developing a unit

Begin with a behavior or distinction worth explaining. State it in a unit and work through examples that make its meaning concrete. Put the unit ID on the opening line and source citations in :lean:. Record contextual definitions in :uses: and link new terminology to where it is introduced. Explanatory content belongs inside the reviewed boundary rather than in untracked semantic prose. The authoring guide gives the supported forms.

A theorem may need several assumptions to capture the intended guarantee. Review compares those assumptions and the conclusion with the prose and mathematics. Lean checks the proof. An example has its own comparison: the cited Lean case must describe the setup and result actually claimed in the book. Unfinished formalizations retain their intended unit kind and use :status: draft. They cannot receive affirmative correspondence decisions or pass evidence validation.

Neither representation automatically wins when they differ. A discrepancy may reveal ambiguous prose, an inadequate proposition, or a design choice that needs discussion. Record the discrepancy and resolve it before claiming correspondence.

Keeping the comparison inspectable

dada-spec prepare snapshots a unit and its required inputs. A human or agent reviewer compares them and records a conclusion, rationale, examined inputs, and limitations. dada-spec record checks that the inputs still match current source before retaining the decision. Exact snapshots remain available so another reviewer can vet the comparison. Changing an input makes affected evidence stale.

The evidence checker validates structure, required input coverage, and freshness. It does not itself judge mathematical correspondence or prove a theorem. Its ordinary Cargo integration test makes missing or stale evidence visible during cargo test --workspace. The review procedure explains how to interpret and repair failures.

Proof checking, test execution, and correspondence review remain separate. Passing Lean establishes the proposition checked under its assumptions; a current review records a judgment that this proposition captures the intended claim. A passing test establishes its tested cases. None of these results should be silently substituted for another.

Working in this repository

Edit chapters under v2/md/ and register them in v2/md/SUMMARY.md. From the repository root, just book-v2 builds the draft and just test-lean checks the Lean project. Run mdbook serve inside v2/ to preview the book.

From v2/, run:

cargo run -p mdbook-dada --bin dada-spec -- status --explain
cargo run -p mdbook-dada --bin dada-spec -- check
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Every new-style unit participates in evidence validation. v2/spec.json names strict chapters that additionally require all semantic prose to lie within units. The Given and Shared chapters use the complete review loop, alongside the implementation contracts. Legacy requirements in the system reference still await migration to review units.

The system design defines the evidence contract. The layer extension protocol describes the model organization: unique ownership with p→, then shared ownership with p→share, with a formal correspondence between the two layers.