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

Specification system design

The specification consists of named units of Markdown and mathematics, each linked to its formalization or implementation. The Rust library in v2/mdbook-dada supplies both the mdBook renderer and the dada-spec evidence commands. A unit has one stable identity, a complete authored body, and explicit source and context dependencies. The renderer and evidence checker use the same unit boundaries.

Every structured unit under md/ participates in the inventory. Future notes record nonnormative ideas with no formalization or correspondence claim; all other structured units require evidence. v2/spec.json additionally lists strict chapters, where semantic prose must be inside units using the syntax described in Authoring units. The renderer also retains the earlier citation syntax for compatibility. Successful validation does not imply that every paragraph of this book has been reviewed.

A source citation, correspondence review, passing test, and checked Lean proof answer different questions. A shield identifies a unit; it does not certify it. The review procedure explains how to prepare and record evidence, and extending the model describes how independently understandable semantic layers are related.

anchormeta.anchors.identity Each named claim has a unique identity and one defining source location. References and generated views resolve to that definition. Missing or ambiguous identities are reported as errors rather than silently omitted.

anchormeta.anchors.content A structured unit’s opening and closing fences delimit its complete content, including its options, prose, mathematics, qualifications, and examples. The opening-line argument is its stable ID. Rendering and review use that complete unit, before Markdown escaping or HTML generation. A legacy inline anchor names a location but does not establish an evidence boundary.

In strict chapters, semantic explanations belong inside units. New terminology links to the unit that introduces it; explanatory examples cite Lean cases that state the behavior described. Headings organize the reading order without adding untracked semantic claims.

anchormeta.correspondence.coverage A claim can be associated with multiple definitions, operations, examples, tests, and propositions. The associations identify their exact targets. The system records explicit gaps and the scope covered by each association; the existence of a link alone does not establish adequate coverage.

anchormeta.reviews.correspondence Human or agent review assesses whether the associated views collectively express a coherent, intended design. It examines quantifiers, assumptions, exceptions, and relevant definitions, and considers cases that satisfy the propositions but violate the prose. Reviews retain claim-specific reasoning and unresolved issues.

Neither English, propositions, nor code automatically prevails in a discrepancy. The discrepancy must be discussed; resolving it can change any of those views or the intended design. Proof difficulty alone does not establish that a design is flawed or a proposition false.

anchormeta.reviews.freshness A saved correspondence review applies only to its recorded claim, propositions, assumptions, and relevant definitions and evidence, under its recorded review policy. Changes affecting those inputs require renewed review. A stored line number is only a diagnostic location and does not participate in the bundle digest. Moving text within a conservatively fingerprinted source file still changes that file’s contents and therefore invalidates the current implementation’s evidence. Link and reading-order audits additionally hash source positions as inventory content, so moving an unchanged use or definition changes those audit inputs.

Changing the definition of live, for example, can invalidate review even when a theorem’s displayed statement is unchanged. A change confined to proof technique need not change the mathematical intent. The current implementation conservatively fingerprints all local Lean sources for units with Lean citations, so it also invalidates reviews after proof-only edits or changes elsewhere in the local formalization. This can require extra review; it must not silently omit a dependency. Finer tracking of elaborated statement dependencies is a future refinement.

anchormeta.reviews.recording Preparing review inputs does not approve them. Recording a decision checks that its inputs still match the current sources and retains the reviewer identity and reasoning. Automated checking reports stale or missing decisions; it does not manufacture approvals to make a check pass.

anchormeta.evidence.status The system distinguishes claims awaiting formalization, proposed formalizations awaiting review, reviewed formalizations with incomplete proofs or coverage gaps, and mechanically checked proofs under recorded assumptions. It separately identifies executed examples and tests. Partial coverage of a claim is not presented as establishment of the whole claim.

Build success, a source association, a review judgment, a passing test, and a checked proof remain distinct evidence. Unfinished formalization stays marked draft and prevents the evidence check from passing.

Structured units separate kind from readiness: :status: draft keeps the Definition, Example, Theorem, or other kind label and adds a Draft indicator. A draft may omit citations; supplied citations retain their kind checks. Drafts fail evidence validation and cannot receive an affirmative correspondence record. Definitions introduce concepts and judgments without asserting a result to prove. Theorems and lemmas state results; draft status marks proposed results whose formalization is unfinished.

anchormeta.proofs.assumptions Evidence presented as a checked proof identifies its proposition, checked source version, and assumptions, including admitted results or additional axioms. Standard verification uses just test-lean, whose lake build --wfail rejects warnings, including those emitted by sorry; do not suppress warn.sorry. Any future allowance for admissions must require an explicit opt-in; an admitted statement must not be reported as proved.

anchormeta.rendering.faithfulness Mathematical views render the notation authored in the Markdown, and Lean views extract their cited source. Graph renderings derive from explicit state facts; layout hints do not silently add semantic relationships. Readers can inspect the formalization associated with a mathematical view and the facts underlying a diagram. Extraction preserves the cited source; correspondence between authored mathematics and that source requires a separate review.

The Markdown supplies a self-contained mathematical account. Its definitions and explanations can be read without opening the Lean files, whose citations identify associated formalizations for comparison.

anchormeta.system.self_specification The tooling’s review and rendering contracts are structured units in Implementation contracts and Renderer contracts. They cite Rust symbols and tests and require the same recorded comparison as language units.

The tooling review inventory includes the renderer contracts linked here, with their exact implementation and test selections. Every structured specification unit under the book source root, including dot-prefixed files and directories, requires current positive correspondence evidence, even when its chapter is not strict about surrounding prose. Explicit dependencies must name existing units and become review inputs. Future notes remain in the inventory and undergo structural and reference checks, but assert no correspondence and require no correspondence review. Their explicit boundary is described under Future notes. Specification units and future notes both require link audits, including review of future notes used as link targets.

Mechanical execution records remain separate from correspondence judgments. A review cannot stand in for a command result, and a command result cannot approve a review. The inventory checks these declared boundaries; it does not discover unwritten requirements or prove that tests exercise all possible behavior.

mdbook-dada/src/inventory.rs:Inventory::load
#![allow(unused)]
fn main() {
pub fn load(root: &Path) -> Result<Self> {
        let root = root
            .canonicalize()
            .context("resolving specification root")?;
        let config: Config = serde_json::from_str(
            &fs::read_to_string(root.join("spec.json")).context("reading spec.json")?,
        )
        .context("parsing spec.json")?;
        ensure!(
            config.schema == SCHEMA,
            "unsupported specification schema {}",
            config.schema
        );
        ensure!(
            !config.chapters.is_empty(),
            "spec.json must name at least one strict chapter"
        );
        ensure!(
            !config.policies.is_empty(),
            "spec.json must name a review policy"
        );
        let source_configuration = SourceConfiguration::load(&root)?;
        source_configuration.lean_root(&root)?;
        let mut units = BTreeMap::new();
        let mut sources = BTreeMap::new();
        for path in files(&root, &source_configuration.markdown_root(&root)?, "md")? {
            let name = relative_path(&root, &path)?;
            let source = fs::read_to_string(&path)?;
            for unit in units::parse(&source, &name)? {
                ensure!(
                    !units.contains_key(&unit.id),
                    "duplicate unit ID {}",
                    unit.id
                );
                units.insert(unit.id.clone(), unit);
            }
            sources.insert(name, source);
        }
        let mut required = BTreeSet::new();
        let mut chapters = BTreeSet::new();
        for chapter in &config.chapters {
            input_path(&root, chapter)?;
            ensure!(
                chapters.insert(chapter),
                "duplicate strict chapter {chapter}"
            );
            let source = sources
                .get(chapter)
                .with_context(|| format!("strict chapter is not Markdown under md/: {chapter}"))?;
            units::validate_coverage(source, chapter)?;
            let ids: Vec<_> = units
                .values()
                .filter(|unit| &unit.source_path == chapter)
                .map(|unit| unit.id.clone())
                .collect();
            ensure!(!ids.is_empty(), "strict chapter has no units: {chapter}");
            required.extend(ids);
        }
        // A new-style unit always participates, even before its chapter becomes
        // strict about free-floating prose. Legacy directives are not units.
        required.extend(units.keys().cloned());
        for unit in units.values() {
            for dependency in &unit.uses {
                ensure!(
                    units.contains_key(dependency),
                    "{}: {} uses missing unit {dependency}",
                    unit.source_path,
                    unit.id
                );
            }
        }
        for path in config.policies.iter().chain(&config.context) {
            input_path(&root, path)?;
        }
        let inventory = Self {
            root,
            config,
            source_configuration,
            units,
            required,
            sources,
        };
        // Resolve authored URLs against actual chapter locations. Checking only
        // global IDs misses wrong-chapter links and excludes legacy anchors.
        crate::links::Links::build(&inventory)?;
        Ok(inventory)
    }
}
mdbook-dada/src/inventory.rs:Inventory::inputs
#![allow(unused)]
fn main() {
/// Derive required snapshots from current sources, never from a review record.
    pub fn inputs(&self, id: &str) -> Result<Vec<Input>> {
        if crate::link_audit::is_subject(id) {
            return crate::link_audit::inputs(self, id);
        }
        let mut inputs = BTreeMap::new();
        self.add_unit(id, &mut inputs, &mut BTreeSet::new())?;
        for input in self.common_inputs()? {
            inputs.insert(input.key.clone(), input);
        }
        if inputs.keys().any(|key| key.starts_with("lean:")) {
            let lean_root = self.source_configuration.lean_root(&self.root)?;
            for path in files(&self.root, &lean_root, "lean")? {
                let name = relative_path(&self.root, &path)?;
                let input = self.file_input(format!("context:{name}"), &name)?;
                inputs.insert(input.key.clone(), input);
            }
            for path in ["lean-toolchain", "lakefile.toml", "lake-manifest.json"] {
                let name = relative_path(&self.root, &lean_root.join(path))?;
                let input = self.file_input(format!("context:{name}"), &name)?;
                inputs.insert(input.key.clone(), input);
            }
        }
        Ok(inputs.into_values().collect())
    }
}
mdbook-dada/src/evidence.rs:check
#![allow(unused)]
fn main() {
/// Check all required units, including record presence, minimum inputs and freshness.
/// Neither the review's conclusion nor a passing result establishes a Lean proof.
pub fn check(inventory: &Inventory) -> Result<Report> {
    let mut report = Report::default();
    if let Err(error) = crate::mechanical::records(&inventory.root) {
        report.issues.push(Issue {
            unit: None,
            message: "malformed mechanical execution evidence".into(),
            details: vec![format!("{error:#}")],
        });
    }
    let mut bundles = BTreeMap::new();
    for path in json_files(&inventory.root, &inventory.root.join("evidence/bundles"))? {
        match read_json::<ReviewBundle>(&path) {
            Ok(bundle) => {
                let errors = bundle.integrity_errors();
                let name = path
                    .file_stem()
                    .and_then(|name| name.to_str())
                    .unwrap_or("");
                if !errors.is_empty() || name != bundle.digest {
                    report.issues.push(Issue {
                        unit: inventory
                            .units
                            .contains_key(&bundle.unit)
                            .then_some(bundle.unit.clone()),
                        message: format!("invalid evidence bundle {}", path.display()),
                        details: errors,
                    });
                } else {
                    bundles.insert(bundle.digest.clone(), bundle);
                }
            }
            Err(error) => report.issues.push(Issue {
                unit: None,
                message: "malformed evidence bundle".into(),
                details: vec![format!("{error:#}")],
            }),
        }
    }
    let audits = AuditInventory::build(inventory)?;
    // Parse every saved decision, including retired subjects. Removing a link or
    // unit retires its obligation, not the integrity checks on its history.
    let mut all_records: BTreeMap<String, BTreeMap<String, ReviewRecord>> = BTreeMap::new();
    let records_root = inventory.root.join("evidence/records");
    for path in json_tree(&inventory.root, &records_root)? {
        let parsed = (|| -> Result<(String, String, ReviewRecord)> {
            let review: ReviewRecord = read_json(&path)?;
            let digest = review.digest()?;
            ensure!(
                path.file_stem().and_then(|name| name.to_str()) == Some(&digest),
                "record filename does not match contents"
            );
            let bundle = bundles
                .get(&review.bundle)
                .context("record's bundle is missing or malformed")?;
            ensure!(
                path == records_root
                    .join(&bundle.unit)
                    .join(format!("{digest}.json")),
                "record filed under wrong subject"
            );
            let errors = validate_review(bundle, &review);
            ensure!(errors.is_empty(), "invalid review: {}", errors.join("; "));
            Ok((bundle.unit.clone(), digest, review))
        })();
        match parsed {
            Ok((subject, digest, review)) => {
                all_records
                    .entry(subject)
                    .or_default()
                    .insert(digest, review);
            }
            Err(error) => report.issues.push(Issue {
                unit: None,
                message: "malformed stored review".into(),
                details: vec![format!("{}: {error:#}", path.display())],
            }),
        }
    }
    for (id, records) in &all_records {
        for review in records.values() {
            for previous in &review.supersedes {
                if !records.contains_key(previous) {
                    report.issues.push(Issue {
                        unit: Some(id.clone()),
                        message: "review supersedes absent or unrelated evidence".into(),
                        details: vec![previous.clone()],
                    });
                }
            }
        }
    }
    let required_subjects: BTreeSet<_> = inventory
        .required
        .iter()
        .chain(audits.manifests.keys())
        .cloned()
        .collect();
    let mut current_active = BTreeMap::new();
    for id in &required_subjects {
        // Derive inputs even for drafts: malformed
        // citations never disappear because a formalization is unfinished.
        let required = match if link_audit::is_subject(id) {
            audits.inputs(inventory, id)
        } else {
            inventory.inputs(id)
        } {
            Ok(inputs) => inputs,
            Err(error) => {
                report.issues.push(Issue {
                    unit: Some(id.clone()),
                    message: "cannot resolve required evidence inputs".into(),
                    details: vec![format!("{error:#}")],
                });
                report.statuses.push(UnitStatus {
                    unit: id.clone(),
                    evidence: "invalid sources",
                    correspondence: "not checked",
                });
                continue;
            }
        };
        if inventory
            .units
            .get(id)
            .is_some_and(|unit| unit.kind == UnitKind::FutureNote)
        {
            report.statuses.push(UnitStatus {
                unit: id.clone(),
                evidence: "future note",
                correspondence: "not applicable",
            });
            continue;
        }
        if inventory.units.get(id).is_some_and(|unit| unit.draft) {
            report.statuses.push(UnitStatus {
                unit: id.clone(),
                evidence: "draft",
                correspondence: "not asserted",
            });
            report.issues.push(Issue {
                unit: Some(id.clone()),
                message: format!("draft unit {id} requires formalization"),
                details: vec![
                    "draft status preserves the unit's semantic kind but cannot count as completed correspondence evidence".into(),
                ],
            });
            continue;
        }
        let mut current = BTreeSet::new();
        let mut stale = Vec::new();
        for bundle in bundles.values().filter(|bundle| &bundle.unit == id) {
            // Historical bundles compare with one independently derived current
            // manifest. Re-reading all sources for each past review made the
            // ordinary evidence test grow with the entire review history.
            let errors = validate_bundle_against(inventory, bundle, required.clone())?;
            if errors.is_empty() {
                current.insert(bundle.digest.clone());
            } else {
                stale.extend(errors);
            }
        }
        let empty_records = BTreeMap::new();
        let records = all_records.get(id).unwrap_or(&empty_records);
        let superseded: BTreeSet<_> = records
            .values()
            .flat_map(|review| review.supersedes.iter().cloned())
            .collect();
        let stale_active = records.iter().any(|(digest, review)| {
            !superseded.contains(digest) && !current.contains(&review.bundle)
        });
        let active: Vec<_> = records
            .iter()
            .filter(|(digest, review)| {
                current.contains(&review.bundle) && !superseded.contains(*digest)
            })
            .map(|(_, review)| review)
            .collect();
        // Cross-review order decisions may rely only on an entirely current,
        // positive subject; a conflicting or stale active record blocks it.
        if !stale_active
            && !active.is_empty()
            && active
                .iter()
                .all(|review| review.conclusion == Conclusion::Corresponds)
        {
            current_active.insert(
                id.clone(),
                active.iter().map(|review| (*review).clone()).collect(),
            );
        }
        let evidence = if stale_active {
            "stale"
        } else if !current.is_empty() {
            "current"
        } else if !stale.is_empty() {
            "stale"
        } else {
            "missing"
        };
        let correspondence = if stale_active {
            "stale decision"
        } else if active.is_empty() {
            "missing"
        } else if active
            .iter()
            .any(|review| review.conclusion == Conclusion::Mismatch)
        {
            "mismatch"
        } else if active
            .iter()
            .any(|review| review.conclusion == Conclusion::Inconclusive)
        {
            "inconclusive"
        } else {
            "corresponds"
        };
        report.statuses.push(UnitStatus {
            unit: id.clone(),
            evidence,
            correspondence,
        });
        if correspondence != "corresponds" {
            let mut details = if evidence == "stale" {
                stale
            } else {
                Vec::new()
            };
            details.sort();
            details.dedup();
            if evidence == "current" && active.is_empty() {
                details.push("preparing a bundle does not record a completed review".into());
            }
            report.issues.push(Issue {
                unit: Some(id.clone()),
                message: format!("{evidence} evidence for {id}: correspondence {correspondence}"),
                details,
            });
        }
    }
    for (unit, message) in link_audit::cross_validate(&audits, &current_active) {
        report.issues.push(Issue {
            unit: Some(unit),
            message,
            details: Vec::new(),
        });
    }
    Ok(report)
}
}
mdbook-dada/tests/evidence_validation.rs:complete_current_reviews_pass_and_remain_distinct_from_mechanical_checks
#![allow(unused)]
fn main() {
#[test]
fn complete_current_reviews_pass_and_remain_distinct_from_mechanical_checks() {
    let fixture = Fixture::new();
    fixture.complete_reviews();
    let inventory = fixture.inventory();
    let report = evidence::check(&inventory).unwrap();
    assert!(report.is_ok(), "{}", report.render(&inventory));
    assert_eq!(report.statuses.len(), 4);
    for status in &report.statuses {
        assert_eq!(status.evidence, "current");
        assert_eq!(status.correspondence, "corresponds");
        assert!(mdbook_dada::mechanical::status(&inventory.root)
            .unwrap()
            .is_empty());
    }
}
}
mdbook-dada/tests/evidence_validation.rs:prepared_bundles_are_not_completed_reviews
#![allow(unused)]
fn main() {
#[test]
fn prepared_bundles_are_not_completed_reviews() {
    let fixture = Fixture::new();
    let inventory = fixture.inventory();
    let bundle = fixture.bundle();
    evidence::save_bundle(&inventory, &bundle).unwrap();
    let report = evidence::check(&inventory).unwrap();
    assert!(!report.is_ok());
    let status = report
        .statuses
        .iter()
        .find(|status| status.unit == "model.empty")
        .unwrap();
    assert_eq!(status.evidence, "current");
    assert_eq!(status.correspondence, "missing");
    assert!(report
        .render(&inventory)
        .contains("preparing a bundle does not record a completed review"));
}
}
mdbook-dada/tests/evidence_validation.rs:explicit_dependencies_and_unit_links_must_resolve
#![allow(unused)]
fn main() {
#[test]
fn explicit_dependencies_and_unit_links_must_resolve() {
    let fixture = Fixture::new();
    for source in [
        MODEL.replace(":uses: model.variable", ":uses: model.missing"),
        MODEL.replace(
            "The empty list",
            "See {anchor-ref}`model.missing`. The empty list",
        ),
        MODEL.replace(
            "The empty list",
            "See [the missing unit](#claim-model.missing). The empty list",
        ),
    ] {
        fixture.write("md/model.md", &source);
        let error = Inventory::load(&fixture.0)
            .err()
            .expect("unresolved unit reference must fail");
        assert!(format!("{error:#}").contains("model.missing"));
    }

    // Referencing a real unit supplies its exact inputs even without :uses:.
    fixture.write(
        "md/model.md",
        &MODEL.replace(":uses: model.variable\n", "").replace(
            "The empty list",
            "See {anchor-ref}`model.variable`. The empty list",
        ),
    );
    let bundle = fixture.bundle();
    assert!(bundle
        .inputs
        .iter()
        .any(|input| input.key == "unit:model.variable"));
    assert!(bundle
        .inputs
        .iter()
        .any(|input| input.key == "lean:Fixture:Variable"));
}
}
mdbook-dada/tests/evidence_validation.rs:hidden_markdown_chapters_cannot_escape_required_evidence
#![allow(unused)]
fn main() {
#[test]
fn hidden_markdown_chapters_cannot_escape_required_evidence() {
    let fixture = Fixture::new();
    for (path, id) in [
        ("md/.hidden.md", "hidden.direct"),
        ("md/.drafts/chapter.md", "hidden.nested"),
    ] {
        fixture.write(path, &format!("# Hidden chapter\n\n```{{definition}} {id}\n:lean: Fixture:Variable\n\nA natural-number variable.\n```\n"));
    }
    fixture.write("md/SUMMARY.md", "# Summary\n\n- [Visible](model.md)\n- [Direct](.hidden.md)\n- [Nested](.drafts/chapter.md)\n");
    let inventory = fixture.inventory();
    for id in ["hidden.direct", "hidden.nested"] {
        assert!(inventory.required.contains(id));
        let report = evidence::check(&inventory).unwrap();
        assert!(report
            .statuses
            .iter()
            .any(|status| status.unit == id && status.evidence == "missing"));
    }
    fixture.complete_reviews();
    let report = evidence::check(&fixture.inventory()).unwrap();
    assert!(report.is_ok(), "{}", report.render(&fixture.inventory()));
}
}

Evidence and validation

anchormeta.evidence.inputs The checker derives a required input set from the current unit inventory. It does not accept a review’s own list as the definition of what must have been reviewed. That set includes the complete authored unit, every exact cited Lean declaration, its required source context, referenced units, and the review policy. Meta units also identify implementation and test targets. Their source files and declared dependencies are review inputs. Tool and schema versions, including book.toml, participate in freshness. Rendering and inventory use the same configured book and Lean source roots. Structured units reject mdBook expansion directives and nested legacy citation blocks; separate units and explicit dependencies keep those sources reviewable.

A bundle retains the exact input contents and content hashes in JSON, together with source identities and locations. A reviewer can retrieve what was considered, and another reviewer can inspect the same evidence later. A repository revision is useful provenance but does not replace these snapshots. Changing an unrelated file need not invalidate a review; changing an input does.

anchormeta.evidence.minimum_inputs Syntactic validation requires the authored unit and every cited formalization to be present under the correct input identities and to match current source. Substituting a different declaration, dropping a citation or dependency, or changing snapshot contents without updating their hashes is an error. Matching hashes establish input identity, not mathematical correspondence.

anchormeta.evidence.decisions A completed review records its bundle digest, reviewer identity, examined inputs, conclusion, rationale, and limitations. Conclusions distinguish correspondence, mismatch, and an inconclusive comparison. A prepared packet is not a completed review, and a mismatch is not positive evidence. Required positive review cannot be satisfied by merely creating a packet or filling in a conclusion field. Decisions may explicitly supersede earlier decisions for the same unit, including ones made against different input bundles. Every unsuperseded decision must be current and positive; a stale replacement cannot silently restore an older approval. The retained records preserve the decision history. Draft units fail evidence validation and cannot receive affirmative decisions. A cited theorem statement alone does not establish that its proof was checked.

The examined-input list must cover the authored units, exact Lean/Rust/test selections, policy, and extra files supplied with prepare --input. Conservative full-source and tool snapshots remain available for freshness and deeper inspection; a reviewer records them as examined only when actually used. The list is a syntactic attestation, not mechanical proof that reading occurred.

anchormeta.evidence.workspace_test An ordinary Cargo integration test validates the configured evidence through the same library used by dada-spec check. Running cargo test --workspace from v2/ therefore checks evidence presence, required inputs, schema, and freshness. This validation is deterministic and syntactic: it invokes no agent, network service, or Lean compiler. It cannot decide whether a recorded rationale is persuasive or a theorem captures the intended behavior.

Diagnostics use annotate-snippets to identify the relevant unit or citation and explain the repair. Missing or stale evidence directs the author to prepare a new bundle, perform its review, and record the result. A check must not refresh hashes or generate favorable reviews on the author’s behalf.

anchormeta.evidence.self_validation Meta requirements can cite Rust implementation symbols and named tests using :rust: and :tests:. Their correspondence reviews use the same snapshots and freshness rules as language units. Tests exercise specified cases and rejection paths; they do not prove all possible behavior. The validator’s own adversarial tests remain necessary even when a review of the validator is current. Its version is an input to evidence validation, and generated evidence is not an input to its own hash.

The command and review formats are described in Correspondence review. Mechanical Lean checking remains a separate just test-lean invocation. Mechanical records retain actual command outcomes separately; a recorded review is not an assertion that Lean or Cargo was executed.

Rendering and source selection

The renderer contracts specify identities, supported blocks, mathematics, source extraction, and diagrams. Each contract cites its implementation and tests. The authoring guide gives the syntax for writing units. The contracts describe textual processing; correspondence review and Lean compilation remain separate checks.

Mathematical presentation and review

anchormeta.math.source A grammar, judgment, or rule block contains authored mathematical notation and citations into Lean. A definition block contains an authored Markdown explanation with citations to its Lean formalization. A theorem or lemma block contains an authored Markdown statement, with a citation to its Lean theorem and proof. These accounts are part of the Markdown specification and stand on their own, with symbols and assumptions explained in the book. The preprocessor renders the authored account and extracts the cited source; it does not derive mathematics from Lean.

anchormeta.lean.definitions.source Lean files contain the formal declarations cited by the book. The mathematical account and its Lean formalization are maintained independently and compared through explicit correspondence review. Neither version automatically prevails in a discrepancy; resolving it can change either view or the intended design, as in refmeta.reviews.correspondence.

anchormeta.lean.definitions.presentation The mathematical presentation may use conventional symbols and omit Lean’s implementation details under explicit notation conventions. The Lean view retains the original declaration, including fields, proof arguments, and derived instances. The renderer does not infer a mathematical grammar from these details.

anchormeta.math.identifiers The book defines a shared vocabulary of mathematical categories and metavariables for use across chapters. Short conventional letters denote variables; upright text denotes multi-character constructor or helper names. A notation key relates these symbols to their meanings and cited Lean declarations. Changing notation requires updating uses and the relevant correspondence explanations together.

anchormeta.math.fields An authored grammar may use positional constructor arguments when the surrounding notation key and prose make their meaning unambiguous. The book explains how these arguments correspond to Lean’s named fields. Any omission or abstraction of a field must be stated; a shorter presentation must not silently discard a semantic distinction.

anchormeta.math.containers An overbar denotes a finite ordered sequence, and K ⇀ V denotes a finite map from keys in K to values in V. The notation abstracts from Lean’s List, Array, and FiniteMap representations. The representation and its associated proofs remain available in the cited source. See refmeta.syntax.lean.mathematical_containers.

anchormeta.math.abbreviations Authored notation may abbreviate terms and suppress proof terms under stated conventions. Implicit parameters must be explained where introduced. Conditions represented by proof arguments remain explicit: hiding the proof of freshness or distinctness does not remove that condition. Equations introducing intermediate names must preserve their dependencies and scopes.

anchormeta.math.heap_representation Each language chapter explains its own representation conventions. For example, Given writes an empty slot as \(\bot\) and an occupied slot as an object identity; Lean represents these as none and some object. Such abbreviations must preserve distinctions used by the rules. A list may be presented as a map only under the stated uniqueness conditions, and any order relevant to the semantics must remain visible. Omitting a proof term does not omit its condition.

anchormeta.math.rule.layout Each premise occupies its own line above the inference bar. Intermediate values can have short names with defining equations. Rules use the shared vocabulary consistently in premises and conclusions, including the judgment’s introduced notation. Grammar alternatives align with their definition symbol, as described in refmeta.syntax.lean.alignment.

anchormeta.math.correspondence A mathematical block must express the intended content of its cited Lean source under the book’s notation conventions. Review checks represented categories, variables, quantification, constructor fields, premises, conclusions, scopes, and hidden parameters or proof arguments. A source citation alone is not evidence that this correspondence holds. A discrepancy can require changes to either view or to the intended design, as in refmeta.reviews.correspondence.

For example, a rule may give a short name to the state obtained by clearing a slot. The Markdown defines that name and the affected location; the renderer does not reconstruct the update from Lean.

anchormeta.math.correspondence.evidence Review evidence identifies the authored mathematics, cited Lean source, and notation conventions it covers. Saved bundles and review records make the comparison inspectable and allow syntactic checks to identify missing or stale evidence when its inputs change. A successful citation lookup or MathJax render must not be reported as that review evidence.

Informational Selectors support inspection; the evidence checker validates record structure, coverage of required inputs, and freshness. Human or agent review still judges correspondence. Passing the checker does not establish mathematical equivalence between the authored account and Lean.

anchormeta.examples.coverage Every completed semantic example links to a Lean test of its intended behavior. A proposed scenario whose semantics or test is unfinished uses :status: draft; it is not presented as a checked example. Authoring-syntax illustrations are ordinary prose and literal code; they do not create additional semantic claims or evidence records.

anchormeta.examples.evidence The source association, Lean proof check, and correspondence review are separate checks. The preprocessor checks the association. Compiling the containing Lean file checks the example under its imports, declarations, and assumptions; that compilation is separate from rendering the book. Review checks that the example’s proposition and setup cover the behavior described by the Markdown, including any stated preconditions and results. Neither a valid citation nor a successful proof by itself establishes that correspondence or broader claim coverage.

anchormeta.syntax.lean.mathematical_containers The shared mathematical notation writes an overbar over an element or category for a finite ordered sequence, whether its Lean representation uses List or Array. A finite map is written K ⇀ V, with no finiteness subscript. Map domains, comprehensions, lookup, and update are defined where used. The notation does not assert that Lean’s list and array types are identical or erase any required bounds or uniqueness conditions. Supporting representation details, such as the proof field in FiniteMap, may remain only in Lean when their mathematical meaning has been stated in the book.

anchormeta.syntax.lean.alignment Authors align grammar definition symbols and alternative separators in one column. Long constructor arguments can continue on separate lines aligned with the first argument; rules place distinct premises on separate lines. These are conventions for the authored LaTeX, not layouts inferred from Lean syntax.