meta.anchors.canonical_sources

A specification rule can be defined in a Markdown or .sage Design chapter, with equal authority. Its definition records the rule’s text and source location; a .sage definition also identifies its containing declaration, method, or envelope clause. Either documentation form can reference a rule defined in the other without creating another definition. Every reference must resolve to an existing definition; a dangling reference is an error.

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

Implementation

Implemented crates/sage-meta/src/spec.rs:805–810

sage_meta::spec · lib:sage_meta

#![allow(unused)]
fn main() {
    // {anchor}`meta.anchors.canonical_sources`
    fn add_chapter_text(
        &mut self,
        file: &str,
        namespace: &str,
        text: &str,

}

See more source ↗

Tests and review

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

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::reference_roles_validate_targets_but_ignore_code_examples

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.canonical_sources)]
#[sage::test(meta.anchors.unique_names)]
fn reference_roles_validate_targets_but_ignore_code_examples() {
    let fixture = BookFixture::new("- [Rules](design/rules.md)\n");
    fixture.write("design/rules.md", "{anchor}`claim` A precise claim.\n\nSee {spec}`missing.rule`.\n\n`` {spec}`example` ``\n\n```text\n{spec}`code.example`\n```\n\n{spec} malformed\n");
    let index = fixture.load();
    assert_eq!(index.references.len(), 1);
    assert!(index.diagnostics.iter().any(|error| {
        error
            .message
            .contains("unknown specification reference `missing.rule`")
    }));
    assert!(
        index
            .diagnostics
            .iter()
            .any(|error| error.message.contains("expected {spec}"))
    );
    assert_eq!(index.diagnostics.len(), 2);
}
}

See more source ↗

Implemented sage_meta::sage_prose_rules_have_precise_spans_model_owners_and_cross_source_references

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.canonical_sources)]
#[sage::test(meta.anchors.context_navigation)]
#[sage::test(meta.anchors.content.source_end)]
#[sage::test(meta.reviews.claim_text)]
#[sage::test(meta.anchors.unique_names)]
fn sage_prose_rules_have_precise_spans_model_owners_and_cross_source_references() {
    let fixture =
        BookFixture::new("- [Meta](design/meta.md)\n- [Crates](design/crates/README.md)\n");
    fixture.write(
        "design/meta.md",
        "{anchor}`rule` A rule refers to {spec}`crates.demo.nodes.member`.\n",
    );
    fixture.write("design/crates/README.md", "# Crates\n");
    fixture.write(
        "design/crates/demo/crate.sage",
        "crate demo { \"\"\"Demo.\"\"\" module nodes; }",
    );
    let sage = r#"module crate::nodes;
struct Value {
    """
    {anchor}`value`
    A value with **meaning**.

    Précise values survive edits.

    - Keep the cached value.

    ```text
        Preserve relative indentation.
    ```
    """
    """
    {anchor}`member`
    Fields obey {spec}`meta.rule`.
    """
    number: Value,
}
class Node {
    """A node."""
    query value() -> Value {
        """
        {anchor}`query`
        Query results have stable identity.
        """
        envelope {}
    }
}
"#;
    fixture.write("design/crates/demo/nodes.sage", sage);
    let index = fixture.load();
    assert!(index.diagnostics.is_empty(), "{:?}", index.diagnostics);
    let value = &index.anchors["crates.demo.nodes.value"];
    assert_eq!(value.entity.as_deref(), Some("demo::nodes::Value"));
    assert_eq!(
        value.content,
        "A value with **meaning**.\n\nPrécise values survive edits.\n\n- Keep the cached value.\n\n```text\n    Preserve relative indentation.\n```"
    );
    assert_eq!(&sage[value.span.start..value.span.end], "{anchor}`value`");
    assert_eq!(
        &sage[value.content_span.start..value.content_span.end],
        "A value with **meaning**.\n\n    Précise values survive edits.\n\n    - Keep the cached value.\n\n    ```text\n        Preserve relative indentation.\n    ```"
    );
    let rust = sage_meta::correspondence::CorrespondenceIndex::from_sources(&[]).unwrap();
    let inputs = sage_meta::review::inventory(&index, &rust).unwrap();
    assert_eq!(
        inputs["crates.demo.nodes.value"].fragments.iter().find(|fragment| matches!(&fragment.selector, sage_meta::review::Selector::Claim { anchor_id } if anchor_id == "crates.demo.nodes.value")).unwrap().contents.join("\n"),
        "A value with **meaning**.\n\nPrécise values survive edits.\n\n- Keep the cached value.\n\n```text\n    Preserve relative indentation.\n```"
    );
    assert_eq!(
        index.anchors["crates.demo.nodes.member"].entity.as_deref(),
        Some("demo::nodes::Value::number")
    );
    assert_eq!(
        index.anchors["crates.demo.nodes.member"].content,
        "Fields obey {spec}`meta.rule`."
    );
    assert_eq!(
        index.anchors["crates.demo.nodes.query"].entity.as_deref(),
        Some("demo::nodes::Node::value")
    );
    let query = &index.anchors["crates.demo.nodes.query"];
    assert_eq!(query.content, "Query results have stable identity.");
    assert_eq!(
        &sage[query.content_span.start..query.content_span.end],
        query.content
    );
    assert_eq!(
        value.context_url,
        "design/crates/demo/nodes.html#anchor:crates.demo.nodes.value"
    );
    assert_eq!(index.references.len(), 2);
    for reference in &index.references {
        assert_eq!(
            &index.sources[&reference.file][reference.span.start..reference.span.end],
            format!("{{spec}}`{}`", reference.name)
        );
    }
}
}

See more source ↗

TODO sage_meta::todo::definitions_across_markdown_and_sage

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

#![allow(unused)]
fn main() {
#[test]
    #[sage::test(meta.anchors.canonical_sources)]
    #[sage::test(meta.anchors.unique_names)]
    fn definitions_across_markdown_and_sage() {
        // TODO: Check both definition origins, cross-source duplicates,
        // references, preserved context, and the chapter-based naming rules.
        // Envelope-clause rule ownership additionally requires clause-level
        // prose syntax, captured clause source spans, and a stable clause owner
        // representation; parser::method models effects without prose. Add
        // owner/source-location assertions once that representation exists.
    }
}

See more source ↗

Review: Accepted · final_quality.

Fresh marker followup of meta.anchors.canonical_sources. Preserved prior input/output, started fresh, read the full claim and all four associated tests, and recaptured all prior dependencies: BookFixture lines 536–566, parser.rs lines 90–165 and whole file, and review inventory lines 155–200. Compared every fragment by path/selector and both association metadata collections. The sole delta is an implementation_references association comment on SpecIndex::validate_implementation_references; claim, canonical-source implementation behavior, parser, tests, helpers, and metadata are unchanged, with no removed captures. The following complete assessment rechecks that marker-only delta against the prior findings and preserves the documented deferral.

The ordinary implementation association is SpecIndex::add_chapter_text in spec.rs. Both normative Markdown and Sage Design inputs use this routine and one definition inventory, giving equal canonical authority. Markdown retains source positions directly; Sage prose is dedented with byte-offset mapping, then definition marker/content spans and references are remapped to original source locations. Model namespace plus prose owner gives declaration/field/method entity identity and chapter context URL. Definitions are inserted separately from references, and duplicate definitions diagnose instead of replacing an earlier definition. References are resolved against the completed inventory and dangling references receive file/span diagnostics. Nonnormative chapters contribute references without creating definitions. review inventory constructs claim text from anchor.content.

Three ordinary tests provide concrete evidence. nonnormative_book_chapters_reference_rules_without_defining_them asserts one canonical definition/two references, excludes an RFD marker as a definition, checks reference navigation and diagnoses a dangling reference in the RFD file. reference_roles_validate_targets_but_ignore_code_examples checks exactly one real reference and exactly two diagnostics for unknown target/malformed role, excluding inline/fenced examples. sage_prose_rules_have_precise_spans_model_owners_and_cross_source_references creates real Markdown and Sage sources referencing each other with no diagnostics; checks declaration, field and method owners, exact multiline Unicode/rich content, original marker/content source slices, context URL, both reference records and their exact source slices, and the saved review claim's dedented text. Captured BookFixture writes an isolated real book and invokes load_workspace. These bodies expose substantive assertions rather than relying on helper names.

The associated TODO definitions_across_markdown_and_sage remains incomplete. Its broader origin/duplicate/naming/context matrix is not established by the ordinary tests. In particular, envelope-clause ownership is not implemented or tested: parser::method creates effect entries without clause prose, clause spans or clause-specific owner representation. The explicit existing TODO states those prerequisites and calls for owner/source-location assertions once that representation exists. Parser dependencies remain captured. This root-approved deferral is retained honestly; the ordinary shared canonical-source mechanism does not imply envelope-clause completion. There are no N/A entries. Every claim aspect is either supported above or remains visibly deferred by that specific TODO.

No source edits or test execution were performed in this followup. Executed review start/read, capture comparisons and record; no new build or formatting was claimed. The isolated marker addition introduces no behavioral change or new adequacy gap. No requested edits.

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.anchors.canonical_sources

Implementation

Tests and review