meta.anchors.implementation_references

A Rust implementation entry is introduced by a <code>// {anchor}`meta.language.calls.declared`</code> comment, optionally followed immediately by <<. Its name must resolve to a specification definition; malformed and unknown references are errors. Only actual Rust comments create these entries: marker-like text inside string literals does not. Entries retain their source location and enclosing module, and multiple entries may reference the same rule, including across crates.

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

Implementation

Implemented crates/sage-meta/src/evidence.rs:78–83

sage_meta::evidence · lib:sage_meta

#![allow(unused)]
fn main() {
// {anchor}`meta.anchors.implementation_references`
// {anchor}`meta.anchors.evidence_status`
pub(crate) fn index_source(
    source: &str,
    syntax: &syn::File,
    context: SourceContext<'_>,

}

See more source ↗

Implemented crates/sage-meta/src/spec.rs:146–151

sage_meta::spec · lib:sage_meta

#![allow(unused)]
fn main() {
    // {anchor}`meta.anchors.implementation_references`
    pub fn validate_implementation_references(
        &self,
        rust: &crate::correspondence::CorrespondenceIndex,
    ) -> Vec<Diagnostic> {
        rust.implementations

}

See more source ↗

Tests and review

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

Implemented sage_meta::cargo_owned_out_of_line_sources_retain_inherited_module_and_cfg

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.implementation_references)]
#[sage::test(meta.anchors.evidence_status)]
fn cargo_owned_out_of_line_sources_retain_inherited_module_and_cfg() {
    let directory =
        std::env::temp_dir().join(format!("sage-evidence-owned-{}", std::process::id()));
    let _ = std::fs::remove_dir_all(&directory);
    std::fs::create_dir_all(directory.join("src")).unwrap();
    std::fs::write(directory.join("Cargo.toml"), "[package]\nname = \"evidence-fixture\"\nversion = \"0.0.0\"\nedition = \"2024\"\n[workspace]\n").unwrap();
    std::fs::write(directory.join("src/lib.rs"), "#[cfg(any())]\nmod todo;\n").unwrap();
    std::fs::write(
        directory.join("src/todo.rs"),
        "// {anchor}`example.pending`\n// TODO: Add the implementation.\n",
    )
    .unwrap();
    std::fs::write(
        directory.join("src/unowned.rs"),
        "// {anchor}`example.unowned`\n",
    )
    .unwrap();
    let rust = CorrespondenceIndex::load(&directory).unwrap();
    std::fs::remove_dir_all(&directory).unwrap();
    assert!(rust.diagnostics.is_empty(), "{:?}", rust.diagnostics);
    assert_eq!(rust.implementations.len(), 1);
    let site = &rust.implementations["example.pending"][0];
    assert_eq!(site.file, "src/todo.rs");
    assert_eq!(site.module, "evidence_fixture::todo");
    assert_eq!(site.status, EvidenceStatus::Todo);
    assert_eq!(site.cfg, ["#[cfg(any())]"]);
    assert_eq!(
        site.explanation.as_deref(),
        Some("TODO: Add the implementation.")
    );
    assert_eq!(site.excerpt, rust.files["src/todo.rs"]);
}
}

See more source ↗

Implemented sage_meta::malformed_reference_names_and_suffixes_are_errors

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.implementation_references)]
fn malformed_reference_names_and_suffixes_are_errors() {
    for text in [
        "// {anchor}missing",
        "// {anchor} `example.space`",
        "// {anchor}`example..empty`",
        "// {anchor}`example.9number`",
        "// {anchor}`éxample.unicode`",
        "// {anchor}`example.ok` trailing prose",
        "// {anchor}`example.ok` <<",
        "// {anchor}`example.ok`<<<",
        "// {anchor}`example.unclosed",
    ] {
        let rust = index(text);
        assert!(rust.implementations.is_empty(), "accepted {text}");
        assert_eq!(rust.diagnostics.len(), 1, "{text}");
        assert!(
            rust.diagnostics[0]
                .message
                .contains("malformed implementation reference")
        );
    }
}
}

See more source ↗

Implemented sage_meta::only_actual_line_comments_declare_implementation_entries

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.implementation_references)]
fn only_actual_line_comments_declare_implementation_entries() {
    let source = r####"#!/usr/bin/env ignored(with-unbalanced-parenthesis
const TEXT: &str = "// {anchor}`example.string`";
const RAW: &str = r###"
// {anchor}`example.raw`<<
// >>
"###;
const BYTE: &[u8] = br#"// {anchor}`example.byte`"#;
const C: &std::ffi::CStr = c"// {anchor}`example.c`";
const RAW_C: &std::ffi::CStr = cr#"// {anchor}`example.raw_c`"#;
const ESCAPED: &str = "quote \" // {anchor}`example.escaped`";
const CHAR: char = '\'';
/* Nested comment /* // {anchor}`example.block` */
// >>
*/
/// {anchor}`example.doc`
fn café<'a>() {
    let café = "é"; // {anchor}`example.real`
    // Explanation belongs to a real source comment.
}
macro_rules! source_comments {
    () => {
        // {anchor}`example.macro_input`
        ()
    }
}
"####;
    let rust = index(source);
    assert!(rust.diagnostics.is_empty(), "{:?}", rust.diagnostics);
    assert_eq!(
        rust.implementations
            .keys()
            .map(String::as_str)
            .collect::<Vec<_>>(),
        ["example.macro_input", "example.real"]
    );
    let site = &rust.implementations["example.real"][0];
    assert_eq!(site.module, "fixture");
    assert_eq!(site.file, "src/lib.rs");
    assert_eq!(site.line, 17);
    assert_eq!(
        &source[site.annotation_span.start..site.annotation_span.end],
        "// {anchor}`example.real`"
    );
    assert!(
        rust.entries.is_empty(),
        "comments are not sage::item mappings"
    );
    assert!(rust.tests.is_empty(), "comments are not annotated tests");
}
}

See more source ↗

Implemented sage_meta::repeated_references_keep_distinct_crates_and_targets

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.implementation_references)]
fn repeated_references_keep_distinct_crates_and_targets() {
    let sources = [
        RustSource {
            crate_name: "first".into(),
            target: "lib:first".into(),
            file: "first/lib.rs".into(),
            source: "// {anchor}`example.shared`\n".into(),
        },
        RustSource {
            crate_name: "second".into(),
            target: "bin:runner".into(),
            file: "second/main.rs".into(),
            source: "// {anchor}`example.shared`\n// {anchor}`example.shared`\n".into(),
        },
    ];
    let rust = CorrespondenceIndex::from_sources(&sources).unwrap();
    let sites = &rust.implementations["example.shared"];
    assert!(rust.diagnostics.is_empty());
    assert_eq!(sites.len(), 3);
    assert_eq!(sites[0].crate_name, "first");
    assert_eq!(sites[0].target, "lib:first");
    assert_eq!(sites[1].crate_name, "second");
    assert_eq!(sites[1].target, "bin:runner");
    assert_ne!(sites[1].annotation_span, sites[2].annotation_span);
    assert_eq!(rust.files["second/main.rs"], sources[1].source);
}
}

See more source ↗

TODO sage_meta::todo::rust_implementation_references

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

#![allow(unused)]
fn main() {
#[test]
    #[sage::test(meta.anchors.implementation_references)]
    fn rust_implementation_references() {
        // TODO: Resolve real comments across crates; reject malformed/dangling
        // references and exclude marker-like string contents.
    }
}

See more source ↗

Review: Accepted · Codex /root/anchor_094.

Fresh followup review of implementation_references after the root-authorized essential association was added immediately before SpecIndex::validate_implementation_references. No behavior was changed. cargo fmt and cargo build completed (existing warnings). A fresh start confirms the claim, evidence.rs and all tests are unchanged from the independently inspected pre-marker inputs; spec.rs is now included as an implementation capture, rather than merely a helper dependency. This report reassesses the complete claim, not only that marker.

The two ordinary implementations cover distinct obligations. evidence::index_source recognizes ordinary Rust line comments, parses the exact {anchor}`name` syntax with only an empty suffix or immediate << accepted, validates names, and diagnoses malformed references. Its token-derived literal ranges exclude ordinary/raw/byte/C/escaped string forms and chars; its scanner skips nested block comments and documentation comments. Source sites preserve file, crate, target, enclosing module, annotation byte range, line numbers, and excerpt. References are appended to vectors by name, so multiple sites and crates remain distinct. SpecIndex::validate_implementation_references checks each name against actual definitions and emits an error for each unknown site using its original file/annotation span. The captured correspondence helper supplies Cargo/source module context to the evidence index without replacing these semantics.

All four ordinary tests were read fully. only_actual_line_comments_declare_implementation_entries exercises string variants, nested comments, docs, shebang, Unicode and macro-body comments; it requires exactly the two real comment entries, correct module/file/line and exact source annotation slice, and verifies comments do not fabricate item mappings or tests. malformed_reference_names_and_suffixes_are_errors enumerates nine malformed forms, including spaced << and extra suffix characters, and requires no entries, exactly one diagnostic, and the malformed-reference message for each. repeated_references_keep_distinct_crates_and_targets requires three sites for one rule across two crates/targets, preserves source, and distinguishes repeated annotation ranges. cargo_owned_out_of_line_sources_retain_inherited_module_and_cfg constructs an actual Cargo fixture, verifies the inherited out-of-line module, file, cfg, explanation and exact excerpt, and excludes an unowned source file.

The additionally captured semantic test nested_regions_close_the_nearest_opener_and_points_keep_their_own_preview demonstrates successful immediate << parsing with nested regions: no diagnostics, exact region flags/line extents/excerpts and a distinct point preview. The captured index helper passes fixture source to production CorrespondenceIndex::from_sources. Unknown-reference checking is visible in the new essential implementation association, but its full cross-source resolution regression matrix remains explicitly deferred by the sole TODO rust_implementation_references. That TODO also lists malformed/string/cross-crate aspects already partially covered by ordinary tests; it is not treated as executed proof or erased by that overlap. Completing the remaining end-to-end dangling/resolution cases requires fixtures pairing the implementation inventory with specification definitions and invoking validation. Existing source logic is present; exhaustive integrated test coverage is not claimed.

Every claim aspect is supported by inspected source and meaningful assertions or accounted for by that retained TODO. No behavioral bug was observed, and no behavioral tests were run in this review; only fmt/build and review commands. Independent post-codegen/Sage sanity review of the one association comment was requested through root's existing quality-review agent. No further source changes or requested edits are necessary for this anchor.

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.implementation_references

Implementation

Tests and review