refactor: wire up dead fields, derive Default, clarify package-mgr stubs (refs #22) (#26)

Six dead-code warnings, two genuinely load-bearing fixes and four
intent-signaling cleanups. PR4 of 4 from #22.

Substantive wire-ups (the "dead" fields were forgotten implementations):

* my-ai AICache::timestamp -- the cache stored a timestamp on every set
  but `get` never consulted it, so it was an unbounded-growth cache
  pretending to be a TTL cache. Added a `ttl: Duration` field with a
  five-minute default, made `get` honour the TTL, and made `set` sweep
  expired entries before inserting. New helpers `with_ttl(Duration)`
  for custom TTLs. Three new tokio tests pin the round-trip, expiry,
  and on-set eviction behaviours.

* my-mir Frame::function -- captured at every `call` and never read.
  The InterpreterError::StackOverflow variant grew `function`, `depth`,
  and `call_chain` fields, populated from the live frame stack. A
  stack overflow now reports both the call we tried to make and the
  chain that led there; the previously-dead field carries that chain.

Intent-signaling cleanups (these are real stubs awaiting feature work):

* my-pkg Resolver::registry -- the field is allocated and held but the
  current resolver picks placeholder versions (`// TODO: Query
  registry`), so the field is genuinely unused today. Kept (rather than
  dropped, to preserve the `Resolver::new(Registry)` constructor for
  when the real resolver lands) with `#[allow(dead_code)]` + comment.

* my-pkg resolve / resolve_dependency / store -- three parameters
  (`root_version`, `graph`, `data`) renamed to `_root_version`,
  `_graph`, `_data` so the placeholder implementations stop tripping
  `unused_variables` without changing call signatures. Each gets a
  comment naming the `TODO` that will revive it.

Mechanical:

* my-lang Environment -- replaced the manual `Default` impl with
  `#[derive(Default)]` on the struct (the impl was a verbose
  reimplementation of what derive produces; both call sites of
  `Environment::default()` are unchanged).

Out of scope (kept clean):

* parser.rs `parse_comptime_decl` (never used) -- overlaps with the
  depth-guard PR #21 still in review; will land cleanly once #21 merges.

Tests:

* `cargo test -p my-ai --lib` -- 5/5 pass (2 pre-existing + 3 new TTL
  tests).
* `cargo test -p my-mir --lib` -- 1/1 pass.
* `cargo test -p my-pkg --lib` -- 1/1 pass.
* `cargo test -p my-lang --lib interpreter::` -- 13/13 pass.
* `cargo test -p my-lang --lib library::common::` -- 39/39 pass.

Author: hyperpolymath

crates/my-ai/src/lib.rs

@@ -417,6 +417,7 @@ impl AIProvider for OllamaProvider {
 /// TODO: Replace with rocketcache integration
 pub struct AICache {
     cache: Arc<RwLock<HashMap<String, CachedResponse>>>,
+    ttl: std::time::Duration,
 }
 
 #[derive(Debug, Clone)]
@@ -425,20 +426,53 @@ struct CachedResponse {
     timestamp: std::time::Instant,
 }
 
+/// Default time-to-live for cached AI responses. Picked as five minutes
+/// because: (a) AI responses are model-call expensive enough that short
+/// repeats deserve to hit the cache, (b) five minutes is short enough
+/// that long-lived processes don't serve stale answers indefinitely or
+/// retain memory for keys nobody asks about anymore.
+const DEFAULT_TTL: std::time::Duration = std::time::Duration::from_secs(300);
+
 impl AICache {
+    /// Build a cache with the [`DEFAULT_TTL`] (five minutes).
     pub fn new() -> Self {
+        Self::with_ttl(DEFAULT_TTL)
+    }
+
+    /// Build a cache with a custom time-to-live.
+    ///
+    /// Entries older than `ttl` are treated as absent by [`Self::get`]
+    /// and are opportunistically evicted on the next [`Self::set`].
+    pub fn with_ttl(ttl: std::time::Duration) -> Self {
         AICache {
             cache: Arc::new(RwLock::new(HashMap::new())),
+            ttl,
         }
     }
 
+    /// Look up `key`. Returns `None` if the entry is absent or its
+    /// timestamp has exceeded `ttl` -- an expired entry is reported as
+    /// absent but not removed under the read lock; eviction happens on
+    /// the next write so we don't pay for an upgrade here.
     pub async fn get(&self, key: &str) -> Option<CompletionResponse> {
         let cache = self.cache.read().await;
-        cache.get(key).map(|c| c.response.clone())
+        cache.get(key).and_then(|c| {
+            if c.timestamp.elapsed() <= self.ttl {
+                Some(c.response.clone())
+            } else {
+                None
+            }
+        })
     }
 
+    /// Insert `response` for `key`. As a side effect, every entry whose
+    /// timestamp has exceeded `ttl` is dropped -- we already hold the
+    /// write lock, so this lazy sweep keeps memory bounded without a
+    /// background task.
     pub async fn set(&self, key: String, response: CompletionResponse) {
         let mut cache = self.cache.write().await;
+        let ttl = self.ttl;
+        cache.retain(|_, entry| entry.timestamp.elapsed() <= ttl);
         cache.insert(
             key,
             CachedResponse {
@@ -694,4 +728,51 @@ mod tests {
         let key = AICache::cache_key(&request);
         assert!(!key.is_empty());
     }
+
+    fn dummy_response(content: &str) -> CompletionResponse {
+        CompletionResponse {
+            content: content.to_string(),
+            model: "test".to_string(),
+            usage: Usage { input_tokens: 0, output_tokens: 0 },
+            tool_calls: Vec::new(),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_cache_round_trip() {
+        let cache = AICache::new();
+        assert!(cache.get("k").await.is_none());
+        cache.set("k".to_string(), dummy_response("hello")).await;
+        assert_eq!(cache.get("k").await.map(|r| r.content), Some("hello".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_cache_ttl_expires_entries() {
+        // 50 ms TTL: insert, sleep past it, expect the entry to be reported
+        // as absent. Regression for the field that used to be captured at
+        // `set` time and never consulted on `get`.
+        let cache = AICache::with_ttl(std::time::Duration::from_millis(50));
+        cache.set("k".to_string(), dummy_response("hello")).await;
+        assert!(cache.get("k").await.is_some(), "entry should be fresh");
+        tokio::time::sleep(std::time::Duration::from_millis(80)).await;
+        assert!(
+            cache.get("k").await.is_none(),
+            "entry should be reported absent once past TTL"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_cache_set_evicts_expired_entries() {
+        // After TTL elapses, a subsequent `set` should sweep stale entries
+        // out so the cache cannot grow unboundedly even if old keys are
+        // never read again.
+        let cache = AICache::with_ttl(std::time::Duration::from_millis(50));
+        cache.set("old1".to_string(), dummy_response("a")).await;
+        cache.set("old2".to_string(), dummy_response("b")).await;
+        tokio::time::sleep(std::time::Duration::from_millis(80)).await;
+        cache.set("fresh".to_string(), dummy_response("c")).await;
+        let inner = cache.cache.read().await;
+        assert_eq!(inner.len(), 1, "expired entries should be swept on set");
+        assert!(inner.contains_key("fresh"));
+    }
 }

crates/my-lang/src/interpreter.rs

@@ -129,6 +129,7 @@ pub struct AiResultValue {
 
 /// Environment for variable bindings
 #[derive(Debug, Clone)]
+#[derive(Default)]
 pub struct Environment {
     values: HashMap<String, Value>,
     parent: Option<Env>,
@@ -177,15 +178,6 @@ impl Environment {
     }
 }
 
-impl Default for Environment {
-    fn default() -> Self {
-        Environment {
-            values: HashMap::new(),
-            parent: None,
-        }
-    }
-}
-
 // ============================================================================
 // RUNTIME ERRORS
 // ============================================================================

crates/my-mir/src/lib.rs

@@ -1001,8 +1001,12 @@ pub mod interpreter {
         #[error("type error: {0}")]
         TypeError(String),
 
-        #[error("stack overflow")]
-        StackOverflow,
+        #[error("stack overflow at depth {depth} while calling `{function}` (call chain: {call_chain})")]
+        StackOverflow {
+            function: String,
+            depth: usize,
+            call_chain: String,
+        },
 
         #[error("division by zero")]
         DivisionByZero,
@@ -1089,7 +1093,21 @@ pub mod interpreter {
         /// Call a function with arguments
         pub fn call(&mut self, name: &str, args: Vec<Value>) -> Result<Value, InterpreterError> {
             if self.stack.len() >= self.max_stack {
-                return Err(InterpreterError::StackOverflow);
+                // The previous variant dropped the caller chain, which is
+                // why `Frame::function` was captured at every `call` and
+                // never read. Building the chain here makes the field
+                // load-bearing for debugging real overflows.
+                let call_chain = self
+                    .stack
+                    .iter()
+                    .map(|f| f.function.as_str())
+                    .collect::<Vec<_>>()
+                    .join(" -> ");
+                return Err(InterpreterError::StackOverflow {
+                    function: name.to_string(),
+                    depth: self.stack.len(),
+                    call_chain,
+                });
             }
 
             let func = self.program.functions.get(name).cloned()

crates/my-pkg/src/lib.rs

@@ -131,6 +131,12 @@ pub struct LockedPackage {
 
 /// Dependency resolver
 pub struct Resolver {
+    // Not yet consulted during resolution -- the resolver currently uses
+    // a placeholder version pick (see the `TODO: Query registry` in
+    // `resolve_dependency`). The field is kept (rather than dropped) so
+    // the constructor signature stays put for when the real resolver
+    // lands; allow the lint until then.
+    #[allow(dead_code)]
     registry: Registry,
 }
 
@@ -144,8 +150,9 @@ impl Resolver {
         let mut graph: DiGraph<(String, Version), ()> = DiGraph::new();
         let mut resolved = HashMap::new();
 
-        // Add root package
-        let root_version = Version::parse(&manifest.package.version)
+        // Add root package. Parsed for validation -- when the real
+        // resolver lands it will seed the graph with this version.
+        let _root_version = Version::parse(&manifest.package.version)
             .map_err(|e| PkgError::InvalidManifest(e.to_string()))?;
 
         // Resolve each dependency
@@ -173,7 +180,10 @@ impl Resolver {
         &self,
         name: &str,
         dep: &Dependency,
-        graph: &mut DiGraph<(String, Version), ()>,
+        // Threaded through for the real resolver (see the `TODO: Query
+        // registry` below) -- the placeholder version-pick implementation
+        // doesn't touch the graph yet.
+        _graph: &mut DiGraph<(String, Version), ()>,
         resolved: &mut HashMap<String, Version>,
     ) -> Result<(), PkgError> {
         let version_req = match dep {
@@ -306,12 +316,17 @@ impl PackageCache {
         }
     }
 
-    /// Store package in cache
+    /// Store package in cache.
+    ///
+    /// `data` is the raw tarball bytes; currently ignored because tarball
+    /// extraction (`TODO` below) is not yet implemented. The parameter
+    /// stays in the public signature so adding the body doesn't require
+    /// a breaking API change.
     pub async fn store(
         &self,
         name: &str,
         version: &Version,
-        data: &[u8],
+        _data: &[u8],
     ) -> Result<PathBuf, PkgError> {
         let path = self
             .cache_dir