Initial commit: aether-tools-rs workspace

examples/library_usage/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "library_usage"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+aether-atom = { path = "/home/cosmos/aether-atom" }

examples/library_usage/src/main.rs

@@ -0,0 +1,87 @@
+//! Library usage — third-party code consuming aether-atom.
+//!
+//! This is what every binary in `crates/` does, distilled to ~50 LOC.
+//! Use the atom directly (via `Lattice`); there is no helper layer to
+//! hide behind — the primitives *are* the API.
+//!
+//! Runs in an ephemeral temp directory by default so this example
+//! cannot pollute `$HOME/.aether-recall` unless `AETHER_RECALL_DIR`
+//! is set explicitly.
+
+use aether_atom::{fingerprint, rust_canonicalize, Lattice};
+
+fn open_lattice() -> Result<Lattice, std::io::Error> {
+    // Use the standard path; override via env if desired.
+    Lattice::open(&aether_atom::data_dir("AETHER_RECALL_DIR"))
+}
+
+fn main() {
+    // The example is read-only against the user's real ledger, but to
+    // demonstrate without state there, point it at a clean tmp dir.
+    let dir = match std::env::var("AETHER_RECALL_DIR") {
+        Ok(d) => std::path::PathBuf::from(d),
+        Err(_) => {
+            let stamp = std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos();
+            let p = std::env::temp_dir().join(format!("library-usage-demo-{stamp}"));
+            std::fs::create_dir_all(&p).unwrap();
+            p
+        }
+    };
+    let mut lat = Lattice::open(&dir).expect("open atom");
+    println!("memory: dir={:?}", dir);
+
+    let question = "error[E0308]: expected i32, found &str";
+    let sig = fingerprint(&rust_canonicalize(question));
+
+    match lat.lookup(&sig, "global") {
+        Some(hit) => println!("hit: {}", String::from_utf8_lossy(hit.value.as_ref())),
+        None => {
+            println!("miss — recording placeholder answer");
+            lat.record(sig, "global", b"use .to_string()", Some(true));
+        }
+    }
+
+    // Path-equivalent lookup: the rust_canonicalize step collapses
+    // `path:line:col` back to identical bytes, so this hits too.
+    let equiv_sig = fingerprint(&rust_canonicalize(
+        "error[E0308]: expected i32, found &str\n --> src/foo.rs:42:5",
+    ));
+    assert_eq!(equiv_sig, sig, "path-line-col must not change the canonical form");
+
+    let stats = lat;
+    println!("stats: records={} lookups={} hits={} misses={} hit_rate={:.2}",
+        stats.record_count(),
+        stats.lookups,
+        stats.hits,
+        stats.misses,
+        stats.hit_rate()
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn tmp_dir() -> std::path::PathBuf {
+        let stamp = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos();
+        let p = std::env::temp_dir().join(format!("library-usage-test-{stamp}"));
+        std::fs::create_dir_all(&p).unwrap();
+        p
+    }
+
+    #[test]
+    fn open_lattice_creates_dir_if_missing() {
+        let dir = tmp_dir();
+        let mut lat = Lattice::open(&dir).unwrap();
+        lat.record(
+            fingerprint(b"hello"),
+            "global",
+            b"world",
+            Some(true),
+        );
+        let hit = lat.lookup(&fingerprint(b"hello"), "global");
+        assert_eq!(hit.unwrap().value.as_ref(), b"world");
+    }
+}