checkpoint: matrix-agent-validated (2026-04-25)

Architectural snapshot of the lakehouse codebase at the point where the
full matrix-driven agent loop with Mem0 versioning + deletion was
validated end-to-end.

WHAT THIS REPO IS
A clean single-commit snapshot of the lakehouse code. Heavy test data
(.parquet datasets, vector indexes) excluded — see REPLICATION.md for
regen path. Full lakehouse history at git.agentview.dev/profit/lakehouse.

WHAT WAS PROVEN
- Vector retrieval across multi-corpora matrix (chicago_permits + entity
  briefs + sec_tickers + distilled procedural + llm_team runs)
- Observer hand-review (cloud + heuristic fallback) gating each candidate
- Local-model agent loop (qwen3.5:latest) with tool use + scratchpad
- Playbook seal on success → next-iter retrieval surfaces it as preamble
- Mem0 versioning + deletion in pathway_memory:
    * UPSERT: ADD on new workflow, UPDATE bumps replay_count on identical
    * REVISE: chains versions, parent.superseded_at + superseded_by stamped
    * RETIRE: marks specific trace retired with reason, excluded from retrieval
    * HISTORY: walks chain root→tip, cycle-safe

KEY DIRECTORIES
- crates/vectord/src/pathway_memory.rs — Mem0 ops live here
- crates/vectord/src/playbook_memory.rs — original Mem0 reference
- tests/agent_test/ — local-model agent harness + PRD + session archives
- scripts/dump_raw_corpus.sh — MinIO bucket dump (raw test corpus)
- scripts/vectorize_raw_corpus.ts — corpus → vector indexes
- scripts/analyze_chicago_contracts.ts — real inference pipeline
- scripts/seal_agent_playbook.ts — Mem0 upsert from agent traces

Replication: see REPLICATION.md for Debian 13 clean install + cloud-only
adaptation (no local Ollama).

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

crates/aibridge/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "aibridge"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+shared = { path = "../shared" }
+tokio = { workspace = true }
+axum = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+tracing = { workspace = true }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+async-trait = "0.1"

crates/aibridge/src/client.rs

@@ -0,0 +1,188 @@
+use reqwest::Client;
+use serde::{Deserialize, Serialize};
+use std::time::Duration;
+
+/// HTTP client for the Python AI sidecar.
+#[derive(Clone)]
+pub struct AiClient {
+    client: Client,
+    base_url: String,
+}
+
+// -- Request/Response types --
+
+#[derive(Serialize, Deserialize)]
+pub struct EmbedRequest {
+    pub texts: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+}
+
+#[derive(Deserialize, Serialize, Clone)]
+pub struct EmbedResponse {
+    pub embeddings: Vec<Vec<f64>>,
+    pub model: String,
+    pub dimensions: usize,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct GenerateRequest {
+    pub prompt: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub system: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_tokens: Option<u32>,
+    /// Phase 21 — per-call opt-out of hidden reasoning. Thinking models
+    /// (qwen3.5, gpt-oss, etc) burn tokens on reasoning before the
+    /// visible response starts; setting this to `false` on hot-path
+    /// JSON emitters avoids empty returns when the budget is tight.
+    /// Sidecar forwards this to Ollama's `think` parameter; if the
+    /// sidecar drops an unknown field the request still succeeds.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub think: Option<bool>,
+}
+
+#[derive(Deserialize, Serialize, Clone)]
+pub struct GenerateResponse {
+    pub text: String,
+    pub model: String,
+    pub tokens_evaluated: Option<u64>,
+    pub tokens_generated: Option<u64>,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct RerankRequest {
+    pub query: String,
+    pub documents: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub top_k: Option<usize>,
+}
+
+#[derive(Deserialize, Serialize, Clone)]
+pub struct ScoredDocument {
+    pub index: usize,
+    pub text: String,
+    pub score: f64,
+}
+
+#[derive(Deserialize, Serialize, Clone)]
+pub struct RerankResponse {
+    pub results: Vec<ScoredDocument>,
+    pub model: String,
+}
+
+impl AiClient {
+    pub fn new(base_url: &str) -> Self {
+        let client = Client::builder()
+            .timeout(Duration::from_secs(120))
+            .build()
+            .expect("failed to build HTTP client");
+        Self {
+            client,
+            base_url: base_url.trim_end_matches('/').to_string(),
+        }
+    }
+
+    pub async fn health(&self) -> Result<serde_json::Value, String> {
+        let resp = self.client
+            .get(format!("{}/health", self.base_url))
+            .send()
+            .await
+            .map_err(|e| format!("sidecar unreachable: {e}"))?;
+        resp.json().await.map_err(|e| format!("invalid response: {e}"))
+    }
+
+    pub async fn embed(&self, req: EmbedRequest) -> Result<EmbedResponse, String> {
+        let resp = self.client
+            .post(format!("{}/embed", self.base_url))
+            .json(&req)
+            .send()
+            .await
+            .map_err(|e| format!("embed request failed: {e}"))?;
+
+        if !resp.status().is_success() {
+            let text = resp.text().await.unwrap_or_default();
+            return Err(format!("embed error ({}): {text}", text.len()));
+        }
+        resp.json().await.map_err(|e| format!("embed parse error: {e}"))
+    }
+
+    pub async fn generate(&self, req: GenerateRequest) -> Result<GenerateResponse, String> {
+        let resp = self.client
+            .post(format!("{}/generate", self.base_url))
+            .json(&req)
+            .send()
+            .await
+            .map_err(|e| format!("generate request failed: {e}"))?;
+
+        if !resp.status().is_success() {
+            let text = resp.text().await.unwrap_or_default();
+            return Err(format!("generate error: {text}"));
+        }
+        resp.json().await.map_err(|e| format!("generate parse error: {e}"))
+    }
+
+    pub async fn rerank(&self, req: RerankRequest) -> Result<RerankResponse, String> {
+        let resp = self.client
+            .post(format!("{}/rerank", self.base_url))
+            .json(&req)
+            .send()
+            .await
+            .map_err(|e| format!("rerank request failed: {e}"))?;
+
+        if !resp.status().is_success() {
+            let text = resp.text().await.unwrap_or_default();
+            return Err(format!("rerank error: {text}"));
+        }
+        resp.json().await.map_err(|e| format!("rerank parse error: {e}"))
+    }
+
+    /// Force Ollama to unload the named model from VRAM (keep_alive=0).
+    /// Used for predictable profile swaps — without this, Ollama holds a
+    /// model for its configured TTL (default 5min) and the previous
+    /// profile's model can linger in VRAM next to the new one.
+    pub async fn unload_model(&self, model: &str) -> Result<serde_json::Value, String> {
+        let resp = self.client
+            .post(format!("{}/admin/unload", self.base_url))
+            .json(&serde_json::json!({ "model": model }))
+            .send().await
+            .map_err(|e| format!("unload request failed: {e}"))?;
+        if !resp.status().is_success() {
+            let text = resp.text().await.unwrap_or_default();
+            return Err(format!("unload error: {text}"));
+        }
+        resp.json().await.map_err(|e| format!("unload parse error: {e}"))
+    }
+
+    /// Ask Ollama to load the named model into VRAM proactively. Makes
+    /// the first real request after profile activation fast (no cold-load
+    /// latency).
+    pub async fn preload_model(&self, model: &str) -> Result<serde_json::Value, String> {
+        let resp = self.client
+            .post(format!("{}/admin/preload", self.base_url))
+            .json(&serde_json::json!({ "model": model }))
+            .send().await
+            .map_err(|e| format!("preload request failed: {e}"))?;
+        if !resp.status().is_success() {
+            let text = resp.text().await.unwrap_or_default();
+            return Err(format!("preload error: {text}"));
+        }
+        resp.json().await.map_err(|e| format!("preload parse error: {e}"))
+    }
+
+    /// GPU + loaded-model snapshot from the sidecar. Combines nvidia-smi
+    /// output (if available) with Ollama's /api/ps.
+    pub async fn vram_snapshot(&self) -> Result<serde_json::Value, String> {
+        let resp = self.client
+            .get(format!("{}/admin/vram", self.base_url))
+            .send().await
+            .map_err(|e| format!("vram request failed: {e}"))?;
+        resp.json().await.map_err(|e| format!("vram parse error: {e}"))
+    }
+}

crates/aibridge/src/context.rs

@@ -0,0 +1,188 @@
+//! Phase 21 — context-budget accounting for model calls.
+//!
+//! Ports `assertContextBudget` + `estimateTokens` + `CONTEXT_WINDOWS`
+//! from `tests/multi-agent/agent.ts` so Rust-side callers (gateway
+//! tool surfaces, future Rust agents) get the same loud-fail behavior
+//! on window overflow instead of silent truncation.
+//!
+//! The token estimator is deliberately the same chars/4 heuristic as
+//! the TS side. It's biased ~15% safe — pessimistic on English, correct
+//! within a factor of 2 on code. Swap to a provider tokenizer only when
+//! the estimator drives a decision (we're nowhere near that yet).
+
+use std::collections::HashMap;
+use std::sync::OnceLock;
+
+// `estimate_tokens` moved to `shared::model_matrix::ModelMatrix::estimate_tokens`
+// (cdc24d8). All callers migrated; the deprecated wrapper that stood in its
+// place has been removed since it had zero external consumers.
+
+/// Phase 21 — per-model context windows, mirroring the TS table in
+/// `tests/multi-agent/agent.ts`. Anchored on each model's documented
+/// max; unknown models fall back to `DEFAULT_CONTEXT_WINDOW`.
+pub const DEFAULT_CONTEXT_WINDOW: usize = 32_768;
+pub const DEFAULT_SAFETY_MARGIN: usize = 2_000;
+pub const DEFAULT_MAX_TOKENS: usize = 800;
+
+fn known_windows() -> &'static HashMap<&'static str, usize> {
+    static TABLE: OnceLock<HashMap<&'static str, usize>> = OnceLock::new();
+    TABLE.get_or_init(|| {
+        let mut m = HashMap::new();
+        m.insert("mistral:latest", 32_768);
+        m.insert("qwen2.5:latest", 32_768);
+        m.insert("qwen3:latest", 40_960);
+        m.insert("qwen3.5:latest", 262_144);
+        m.insert("qwen3-embedding", 32_768);
+        m.insert("nomic-embed-text-v2-moe", 2_048);
+        m.insert("gpt-oss:20b", 131_072);
+        m.insert("gpt-oss:120b", 131_072);
+        m.insert("qwen3.5:397b", 131_072);
+        m.insert("kimi-k2-thinking", 200_000);
+        m.insert("kimi-k2.6", 200_000);
+        m.insert("kimi-k2:1t", 1_048_576);
+        m.insert("deepseek-v3.1:671b", 131_072);
+        m.insert("glm-4.7", 131_072);
+        m
+    })
+}
+
+pub fn context_window_for(model: &str) -> usize {
+    known_windows().get(model).copied().unwrap_or(DEFAULT_CONTEXT_WINDOW)
+}
+
+/// Result of a budget check — exposes the numbers so callers can log
+/// how much headroom remains without re-running the estimator.
+#[derive(Debug, Clone, Copy)]
+pub struct BudgetCheck {
+    pub estimated: usize,
+    pub window: usize,
+    pub remaining: i64,
+}
+
+/// Inputs to `assert_context_budget`. `bypass` exists for call sites
+/// that handle their own overflow (continuation's second pass already
+/// counted the partial; T5 gatekeeper prompts have a separate policy).
+#[derive(Debug, Clone, Default)]
+pub struct BudgetOpts<'a> {
+    pub system: Option<&'a str>,
+    pub max_tokens: Option<usize>,
+    pub safety_margin: Option<usize>,
+    pub bypass: bool,
+}
+
+/// Phase 21's loud-fail primitive. Returns a `BudgetCheck` on success
+/// and the same struct plus over-by count on failure. The whole point
+/// is to stop silent truncation — callers that expect overflow should
+/// chunk BEFORE calling or set `bypass: true`.
+pub fn assert_context_budget(
+    model: &str,
+    prompt: &str,
+    opts: BudgetOpts,
+) -> Result<BudgetCheck, (BudgetCheck, usize)> {
+    let window = context_window_for(model);
+    let safety = opts.safety_margin.unwrap_or(DEFAULT_SAFETY_MARGIN);
+    let max_tokens = opts.max_tokens.unwrap_or(DEFAULT_MAX_TOKENS);
+    let sys_tokens = opts.system.map(shared::model_matrix::ModelMatrix::estimate_tokens).unwrap_or(0);
+    let estimated = shared::model_matrix::ModelMatrix::estimate_tokens(prompt) + sys_tokens + max_tokens;
+    let remaining = window as i64 - estimated as i64 - safety as i64;
+    let check = BudgetCheck { estimated, window, remaining };
+    if remaining < 0 && !opts.bypass {
+        return Err((check, (-remaining) as usize));
+    }
+    Ok(check)
+}
+
+/// Convenience — format an overflow error the same way the TS side
+/// does. Exposed so downstream crates render consistent messages.
+pub fn overflow_message(model: &str, check: &BudgetCheck, over_by: usize, safety: usize) -> String {
+    format!(
+        "context overflow: model={} est={}t window={}t safety={}t over={}t. \
+         Chunk the prompt (see config/models.json overflow_policies) or set \
+         bypass:true if you know the risk.",
+        model, check.estimated, check.window, safety, over_by,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Deprecated-function behavior is now canonically tested in
+    // crates/shared/src/model_matrix.rs. This test was the legacy
+    // pin that preceded the migration; delete when the deprecated
+    // wrapper itself goes (see the #[deprecated] attribute).
+
+    #[test]
+    fn context_window_known_and_fallback() {
+        assert_eq!(context_window_for("qwen3.5:latest"), 262_144);
+        assert_eq!(context_window_for("kimi-k2:1t"), 1_048_576);
+        assert_eq!(context_window_for("some-unreleased-model"), DEFAULT_CONTEXT_WINDOW);
+    }
+
+    #[test]
+    fn budget_passes_well_under_window() {
+        let check = assert_context_budget(
+            "qwen3:latest",
+            &"x".repeat(4_000), // ~1000 tokens
+            BudgetOpts { max_tokens: Some(500), ..Default::default() },
+        ).expect("well under 40K window");
+        assert!(check.remaining > 30_000);
+    }
+
+    #[test]
+    fn budget_fails_when_prompt_overflows_window() {
+        let huge = "x".repeat(200_000); // ~50K tokens, over qwen3's 40K
+        let err = assert_context_budget(
+            "qwen3:latest",
+            &huge,
+            BudgetOpts::default(),
+        ).expect_err("should overflow qwen3's 40K window");
+        assert!(err.1 > 0, "over_by must be positive");
+    }
+
+    #[test]
+    fn budget_bypass_returns_ok_even_over() {
+        let huge = "x".repeat(200_000);
+        let check = assert_context_budget(
+            "qwen3:latest",
+            &huge,
+            BudgetOpts { bypass: true, ..Default::default() },
+        ).expect("bypass must suppress the error");
+        assert!(check.remaining < 0, "check still reports negative remaining");
+    }
+
+    #[test]
+    fn budget_counts_system_prompt() {
+        // 10K-char system prompt → ~2500 tokens. With a big max_tokens
+        // this should push us closer to the window.
+        let sys = "s".repeat(10_000);
+        let prompt = "p".repeat(4_000);
+        let with_sys = assert_context_budget(
+            "qwen3:latest",
+            &prompt,
+            BudgetOpts {
+                system: Some(&sys),
+                max_tokens: Some(500),
+                ..Default::default()
+            },
+        ).unwrap();
+        let without_sys = assert_context_budget(
+            "qwen3:latest",
+            &prompt,
+            BudgetOpts { max_tokens: Some(500), ..Default::default() },
+        ).unwrap();
+        assert!(with_sys.estimated > without_sys.estimated,
+            "system prompt should raise estimate");
+        assert_eq!(with_sys.estimated - without_sys.estimated, shared::model_matrix::ModelMatrix::estimate_tokens(&sys));
+    }
+
+    #[test]
+    fn overflow_message_includes_numbers() {
+        let check = BudgetCheck { estimated: 42_000, window: 40_960, remaining: -1_040 };
+        let msg = overflow_message("qwen3:latest", &check, 3_040, 2_000);
+        assert!(msg.contains("qwen3:latest"));
+        assert!(msg.contains("42000t"));
+        assert!(msg.contains("40960t"));
+        assert!(msg.contains("3040t"));
+    }
+}

crates/aibridge/src/continuation.rs

@@ -0,0 +1,461 @@
+//! Phase 21 — OUTPUT-overflow handler. Ports `generateContinuable`
+//! from `tests/multi-agent/agent.ts`.
+//!
+//! Two failure modes to repair:
+//!
+//! * EMPTY response — thinking model ate the entire budget on hidden
+//!   reasoning before emitting a token. Fix: retry the original prompt
+//!   with 2× the budget, geometric up to `BUDGET_CAP`.
+//!
+//! * TRUNCATED non-empty — model got most of the way but hit
+//!   max_tokens before closing the structure. Fix: continue with the
+//!   partial response in the prompt as scratchpad, so the model knows
+//!   where to pick up without restarting.
+//!
+//! `TextGenerator` abstracts the sidecar so tests can inject canned
+//! responses without a live Ollama.
+
+use std::future::Future;
+
+use crate::client::{AiClient, GenerateRequest, GenerateResponse};
+
+/// Shape classifier for `is_structurally_complete`. JSON responses
+/// must parse; text responses just need to be non-empty.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResponseShape {
+    Json,
+    Text,
+}
+
+/// Trait that `generate_continuable` + `generate_tree_split` call. The
+/// real implementation forwards to `AiClient::generate`; tests supply a
+/// mock with a scripted sequence of responses.
+pub trait TextGenerator: Send + Sync {
+    fn generate_text(
+        &self,
+        req: GenerateRequest,
+    ) -> impl Future<Output = Result<GenerateResponse, String>> + Send;
+}
+
+impl TextGenerator for AiClient {
+    fn generate_text(
+        &self,
+        req: GenerateRequest,
+    ) -> impl Future<Output = Result<GenerateResponse, String>> + Send {
+        self.generate(req)
+    }
+}
+
+/// Strip a surrounding ```json``` fence if present. Leaves the inner
+/// content alone otherwise. Returns a slice of `s`.
+fn strip_json_fence(s: &str) -> &str {
+    let t = s.trim();
+    if let Some(rest) = t.strip_prefix("```json") {
+        rest.trim_start_matches('\n').strip_suffix("```").unwrap_or(rest).trim()
+    } else if let Some(rest) = t.strip_prefix("```") {
+        rest.trim_start_matches('\n').strip_suffix("```").unwrap_or(rest).trim()
+    } else {
+        t
+    }
+}
+
+/// Port of the TS brace-balance + JSON.parse check. Returns true when
+/// the outermost `{...}` block is balanced and parses. Text shape is
+/// satisfied by any non-empty, non-whitespace payload.
+pub fn is_structurally_complete(text: &str, shape: ResponseShape) -> bool {
+    if text.trim().is_empty() { return false; }
+    if shape == ResponseShape::Text { return true; }
+
+    let s = strip_json_fence(text);
+    let Some(start) = s.find('{') else { return false };
+    let Some(end) = s.rfind('}') else { return false };
+    if end <= start { return false; }
+    let slice = &s[start..=end];
+
+    // Balance check — cheaper than parse, catches truncated nests.
+    // String state tracked because `{` inside a string doesn't count.
+    let mut depth: i32 = 0;
+    let mut in_str = false;
+    let mut esc = false;
+    for c in slice.chars() {
+        if esc { esc = false; continue; }
+        if c == '\\' { esc = true; continue; }
+        if c == '"' { in_str = !in_str; continue; }
+        if in_str { continue; }
+        if c == '{' { depth += 1; }
+        else if c == '}' {
+            depth -= 1;
+            if depth < 0 { return false; }
+        }
+    }
+    if depth != 0 { return false; }
+    // Parse check is the tie-breaker — balanced but invalid JSON (e.g.
+    // trailing comma before `}`) shouldn't count as complete.
+    serde_json::from_str::<serde_json::Value>(slice).is_ok()
+}
+
+/// Knobs for `generate_continuable`. All optional with sensible
+/// defaults that match the TS version.
+#[derive(Debug, Clone)]
+pub struct ContinuableOpts {
+    pub model: String,
+    pub max_tokens: Option<u32>,
+    pub temperature: Option<f64>,
+    pub system: Option<String>,
+    pub shape: ResponseShape,
+    pub max_continuations: usize,
+    pub think: Option<bool>,
+    /// Geometric-backoff ceiling for the empty-response retry path.
+    /// Matches TS's `budgetCap = 8000`.
+    pub budget_cap: u32,
+    /// Maximum empty-response retries before giving up. Matches TS's
+    /// hardcoded `retry < 3`.
+    pub max_empty_retries: usize,
+}
+
+impl ContinuableOpts {
+    pub fn new(model: impl Into<String>) -> Self {
+        Self {
+            model: model.into(),
+            max_tokens: None,
+            temperature: None,
+            system: None,
+            shape: ResponseShape::Json,
+            max_continuations: 3,
+            think: None,
+            budget_cap: 8_000,
+            max_empty_retries: 3,
+        }
+    }
+}
+
+/// Outcome of a `generate_continuable` call. Carries the combined
+/// text plus diagnostic counters so observability downstream can
+/// report "how many continuations did that query cost".
+#[derive(Debug, Clone)]
+pub struct ContinuableOutcome {
+    pub text: String,
+    pub empty_retries: usize,
+    pub continuations: usize,
+    pub final_complete: bool,
+    /// Sum of `prompt_tokens` across every generator call made to
+    /// produce this outcome — including empty retries and continuations.
+    /// Lets callers (gateway execution loop, observability) stamp
+    /// accurate per-task usage without second-guessing the retry fan-out.
+    pub prompt_tokens: u32,
+    /// Sum of `completion_tokens` across every generator call.
+    pub completion_tokens: u32,
+    /// Total number of generator calls. `1 + empty_retries +
+    /// continuations` in the normal case; the field is explicit so
+    /// callers don't have to re-derive it.
+    pub calls: u32,
+}
+
+fn make_request(opts: &ContinuableOpts, prompt: String, current_max: u32) -> GenerateRequest {
+    GenerateRequest {
+        prompt,
+        model: Some(opts.model.clone()),
+        system: opts.system.clone(),
+        temperature: opts.temperature,
+        max_tokens: Some(current_max),
+        think: opts.think,
+    }
+}
+
+fn continuation_prompt(original: &str, partial: &str) -> String {
+    format!(
+        "{original}\n\n\
+         PARTIAL RESPONSE SO FAR (continue from here — do NOT restart, \
+         do NOT repeat what's already there, emit ONLY the remaining \
+         tokens to close the structure):\n{partial}"
+    )
+}
+
+/// Phase 21 — output-overflow safe generate. See module docs for the
+/// two failure modes repaired. On final-still-incomplete, returns the
+/// combined text with `final_complete: false` so the caller's parser
+/// can throw with the raw text for forensics rather than silently
+/// truncating.
+pub async fn generate_continuable<G: TextGenerator>(
+    generator: &G,
+    prompt: &str,
+    opts: &ContinuableOpts,
+) -> Result<ContinuableOutcome, String> {
+    let initial_max = opts.max_tokens.unwrap_or(800);
+    let mut current_max = initial_max;
+    let mut combined = String::new();
+    let mut empty_retries = 0usize;
+    let mut continuations = 0usize;
+    let mut prompt_tokens: u32 = 0;
+    let mut completion_tokens: u32 = 0;
+    let mut calls: u32 = 0;
+
+    // Phase 21(a) — empty-response backoff loop.
+    for retry in 0..opts.max_empty_retries {
+        let req = make_request(opts, prompt.to_string(), current_max);
+        let resp = generator.generate_text(req).await?;
+        calls += 1;
+        prompt_tokens = prompt_tokens.saturating_add(resp.tokens_evaluated.unwrap_or(0) as u32);
+        completion_tokens = completion_tokens.saturating_add(resp.tokens_generated.unwrap_or(0) as u32);
+        if !resp.text.trim().is_empty() {
+            combined = resp.text;
+            break;
+        }
+        empty_retries = retry + 1;
+        current_max = (current_max.saturating_mul(2)).min(opts.budget_cap);
+    }
+
+    // Phase 21(b) — structural-completion continuation loop.
+    for _ in 0..opts.max_continuations {
+        if is_structurally_complete(&combined, opts.shape) {
+            return Ok(ContinuableOutcome {
+                text: combined,
+                empty_retries,
+                continuations,
+                final_complete: true,
+                prompt_tokens,
+                completion_tokens,
+                calls,
+            });
+        }
+        if combined.trim().is_empty() {
+            // Nothing to continue from — continuing "" is identical to
+            // the initial call and would loop.
+            break;
+        }
+        let cont_prompt = continuation_prompt(prompt, &combined);
+        let req = make_request(opts, cont_prompt, current_max.min(opts.budget_cap));
+        let resp = generator.generate_text(req).await?;
+        calls += 1;
+        prompt_tokens = prompt_tokens.saturating_add(resp.tokens_evaluated.unwrap_or(0) as u32);
+        completion_tokens = completion_tokens.saturating_add(resp.tokens_generated.unwrap_or(0) as u32);
+        combined.push_str(&resp.text);
+        continuations += 1;
+    }
+
+    let final_complete = is_structurally_complete(&combined, opts.shape);
+    Ok(ContinuableOutcome {
+        text: combined,
+        empty_retries,
+        continuations,
+        final_complete,
+        prompt_tokens,
+        completion_tokens,
+        calls,
+    })
+}
+
+/// Scripted generator for unit tests. Returns responses from `script`
+/// in order; extra calls reuse the last entry so tests don't have to
+/// count past what they actually assert on.
+#[cfg(test)]
+pub struct ScriptedGenerator {
+    script: Vec<Result<String, String>>,
+    calls: std::sync::Arc<std::sync::Mutex<Vec<GenerateRequest>>>,
+}
+
+#[cfg(test)]
+impl ScriptedGenerator {
+    pub fn new<I>(script: I) -> Self
+    where
+        I: IntoIterator<Item = Result<String, String>>,
+    {
+        Self {
+            script: script.into_iter().collect(),
+            calls: std::sync::Arc::new(std::sync::Mutex::new(Vec::new())),
+        }
+    }
+
+    pub fn calls(&self) -> Vec<GenerateRequest> {
+        self.calls.lock().unwrap().clone()
+    }
+
+    pub fn call_count(&self) -> usize {
+        self.calls.lock().unwrap().len()
+    }
+}
+
+#[cfg(test)]
+impl TextGenerator for ScriptedGenerator {
+    fn generate_text(
+        &self,
+        req: GenerateRequest,
+    ) -> impl Future<Output = Result<GenerateResponse, String>> + Send {
+        let i = {
+            let mut calls = self.calls.lock().unwrap();
+            let i = calls.len();
+            calls.push(req.clone());
+            i
+        };
+        let model = req.model.clone().unwrap_or_default();
+        let entry = self.script.get(i)
+            .cloned()
+            .unwrap_or_else(|| self.script.last().cloned().unwrap_or(Ok(String::new())));
+        async move {
+            entry.map(|text| GenerateResponse {
+                text,
+                model,
+                tokens_evaluated: None,
+                tokens_generated: None,
+            })
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn structural_complete_rejects_empty_and_text_mismatch() {
+        assert!(!is_structurally_complete("", ResponseShape::Text));
+        assert!(!is_structurally_complete("   ", ResponseShape::Text));
+        assert!(is_structurally_complete("any content", ResponseShape::Text));
+    }
+
+    #[test]
+    fn structural_complete_handles_balanced_json() {
+        assert!(is_structurally_complete(r#"{"a": 1}"#, ResponseShape::Json));
+        assert!(is_structurally_complete(
+            r#"```json
+{"a": 1, "b": [1, 2, 3]}
+```"#,
+            ResponseShape::Json,
+        ));
+    }
+
+    #[test]
+    fn structural_complete_rejects_truncated_json() {
+        assert!(!is_structurally_complete(r#"{"a": 1"#, ResponseShape::Json));
+        assert!(!is_structurally_complete(r#"{"a": {"b": 1"#, ResponseShape::Json));
+        // Trailing comma — balanced but unparseable
+        assert!(!is_structurally_complete(r#"{"a": 1,}"#, ResponseShape::Json));
+    }
+
+    #[test]
+    fn structural_complete_ignores_braces_inside_strings() {
+        assert!(is_structurally_complete(r#"{"s": "has } inside"}"#, ResponseShape::Json));
+        assert!(is_structurally_complete(r#"{"s": "escaped \" quote"}"#, ResponseShape::Json));
+    }
+
+    #[tokio::test]
+    async fn continuable_returns_first_response_when_complete() {
+        let generator = ScriptedGenerator::new(vec![Ok(r#"{"ok": true}"#.to_string())]);
+        let opts = ContinuableOpts::new("qwen3:latest");
+        let out = generate_continuable(&generator, "test", &opts).await.unwrap();
+        assert!(out.final_complete);
+        assert_eq!(out.empty_retries, 0);
+        assert_eq!(out.continuations, 0);
+        assert_eq!(generator.call_count(), 1);
+    }
+
+    #[tokio::test]
+    async fn continuable_retries_on_empty_with_doubled_budget() {
+        // Two empties, then a good response. Third call should see 4×
+        // the initial budget (2× twice).
+        let generator = ScriptedGenerator::new(vec![
+            Ok("".to_string()),
+            Ok("".to_string()),
+            Ok(r#"{"ok": true}"#.to_string()),
+        ]);
+        let mut opts = ContinuableOpts::new("qwen3:latest");
+        opts.max_tokens = Some(100);
+        let out = generate_continuable(&generator, "test", &opts).await.unwrap();
+        assert!(out.final_complete);
+        assert_eq!(out.empty_retries, 2);
+
+        let calls = generator.calls();
+        assert_eq!(calls.len(), 3);
+        assert_eq!(calls[0].max_tokens, Some(100));
+        assert_eq!(calls[1].max_tokens, Some(200));
+        assert_eq!(calls[2].max_tokens, Some(400));
+    }
+
+    #[tokio::test]
+    async fn continuable_caps_budget_at_budget_cap() {
+        let generator = ScriptedGenerator::new(vec![
+            Ok("".to_string()),
+            Ok("".to_string()),
+            Ok(r#"{"ok":1}"#.to_string()),
+        ]);
+        let mut opts = ContinuableOpts::new("qwen3:latest");
+        opts.max_tokens = Some(5_000);
+        opts.budget_cap = 7_000;
+        let out = generate_continuable(&generator, "test", &opts).await.unwrap();
+        assert!(out.final_complete);
+        let calls = generator.calls();
+        // 5000 → doubled would be 10000; cap pulls it to 7000.
+        assert_eq!(calls[1].max_tokens, Some(7_000));
+        assert_eq!(calls[2].max_tokens, Some(7_000));
+    }
+
+    #[tokio::test]
+    async fn continuable_glues_truncated_response() {
+        // First call returns balanced-open `{...`; continuation closes
+        // it with `...}`. Combined must parse.
+        let generator = ScriptedGenerator::new(vec![
+            Ok(r#"{"fills": [{"candidate_id": "C-001""#.to_string()),
+            Ok(r#", "name": "Alice"}]}"#.to_string()),
+        ]);
+        let opts = ContinuableOpts::new("qwen3:latest");
+        let out = generate_continuable(&generator, "ORIGINAL", &opts).await.unwrap();
+        assert!(out.final_complete, "combined must parse: {}", out.text);
+        assert_eq!(out.continuations, 1);
+
+        let calls = generator.calls();
+        assert_eq!(calls.len(), 2);
+        // Continuation prompt must contain the partial — that's the
+        // scratchpad primitive J called out.
+        let cont_prompt = &calls[1].prompt;
+        assert!(cont_prompt.contains("ORIGINAL"),
+            "continuation must include original prompt");
+        assert!(cont_prompt.contains(r#"{"fills": [{"candidate_id": "C-001""#),
+            "continuation must include partial");
+    }
+
+    #[tokio::test]
+    async fn continuable_does_not_loop_on_persistent_empty() {
+        // All three retries return empty; we must NOT then enter the
+        // continuation loop with an empty partial (would burn 3 more
+        // calls continuing from "").
+        let generator = ScriptedGenerator::new(vec![
+            Ok("".to_string()),
+            Ok("".to_string()),
+            Ok("".to_string()),
+        ]);
+        let opts = ContinuableOpts::new("qwen3:latest");
+        let out = generate_continuable(&generator, "test", &opts).await.unwrap();
+        assert!(!out.final_complete);
+        assert_eq!(out.empty_retries, 3);
+        assert_eq!(out.continuations, 0, "must not continue from empty");
+        assert_eq!(generator.call_count(), 3);
+    }
+
+    #[tokio::test]
+    async fn continuable_returns_raw_on_exhausted_continuations() {
+        // Three continuations that never complete — caller's parser
+        // will throw. We must return the combined text so forensics
+        // has the raw content, not a lossy truncation.
+        let generator = ScriptedGenerator::new(vec![
+            Ok(r#"{"a": ["#.to_string()),
+            Ok("1,".to_string()),
+            Ok("2,".to_string()),
+            Ok("3,".to_string()),
+        ]);
+        let mut opts = ContinuableOpts::new("qwen3:latest");
+        opts.max_continuations = 3;
+        let out = generate_continuable(&generator, "test", &opts).await.unwrap();
+        assert!(!out.final_complete);
+        assert_eq!(out.continuations, 3);
+        assert!(out.text.contains(r#"{"a": ["#));
+        assert!(out.text.contains("3,"));
+    }
+
+    #[tokio::test]
+    async fn continuable_propagates_generator_errors() {
+        let generator = ScriptedGenerator::new(vec![Err("sidecar 503".to_string())]);
+        let opts = ContinuableOpts::new("qwen3:latest");
+        let err = generate_continuable(&generator, "test", &opts).await.unwrap_err();
+        assert!(err.contains("503"));
+    }
+}

crates/aibridge/src/lib.rs

@@ -0,0 +1,8 @@
+pub mod client;
+pub mod context;
+pub mod continuation;
+pub mod provider;
+pub mod providers;
+pub mod routing;
+pub mod service;
+pub mod tree_split;

crates/aibridge/src/provider.rs

@@ -0,0 +1,39 @@
+use async_trait::async_trait;
+use crate::client::{GenerateRequest, GenerateResponse, EmbedRequest, EmbedResponse};
+
+#[async_trait]
+pub trait ProviderAdapter: Send + Sync {
+    /// Name for routing (ollama, openrouter, etc.)
+    fn name(&self) -> &str;
+
+    /// Chat completion — returns text, model, token counts
+    async fn chat(&self, req: GenerateRequest) -> Result<GenerateResponse, String>;
+
+    /// Embeddings — returns vectors, model, dimensions
+    async fn embed(&self, req: EmbedRequest) -> Result<EmbedResponse, String>;
+
+    /// Unload model from VRAM (optional, no-op if not supported)
+    async fn unload(&self, _model: &str) -> Result<(), String> {
+        Ok(())
+    }
+
+    /// Health check
+    async fn health(&self) -> Result<serde_json::Value, String>;
+}
+
+/// Routing key extracted from model name.
+/// - "qwen3.5:latest" → "ollama"
+/// - "openrouter/anthropic/claude-3.5-sonnet" → "openrouter"
+/// - "gpt-4o" → "ollama" (default)
+pub fn provider_key(model: &str) -> &'static str {
+    let lower = model.to_lowercase();
+    if lower.starts_with("openrouter/") {
+        "openrouter"
+    } else if lower.starts_with("gemini") {
+        "gemini"
+    } else if lower.starts_with("claude") {
+        "claude"
+    } else {
+        "ollama"  // default: local Ollama
+    }
+}

crates/aibridge/src/providers/mod.rs

@@ -0,0 +1,2 @@
+pub mod ollama;
+pub mod openrouter;

crates/aibridge/src/providers/ollama.rs

@@ -0,0 +1,37 @@
+use async_trait::async_trait;
+use crate::client::{AiClient, GenerateRequest, GenerateResponse, EmbedRequest, EmbedResponse};
+use crate::provider::ProviderAdapter;
+
+pub struct OllamaAdapter {
+    client: AiClient,
+}
+
+impl OllamaAdapter {
+    pub fn new(client: AiClient) -> Self {
+        Self { client }
+    }
+}
+
+#[async_trait]
+impl ProviderAdapter for OllamaAdapter {
+    fn name(&self) -> &str {
+        "ollama"
+    }
+
+    async fn chat(&self, req: GenerateRequest) -> Result<GenerateResponse, String> {
+        self.client.generate(req).await
+    }
+
+    async fn embed(&self, req: EmbedRequest) -> Result<EmbedResponse, String> {
+        self.client.embed(req).await
+    }
+
+    async fn unload(&self, model: &str) -> Result<(), String> {
+        let _: serde_json::Value = self.client.unload_model(model).await?;
+        Ok(())
+    }
+
+    async fn health(&self) -> Result<serde_json::Value, String> {
+        self.client.health().await
+    }
+}

crates/aibridge/src/providers/openrouter.rs

@@ -0,0 +1,152 @@
+use async_trait::async_trait;
+use reqwest::Client;
+use serde::{Deserialize, Serialize};
+use std::time::Duration;
+
+use crate::client::{GenerateRequest, GenerateResponse, EmbedRequest, EmbedResponse};
+use crate::provider::ProviderAdapter;
+
+pub struct OpenRouterAdapter {
+    client: Client,
+    base_url: String,
+    api_key: String,
+    default_model: String,
+}
+
+#[derive(Serialize)]
+struct OpenRouterChatRequest {
+    model: String,
+    messages: Vec<OpenRouterMessage>,
+    temperature: Option<f64>,
+    max_tokens: Option<u32>,
+}
+
+#[derive(Serialize)]
+struct OpenRouterMessage {
+    role: String,
+    content: String,
+}
+
+#[derive(Deserialize)]
+struct OpenRouterChatResponse {
+    choices: Vec<OpenRouterChoice>,
+    usage: OpenRouterUsage,
+    model: String,
+}
+
+#[derive(Deserialize)]
+struct OpenRouterChoice {
+    message: OpenRouterMessageOut,
+}
+
+#[derive(Deserialize)]
+#[allow(dead_code)]
+struct OpenRouterMessageOut {
+    role: String,
+    content: String,
+}
+
+#[derive(Deserialize)]
+#[allow(dead_code)]
+struct OpenRouterUsage {
+    prompt_tokens: Option<u32>,
+    completion_tokens: Option<u32>,
+    total_tokens: Option<u32>,
+}
+
+impl OpenRouterAdapter {
+    pub fn new(base_url: &str, api_key: String, default_model: &str) -> Self {
+        let client = Client::builder()
+            .timeout(Duration::from_secs(180))
+            .build()
+            .expect("failed to build HTTP client");
+        Self {
+            client,
+            base_url: base_url.trim_end_matches('/').to_string(),
+            api_key,
+            default_model: default_model.to_string(),
+        }
+    }
+
+    fn chat_model(&self, model: &str) -> String {
+        // Strip "openrouter/" prefix if present
+        let m = model.trim_start_matches("openrouter/");
+        if m.is_empty() || m == model {
+            self.default_model.clone()
+        } else {
+            m.to_string()
+        }
+    }
+
+    fn to_openrouter_messages(req: &GenerateRequest) -> Vec<OpenRouterMessage> {
+        let mut out = vec![];
+        if let Some(sys) = &req.system {
+            out.push(OpenRouterMessage { role: "system".into(), content: sys.clone() });
+        }
+        out.push(OpenRouterMessage {
+            role: "user".into(),
+            content: req.prompt.clone(),
+        });
+        out
+    }
+}
+
+#[async_trait]
+impl ProviderAdapter for OpenRouterAdapter {
+    fn name(&self) -> &str {
+        "openrouter"
+    }
+
+    async fn chat(&self, req: GenerateRequest) -> Result<GenerateResponse, String> {
+        let model = self.chat_model(req.model.as_deref().unwrap_or(""));
+        let or_req = OpenRouterChatRequest {
+            model: model.clone(),
+            messages: OpenRouterAdapter::to_openrouter_messages(&req),
+            temperature: req.temperature,
+            max_tokens: req.max_tokens,
+        };
+
+        let resp = self.client
+            .post(format!("{}/chat/completions", self.base_url))
+            .header("Authorization", format!("Bearer {}", self.api_key))
+            .header("Content-Type", "application/json")
+            .json(&or_req)
+            .send()
+            .await
+            .map_err(|e| format!("openrouter request failed: {e}"))?;
+
+        let status = resp.status();
+        let body = resp.text().await.unwrap_or_default();
+
+        if !status.is_success() {
+            return Err(format!("openrouter error ({}): {}", status, body));
+        }
+
+        let or_resp: OpenRouterChatResponse = serde_json::from_str(&body)
+            .map_err(|e| format!("openrouter parse error: {e}"))?;
+
+        let choice = or_resp.choices.into_iter().next()
+            .ok_or("no completion choice returned")?;
+        let usage = or_resp.usage;
+
+        Ok(GenerateResponse {
+            text: choice.message.content,
+            model: or_resp.model,
+            tokens_evaluated: usage.prompt_tokens.map(|n| n as u64),
+            tokens_generated: usage.completion_tokens.map(|n| n as u64),
+        })
+    }
+
+    async fn embed(&self, _req: EmbedRequest) -> Result<EmbedResponse, String> {
+        Err("openrouter: embed not implemented".into())
+    }
+
+    async fn health(&self) -> Result<serde_json::Value, String> {
+        // OpenRouter doesn't have a dedicated health endpoint,
+        // so we just return a healthy response if the client works.
+        Ok(serde_json::json!({
+            "status": "ok",
+            "provider": "openrouter",
+        }))
+    }
+}

crates/aibridge/src/routing.rs

@@ -0,0 +1,119 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct RoutingRule {
+    pub model_pattern: String,
+    pub provider: String,
+    pub max_tokens: Option<u32>,
+    pub temperature: Option<f64>,
+}
+
+#[derive(Clone, Default)]
+pub struct RoutingEngine {
+    rules: Vec<RoutingRule>,
+    fallback_chain: Vec<String>,
+}
+
+impl RoutingEngine {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_rules(mut self, rules: Vec<RoutingRule>) -> Self {
+        self.rules = rules;
+        self
+    }
+
+    pub fn with_fallback(mut self, chain: Vec<String>) -> Self {
+        self.fallback_chain = chain;
+        self
+    }
+
+    pub fn route(&self, model: &str) -> RouteDecision {
+        let lower = model.to_lowercase();
+
+        for rule in &self.rules {
+            if glob_match(&rule.model_pattern.to_lowercase(), &lower) {
+                return RouteDecision {
+                    provider: rule.provider.clone(),
+                    model: model.to_string(),
+                    max_tokens: rule.max_tokens,
+                    temperature: rule.temperature,
+                };
+            }
+        }
+
+        if let Some(first) = self.fallback_chain.first() {
+            RouteDecision {
+                provider: first.clone(),
+                model: model.to_string(),
+                max_tokens: None,
+                temperature: None,
+            }
+        } else {
+            RouteDecision {
+                provider: "ollama".to_string(),
+                model: model.to_string(),
+                max_tokens: None,
+                temperature: None,
+            }
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct RouteDecision {
+    pub provider: String,
+    pub model: String,
+    pub max_tokens: Option<u32>,
+    pub temperature: Option<f64>,
+}
+
+fn glob_match(pattern: &str, name: &str) -> bool {
+    if !pattern.contains('*') { return pattern == name; }
+    let parts: Vec<&str> = pattern.split('*').collect();
+    // Multi-* support: first must be prefix, last must be suffix, each
+    // interior piece must appear in order. Fixes the iter-9 finding
+    // where gpt-*-large* silently fell through to an exact-match path.
+    // Also removes the dead `parts.len() == 1` branch that accessed
+    // parts[1] and would panic if ever reached (unreachable today
+    // since split('*') on a string containing '*' always yields ≥2).
+    if !name.starts_with(parts[0]) || !name.ends_with(parts.last().unwrap()) { return false; }
+    let mut cursor = parts[0].len();
+    parts[1..parts.len() - 1].iter().all(|mid| {
+        name[cursor..].find(mid).map(|pos| { cursor += pos + mid.len(); true }).unwrap_or(false)
+    })
+}
+
+impl Default for RoutingRule {
+    fn default() -> Self {
+        Self {
+            model_pattern: "*".to_string(),
+            provider: "ollama".to_string(),
+            max_tokens: None,
+            temperature: None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod glob_match_tests {
+    use super::glob_match;
+
+    #[test] fn exact_match() { assert!(glob_match("gpt-oss:120b", "gpt-oss:120b")); }
+    #[test] fn exact_mismatch() { assert!(!glob_match("a", "b")); }
+    #[test] fn leading_wildcard() { assert!(glob_match("*:120b", "gpt-oss:120b")); }
+    #[test] fn trailing_wildcard() { assert!(glob_match("gpt-oss:*", "gpt-oss:120b")); }
+    #[test] fn bare_wildcard() { assert!(glob_match("*", "anything")); }
+    #[test] fn multi_wildcard_in_order() { assert!(glob_match("gpt-*-oss-*", "gpt-4-oss-120b")); }
+    #[test] fn multi_wildcard_wrong_order() { assert!(!glob_match("b*a*", "abba")); }
+    #[test] fn multi_wildcard_panic_safety() {
+        // Regression: earlier impl had an unreachable `parts.len() == 1`
+        // branch that indexed parts[1] — would panic if ever hit. Now
+        // the split('*') invariant guarantees ≥2 parts when * present,
+        // and we handle all N-part cases explicitly.
+        assert!(glob_match("a*b*c", "abc"));
+        assert!(glob_match("a*b*c", "axxxbxxxc"));
+        assert!(!glob_match("a*b*c", "xxxbxxx"));
+    }
+}

crates/aibridge/src/service.rs

@@ -0,0 +1,68 @@
+use axum::{
+    Json, Router,
+    extract::State,
+    http::StatusCode,
+    response::IntoResponse,
+    routing::{get, post},
+};
+
+use crate::client::{
+    AiClient, EmbedRequest, GenerateRequest, RerankRequest,
+};
+
+pub fn router(client: AiClient) -> Router {
+    Router::new()
+        .route("/health", get(health))
+        .route("/embed", post(embed))
+        .route("/generate", post(generate))
+        .route("/rerank", post(rerank))
+        .route("/vram", get(vram))
+        .with_state(client)
+}
+
+async fn vram(State(client): State<AiClient>) -> impl IntoResponse {
+    match client.vram_snapshot().await {
+        Ok(snap) => Ok(Json(snap)),
+        Err(e) => Err((StatusCode::BAD_GATEWAY, e)),
+    }
+}
+
+async fn health(State(client): State<AiClient>) -> impl IntoResponse {
+    match client.health().await {
+        Ok(info) => Ok(Json(info)),
+        Err(e) => Err((StatusCode::BAD_GATEWAY, format!("sidecar down: {e}"))),
+    }
+}
+
+async fn embed(
+    State(client): State<AiClient>,
+    Json(req): Json<EmbedRequest>,
+) -> impl IntoResponse {
+    tracing::info!("embedding {} texts", req.texts.len());
+    match client.embed(req).await {
+        Ok(resp) => Ok(Json(resp)),
+        Err(e) => Err((StatusCode::BAD_GATEWAY, e)),
+    }
+}
+
+async fn generate(
+    State(client): State<AiClient>,
+    Json(req): Json<GenerateRequest>,
+) -> impl IntoResponse {
+    tracing::info!("generating with prompt len={}", req.prompt.len());
+    match client.generate(req).await {
+        Ok(resp) => Ok(Json(resp)),
+        Err(e) => Err((StatusCode::BAD_GATEWAY, e)),
+    }
+}
+
+async fn rerank(
+    State(client): State<AiClient>,
+    Json(req): Json<RerankRequest>,
+) -> impl IntoResponse {
+    tracing::info!("reranking {} documents", req.documents.len());
+    match client.rerank(req).await {
+        Ok(resp) => Ok(Json(resp)),
+        Err(e) => Err((StatusCode::BAD_GATEWAY, e)),
+    }
+}

crates/aibridge/src/tree_split.rs

@@ -0,0 +1,327 @@
+//! Phase 21 — INPUT-overflow handler. Ports `generateTreeSplit` from
+//! `tests/multi-agent/agent.ts`.
+//!
+//! When the input corpus exceeds the model's window (200 playbooks
+//! pasted into a T4 strategic prompt, a long retrospective digest, a
+//! cross-corpus summarization), raising `max_tokens` doesn't help —
+//! the prompt itself is the problem. The answer is map-reduce:
+//!
+//!   1. Caller shards the input at semantic boundaries (records,
+//!      paragraphs, playbook entries).
+//!   2. For each shard, build a map prompt that includes the running
+//!      scratchpad and run it through `generate_continuable`.
+//!   3. Append the map output to the scratchpad (oldest-first
+//!      truncation when it outgrows `scratchpad_budget`).
+//!   4. Build a reduce prompt from the final scratchpad and run it.
+//!
+//! Every shard prompt and the reduce prompt go through
+//! `assert_context_budget` first — if a single shard still overflows
+//! we bubble the error up rather than silently truncating. That's the
+//! whole point of Phase 21.
+
+use crate::context::{assert_context_budget, BudgetOpts, overflow_message,
+                     DEFAULT_MAX_TOKENS, DEFAULT_SAFETY_MARGIN};
+use shared::model_matrix::ModelMatrix;
+use crate::continuation::{generate_continuable, ContinuableOpts, ResponseShape, TextGenerator};
+
+/// Callback signatures — caller supplies closures that stitch the
+/// scratchpad into each shard's prompt and build the final reduce
+/// prompt. Kept as `Fn` (not `FnMut`) so the map loop can call them
+/// by reference.
+pub type MapPromptFn<'a> = dyn Fn(&str, &str) -> String + Send + Sync + 'a;
+pub type ReducePromptFn<'a> = dyn Fn(&str) -> String + Send + Sync + 'a;
+
+/// Knobs for `generate_tree_split`.
+#[derive(Debug, Clone)]
+pub struct TreeSplitOpts {
+    pub model: String,
+    pub system: Option<String>,
+    pub temperature: Option<f64>,
+    /// max_tokens for map AND reduce (reduce defaults are usually
+    /// higher; caller overrides for just reduce by calling through
+    /// continuable directly if needed).
+    pub max_tokens: Option<u32>,
+    pub reduce_max_tokens: Option<u32>,
+    pub think: Option<bool>,
+    /// Soft ceiling on scratchpad size (estimated tokens). When it
+    /// grows past this, the oldest shard digest gets dropped. Default
+    /// 6000, matching the TS implementation.
+    pub scratchpad_budget: usize,
+    pub safety_margin: Option<usize>,
+}
+
+impl TreeSplitOpts {
+    pub fn new(model: impl Into<String>) -> Self {
+        Self {
+            model: model.into(),
+            system: None,
+            temperature: None,
+            max_tokens: None,
+            reduce_max_tokens: None,
+            think: None,
+            scratchpad_budget: 6_000,
+            safety_margin: None,
+        }
+    }
+}
+
+/// Result — final reduce response plus the accumulated scratchpad so
+/// the caller can inspect what was kept vs truncated.
+#[derive(Debug, Clone)]
+pub struct TreeSplitResult {
+    pub response: String,
+    pub scratchpad: String,
+    pub shards_processed: usize,
+    pub scratchpad_truncations: usize,
+    pub total_continuations: usize,
+}
+
+/// Drop shard-digest blocks from the head of `scratchpad` until its
+/// estimated-token count fits the budget. Digest blocks are delimited
+/// by `\n— shard N/M digest —\n` so we can find the first one and
+/// chop everything before its successor.
+fn truncate_scratchpad(scratchpad: &mut String, budget_tokens: usize) -> bool {
+    if ModelMatrix::estimate_tokens(scratchpad) <= budget_tokens { return false; }
+    // Find the second delimiter — everything before it gets dropped.
+    const DELIM_PREFIX: &str = "\n— shard ";
+    let mut cursor = 0;
+    let mut truncated = false;
+    while ModelMatrix::estimate_tokens(&scratchpad[cursor..]) > budget_tokens {
+        // Skip past a leading delimiter (if we're sitting on one from
+        // a previous iteration), then find the next.
+        let search_from = cursor + if scratchpad[cursor..].starts_with(DELIM_PREFIX) {
+            DELIM_PREFIX.len()
+        } else { 0 };
+        let Some(rel_next) = scratchpad[search_from..].find(DELIM_PREFIX) else { break };
+        cursor = search_from + rel_next;
+        truncated = true;
+    }
+    if cursor > 0 {
+        scratchpad.drain(..cursor);
+    }
+    truncated
+}
+
+/// Phase 21 — map-reduce over shards with a running scratchpad. See
+/// module docs.
+pub async fn generate_tree_split<G: TextGenerator>(
+    generator: &G,
+    shards: &[String],
+    map_prompt: &MapPromptFn<'_>,
+    reduce_prompt: &ReducePromptFn<'_>,
+    opts: &TreeSplitOpts,
+) -> Result<TreeSplitResult, String> {
+    let mut scratchpad = String::new();
+    let safety = opts.safety_margin.unwrap_or(DEFAULT_SAFETY_MARGIN);
+    let map_max = opts.max_tokens.unwrap_or(DEFAULT_MAX_TOKENS as u32);
+    let reduce_max = opts.reduce_max_tokens.unwrap_or(1_500);
+    let mut truncations = 0usize;
+    let mut total_continuations = 0usize;
+
+    for (i, shard) in shards.iter().enumerate() {
+        let shard_prompt = map_prompt(shard, &scratchpad);
+        // Loud-fail on per-shard overflow — caller sharded too
+        // coarsely. Silent truncation is exactly the mode J rejected.
+        let budget = BudgetOpts {
+            system: opts.system.as_deref(),
+            max_tokens: Some(map_max as usize),
+            safety_margin: Some(safety),
+            bypass: false,
+        };
+        let check = assert_context_budget(&opts.model, &shard_prompt, budget)
+            .map_err(|(c, over)| overflow_message(&opts.model, &c, over, safety))?;
+        let _ = check;
+
+        let mut cont_opts = ContinuableOpts::new(&opts.model);
+        cont_opts.max_tokens = Some(map_max);
+        cont_opts.temperature = opts.temperature;
+        cont_opts.system = opts.system.clone();
+        cont_opts.shape = ResponseShape::Text;
+        cont_opts.think = opts.think;
+
+        let outcome = generate_continuable(generator, &shard_prompt, &cont_opts).await?;
+        total_continuations += outcome.continuations;
+
+        // Append this shard's digest and, if needed, drop oldest.
+        scratchpad.push_str(&format!(
+            "\n— shard {}/{} digest —\n{}",
+            i + 1, shards.len(), outcome.text.trim(),
+        ));
+        if truncate_scratchpad(&mut scratchpad, opts.scratchpad_budget) {
+            truncations += 1;
+        }
+    }
+
+    // Reduce pass. Budget check first — if the scratchpad is still too
+    // big for the reduce prompt we fail loud with numbers.
+    let reduce_p = reduce_prompt(&scratchpad);
+    let budget = BudgetOpts {
+        system: opts.system.as_deref(),
+        max_tokens: Some(reduce_max as usize),
+        safety_margin: Some(safety),
+        bypass: false,
+    };
+    assert_context_budget(&opts.model, &reduce_p, budget)
+        .map_err(|(c, over)| overflow_message(&opts.model, &c, over, safety))?;
+
+    let mut cont_opts = ContinuableOpts::new(&opts.model);
+    cont_opts.max_tokens = Some(reduce_max);
+    cont_opts.temperature = opts.temperature;
+    cont_opts.system = opts.system.clone();
+    cont_opts.shape = ResponseShape::Text;
+    cont_opts.think = opts.think;
+
+    let outcome = generate_continuable(generator, &reduce_p, &cont_opts).await?;
+    total_continuations += outcome.continuations;
+
+    Ok(TreeSplitResult {
+        response: outcome.text,
+        scratchpad,
+        shards_processed: shards.len(),
+        scratchpad_truncations: truncations,
+        total_continuations,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::continuation::ScriptedGenerator;
+
+    fn simple_map(shard: &str, scratchpad: &str) -> String {
+        format!("SCRATCHPAD:\n{scratchpad}\n---\nSHARD:\n{shard}\n---\nDIGEST:")
+    }
+
+    fn simple_reduce(scratchpad: &str) -> String {
+        format!("SCRATCHPAD:\n{scratchpad}\n---\nFINAL:")
+    }
+
+    #[tokio::test]
+    async fn tree_split_runs_map_then_reduce() {
+        // 3 shards → 3 map calls → 1 reduce call = 4 responses scripted.
+        let generator = ScriptedGenerator::new(vec![
+            Ok("digest-1".to_string()),
+            Ok("digest-2".to_string()),
+            Ok("digest-3".to_string()),
+            Ok("FINAL ANSWER".to_string()),
+        ]);
+        let shards: Vec<String> = ["a", "b", "c"].iter().map(|s| s.to_string()).collect();
+        let opts = TreeSplitOpts::new("qwen3:latest");
+        let map_fn: &MapPromptFn = &simple_map;
+        let reduce_fn: &ReducePromptFn = &simple_reduce;
+        let result = generate_tree_split(&generator, &shards, map_fn, reduce_fn, &opts)
+            .await
+            .unwrap();
+        assert_eq!(result.shards_processed, 3);
+        assert_eq!(result.response, "FINAL ANSWER");
+        assert_eq!(generator.call_count(), 4);
+        // Scratchpad must carry all three digests in order.
+        assert!(result.scratchpad.contains("digest-1"));
+        assert!(result.scratchpad.contains("digest-2"));
+        assert!(result.scratchpad.contains("digest-3"));
+    }
+
+    #[tokio::test]
+    async fn tree_split_reduce_prompt_sees_full_scratchpad() {
+        let generator = ScriptedGenerator::new(vec![
+            Ok("summary-A".to_string()),
+            Ok("summary-B".to_string()),
+            Ok("REDUCED".to_string()),
+        ]);
+        let shards = vec!["input-one".to_string(), "input-two".to_string()];
+        let opts = TreeSplitOpts::new("qwen3:latest");
+        let _ = generate_tree_split(&generator, &shards, &simple_map, &simple_reduce, &opts)
+            .await
+            .unwrap();
+        // Third call = reduce. Its prompt must include both digests.
+        let calls = generator.calls();
+        let reduce_prompt = &calls[2].prompt;
+        assert!(reduce_prompt.contains("summary-A"),
+            "reduce prompt must see first shard digest");
+        assert!(reduce_prompt.contains("summary-B"),
+            "reduce prompt must see second shard digest");
+    }
+
+    #[tokio::test]
+    async fn tree_split_loud_fails_on_shard_overflow() {
+        let generator = ScriptedGenerator::new(vec![Ok("digest".to_string())]);
+        // One gigantic shard — well over qwen3's 40K window even as a
+        // prompt. The budget check must reject before any generate call.
+        let shards = vec!["x".repeat(200_000)];
+        let opts = TreeSplitOpts::new("qwen3:latest");
+        let err = generate_tree_split(&generator, &shards, &simple_map, &simple_reduce, &opts)
+            .await
+            .expect_err("shard-sized overflow must be rejected");
+        assert!(err.contains("overflow"), "error should mention overflow: {err}");
+        assert_eq!(generator.call_count(), 0, "generate must not be called on overflow");
+    }
+
+    #[tokio::test]
+    async fn tree_split_truncates_scratchpad_when_over_budget() {
+        // Tight budget so each shard trips truncation. qwen3's 40K
+        // window is fine; the budget we care about is the scratchpad
+        // cap, not the model window.
+        let generator = ScriptedGenerator::new(vec![
+            Ok("A".repeat(2_000)),
+            Ok("B".repeat(2_000)),
+            Ok("C".repeat(2_000)),
+            Ok("D".repeat(2_000)),
+            Ok("FINAL".to_string()),
+        ]);
+        let shards: Vec<String> = (0..4).map(|i| format!("shard{i}")).collect();
+        let mut opts = TreeSplitOpts::new("qwen3:latest");
+        opts.scratchpad_budget = 1_000; // ~4000 chars — one digest barely fits
+        let result = generate_tree_split(&generator, &shards, &simple_map, &simple_reduce, &opts)
+            .await
+            .unwrap();
+        assert!(result.scratchpad_truncations > 0,
+            "tight budget must trigger truncation");
+        // Scratchpad should still fit roughly within the budget
+        // (post-truncation); the estimator uses chars/4 so the bound
+        // is ~budget*4 chars. Give some slack for the delimiter.
+        let scratchpad_tokens = ModelMatrix::estimate_tokens(&result.scratchpad);
+        assert!(scratchpad_tokens <= opts.scratchpad_budget * 2,
+            "scratchpad {} tokens vs budget {}", scratchpad_tokens, opts.scratchpad_budget);
+    }
+
+    #[tokio::test]
+    async fn tree_split_reports_continuations_from_map_and_reduce() {
+        // First shard: truncated-then-continued. Reduce: truncated-then-continued.
+        // 1 shard: 2 map calls (initial + continuation), then 2 reduce calls.
+        let generator = ScriptedGenerator::new(vec![
+            Ok("partial".to_string()),         // map shape=text, non-empty → complete on first pass
+            Ok("reduce-out".to_string()),
+        ]);
+        let shards = vec!["only".to_string()];
+        let opts = TreeSplitOpts::new("qwen3:latest");
+        let result = generate_tree_split(&generator, &shards, &simple_map, &simple_reduce, &opts)
+            .await
+            .unwrap();
+        // Text shape treats non-empty as complete → 0 continuations.
+        assert_eq!(result.total_continuations, 0);
+        assert_eq!(result.shards_processed, 1);
+    }
+
+    #[test]
+    fn truncate_scratchpad_noop_when_under_budget() {
+        let mut s = "\n— shard 1/1 digest —\nshort".to_string();
+        let truncated = truncate_scratchpad(&mut s, 1_000);
+        assert!(!truncated);
+        assert!(s.contains("short"));
+    }
+
+    #[test]
+    fn truncate_scratchpad_drops_oldest_first() {
+        let mut s = format!(
+            "\n— shard 1/3 digest —\n{}\n— shard 2/3 digest —\n{}\n— shard 3/3 digest —\nshort",
+            "x".repeat(4_000), // ~1000 tokens
+            "y".repeat(4_000), // ~1000 tokens
+        );
+        let truncated = truncate_scratchpad(&mut s, 500); // ~2000 chars
+        assert!(truncated);
+        assert!(!s.contains(&"x".repeat(4_000)),
+            "oldest digest should be dropped");
+        assert!(s.contains("short"),
+            "newest digest should survive");
+    }
+}