pushkin 0.2.0

//! Gate-dispatch conformance — one contract, two surfaces.
//!
//! Authorized by `docs/charters/2026-08-18-gate-dispatch-conformance.md`
//! (RATIFIED — Amos Coletti, 2026-08-18), **shape 1 only**: a conformance suite.
//! Shapes 2 and 3 (`extract-one-decide()` / shared dispatch) are explicitly NOT
//! authorized and nothing here anticipates them (N12).
//!
//! A NEW file per N10. No production file is touched by this pass.
//!
//! **The contract this pins.** `pushkin check` (stdin — the pre-commit floor's
//! path) and `pushkin hook <agent>` (the agent write-time path) render a verdict
//! for the same logical action. They share `CheckResult`/`Violation` and the
//! `verbs.rs` gate helpers, but NOT the path from payload to verdict: each has
//! its own parser, its own malformed branch, and its own rule dispatch. F48
//! proved the copies drift — the identical `Edit`/`MultiEdit` fail-open existed
//! in both and had to be fixed twice. Nothing mechanical held them in step.
//! This file is that mechanism.
//!
//! **Equality is STRUCTURAL, not byte-identical prose** (charter open question
//! #3). Byte-identity is not merely inconvenient, it is impossible today and by
//! design: `check::render` emits `(contract: user)` while
//! `hook::render_ladder_for` emits `(contract: 'user') — attempt 1/3` plus a
//! `waiver:` line, and `CheckResult::duration_ms` is wall-clock and so cannot
//! agree across two process invocations. What must agree is the verdict:
//! the decision, and the set of `file:line [rule]` triples. The surfaces
//! legitimately render differently; they may not legitimately DECIDE
//! differently.
//!
//! **Three decisions, not two.** `allow` and `block` are not the whole space —
//! a surface can also ABSTAIN, failing open on a payload it could not read.
//! Collapsing that into `allow` would score the two real divergences below as
//! agreement-with-different-prose instead of "one surface never rendered a
//! verdict at all". `Decision::FailOpen` keeps them distinct.
//!
//! **Deliberately NOT in scope.** No `--json` verdict for the hook verb (a
//! production change, and therefore a separate charter — see the parser note on
//! `hook_violation_keys`). No `PartialEq` derive on `pushkin_core::envelope`
//! (same reason). No manifest schema change, no `read_only_paths` entry, no
//! git-plane change. No peer-board `claim_violations` row: it needs board state
//! this fixture does not build, so a row for it would prove nothing. No
//! five-agent cross-product — `encode_deny` dialect coverage is
//! `tests/hook_verdicts.rs`'s job, not gate DISPATCH.

use assert_cmd::Command;
use std::fs;
use std::path::Path;
use std::process::Command as StdCommand;

type TestResult = Result<(), Box<dyn std::error::Error>>;

/// The fixture arms its own gates. This repo's `pushkin.toml` has every
/// `[gates]` line commented out (the git-plane pause, 2026-08-18), so a suite
/// that leaned on the real manifest would assert nothing.
const MANIFEST: &str = r#"
version = 1
canonical = "json-schema-2020-12"
authoring = "zod"

[[contracts]]
name = "user"
source = "contracts/user.zod.ts"
emit = ["zod"]

[[mappings]]
glob = "app/api/**/*.ts"
contracts = ["user"]
require = "boundary-validation"

[gates]
suppression_comments = "deny"
protected_paths = ["pushkin.toml"]
read_only_paths = ["crates/**/tests/**"]
retrieval_paths = ["crates/**/*.rs"]
retrieval_tool = "mcp__codebase-retrieval__codebase-retrieval"
"#;

const PROTECTED: &str = "pushkin.toml";
/// Committed, so the read-only predicate (glob AND present in HEAD) holds.
const COMMITTED_TEST: &str = "crates/pushkin-cli/tests/committed_suite.rs";
/// Under `retrieval_paths` — the read contract's target.
const SOURCE: &str = "crates/pushkin-cli/src/main.rs";
/// Mapped to a contract requiring boundary-validation.
const MAPPED: &str = "app/api/users/route.ts";
/// Neither gated nor mapped.
const UNGATED: &str = "docs/notes.md";

const RULE_UNVALIDATED: &str = "contract.boundary.unvalidated_input";
const RULE_PROTECTED: &str = "pushkin.protected_path";
const RULE_READ_ONLY: &str = "pushkin.read_only_path";
const RULE_RAW_READ: &str = "pushkin.retrieval.raw_read";

/// Both surfaces print this exact phrase on their fail-open branch —
/// `check::run` and `hook::handle_malformed`.
const FAIL_OPEN_MARKER: &str = "failing open";

// ---------------------------------------------------------------- fixture

fn git(dir: &Path, args: &[&str]) -> TestResult {
    let status = StdCommand::new("git")
        .current_dir(dir)
        .args(args)
        .status()?;
    assert!(status.success(), "git {args:?} failed");
    Ok(())
}

fn write_fixture_tree(dir: &Path) -> TestResult {
    fs::write(dir.join(PROTECTED), MANIFEST)?;
    fs::create_dir_all(dir.join("contracts"))?;
    fs::write(
        dir.join("contracts/user.zod.ts"),
        "export const user = 1;\n",
    )?;
    fs::create_dir_all(dir.join("app/api/users"))?;
    fs::write(dir.join(MAPPED), "export const handler = 1;\n")?;
    fs::create_dir_all(dir.join("crates/pushkin-cli/tests"))?;
    fs::write(dir.join(COMMITTED_TEST), "// committed suite\n")?;
    fs::create_dir_all(dir.join("crates/pushkin-cli/src"))?;
    fs::write(dir.join(SOURCE), "fn main() {}\n")?;
    fs::create_dir_all(dir.join("docs"))?;
    fs::write(dir.join(UNGATED), "notes\n")?;
    Ok(())
}

fn repo() -> Result<tempfile::TempDir, Box<dyn std::error::Error>> {
    let dir = tempfile::tempdir()?;
    write_fixture_tree(dir.path())?;
    git(dir.path(), &["init", "-q", "."])?;
    git(dir.path(), &["add", "-A"])?;
    git(
        dir.path(),
        &[
            "-c",
            "user.name=Conformance Suite",
            "-c",
            "user.email=conformance@test",
            "commit",
            "-qm",
            "fixture",
        ],
    )?;
    Ok(dir)
}

// ---------------------------------------------------------------- verdict

/// What a surface DID, independent of how it said so.
///
/// `FailOpen` is a third state and not a flavour of `Allow`: the surface never
/// reached a rule at all. Two of the corpus rows below differ precisely here,
/// and a two-valued decision would report them as agreeing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Decision {
    Allow,
    Block,
    FailOpen,
}

/// The comparable verdict. `duration_ms` is absent by construction — it is
/// wall-clock, so two invocations can never agree on it (envelope.rs).
#[derive(Debug, Clone, PartialEq, Eq)]
struct Verdict {
    decision: Decision,
    /// Sorted, deduped `file:line [rule]` keys.
    violations: Vec<String>,
}

/// One logical action, rendered into both surfaces' payload dialects.
///
/// The two renderings live BESIDE the corpus (charter open question #4). The
/// alternative — "in each verb's module" — means editing
/// `crates/pushkin-cli/src/verbs/check.rs` and `.../hook.rs`, which the
/// charter's scope ruling forbids outright.
struct Case {
    name: &'static str,
    check_payload: &'static str,
    agent: &'static str,
    hook_payload: &'static str,
    /// `PUSHKIN_DAEMON` for both surfaces — the S1c warm/cold parity lever. A
    /// gate that holds cold and not warm is not a gate.
    daemon: &'static str,
    expect: Expect,
}

/// Not a bool: the diverging arm carries WHY, so the assertion message names
/// the finding instead of just failing.
enum Expect {
    Agree,
    /// The surfaces disagree today and the charter forbids the production
    /// change that would reconcile them. The row pins WHICH WAY they disagree,
    /// not merely that they do: bare inequality would still pass if `check`
    /// started emitting an allow envelope instead of abstaining, which is a
    /// different finding wearing the same test result. It also asserts the
    /// disagreement itself, so a future convergence fails loudly and forces
    /// this row to be revisited rather than drifting shut unnoticed.
    Diverges {
        check: Decision,
        hook: Decision,
        why: &'static str,
    },
}

/// The `file:line [rule]` prefix both renderers emit identically.
///
/// `check::render`          -> `  {file}:{line} [{rule}] (contract: {name})`
/// `hook::render_ladder_for`-> `  {file}:{line} [{rule}] (contract: '{name}') — attempt {n}/3`
///
/// Everything after `]` is rendering and is deliberately not compared. The
/// segment before `[` must end in `:{digits}` so a `try:` suggestion line
/// carrying brackets cannot masquerade as a violation.
fn key_from_line(line: &str) -> Option<String> {
    let (head, rest) = line.split_once(" [")?;
    let rule = rest.split_once(']')?.0;
    let head = head.trim();
    let (file, line_no) = head.rsplit_once(':')?;
    if file.is_empty() || line_no.is_empty() || !line_no.bytes().all(|b| b.is_ascii_digit()) {
        return None;
    }
    Some(format!("{file}:{line_no} [{rule}]"))
}

fn violation_keys(prose: &str) -> Vec<String> {
    let mut keys: Vec<String> = prose.lines().filter_map(key_from_line).collect();
    keys.sort();
    keys.dedup();
    keys
}

// ---------------------------------------------------------------- surfaces

#[derive(Debug)]
struct Raw {
    code: i32,
    stdout: String,
    stderr: String,
}

impl Raw {
    fn failed_open(&self) -> bool {
        self.stderr.contains(FAIL_OPEN_MARKER)
    }
}

/// One binary invocation, bundled so `run` stays at two arguments.
struct Invocation<'a> {
    args: &'a [&'a str],
    daemon: &'a str,
    payload: &'a str,
}

fn run(dir: &Path, call: &Invocation) -> Result<Raw, Box<dyn std::error::Error>> {
    let output = Command::cargo_bin("pushkin")?
        .current_dir(dir)
        .env("PUSHKIN_DAEMON", call.daemon)
        .args(call.args)
        .write_stdin(call.payload.to_owned())
        .output()?;
    Ok(Raw {
        code: output.status.code().unwrap_or(-1),
        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
    })
}

/// The third state. `check --json` returns from its fail-open branch BEFORE
/// `emit()` runs, so an empty stdout is the abstention's signature — but only
/// when the fail-open marker is on stderr. Empty stdout without it would mean
/// the envelope went missing for some other reason, which must not be laundered
/// into a verdict.
fn abstained(raw: &Raw, case: &str) -> Verdict {
    assert!(
        raw.failed_open(),
        "{case}: check produced no envelope and did not fail open: {raw:?}"
    );
    Verdict {
        decision: Decision::FailOpen,
        violations: Vec::new(),
    }
}

/// `pushkin check --json` emits the literal §8.3 `CheckResult` envelope on
/// stdout, so the check side needs no prose parsing at all. The fail-open
/// branch returns before `emit()` is reached, so stdout is EMPTY there — which
/// is what makes the third state detectable rather than inferred.
fn check_verdict(dir: &Path, case: &Case) -> Result<Verdict, Box<dyn std::error::Error>> {
    let raw = run(
        dir,
        &Invocation {
            args: &["check", "--json"],
            daemon: case.daemon,
            payload: case.check_payload,
        },
    )?;
    if raw.stdout.trim().is_empty() {
        return Ok(abstained(&raw, case.name));
    }
    let envelope: serde_json::Value = serde_json::from_str(&raw.stdout)?;
    let decision = match envelope["decision"].as_str() {
        Some("allow") => Decision::Allow,
        Some("block") => Decision::Block,
        other => {
            return Err(format!("{}: unknown check decision {other:?}: {raw:?}", case.name).into())
        }
    };
    assert_code_corroborates(&raw, decision);
    Ok(Verdict {
        decision,
        violations: envelope_keys(&envelope),
    })
}

/// `check::emit` derives the exit code from the same result it serializes, so
/// the two can only disagree if the serialization fallback fired. That fallback
/// is deny-shaped BY DESIGN (M3: a serialization bug must never launder a block
/// into an allow), which makes an allow-carrying-exit-2 the exact shape of a
/// laundered verdict. Cheap to check here, and nothing else checks it.
fn assert_code_corroborates(raw: &Raw, decision: Decision) {
    let expected = if decision == Decision::Block { 2 } else { 0 };
    assert_eq!(
        raw.code, expected,
        "check's exit code contradicts its own envelope: {raw:?}"
    );
}

/// The same `file:line [rule]` key `violation_keys` recovers from prose, read
/// structurally instead. A field the envelope does not carry renders as `?`
/// rather than being skipped, so a schema change surfaces as a mismatch in the
/// calibration test instead of as a silently shorter violation set.
fn envelope_keys(envelope: &serde_json::Value) -> Vec<String> {
    let mut keys: Vec<String> = envelope["violations"]
        .as_array()
        .into_iter()
        .flatten()
        .map(|v| {
            format!(
                "{}:{} [{}]",
                v["file"].as_str().unwrap_or("?"),
                v["line"].as_u64().unwrap_or(0),
                v["rule"].as_str().unwrap_or("?")
            )
        })
        .collect();
    keys.sort();
    keys.dedup();
    keys
}

/// The hook verb has no `--json` verdict, so its violation set is recovered
/// from the ladder prose carried inside the agent-native deny envelope. That
/// couples this suite to `render_ladder_for`'s line format — the honest fix
/// would be a machine-readable hook verdict, which is production code and
/// therefore a separate charter. `check_prose_and_json_agree` below calibrates
/// this parser against ground truth so it is proven, not trusted.
fn hook_verdict(dir: &Path, case: &Case) -> Result<Verdict, Box<dyn std::error::Error>> {
    let raw = run(
        dir,
        &Invocation {
            args: &["hook", case.agent],
            daemon: case.daemon,
            payload: case.hook_payload,
        },
    )?;
    let Some(prose) = deny_prose(&raw.stdout) else {
        return Ok(Verdict {
            decision: if raw.failed_open() {
                Decision::FailOpen
            } else {
                Decision::Allow
            },
            violations: Vec::new(),
        });
    };
    let violations = violation_keys(&prose);
    assert!(
        !violations.is_empty(),
        "{}: hook denied but no violation line parsed — the ladder format moved: {prose}",
        case.name
    );
    Ok(Verdict {
        decision: Decision::Block,
        violations,
    })
}

/// `None` for every `encode_allow` shape (empty string, `{}`,
/// `{"decision":"allow"}`); the prose for every `encode_deny` dialect.
fn deny_prose(stdout: &str) -> Option<String> {
    let value: serde_json::Value = serde_json::from_str(stdout.trim()).ok()?;
    for field in [
        "/hookSpecificOutput/permissionDecisionReason",
        "/reason",
        "/message",
    ] {
        if let Some(prose) = value.pointer(field).and_then(serde_json::Value::as_str) {
            return Some(prose.to_owned());
        }
    }
    None
}

// ---------------------------------------------------------------- the assertion

fn assert_conformance(dir: &Path, case: &Case) -> TestResult {
    let check = check_verdict(dir, case)?;
    let hook = hook_verdict(dir, case)?;
    match case.expect {
        Expect::Agree => assert_eq!(
            check, hook,
            "{}: the two surfaces rendered DIFFERENT verdicts for one logical \
             action. check={check:?} hook={hook:?}",
            case.name
        ),
        Expect::Diverges {
            check: want_check,
            hook: want_hook,
            why,
        } => {
            assert_ne!(
                check, hook,
                "{}: the surfaces now AGREE, but this row is recorded as \
                 divergent ({why}). If the divergence was fixed, reclassify this \
                 row to Expect::Agree and close the finding. check={check:?}",
                case.name
            );
            assert_eq!(
                (check.decision, hook.decision),
                (want_check, want_hook),
                "{}: the surfaces still disagree, but not in the recorded \
                 SHAPE ({why}). check={check:?} hook={hook:?}",
                case.name
            );
        }
    }
    Ok(())
}

// ---------------------------------------------------------------- the corpus
//
// Every row is one logical action in two dialects. A new rule class adds one
// row here and is thereby required to behave identically on both surfaces from
// the day it lands — the charter's stated purpose for this file.

const WRITE_NONCONFORMING: Case = Case {
    name: "write_nonconforming_to_mapped_glob",
    check_payload: r#"{"session_id":"gdc-01","tool_name":"Write","tool_input":{"file_path":"app/api/users/route.ts","content":"export async function POST(req){ const b = await req.json(); return Response.json(b); }"}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-01","tool_name":"Write","tool_input":{"file_path":"app/api/users/route.ts","content":"export async function POST(req){ const b = await req.json(); return Response.json(b); }"}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

/// The same action with the daemon eligible. S1c: a gate that holds cold and
/// not warm is not a gate, so the conformance claim is made on both paths.
const WRITE_NONCONFORMING_WARM: Case = Case {
    name: "write_nonconforming_to_mapped_glob_warm",
    daemon: "auto",
    ..WRITE_NONCONFORMING
};

const WRITE_CONFORMING: Case = Case {
    name: "write_conforming_to_mapped_glob",
    check_payload: r#"{"session_id":"gdc-02","tool_name":"Write","tool_input":{"file_path":"app/api/users/route.ts","content":"import { UserCreateSchema } from \"contracts/user.zod\";\nexport async function POST(req){ const b = UserCreateSchema.parse(await req.json()); return Response.json(b); }"}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-02","tool_name":"Write","tool_input":{"file_path":"app/api/users/route.ts","content":"import { UserCreateSchema } from \"contracts/user.zod\";\nexport async function POST(req){ const b = UserCreateSchema.parse(await req.json()); return Response.json(b); }"}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

const WRITE_UNGATED: Case = Case {
    name: "write_to_ungated_unmapped_path",
    check_payload: r#"{"session_id":"gdc-03","tool_name":"Write","tool_input":{"file_path":"docs/notes.md","content":"hello"}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-03","tool_name":"Write","tool_input":{"file_path":"docs/notes.md","content":"hello"}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

const WRITE_PROTECTED: Case = Case {
    name: "write_to_protected_path",
    check_payload: r#"{"session_id":"gdc-04","tool_name":"Write","tool_input":{"file_path":"pushkin.toml","content":"version = 1"}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-04","tool_name":"Write","tool_input":{"file_path":"pushkin.toml","content":"version = 1"}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

/// F48's own class: content absent, target named. Both surfaces must run the
/// path rules from the payload rather than treating it as malformed.
const EDIT_READ_ONLY: Case = Case {
    name: "edit_a_committed_read_only_test",
    check_payload: r#"{"session_id":"gdc-05","tool_name":"Edit","tool_input":{"file_path":"crates/pushkin-cli/tests/committed_suite.rs","old_string":"// committed suite","new_string":"// tampered"}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-05","tool_name":"Edit","tool_input":{"file_path":"crates/pushkin-cli/tests/committed_suite.rs","old_string":"// committed suite","new_string":"// tampered"}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

const MULTIEDIT_READ_ONLY: Case = Case {
    name: "multiedit_a_committed_read_only_test",
    check_payload: r#"{"session_id":"gdc-06","tool_name":"MultiEdit","tool_input":{"file_path":"crates/pushkin-cli/tests/committed_suite.rs","edits":[{"old_string":"// committed suite","new_string":"// tampered"}]}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-06","tool_name":"MultiEdit","tool_input":{"file_path":"crates/pushkin-cli/tests/committed_suite.rs","edits":[{"old_string":"// committed suite","new_string":"// tampered"}]}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

/// The one branch both surfaces reach through the SAME function
/// (`check::sweep_repo`, which `hook::evaluate` imports).
const STOP_SWEEP: Case = Case {
    name: "stop_payload_sweeps_the_repo",
    check_payload: r#"{"session_id":"gdc-07","stop_hook_active":true}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-07","stop_hook_active":true}"#,
    daemon: "off",
    expect: Expect::Agree,
};

/// F60's class: a payload neither surface can read, naming an unwaivable path.
const UNREADABLE_NAMING_PROTECTED: Case = Case {
    name: "unreadable_payload_naming_a_protected_path",
    check_payload: r#"{"session_id":"gdc-08","tool_name":"SomeToolPushkinHasNeverHeardOf","tool_input":{"target":"pushkin.toml"}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-08","tool_name":"SomeToolPushkinHasNeverHeardOf","tool_input":{"target":"pushkin.toml"}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

/// Cross-dialect, and agreement by two DIFFERENT routes: `hook codex` parses
/// the patch and runs `gate_delete`; `check`'s Claude-shaped parser cannot read
/// it at all and arrives via F60's token scan. Same verdict, no shared code
/// path — so nothing but this row holds them together.
const CODEX_DELETE_READ_ONLY: Case = Case {
    name: "codex_apply_patch_delete_of_a_read_only_test",
    check_payload: r#"{"session_id":"gdc-09","tool_name":"apply_patch","tool_input":{"command":"*** Begin Patch\n*** Delete File: crates/pushkin-cli/tests/committed_suite.rs\n*** End Patch\n"}}"#,
    agent: "codex",
    hook_payload: r#"{"session_id":"gdc-09","tool_name":"apply_patch","tool_input":{"command":"*** Begin Patch\n*** Delete File: crates/pushkin-cli/tests/committed_suite.rs\n*** End Patch\n"}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

/// Cross-dialect again, and the same accidental agreement: an auggie fragment
/// reaches `pushkin.protected_path` on the hook side through
/// `normalize_auggie`, and on the check side through F60's scan.
const AUGGIE_FRAGMENT_PROTECTED: Case = Case {
    name: "auggie_fragment_targeting_a_protected_path",
    check_payload: r#"{"session_id":"gdc-10","tool_name":"str-replace-editor","tool_input":{"path":"pushkin.toml","new_str_1":"version = 2"}}"#,
    agent: "auggie",
    hook_payload: r#"{"session_id":"gdc-10","tool_name":"str-replace-editor","tool_input":{"path":"pushkin.toml","new_str_1":"version = 2"}}"#,
    daemon: "off",
    expect: Expect::Agree,
};

/// F67, arm 1. The read contract exists only on the hook surface:
/// `hook::evaluate` routes `Intent::ReadWhole` to `gate_raw_read`, while
/// `check::parse_payload` requires `tool_input.content` and so lands in the
/// malformed branch. F60's fallback cannot rescue it, because `retrieval_paths`
/// is the ONE family F60 deliberately excluded ("a READ rule — any payload
/// mentioning a source file would deny, which is intolerable noise").
/// Every step is correct alone; the aggregate is a fail-open the floor inherits.
const READ_WHOLE_GATED_SOURCE: Case = Case {
    name: "unbounded_read_of_a_retrieval_gated_source_file",
    check_payload: r#"{"session_id":"gdc-11","tool_name":"Read","tool_input":{"file_path":"crates/pushkin-cli/src/main.rs"}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-11","tool_name":"Read","tool_input":{"file_path":"crates/pushkin-cli/src/main.rs"}}"#,
    daemon: "off",
    expect: Expect::Diverges {
        check: Decision::FailOpen,
        hook: Decision::Block,
        why: "F67 arm 1 — hook denies pushkin.retrieval.raw_read; check fails \
              open. The read contract has no check-verb counterpart.",
    },
};

/// F67, arm 2. Same gap reached through the shell: `hook::evaluate` matches the
/// target inside the command string via `gate_shell_read`; `check` has no
/// `Intent::Shell` branch at all.
const BASH_READ_GATED_SOURCE: Case = Case {
    name: "shell_read_of_a_retrieval_gated_source_file",
    check_payload: r#"{"session_id":"gdc-12","tool_name":"Bash","tool_input":{"command":"cat crates/pushkin-cli/src/main.rs"}}"#,
    agent: "claude",
    hook_payload: r#"{"session_id":"gdc-12","tool_name":"Bash","tool_input":{"command":"cat crates/pushkin-cli/src/main.rs"}}"#,
    daemon: "off",
    expect: Expect::Diverges {
        check: Decision::FailOpen,
        hook: Decision::Block,
        why: "F67 arm 2 — hook denies pushkin.retrieval.raw_read via \
              gate_shell_read; check has no Intent::Shell branch and fails open.",
    },
};

const CORPUS: &[&Case] = &[
    &WRITE_NONCONFORMING,
    &WRITE_NONCONFORMING_WARM,
    &WRITE_CONFORMING,
    &WRITE_UNGATED,
    &WRITE_PROTECTED,
    &EDIT_READ_ONLY,
    &MULTIEDIT_READ_ONLY,
    &STOP_SWEEP,
    &UNREADABLE_NAMING_PROTECTED,
    &CODEX_DELETE_READ_ONLY,
    &AUGGIE_FRAGMENT_PROTECTED,
    &READ_WHOLE_GATED_SOURCE,
    &BASH_READ_GATED_SOURCE,
];

// ---------------------------------------------------------------- the rows

#[test]
fn write_nonconforming_to_mapped_glob() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &WRITE_NONCONFORMING)
}

#[test]
fn write_nonconforming_to_mapped_glob_warm() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &WRITE_NONCONFORMING_WARM)
}

#[test]
fn write_conforming_to_mapped_glob() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &WRITE_CONFORMING)
}

#[test]
fn write_to_ungated_unmapped_path() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &WRITE_UNGATED)
}

#[test]
fn write_to_protected_path() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &WRITE_PROTECTED)
}

#[test]
fn edit_a_committed_read_only_test() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &EDIT_READ_ONLY)
}

#[test]
fn multiedit_a_committed_read_only_test() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &MULTIEDIT_READ_ONLY)
}

#[test]
fn stop_payload_sweeps_the_repo() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &STOP_SWEEP)
}

#[test]
fn unreadable_payload_naming_a_protected_path() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &UNREADABLE_NAMING_PROTECTED)
}

#[test]
fn codex_apply_patch_delete_of_a_read_only_test() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &CODEX_DELETE_READ_ONLY)
}

#[test]
fn auggie_fragment_targeting_a_protected_path() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &AUGGIE_FRAGMENT_PROTECTED)
}

#[test]
fn unbounded_read_of_a_retrieval_gated_source_file_diverges() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &READ_WHOLE_GATED_SOURCE)
}

#[test]
fn shell_read_of_a_retrieval_gated_source_file_diverges() -> TestResult {
    let dir = repo()?;
    assert_conformance(dir.path(), &BASH_READ_GATED_SOURCE)
}

// ---------------------------------------------------------------- instrument checks
//
// A conformance suite whose own comparator is unverified is an assertion with
// extra steps. These four pin the instrument rather than the subject.

/// Calibrates the prose parser against ground truth.
///
/// The check surface renders BOTH a typed `CheckResult` envelope (`--json`,
/// stdout) and the ladder-shaped prose (default, stderr) for the same payload.
/// So for every corpus row, the keys `violation_keys` recovers from prose must
/// equal the keys read structurally from the envelope. That is the evidence
/// that the identical parser, applied to the hook surface where no envelope
/// exists, is reporting the truth.
#[test]
fn check_prose_and_json_agree_on_every_row() -> TestResult {
    for case in CORPUS {
        let dir = repo()?;
        let structural = check_verdict(dir.path(), case)?;
        let raw = run(
            dir.path(),
            &Invocation {
                args: &["check"],
                daemon: case.daemon,
                payload: case.check_payload,
            },
        )?;
        let parsed = violation_keys(&raw.stderr);
        assert_eq!(
            structural.violations, parsed,
            "{}: the prose parser disagrees with the JSON envelope on the SAME \
             payload, so it cannot be trusted on the hook surface. stderr={}",
            case.name, raw.stderr
        );
    }
    Ok(())
}

/// The hook surface must actually be gating in this fixture. `hook::run`
/// returns `Ok(0)` silently in a detached worktree BEFORE reading the manifest,
/// so a worktree-policy change could turn every row into a vacuous allow and
/// the whole suite green. One known-block row asserted directly stops that.
#[test]
fn the_hook_surface_is_not_vacuously_allowing() -> TestResult {
    let dir = repo()?;
    let verdict = hook_verdict(dir.path(), &WRITE_PROTECTED)?;
    assert_eq!(verdict.decision, Decision::Block);
    assert!(
        verdict
            .violations
            .iter()
            .any(|k| k.contains(RULE_PROTECTED)),
        "hook must deny a protected-path write: {verdict:?}"
    );
    Ok(())
}

/// The corpus is the specification of equivalence. Under N10 this file is
/// read-only once committed, so rows cannot be quietly dropped by an agent —
/// but the floor makes that mechanical rather than a matter of review
/// attention, and names every rule the corpus claims to exercise.
#[test]
fn the_corpus_covers_every_rule_it_claims() -> TestResult {
    assert!(
        CORPUS.len() >= 13,
        "corpus rows may be added, never removed"
    );
    let names: Vec<&str> = CORPUS.iter().map(|c| c.name).collect();
    let mut sorted = names.clone();
    sorted.sort_unstable();
    sorted.dedup();
    assert_eq!(sorted.len(), names.len(), "corpus row names must be unique");

    let dir = repo()?;
    let mut seen: Vec<String> = Vec::new();
    for case in CORPUS {
        seen.extend(hook_verdict(dir.path(), case)?.violations);
    }
    for rule in [
        RULE_UNVALIDATED,
        RULE_PROTECTED,
        RULE_READ_ONLY,
        RULE_RAW_READ,
    ] {
        assert!(
            seen.iter().any(|k| k.contains(rule)),
            "no corpus row exercises {rule}; the suite would agree vacuously on it"
        );
    }
    Ok(())
}

/// `key_from_line` must reject the decorations that surround a violation line
/// in both renderers. A parser that accepted a `try:` line would inflate both
/// verdicts equally and hide a real difference underneath.
#[test]
fn the_key_parser_rejects_ladder_decoration() {
    assert_eq!(
        key_from_line(
            "  app/api/users/route.ts:1 [contract.boundary.unvalidated_input] (contract: user)"
        ),
        Some("app/api/users/route.ts:1 [contract.boundary.unvalidated_input]".to_owned()),
    );
    assert_eq!(
        key_from_line("  app/api/users/route.ts:1 [contract.boundary.unvalidated_input] (contract: 'user') — attempt 1/3"),
        Some("app/api/users/route.ts:1 [contract.boundary.unvalidated_input]".to_owned()),
        "the check and hook renderings of one violation must key identically",
    );
    // The hook renderer decorates a denial with lines the check renderer never
    // emits — the waiver pointer, the nudge, and the contract slice. The parser
    // meets those only on the hook surface, where no envelope exists to
    // calibrate against, so they are pinned here by literal instead.
    for decoration in [
        "    try: import { UserCreateSchema } from \"contracts/user.zod\"",
        "    fix: Parse the request body with UserCreateSchema [not a rule]",
        "    waiver: a human (not you) can run `pushkin waive pushkin.read_only_path`",
        "    nudge: the contract can be shown instead of searched — run `pushkin instructions` before retrying.",
        "    contract 'user' slice:",
        "      export const user = 1;",
        "pushkin: write blocked. Fix the violations below and retry.",
        "pushkin: read blocked AGAIN. Do not retry the same read — the result will be identical.",
        "pushkin: STOP. This write has been blocked 3 times. Do not attempt it again.",
        "",
    ] {
        assert_eq!(
            key_from_line(decoration),
            None,
            "decoration parsed as a violation: {decoration}"
        );
    }

    // A denial carrying two violations must yield two keys, sorted and deduped,
    // with every decoration between them discarded. This is the shape the hook
    // surface produces and the check envelope cannot calibrate.
    let ladder = "pushkin: write blocked. Fix the violations below and retry.\n          pushkin.toml:1 [pushkin.protected_path] — attempt 1/3\n            fix: a human must make it.\n            waiver: a human (not you) can run `pushkin waive pushkin.protected_path`\n          app/api/users/route.ts:1 [contract.boundary.unvalidated_input] (contract: 'user') — attempt 1/3\n            try: contract_show user";
    assert_eq!(
        violation_keys(ladder),
        vec![
            "app/api/users/route.ts:1 [contract.boundary.unvalidated_input]".to_owned(),
            "pushkin.toml:1 [pushkin.protected_path]".to_owned(),
        ],
    );
}