meta.book.shared_model

Book generation and sage-meta check consume the same resolved Design chapter inventory, rule identities, source provenance, and correspondence data. Plugins that contribute specification chapters participate in that inventory. A source chapter omitted from the intended Design inventory is diagnosed rather than silently checked but unpublished or published but unchecked. Generated copies of rule text are not re-indexed as new definitions. The CLI, CI, and workspace test apply the shared validation to the book system’s own rules too.

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

Implementation

Implemented crates/sage-meta/src/spec.rs:636–641

sage_meta::spec · lib:sage_meta

#![allow(unused)]
fn main() {
    // {anchor}`meta.book.shared_model`
    pub fn load_workspace(workspace: &Path) -> Result<Self, Box<dyn std::error::Error>> {
        if !workspace.join("book.toml").is_file() {
            return Self::load(&workspace.join("md"));
        }
        let root = crate::workspace::book_source_root(workspace)?;

}

See more source ↗

TODO crates/sage-meta/tests/spec_plan.rs:243–250

sage_meta::todo · test:spec_plan

TODO: Use one inventory for plugins, checks, and rendering; diagnose omitted source chapters and avoid indexing generated copies twice.

#![allow(unused)]
fn main() {
    // {anchor}`meta.book.shared_model`<<
    #[test]
    #[sage::test(meta.book.shared_model)]
    fn generation_and_checking_share_the_design_inventory() {
        // TODO: Use one inventory for plugins, checks, and rendering; diagnose
        // omitted source chapters and avoid indexing generated copies twice.
    }
    // >>

}

See more source ↗

Implemented xtask/src/main.rs:104–109

xtask · bin:xtask

#![allow(unused)]
fn main() {
// {anchor}`meta.book.shared_model`
fn check_orphaned_chapters_at(root: &Path) -> Result<()> {
    let md_dir = sage_meta::workspace::book_source_root(root)?;
    let inventory = sage_meta::spec::SpecIndex::load_workspace(root)?;

    let mut md_files = BTreeSet::new();

}

See more source ↗

Tests and review

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

Implemented sage_meta::companion_guides_use_the_nearest_enclosing_crate_in_inventory_and_book

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.shared_model)]
fn companion_guides_use_the_nearest_enclosing_crate_in_inventory_and_book() {
    let fixture = Fixture::new("manual");
    std::fs::rename(
        fixture.source.join("design/crates/support"),
        fixture.source.join("design/crates/demo/support"),
    )
    .unwrap();
    fixture.doc("design/crates/demo/guide.md", "# Demo guide\n");
    fixture.doc("design/crates/demo/support/guide.md", "# Support guide\n");

    let spec = sage_meta::spec::SpecIndex::load_workspace(&fixture.root).unwrap();
    assert!(spec.diagnostics.is_empty(), "{:?}", spec.diagnostics);
    let book = fixture.book("items");
    let entries = chapters(book["items"].as_array().unwrap());
    for (file, owner) in [
        ("design/crates/demo/guide.md", "demo"),
        ("design/crates/demo/support/guide.md", "support"),
    ] {
        assert!(spec.chapters.contains_key(file));
        assert_eq!(entries[file]["source_path"], file);
        assert_eq!(
            entries[file]["parent_names"],
            json!(["Design", "Crates", owner])
        );
    }
}
}

See more source ↗

Implemented sage_meta::canonical_inventory_uses_configured_chapters_and_local_names

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.chapter_names)]
#[sage::test(meta.book.authority)]
#[sage::test(meta.book.shared_model)]
#[sage::test(meta.anchors.unique_names)]
fn canonical_inventory_uses_configured_chapters_and_local_names() {
    let fixture = BookFixture::new(
        "- [Design](design/README.md)\n  - [Meta](design/meta/README.md)\n  - [Rules](design/meta/call-rules.md)\n  - [Tenets](design/tenets.md)\n- [RFD](rfds/proposal.md)\n",
    );
    fixture.write("design/README.md", "# Design\n");
    fixture.write(
        "design/meta/README.md",
        "{anchor}`authority` Meta is normative.\n",
    );
    fixture.write(
        "design/meta/call-rules.md",
        "{anchor}`declared` Calls are declared.\n",
    );
    fixture.write("design/tenets.md", "{anchor}`not_a_rule` A motivation.\n");
    fixture.write(
        "rfds/proposal.md",
        "{anchor}`not_a_rule` Historical rationale.\n",
    );
    let index = fixture.load();
    assert!(index.diagnostics.is_empty(), "{:?}", index.diagnostics);
    assert_eq!(
        index.anchors.keys().map(String::as_str).collect::<Vec<_>>(),
        ["meta.authority", "meta.call_rules.declared"]
    );
    assert_eq!(index.chapters["design/meta/README.md"].namespace, "meta");
    assert_eq!(
        index.anchors["meta.authority"].context_url,
        "design/meta/index.html#meta.authority"
    );
    assert_eq!(index.documents, 3);
}
}

See more source ↗

Implemented sage_meta::generated_crate_guides_are_canonical_and_link_to_rendered_sage_chapters

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.shared_model)]
fn generated_crate_guides_are_canonical_and_link_to_rendered_sage_chapters() {
    let fixture = BookFixture::new("- [Crates](design/crates/README.md)\n");
    fixture.write(
        "design/crates/README.md",
        "Explore [Demo](demo/crate.sage#crate:demo).\n",
    );
    fixture.write(
        "design/crates/demo/crate.sage",
        "crate demo { \"\"\"Demo.\"\"\" }",
    );
    fixture.write(
        "design/crates/demo/guide.md",
        "{anchor}`claim` The guide supplements the model.\n",
    );
    let index = fixture.load();
    assert!(index.diagnostics.is_empty(), "{:?}", index.diagnostics);
    assert!(index.anchors.contains_key("crates.demo.guide.claim"));
    let rendered = index
        .render_chapter(
            "design/crates/README.md",
            "Explore [Demo](demo/crate.sage#crate:demo).\n",
        )
        .unwrap();
    assert_eq!(rendered, "Explore [Demo](demo/crate.html#crate:demo).\n");
    assert!(
        index
            .render_chapter("design/crates/README.md", "[Missing](demo/absent.sage)")
            .is_err()
    );
    fixture.write("SUMMARY.md", "- [Design](design/README.md)\n");
    fixture.write("design/README.md", "# Design\n");
    let unpublished = fixture.load();
    assert!(
        unpublished
            .diagnostics
            .iter()
            .any(|error| error.file.ends_with("crate.sage") && error.message.contains("omitted"))
    );
}
}

See more source ↗

Implemented sage_meta::noncanonical_crates_chapters_do_not_activate_generated_sources

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.shared_model)]
fn noncanonical_crates_chapters_do_not_activate_generated_sources() {
    let fixture = BookFixture::new("- [Crates](design/crates.md)\n");
    fixture.write(
        "design/crates.md",
        "{anchor}`landing` An explicit chapter.\n",
    );
    fixture.write(
        "design/crates/demo/crate.sage",
        "crate demo { \"\"\"Demo.\"\"\" }",
    );
    fixture.write(
        "design/crates/demo/guide.md",
        "{anchor}`claim` Owned guide.\n",
    );

    let index = fixture.load();
    assert_eq!(index.chapters.len(), 1);
    assert!(index.chapters.contains_key("design/crates.md"));
    assert_eq!(index.anchors.len(), 1);
    assert!(index.anchors.contains_key("crates.landing"));
    assert_eq!(index.diagnostics.len(), 2, "{:?}", index.diagnostics);
    for file in [
        "design/crates/demo/crate.sage",
        "design/crates/demo/guide.md",
    ] {
        assert!(index.diagnostics.iter().any(|error| {
            error.file == file
                && error
                    .message
                    .contains("omitted from the Design chapter inventory")
        }));
    }
}
}

See more source ↗

Implemented sage_meta::nonnormative_book_chapters_reference_rules_without_defining_them

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.shared_model)]
#[sage::test(meta.anchors.canonical_sources)]
fn nonnormative_book_chapters_reference_rules_without_defining_them() {
    let fixture = BookFixture::new(
        "- [Design](design/README.md)\n- [Tenets](design/tenets.md)\n- [History](rfds/history.md)\n",
    );
    fixture.write("design/README.md", "{anchor}`rule` A canonical rule.\n");
    fixture.write("design/tenets.md", "See {spec}`rule`.\n");
    fixture.write(
        "rfds/history.md",
        "See {spec}`rule`.\n\n{anchor}`historical` This is not a definition.\n",
    );
    let index = fixture.load();
    assert!(index.diagnostics.is_empty(), "{:?}", index.diagnostics);
    assert_eq!(index.anchors.len(), 1);
    assert_eq!(index.references.len(), 2);
    assert!(!index.chapters["rfds/history.md"].normative);
    assert!(
        index
            .render_chapter("design/tenets.md", "See {spec}`rule`.")
            .unwrap()
            .contains("href=\"anchor/rule.html\"")
    );
    fixture.write("rfds/history.md", "See {spec}`missing.rule`.\n");
    assert!(fixture.load().diagnostics.iter().any(|diagnostic| {
        diagnostic.file == "rfds/history.md"
            && diagnostic
                .message
                .contains("unknown specification reference")
    }));
}
}

See more source ↗

Implemented sage_meta::only_owned_crate_guides_are_automatically_published

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.shared_model)]
fn only_owned_crate_guides_are_automatically_published() {
    let fixture = BookFixture::new(
        "- [Crates](design/crates/README.md)\n  - [Shared](design/crates/shared.md)\n",
    );
    fixture.write("design/crates/README.md", "# Crates\n");
    fixture.write(
        "design/crates/demo/crate.sage",
        "crate demo { \"\"\"Demo.\"\"\" }",
    );
    fixture.write(
        "design/crates/demo/guide.md",
        "{anchor}`claim` Owned guide.\n",
    );
    fixture.write(
        "design/crates/shared.md",
        "{anchor}`claim` Explicit chapter.\n",
    );
    fixture.write(
        "design/crates/unowned/guide.md",
        "{anchor}`claim` Unpublished guide.\n",
    );

    let index = fixture.load();
    assert!(index.chapters.contains_key("design/crates/README.md"));
    assert!(index.chapters.contains_key("design/crates/demo/guide.md"));
    assert!(index.anchors.contains_key("crates.demo.guide.claim"));
    assert!(index.chapters.contains_key("design/crates/shared.md"));
    assert!(index.anchors.contains_key("crates.shared.claim"));
    assert!(
        !index
            .chapters
            .contains_key("design/crates/unowned/guide.md")
    );
    assert!(!index.anchors.contains_key("crates.unowned.guide.claim"));
    assert_eq!(index.diagnostics.len(), 1, "{:?}", index.diagnostics);
    assert_eq!(index.diagnostics[0].file, "design/crates/unowned/guide.md");
    assert!(
        index.diagnostics[0]
            .message
            .contains("omitted from the Design chapter inventory")
    );
}
}

See more source ↗

Implemented sage_meta::unpublished_rule_sources_do_not_silently_disappear

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.shared_model)]
fn unpublished_rule_sources_do_not_silently_disappear() {
    let fixture = BookFixture::new("- [Design](design/README.md)\n");
    fixture.write("design/README.md", "# Design\n");
    fixture.write("design/orphan.md", "{anchor}`claim` An unpublished rule.\n");
    let index = fixture.load();
    assert!(index.diagnostics.iter().any(|error| {
        error.file == "design/orphan.md"
            && error
                .message
                .contains("omitted from the Design chapter inventory")
    }));
}
}

See more source ↗

TODO sage_meta::todo::generation_and_checking_share_the_design_inventory

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

#![allow(unused)]
fn main() {
#[test]
    #[sage::test(meta.book.shared_model)]
    fn generation_and_checking_share_the_design_inventory() {
        // TODO: Use one inventory for plugins, checks, and rendering; diagnose
        // omitted source chapters and avoid indexing generated copies twice.
    }
}

See more source ↗

Implemented xtask::tests::orphan_check_uses_generated_chapters_and_rejects_unpublished_sources

xtask/src/main.rs · bin:xtask

#![allow(unused)]
fn main() {
#[test]
    #[sage::test(meta.book.shared_model)]
    fn orphan_check_uses_generated_chapters_and_rejects_unpublished_sources() {
        let root = std::env::temp_dir().join(format!(
            "sage-book-lint-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let source = root.join("manual");
        std::fs::create_dir_all(source.join("design/crates/demo")).unwrap();
        std::fs::write(root.join("book.toml"), "[book]\nsrc = 'manual'\n").unwrap();
        for (path, text) in [
            (
                "SUMMARY.md",
                "- [Guide](./guide.md#usage)\n- [Crates](design/crates/README.md)\n",
            ),
            ("guide.md", "# Usage\n"),
            ("design/crates/README.md", "# Crates\n"),
            (
                "design/crates/demo/crate.sage",
                "crate demo { \"\"\"Demo model.\"\"\" }",
            ),
            ("design/crates/demo/guide.md", "# Generated crate guide\n"),
        ] {
            std::fs::write(source.join(path), text).unwrap();
        }
        // The generated guide is published without its own SUMMARY.md entry.
        check_orphaned_chapters_at(&root).unwrap();

        std::fs::write(source.join("orphan.md"), "# Unpublished\n").unwrap();
        let error = check_orphaned_chapters_at(&root).unwrap_err().to_string();
        assert!(error.contains("orphaned markdown files"), "{error}");
        assert!(error.contains("manual/orphan.md"), "{error}");
        assert!(!error.contains("demo/guide.md"), "{error}");
        std::fs::remove_file(source.join("orphan.md")).unwrap();

        // A generated companion needs an enclosing modeled crate.
        std::fs::write(source.join("design/crates/unowned.md"), "# Unowned\n").unwrap();
        let error = check_orphaned_chapters_at(&root).unwrap_err().to_string();
        assert!(error.contains("design/crates/unowned.md"), "{error}");
        assert!(!error.contains("demo/guide.md"), "{error}");
        std::fs::remove_file(source.join("design/crates/unowned.md")).unwrap();

        // Merely residing under design/crates does not publish a chapter.
        std::fs::write(source.join("SUMMARY.md"), "- [Guide](guide.md)\n").unwrap();
        let error = check_orphaned_chapters_at(&root).unwrap_err().to_string();
        assert!(error.contains("design/crates/demo/guide.md"), "{error}");
        std::fs::remove_dir_all(root).unwrap();
    }
}

Conditional source: #[cfg(test)]

See more source ↗

Review: Accepted · final_quality.

Fresh final marker followup of meta.book.shared_model. Preserved previous input/output, started fresh, read the complete claim and all nine associated tests, and recaptured all previous dependencies: book/spec fixtures, book.rs, workspace.rs, check.rs, main.rs, workspace test, CI workflow, correspondence.rs and book/anchors.rs. Compared every fragment by path/selector and both association metadata sets. The sole change is an implementation_references association comment in spec.rs. All behavior, tests, claim, helpers, TODO text and metadata are unchanged; no fragments were removed. This actual delta was assessed against the full prior findings below.

Three implementation entries are accounted for: SpecIndex::load_workspace, xtask orphan checking and the explicit TODO region. The shared loader uses configured source root/SUMMARY, includes modeled Sage chapters and nearest-owned companion Markdown under the canonical Crates landing, and assigns canonical identities/provenance through shared chapter insertion. Generated anchor pages are excluded as definitions; omitted Design Markdown and model chapters diagnose errors. Captured book.rs and anchors.rs use that inventory to render chapters/rule pages; check.rs uses the same loader and CorrespondenceIndex with Cargo-owned discovery. Common workspace helpers supply model roots and ownership. CLI main invokes shared check, xtask CI invokes the CLI and workspace tests, the captured workflow invokes xtask ci test, and tests/workspace.rs applies sage_meta::check to the repository. No book-rule namespace exemption exists. These are wiring/source observations, not CI execution.

Eight ordinary tests provide substantive assertions. canonical_inventory_uses_configured_chapters_and_local_names checks exact normative keys, README context and document count. companion_guides_use_the_nearest_enclosing_crate_in_inventory_and_book compares index membership with actual book source_path/parent_names for nested demo/support guides. generated_crate_guides_are_canonical_and_link_to_rendered_sage_chapters checks companion definition, exact rewritten link, missing target rejection and omitted model diagnosis after removing the landing. noncanonical_crates_chapters_do_not_activate_generated_sources checks an alternative crates.md does not activate model/guide publication and both omissions diagnose. nonnormative_book_chapters_reference_rules_without_defining_them checks one definition/two references, rendered navigation and dangling historical reference errors. only_owned_crate_guides_are_automatically_published distinguishes owned, explicitly listed and unowned sources with exact inclusion/exclusion and a single omission error. unpublished_rule_sources_do_not_silently_disappear checks the orphan Design source diagnostic. xtask's orphan_check_uses_generated_chapters_and_rejects_unpublished_sources accepts generated guides, rejects non-Design orphans/unowned guides and missing landing publication, and excludes still-published guides from error text. Captured fixtures use actual files and preprocessing.

The ninth test and third implementation entry, TODO generation_and_checking_share_the_design_inventory, preserve incomplete full plugin/check/render and generated-copy parity coverage. The ordinary cases establish ownership/omission behavior but do not compare every identity/provenance/correspondence record across all consumers or prove arbitrary contributing plugins. Completion requires a representative chapter-contributing plugin fixture and generation/CLI/library/re-indexed-copy comparisons, including the book's own rules and negative omissions. The empty TODO is not treated as passing behavioral evidence. No N/A entries exist.

All requirements are supported by current shared mechanisms and concrete assertions or remain explicitly deferred in that TODO. No source edits, formatting, tests or workspace build were performed; executed review start/read, capture comparisons and record only. No requested edits.

Browse meta anchors

116 anchors

Specification anchors and declared coverage
AnchorImplementationTests
meta (116)102 Implemented24 TODO103 Implemented36 TODO
meta.anchors (22)22 Implemented21 Implemented12 TODO
anchor_pagesImplementedImplementedTODO
book_explorerImplementedImplementedTODO
canonical_sourcesImplementedImplementedTODO
meta.anchors.content (7)7 Implemented7 Implemented
blocksImplementedImplemented
explicit_endImplementedImplemented
headingImplementedImplemented
literal_syntaxImplementedImplemented
next_anchorImplementedImplemented
source_endImplementedImplemented
unmatched_endImplementedImplemented
context_navigationImplementedImplementedTODO
evidence_statusImplementedImplementedTODO
explorer_navigationImplementedTODO
implementation_coverageImplementedImplementedTODO
implementation_referencesImplementedImplementedTODO
placeholder_statusImplementedImplementedTODO
point_excerptsImplementedImplementedTODO
region_balanceImplementedImplemented
region_excerptsImplementedImplementedTODO
test_coverageImplementedImplemented
test_referencesImplementedImplemented
unique_namesImplementedImplementedTODO
meta.book (21)10 Implemented18 TODO12 Implemented18 TODO
anchor_movesImplementedTODOImplementedTODO
authorityImplementedTODOImplementedTODO
browser_deliveryTODOImplementedTODO
browser_dependenciesTODOTODO
browser_rust_sourceTODOTODO
browser_searchTODOTODO
browser_serveTODOTODO
browser_structureTODOTODO
chapter_namesImplementedTODOImplementedTODO
crate_ownershipImplementedImplemented
crates_landingImplementedImplemented
entity_linksTODOTODO
index_groupsImplementedTODOImplementedTODO
index_namespace_pagesImplementedImplemented
index_rowsImplementedTODOImplementedTODO
index_statusImplementedTODOImplementedTODO
rfd_changesTODOTODO
sage_chaptersTODOImplementedTODO
self_descriptionTODOTODO
shared_modelImplementedTODOImplementedTODO
source_rolesTODOTODO
meta.contracts (4)4 Implemented3 TODO4 Implemented3 TODO
cache_invocationsImplementedTODOImplementedTODO
correspondenceImplementedImplemented
observation_coverageImplementedTODOImplementedTODO
validated_sessionImplementedTODOImplementedTODO
meta.language (39)39 Implemented39 Implemented
meta.language.calls (2)2 Implemented2 Implemented
declaredImplementedImplemented
forbiddenImplementedImplemented
meta.language.classes (3)3 Implemented3 Implemented
abstract_completeImplementedImplemented
override_signatureImplementedImplemented
single_inheritanceImplementedImplemented
meta.language.contexts (1)1 Implemented1 Implemented
inheritanceImplementedImplemented
meta.language.envelopes (7)7 Implemented7 Implemented
class_callsImplementedImplemented
createsImplementedImplemented
direct_callsImplementedImplemented
leafImplementedImplemented
permissionsImplementedImplemented
readsImplementedImplemented
receiver_callsImplementedImplemented
meta.language.fields (2)2 Implemented2 Implemented
context_stateImplementedImplemented
kindsImplementedImplemented
meta.language.methods (2)2 Implemented2 Implemented
kindsImplementedImplemented
proseImplementedImplemented
meta.language.model (3)3 Implemented3 Implemented
forbidden_pathsImplementedImplemented
inherited_prohibitionsImplementedImplemented
virtual_dispatchImplementedImplemented
meta.language.types (19)19 Implemented19 Implemented
argument_arityImplementedImplemented
declaration_proseImplementedImplemented
enum_variantsImplementedImplemented
field_proseImplementedImplemented
generic_parametersImplementedImplemented
member_commasImplementedImplemented
name_resolutionImplementedImplemented
opaque_representationImplementedImplemented
preludeImplementedImplemented
qualified_namesImplementedImplemented
recursive_valuesImplementedImplemented
struct_fieldsImplementedImplemented
tuplesImplementedImplemented
type_expressionsImplementedImplemented
unique_fieldsImplementedImplemented
unique_parametersImplementedImplemented
unique_variantsImplementedImplemented
unknown_namesImplementedImplemented
variant_proseImplementedImplemented
meta.reviews (27)27 Implemented27 Implemented
claim_textImplementedImplemented
complete_test_setImplementedImplemented
decisionsImplementedImplemented
fragment_associationsImplementedImplemented
fragment_formatImplementedImplemented
fragment_freshnessImplementedImplemented
gateImplementedImplemented
input_formatImplementedImplemented
input_fragmentsImplementedImplemented
output_formatImplementedImplemented
preparationImplementedImplemented
record_requiredImplementedImplemented
recorded_readsImplementedImplemented
recordingImplementedImplemented
review_delegationImplementedImplemented
review_diagnosticsImplementedImplemented
review_instructionsImplementedImplemented
review_scopeImplementedImplemented
selector_claimImplementedImplemented
selector_line_rangeImplementedImplemented
selector_testImplementedImplemented
selector_whole_fileImplementedImplemented
source_representationImplementedImplemented
stalenessImplementedImplemented
summary_formatImplementedImplemented
test_sourceImplementedImplemented
validation_layoutImplementedImplemented
meta.validation (3)3 TODO3 TODO
claim_specific_evidenceTODOTODO
independent_inspectionTODOTODO
review_packetsTODOTODO