Skip to main content

Archive

yarp_cli::archive

Struct Archive 

Source 
pub struct Archive { /* private fields */ }

Implementations§

Source§

impl Archive

Source

pub fn open_read_only() -> Result<Self, String>

Open the configured archive without performing any writes.

§Errors

Returns an error when the archive is missing, unreadable, or uses another schema version.

Source

pub fn open_path(path: PathBuf) -> Result<Self, String>

Open an archive at an explicit path.

§Errors

Returns an error when the path, permissions, SQLite database, or schema is invalid.

Examples found in repository?
examples/indexed_output_benchmark.rs (line 33)
16fn main() -> Result<(), String> {
17    let executable = release_yarp()?;
18    let directory = TempDir::new().map_err(|error| error.to_string())?;
19    let database = directory.path().join("archive/tool-calls.sqlite3");
20    let config_home = directory.path().join("config");
21    fs::create_dir_all(config_home.join("yarp")).map_err(|error| error.to_string())?;
22    let database_text = serde_json::to_string(
23        database
24            .to_str()
25            .ok_or_else(|| "benchmark archive path is not UTF-8".to_owned())?,
26    )
27    .map_err(|error| error.to_string())?;
28    fs::write(
29        config_home.join("yarp/config.toml"),
30        format!("version = 1\n[archive]\npath = {database_text}\n"),
31    )
32    .map_err(|error| error.to_string())?;
33    let mut archive = Archive::open_path(database.clone())?;
34    let session = SessionIdentity {
35        agent: "benchmark".to_owned(),
36        account: "local".to_owned(),
37        source_session_id: "indexed-output".to_owned(),
38        started_at_ms: Some(1),
39    };
40    let call = CallIdentity {
41        source_call_id: "query".to_owned(),
42        tool_name: "exec_command".to_owned(),
43        provider: None,
44        model: None,
45        working_directory: None,
46        started_at_ms: 2,
47        requires_streams: false,
48    };
49    let archive_ref = archive.begin_call(&session, &call, &json!({}), &json!({}), 2)?;
50    let source = "path/to/file.rs:42: needle repeated output for bounded query\n".repeat(17_000);
51    archive.result_text(&session, "query", &source, SourceCompleteness::Complete, 3)?;
52    drop(archive);
53
54    let search = benchmark_command(
55        &executable,
56        &config_home,
57        &["search", &archive_ref, "needle", "--max-results", "20"],
58    )?;
59    let read = benchmark_command(
60        &executable,
61        &config_home,
62        &["read", &archive_ref, "result_text", "1:200"],
63    )?;
64    let result = benchmark_result_reducer(&executable, &config_home, &archive_ref)?;
65    let representative_source = "set -o pipefail && rg TODO . | sort | uniq | head -50";
66    let representative_parser = benchmark_parser(representative_source, WARMUP, SAMPLES)?;
67    let maximum_source = format!("rg {}", "x".repeat(256 * 1024 - 3));
68    let maximum_parser = benchmark_parser(&maximum_source, 2, 10)?;
69    print_stats("search_1m", &search);
70    print_stats("read_12k", &read);
71    print_stats("result_reducer_16k", &result);
72    print_stats("parser_representative", &representative_parser);
73    print_stats("parser_maximum_accepted", &maximum_parser);
74    println!(
75        "parser_representative_input_bytes: {}",
76        representative_source.len()
77    );
78    println!(
79        "parser_maximum_accepted_input_bytes: {}",
80        maximum_source.len()
81    );
82    for (name, samples) in [
83        ("search", &search),
84        ("read", &read),
85        ("result reducer", &result),
86    ] {
87        if percentile(samples, 95) > TARGET {
88            return Err(format!("{name} p95 exceeded {} ms", TARGET.as_millis()));
89        }
90    }
91    if percentile(&representative_parser, 95) > PARSER_TARGET {
92        return Err(format!(
93            "representative parser p95 exceeded {} ms",
94            PARSER_TARGET.as_millis()
95        ));
96    }
97    Ok(())
98}
Source

pub fn begin_call( &mut self, session: &SessionIdentity, call: &CallIdentity, input_before: &Value, input_after: &Value, captured_at_ms: i64, ) -> Result<String, String>

Store one call and its input snapshots before execution.

§Errors

Returns an error when JSON encoding or the SQLite transaction fails.

Examples found in repository?
examples/indexed_output_benchmark.rs (line 49)
16fn main() -> Result<(), String> {
17    let executable = release_yarp()?;
18    let directory = TempDir::new().map_err(|error| error.to_string())?;
19    let database = directory.path().join("archive/tool-calls.sqlite3");
20    let config_home = directory.path().join("config");
21    fs::create_dir_all(config_home.join("yarp")).map_err(|error| error.to_string())?;
22    let database_text = serde_json::to_string(
23        database
24            .to_str()
25            .ok_or_else(|| "benchmark archive path is not UTF-8".to_owned())?,
26    )
27    .map_err(|error| error.to_string())?;
28    fs::write(
29        config_home.join("yarp/config.toml"),
30        format!("version = 1\n[archive]\npath = {database_text}\n"),
31    )
32    .map_err(|error| error.to_string())?;
33    let mut archive = Archive::open_path(database.clone())?;
34    let session = SessionIdentity {
35        agent: "benchmark".to_owned(),
36        account: "local".to_owned(),
37        source_session_id: "indexed-output".to_owned(),
38        started_at_ms: Some(1),
39    };
40    let call = CallIdentity {
41        source_call_id: "query".to_owned(),
42        tool_name: "exec_command".to_owned(),
43        provider: None,
44        model: None,
45        working_directory: None,
46        started_at_ms: 2,
47        requires_streams: false,
48    };
49    let archive_ref = archive.begin_call(&session, &call, &json!({}), &json!({}), 2)?;
50    let source = "path/to/file.rs:42: needle repeated output for bounded query\n".repeat(17_000);
51    archive.result_text(&session, "query", &source, SourceCompleteness::Complete, 3)?;
52    drop(archive);
53
54    let search = benchmark_command(
55        &executable,
56        &config_home,
57        &["search", &archive_ref, "needle", "--max-results", "20"],
58    )?;
59    let read = benchmark_command(
60        &executable,
61        &config_home,
62        &["read", &archive_ref, "result_text", "1:200"],
63    )?;
64    let result = benchmark_result_reducer(&executable, &config_home, &archive_ref)?;
65    let representative_source = "set -o pipefail && rg TODO . | sort | uniq | head -50";
66    let representative_parser = benchmark_parser(representative_source, WARMUP, SAMPLES)?;
67    let maximum_source = format!("rg {}", "x".repeat(256 * 1024 - 3));
68    let maximum_parser = benchmark_parser(&maximum_source, 2, 10)?;
69    print_stats("search_1m", &search);
70    print_stats("read_12k", &read);
71    print_stats("result_reducer_16k", &result);
72    print_stats("parser_representative", &representative_parser);
73    print_stats("parser_maximum_accepted", &maximum_parser);
74    println!(
75        "parser_representative_input_bytes: {}",
76        representative_source.len()
77    );
78    println!(
79        "parser_maximum_accepted_input_bytes: {}",
80        maximum_source.len()
81    );
82    for (name, samples) in [
83        ("search", &search),
84        ("read", &read),
85        ("result reducer", &result),
86    ] {
87        if percentile(samples, 95) > TARGET {
88            return Err(format!("{name} p95 exceeded {} ms", TARGET.as_millis()));
89        }
90    }
91    if percentile(&representative_parser, 95) > PARSER_TARGET {
92        return Err(format!(
93            "representative parser p95 exceeded {} ms",
94            PARSER_TARGET.as_millis()
95        ));
96    }
97    Ok(())
98}
Source

pub fn result_before( &mut self, session: &SessionIdentity, source_call_id: &str, result: &Value, full_output_path: Option<&Path>, captured_at_ms: i64, ) -> Result<(), String>

Store the result exposed before YARP result processing.

§Errors

Returns an error when the call is missing or the payload cannot be committed.

Source

pub fn result_text( &mut self, session: &SessionIdentity, source_call_id: &str, text: &str, completeness: SourceCompleteness, captured_at_ms: i64, ) -> Result<String, String>

Store the exact host-exposed result text selected for post-result reduction.

§Errors

Returns an error when the call is missing, completeness is invalid, or the snapshot cannot be committed.

Examples found in repository?
examples/indexed_output_benchmark.rs (line 51)
16fn main() -> Result<(), String> {
17    let executable = release_yarp()?;
18    let directory = TempDir::new().map_err(|error| error.to_string())?;
19    let database = directory.path().join("archive/tool-calls.sqlite3");
20    let config_home = directory.path().join("config");
21    fs::create_dir_all(config_home.join("yarp")).map_err(|error| error.to_string())?;
22    let database_text = serde_json::to_string(
23        database
24            .to_str()
25            .ok_or_else(|| "benchmark archive path is not UTF-8".to_owned())?,
26    )
27    .map_err(|error| error.to_string())?;
28    fs::write(
29        config_home.join("yarp/config.toml"),
30        format!("version = 1\n[archive]\npath = {database_text}\n"),
31    )
32    .map_err(|error| error.to_string())?;
33    let mut archive = Archive::open_path(database.clone())?;
34    let session = SessionIdentity {
35        agent: "benchmark".to_owned(),
36        account: "local".to_owned(),
37        source_session_id: "indexed-output".to_owned(),
38        started_at_ms: Some(1),
39    };
40    let call = CallIdentity {
41        source_call_id: "query".to_owned(),
42        tool_name: "exec_command".to_owned(),
43        provider: None,
44        model: None,
45        working_directory: None,
46        started_at_ms: 2,
47        requires_streams: false,
48    };
49    let archive_ref = archive.begin_call(&session, &call, &json!({}), &json!({}), 2)?;
50    let source = "path/to/file.rs:42: needle repeated output for bounded query\n".repeat(17_000);
51    archive.result_text(&session, "query", &source, SourceCompleteness::Complete, 3)?;
52    drop(archive);
53
54    let search = benchmark_command(
55        &executable,
56        &config_home,
57        &["search", &archive_ref, "needle", "--max-results", "20"],
58    )?;
59    let read = benchmark_command(
60        &executable,
61        &config_home,
62        &["read", &archive_ref, "result_text", "1:200"],
63    )?;
64    let result = benchmark_result_reducer(&executable, &config_home, &archive_ref)?;
65    let representative_source = "set -o pipefail && rg TODO . | sort | uniq | head -50";
66    let representative_parser = benchmark_parser(representative_source, WARMUP, SAMPLES)?;
67    let maximum_source = format!("rg {}", "x".repeat(256 * 1024 - 3));
68    let maximum_parser = benchmark_parser(&maximum_source, 2, 10)?;
69    print_stats("search_1m", &search);
70    print_stats("read_12k", &read);
71    print_stats("result_reducer_16k", &result);
72    print_stats("parser_representative", &representative_parser);
73    print_stats("parser_maximum_accepted", &maximum_parser);
74    println!(
75        "parser_representative_input_bytes: {}",
76        representative_source.len()
77    );
78    println!(
79        "parser_maximum_accepted_input_bytes: {}",
80        maximum_source.len()
81    );
82    for (name, samples) in [
83        ("search", &search),
84        ("read", &read),
85        ("result reducer", &result),
86    ] {
87        if percentile(samples, 95) > TARGET {
88            return Err(format!("{name} p95 exceeded {} ms", TARGET.as_millis()));
89        }
90    }
91    if percentile(&representative_parser, 95) > PARSER_TARGET {
92        return Err(format!(
93            "representative parser p95 exceeded {} ms",
94            PARSER_TARGET.as_millis()
95        ));
96    }
97    Ok(())
98}
Source

pub fn archive_ref(&self, key: &ArchiveKey) -> Result<String, String>

Resolve the stable reference for one internally identified call.

§Errors

Returns an error when the call or reference is missing.

Source

pub fn searchable_sources( &self, archive_ref: &str, ) -> Result<Vec<VerifiedSource>, String>

Resolve and verify the canonical recovery sources for one call reference.

§Errors

Returns an error when the reference is malformed, missing, or any selected payload fails integrity verification.

Source

pub fn stage_result( &mut self, session: &SessionIdentity, source_call_id: &str, result: &Value, is_error: bool, captured_at_ms: i64, ) -> Result<(), String>

Store the provisional post-YARP result while leaving the call incomplete.

§Errors

Returns an error when the call is missing, required snapshots are missing, or the payload cannot be committed.

Source

pub fn finish_call( &mut self, session: &SessionIdentity, source_call_id: &str, result: &Value, is_error: bool, require_pre_result: bool, finished_at_ms: i64, ) -> Result<(), String>

Store the finalized result and mark the call finished.

§Errors

Returns an error when the call is missing or the payload cannot be committed.

Source

pub fn update_final_result( &mut self, session: &SessionIdentity, source_call_id: &str, result: &Value, is_error: bool, finished_at_ms: i64, ) -> Result<(), String>

Finalize a staged call with the result after every Pi result hook has run.

§Errors

Returns an error when the call is not staged or the final result cannot be committed.

Source

pub fn capture_streams( &mut self, key: &ArchiveKey, captured_at_ms: i64, stdout_before: &mut (impl Read + Seek), stderr_before: &mut (impl Read + Seek), stdout_after: &[u8], stderr_after: &[u8], ) -> Result<(), String>

Store exact shell streams before and after pruning.

§Errors

Returns an error when a stream cannot be read or the transaction cannot commit.

Source

pub fn capture_passthrough_streams( &mut self, key: &ArchiveKey, captured_at_ms: i64, stdout: &mut (impl Read + Seek), stderr: &mut (impl Read + Seek), ) -> Result<(), String>

Store exact shell streams when a wrapper deliberately passed output through unchanged.

§Errors

Returns an error when a stream cannot be read or the transaction cannot commit.

Source

pub fn restore_streams( &self, key: &ArchiveKey, stdout: impl Write, stderr: impl Write, ) -> Result<(), String>

Restore the exact pre-pruning shell streams for one call.

§Errors

Returns an error when the call, snapshots, or payload bodies cannot be read.

Source

pub fn stats(&self) -> Result<ArchiveStats, String>

Read aggregate archive statistics without reading payload content.

§Errors

Returns an error when SQLite queries or filesystem metadata reads fail.

Source

pub fn verify(&self) -> Result<VerifyReport, String>

Verify SQLite integrity, relationships, snapshots, payloads, and permissions.

§Errors

Returns an error when verification itself cannot read the archive.

Source

pub fn prune_before(&mut self, timestamp_ms: i64) -> Result<i64, String>

Delete finished calls older than the given Unix millisecond timestamp.

§Errors

Returns an error when deletion, payload cleanup, or vacuuming fails.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.