Integration tests + cached/speculative branch eval + conversation log

Integration tests (integration_tests.rs, 15 tests):
- e2e parse→typecheck→evaluate pipeline for data bindings, functions,
  branches, type declarations, send-to syntax, @ref, agent API
- Negative tests: linear handle leak, budget exceeded (both caught)
- Regression guard: parse all 9 example files
- Agent registration, record evaluation, variable chaining

Cached branch evaluation:
- branch_cache HashMap on Evaluator keyed by label:context
- eval_branch_cached(): cache hit returns stored result, miss evaluates
- eval_branch_speculative(): evaluates ALL arms, records all traces,
  strategy picks best
- 3 new eval tests: cache hit, cache miss (different context), speculative

Conversation log updated with Austin, Schlegel, security, Bruner sections.

194 tests. Zero clippy warnings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

crates/oo7-core/src/eval.rs

@@ -260,6 +260,15 @@ pub struct Evaluator {
 
     /// The ID of the agent currently executing, if any.
     pub current_agent_id: Option<String>,
+
+    // -- Branch Cache (Section 18.2: Cached Branches) --
+    // Key: "label:serialized_given_context"
+    // Value: (chosen_arm_label, result_value)
+
+    /// Cache for `branch cached` — memoises decisions by branch
+    /// label + given context. On cache hit, the strategy is NOT
+    /// consulted and the arm body is NOT re-executed.
+    pub branch_cache: HashMap<String, (String, RtValue)>,
 }
 
 impl Evaluator {
@@ -278,6 +287,7 @@ impl Evaluator {
             return_signal: false,
             return_value: None,
             current_agent_id: None,
+            branch_cache: HashMap::new(),
         }
     }
 
@@ -296,6 +306,7 @@ impl Evaluator {
             return_signal: false,
             return_value: None,
             current_agent_id: None,
+            branch_cache: HashMap::new(),
         }
     }
 
@@ -692,6 +703,197 @@ impl Evaluator {
         self.eval_stmts(&chosen_arm.body, env)
     }
 
+    // ========================================================
+    // Branch Modifier Dispatch (Section 18.2)
+    // ========================================================
+
+    /// Dispatch branch evaluation based on modifier.
+    ///
+    /// - `None` → standard `eval_branch` (strategy chooses one arm)
+    /// - `Cached` → memoised branch: cache key is label + serialized given context.
+    ///   On cache hit, returns cached (chosen_arm, result) WITHOUT running
+    ///   strategy or arm body. On miss, evaluates normally and stores result.
+    /// - `Speculative` → evaluates ALL arms, uses strategy to pick best,
+    ///   records traces for ALL arms (not just chosen).
+    pub fn eval_branch_with_modifier(
+        &mut self,
+        modifier: &Option<BranchModifier>,
+        traced: &Option<String>,
+        arms: &[BranchArm],
+        env: &mut Env,
+    ) -> RtValue {
+        match modifier {
+            None => self.eval_branch(traced, arms, env),
+            Some(BranchModifier::Cached) => self.eval_branch_cached(traced, arms, env),
+            Some(BranchModifier::Speculative) => self.eval_branch_speculative(traced, arms, env),
+        }
+    }
+
+    /// Evaluate a cached branch (Section 18.2).
+    ///
+    /// Cache key = "label:serialized_given_context".
+    /// On cache hit: return cached result, emit a trace record noting
+    /// "cache_hit" in the reason field.
+    /// On cache miss: evaluate normally via `eval_branch`, store result.
+    fn eval_branch_cached(
+        &mut self,
+        traced: &Option<String>,
+        arms: &[BranchArm],
+        env: &mut Env,
+    ) -> RtValue {
+        let label = traced.as_deref().unwrap_or("__unlabelled__");
+
+        // Serialize given contexts to form the cache key.
+        let mut given_key_parts: Vec<String> = Vec::new();
+        for arm in arms {
+            if let Some(given) = &arm.given {
+                let (named, _preds) = self.eval_given(given, env);
+                let json_vals: Vec<String> = named
+                    .iter()
+                    .map(|(k, v)| format!("{}={}", k, v.to_json()))
+                    .collect();
+                given_key_parts.push(format!("{}:{}", arm.label, json_vals.join(",")));
+            }
+        }
+        let cache_key = format!("{}:{}", label, given_key_parts.join("|"));
+
+        // Check cache.
+        if let Some((cached_chosen, cached_result)) = self.branch_cache.get(&cache_key) {
+            // Cache hit — emit trace record noting the hit.
+            if let Some(trace_label) = traced {
+                let record = TraceRecord {
+                    branch_id: trace_label.clone(),
+                    branch_options: arms.iter().map(|a| a.label.clone()).collect(),
+                    given_contexts: JsonValue::Null,
+                    chosen: cached_chosen.clone(),
+                    reason: format!("cache_hit(key={})", cache_key),
+                    trace_report: JsonValue::Null,
+                    timestamp: Utc::now().to_rfc3339(),
+                    agent_id: "evaluator".to_string(),
+                    hermeneutic_context: env.snapshot(),
+                };
+                self.trace.append(record);
+            }
+            return cached_result.clone();
+        }
+
+        // Cache miss — evaluate normally.
+        let result = self.eval_branch(traced, arms, env);
+
+        // Store in cache: look up chosen arm from the last trace record.
+        let chosen_label = self
+            .trace
+            .records
+            .last()
+            .map(|r| r.chosen.clone())
+            .unwrap_or_else(|| arms.first().map(|a| a.label.clone()).unwrap_or_default());
+        self.branch_cache
+            .insert(cache_key, (chosen_label, result.clone()));
+
+        result
+    }
+
+    /// Evaluate a speculative branch (Section 18.2).
+    ///
+    /// Evaluates ALL arms (not just the strategy-selected one).
+    /// Uses the strategy to pick the best result.
+    /// Records traces for ALL arms, marking the chosen one.
+    fn eval_branch_speculative(
+        &mut self,
+        traced: &Option<String>,
+        arms: &[BranchArm],
+        env: &mut Env,
+    ) -> RtValue {
+        let label = traced.as_deref().unwrap_or("__unlabelled__");
+
+        // Step 1: Evaluate given clauses for strategy selection.
+        let mut evaluated_arms: Vec<EvaluatedArm> = Vec::new();
+        let mut given_contexts_json: HashMap<String, JsonValue> = HashMap::new();
+
+        for arm in arms {
+            let (named, preds) = if let Some(given) = &arm.given {
+                let (n, p) = self.eval_given(given, env);
+                given_contexts_json.insert(
+                    arm.label.clone(),
+                    JsonValue::Object(n.iter().map(|(k, v)| (k.clone(), v.to_json())).collect()),
+                );
+                (Some(n), Some(p))
+            } else {
+                (None, None)
+            };
+            evaluated_arms.push((arm.label.clone(), named, preds));
+        }
+
+        // Step 2: Evaluate ALL arms and collect results.
+        let mut arm_results: Vec<(String, RtValue)> = Vec::new();
+        for arm in arms {
+            let mut arm_env = env.clone();
+            arm_env.push_scope();
+            let result = self.eval_stmts(&arm.body, &mut arm_env);
+            arm_results.push((arm.label.clone(), result));
+
+            // Record a trace for each arm.
+            if let Some(trace_label) = traced {
+                let trace_report = if let Some(tc) = &arm.trace {
+                    let fields: HashMap<String, JsonValue> = tc
+                        .fields
+                        .iter()
+                        .map(|(k, v)| (k.clone(), self.eval_data(v, env).to_json()))
+                        .collect();
+                    JsonValue::Object(fields.into_iter().collect())
+                } else {
+                    JsonValue::Null
+                };
+
+                let record = TraceRecord {
+                    branch_id: format!("{}/speculative/{}", trace_label, arm.label),
+                    branch_options: arms.iter().map(|a| a.label.clone()).collect(),
+                    given_contexts: JsonValue::Object(
+                        given_contexts_json.clone().into_iter().collect(),
+                    ),
+                    chosen: arm.label.clone(),
+                    reason: "speculative: evaluating all arms".to_string(),
+                    trace_report,
+                    timestamp: Utc::now().to_rfc3339(),
+                    agent_id: "evaluator".to_string(),
+                    hermeneutic_context: env.snapshot(),
+                };
+                self.trace.append(record);
+            }
+        }
+
+        // Step 3: Use strategy to pick the best arm.
+        let (chosen_idx, reason) = self.strategy.choose(&evaluated_arms, env);
+        let chosen_idx = chosen_idx.min(arms.len() - 1);
+        let chosen_arm = &arms[chosen_idx];
+
+        // Step 4: Record the final selection trace.
+        if traced.is_some() {
+            let record = TraceRecord {
+                branch_id: label.to_string(),
+                branch_options: arms.iter().map(|a| a.label.clone()).collect(),
+                given_contexts: JsonValue::Object(given_contexts_json.into_iter().collect()),
+                chosen: chosen_arm.label.clone(),
+                reason: format!(
+                    "speculative_selected: {}",
+                    reason.unwrap_or_else(|| "default".to_string())
+                ),
+                trace_report: JsonValue::Null,
+                timestamp: Utc::now().to_rfc3339(),
+                agent_id: "evaluator".to_string(),
+                hermeneutic_context: env.snapshot(),
+            };
+            self.trace.append(record);
+        }
+
+        // Return the result of the chosen arm.
+        arm_results
+            .into_iter()
+            .nth(chosen_idx)
+            .map(|(_, v)| v)
+            .unwrap_or(RtValue::Unit)
+    }
+
     // ========================================================
     // Control Statement Evaluation
     // ========================================================
@@ -749,17 +951,18 @@ impl Evaluator {
             }
 
             ControlStmt::Branch {
-                modifier: _modifier,
+                modifier,
                 traced,
                 arms,
             } => {
-                // Section 18.2: modifier (speculative/cached) is ignored in
-                // the reference evaluator — it affects scheduling strategy,
-                // not observable semantics. A production runtime would fork
-                // evaluation streams for speculative and check trace cache
-                // for cached.
+                // Section 18.2: Branch modifiers affect evaluation strategy.
+                // - Cached: memoises decisions by label + given context.
+                //   On cache hit, the strategy is NOT consulted and the
+                //   arm body is NOT re-executed.
+                // - Speculative: evaluates ALL arms, picks best result,
+                //   records traces for ALL arms (not just chosen).
                 env.push_scope();
-                let r = self.eval_branch(traced, arms, env);
+                let r = self.eval_branch_with_modifier(modifier, traced, arms, env);
                 env.pop_scope();
                 r
             }