meta.book.browser_delivery

Book generation, standalone export, and local serving use the same resolved model and renderer to implement these browsing rules. Invalid models produce diagnostics instead of a partially valid explorer. A generated book or standalone HTML artifact includes the data and assets needed for navigation, search, entity links, and Rust source display without a Sage server. Each view identifies itself as a snapshot. Model or Rust edits become visible when that snapshot is rebuilt, exported again, or regenerated by restarting the server.

Read in specification context · design/meta/book.md

Implementation

TODO crates/sage-meta/tests/spec_plan.rs:180–187

sage_meta::todo · test:spec_plan

TODO: Compare served/exported/book snapshots; reject invalid models, browse offline, and verify regeneration reflects source edits.

#![allow(unused)]
fn main() {
    // {anchor}`meta.book.browser_delivery`<<
    #[test]
    #[sage::test(meta.book.browser_delivery)]
    fn browser_delivery_modes_share_a_validated_snapshot() {
        // TODO: Compare served/exported/book snapshots; reject invalid models,
        // browse offline, and verify regeneration reflects source edits.
    }
    // >>

}

See more source ↗

Tests and review

Indexed tests and the implementation-completeness and test-adequacy review; no test run is implied.

Implemented sage_meta::book_asset_is_self_contained_and_embeds_exact_script_safe_model_and_source

crates/sage-meta/tests/book.rs · test:book

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.browser_delivery)]
#[sage::test(meta.anchors.book_explorer)]
fn book_asset_is_self_contained_and_embeds_exact_script_safe_model_and_source() {
    let fixture = Fixture::new("manual");
    let prose = "</script><script>globalThis.compromised = true</script> & prose";
    fixture.model(
        "demo/crate.sage",
        &format!("crate demo {{ \"\"\"{prose}\"\"\" depends $support; module symbols; }}"),
    );
    let rust = format!(
        "// {prose}\n{}",
        std::fs::read_to_string(fixture.root.join("src/lib.rs")).unwrap()
    );
    fixture.write("src/lib.rs", &rust);
    let crates = fixture.source.join("design/crates");
    let escaped_parent = crates.join("nested");
    std::fs::create_dir_all(&escaped_parent).unwrap();
    std::fs::rename(crates.join("demo"), escaped_parent.join("demo")).unwrap();
    fixture.book("items");
    let html = std::fs::read_to_string(fixture.asset()).unwrap();
    assert!(!html.contains("</script><script>globalThis.compromised"));
    assert!(!html.contains("<script src="));
    assert!(!html.contains("<link rel=\"stylesheet\""));
    assert!(!html.contains("<!-- BROWSER_DATA -->"));
    assert!(!html.contains("/* BROWSER_JS */"));
    let model = script_data(&html, "model-data");
    let demo = model
        .as_array()
        .unwrap()
        .iter()
        .find(|document| document["namespace"] == "demo")
        .unwrap();
    assert_eq!(demo["document"]["header"]["Crate"]["purpose"], prose);
    let sources = script_data(&html, "source-data");
    assert_eq!(sources["files"]["src/lib.rs"], rust);
    assert_eq!(
        sources["targets"]["demo::symbols::Item"][0]["path"],
        "demo::symbols::ActualItem"
    );
    let navigation = script_data(&html, "book-data");
    assert_eq!(navigation["chapters"].as_object().unwrap().len(), 3);
    assert_eq!(
        navigation["chapters"]["demo"],
        "design/crates/nested/demo/crate.html"
    );
}
}

See more source ↗

Implemented sage_meta::invalid_models_and_correspondence_fail_before_publishing_an_explorer

crates/sage-meta/tests/book.rs · test:book

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.browser_delivery)]
#[sage::test(meta.book.crate_ownership)]
fn invalid_models_and_correspondence_fail_before_publishing_an_explorer() {
    for (path, replacement, expected) in [
        (
            "manual/design/crates/demo/symbols.sage",
            "module crate::symbols; struct Item { value: Missing }",
            "unknown type Missing",
        ),
        (
            "src/lib.rs",
            "#[sage::item(crate)] mod architecture {}",
            "has no Rust",
        ),
        (
            "src/lib.rs",
            "#[sage::item(support::Value)] pub struct WrongCrate;",
            "different crate",
        ),
    ] {
        let fixture = Fixture::new("manual");
        fixture.write(path, replacement);
        let output = fixture.run(&fixture.input("items"));
        assert!(!output.status.success());
        let error = String::from_utf8_lossy(&output.stderr);
        assert!(error.contains(expected), "{error}");
        assert!(output.stdout.is_empty());
        assert!(!fixture.asset().exists());
    }
}
}

See more source ↗

Implemented sage_meta::unchanged_preprocessing_preserves_asset_timestamp_and_source_edits_refresh_it

crates/sage-meta/tests/book.rs · test:book

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.browser_delivery)]
#[sage::test(meta.anchors.book_explorer)]
fn unchanged_preprocessing_preserves_asset_timestamp_and_source_edits_refresh_it() {
    let fixture = Fixture::new("manual");
    fixture.book("items");
    let before = std::fs::read(fixture.asset()).unwrap();
    let sentinel = std::time::UNIX_EPOCH + std::time::Duration::from_secs(1_700_000_000);
    std::fs::File::options()
        .write(true)
        .open(fixture.asset())
        .unwrap()
        .set_modified(sentinel)
        .unwrap();
    fixture.book("items");
    assert_eq!(std::fs::read(fixture.asset()).unwrap(), before);
    assert_eq!(
        std::fs::metadata(fixture.asset())
            .unwrap()
            .modified()
            .unwrap(),
        sentinel,
        "rewriting an unchanged source asset would repeatedly trigger mdbook serve"
    );
    fixture.model(
        "demo/symbols.sage",
        "module crate::symbols; struct Item { \"\"\"Updated symbol description.\"\"\" value: $support::Value, }",
    );
    let book = fixture.book("items");
    let after = std::fs::read_to_string(fixture.asset()).unwrap();
    assert_ne!(after.as_bytes(), before);
    assert!(after.contains("Updated symbol description."));
    let entries = chapters(book["items"].as_array().unwrap());
    assert!(
        entries["design/crates/demo/symbols.sage"]["content"]
            .as_str()
            .unwrap()
            .contains("Updated symbol description.")
    );
}
}

See more source ↗

TODO sage_meta::todo::browser_delivery_modes_share_a_validated_snapshot

crates/sage-meta/tests/spec_plan.rs · test:spec_plan

#![allow(unused)]
fn main() {
#[test]
    #[sage::test(meta.book.browser_delivery)]
    fn browser_delivery_modes_share_a_validated_snapshot() {
        // TODO: Compare served/exported/book snapshots; reject invalid models,
        // browse offline, and verify regeneration reflects source edits.
    }
}

See more source ↗

Review: Accepted · /root/final_quality.

Fresh delta-based review of meta.book.browser_delivery. Preserved and read the prior input/output, started fresh and recaptured all three prior additional fragments. Comparison of every fragment by path/selector shows exactly one change: four prerequisite-comment lines in the unrelated canonical-source TODO within the whole spec_plan.rs capture, documenting envelope-clause prose/source-span/owner prerequisites. No fragment was added or removed after recapture; implementation/test metadata, the complete browser_delivery claim, its own TODO and all three ordinary tests/helpers are unchanged. That comment does not affect this claim's behavior or adequacy. The full assessment was reconsidered and follows; no edits, build or tests performed.

Requirements: book generation, standalone export and local serving must share the resolved model/renderer; invalid inputs must diagnose before partial publication; artifacts must bundle navigation/search/entity/Rust-source data and assets for server-free use; each view must identify a snapshot; rebuild/export/restart must expose model and Rust changes. The sole implementation association is the explicit TODO browser_delivery_modes_share_a_validated_snapshot in spec_plan.rs, also the fourth associated test. Its comment calls for cross-mode comparison, invalid-model rejection, offline use and regeneration. It is a pending implementation/test entry, not ordinary implementation evidence. There is no ordinary implementation association to certify as fulfilling the full delivery contract.

Partial ordinary evidence, reassessed in full: book_asset_is_self_contained_and_embeds_exact_script_safe_model_and_source creates real model/Rust files containing hostile script-shaped text, preprocesses, checks no external script/stylesheet or unresolved template placeholders, parses embedded JSON and asserts exact prose/Rust contents, a Rust target mapping and nested-crate navigation paths. This supports static bundling and script-safe embedded content for book output; it does not execute offline navigation/search or establish export/serve equivalence. invalid_models_and_correspondence_fail_before_publishing_an_explorer exercises unknown types, missing correspondence and wrong-crate correspondence, requiring failed exit, the specific diagnostic, empty stdout and no explorer asset. This establishes the tested book failure-before-publication cases. unchanged_preprocessing_preserves_asset_timestamp_and_source_edits_refresh_it checks byte/mtime preservation for unchanged preprocessing, edits .sage prose and requires updated artifact and chapter contents. Its edit is model prose, not Rust; Rust refresh and other delivery modes remain deferred. Captured Fixture helpers invoke the real preprocess executable and parse actual artifacts; these assertions are substantive, not test-name evidence.

Deferral and prerequisites: shared resolved-renderer behavior across all three modes, actual offline interactive operations, snapshot labeling of every view and complete model/Rust regeneration across rebuild/export/restart remain explicit TODO scope. Completing the placeholder requires real cross-mode integration/browser fixtures and implementation associations, including Rust-edit refresh, not treating static book assertions or a passing empty TODO as full coverage. There are no N/A entries. The unrelated prerequisite comment does not close or expand this claim's delivery TODO. No new concrete defect or requested edit; no test execution outcome claimed.

Browse meta anchors

116 anchors

Anchor Implementation Tests

meta (116) 102 Implemented24 TODO 103 Implemented36 TODO

meta.anchors (22) 22 Implemented 21 Implemented12 TODO

anchor_pages Implemented ImplementedTODO

Every specification anchor has a stable page identifying the rule and showing its definition, context, implementation entries, and tests/evidence. The page includes Rust excerpts and access to surrounding source, and exposes each entry’s placeholder status and explanation. Multiple sites remain individually inspectable rather than being reduced to a single coverage badge.

Symposiun AGentic Environment (SAGE)

meta.book.browser_delivery

Implementation

Tests and review