meta.reviews.recorded_reads

The recorded-read command takes an anchor with an active review directory, a workspace-relative source path, and a selector from meta.reviews.fragment_format. A read without an explicit selector selects the whole file. It appends the selected contents and selector directly to that anchor’s input.json before returning those same contents to the reviewer. Repeated reads are retained in order. Reads outside the workspace, invalid selections, and reads without an active unfinished review are rejected. These fragments participate in the same freshness checks as the initial inputs.

Reviewers declare every additional source dependency through this command and are responsible for the completeness of those declarations.

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

Implementation

Implemented crates/sage-meta/src/review.rs:556–561

sage_meta::review · lib:sage_meta

#![allow(unused)]
fn main() {
// {anchor}`meta.reviews.recorded_reads`
pub fn capture_read(
    workspace: &Path,
    anchor: &str,
    path: &str,
    selector: Selector,

}

See more source ↗

Implemented crates/sage-meta/src/main.rs:101–106

sage_meta · bin:sage-meta

#![allow(unused)]
fn main() {
// {anchor}`meta.reviews.recorded_reads`
// {anchor}`meta.reviews.recording`
// {anchor}`meta.reviews.review_instructions`
fn review(args: &[std::ffi::OsString]) -> Result<(), Box<dyn std::error::Error>> {
    use sage_meta::review::{self, Selector, ValidationOutput};
    let args = args

}

See more source ↗

Tests and review

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

Implemented sage_meta::another_anchors_test_read_tracks_body_and_identity

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.fragment_freshness)]
#[sage::test(meta.reviews.selector_test)]
#[sage::test(meta.reviews.recorded_reads)]
fn another_anchors_test_read_tracks_body_and_identity() {
    for change in ["body", "missing", "ambiguous"] {
        let fixture = Fixture::new();
        fixture.write(
            "md/design/README.md",
            &format!("{CLAIM}\n{{anchor}}`demo.other`\nOther scenario.\n"),
        );
        fixture.write("src/behavior.rs", "// {anchor}`demo.rule`\npub fn result() -> u32 { 4 }\n// {anchor}`demo.other`\npub fn other() -> u32 { 5 }\n");
        let other = "#[test] #[sage::test(demo.other)] fn other() { assert_eq!(2 + 3, 5); }";
        fixture.write("src/tests.rs", &format!("{TEST}\n{other}"));
        let initial = fixture.start();
        let selector = Selector::Test {
            crate_name: "demo".into(),
            target: "lib:demo".into(),
            rust_path: "demo::tests::other".into(),
        };
        assert_eq!(
            review::capture_read(&fixture.0, "demo.rule", "src/tests.rs", selector).unwrap(),
            other
        );
        let changed = match change {
            "body" => other.replace("2 + 3", "1 + 4"),
            "missing" => other.replace("fn other()", "fn renamed()"),
            _ => format!("#[cfg(unix)] {other}\n#[cfg(windows)] {other}"),
        };
        fixture.write(
            "src/tests.rs",
            &format!("// unrelated line\n{TEST}\n{changed}"),
        );
        if change != "ambiguous" {
            let spec = sage_meta::spec::SpecIndex::load_workspace(&fixture.0).unwrap();
            let rust = sage_meta::correspondence::CorrespondenceIndex::load(&fixture.0).unwrap();
            let current = review::inventory(&spec, &rust).unwrap();
            assert_eq!(initial.fragments, current["demo.rule"].fragments);
            assert_eq!(initial.tests, current["demo.rule"].tests);
        }
        assert!(
            review::record(&fixture.0, "demo.rule", &Fixture::report()).is_err(),
            "{change}"
        );
        assert!(!fixture.0.join("validations/demo.rule/output.json").exists());
    }
}
}

See more source ↗

Implemented sage_meta::cli_read_defaults_to_whole_file_from_workspace_subdirectory

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.recorded_reads)]
fn cli_read_defaults_to_whole_file_from_workspace_subdirectory() {
    let fixture = Fixture::new();
    let before = fixture.start();
    let text = "first\r\nsecond\n";
    fixture.write("context.txt", text);
    let output = std::process::Command::new(env!("CARGO_BIN_EXE_sage-meta"))
        .current_dir(fixture.0.join("src"))
        .args(["review", "read", "demo.rule", "context.txt"])
        .output()
        .unwrap();
    assert!(
        output.status.success(),
        "{}",
        String::from_utf8_lossy(&output.stderr)
    );
    assert_eq!(output.stdout, text.as_bytes());
    let after = fixture.input();
    assert_eq!(after.fragments.len(), before.fragments.len() + 1);
    assert_eq!(
        &after.fragments[..before.fragments.len()],
        before.fragments.as_slice()
    );
    let captured = after.fragments.last().unwrap();
    assert_eq!(captured.path, "context.txt");
    assert_eq!(captured.selector, Selector::WholeFile);
    assert_eq!(captured.contents.join("\n"), text);
    assert!(fixture.summary()["recorded_at_unix_seconds"].is_null());
}
}

See more source ↗

Implemented sage_meta::declared_claim_read_tracks_selected_text_without_capturing_the_document

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.selector_claim)]
#[sage::test(meta.reviews.fragment_freshness)]
#[sage::test(meta.reviews.recorded_reads)]
fn declared_claim_read_tracks_selected_text_without_capturing_the_document() {
    let fixture = Fixture::new();
    fixture.start();
    let text = review::capture_read(
        &fixture.0,
        "demo.rule",
        "md/design/README.md",
        Selector::Claim {
            anchor_id: "demo.rule".into(),
        },
    )
    .unwrap();
    assert_eq!(text, "The result is four.");
    let input = fixture.input();
    assert_eq!(input.fragments.last().unwrap().contents.join("\n"), text);
    review::record(&fixture.0, "demo.rule", &Fixture::report()).unwrap();
    fixture.write(
        "md/design/README.md",
        &format!("# An unrelated heading\n\n{CLAIM}"),
    );
    assert!(sage_meta::check(&fixture.0).is_valid());
    fixture.write("md/design/README.md", &CLAIM.replace("four", "five"));
    assert!(!sage_meta::check(&fixture.0).is_valid());
}
}

See more source ↗

Implemented sage_meta::invalid_ids_and_paths_are_rejected_without_destroying_existing_reports

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.preparation)]
#[sage::test(meta.reviews.recorded_reads)]
#[sage::test(meta.reviews.gate)]
#[sage::test(meta.reviews.validation_layout)]
fn invalid_ids_and_paths_are_rejected_without_destroying_existing_reports() {
    let fixture = Fixture::new();
    fixture.approve();
    let output = std::fs::read(fixture.0.join("validations/demo.rule/output.json")).unwrap();
    for anchor in [
        "../escape",
        "/absolute",
        "demo/rule",
        "demo..rule",
        "demo.missing",
    ] {
        assert!(review::start(&fixture.0, anchor, vec![]).is_err());
        assert_eq!(
            output,
            std::fs::read(fixture.0.join("validations/demo.rule/output.json")).unwrap()
        );
    }
    assert!(
        review::capture_read(
            &fixture.0,
            "demo.missing",
            "src/tests.rs",
            Selector::WholeFile
        )
        .is_err()
    );
    fixture.start();
    let before = fixture.input();
    for path in ["../outside", "/etc/passwd", "missing.txt"] {
        assert!(review::capture_read(&fixture.0, "demo.rule", path, Selector::WholeFile).is_err());
        assert_eq!(fixture.input(), before);
    }
    assert!(
        review::capture_read(
            &fixture.0,
            "demo.rule",
            "src/tests.rs",
            Selector::Claim {
                anchor_id: "demo.rule".into()
            }
        )
        .is_err()
    );
    assert!(
        review::capture_read(
            &fixture.0,
            "demo.rule",
            "src/tests.rs",
            Selector::Test {
                crate_name: "demo".into(),
                target: "test:missing".into(),
                rust_path: "demo::tests::verifies_result".into()
            }
        )
        .is_err()
    );
    assert_eq!(fixture.input(), before);
}
}

See more source ↗

Implemented sage_meta::recorded_reads_reject_symlink_escape_without_capturing_context

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

#![allow(unused)]
fn main() {
#[cfg(unix)]
#[test]
#[sage::test(meta.reviews.recorded_reads)]
fn recorded_reads_reject_symlink_escape_without_capturing_context() {
    let fixture = Fixture::new();
    fixture.start();
    let before = fixture.input();
    std::os::unix::fs::symlink("/etc/passwd", fixture.0.join("escape")).unwrap();
    assert!(review::capture_read(&fixture.0, "demo.rule", "escape", Selector::WholeFile).is_err());
    assert_eq!(before, fixture.input());
}
}

Conditional source: #[cfg(unix)]

See more source ↗

Implemented sage_meta::start_invalidates_previous_success_and_record_is_required

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.validation_layout)]
#[sage::test(meta.reviews.summary_format)]
#[sage::test(meta.reviews.preparation)]
#[sage::test(meta.reviews.record_required)]
#[sage::test(meta.reviews.recorded_reads)]
#[sage::test(meta.reviews.recording)]
#[sage::test(meta.reviews.decisions)]
fn start_invalidates_previous_success_and_record_is_required() {
    let fixture = Fixture::new();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    fixture.approve();
    assert!(sage_meta::check(&fixture.0).is_valid());
    let input = fixture.start();
    assert_eq!(fixture.input(), input);
    let summary = fixture.summary();
    assert_eq!(summary["anchor"], "demo.rule");
    assert!(summary["started_at_unix_seconds"].as_u64().unwrap() > 0);
    assert!(summary["recorded_at_unix_seconds"].is_null());
    assert_eq!(summary["schema_version"], review::SCHEMA_VERSION);
    assert_eq!(summary["policy_version"], review::POLICY_VERSION);
    assert!(summary.get("input_sha256").is_none());
    assert!(!fixture.0.join("validations/demo.rule/output.json").exists());
    assert!(!sage_meta::check(&fixture.0).is_valid());
    let saved = review::load_saved(&fixture.0.join("validations")).unwrap();
    assert_eq!(saved.reviews.len(), 1);
    assert!(saved.reviews[0].output.is_none());
    fixture.write("helper.txt", "context\n");
    review::capture_read(&fixture.0, "demo.rule", "helper.txt", Selector::WholeFile).unwrap();
    assert!(!sage_meta::check(&fixture.0).is_valid());
    let bytes = std::fs::read(fixture.0.join("validations/demo.rule/input.json")).unwrap();
    review::record(&fixture.0, "demo.rule", &Fixture::report()).unwrap();
    assert_eq!(
        bytes,
        std::fs::read(fixture.0.join("validations/demo.rule/input.json")).unwrap()
    );
    assert!(
        fixture.summary()["recorded_at_unix_seconds"]
            .as_u64()
            .unwrap()
            >= summary["started_at_unix_seconds"].as_u64().unwrap()
    );
    assert!(sage_meta::check(&fixture.0).is_valid());
    assert!(review::record(&fixture.0, "demo.rule", &Fixture::report()).is_err());
    assert!(
        review::capture_read(&fixture.0, "demo.rule", "helper.txt", Selector::WholeFile).is_err()
    );
}
}

See more source ↗

Implemented sage_meta::test_selectors_disambiguate_identical_paths_by_cargo_target

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.selector_test)]
#[sage::test(meta.reviews.recorded_reads)]
fn test_selectors_disambiguate_identical_paths_by_cargo_target() {
    let fixture = Fixture::new();
    // The same physical source is compiled as two independently named targets.
    fixture.write("Cargo.toml", "[package]\nname = 'demo'\nversion = '0.0.0'\nedition = '2024'\n[workspace]\n[[test]]\nname = 'first'\npath = 'tests/shared.rs'\n[[test]]\nname = 'second'\npath = 'tests/shared.rs'\n");
    fixture.write(
        "tests/shared.rs",
        "#[test] #[sage::test(demo.rule)] fn shared() { assert_eq!(4, 4); }",
    );
    let input = fixture.start();
    let tests: Vec<_> = input
        .tests
        .iter()
        .filter(|test| test.file == "tests/shared.rs")
        .collect();
    assert_eq!(tests.len(), 2);
    assert_ne!(tests[0].target, tests[1].target);
    for test in tests {
        let result = review::capture_read(
            &fixture.0,
            "demo.rule",
            &test.file,
            Selector::Test {
                crate_name: test.crate_name.clone(),
                target: test.target.clone(),
                rust_path: test.rust_path.clone(),
            },
        )
        .unwrap();
        assert_eq!(
            result,
            "#[test] #[sage::test(demo.rule)] fn shared() { assert_eq!(4, 4); }"
        );
    }
    assert!(
        review::capture_read(
            &fixture.0,
            "demo.rule",
            "tests/shared.rs",
            Selector::Test {
                crate_name: "other".into(),
                target: "test:first".into(),
                rust_path: "demo::shared".into()
            }
        )
        .is_err()
    );
}
}

See more source ↗

Implemented sage_meta::whole_files_and_ranges_preserve_exact_line_endings_and_detect_selected_edits

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.reviews.selector_whole_file)]
#[sage::test(meta.reviews.selector_line_range)]
#[sage::test(meta.reviews.recorded_reads)]
#[sage::test(meta.reviews.fragment_freshness)]
#[sage::test(meta.reviews.input_format)]
#[sage::test(meta.reviews.input_fragments)]
#[sage::test(meta.reviews.source_representation)]
#[sage::test(meta.reviews.staleness)]
fn whole_files_and_ranges_preserve_exact_line_endings_and_detect_selected_edits() {
    let fixture = Fixture::new();
    fixture.start();
    fixture.write("helper.txt", "first\r\n\r\nthird\nlast");
    assert_eq!(
        review::capture_read(
            &fixture.0,
            "demo.rule",
            "helper.txt",
            Selector::LineRange { start: 1, end: 2 }
        )
        .unwrap(),
        "first\r\n\r\n"
    );
    assert_eq!(
        review::capture_read(
            &fixture.0,
            "demo.rule",
            "helper.txt",
            Selector::LineRange { start: 4, end: 4 }
        )
        .unwrap(),
        "last"
    );
    for (start, end) in [(0, 1), (3, 2), (1, 5), (5, 5)] {
        assert!(
            review::capture_read(
                &fixture.0,
                "demo.rule",
                "helper.txt",
                Selector::LineRange { start, end }
            )
            .is_err()
        );
    }
    review::record(&fixture.0, "demo.rule", &Fixture::report()).unwrap();
    fixture.write("helper.txt", "first\r\n\r\nUNSELECTED\nlast");
    assert!(sage_meta::check(&fixture.0).is_valid());
    fixture.write("helper.txt", "changed\r\n\r\nthird\nlast");
    assert!(!sage_meta::check(&fixture.0).is_valid());
    fixture.start();
    for _ in 0..2 {
        assert_eq!(
            review::capture_read(&fixture.0, "demo.rule", "helper.txt", Selector::WholeFile)
                .unwrap(),
            "changed\r\n\r\nthird\nlast"
        );
    }
    let input = fixture.input();
    let tail = &input.fragments[input.fragments.len() - 2..];
    assert_eq!(tail[0], tail[1]);
    assert_eq!(tail[0].contents.join("\n"), "changed\r\n\r\nthird\nlast");
    review::record(&fixture.0, "demo.rule", &Fixture::report()).unwrap();
    fixture.write("helper.txt", "changed\r\n\r\nthird\nlast\n");
    assert!(!sage_meta::check(&fixture.0).is_valid());
}
}

See more source ↗

Review: Accepted · Codex /root/anchor_094.

Fresh final followup assessment of recorded_reads. Saved/read prior complete report and captures, started fresh, recaptured all five dependencies and compared every fragment. Claim, both implementation files, all eight tests and four dependencies are unchanged. The sole spec.rs dependency delta is an implementation_references association comment on the existing validator. No read or freshness behavior changed.

The full claim requires an active unfinished review, workspace-relative source and selector (default WholeFile), append-and-save before returning exact contents, ordered repeated reads, rejection of outside paths/invalid selections/inactive reviews, shared freshness and reviewer-declared dependency completeness. Both ordinary implementations remain sufficient: CLI parses selectors/default and prints capture_read's exact returned text without adding a newline. capture_read resolves workspace root, locks storage, validates unfinished summary/input with no completed output, selects text, appends path/selector/source lines without deduplication, writes input.json, then returns the same text. source_path rejects traversal/absolute/missing/escaping paths; select rejects invalid range or missing/ambiguous/wrong-source semantic identities. input_errors reselects appended dependencies just as initial inputs are reconstructed and compared. Prompt/checklist require reviewers to declare all additional dependencies; the system does not pretend to intercept arbitrary unrecorded reads. The new comment has no effect on these obligations.

All eight ordinary tests remain substantive. cli_read_defaults_to_whole_file_from_workspace_subdirectory asserts byte-exact mixed-ending stdout, one appended workspace-relative WholeFile, unchanged initial prefix and unfinished summary. whole_files_and_ranges_preserve_exact_line_endings_and_detect_selected_edits verifies exact ranges, invalid bounds, ordered retained repetitions, unselected-versus-selected changes and final-newline staleness. declared_claim_read_tracks_selected_text_without_capturing_the_document asserts returned/saved claim text and distinguishes outside edits from selected changes. another_anchors_test_read_tracks_body_and_identity isolates additional-read freshness for changed/renamed/ambiguous tests while initial inputs stay unchanged where applicable. invalid_ids_and_paths_are_rejected_without_destroying_existing_reports checks inactive reads, invalid paths and mismatched semantic selectors with unchanged input. recorded_reads_reject_symlink_escape_without_capturing_context covers canonical escape on Unix and preserved input. start_invalidates_previous_success_and_record_is_required proves reads do not finish an active review and postcompletion reads fail. test_selectors_disambiguate_identical_paths_by_cargo_target captures the same file's distinct target identities and rejects a wrong crate.

Captured Fixture/TEST helpers create actual Cargo/Design files and persisted reviews; source/check dependencies substantiate shared resolution/freshness. Assertions remain visible in test bodies. No TODO/N/A evidence or deferral exists; the Unix test condition is preserved and not claimed executed here. The actual one-comment dependency delta was checked against the complete prior assessment, with no other relied-on changes. No source edits, builds or test runs occurred; fresh start/read/record and source inspection 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