supercode_harness/

audit.rs

//! Corpus coverage audit.
//!
//! Walks a directory of session logs, parses every line through the typed
//! [`crate::schema`], and reports — with real counts — exactly what we model,
//! what we model-but-drop on normalization, and what we don't model at all.
//! This is the machine that turns "what's missing?" into an enumerated answer
//! rather than a guess.
//!
//! ```no_run
//! use std::path::Path;
//! use supercode_harness::audit::{audit_dir, Corpus};
//!
//! let report = audit_dir(Path::new("/home/me/.codex/sessions"), Corpus::Codex, None);
//! report.print();
//! ```

use std::collections::BTreeMap;
use std::path::{Path, PathBuf};

use serde_json::Value;

use crate::schema::{claude_code::*, codex::*, raw_block_tag, ContentBlock};
use crate::session::{opencode_file_image_part, pi_content_has_unknown_image_shape};

/// Which corpus a directory holds.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Corpus {
    /// `~/.claude/projects`
    ClaudeCode,
    /// `~/.codex/sessions`
    Codex,
    /// `~/.pi/agent/sessions`
    Pi,
    /// `~/.local/share/opencode` (envelope-form fixtures/corpus — see
    /// `docs/interop/opencode-pi-spec.md` §1.2/§4.1).
    OpenCode,
    /// `~/.grok/sessions` (`chat_history.jsonl` files only; companion
    /// `updates.jsonl` streams are live protocol events, not transcripts).
    Grok,
    /// `~/.gemini/tmp/<project>/chats` Gemini CLI JSONL transcripts.
    Gemini,
    /// Goose's `sessions/sessions.db` native store.
    Goose,
}

/// How a given discriminant is handled by the loader.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Coverage {
    /// Parsed and normalized into the canonical conversation.
    Normalized,
    /// PARITY-12/PARITY-13 (P012/P013): parsed and its content/provenance IS
    /// captured by the loader — into `Session.meta` (Codex `session_meta`'s
    /// id/cwd/model/base_instructions, `turn_context`'s model), replay
    /// semantics (`thread_rolled_back` actually removes the rolled-back
    /// turns, `exited_review_mode`'s `review_output.overall_explanation`
    /// becomes a message with `review_output.findings` AND
    /// `overall_correctness`/`overall_confidence_score` (N4) captured onto
    /// that message's metadata (D4/N4), `thread_goal_updated`'s
    /// `goal.objective` becomes a message with `goal.status`/
    /// `goal.tokenBudget` captured onto that message's metadata too (D4),
    /// `agent_message` can become a message when its text has no
    /// `response_item` twin) — just not 1:1 into a `ChatMessage` the way
    /// `Normalized` records are.
    /// This is the "retained, not dropped" bucket the two audits were
    /// missing: before this variant existed, every one of these landed in
    /// `Dropped` indistinguishably from truly-inert UI noise (`token_count`,
    /// `task_started`, …), which is exactly the false "silently dropped"
    /// signal both items' dev/03 ACs flag.
    ///
    /// `response_item/reasoning` also belongs here (D5, PARITY-12): its
    /// `summary` text, raw `content` chain-of-thought text when non-null
    /// (N2 — previously dropped despite this very label claiming otherwise;
    /// `content` is `null` on the vast majority of real turns, so this was
    /// easy to miss until fixtures carried the key at all), and the
    /// `encrypted_content` presence flag (N1: only a genuinely non-null
    /// value counts — `serde_json` returns `Some(&Value::Null)` for a
    /// present-but-null key, which is what EVERY real rollout's reasoning
    /// item carries per upstream `codex-rs/protocol/src/models.rs:970-983`,
    /// so a naive `.is_some()` false-flagged every reasoning item as
    /// "encrypted" on real data) are captured by `Session::from_codex_str`
    /// onto the *next* assistant `ChatMessage`'s metadata (`reasoning`/
    /// `reasoning_content`/`reasoning_encrypted`) — see `audit_codex_item`'s
    /// `Reasoning` arm. When no following assistant turn exists to attach to
    /// (a non-assistant item interrupts, or the reasoning is dangling at
    /// EOF — an aborted-turn shape, N3), it is flushed as its own synthesized
    /// `[reasoning] (turn ended without a reply)` message instead of being
    /// silently discarded, so this label stays honest for that shape too.
    /// It isn't `Normalized` (no canonical "reasoning" `ChatMessage`), but it
    /// is provably not a blind drop either.
    ///
    /// DISCLOSURE: every metadata key mentioned above (`review_findings`,
    /// `review_overall_correctness`, `review_overall_confidence_score`,
    /// `goal_status`, `goal_token_budget`, `reasoning`, `reasoning_content`,
    /// `reasoning_encrypted`) is LOADER-CAPTURE ONLY. It survives the
    /// verbatim Codex→Codex diagonal (raw bytes, untouched) and reads back
    /// out of the native supercode format, but it does NOT survive a
    /// cross-format writer or the `--session-id` re-serialized diagonal:
    /// `ChatMessage.metadata` is never serialized (`message.rs:50-55`) and no
    /// writer reads it back out. Don't misread `Retained` here as
    /// cross-format-durable — it means "captured in-process", not "written
    /// back out".
    Retained,
    /// Parsed and understood, but intentionally dropped (e.g. `token_count`,
    /// `task_started`/`task_complete`, UI echoes of content already captured
    /// elsewhere as `Normalized`/`Retained`). See `event_msg_coverage`'s doc
    /// comment for the few real, currently-unrecovered exceptions (D1) —
    /// e.g. `patch_apply_end`'s `changes[path].unified_diff` — where
    /// `Dropped` means genuine, asserted content loss, not "duplicated
    /// elsewhere".
    Dropped,
    /// Not modeled at all — falls into an `Unknown` typed bucket.
    Unmodeled,
}

impl Coverage {
    fn symbol(self) -> &'static str {
        match self {
            Coverage::Normalized => "✅ normalized",
            Coverage::Retained => "◆ retained  ",
            Coverage::Dropped => "➖ dropped   ",
            Coverage::Unmodeled => "❌ UNMODELED ",
        }
    }
}

/// A tally for one discriminant value.
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct Tally {
    /// How many times it occurred.
    pub count: u64,
    /// Field keys seen in `extra` (fields we didn't model), with counts.
    pub unmodeled_fields: BTreeMap<String, u64>,
}

/// The full audit result.
#[derive(Debug, Default)]
#[non_exhaustive]
pub struct Report {
    /// Which corpus this is.
    pub corpus: Option<&'static str>,
    /// Files scanned.
    pub files: u64,
    /// Lines parsed.
    pub lines: u64,
    /// Lines that failed to deserialize even into the typed schema.
    pub parse_errors: u64,
    /// Per record/payload discriminant: (coverage, tally). Keyed by a readable
    /// path like `response_item/custom_tool_call`.
    pub records: BTreeMap<String, (Coverage, Tally)>,
    /// Content block discriminants seen, with counts SPLIT by the coverage
    /// each instance actually got (N1, Fable-5 review). Keyed by
    /// `(tag, coverage)` rather than `tag` alone: D5 made `image` coverage
    /// PER-INSTANCE (a `base64`/`url` source is `Normalized`, a Files-API/
    /// `file` source is `Dropped`), so a single `tag -> (Coverage, count)`
    /// entry — last-write-wins on `Coverage` — silently collapsed a mixed
    /// corpus's genuinely-`Dropped` instances into whatever coverage the
    /// LAST-seen instance of that tag happened to have, over- or
    /// under-claiming fidelity depending on file order. Splitting the bucket
    /// keeps every instance's actual coverage and never collapses counts.
    pub blocks: BTreeMap<(String, Coverage), u64>,
    /// Tool names seen, with counts.
    pub tools: BTreeMap<String, u64>,
    /// Structural notes discovered while scanning (e.g. sidechain lines).
    pub notes: BTreeMap<String, u64>,
}

impl Report {
    fn bump(&mut self, key: String, cov: Coverage, extra: &crate::schema::ExtraFields) {
        let entry = self.records.entry(key).or_insert((cov, Tally::default()));
        entry.0 = cov;
        entry.1.count += 1;
        for k in extra.keys() {
            *entry.1.unmodeled_fields.entry(k.clone()).or_insert(0) += 1;
        }
    }

    fn bump_block(&mut self, block: &ContentBlock, raw: &Value) {
        let (tag, cov) = match block.tag() {
            Some(t) => (t.to_string(), block_coverage(block)),
            None => (
                raw_block_tag(raw).unwrap_or_else(|| "<no-type>".into()),
                Coverage::Unmodeled,
            ),
        };
        // N1: bucket on (tag, coverage), not tag alone — see the `blocks`
        // field doc. Each instance is counted under its OWN actual coverage
        // instead of one shared, last-write-wins `Coverage` per tag.
        *self.blocks.entry((tag, cov)).or_insert(0) += 1;
    }

    fn note(&mut self, key: &str) {
        *self.notes.entry(key.to_string()).or_insert(0) += 1;
    }

    /// Serialize the report as structured JSON (for CI/dashboards).
    pub fn to_json(&self) -> serde_json::Value {
        let cov = |c: Coverage| match c {
            Coverage::Normalized => "normalized",
            Coverage::Retained => "retained",
            Coverage::Dropped => "dropped",
            Coverage::Unmodeled => "unmodeled",
        };
        let records: serde_json::Map<String, serde_json::Value> = self
            .records
            .iter()
            .map(|(k, (c, t))| {
                (
                    k.clone(),
                    serde_json::json!({
                        "coverage": cov(*c),
                        "count": t.count,
                        "unmodeled_fields": t.unmodeled_fields.keys().collect::<Vec<_>>(),
                    }),
                )
            })
            .collect();
        // N1: a tag can now have MULTIPLE coverage buckets (e.g. `image` ->
        // Normalized:1, Dropped:1 on a mixed corpus), so each tag maps to a
        // list of `{coverage, count}` entries rather than a single one.
        let mut blocks_by_tag: BTreeMap<&str, Vec<serde_json::Value>> = BTreeMap::new();
        for ((tag, c), n) in &self.blocks {
            blocks_by_tag
                .entry(tag.as_str())
                .or_default()
                .push(serde_json::json!({"coverage": cov(*c), "count": n}));
        }
        let blocks: serde_json::Map<String, serde_json::Value> = blocks_by_tag
            .into_iter()
            .map(|(k, v)| (k.to_string(), serde_json::Value::Array(v)))
            .collect();
        serde_json::json!({
            "corpus": self.corpus,
            "files": self.files,
            "lines": self.lines,
            "parse_errors": self.parse_errors,
            "records": records,
            "blocks": blocks,
            "tools": self.tools,
            "notes": self.notes,
        })
    }

    /// Print a human-readable report to stdout.
    pub fn print(&self) {
        println!("# Coverage audit: {}", self.corpus.unwrap_or("?"));
        println!(
            "files={} lines={} parse_errors={}\n",
            self.files, self.lines, self.parse_errors
        );

        println!("## Records (discriminant → coverage, count, unmodeled fields)");
        for (key, (cov, tally)) in &self.records {
            print!("  {}  {:<40} {:>9}", cov.symbol(), key, tally.count);
            if !tally.unmodeled_fields.is_empty() {
                let mut fields: Vec<_> = tally.unmodeled_fields.keys().cloned().collect();
                fields.sort();
                print!("   unmodeled fields: {}", fields.join(", "));
            }
            println!();
        }

        if !self.blocks.is_empty() {
            println!("\n## Content blocks");
            // N1: one row per (tag, coverage) bucket — a tag with mixed
            // coverage (e.g. `image` seen both Normalized and Dropped) now
            // prints as two distinct, honestly-counted rows instead of one
            // row whose coverage was whichever instance was seen last.
            for ((tag, cov), count) in &self.blocks {
                println!("  {}  {:<28} {:>9}", cov.symbol(), tag, count);
            }
        }

        if !self.notes.is_empty() {
            println!("\n## Structural notes");
            for (k, v) in &self.notes {
                println!("  {k}: {v}");
            }
        }

        if !self.tools.is_empty() {
            println!("\n## Tools observed (top 30 by frequency)");
            let mut tools: Vec<_> = self.tools.iter().collect();
            tools.sort_by(|a, b| b.1.cmp(a.1));
            for (name, count) in tools.into_iter().take(30) {
                println!("  {count:>9}  {name}");
            }
        }

        println!("\n## Summary of gaps (UNMODELED or dropped, non-UI)");
        for (key, (cov, tally)) in &self.records {
            if *cov == Coverage::Unmodeled {
                println!("  ❌ {key} ({} occurrences) — not modeled", tally.count);
            }
        }
        for ((tag, cov), count) in &self.blocks {
            if *cov == Coverage::Unmodeled {
                println!("  ❌ content block `{tag}` ({count}) — not modeled");
            }
        }
    }
}

fn block_coverage(block: &ContentBlock) -> Coverage {
    match block {
        ContentBlock::Text { .. }
        | ContentBlock::InputText { .. }
        | ContentBlock::OutputText { .. }
        | ContentBlock::ToolUse { .. }
        | ContentBlock::ToolResult { .. } => Coverage::Normalized,
        // D5 (Fable-5 review, confirmed): `image` used to be blanket-marked
        // `Normalized` regardless of its `source` shape, but
        // `claude_image_block_to_part` (session.rs) only actually converts
        // `base64`/`url` sources into a replayable `content_parts` image —
        // anything else (a Files-API `{"source":{"type":"file",...}}`
        // reference, most commonly) is NOT carried through; the loader now
        // emits a bracketed marker so the record survives (see
        // `UNCONVERTIBLE_IMAGE_MARKER`), but the actual image content is
        // still lost, so this must not claim full fidelity. Codex's
        // `input_image` has no `source` sub-object (a bare, always-
        // convertible `image_url` string via `codex_extract_images`) and
        // `fallback` (folded into a text marker) are both still genuinely
        // `Normalized`.
        // N3 (Fable-5 review, ticket, fixed inline since it's the same
        // `Image{source}` inspection N1 already touches): a well-typed but
        // EMPTY `base64`/`url` source — e.g. `{"type":"base64","data":""}`
        // — used to blanket-audit as `Normalized` just like a genuinely
        // convertible one, but `claude_image_block_to_part` (session.rs)
        // treats it as UNCONVERTIBLE (its own non-empty `mime`/`data`/`url`
        // check returns `None`, same `UNCONVERTIBLE_IMAGE_MARKER` fallback
        // path as a Files-API reference) — audit and loader must agree.
        ContentBlock::Image { source } => image_source_coverage(source),
        ContentBlock::InputImage { .. } | ContentBlock::Fallback { .. } => Coverage::Normalized,
        // Provider-private reasoning: retained verbatim in
        // (skip-serialized) `ChatMessage` metadata (`push_claude_assistant`)
        // so a same-model continuation can replay it, but it has no slot in
        // the canonical replayable conversation itself — "understood, not
        // silently lost" rather than "normalized into the conversation".
        ContentBlock::Thinking { .. } | ContentBlock::RedactedThinking { .. } => Coverage::Dropped,
        ContentBlock::Unknown => Coverage::Unmodeled, // future blocks
    }
}

/// Score a Claude `image` block's `source` object — factored out of
/// `block_coverage`'s `Image` arm (D5/N3 discipline: `base64`/`url` with a
/// non-empty payload is `Normalized`, anything else is `Dropped`) so PARITY-11
/// can reuse the EXACT same test for an `image` block nested inside a
/// `tool_result`'s own `content` array, not just a top-level one.
fn image_source_coverage(source: &Value) -> Coverage {
    match source.get("type").and_then(Value::as_str) {
        Some("base64") => {
            let mime = source
                .get("media_type")
                .and_then(Value::as_str)
                .unwrap_or("");
            let data = source.get("data").and_then(Value::as_str).unwrap_or("");
            if mime.is_empty() || data.is_empty() {
                Coverage::Dropped
            } else {
                Coverage::Normalized
            }
        }
        Some("url") => {
            let url = source.get("url").and_then(Value::as_str).unwrap_or("");
            if url.is_empty() {
                Coverage::Dropped
            } else {
                Coverage::Normalized
            }
        }
        _ => Coverage::Dropped,
    }
}

/// PARITY-11 (nested images, skeptic-confirmed on a real session): a Claude
/// `tool_result` block's OWN `content` array can carry `image` blocks — the
/// everyday "Read a PNG / screenshot tool output" shape. `block_coverage`
/// blanket-labels the enclosing `tool_result` `Normalized` (true for its text
/// portion), which used to be the ONLY signal `audit` gave — so a session
/// whose `tool_result` held nothing but a dropped image still reported zero
/// `image` blocks and a clean `tool_result: Normalized` line, i.e. coverage
/// said "retained" while the loader silently dropped the bytes. This censuses
/// each nested `image` block individually, under its own `tool_result/image`
/// discriminant, scored with the SAME [`image_source_coverage`] test
/// `session.rs`'s `extract_tool_result_content` uses to decide whether it
/// actually captures the block into `content_parts` — so a genuinely
/// unconvertible nested image (Files-API reference, empty payload, …) shows
/// up here as `Dropped`, not folded invisibly into the outer `Normalized`
/// tally.
fn audit_nested_tool_result_images(content: &Value, report: &mut Report) {
    let Some(items) = content.as_array() else {
        return;
    };
    for item in items {
        if item.get("type").and_then(Value::as_str) != Some("image") {
            continue;
        }
        let cov = image_source_coverage(item.get("source").unwrap_or(&Value::Null));
        *report
            .blocks
            .entry(("tool_result/image".to_string(), cov))
            .or_insert(0) += 1;
    }
}

/// Audit a directory. `limit` caps the number of files scanned (None = all).
///
/// `Corpus::OpenCode` (PARITY-4) is special-cased: a real OpenCode data root
/// (`~/.local/share/opencode`) holds no `.jsonl` files at all — sessions live
/// in `opencode*.db` (current installs) or a JSON-file tree (legacy). When
/// [`crate::session::detect_opencode_storage_surface`] resolves `dir` to the
/// SQLite surface, this routes through
/// [`crate::session::opencode_sqlite_corpus_envelope_text`] (up to `limit`
/// SESSIONS, not files — `report.files` counts sessions scanned in that
/// case) instead of the `jsonl_files` walk below, so a real store actually
/// gets audited rather than silently reporting zero files/lines. A directory
/// with no detected SQLite surface (e.g. a fixture dir of committed
/// envelope-form `.jsonl` files, or a not-yet-implemented legacy JSON tree)
/// falls back to the original file-walk unchanged.
pub fn audit_dir(dir: &Path, corpus: Corpus, limit: Option<usize>) -> Report {
    let mut report = Report {
        corpus: Some(match corpus {
            Corpus::ClaudeCode => "claude-code",
            Corpus::Codex => "codex",
            Corpus::Pi => "pi",
            Corpus::OpenCode => "opencode",
            Corpus::Grok => "grok",
            Corpus::Gemini => "gemini",
            Corpus::Goose => "goose",
        }),
        ..Default::default()
    };

    if corpus == Corpus::OpenCode {
        if let Some((crate::session::OpenCodeStorageSurface::Sqlite, db_path)) =
            crate::session::detect_opencode_storage_surface(dir)
        {
            return audit_opencode_sqlite(&db_path, limit, report);
        }
    }
    if corpus == Corpus::Goose {
        return audit_goose(dir, limit, report);
    }

    let mut files = jsonl_files(dir);
    if corpus == Corpus::Grok {
        files.retain(|path| {
            path.file_name().and_then(|name| name.to_str()) == Some("chat_history.jsonl")
        });
    }
    let files = match limit {
        Some(n) => &files[..files.len().min(n)],
        None => &files[..],
    };

    for path in files {
        report.files += 1;
        let Ok(text) = std::fs::read_to_string(path) else {
            continue;
        };
        for line in text.lines().map(str::trim).filter(|l| !l.is_empty()) {
            report.lines += 1;
            match corpus {
                Corpus::Codex => audit_codex_line(line, &mut report),
                Corpus::ClaudeCode => audit_claude_line(line, &mut report),
                Corpus::Pi => audit_pi_line(line, &mut report),
                Corpus::OpenCode => audit_opencode_line(line, &mut report),
                Corpus::Grok => audit_grok_line(line, &mut report),
                Corpus::Gemini => audit_gemini_line(line, &mut report),
                Corpus::Goose => unreachable!("Goose is audited through its SQLite store"),
            }
        }
    }
    report
}

fn audit_goose(root: &Path, limit: Option<usize>, mut report: Report) -> Report {
    let catalog = crate::HarnessCatalog::new();
    let discovery = catalog.discover(&crate::DiscoveryQuery {
        harnesses: vec![crate::HarnessId::from(crate::HarnessId::GOOSE)],
        homes: crate::HarnessHomes {
            goose: root.to_path_buf(),
            ..crate::HarnessHomes::default()
        },
        limit,
        ..crate::DiscoveryQuery::default()
    });
    let descriptors = match discovery {
        Ok(descriptors) => descriptors,
        Err(error) => {
            report.note(&format!("Goose discovery failed: {error}"));
            return report;
        }
    };
    let extra = EMPTY_EXTRA.get_or_init(Default::default);
    for descriptor in descriptors {
        let session = match catalog.load(&descriptor.locator) {
            Ok(session) => session,
            Err(error) => {
                report.note(&format!(
                    "Goose session {} failed to load: {error}",
                    descriptor.locator.session_id
                ));
                continue;
            }
        };
        report.files += 1;
        for message in session.messages {
            report.lines += 1;
            report.bump(
                format!("message/{:?}", message.role).to_lowercase(),
                Coverage::Normalized,
                extra,
            );
            for call in message.tool_calls() {
                *report.tools.entry(call.function.name.clone()).or_insert(0) += 1;
            }
        }
    }
    report
}

/// The `Corpus::OpenCode` + SQLite branch of [`audit_dir`] (PARITY-4): reads
/// every session's `session`/`message`/`part`/`todo` records out of
/// `db_path` as envelope lines
/// ([`crate::session::opencode_sqlite_corpus_envelope_text`]) and scores each
/// one exactly like a line from a committed envelope-form fixture
/// (`audit_opencode_line` — same classifier, same coverage buckets, so a
/// SQLite corpus and a JSON-tree/fixture corpus are held to the identical
/// bar). `report.files` counts SESSIONS scanned (the natural unit for a
/// single-DB corpus), not `.jsonl` files. A store that fails to open (bad
/// path, corrupt DB, wrong schema) does not panic or silently return an
/// empty report — the failure is recorded in `report.notes` so it is visible
/// in both the text and `--json` renderings.
fn audit_opencode_sqlite(db_path: &Path, limit: Option<usize>, mut report: Report) -> Report {
    match crate::session::opencode_sqlite_corpus_envelope_text(db_path, limit) {
        Ok(text) => {
            for line in text.lines().map(str::trim).filter(|l| !l.is_empty()) {
                report.lines += 1;
                // A `session` envelope line is one-per-scanned-session — use
                // it to derive `report.files` (sessions, not `.jsonl` files)
                // without a second SQL pass.
                if let Ok(v) = serde_json::from_str::<Value>(line) {
                    if v.get("key")
                        .and_then(Value::as_array)
                        .and_then(|k| k.first())
                        .and_then(Value::as_str)
                        == Some("session")
                    {
                        report.files += 1;
                    }
                }
                audit_opencode_line(line, &mut report);
            }
        }
        Err(e) => {
            report.note(&format!("opencode_sqlite_error: {e}"));
        }
    }
    report
}

fn audit_codex_line(line: &str, report: &mut Report) {
    let raw: Value = match serde_json::from_str(line) {
        Ok(v) => v,
        Err(_) => {
            report.parse_errors += 1;
            return;
        }
    };
    let parsed: Result<CodexLine, _> = serde_json::from_str(line);
    let Ok(parsed) = parsed else {
        report.parse_errors += 1;
        return;
    };

    match &parsed.record {
        CodexRecord::Unknown => {
            let tag = raw
                .get("type")
                .and_then(Value::as_str)
                .unwrap_or("<no-type>");
            report.bump(
                format!("<line>/{tag}"),
                Coverage::Unmodeled,
                &Default::default(),
            );
        }
        CodexRecord::ResponseItem { payload } => audit_codex_item(payload, &raw, report),
        CodexRecord::EventMsg { payload } => {
            let sub = payload.kind.clone().unwrap_or_else(|| "?".into());
            report.bump(
                format!("event_msg/{sub}"),
                event_msg_coverage(&sub),
                &payload.extra,
            );
        }
        // PARITY-13 (P013): `session_meta` isn't discarded — `from_codex_str`
        // (via `capture_codex_session_meta`) threads its id/cwd/model/
        // base_instructions/lineage fields onto `Session.meta`, and the whole
        // record is kept verbatim in `meta.codex_headers` so a same-format
        // re-export (`to_codex_jsonl`) replays it byte-for-byte. `Dropped`
        // read as a silent, untracked loss; it's retained, just not folded
        // into a `ChatMessage`.
        CodexRecord::SessionMeta { payload } => {
            report.bump("session_meta".into(), Coverage::Retained, &payload.extra);
        }
        // Same reasoning as `SessionMeta` above: `turn_context`'s `model` is
        // threaded onto `Session.meta.model` (first occurrence) and the
        // record itself is kept verbatim in `meta.codex_headers` (P013).
        CodexRecord::TurnContext { payload } => {
            report.bump("turn_context".into(), Coverage::Retained, &payload.extra);
        }
        CodexRecord::Compacted { .. } => {
            // replacement_history now replaces prior turns on load.
            report.bump(
                "compacted".into(),
                Coverage::Normalized,
                &Default::default(),
            );
        }
    }
}

/// PARITY-12/PARITY-13 (P012/P013): `event_msg` coverage, mirroring EXACTLY
/// the subset of `payload.type` values `Session::from_codex_str` special-cases
/// (see its `Some("event_msg") if payload.get("type") == Some(...)` arms) —
/// keep these two lists in lockstep; a subtype added there without a match
/// here regresses to a false `Dropped` again.
///
/// - `agent_message`: real assistant narration with no `response_item`
///   counterpart becomes a message (the sole source of truth in some
///   collaboration/multi-agent sessions); a duplicate of an already-normalized
///   `response_item/message` is skipped as a no-op. Either way the loader
///   parses and acts on it — not a blind, untracked drop.
/// - `thread_rolled_back`: directly mutates the canonical conversation
///   (removes the rolled-back turns) — collaboration/undo provenance that's
///   applied, not discarded.
/// - `thread_goal_updated`: its `goal.objective` becomes a synthesized
///   system message when present; `goal.status`/`goal.tokenBudget` (when
///   present) are captured onto that message's metadata too (D4) —
///   `goal.tokensUsed`/`timeUsedSeconds`/timestamps are still real, minor
///   residue, not claimed as retained.
/// - `exited_review_mode`: its `review_output.overall_explanation` becomes a
///   synthesized assistant message; `review_output.findings` (verbatim JSON:
///   `title`/`body`/`confidence_score`/`priority`/`code_location`) AND the
///   review verdict itself, `overall_correctness`/`overall_confidence_score`
///   (N4 — previously neither captured nor disclosed, unlike the
///   `thread_goal_updated` arm above which already disclosed its own
///   residue), are captured onto that message's metadata too (D4/N4) — the
///   only place review-mode findings/verdict live.
///
/// `token_count`, `task_started`/`task_complete`, `user_message` (a
/// duplicate of the already-normalized `response_item/message[user]`),
/// `entered_review_mode` has no canonical chat turn, but PARITY-13's portable
/// Codex provenance envelope now retains its exact target/hint record across
/// every foreign-format hop, so it is `Retained` rather than an untracked
/// drop. Other UI-only echoes with no unique replayable content stay
/// `Dropped` honestly.
///
/// D1 correction — this used to also claim `exec_command_begin`/`end` and
/// `mcp_tool_call_begin`/`patch_apply_begin` were safe to drop because
/// "already captured via the paired `response_item/function_call*`". That
/// framing was FALSE for what those events would carry if they were ever
/// actually present: verified against upstream `openai/codex`'s
/// `codex-rs/rollout/src/policy.rs` `should_persist_event_msg`, all four of
/// `EventMsg::ExecCommandBegin`, `EventMsg::ExecCommandEnd`,
/// `EventMsg::McpToolCallBegin`, and `EventMsg::PatchApplyBegin` hit that
/// function's `=> false` arm — **codex never writes these event kinds to a
/// real rollout file at all.** So in a genuine `~/.codex/sessions` corpus
/// this isn't "content safely captured elsewhere"; it's a branch that is
/// simply never reached. `Dropped` below is defensive (a hand-edited or
/// legacy-schema file could still carry one, and the typed schema should
/// keep parsing it rather than falling into `Unmodeled`), not a claim that
/// real sessions lose this content on every turn.
///
/// `patch_apply_end` and `mcp_tool_call_end`, by contrast, ARE persisted by
/// real Codex (`should_persist_event_msg` `=> true` for both) — and here the
/// old "already captured" framing is mostly right but not entirely: their
/// short `stdout`/`result` text does duplicate the paired
/// `response_item/function_call_output` or
/// `response_item/custom_tool_call_output`. `patch_apply_end`'s
/// `changes[path]`'s `unified_diff` is NOT duplicated there — the paired
/// `function_call_output` only carries the apply summary text, never the
/// diff body — and the loader does not capture it, so this is genuine,
/// currently-real content loss on cross-format export. (N5: the diff body's
/// raw hunk TEXT does have a counterpart — the paired `response_item/
/// function_call.arguments` for the preceding `apply_patch` call carries the
/// same added/removed lines in its own `*** Begin Patch` format, since
/// that's literally what was applied. What's genuinely unique to
/// `unified_diff` and absent from `function_call.arguments` is its
/// standard-diff framing — the `--- a/<path>`/`+++ b/<path>`/`@@ …@@` header
/// lines `apply_patch`'s custom patch format never emits. The dev/02 test
/// below keys its residue assertion on those header lines specifically, not
/// on the shared hunk body, so it proves the part that's actually
/// unrecovered rather than merely re-finding text that was never at risk.)
/// `Dropped` is the honest label for it, not "already captured" — and
/// `parity12_cross_format_export_retains_tool_outputs_as_transcript_content`
/// (dev/02, `crates/cli/tests/codex_fidelity_cli.rs`) now asserts this
/// residue explicitly instead of staying silent about it.
fn event_msg_coverage(sub: &str) -> Coverage {
    match sub {
        "agent_message"
        | "thread_rolled_back"
        | "thread_goal_updated"
        | "entered_review_mode"
        | "exited_review_mode" => Coverage::Retained,
        _ => Coverage::Dropped,
    }
}

fn audit_codex_item(item: &ResponseItem, raw: &Value, report: &mut Report) {
    let raw_payload = raw.get("payload").cloned().unwrap_or(Value::Null);
    let cov = if item.is_normalized() {
        Coverage::Normalized
    } else if matches!(item, ResponseItem::Reasoning { .. }) {
        // D5/N1/N2/N3: `Session::from_codex_str` captures `summary` text,
        // the raw `content` chain-of-thought text when genuinely present
        // (N2), and a correctly-computed `encrypted_content` presence flag
        // (N1: only a non-null value counts, not merely a present-but-null
        // key) onto the NEXT assistant `ChatMessage`'s metadata
        // (`reasoning`/`reasoning_content`/`reasoning_encrypted`) — or, when
        // there is no following assistant turn to attach to, flushes it as
        // its own synthesized message instead of discarding it (N3). Not a
        // blind drop. The opaque `encrypted_content` blob itself isn't
        // replayed cross-model, so this is an honest `Retained`, not
        // `Normalized` (there's no 1:1 canonical "reasoning" `ChatMessage`).
        // See `Coverage::Retained`'s doc comment for the LOADER-CAPTURE-ONLY
        // disclosure that applies to all of this.
        Coverage::Retained
    } else {
        // custom_tool_call, web_search_call, tool_search_*, image_generation,
        // and any future Unknown — all not yet normalized.
        Coverage::Unmodeled
    };

    let tag = item.tag().map(str::to_string).unwrap_or_else(|| {
        raw_payload
            .get("type")
            .and_then(Value::as_str)
            .unwrap_or("<no-type>")
            .to_string()
    });

    match item {
        ResponseItem::Message {
            content,
            extra,
            role,
        } => {
            report.bump(format!("response_item/message[{role}]"), cov, extra);
            audit_blocks(content, &raw_payload, report);
        }
        ResponseItem::FunctionCall { name, extra, .. } => {
            *report.tools.entry(name.clone()).or_insert(0) += 1;
            report.bump("response_item/function_call".into(), cov, extra);
        }
        ResponseItem::FunctionCallOutput { extra, .. } => {
            report.bump("response_item/function_call_output".into(), cov, extra);
        }
        ResponseItem::CustomToolCall { name, extra, .. } => {
            if let Some(n) = name {
                *report.tools.entry(n.clone()).or_insert(0) += 1;
            }
            report.bump("response_item/custom_tool_call".into(), cov, extra);
        }
        other => {
            let extra = item_extra(other);
            report.bump(format!("response_item/{tag}"), cov, extra);
        }
    }
}

fn item_extra(item: &ResponseItem) -> &crate::schema::ExtraFields {
    match item {
        ResponseItem::CustomToolCallOutput { extra, .. }
        | ResponseItem::Reasoning { extra }
        | ResponseItem::WebSearchCall { extra }
        | ResponseItem::ToolSearchCall { extra }
        | ResponseItem::ToolSearchOutput { extra }
        | ResponseItem::ImageGenerationCall { extra } => extra,
        _ => EMPTY_EXTRA.get_or_init(Default::default),
    }
}

static EMPTY_EXTRA: std::sync::OnceLock<crate::schema::ExtraFields> = std::sync::OnceLock::new();

fn audit_claude_line(line: &str, report: &mut Report) {
    let raw: Value = match serde_json::from_str(line) {
        Ok(v) => v,
        Err(_) => {
            report.parse_errors += 1;
            return;
        }
    };
    let parsed: Result<ClaudeRecord, _> = serde_json::from_str(line);
    let Ok(parsed) = parsed else {
        report.parse_errors += 1;
        return;
    };

    match &parsed {
        ClaudeRecord::Unknown => {
            let tag = raw
                .get("type")
                .and_then(Value::as_str)
                .unwrap_or("<no-type>");
            report.bump(
                format!("<line>/{tag}"),
                Coverage::Unmodeled,
                &Default::default(),
            );
        }
        ClaudeRecord::User { message, meta } | ClaudeRecord::Assistant { message, meta } => {
            let role = match &parsed {
                ClaudeRecord::Assistant { .. } => "assistant",
                _ => "user",
            };
            report.bump(role.to_string(), Coverage::Normalized, &meta.extra);
            if meta.is_sidechain {
                report.note("sidechain (subagent) lines — flattened, not separated");
            }
            match &message.content {
                MessageContent::Text(_) => {
                    report.bump_block(
                        &ContentBlock::Text {
                            text: String::new(),
                        },
                        &Value::Null,
                    );
                }
                MessageContent::Blocks(blocks) => {
                    let raw_blocks = raw
                        .get("message")
                        .and_then(|m| m.get("content"))
                        .cloned()
                        .unwrap_or(Value::Null);
                    audit_blocks(blocks, &Value::Null, report);
                    let _ = raw_blocks;
                    // capture tool names
                    for b in blocks {
                        if let ContentBlock::ToolUse { name, .. } = b {
                            *report.tools.entry(name.clone()).or_insert(0) += 1;
                        }
                    }
                }
            }
        }
        ClaudeRecord::System { subtype, extra } => {
            let sub = subtype.clone().unwrap_or_else(|| "?".into());
            // Content-bearing system subtypes are now folded into the conversation.
            let cov = match sub.as_str() {
                "scheduled_task_fire" | "local_command" | "away_summary" => Coverage::Normalized,
                _ => Coverage::Dropped,
            };
            report.bump(format!("system/{sub}"), cov, extra);
        }
        other => {
            let tag = other.tag().unwrap_or("?");
            let cov = match tag {
                // Metadata/UI we deliberately skip.
                "permission-mode" | "mode" | "last-prompt" | "queue-operation" | "ai-title"
                | "pr-link" | "frame-link" | "agent-name" | "worktree-state" => Coverage::Dropped,
                // Content-bearing attachment subtypes are now folded into the
                // conversation (regenerable ones are still skipped).
                "attachment" => Coverage::Normalized,
                // PARITY-10: captured into `Session::meta.lineage` on load
                // (`capture_claude_meta` in `session.rs`) and re-emitted
                // verbatim by the Claude Code writer — no longer silently
                // dropped, even though (like `attachment`) it has no slot in
                // the OpenAI-shaped canonical message conversation itself.
                "fork-context-ref" => Coverage::Normalized,
                // These still carry real content/structure we don't yet use:
                // file-history-snapshot / file-history-delta (undo state),
                // started/result (subagent task lifecycle).
                _ => Coverage::Unmodeled,
            };
            report.bump(tag.to_string(), cov, record_extra(other));
        }
    }
}

fn record_extra(rec: &ClaudeRecord) -> &crate::schema::ExtraFields {
    match rec {
        ClaudeRecord::Attachment { extra }
        | ClaudeRecord::FileHistorySnapshot { extra }
        | ClaudeRecord::FileHistoryDelta { extra }
        | ClaudeRecord::AiTitle { extra }
        | ClaudeRecord::PermissionMode { extra }
        | ClaudeRecord::Mode { extra }
        | ClaudeRecord::LastPrompt { extra }
        | ClaudeRecord::QueueOperation { extra }
        | ClaudeRecord::PrLink { extra }
        | ClaudeRecord::FrameLink { extra }
        | ClaudeRecord::AgentName { extra }
        | ClaudeRecord::Started { extra }
        | ClaudeRecord::Result { extra }
        | ClaudeRecord::WorktreeState { extra }
        | ClaudeRecord::ForkContextRef { extra } => extra,
        _ => EMPTY_EXTRA.get_or_init(Default::default),
    }
}

fn audit_blocks(blocks: &[ContentBlock], raw_payload: &Value, report: &mut Report) {
    let raw_blocks = raw_payload.get("content").and_then(Value::as_array);
    for (i, b) in blocks.iter().enumerate() {
        let raw = raw_blocks
            .and_then(|arr| arr.get(i))
            .cloned()
            .unwrap_or(Value::Null);
        report.bump_block(b, &raw);
        // PARITY-11: census any `image` block nested inside this
        // `tool_result`'s own `content` array separately — see
        // `audit_nested_tool_result_images`'s doc comment.
        if let ContentBlock::ToolResult { content, .. } = b {
            audit_nested_tool_result_images(content, report);
        }
    }
}

/// Audit one line of a pi session file (`docs/interop/opencode-pi-spec.md`
/// §1.1/§4.1, `pi-fields.md`). Unlike the Claude/Codex auditors this walks
/// raw [`Value`]s rather than a typed `crate::schema` module — Wave A scopes
/// the typed-schema mirror to a later pass; the tally/Unknown-bucket
/// machinery this function drives is the same [`Report`] used everywhere
/// else, so the coverage guard test reads identically.
///
/// `message.role` is tallied as a **second-level discriminant** under its own
/// `message/…` keys, with an `message/UnknownRole:<role>` bucket for any role
/// outside pi's five modeled ones — pi's `message.role` is an OPEN,
/// extension-mergeable union (§1.1 S6), so a role the loader doesn't
/// recognize must surface here as a scored `Unmodeled` entry, not vanish.
///
/// A second, orthogonal second-level bucket — `message/UnknownImageShape` —
/// covers FIX #2: `user`/`toolResult`/`custom` content can carry an
/// `ImageContent` block whose `{mimeType, data}` shape is an unverified guess
/// (`pi-fields.md` never enumerates `ImageContent`'s own fields). A block
/// that doesn't match that shape must score `Unmodeled` here too, instead of
/// letting the loader silently synthesize an empty/corrupt `image_url` part.
fn audit_pi_line(line: &str, report: &mut Report) {
    let raw: Value = match serde_json::from_str(line) {
        Ok(v) => v,
        Err(_) => {
            report.parse_errors += 1;
            return;
        }
    };
    let extra = EMPTY_EXTRA.get_or_init(Default::default);
    let Some(ty) = raw.get("type").and_then(Value::as_str) else {
        report.bump("<line>/<no-type>".to_string(), Coverage::Unmodeled, extra);
        return;
    };
    match ty {
        "session" => report.bump("session".to_string(), Coverage::Normalized, extra),
        "message" => {
            let message = raw.get("message");
            let role = message.and_then(|m| m.get("role")).and_then(Value::as_str);
            // FIX #2: `user`/`toolResult`/`custom` all carry the shared
            // `(TextContent|ImageContent)[]` content union (`pi-fields.md`
            // §3a/§3c/§3e) — an `ImageContent` block that doesn't match the
            // loader's assumed (and unverified) `{mimeType, data}` shape
            // must score as `message/UnknownImageShape`, never silently
            // `Normalized`, mirroring `UnknownRole`'s "surface it, don't
            // vanish" rule exactly.
            let content = message.and_then(|m| m.get("content"));
            let unknown_image = matches!(role, Some("user") | Some("toolResult") | Some("custom"))
                && pi_content_has_unknown_image_shape(content);
            match role {
                _ if unknown_image => report.bump(
                    "message/UnknownImageShape".to_string(),
                    Coverage::Unmodeled,
                    extra,
                ),
                Some("user") => {
                    report.bump("message/user".to_string(), Coverage::Normalized, extra)
                }
                Some("assistant") => {
                    report.bump("message/assistant".to_string(), Coverage::Normalized, extra)
                }
                Some("toolResult") => report.bump(
                    "message/toolResult".to_string(),
                    Coverage::Normalized,
                    extra,
                ),
                Some("bashExecution") => report.bump(
                    "message/bashExecution".to_string(),
                    Coverage::Normalized,
                    extra,
                ),
                Some("custom") => {
                    report.bump("message/custom".to_string(), Coverage::Normalized, extra)
                }
                Some(other) => report.bump(
                    format!("message/UnknownRole:{other}"),
                    Coverage::Unmodeled,
                    extra,
                ),
                None => report.bump(
                    "message/UnknownRole:<none>".to_string(),
                    Coverage::Unmodeled,
                    extra,
                ),
            }
        }
        "custom_message" => report.bump("custom_message".to_string(), Coverage::Normalized, extra),
        "compaction" => report.bump("compaction".to_string(), Coverage::Normalized, extra),
        "branch_summary" => report.bump("branch_summary".to_string(), Coverage::Normalized, extra),
        "thinking_level_change" => report.bump(
            "thinking_level_change".to_string(),
            Coverage::Dropped,
            extra,
        ),
        "model_change" => report.bump("model_change".to_string(), Coverage::Normalized, extra),
        "custom" => report.bump("custom".to_string(), Coverage::Dropped, extra),
        "label" => report.bump("label".to_string(), Coverage::Dropped, extra),
        "session_info" => report.bump("session_info".to_string(), Coverage::Normalized, extra),
        other => report.bump(format!("<line>/{other}"), Coverage::Unmodeled, extra),
    }
}

/// Score one Gemini CLI session record against the native loader.
fn audit_gemini_line(line: &str, report: &mut Report) {
    let raw: Value = match serde_json::from_str(line) {
        Ok(value) => value,
        Err(_) => {
            report.parse_errors += 1;
            return;
        }
    };
    let extra = EMPTY_EXTRA.get_or_init(Default::default);
    let kind = raw.get("type").and_then(Value::as_str);
    if kind.is_none() {
        let key = if raw.get("sessionId").is_some_and(Value::is_string) {
            "session_header"
        } else if raw.get("$set").is_some() {
            "metadata_update"
        } else {
            "<line>/<no-type>"
        };
        let coverage = if key == "<line>/<no-type>" {
            Coverage::Unmodeled
        } else {
            Coverage::Retained
        };
        report.bump(key.to_string(), coverage, extra);
        return;
    }
    match kind.unwrap_or_default() {
        "user" | "gemini" => {
            report.bump(
                kind.unwrap_or_default().to_string(),
                Coverage::Normalized,
                extra,
            );
            if let Some(parts) = raw.get("content").and_then(Value::as_array) {
                for part in parts {
                    if part.get("text").is_some() {
                        report.bump("content/text".into(), Coverage::Normalized, extra);
                    } else if part.get("inlineData").is_some() {
                        report.bump("content/inlineData".into(), Coverage::Normalized, extra);
                    } else if let Some(call) = part.get("functionCall") {
                        report.bump("content/functionCall".into(), Coverage::Normalized, extra);
                        if let Some(name) = call.get("name").and_then(Value::as_str) {
                            *report.tools.entry(name.to_string()).or_insert(0) += 1;
                        }
                    } else if let Some(response) = part.get("functionResponse") {
                        report.bump(
                            "content/functionResponse".into(),
                            Coverage::Normalized,
                            extra,
                        );
                        if let Some(name) = response.get("name").and_then(Value::as_str) {
                            *report.tools.entry(name.to_string()).or_insert(0) += 1;
                        }
                    } else {
                        report.bump("content/unknown".into(), Coverage::Unmodeled, extra);
                    }
                }
            } else if !raw
                .get("content")
                .is_some_and(|content| content.is_string() || content.is_null())
            {
                report.bump("content/nonstandard".into(), Coverage::Unmodeled, extra);
            }
            if raw.get("thoughts").is_some() {
                report.bump("thoughts".into(), Coverage::Retained, extra);
            }
        }
        "info" | "error" => report.bump(
            kind.unwrap_or_default().to_string(),
            Coverage::Retained,
            extra,
        ),
        other => report.bump(format!("<line>/{other}"), Coverage::Unmodeled, extra),
    }
}

/// Score one Grok `chat_history.jsonl` record against the same shapes the
/// native loader actually consumes. Companion `updates.jsonl` streams are
/// excluded by [`audit_dir`], because they are ACP/runtime evidence rather
/// than the resumable transcript.
fn audit_grok_line(line: &str, report: &mut Report) {
    let raw: Value = match serde_json::from_str(line) {
        Ok(value) => value,
        Err(_) => {
            report.parse_errors += 1;
            return;
        }
    };
    let extra = EMPTY_EXTRA.get_or_init(Default::default);
    let Some(kind) = raw.get("type").and_then(Value::as_str) else {
        report.bump("<line>/<no-type>".to_string(), Coverage::Unmodeled, extra);
        return;
    };
    match kind {
        "system" => {
            let coverage = if raw.get("content").is_some_and(Value::is_string) {
                Coverage::Retained
            } else {
                Coverage::Unmodeled
            };
            report.bump("system".to_string(), coverage, extra);
        }
        "user" => {
            let (key, coverage) = classify_grok_user(&raw);
            report.bump(key.clone(), coverage, extra);
            audit_grok_content(raw.get("content"), &key, coverage, report);
        }
        "assistant" => {
            let content_supported = raw
                .get("content")
                .is_none_or(|content| content.is_null() || content.is_string());
            report.bump(
                "assistant".to_string(),
                if content_supported {
                    Coverage::Normalized
                } else {
                    Coverage::Unmodeled
                },
                extra,
            );
            if let Some(calls) = raw.get("tool_calls").and_then(Value::as_array) {
                for call in calls {
                    let modeled = call.get("id").is_some_and(Value::is_string)
                        && call.get("name").is_some_and(Value::is_string);
                    report.bump(
                        if modeled {
                            "assistant/tool_call".to_string()
                        } else {
                            "assistant/tool_call:invalid".to_string()
                        },
                        if modeled {
                            Coverage::Normalized
                        } else {
                            Coverage::Unmodeled
                        },
                        extra,
                    );
                    if let Some(name) = call.get("name").and_then(Value::as_str) {
                        *report.tools.entry(name.to_string()).or_insert(0) += 1;
                    }
                }
            } else if raw.get("tool_calls").is_some() {
                report.bump(
                    "assistant/tool_calls:non-array".to_string(),
                    Coverage::Unmodeled,
                    extra,
                );
            }
        }
        "tool_result" => {
            let modeled = raw.get("tool_call_id").is_some_and(Value::is_string);
            report.bump(
                "tool_result".to_string(),
                if modeled {
                    Coverage::Normalized
                } else {
                    Coverage::Unmodeled
                },
                extra,
            );
            audit_grok_content(
                raw.get("content"),
                "tool_result",
                Coverage::Normalized,
                report,
            );
        }
        // These are understood native records but deliberately remain in
        // the byte-exact raw prefix instead of becoming replayable messages.
        "reasoning" | "backend_tool_call" => {
            report.bump(kind.to_string(), Coverage::Dropped, extra)
        }
        other => report.bump(format!("<line>/{other}"), Coverage::Unmodeled, extra),
    }
}

/// Classify a Grok `user` record using the exact replay boundary enforced by
/// `Session::from_grok_str`: generated context wrappers are native session
/// state, not human turns, and therefore remain raw-only. Separate record
/// keys are deliberate — [`Report::records`] stores one coverage value per
/// key, so mixing replayed and discarded users under a single `user` key
/// would make the last line scanned overwrite the truth for the whole corpus.
fn classify_grok_user(raw: &Value) -> (String, Coverage) {
    if raw.get("synthetic_reason").and_then(Value::as_str) == Some("supercode_system_event") {
        return ("user/system_event".to_string(), Coverage::Normalized);
    }

    let content = grok_audit_text(raw.get("content"));
    let text = content.trim();
    if text.starts_with("<user_info>") {
        return (
            "user/injected_context:user_info".to_string(),
            Coverage::Dropped,
        );
    }
    if text.starts_with("<system-reminder>") {
        return (
            "user/injected_context:system-reminder".to_string(),
            Coverage::Dropped,
        );
    }
    if text.is_empty() {
        return ("user/empty".to_string(), Coverage::Dropped);
    }
    if text
        .strip_prefix("<user_query>")
        .and_then(|value| value.strip_suffix("</user_query>"))
        .is_some_and(|value| value.trim().is_empty())
    {
        return ("user/empty_query".to_string(), Coverage::Dropped);
    }
    ("user".to_string(), Coverage::Normalized)
}

/// Mirror the loader's text extraction for the two organic Grok shapes:
/// direct string content and arrays containing either `{text: ...}` blocks
/// or string entries. Other scalar/object values stringify exactly as the
/// loader does, making the audit a behavioral classification rather than a
/// narrower invented schema.
fn grok_audit_text(content: Option<&Value>) -> String {
    match content {
        Some(Value::String(text)) => text.clone(),
        Some(Value::Array(items)) => items
            .iter()
            .filter_map(|item| {
                item.get("text")
                    .and_then(Value::as_str)
                    .or_else(|| item.as_str())
            })
            .collect::<Vec<_>>()
            .join("\n"),
        Some(other) => other.to_string(),
        None => String::new(),
    }
}

fn audit_grok_content(
    content: Option<&Value>,
    prefix: &str,
    record_coverage: Coverage,
    report: &mut Report,
) {
    let extra = EMPTY_EXTRA.get_or_init(Default::default);
    match content {
        Some(Value::Array(items)) => {
            for item in items {
                let tag = item
                    .get("type")
                    .and_then(Value::as_str)
                    .unwrap_or("<no-type>");
                let modeled = item.is_string() || item.get("text").is_some_and(Value::is_string);
                let coverage = if record_coverage == Coverage::Dropped {
                    Coverage::Dropped
                } else if modeled {
                    Coverage::Normalized
                } else {
                    Coverage::Unmodeled
                };
                report.bump(format!("{prefix}/content/{tag}"), coverage, extra);
            }
        }
        Some(_) => report.bump(format!("{prefix}/content"), record_coverage, extra),
        None => report.bump(
            format!("{prefix}/content:<missing>"),
            if record_coverage == Coverage::Dropped {
                Coverage::Dropped
            } else {
                Coverage::Unmodeled
            },
            extra,
        ),
    }
}

/// The frozen 12-part union discriminant values
/// (`docs/interop/research/opencode-fields.md` §3, `v1/session.ts:357-370`).
/// Anything outside this set is an UNKNOWN part type — never silently
/// dropped, always scored `Unmodeled` (§4.1's "no record/part discriminant
/// falls into an Unknown bucket" completeness guard).
const OPENCODE_KNOWN_PART_TYPES: &[&str] = &[
    "text",
    "reasoning",
    "tool",
    "file",
    "step-start",
    "step-finish",
    "snapshot",
    "patch",
    "agent",
    "subtask",
    "retry",
    "compaction",
];

/// `ToolState`'s frozen discriminant values (`opencode-fields.md` §3.3,
/// `v1/session.ts:259-313`).
const OPENCODE_KNOWN_TOOL_STATUSES: &[&str] = &["pending", "running", "completed", "error"];

/// Audit one envelope line of an OpenCode session
/// (`docs/interop/opencode-pi-spec.md` §1.2/§4.1): `{"key":[...],"value":...}`,
/// classified by the envelope `key`'s first component exactly like
/// [`crate::session::Session::from_opencode_str`]. Two second-level
/// discriminants get their own `Unknown*` buckets, mirroring pi's
/// `UnknownRole`/`UnknownImageShape` discipline (S6): `message/UnknownRole:*`
/// for a `message` record whose `role` isn't `user`/`assistant`, and
/// `part/UnknownType:*` for a `part` record whose `type` isn't one of the
/// frozen 12 — plus a THIRD level for `tool` parts specifically,
/// `part/tool/UnknownStatus:*`, for a `state.status` outside the frozen
/// four. All three must be empty over the committed fixture + real corpus.
fn audit_opencode_line(line: &str, report: &mut Report) {
    let raw: Value = match serde_json::from_str(line) {
        Ok(v) => v,
        Err(_) => {
            report.parse_errors += 1;
            return;
        }
    };
    let extra = EMPTY_EXTRA.get_or_init(Default::default);
    let Some(key) = raw.get("key").and_then(Value::as_array) else {
        report.bump("<line>/<no-key>".to_string(), Coverage::Unmodeled, extra);
        return;
    };
    let value = raw.get("value").cloned().unwrap_or(Value::Null);
    let kind = key.first().and_then(Value::as_str).unwrap_or("<no-kind>");
    match kind {
        "session" => report.bump("session".to_string(), Coverage::Normalized, extra),
        "message" => match value.get("role").and_then(Value::as_str) {
            Some("user") => report.bump("message/user".to_string(), Coverage::Normalized, extra),
            Some("assistant") => {
                report.bump("message/assistant".to_string(), Coverage::Normalized, extra)
            }
            Some(other) => report.bump(
                format!("message/UnknownRole:{other}"),
                Coverage::Unmodeled,
                extra,
            ),
            None => report.bump(
                "message/UnknownRole:<none>".to_string(),
                Coverage::Unmodeled,
                extra,
            ),
        },
        "part" => match value.get("type").and_then(Value::as_str) {
            Some(t) if OPENCODE_KNOWN_PART_TYPES.contains(&t) => {
                if t == "tool" {
                    // D5: tally the tool NAME (`tool`, e.g. "bash"/"edit"),
                    // not just the call-status bucket — previously
                    // `report.tools` was always empty for opencode corpora.
                    if let Some(name) = value.get("tool").and_then(Value::as_str) {
                        *report.tools.entry(name.to_string()).or_insert(0) += 1;
                    }
                    match value
                        .get("state")
                        .and_then(|s| s.get("status"))
                        .and_then(Value::as_str)
                    {
                        Some(s) if OPENCODE_KNOWN_TOOL_STATUSES.contains(&s) => {
                            report.bump(format!("part/tool/{s}"), Coverage::Normalized, extra)
                        }
                        Some(other) => report.bump(
                            format!("part/tool/UnknownStatus:{other}"),
                            Coverage::Unmodeled,
                            extra,
                        ),
                        None => report.bump(
                            "part/tool/UnknownStatus:<none>".to_string(),
                            Coverage::Unmodeled,
                            extra,
                        ),
                    }
                } else if t == "text" {
                    // D5: an `ignored:true` text part is EXCLUDED from
                    // replay by design (§2.2: "must not be re-emitted to
                    // the model") — it is recognized and preserved in
                    // `raw`, but never lands in canonical `messages`, so it
                    // is Dropped, not Normalized. A separate discriminant
                    // key keeps the two counted (and displayed) apart
                    // rather than one overwriting the other's coverage.
                    let ignored = value.get("ignored").and_then(Value::as_bool) == Some(true);
                    if ignored {
                        report.bump("part/text:ignored".to_string(), Coverage::Dropped, extra);
                    } else {
                        report.bump("part/text".to_string(), Coverage::Normalized, extra);
                    }
                } else if t == "file" {
                    // D5: the loader only canonicalizes a `data:`-URI
                    // `image/*` file part into `content_parts` (the SAME
                    // test `opencode_file_image_part` uses, reused here so
                    // audit can never drift from what convert actually
                    // replays). An `https:` link, a bare path, a PDF, or
                    // any other non-image/non-data-URI file is raw-only
                    // residue — Dropped, not Normalized.
                    if opencode_file_image_part(&value).is_some() {
                        report.bump("part/file".to_string(), Coverage::Normalized, extra);
                    } else {
                        report.bump("part/file:residue".to_string(), Coverage::Dropped, extra);
                    }
                } else {
                    // compaction drives the `compacted_out` boundary —
                    // Normalized. reasoning feeds `metadata["thinking"]`
                    // (recognized, deliberately not canonical content —
                    // Dropped, same label Claude/Codex `thinking` blocks
                    // get). step-start/step-finish/snapshot/patch/agent/
                    // subtask/retry are recognized but have NO clean home
                    // at all (§2.3) — also Dropped. Only a truly
                    // unrecognized type is Unmodeled.
                    let cov = match t {
                        "compaction" => Coverage::Normalized,
                        _ => Coverage::Dropped,
                    };
                    report.bump(format!("part/{t}"), cov, extra);
                }
            }
            Some(other) => report.bump(
                format!("part/UnknownType:{other}"),
                Coverage::Unmodeled,
                extra,
            ),
            None => report.bump(
                "part/UnknownType:<none>".to_string(),
                Coverage::Unmodeled,
                extra,
            ),
        },
        "session_diff" => report.bump("session_diff".to_string(), Coverage::Normalized, extra),
        "todo" => report.bump("todo".to_string(), Coverage::Normalized, extra),
        other => report.bump(format!("<line>/{other}"), Coverage::Unmodeled, extra),
    }
}

fn jsonl_files(dir: &Path) -> Vec<PathBuf> {
    let mut out = Vec::new();
    let walker = ignore::WalkBuilder::new(dir)
        .standard_filters(false)
        .build();
    for entry in walker.flatten() {
        let p = entry.into_path();
        if p.extension().and_then(|e| e.to_str()) == Some("jsonl") {
            out.push(p);
        }
    }
    out.sort();
    out
}