supercode/reduce/

rehydrate.rs

//! T12 — model-invocable rehydration/retrieval over the sidecar (SPEC.md
//! TR-1): the two agent intrinsics `expand_reduction` and `sidecar_search`.
//! "The missing half of A7": until this landed, only the USER could recover
//! reduced content mid-flight (C4 `/expand`); the model itself had no way to
//! ask for it back, which is exactly what capped how aggressive every other
//! reducer could safely be.
//!
//! # The two resolution sources
//!
//! Both functions here are pure resolvers — no filesystem I/O, no
//! [`crate::session::Session`] required — over TWO message slices:
//!
//! - `minted_view`: the messages the reductions in `log` were minted against
//!   (a live [`crate::agent::Agent`] passes `history[1..]`; offline callers
//!   pass a loaded `Session`'s `.messages`). Every `SidecarPtr` hash is
//!   verified against THIS slice, because this is the slice
//!   [`super::project_messages`] hashed when it created the reduction.
//! - `recorded`: optionally, the recorder's full-fidelity recorded messages
//!   (the sidecar reloaded from disk). **Defense in depth, since TR-12
//!   (SPEC.md D6/A7 supersession, `Agent::run_loop`):** for any session
//!   recorded under that gate — a recorder and a [`crate::reduce::ReductionPolicy`]
//!   both installed, which is what actually triggers minting a reduction over
//!   `history` in the first place — `Agent::cap_tool_output` is off, so
//!   `minted_view` (`history[1..]`) already holds the same full bytes as
//!   `recorded`, and every upgrade below is a provable no-op (`rc != minted`
//!   fails, `minted` returned unchanged). The path still matters for two
//!   cases where `history`/the sidecar genuinely can diverge: (1) a
//!   **legacy** sidecar recorded before this gate existed, whose reductions
//!   were minted from an already-`cap_tool_output`-capped `history` (`minted_view`'s
//!   copy is a capped prefix + an honest cap notice, and the ONLY place the
//!   full bytes still exist is the recorded copy); (2) a policy-without-recorder
//!   agent (gate off because nothing durable backs the full bytes) that later
//!   gains a recorder. In either case, when `recorded` is provided and its
//!   copy of an addressed message matches the full supersession key — same
//!   index, same role, same `tool_call_id` (present on BOTH sides; only tool
//!   results are ever capped, and the id is unique per call), and the minted
//!   copy is a cap-notice-bearing prefix of the recorded copy — the recorded
//!   bytes are returned instead. The `tool_call_id` component is what makes
//!   the key exact rather than heuristic: after `Agent::rewind_to` truncates
//!   history (the sidecar is append-only), a re-run command can produce a
//!   same-index, same-role tool result sharing the old run's entire kept
//!   prefix, but it always carries a fresh `tool_call_id`, so the
//!   old-timeline copy can never satisfy the key. Anything else falls back
//!   to the hash-verified minted copy, so a wrong-bytes substitution is
//!   structurally impossible: the result is always either the exact bytes
//!   the hash was minted from, or their verified same-call full-length
//!   superset.
//!
//! # No new reductions, no sentinel text
//!
//! This module **deliberately mints no new [`Reduction`] records and never
//! writes [`REDUCTION_SENTINEL`] text.** An oversized [`expand_reduction`]
//! result is just an ordinary tool result once the agent loop pushes it onto
//! history — the EXISTING [`super::project_messages`] A7 pass re-truncates
//! it (with a fresh, genuinely reversible stub, recorded in the log like any
//! other reduction) once it ages out of
//! `ReductionPolicy::protect_last_n_tool_results` on a later turn. That is
//! what SPEC.md TR-1 dev/05 ("expand results are reduction-eligible") tests,
//! and it is also why TR-1's "no leak-guard special case needed" holds:
//! nothing in this module ever produces sentinel-bearing text, so a session
//! that used these intrinsics exports through `export_session`'s existing,
//! unconditional leak guard (A11) unmodified. `byte_range` is the proactive
//! tool: a caller who slices a large reduction into sub-`ReductionPolicy`-
//! cap chunks never needs the safety net at all.
//!
//! Note that expanding does NOT remove the reduction from the log — the
//! stub stays in the projected view (unchanged), and the expanded content
//! arrives as a new tool result. That is correct and deliberate: the log
//! entry must survive so the stub keeps resolving (for a later re-expand,
//! for `sidecar_search`, and for C4's offline tooling); contrast
//! [`super::invert_one`], which really does splice the original back into a
//! view and therefore removes the entry.
//!
//! [`REDUCTION_SENTINEL`]: super::REDUCTION_SENTINEL

use serde::{Deserialize, Serialize};

use super::stub::Kind;
use super::{
    char_boundary_floor, resolve_image_part, resolve_original_content, resolve_tool_input_value,
    resolve_turns_range, Reduction, ReductionKind, ReductionLog,
};
use crate::error::{Error, Result};
use crate::message::ChatMessage;

/// The result of a successful [`expand_reduction`] call.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExpandOutcome {
    /// The resolved (optionally range-sliced) original content — exactly
    /// what was asked for, byte for byte. This never truncates further on
    /// its own; see the module doc comment for why an oversized ask is left
    /// to the ordinary A7 pass instead, once this content lands in history.
    pub content: String,
    /// Total byte length of the FULL original content behind the requested
    /// id, before any `byte_range` slicing — lets a caller judge whether (and
    /// how) to ask for a narrower range next time.
    pub total_bytes: usize,
    /// The effective `[start, end)` byte range `content` was sliced to, when
    /// the caller asked for one (clamped to `total_bytes` and to char
    /// boundaries). `None` for a whole-content expand.
    pub range: Option<(usize, usize)>,
}

/// Resolve the `expand_reduction(reduction_id, byte_range?)` agent intrinsic
/// (SPEC.md TR-1 dev/01): the exact original bytes behind reduction `id` in
/// `log`, resolved against `minted_view` (hash-verified) with `recorded`
/// preferred for cap-diverged content — see the module doc comment for the
/// two-source contract. With `byte_range = Some((start, end))`, just that
/// `[start, end)` slice (end clamped to `total_bytes`, char-boundary-safe).
///
/// Errors, all model-recoverable:
/// - unknown `id` → names every currently-valid id (mirrors C4's `/expand`
///   error style);
/// - reversed range (`start > end`) or `start` beyond the original's total
///   bytes → names the expected `[start, end)` form and the true
///   `total_bytes`, rather than ever silently returning empty or full
///   content the caller didn't ask for.
pub fn expand_reduction(
    log: &ReductionLog,
    minted_view: &[ChatMessage],
    recorded: Option<&[ChatMessage]>,
    id: &str,
    byte_range: Option<(usize, usize)>,
) -> Result<ExpandOutcome> {
    let r = find_reduction(log, id)?;
    let text = resolve_text(r, minted_view, recorded)?;
    let total_bytes = text.len();
    let range = match byte_range {
        Some((s, e)) => {
            if s > e {
                return Err(Error::Other(format!(
                    "expand_reduction: reversed byte_range [{s}, {e}) — expected [start, end) \
                     with start <= end; the original is {total_bytes} bytes"
                )));
            }
            if s > total_bytes {
                return Err(Error::Other(format!(
                    "expand_reduction: byte_range start {s} is beyond the original's \
                     {total_bytes} bytes — expected [start, end) with start <= {total_bytes}"
                )));
            }
            let cs = char_boundary_floor(&text, s);
            let ce = char_boundary_floor(&text, e.min(total_bytes)).max(cs);
            Some((cs, ce))
        }
        None => None,
    };
    let (start, end) = range.unwrap_or((0, total_bytes));
    Ok(ExpandOutcome {
        content: text[start..end].to_string(),
        total_bytes,
        range,
    })
}

/// Total byte length of the original content behind reduction `id` — what
/// [`ExpandOutcome::total_bytes`] would report — without slicing anything.
/// Used by the agent's argument-validation error path so a malformed
/// `byte_range` error can name the true size the caller is ranging over.
pub fn reduction_total_bytes(
    log: &ReductionLog,
    minted_view: &[ChatMessage],
    recorded: Option<&[ChatMessage]>,
    id: &str,
) -> Result<usize> {
    let r = find_reduction(log, id)?;
    Ok(resolve_text(r, minted_view, recorded)?.len())
}

/// One match [`sidecar_search`] found.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SidecarSearchMatch {
    /// The reduction whose hidden content this match was found in — pass
    /// this straight to [`expand_reduction`] to see more of it.
    pub reduction_id: String,
    /// The stub `<kind>` token (SPEC.md D2/C2 grammar), e.g. `"tool-output"`.
    /// Owned (rather than `&'static str`, though [`Kind::as_str`] always
    /// hands back one) so this type round-trips through
    /// `serde_json::from_str` — a derived `Deserialize` for a `&'static str`
    /// field would need the deserializer's whole input to live for
    /// `'static`, which a freshly-parsed tool-result string never does.
    pub kind: String,
    /// A short window of text around the match — not the whole hidden span.
    pub snippet: String,
}

/// The complete result of a [`sidecar_search`] call. Bounded by construction
/// (SPEC.md TR-1 fix pass): at most [`MAX_MATCHES`] snippets, each at most
/// [`SNIPPET_MAX_BYTES`], and the whole serialized form at most
/// [`MAX_RESULT_BYTES`] — a broad query over megabytes of hidden content can
/// never blow the result back up to the size the reductions saved, and the
/// truncation is honest, structured JSON (never a mid-structure byte chop).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SidecarSearchResult {
    /// The matches kept (first [`MAX_MATCHES`] found, then byte-capped).
    pub matches: Vec<SidecarSearchMatch>,
    /// How many matches the query REALLY had, including ones dropped by the
    /// caps — `truncated && total_matches > matches.len()` tells the model
    /// to narrow its query.
    pub total_matches: usize,
    /// True when any match was dropped by [`MAX_MATCHES`]/[`MAX_RESULT_BYTES`].
    pub truncated: bool,
    /// Reductions in the log whose content could not currently be resolved
    /// (e.g. their address no longer exists after `Agent::rewind_to`). They
    /// were skipped, not fatal — one stale log entry never disables search
    /// over the rest.
    pub unresolvable: usize,
}

/// Bytes of context kept on each side of a match for [`SidecarSearchMatch::snippet`].
const SNIPPET_RADIUS: usize = 80;

/// Hard cap on the byte length of one [`SidecarSearchMatch::snippet`] (a
/// regex like `z.*` can match almost an entire hidden span; the snippet must
/// stay a snippet).
const SNIPPET_MAX_BYTES: usize = 200;

/// Hard cap on how many matches a single [`sidecar_search`] returns.
const MAX_MATCHES: usize = 50;

/// Hard cap on the serialized byte length of a [`SidecarSearchResult`].
const MAX_RESULT_BYTES: usize = 65_536;

/// Resolve the `sidecar_search(query)` agent intrinsic (SPEC.md TR-1
/// dev/04): substring/regex search over content CURRENTLY reduced out of the
/// view — every [`Reduction`] in `log`, restricted to its [`hidden_span`] so
/// a still-visible portion (e.g. `ToolOutputTruncated`'s kept prefix) is
/// never matched. "The same string visible in the live view is not
/// double-reported" is upheld entirely from the log's own records — this
/// still never inspects the live view: for most kinds the hidden span is a
/// pure function of the reduction itself, and for
/// [`ReductionKind::DuplicateOutput`] (TR-2, whose content is byte-identical
/// to a canonical instance that is usually still fully visible) visibility
/// is decided by whether any OTHER log record reduces the canonical's
/// address — no per-message record there and no enclosing `TurnsCleared`
/// range means the canonical is fully visible, so the duplicate's content is
/// not hidden and search skips it ([`hidden_span`] returns `None`). See the
/// module doc comment for the `minted_view`/`recorded` two-source contract.
///
/// An empty (or all-whitespace) `query` is an error, not a match-everything
/// wildcard: the empty pattern compiles as a regex that matches at every
/// position, which is never what a caller meant and used to make the result
/// size explode.
///
/// `query` is tried as a case-insensitive regex first; a query that fails to
/// compile as one (e.g. literal text with an unbalanced `[`/`(`, common in
/// file paths or code) falls back to a plain case-insensitive substring
/// search, so both "search for this exact snippet" and "search with a
/// pattern" work without the caller ever needing to escape anything.
pub fn sidecar_search(
    log: &ReductionLog,
    minted_view: &[ChatMessage],
    recorded: Option<&[ChatMessage]>,
    query: &str,
) -> Result<SidecarSearchResult> {
    if query.trim().is_empty() {
        return Err(Error::Other(
            "sidecar_search: `query` must be a non-empty substring or regex".to_string(),
        ));
    }
    let regex = regex::RegexBuilder::new(query)
        .case_insensitive(true)
        .build()
        .ok();
    let lower_query = query.to_ascii_lowercase();

    let mut matches = Vec::new();
    let mut total_matches = 0usize;
    let mut unresolvable = 0usize;
    for r in &log.reductions {
        // Skip (and count) anything unresolvable rather than aborting the
        // whole search — after a rewind, one stale log entry must not
        // disable the intrinsic for every other reduction.
        let Ok(text) = resolve_text(r, minted_view, recorded) else {
            unresolvable += 1;
            continue;
        };
        let Some((hs, he)) = hidden_span(r, &text, log) else {
            // ImageRedacted (not a meaningful text-search target), or a
            // DuplicateOutput whose canonical is still fully visible (the
            // model can already see these exact bytes in the live view).
            continue;
        };
        let hidden = &text[hs..he];
        let kind = Kind::from(&r.kind).as_str().to_string();

        // `to_ascii_lowercase` (unlike `to_lowercase`) never changes byte
        // length, so match indices stay valid against `hidden` unchanged —
        // needed since the substring fallback path locates matches in the
        // lowercased copy but slices snippets out of the original.
        let positions: Vec<(usize, usize)> = match &regex {
            Some(re) => re.find_iter(hidden).map(|m| (m.start(), m.end())).collect(),
            None => hidden
                .to_ascii_lowercase()
                .match_indices(&lower_query)
                .map(|(i, m)| (i, i + m.len()))
                .collect(),
        };

        for (start, end) in positions {
            total_matches += 1;
            if matches.len() < MAX_MATCHES {
                matches.push(SidecarSearchMatch {
                    reduction_id: r.id.clone(),
                    kind: kind.clone(),
                    snippet: snippet_around(hidden, start, end),
                });
            }
        }
    }

    let mut result = SidecarSearchResult {
        truncated: total_matches > matches.len(),
        matches,
        total_matches,
        unresolvable,
    };
    // Final serialized-size cap: drop trailing matches (valid JSON with an
    // honest `truncated` flag, never a mid-structure byte chop) until the
    // whole result fits. With the per-snippet and match-count caps above
    // this loop almost never runs, but it makes the bound unconditional.
    while serialized_len(&result) > MAX_RESULT_BYTES && !result.matches.is_empty() {
        result.matches.pop();
        result.truncated = true;
    }
    Ok(result)
}

fn serialized_len(result: &SidecarSearchResult) -> usize {
    serde_json::to_string(result).map(|s| s.len()).unwrap_or(0)
}

/// Look up a reduction by id in `log`, erroring with a valid-id hint
/// (mirrors `cli/src/main.rs`'s `/expand` error style) when it isn't there.
fn find_reduction<'a>(log: &'a ReductionLog, id: &str) -> Result<&'a Reduction> {
    log.reductions.iter().find(|r| r.id == id).ok_or_else(|| {
        let valid: Vec<&str> = log.reductions.iter().map(|r| r.id.as_str()).collect();
        Error::Other(format!(
            "expand_reduction: no reduction with id `{id}` — valid ids: {}",
            if valid.is_empty() {
                "(none)".to_string()
            } else {
                valid.join(", ")
            }
        ))
    })
}

/// Substitute `recorded`'s copy of the message at `index` for the
/// already-hash-verified `minted` content — but ONLY when the full
/// supersession key matches: same `index`, same role, same `tool_call_id`
/// (both sides must carry one — only tool results are ever
/// `cap_tool_output`-capped, and the id is unique per call), and `minted` is
/// a cap-notice-bearing prefix of the recorded copy (see
/// [`crate::agent::CAP_NOTICE_MARKER`]).
///
/// `tool_call_id` is what makes the key exact rather than heuristic: after
/// `Agent::rewind_to` truncates history while the append-only sidecar keeps
/// the old timeline, a re-run command can land a tool result at the SAME
/// index with the SAME role whose output shares the entire kept prefix with
/// the old run — but it always carries a NEW `tool_call_id`, so the
/// old-timeline recorded copy can never satisfy the key. Identical content,
/// a missing id on either side, role mismatch, or any unrelated divergence
/// all fall back to `minted` — never a silent wrong-bytes substitution.
fn prefer_recorded(
    minted: String,
    minted_msg: &ChatMessage,
    index: usize,
    recorded: Option<&[ChatMessage]>,
) -> String {
    let Some(rec) = recorded else { return minted };
    let Some(msg) = rec.get(index) else {
        return minted;
    };
    if msg.role != minted_msg.role {
        return minted;
    }
    let (Some(minted_id), Some(recorded_id)) = (
        minted_msg.tool_call_id.as_deref(),
        msg.tool_call_id.as_deref(),
    ) else {
        return minted; // Only tool results are ever capped; both must carry an id.
    };
    if minted_id != recorded_id {
        return minted;
    }
    let Some(rc) = msg.content.as_deref() else {
        return minted;
    };
    if rc != minted && capped_prefix_of(&minted, rc) {
        rc.to_string()
    } else {
        minted
    }
}

/// Is `minted` a `cap_tool_output`-capped copy of `full`? True iff `minted`
/// carries the cap-notice marker and everything before that marker is a
/// proper prefix of `full` — the exact construction `cap_tool_output`
/// performs (kept prefix + notice), verified byte-for-byte against the
/// candidate full copy.
fn capped_prefix_of(minted: &str, full: &str) -> bool {
    let Some(pos) = minted.rfind(crate::agent::CAP_NOTICE_MARKER) else {
        return false;
    };
    full.len() > pos && full.as_bytes().starts_with(&minted.as_bytes()[..pos])
}

/// The full text form of a reduction's ORIGINAL content: hash-verified
/// against `minted_view` (the same resolve primitives `invert`/`invert_one`
/// use, A6), then upgraded per-message to `recorded`'s full bytes where the
/// minted copy is a verified capped prefix ([`prefer_recorded`]) — rendered
/// to a single string for every kind so [`expand_reduction`]/
/// [`sidecar_search`] can treat them uniformly.
///
/// [`ReductionKind::DuplicateOutput`] (TR-2) resolves through its OWN address
/// exactly like [`ReductionKind::ToolOutputTruncated`]/[`ReductionKind::FileReadElided`]
/// — never by chasing `canonical`. `minted_view` (the agent's own `history`,
/// per the module doc comment) always retains the full original bytes at
/// every index regardless of what any given turn's PROJECTED view showed, so
/// self-resolution works unconditionally, including when the canonical
/// instance has ITSELF since been truncated or cleared (dev/04) — that only
/// ever changes what sits at the canonical's own address, never this one.
///
/// [`ReductionKind::OutputNormalized`] (T30/TR-4) likewise resolves through
/// [`resolve_original_content`] — which, for this kind, means the RAW
/// pre-normalization capture (ANSI/CR redraws and all), never the
/// normalized/rendered text the live view shows: the sidecar only ever
/// stores the raw bytes (A3), so byte-exact restore falls out of the exact
/// same self-addressed pattern every other kind uses, no special-casing
/// needed here.
fn resolve_text(
    r: &Reduction,
    minted_view: &[ChatMessage],
    recorded: Option<&[ChatMessage]>,
) -> Result<String> {
    match &r.kind {
        ReductionKind::ToolOutputTruncated { .. }
        | ReductionKind::FileReadElided { .. }
        | ReductionKind::OutputNormalized { .. }
        | ReductionKind::FileReadDiffed { .. }
        | ReductionKind::DuplicateOutput { .. }
        | ReductionKind::Superseded { .. } => {
            let minted = resolve_original_content(&r.ptr, minted_view)?;
            // Indexing is safe: resolve_original_content just verified the
            // address (and role) against this very slice.
            let minted_msg = &minted_view[r.ptr.addr.index];
            Ok(prefer_recorded(
                minted,
                minted_msg,
                r.ptr.addr.index,
                recorded,
            ))
        }
        ReductionKind::ImageRedacted { part_index } => {
            // `cap_tool_output` never touches `content_parts`, so the minted
            // copy IS the full copy here — no recorded upgrade needed.
            let part = resolve_image_part(&r.ptr, *part_index, minted_view)?;
            // The redacted content part's original `image_url.url` (a
            // `data:` URL) IS the original bytes for expand purposes; fall
            // back to the part's raw JSON if the shape is ever unexpected.
            Ok(part
                .get("image_url")
                .and_then(|iu| iu.get("url"))
                .and_then(|u| u.as_str())
                .map(str::to_string)
                .unwrap_or_else(|| part.to_string()))
        }
        ReductionKind::TurnsCleared { first, last, .. } => {
            let msgs = resolve_turns_range(&r.ptr, *first, *last, minted_view)?;
            let enriched: Vec<ChatMessage> = msgs
                .into_iter()
                .enumerate()
                .map(|(offset, mut m)| {
                    if let Some(content) = m.content.take() {
                        let upgraded = prefer_recorded(content, &m, first + offset, recorded);
                        m.content = Some(upgraded);
                    }
                    m
                })
                .collect();
            Ok(render_turns(&enriched))
        }
        ReductionKind::ToolInputElided { call_id, field, .. } => {
            // `cap_tool_output` only ever caps `Role::Tool` RESULT content,
            // never a `Role::Assistant` tool_call's `arguments` — so there is
            // no minted/recorded divergence to bridge here (the minted copy
            // IS the full copy), the same reasoning `ImageRedacted` uses.
            resolve_tool_input_value(&r.ptr, call_id, field, minted_view)
        }
    }
}

/// Render a resolved `TurnsCleared` message range as readable text for
/// `expand_reduction`/`sidecar_search` — one role-labeled block per message,
/// carrying EVERYTHING the cleared messages held: text content, multimodal
/// `content_parts` (as their JSON), tool-result attribution
/// (`name`/`tool_call_id`), and every tool call's id, name, and full
/// arguments. Tool-call arguments matter most: content that exists ONLY
/// there (a `write_file` call's file body, a `bash` command line) would
/// otherwise be neither searchable nor expandable, and rescue-scenario
/// transcripts are full of exactly that.
fn render_turns(msgs: &[ChatMessage]) -> String {
    let mut out = String::new();
    for m in msgs {
        out.push_str(&format!("--- {:?}", m.role));
        if let Some(name) = &m.name {
            out.push_str(&format!(" name={name}"));
        }
        if let Some(id) = &m.tool_call_id {
            out.push_str(&format!(" tool_call_id={id}"));
        }
        out.push_str(" ---\n");
        if let Some(c) = &m.content {
            out.push_str(c);
            out.push('\n');
        }
        if let Some(parts) = &m.content_parts {
            for part in parts {
                out.push_str(&serde_json::to_string(part).unwrap_or_default());
                out.push('\n');
            }
        }
        for call in m.tool_calls() {
            out.push_str(&format!(
                "[tool call {} {}: {}]\n",
                call.id, call.function.name, call.function.arguments
            ));
        }
    }
    out
}

/// The byte span of `resolve_text(r, ..)`'s output that is CURRENTLY HIDDEN
/// from the live (reduced) view — what [`sidecar_search`] is allowed to
/// match against. [`ReductionKind::ToolOutputTruncated`]'s kept prefix
/// (`ptr.span`'s first element) is still visible in the view, so only the
/// remainder counts as hidden; every other kind's `ptr.span` is `None`
/// ("whole content removed", per [`super::SidecarPtr::span`]'s doc comment),
/// so the whole resolved text is hidden. `None` return means "not
/// searchable": [`ReductionKind::ImageRedacted`] (a `data:` URL's base64
/// payload is not a meaningful text-search target), and a
/// [`ReductionKind::DuplicateOutput`] whose byte-identical canonical
/// instance is still fully visible in the view — decided from `log` itself
/// ([`canonical_is_reduced`]), never by inspecting the live view. When the
/// canonical IS itself reduced (any kind, including sitting inside a
/// `TurnsCleared` range), the duplicate's whole content counts as hidden;
/// deliberately conservative for a `ToolOutputTruncated` canonical whose
/// kept prefix is still partially visible.
///
/// [`ReductionKind::OutputNormalized`] resolves to the RAW pre-normalization
/// bytes (ANSI codes and all, per [`resolve_text`]) — none of which are
/// literally present in the live view (which shows the normalized text
/// instead), so — like `FileReadElided`/`FileReadDiffed`/`TurnsCleared` — the
/// whole resolved text counts as hidden, not just a suffix.
///
/// [`ReductionKind::Superseded`] (TR-6) is, unconditionally, likewise fully
/// hidden — UNLIKE `DuplicateOutput`, its content is never required to be
/// byte-identical to its successor (`by`), so there is no "the same bytes
/// are already visible elsewhere" case to special-case away: whatever this
/// reduction hides is genuinely gone from the live view, full stop.
fn hidden_span(r: &Reduction, text: &str, log: &ReductionLog) -> Option<(usize, usize)> {
    match &r.kind {
        ReductionKind::ImageRedacted { .. } => None,
        ReductionKind::ToolOutputTruncated { .. } => {
            let kept = r.ptr.span.map(|(kept, _total)| kept).unwrap_or(0);
            let start = char_boundary_floor(text, kept.min(text.len()));
            Some((start, text.len()))
        }
        ReductionKind::DuplicateOutput { canonical, .. } => {
            if canonical_is_reduced(canonical.index, r, log) {
                Some((0, text.len()))
            } else {
                None // Canonical fully visible: these bytes are already in view.
            }
        }
        ReductionKind::FileReadElided { .. }
        | ReductionKind::FileReadDiffed { .. }
        | ReductionKind::OutputNormalized { .. }
        | ReductionKind::TurnsCleared { .. }
        | ReductionKind::ToolInputElided { .. }
        | ReductionKind::Superseded { .. } => Some((0, text.len())),
    }
}

/// Is the message at `canonical_index` reduced (its full content NOT
/// visible in the live view) according to `log`'s own records? True when any
/// record other than `this` either addresses that index directly (a
/// per-message reduction of any kind) or covers it with a `TurnsCleared`
/// range. Pure function of the log — the live view is never consulted.
fn canonical_is_reduced(canonical_index: usize, this: &Reduction, log: &ReductionLog) -> bool {
    log.reductions.iter().any(|other| {
        if other.id == this.id {
            return false;
        }
        match other.kind {
            ReductionKind::TurnsCleared { first, last, .. } => {
                canonical_index >= first && canonical_index <= last
            }
            _ => other.ptr.addr.index == canonical_index,
        }
    })
}

/// A char-boundary-safe window of [`SNIPPET_RADIUS`] bytes on each side of
/// `[start, end)` within `text`, hard-capped at [`SNIPPET_MAX_BYTES`] (a
/// huge regex match must not smuggle the whole hidden span back out through
/// its own snippet).
fn snippet_around(text: &str, start: usize, end: usize) -> String {
    let lo = char_boundary_floor(text, start.saturating_sub(SNIPPET_RADIUS));
    let hi_target = (end + SNIPPET_RADIUS).min(text.len());
    let mut hi = hi_target;
    while hi < text.len() && !text.is_char_boundary(hi) {
        hi += 1;
    }
    let window = &text[lo..hi.min(text.len())];
    let cap = char_boundary_floor(window, SNIPPET_MAX_BYTES);
    window[..cap].to_string()
}

// ---------------------------------------------------------------------------
// P4c (COMPOSABLE-HARNESS-DESIGN.md §5.2 "P4" core NEW-significant item,
// §1.10 "mid-session model switch", dep 8): reasoning-artifact filtering for
// cross-model handoff. §1.13 names THIS FILE as dep 8's home ("cross-model
// switches route through reasoning-artifact filtering (`reduce/rehydrate.rs`
// — catalog §5 dep 8)") — co-located with `expand_reduction`/`sidecar_search`
// because all three are the sidecar/cross-format-safety-relevant plumbing
// obligation 10 (model routing) and priority 2 (emulate-to-continue) share.
// ---------------------------------------------------------------------------

/// `ChatMessage::metadata` keys that carry a source model's private
/// reasoning/thinking payload — populated today by `Session`'s foreign-
/// format importers:
///
/// - Claude Code / Codex legacy singular fields (`session.rs`'s
///   `push_claude_assistant`/Codex `reasoning` `response_item` handling):
///   `"thinking"`/`"thinking_signature"`/`"redacted_thinking"`/
///   `"reasoning"`/`"reasoning_content"`/`"reasoning_encrypted"`.
/// - `"thinking_blocks"` — the Claude Code importer's exact per-block replay
///   list (`session.rs:3475-3480`, `push_claude_assistant`): every
///   `thinking`/`redacted_thinking` content block preserved SEPARATELY, in
///   order, each with its own signature/data, as a serialized JSON array.
///   REVIEW FINDING (P4c dep 8, MEDIUM, proven): the Claude Code EXPORTER
///   (`session.rs`'s `to_claude_code_jsonl`, ~5654-5676) PREFERS this key
///   over the legacy singular fields whenever present — so leaving it out of
///   this list let a full signed chain-of-thought survive `switch_model`
///   untouched and get re-emitted, re-attributed to model-B, on the very
///   next Claude Code export. Added here to close that hole.
/// - `"pi_thought_signature"` — pi's per-`toolCall`-block `thoughtSignature`
///   (Google-provider reasoning-continuity token, `session.rs:4248-4249`
///   import / `session.rs:7418-7419` export as `pi_assistant_content_value`
///   re-emits it onto every `toolCall` block, independent of whether any
///   `thinking`/`thinking_blocks` key is even present on the message).
///   Audited in alongside the fix above: like `redacted_thinking`, its
///   payload is opaque/encrypted rather than literal text, but this crate
///   already treats "opaque encrypted reasoning artifact" as reasoning-
///   bearing for `redacted_thinking` — `pi_thought_signature` is the same
///   class of thing (Google's opaque encoded reasoning trace tied to a tool
///   call), just pi-namespaced (`docs/interop/research/pi-fields.md:161`
///   groups it under "provider replay signatures" alongside
///   `thinking_signature`). Deliberately NOT added: `pi_text_signature`
///   (`session.rs:4219-4224`/`4271-4272`, OpenAI Responses replay-continuity
///   id for a `text` block whose content is already fully exposed via
///   `msg.content` — pi-fields.md's own per-field note calls it "replay-
///   continuity residue", not a reasoning payload) and `pi_thinking_redacted`
///   (`session.rs:4267-4269`, a bare boolean flag with no payload of its
///   own — and inert regardless, since `pi_assistant_content_value` only
///   ever reads it from inside the `if let Some(thinking) = ...` arm gated
///   on the now-stripped `"thinking"` key, so it can never reach an export
///   on its own). Stripping either would be over-stripping non-reasoning
///   metadata for no leak-closing benefit.
///
/// `metadata` itself is never serialized onto the wire (`ChatMessage`'s
/// custom `Serialize` impl omits it — see `message.rs`), so this list is a
/// DEFENSE-IN-DEPTH filter, not the primary leak-prevention mechanism: the
/// primary one is that `metadata` never reaches a provider request at all,
/// regardless of this function. What this filter actually guarantees is the
/// OBSERVABLE contract dep 8 asks for — a post-switch inspection of
/// `history` (the in-memory session state, sidecar exports, `/export`, a
/// future translator emitting this session under another harness's format)
/// never shows model-A's reasoning attributed to a conversation now being
/// driven by model-B.
pub const REASONING_METADATA_KEYS: &[&str] = &[
    "thinking",
    "thinking_signature",
    "redacted_thinking",
    "reasoning",
    "reasoning_content",
    "reasoning_encrypted",
    "thinking_blocks",
    "pi_thought_signature",
];

/// `content_parts` block `"type"` values that carry a reasoning payload as
/// model-VISIBLE content (as opposed to the metadata-only keys above) —
/// e.g. a future/foreign provider that echoes `{"type":"thinking",...}` or
/// `{"type":"reasoning",...}` blocks back into a message's content array
/// for continuation. None of supercode's own `content_parts` constructors
/// (`ChatMessage::user_with_images`/`tool_result_with_image`) ever produce
/// these types today, so this branch is defensive breadth against future/
/// foreign content rather than something exercised by supercode's own
/// native loop yet.
pub const REASONING_CONTENT_PART_TYPES: &[&str] = &["thinking", "reasoning", "redacted_thinking"];

/// Mid-session model switch (§1.10, dep 8): strip every reasoning artifact
/// out of `history` in place — both the metadata keys
/// ([`REASONING_METADATA_KEYS`]) and any `content_parts` blocks whose
/// `"type"` is in [`REASONING_CONTENT_PART_TYPES`] — so model-A's reasoning
/// never reaches model-B's context on the next request built from this
/// history. Returns the count of MESSAGES actually touched (had at least
/// one metadata key removed and/or at least one content part removed) —
/// `Agent::switch_model` records this in the persisted `model_change`
/// entry (`ModelChangeRecord::reasoning_artifacts_filtered`).
///
/// Pure and total: never panics, a message with nothing to filter is left
/// byte-identical (down to `content_parts` ordering of the parts that
/// survive), and calling this with nothing to filter (the common case —
/// supercode's own live loop never populates these keys) is a cheap no-op
/// scan, not a rebuild.
pub fn filter_reasoning_artifacts(history: &mut [ChatMessage]) -> usize {
    let mut touched = 0usize;
    for msg in history.iter_mut() {
        let mut this_touched = false;
        for key in REASONING_METADATA_KEYS {
            if msg.metadata.remove(*key).is_some() {
                this_touched = true;
            }
        }
        if let Some(parts) = msg.content_parts.as_mut() {
            let before = parts.len();
            parts.retain(|p| {
                p.get("type")
                    .and_then(|t| t.as_str())
                    .map(|t| !REASONING_CONTENT_PART_TYPES.contains(&t))
                    .unwrap_or(true)
            });
            if parts.len() != before {
                this_touched = true;
            }
        }
        if this_touched {
            touched += 1;
        }
    }
    touched
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::reduce::{content_hash, make_id, stub, MessageAddr, SidecarPtr};
    use crate::Role;

    fn tool_output_reduction(
        id_ordinal: usize,
        addr_index: usize,
        original: &str,
        kept: usize,
    ) -> Reduction {
        let hash = content_hash(original.as_bytes());
        let id = make_id(id_ordinal, &hash);
        let summary = format!(
            "t output truncated {}B, kept {kept}B — full output in session sidecar",
            original.len()
        );
        Reduction {
            id: id.clone(),
            kind: ReductionKind::ToolOutputTruncated {
                original_bytes: original.len(),
                kept_bytes: kept,
            },
            ptr: SidecarPtr {
                addr: MessageAddr {
                    index: addr_index,
                    role: Role::Tool,
                },
                span: Some((kept, original.len())),
                content_hash: hash,
            },
            placeholder: stub::format(stub::Kind::ToolOutput, &id, &summary),
        }
    }

    fn one_reduction_log(original: &str, kept: usize) -> (Vec<ChatMessage>, ReductionLog) {
        let msg = ChatMessage::tool_result("c1", "bash", original.to_string());
        let r = tool_output_reduction(0, 0, original, kept);
        (
            vec![msg],
            ReductionLog {
                reductions: vec![r],
                expanded: vec![],
                read_log: vec![],
                attribution: None,
            },
        )
    }

    #[test]
    fn expand_returns_exact_bytes_and_ranges() {
        let original = "0123456789abcdefghij";
        let (minted, log) = one_reduction_log(original, 10);
        let id = log.reductions[0].id.clone();

        let whole = expand_reduction(&log, &minted, None, &id, None).unwrap();
        assert_eq!(whole.content, original);
        assert_eq!(whole.total_bytes, original.len());
        assert_eq!(whole.range, None);

        let ranged = expand_reduction(&log, &minted, None, &id, Some((10, 15))).unwrap();
        assert_eq!(ranged.content, "abcde");
        assert_eq!(ranged.range, Some((10, 15)));
        assert_eq!(ranged.total_bytes, original.len());

        // End beyond the total clamps (the model may not know the exact
        // size); start beyond it errors — see the validation test below.
        let clamped = expand_reduction(&log, &minted, None, &id, Some((15, 10_000))).unwrap();
        assert_eq!(clamped.content, &original[15..]);
        assert_eq!(clamped.range, Some((15, original.len())));
    }

    #[test]
    fn expand_rejects_reversed_and_out_of_bounds_ranges() {
        let original = "0123456789";
        let (minted, log) = one_reduction_log(original, 4);
        let id = log.reductions[0].id.clone();

        let reversed = expand_reduction(&log, &minted, None, &id, Some((100, 5))).unwrap_err();
        let msg = reversed.to_string();
        assert!(msg.contains("reversed"), "{msg}");
        assert!(msg.contains("[start, end)"), "{msg}");
        assert!(msg.contains("10 bytes"), "{msg}");

        let oob = expand_reduction(&log, &minted, None, &id, Some((11, 20))).unwrap_err();
        let msg = oob.to_string();
        assert!(msg.contains("beyond"), "{msg}");
        assert!(msg.contains("10"), "{msg}");
    }

    #[test]
    fn expand_unknown_id_errors_with_valid_id_hint() {
        let log = ReductionLog {
            reductions: vec![tool_output_reduction(0, 0, "abc", 1)],
            expanded: vec![],
            read_log: vec![],
            attribution: None,
        };
        let err = expand_reduction(&log, &[], None, "r9999-dead", None).unwrap_err();
        assert!(err.to_string().contains("r9999-dead"));
        assert!(err.to_string().contains(&log.reductions[0].id));
    }

    #[test]
    fn recorded_copy_supersedes_a_capped_minted_copy() {
        // The recorded (sidecar) copy holds the full bytes; the minted
        // (history) copy is cap_tool_output's prefix + notice, and the
        // reduction hash was minted from THAT copy.
        let full = "F".repeat(1000);
        let capped = format!(
            "{}{}{} bytes total, showing first 600; full output in session sidecar]",
            &full[..600],
            crate::agent::CAP_NOTICE_MARKER,
            1000
        );
        let (minted, log) = one_reduction_log(&capped, 100);
        let id = log.reductions[0].id.clone();
        let recorded = vec![ChatMessage::tool_result("c1", "bash", full.clone())];

        // With the recorded source: the FULL bytes, not the capped copy.
        let out = expand_reduction(&log, &minted, Some(&recorded), &id, None).unwrap();
        assert_eq!(out.content, full);
        assert_eq!(out.total_bytes, 1000);

        // Without it: the verified minted copy (whose embedded notice is
        // honest about the true total) — never an error, never wrong bytes.
        let out = expand_reduction(&log, &minted, None, &id, None).unwrap();
        assert_eq!(out.content, capped);

        // A recorded copy that is NOT a capped superset (index drift after
        // a rewind) is ignored in favor of the verified minted copy.
        let drifted = vec![ChatMessage::tool_result("cX", "bash", "unrelated")];
        let out = expand_reduction(&log, &minted, Some(&drifted), &id, None).unwrap();
        assert_eq!(out.content, capped);
    }

    #[test]
    fn recorded_copy_with_different_tool_call_id_never_supersedes() {
        // The rewind-and-re-run drift scenario: `rewind_to` truncated
        // history (the sidecar is append-only), then the model re-ran a
        // command at the SAME history index whose output shares the ENTIRE
        // kept prefix with the pre-rewind run but diverges after. Same
        // index, same role, and the old-timeline full copy really does
        // extend the new capped copy's kept prefix — the only component of
        // the supersession key telling the two apart is the per-call-unique
        // `tool_call_id`.
        let old_full = format!("{}OLD-TIMELINE-TAIL", "S".repeat(600));
        let capped = format!(
            "{}{}{} bytes total, showing first 600; full output in session sidecar]",
            &old_full[..600], // the shared kept prefix
            crate::agent::CAP_NOTICE_MARKER,
            900
        );

        // The minted (post-rewind) tool result carries the NEW call id; the
        // recorded (old-timeline) copy at the same index carries the OLD one.
        let minted = vec![ChatMessage::tool_result("c-new", "bash", capped.clone())];
        let r = tool_output_reduction(0, 0, &capped, 100);
        let id = r.id.clone();
        let log = ReductionLog {
            reductions: vec![r],
            expanded: vec![],
            read_log: vec![],
            attribution: None,
        };
        let recorded = vec![ChatMessage::tool_result("c-old", "bash", old_full.clone())];

        // The old timeline's tail must NEVER come back as this run's hidden
        // content: the id mismatch fails the key, falling back to the
        // verified minted copy.
        let out = expand_reduction(&log, &minted, Some(&recorded), &id, None).unwrap();
        assert_eq!(
            out.content, capped,
            "an old-timeline copy with a different tool_call_id must never supersede"
        );
        assert!(!out.content.contains("OLD-TIMELINE-TAIL"));

        // Control: the identical setup with MATCHING ids does supersede —
        // proving the assertion above fails exactly when the id check is
        // removed, not for some incidental reason.
        let same_id = vec![ChatMessage::tool_result("c-new", "bash", old_full.clone())];
        let out = expand_reduction(&log, &minted, Some(&same_id), &id, None).unwrap();
        assert_eq!(out.content, old_full);
    }

    #[test]
    fn search_finds_hidden_but_not_kept_prefix() {
        let original = "KEPTPREFIX-needle-is-here-in-the-hidden-tail";
        let kept = "KEPTPREFIX".len();
        let (minted, log) = one_reduction_log(original, kept);
        let id = log.reductions[0].id.clone();

        let hits = sidecar_search(&log, &minted, None, "needle").unwrap();
        assert_eq!(hits.matches.len(), 1);
        assert_eq!(hits.total_matches, 1);
        assert!(!hits.truncated);
        assert_eq!(hits.unresolvable, 0);
        assert_eq!(hits.matches[0].reduction_id, id);
        assert_eq!(hits.matches[0].kind, "tool-output");
        assert!(hits.matches[0].snippet.contains("needle"));

        // A query only present in the still-visible kept prefix is not
        // reported at all.
        let none = sidecar_search(&log, &minted, None, "KEPTPREFIX").unwrap();
        assert!(
            none.matches.is_empty() && none.total_matches == 0,
            "kept prefix must not be searchable: {none:?}"
        );
    }

    #[test]
    fn search_regex_and_literal_fallback() {
        let original = "error: file not found at /a/b/c.rs [line 42";
        let (minted, log) = one_reduction_log(original, 0);

        // Regex query.
        let hits = sidecar_search(&log, &minted, None, r"line \d+").unwrap();
        assert_eq!(hits.matches.len(), 1);

        // Literal text with an unbalanced `[`: fails to compile as a regex
        // (unterminated character class), falls back to plain substring.
        let hits2 = sidecar_search(&log, &minted, None, "c.rs [line").unwrap();
        assert_eq!(hits2.matches.len(), 1);
        assert!(hits2.matches[0].snippet.contains("c.rs [line"));
    }

    #[test]
    fn search_rejects_empty_query_and_caps_result_size() {
        let original = "z".repeat(50_000);
        let (minted, log) = one_reduction_log(&original, 0);

        // Empty/whitespace queries are errors, not match-everything.
        assert!(sidecar_search(&log, &minted, None, "").is_err());
        assert!(sidecar_search(&log, &minted, None, "   ").is_err());

        // 50,000 single-char matches: capped at MAX_MATCHES, honestly
        // flagged, with the true total reported and the serialized form
        // bounded and valid JSON.
        let hits = sidecar_search(&log, &minted, None, "z").unwrap();
        assert_eq!(hits.matches.len(), MAX_MATCHES);
        assert_eq!(hits.total_matches, 50_000);
        assert!(hits.truncated);
        let serialized = serde_json::to_string(&hits).unwrap();
        assert!(
            serialized.len() <= MAX_RESULT_BYTES,
            "serialized result must stay under the byte cap: {} bytes",
            serialized.len()
        );
        let reparsed: SidecarSearchResult = serde_json::from_str(&serialized).unwrap();
        assert_eq!(reparsed, hits);

        // A pathological regex matching (nearly) the whole span: the
        // snippet stays a snippet.
        let hits = sidecar_search(&log, &minted, None, "z.*").unwrap();
        assert!(hits.matches[0].snippet.len() <= SNIPPET_MAX_BYTES);
        assert!(serialized_len(&hits) <= MAX_RESULT_BYTES);
    }

    #[test]
    fn search_skips_unresolvable_reductions_instead_of_aborting() {
        let original = "the needle is in here";
        let (minted, log) = one_reduction_log(original, 0);
        // A second reduction whose address does not exist in the view (the
        // post-rewind shape).
        let mut log = log;
        log.reductions.push(tool_output_reduction(1, 99, "gone", 0));

        let hits = sidecar_search(&log, &minted, None, "needle").unwrap();
        assert_eq!(hits.matches.len(), 1, "{hits:?}");
        assert_eq!(hits.unresolvable, 1);
    }

    #[test]
    fn turns_cleared_render_carries_tool_call_payloads() {
        use crate::message::{FunctionCall, ToolCall};

        let call = ChatMessage {
            role: Role::Assistant,
            content: None,
            content_parts: None,
            tool_calls: Some(vec![ToolCall {
                id: "w1".to_string(),
                kind: "function".to_string(),
                function: FunctionCall {
                    name: "write_file".to_string(),
                    arguments: serde_json::json!({
                        "path": "notes.txt",
                        "content": "ARGS-ONLY-PAYLOAD-77"
                    })
                    .to_string(),
                },
            }]),
            tool_call_id: None,
            name: None,
            metadata: Default::default(),
        };
        let result = ChatMessage::tool_result("w1", "write_file", "ok");
        let rendered = render_turns(&[call, result]);
        assert!(rendered.contains("ARGS-ONLY-PAYLOAD-77"), "{rendered}");
        assert!(rendered.contains("write_file"), "{rendered}");
        assert!(rendered.contains("w1"), "{rendered}");
        assert!(rendered.contains("tool_call_id=w1"), "{rendered}");
    }

    // ---- P4c: filter_reasoning_artifacts (S1.10 dep 8) --------------------

    #[test]
    fn filter_reasoning_artifacts_strips_every_documented_metadata_key() {
        let mut msg = ChatMessage::assistant("the answer");
        for key in REASONING_METADATA_KEYS {
            msg.metadata
                .insert(key.to_string(), "secret-cot".to_string());
        }
        msg.metadata
            .insert("unrelated".to_string(), "kept".to_string());
        let mut history = vec![msg];
        let touched = filter_reasoning_artifacts(&mut history);
        assert_eq!(touched, 1);
        for key in REASONING_METADATA_KEYS {
            assert!(
                !history[0].metadata.contains_key(*key),
                "{key} should have been stripped"
            );
        }
        assert_eq!(
            history[0].metadata.get("unrelated").map(String::as_str),
            Some("kept"),
            "non-reasoning metadata must survive untouched"
        );
    }

    #[test]
    fn filter_reasoning_artifacts_strips_reasoning_content_parts_keeps_others() {
        let mut msg = ChatMessage::assistant("");
        msg.content_parts = Some(vec![
            serde_json::json!({"type": "text", "text": "visible"}),
            serde_json::json!({"type": "thinking", "text": "model-A's private CoT"}),
            serde_json::json!({"type": "image_url", "image_url": {"url": "data:image/png;base64,x"}}),
        ]);
        let mut history = vec![msg];
        let touched = filter_reasoning_artifacts(&mut history);
        assert_eq!(touched, 1);
        let parts = history[0].content_parts.as_ref().unwrap();
        assert_eq!(parts.len(), 2, "{parts:?}");
        assert!(parts.iter().all(|p| p["type"] != "thinking"), "{parts:?}");
        assert!(parts.iter().any(|p| p["type"] == "text"), "{parts:?}");
        assert!(parts.iter().any(|p| p["type"] == "image_url"), "{parts:?}");
    }

    /// Default/happy path: a message with nothing to filter is left
    /// byte-identical — not touched, not counted.
    #[test]
    fn filter_reasoning_artifacts_leaves_clean_messages_untouched() {
        let mut history = vec![
            ChatMessage::user("hello"),
            ChatMessage::assistant("hi there"),
            ChatMessage::tool_result("call_1", "read_file", "file contents"),
        ];
        let before = history.clone();
        let touched = filter_reasoning_artifacts(&mut history);
        assert_eq!(touched, 0);
        for (a, b) in history.iter().zip(before.iter()) {
            assert_eq!(a.content, b.content);
            assert_eq!(a.metadata, b.metadata);
        }
    }

    /// Only messages that actually carry a reasoning artifact count toward
    /// the returned total — the boundary between "filtered" and "just
    /// passed through".
    #[test]
    fn filter_reasoning_artifacts_only_counts_actually_touched_messages() {
        let mut clean = ChatMessage::assistant("clean turn");
        let mut dirty = ChatMessage::assistant("dirty turn");
        dirty
            .metadata
            .insert("thinking".to_string(), "secret".to_string());
        let mut history = vec![clean.clone(), dirty];
        let touched = filter_reasoning_artifacts(&mut history);
        assert_eq!(touched, 1);
        clean.metadata.clear();
        assert_eq!(history[0].content, clean.content);
        assert!(!history[1].metadata.contains_key("thinking"));
    }

    /// P4c-review (MEDIUM, proven): `"thinking_blocks"` — the Claude Code
    /// importer's per-block replay list the CC exporter PREFERS over the
    /// legacy singular fields (`session.rs:3475-3480` import,
    /// `session.rs:5654-5676` export) — and `"pi_thought_signature"` — pi's
    /// per-`toolCall` Google reasoning-continuity token
    /// (`session.rs:4248-4249` import, `session.rs:7418-7419` export,
    /// re-emitted independent of any `thinking`/`thinking_blocks` key —
    /// were the two additional reasoning-bearing metadata keys the audit
    /// found missing from the strip list. Explicit, standalone proof (on
    /// top of the loop over the whole list above) that both are actually
    /// removed, not just declared.
    #[test]
    fn filter_reasoning_artifacts_strips_thinking_blocks_and_pi_thought_signature() {
        assert!(REASONING_METADATA_KEYS.contains(&"thinking_blocks"));
        assert!(REASONING_METADATA_KEYS.contains(&"pi_thought_signature"));

        let mut msg = ChatMessage::assistant("here's my answer");
        msg.metadata.insert(
            "thinking_blocks".to_string(),
            serde_json::json!([{"type": "thinking", "thinking": "model-A's private CoT", "signature": "sig-abc"}]).to_string(),
        );
        msg.metadata.insert(
            "pi_thought_signature".to_string(),
            "google-opaque-reasoning-continuity-token".to_string(),
        );
        let mut history = vec![msg];
        let touched = filter_reasoning_artifacts(&mut history);
        assert_eq!(touched, 1);
        assert!(!history[0].metadata.contains_key("thinking_blocks"));
        assert!(!history[0].metadata.contains_key("pi_thought_signature"));
    }

    /// P4c-review audit: `"pi_text_signature"` (OpenAI Responses replay-
    /// continuity id for a `text` block whose content is already exposed
    /// via `msg.content` — not a reasoning payload) and
    /// `"pi_thinking_redacted"` (a bare boolean flag, no payload, and inert
    /// on export anyway since `pi_assistant_content_value` only reads it
    /// from inside the `if let Some(thinking) = ...` arm gated on the
    /// already-stripped `"thinking"` key) are deliberately NOT reasoning-
    /// bearing — the filter must not over-strip them.
    #[test]
    fn filter_reasoning_artifacts_does_not_over_strip_non_reasoning_pi_keys() {
        assert!(!REASONING_METADATA_KEYS.contains(&"pi_text_signature"));
        assert!(!REASONING_METADATA_KEYS.contains(&"pi_thinking_redacted"));

        let mut msg = ChatMessage::assistant("here's my answer");
        msg.metadata
            .insert("pi_text_signature".to_string(), "replay-id-123".to_string());
        msg.metadata
            .insert("pi_thinking_redacted".to_string(), "true".to_string());
        let mut history = vec![msg];
        filter_reasoning_artifacts(&mut history);
        assert_eq!(
            history[0]
                .metadata
                .get("pi_text_signature")
                .map(String::as_str),
            Some("replay-id-123")
        );
        assert_eq!(
            history[0]
                .metadata
                .get("pi_thinking_redacted")
                .map(String::as_str),
            Some("true")
        );
    }
}