Plan: Test Framework Hardening — 8 Test Categories, Happy/Sad/Evil Coverage, Failure-Path Infrastructure

// crates/craig-test-lib/src/concurrent.rs

use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::time::{Duration, Instant};
use tokio::sync::Barrier;
use tokio::task::JoinHandle;

/// Outcome of a single task in a concurrent run.
#[derive(Debug)]
pub struct TaskOutcome<R> {
    /// 0-based index passed to the builder.
    pub index: usize,
    /// Wall-clock duration from spawn to handler return.
    pub latency: Duration,
    /// Wall-clock instant the task was spawned (monotonic, set under
    /// the same `Instant::now()` epoch as `latency`'s start).
    pub started_at: Instant,
    /// Value returned by the builder future, or panic info.
    pub result: TaskResult<R>,
}

#[derive(Debug)]
pub enum TaskResult<R> {
    Ok(R),
    Panicked { message: String },
}

/// Aggregate report over a `concurrent_fire_*` invocation.
pub struct ConcurrentRunReport<R> {
    /// One entry per task, ordered by `started_at` ascending.
    pub outcomes: Vec<TaskOutcome<R>>,
    /// Wall-clock duration from first-spawn to last-return.
    pub total: Duration,
}

impl<R> ConcurrentRunReport<R> {
    /// Number of tasks whose result is `TaskResult::Ok(_)`.
    pub fn ok_count(&self) -> usize { /* ... */ }
    /// Number of tasks whose result is `TaskResult::Panicked { .. }`.
    pub fn panic_count(&self) -> usize { /* ... */ }
    /// Returns `Ok(values)` if all tasks completed without panic, else
    /// `Err(panic_messages)`. Most tests want this.
    pub fn into_results(self) -> Result<Vec<R>, Vec<String>> { /* ... */ }
}

/// Spawn N concurrent tokio tasks, await all, return values in *spawn
/// order* (index 0..N-1). Panics in tasks panic the test thread —
/// matches the current minimal helper's behavior, kept for back-compat.
///
/// When-to-use: drop-in replacement for the &21 Step 2 minimal helper.
pub async fn concurrent_fire_collect<F, Fut, R>(n: usize, builder: F) -> Vec<R>
where
    F: Fn(usize) -> Fut + Send + Sync,
    Fut: Future<Output = R> + Send + 'static,
    R: Send + 'static;

/// Same as `concurrent_fire_collect` but returns a full `ConcurrentRunReport`
/// with per-task latency, ordered-by-start-instant, and panic capture.
///
/// When-to-use: any test that needs to assert *winner-vs-loser shape*
/// (idempotency replay tests), latency distribution, or that wants
/// panic-as-data instead of panic-as-test-failure.
pub async fn concurrent_fire_collect_ordered<F, Fut, R>(
    n: usize,
    builder: F,
) -> ConcurrentRunReport<R>
where
    F: Fn(usize) -> Fut + Send + Sync,
    Fut: Future<Output = R> + Send + 'static,
    R: Send + 'static;

/// Spawn N tasks, all wait on a `tokio::sync::Barrier`, then proceed
/// together. Closes the spawn-skew window: without a barrier, task 0
/// is typically 50–500µs ahead of task N-1; with a barrier they all
/// release within one tokio-scheduler tick.
///
/// When-to-use: outbox/inbox concurrent-claim tests where the test is
/// asserting "two workers race to claim the same row" *and* needs an
/// explicit pre-claim semantic synchronization point (e.g. all N
/// pre-fetch claims_state, then barrier-wait, then race to UPDATE).
/// The barrier is exposed to the caller so the builder can decide
/// where to synchronize.
///
/// Caveat: this variant cannot guarantee the caller actually awaited
/// the barrier. A builder that ignores its `Arc<Barrier>` argument
/// produces the same staggered-start behavior as plain `concurrent_fire`.
/// For tests that just want "all start together, no caller-controlled
/// sync point", use `concurrent_fire_synchronized` (below).
pub async fn concurrent_fire_with_barrier<F, Fut, R>(
    n: usize,
    builder: F,
) -> ConcurrentRunReport<R>
where
    F: Fn(usize, Arc<Barrier>) -> Fut + Send + Sync,
    Fut: Future<Output = R> + Send + 'static,
    R: Send + 'static;

/// Spawn N tasks; the helper itself awaits a `Barrier::new(n)` *immediately
/// before* invoking each `builder(i)` closure, so all N closures begin
/// execution at the same scheduler tick. The barrier is internal to the
/// helper; the caller's builder receives only `i: usize` and runs as if
/// the synchronization never existed.
///
/// When-to-use: tests that simply need "all start together" without a
/// caller-controlled sync point. Idempotency same-key concurrent POST
/// (Phase B test 1), JWT-mutation parametric tests, basic outbox-claim
/// races. Strictly stronger than `concurrent_fire` for catching staggered-
/// start false-negatives, with no API surface caller can leak.
///
/// This is the recommended default. Reach for `concurrent_fire_with_barrier`
/// only when the test needs a *post-prep, pre-race* sync point inside the
/// builder body.
pub async fn concurrent_fire_synchronized<F, Fut, R>(
    n: usize,
    builder: F,
) -> ConcurrentRunReport<R>
where
    F: Fn(usize) -> Fut + Send + Sync,
    Fut: Future<Output = R> + Send + 'static,
    R: Send + 'static;

/// Spawn N tasks, return as soon as the *first* task returns `Ok(_)`
/// (or all N return Err). Cancels the remaining tasks' futures on
/// success.
///
/// When-to-use: state-machine "transition is allowed from this state"
/// tests where any successful transition proves the invariant; or
/// JWT-mutation tests (Phase A.5) where any one of N malformed tokens
/// being accepted is a failure case.
pub async fn concurrent_fire_until_first_success<F, Fut, R, E>(
    n: usize,
    builder: F,
) -> Result<R, Vec<E>>
where
    F: Fn(usize) -> Fut + Send + Sync,
    Fut: Future<Output = Result<R, E>> + Send + 'static,
    R: Send + 'static,
    E: Send + 'static;

/// Spawn N tasks, return as soon as `k` tasks return `Ok(_)`. Aborts
/// the remaining tasks. Returns the first `k` successes in completion
/// order; if fewer than `k` succeed before all N finish, returns Err
/// with the collected errors.
///
/// When-to-use: "exactly K of N concurrent claims succeed" assertions.
/// E.g., concurrent same-key idempotency: K=1 of N=5; concurrent foster
/// home capacity: K=capacity of N=capacity+overflow.
pub async fn concurrent_fire_first_n<F, Fut, R, E>(
    n: usize,
    k: usize,
    builder: F,
) -> Result<Vec<R>, Vec<E>>
where
    F: Fn(usize) -> Fut + Send + Sync,
    Fut: Future<Output = Result<R, E>> + Send + 'static,
    R: Send + 'static,
    E: Send + 'static;

// crates/craig-test-lib/src/fault_injection.rs (post-promotion)
//! Compatibility re-exports. All concrete types now live under
//! `crate::fault::*`. Will be removed in a future release once
//! callers migrate.
pub use crate::fault::cipher::CipherErrorInjector;
pub use crate::fault::rabbit::RabbitDownInjector;
pub use crate::fault::object_store::ObjectStoreErrorInjector;
pub use crate::fault::publish_in_tx::PublishInTxFailureInjector;
// `DbErrorInjector` is intentionally NOT re-exported. Per §D2.0,
// the `PgPool`-wrapping pattern is replaced by codepath-specific
// store traits (FinalizeIdempotencyStore, AttachmentStore, etc.).
// Tests using the inline DbErrorInjector are migrated to the
// matching trait as the seam lands; see §D2.0 sub-pattern (b).

crates/craig-test-lib/src/fault/
├── mod.rs                  # FaultInjector trait + Attempt + ScenarioGuard
├── cipher.rs               # CipherErrorInjector (migrated from inline)
├── rabbit.rs               # RabbitDownInjector
├── object_store.rs         # ObjectStoreErrorInjector
├── publish_in_tx.rs        # PublishInTxFailureInjector
├── stores/                 # NEW — codepath-specific store traits + faulty impls
│   ├── mod.rs              # trait definitions per §D2.0 sub-pattern (b)
│   ├── finalize_idempotency.rs   # FinalizeIdempotencyStore + Faulty impl
│   ├── attachment.rs       # AttachmentStore + Faulty impl
│   ├── outbox.rs           # OutboxStore + Faulty impl
│   ├── inbox.rs            # InboxStore + Faulty impl
│   └── send_job.rs         # SendJobStore + Faulty impl
├── latency.rs              # NEW — LatencyInjector wrapper
├── flap.rs                 # NEW — IntermittentFlapInjector
├── backpressure.rs         # NEW — ConsumerBackpressureInjector
└── scenarios.rs            # NEW — named pre-built Scenario constants

// crates/craig-test-lib/src/fault/mod.rs

/// Common shape every fault injector implements.
pub trait FaultInjector: Send + Sync + 'static {
    /// The `Scenario` type drives this injector's behavior. Distinct
    /// per injector — `CipherScenario`, `DbScenario`, etc.
    type Scenario: Send + Sync + 'static;

    /// Configure the injector with a scenario. Replaces any prior
    /// scenario; returns a `ScenarioGuard` that, when dropped,
    /// asserts the scenario was *consumed* (consume == "the wrapped
    /// callsite was invoked under the scenario at least the expected
    /// number of times"). Use `scenario_guard.disarm()` to opt out
    /// of the assertion (e.g., for pre-condition setup that didn't
    /// actually need the injection to fire).
    #[must_use]
    fn inject(&self, scenario: Self::Scenario) -> ScenarioGuard<'_>;

    /// Audit log: every wrapped-callsite invocation under the active
    /// scenario, in invocation order. Tests use this to assert "the
    /// codepath was reached N times" without coupling to internal
    /// counters.
    fn recorded_attempts(&self) -> Vec<Attempt>;
}

/// One invocation of a fault-injector-wrapped callsite.
#[derive(Debug, Clone)]
pub struct Attempt {
    /// 1-based attempt number under the current scenario.
    pub n: u32,
    /// Wall-clock instant the attempt started.
    pub at: Instant,
    /// Outcome: did the injector return Err (fault injected) or pass
    /// the call through to the underlying real impl (success)?
    pub injected: bool,
    /// Optional per-injector context (e.g., for `ObjectStoreErrorInjector`,
    /// the object key the call was for).
    pub context: Option<String>,
}

/// RAII handle returned by `FaultInjector::inject`. On drop, asserts
/// the scenario's expected-consumption invariant. `disarm()` opts out.
pub struct ScenarioGuard<'a> {
    inner: Box<dyn FnOnce() + 'a>,  // the assertion closure
    armed: bool,
}

impl<'a> ScenarioGuard<'a> {
    pub fn disarm(mut self) { self.armed = false; }
}

impl Drop for ScenarioGuard<'_> {
    fn drop(&mut self) {
        if self.armed && !std::thread::panicking() {
            // Move the closure out via Option-trick.
            // Asserts "scenario was consumed as advertised".
        }
    }
}

// crates/craig-test-lib/src/fault/latency.rs

/// Wrap any `FaultInjector` to add a configurable latency before and/or
/// after each wrapped-callsite invocation. The wrapped injector's
/// scenario fires unchanged; the latency is purely additive.
pub struct LatencyInjector<I: FaultInjector> {
    inner: I,
    before: Option<Duration>,
    after: Option<Duration>,
}

impl<I: FaultInjector> LatencyInjector<I> {
    pub fn new(inner: I) -> Self;
    pub fn with_pre_delay(mut self, d: Duration) -> Self;
    pub fn with_post_delay(mut self, d: Duration) -> Self;
}

// Re-implements FaultInjector by delegating + sleeping.
impl<I: FaultInjector> FaultInjector for LatencyInjector<I> {
    type Scenario = I::Scenario;
    fn inject(&self, scenario: I::Scenario) -> ScenarioGuard<'_> { /* ... */ }
    fn recorded_attempts(&self) -> Vec<Attempt> { /* ... */ }
}

// crates/craig-test-lib/src/fault/flap.rs

/// Configurable cadence pattern of pass-through / inject-error.
pub struct IntermittentFlapInjector<I: FaultInjector> {
    inner: I,
    pattern: Vec<bool>,           // true = inject, false = pass-through
    counter: AtomicUsize,
}

impl<I: FaultInjector> IntermittentFlapInjector<I> {
    /// `pattern.len() >= 1`. The pattern repeats indefinitely:
    /// `[true, false]` = inject every odd attempt;
    /// `[false, false, true]` = inject every 3rd attempt;
    /// `[true, true, true, false]` = "fails 3-of-4".
    pub fn new(inner: I, pattern: Vec<bool>) -> Self;

    /// Convenience: alternating fail-then-succeed.
    pub fn alternating(inner: I) -> Self {
        Self::new(inner, vec![true, false])
    }
}

impl<I: FaultInjector> FaultInjector for IntermittentFlapInjector<I> {
    type Scenario = I::Scenario;
    /* ... */
}

// crates/craig-test-lib/src/fault/backpressure.rs

/// Simulate a slow RabbitMQ consumer that delays its `delivery.ack()`.
/// Wraps a real `lapin::Consumer`-driven loop and inserts a configurable
/// pre-ack sleep; can also drop deliveries silently to simulate hung
/// consumers.
pub struct ConsumerBackpressureInjector {
    /// Per-delivery pre-ack delay. Default `Duration::ZERO`.
    pub ack_delay: Duration,
    /// If `Some(n)`, every nth delivery is *not acked* (simulates a
    /// permanently hung consumer slot).
    pub drop_every_nth: Option<u32>,
    counter: AtomicU32,
    recorded: Mutex<Vec<Attempt>>,
}

impl ConsumerBackpressureInjector {
    pub fn new() -> Self;
    pub fn with_ack_delay(mut self, d: Duration) -> Self;
    pub fn drop_every(mut self, n: u32) -> Self;

    /// Wrap a delivery handler closure to apply the configured back-pressure.
    /// Used by tests that drive a real or fake `lapin::Consumer` stream
    /// through this injector before asserting outbox-depth / DLX behavior.
    pub async fn handle_delivery<F, Fut>(
        &self,
        delivery: lapin::message::Delivery,
        handler: F,
    ) -> anyhow::Result<()>
    where
        F: FnOnce(lapin::message::Delivery) -> Fut,
        Fut: Future<Output = anyhow::Result<()>>;
}

impl FaultInjector for ConsumerBackpressureInjector {
    type Scenario = BackpressureScenario;
    /* ... */
}

pub enum BackpressureScenario {
    Steady { ack_delay: Duration },
    SpikeFor { duration: Duration, ack_delay: Duration },
    HangEveryNth { n: u32 },
}

// crates/craig-test-lib/src/fault/scenarios.rs

//! Named pre-built scenarios for the most common failure-path tests.
//! Tests should prefer these named constants over open-coding scenarios
//! — keeps test intent legible and centralizes "what does 'flaky DB'
//! mean for this codebase" in one place.

use super::*;

pub mod db {
    /// Pool exhaustion after `n` successful queries. Mirrors the
    /// production failure where pgbouncer hits its connection cap.
    pub fn pool_exhausted_after_n(n: u32) -> DbScenario { /* ... */ }

    /// Connection refused on every query. Mirrors the production
    /// failure where the DB is unreachable (e.g., during a Postgres
    /// failover).
    pub fn connection_refused() -> DbScenario { /* ... */ }

    /// Serialization-failure on every query. Mirrors the production
    /// failure where row-level locking + concurrent updates trigger
    /// `serializable_isolation_failure`.
    pub fn serialization_failure() -> DbScenario { /* ... */ }
}

pub mod rmq {
    /// RMQ unreachable for `dur`, then comes back. Models a
    /// short-lived broker outage / failover.
    pub fn flap_for_5s() -> RabbitScenario { flap_for(Duration::from_secs(5)) }
    pub fn flap_for(dur: Duration) -> RabbitScenario { /* ... */ }

    /// Permanently down. Models broker-side cluster failure with no
    /// recovery in test runtime.
    pub fn permanently_down() -> RabbitScenario { /* ... */ }
}

pub mod cipher {
    /// `FieldEncryptor` panics once. Models the corrupted-key case
    /// where the cipher impl panics on bad key material.
    pub fn panic_once() -> CipherScenario { /* ... */ }

    /// `FieldEncryptor` returns Err on next 3 attempts (matches the
    /// inbox max_retries default of 5 attempts so the test can
    /// exercise "3 fails, then succeed" — under-cap retry).
    pub fn err_3_then_succeed() -> CipherScenario { /* ... */ }
}

pub mod object_store {
    /// `Store::put` returns Err for any key matching the prefix.
    pub fn put_failure_for_prefix(prefix: &'static str) -> ObjectStoreScenario { /* ... */ }

    /// `Store::head` returns 404 (key not found) for any key — models
    /// the post-Phase-2-orphan condition where DB has a `pending` row
    /// but the blob never landed.
    pub fn head_404_all() -> ObjectStoreScenario { /* ... */ }
}

// xtask/src/cmd/dev.rs

#[derive(Subcommand)]
pub enum DevCommand {
    /// Start/rebuild all services.
    Start {
        /// Force full rebuild, skip staleness check.
        #[arg(long)]
        force: bool,

        /// Scale specific services. Format: `SERVICE=N[,SERVICE=N…]`.
        /// Each entry must name a service from CRAIG_SERVICES;
        /// N must be ≥1. Repeats with `=1` are no-ops.
        ///
        /// Example: `--replicas craig-cases=2,craig-exchange=2`
        ///
        /// Services not listed default to scale 1 (current behavior).
        ///
        /// Limitations:
        /// * Only stateless CRAIG application services are scalable
        ///   (the 8 in CRAIG_SERVICES). Postgres/RabbitMQ/Keycloak/
        ///   Garage scale to 1 — sharing state requires external
        ///   replication this devstack doesn't model.
        /// * `craig-web` (BFF) is scalable but the 8080 host port
        ///   pins to the first replica. Use `craig-web=1` for now.
        /// * Scaled services lose their fixed host ports; reach them
        ///   by Docker-internal DNS (`craig-cases-1`, `craig-cases-2`)
        ///   from inside the compose network, or by the ephemeral
        ///   host ports surfaced via `docker compose port`.
        #[arg(long, value_parser = parse_replicas)]
        replicas: Vec<ReplicaSpec>,
    },
    // ... rest unchanged
}

#[derive(Debug, Clone)]
pub struct ReplicaSpec {
    pub service: String,
    pub count: u32,
}

fn parse_replicas(raw: &str) -> Result<Vec<ReplicaSpec>, String> {
    let mut out = Vec::new();
    for entry in raw.split(',') {
        let (svc, n) = entry.split_once('=')
            .ok_or_else(|| format!("expected SERVICE=N, got {entry}"))?;
        if !CRAIG_SERVICES.contains(&svc) {
            return Err(format!(
                "unknown service '{svc}'. Allowed: {}",
                CRAIG_SERVICES.join(", ")
            ));
        }
        let count: u32 = n.parse().map_err(|_| format!("non-integer count: {n}"))?;
        if count == 0 {
            return Err(format!("count must be >= 1, got 0 for {svc}"));
        }
        out.push(ReplicaSpec { service: svc.to_string(), count });
    }
    Ok(out)
}

// xtask/src/devstack.rs

pub fn ensure_ready(force: bool, replicas: &[ReplicaSpec]) -> Result<()> { /* ... */ }

pub fn bring_up(no_cache: bool, replicas: &[ReplicaSpec]) -> Result<()> {
    // ... existing port-reservation, compose-up logic ...

    let mut up_args: Vec<String> = vec!["up".into(), "-d".into(), "--build".into()];
    for spec in replicas {
        up_args.push("--scale".into());
        up_args.push(format!("{}={}", spec.service, spec.count));
    }
    docker::compose(&up_args.iter().map(String::as_str).collect::<Vec<_>>())?;

    // health-wait (next section) ...
}

# docker-compose.scale.yml — loaded only when --replicas is non-empty.
# Removes host-port pins from scalable services so docker-compose can
# bind the container ports to ephemeral host ports across replicas.
services:
  craig-rules:
    ports: !override
      - "8001"
  craig-cases:
    ports: !override
      - "8002"
  craig-placement:
    ports: !override
      - "8003"
  craig-exchange:
    ports: !override
      - "8004"
  craig-financial:
    ports: !override
      - "8005"
  craig-reporting:
    ports: !override
      - "8006"
  craig-security:
    ports: !override
      - "8007"
  craig-intake:
    ports: !override
      - "8008"

// xtask/src/devstack.rs (additions)

fn replica_names(svc: &str) -> Result<Vec<String>> {
    // `docker compose ps -a <svc> --format {{.Name}}` returns
    // one line per replica. Trim, filter empties.
    let raw = docker::compose_output(&["ps", "-a", svc, "--format", "{{.Name}}"])?;
    Ok(raw.lines().filter(|l| !l.is_empty()).map(String::from).collect())
}

fn wait_for_service_health_all_replicas(svc: &str) -> Result<()> {
    let replicas = replica_names(svc)?;
    if replicas.is_empty() {
        bail!("no running replicas of {svc} to wait for");
    }
    for name in replicas {
        wait_for_named_health(&name)?;
    }
    Ok(())
}

// crates/craig-test-lib/src/multi_replica.rs (new)

/// Programmatic multi-replica devstack control for tests that drive a
/// dedicated cluster (separate from the pre-push devstack). Tests that
/// run against the *existing* devstack should use the existing
/// `TestHarness` and reach replicas by their compose-network names.
pub struct MultiReplicaCluster {
    workspace_root: std::path::PathBuf,
    replicas: Vec<ReplicaSpec>,
    compose_files: Vec<std::path::PathBuf>,
}

pub struct MultiReplicaClusterBuilder { /* … */ }

impl MultiReplicaCluster {
    pub fn builder() -> MultiReplicaClusterBuilder;

    /// Bring up the cluster. Idempotent — if already up with the same
    /// scale config, no-op.
    pub async fn start(&mut self) -> anyhow::Result<()>;

    /// Tear down the cluster. Always wipes volumes.
    pub async fn stop(self) -> anyhow::Result<()>;

    /// Discover replica host:port endpoints. Iterates `docker compose
    /// port --index N <svc> <port>` for each `index in 1..=count` —
    /// the `--index` flag is **mandatory** here; without it,
    /// `docker compose port <svc> <port>` returns the FIRST replica's
    /// host port only (a silent ambiguity that would make tests pass
    /// against one replica while claiming to test both).
    /// Returns a Vec of `http://localhost:<ephemeral>` URLs, one per
    /// replica of `svc`.
    pub async fn replica_urls(&self, svc: &str) -> anyhow::Result<Vec<String>>;

    /// Reach a specific replica by 1-based index (matching docker
    /// compose's `--index` numbering). Useful for asserting which
    /// replica handled which request (e.g., outbox claim coverage).
    pub async fn replica_url(&self, svc: &str, index: usize) -> anyhow::Result<String>;
}

impl MultiReplicaClusterBuilder {
    pub fn replica(mut self, svc: &str, count: u32) -> Self;
    pub fn extra_compose_file(mut self, path: impl Into<std::path::PathBuf>) -> Self;
    pub fn build(self) -> MultiReplicaCluster;
}

#[tokio::test]
async fn concurrent_same_key_post_to_two_replicas() {
    // Path A: spin up dedicated 2-replica cluster.
    let mut cluster = MultiReplicaCluster::builder()
        .replica("craig-cases", 2)
        .build();
    cluster.start().await.unwrap();

    let urls = cluster.replica_urls("craig-cases").await.unwrap();
    assert_eq!(urls.len(), 2);

    let harness = TestHarness::new().await.unwrap();
    let token = harness.tokens.get_token("admin", "password").await.unwrap();
    let body = serde_json::json!({ "case_number": "FULTON-20260503-DEAD" });
    let key = uuid::Uuid::now_v7().to_string();

    // Fire 5 same-key POSTs across both replicas — alternate by index.
    let report = concurrent_fire_collect_ordered(5, |i| {
        let url = urls[i % 2].clone();
        let token = token.clone();
        let body = body.clone();
        let key = key.clone();
        async move {
            shared_http_client()
                .post(format!("{url}/v1/cases"))
                .bearer_auth(&token)
                .header("Idempotency-Key", &key)
                .json(&body)
                .send()
                .await
                .unwrap()
                .status()
                .as_u16()
        }
    }).await;

    let statuses = report.into_results().unwrap();
    assert_eq!(statuses.len(), 5);
    // Exactly one 200 (winner), four 200s as replays, none as 409
    // (assuming the winner's handler completes inside the 5s ceiling).
    assert!(statuses.iter().all(|s| *s == 200));

    // Path B: query both replicas; assert there's exactly one row in
    // craig-cases' DB matching the case_number. (Single Postgres
    // backs both replicas; if the atomic-claim worked, there's
    // exactly one INSERT.)
    let admin_client = harness.admin_cases_client().await.unwrap();
    let listed = admin_client.list_cases(/* filter by number */).await.unwrap();
    assert_eq!(listed.total, 1);

    cluster.stop().await.unwrap();
}

/// One row of the truth-table input.
#[derive(Debug, Clone, Copy)]
pub struct ValidTransition<S: Copy + Eq + std::fmt::Debug + 'static> {
    pub from: S,
    pub to: S,
}

/// Outcome bucket for a single (from, to) pair.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Outcome {
    /// `reject_fn` returned `Ok(())` and the pair was in the valid list.
    AcceptedValid,
    /// `reject_fn` returned `Err(_)` and the pair was NOT in the valid list.
    RejectedInvalid,
    /// **Bug:** valid pair rejected.
    AcceptedExpectedReject,
    /// **Bug:** invalid pair accepted.
    RejectedExpectedAccept,
    /// `reject_fn` panicked. Always a bug — transition validators must
    /// never panic on bad input strings.
    Panicked(String),
}

/// Result of running a full matrix.
#[derive(Debug, Default)]
pub struct MatrixReport<S> {
    pub total: usize,
    pub accepted_valid: Vec<(S, S)>,
    pub rejected_invalid: Vec<(S, S)>,
    pub mismatches: Vec<(S, S, Outcome)>,
    pub panics: Vec<(S, S, String)>,
}

impl<S> MatrixReport<S>
where
    S: Copy + Eq + std::fmt::Debug,
{
    /// Convenience: `assert!()` no mismatches and no panics. Pretty-prints
    /// the offending pairs into the assertion message.
    pub fn assert_clean(&self);
}

/// Drive a transition predicate against the full Cartesian square of an
/// enum's variants and assert the rejection set is exactly the
/// complement of `valid`.
///
/// `all` enumerates every variant; `valid` lists every accepted ordered
/// pair; `reject_fn` is the function under test (returns `Ok(())` on
/// accept, `Err(_)` on reject; must never panic on well-formed input).
///
/// `reject_fn` runs inside `std::panic::catch_unwind` so a panic on any
/// pair is captured as `Outcome::Panicked` rather than aborting the
/// suite.
pub fn assert_only_valid_transitions_accepted<S, F>(
    all: &[S],
    valid: &[ValidTransition<S>],
    reject_fn: F,
) -> MatrixReport<S>
where
    S: Copy + Eq + std::fmt::Debug + std::panic::UnwindSafe + 'static,
    F: Fn(S, S) -> Result<(), String> + std::panic::UnwindSafe + Copy;

use craig_financial::transitions::{PaymentStatus, validate_payment_transition};
use craig_test_lib::state_machine_matrix::{
    ValidTransition as VT, assert_only_valid_transitions_accepted,
};

const ALL: &[PaymentStatus] = &[
    PaymentStatus::Pending,
    PaymentStatus::Approved,
    PaymentStatus::Issued,
    PaymentStatus::Cleared,
    PaymentStatus::Voided,
];

const VALID: &[VT<PaymentStatus>] = &[
    VT { from: PaymentStatus::Pending,  to: PaymentStatus::Approved },
    VT { from: PaymentStatus::Approved, to: PaymentStatus::Issued },
    VT { from: PaymentStatus::Issued,   to: PaymentStatus::Cleared },
    // any -> voided
    VT { from: PaymentStatus::Pending,  to: PaymentStatus::Voided },
    VT { from: PaymentStatus::Approved, to: PaymentStatus::Voided },
    VT { from: PaymentStatus::Issued,   to: PaymentStatus::Voided },
    VT { from: PaymentStatus::Cleared,  to: PaymentStatus::Voided },
];

#[test]
fn payment_state_machine_matrix_is_exhaustive() {
    let report = assert_only_valid_transitions_accepted(ALL, VALID, |from, to| {
        validate_payment_transition(&from.to_string(), &to.to_string())
    });
    report.assert_clean();
    // 5 × 5 = 25 pairs. 7 valid (above). 18 must reject — including 5 self-loops.
    assert_eq!(report.total, 25);
    assert_eq!(report.accepted_valid.len(), 7);
    assert_eq!(report.rejected_invalid.len(), 18);
}

// crates/craig-auth/src/jwks.rs (additive)

#[cfg(any(test, feature = "test-fixtures"))]
pub mod test_fixtures {
    use super::*;
    use jsonwebtoken::jwk::{Jwk, JwkSet};
    use jsonwebtoken::{Algorithm, EncodingKey};

    /// The shared RSA private key that test middlewares + the
    /// `craig-test-lib::jwt_mutation` helpers sign tokens with.
    /// Identical bytes to `crates/craig-auth/test-fixtures/test_rsa_private.der`.
    pub fn test_encoding_key() -> EncodingKey {
        let der = include_bytes!("../test-fixtures/test_rsa_private.der");
        EncodingKey::from_rsa_der(der)
    }

    /// JWKS containing the public half of [`test_encoding_key`], with
    /// the given `kid`. Mount this on a [`JwksProvider`] via
    /// [`JwksProvider::inject_keys`] (test-only fn — make `pub(crate)`
    /// → `pub` under the same `test-fixtures` feature).
    pub fn test_jwk_set(kid: &str) -> JwkSet {
        let key = test_encoding_key();
        let mut jwk = Jwk::from_encoding_key(&key, Algorithm::RS256)
            .expect("build JWK from RSA test key");
        jwk.common.key_id = Some(kid.to_string());
        JwkSet { keys: vec![jwk] }
    }
}

/// Mutable JWT claim set under construction. All getters/setters are
/// chainable; finalize with [`mint`].
///
/// Defaults (set by `ClaimsBuilder::baseline`): valid sub, future exp
/// (1h), past iat, `iss = TEST_ISSUER`, `aud = ["craig-cases"]` (caller
/// overrides for other services), `typ = "Bearer"`, no scope.
#[derive(Debug, Clone)]
pub struct ClaimsBuilder {
    sub: String,
    iss: String,
    aud: Option<Vec<String>>,
    azp: Option<String>,
    typ: Option<String>,
    scope: Option<String>,
    exp: i64,
    nbf: Option<i64>,
    iat: i64,
    realm_roles: Vec<String>,
    extra: serde_json::Map<String, serde_json::Value>,
    alg: jsonwebtoken::Algorithm,
    kid: String,
}

impl ClaimsBuilder {
    /// Construct a baseline that, when minted, validates against a
    /// JwksProvider configured for `service_aud`. All single-axis
    /// mutators below derive from this.
    pub fn baseline(service_aud: &str) -> Self;

    /// Override the audience claim. Pass `&["craig-cases"]` to scope
    /// to a single service; pass `&[]` then `.without_aud()` to drop
    /// the claim entirely.
    pub fn with_aud(mut self, aud: &[&str]) -> Self;

    /// Drop the `aud` claim. Used to assert the validator rejects
    /// audience-less tokens (ADR-021).
    pub fn without_aud(mut self) -> Self;

    /// Override the `typ` header/claim. ADR-021 requires `"Bearer"`;
    /// passing `"Refresh"` or `"ID"` must be rejected.
    pub fn with_typ(mut self, typ: &str) -> Self;

    /// Set the scope claim. RFC 6749 space-separated string.
    pub fn with_scope(mut self, scope: &str) -> Self;

    /// Set the authorized-party claim. ADR-021 surface; for `craig-ui`
    /// vs `craig-api` distinction.
    pub fn with_azp(mut self, azp: &str) -> Self;

    /// Construct an expired token. `expired(Duration::from_secs(60))`
    /// sets `exp = now - 60s`.
    pub fn expired(mut self, ago: std::time::Duration) -> Self;

    /// Construct a not-yet-valid token via `nbf`.
    pub fn not_yet_valid(mut self, ahead: std::time::Duration) -> Self;

    /// Override the signing algorithm. Pass `Algorithm::HS256` to
    /// assert RS256-only validators reject. Note: `jsonwebtoken` 10.3
    /// does NOT expose `Algorithm::None`. The "alg=none" attack is
    /// covered by `with_unsigned()` below, which manually constructs
    /// the compact JWT with header `{"alg":"none"}` and an empty
    /// signature segment per RFC 7515 §6.1.
    pub fn with_alg(mut self, alg: jsonwebtoken::Algorithm) -> Self;

    /// Manually construct an unsigned JWT (`{"alg":"none"}` header +
    /// claims + empty signature segment). Cannot use `jsonwebtoken::encode`
    /// because the crate intentionally drops `Algorithm::None` support.
    /// Mint path:
    ///   header_b64  = base64url("{\"alg\":\"none\",\"typ\":\"JWT\"}")
    ///   payload_b64 = base64url(serde_json::to_vec(&self.claims))
    ///   token       = format!("{header_b64}.{payload_b64}.")  // empty signature
    /// Validators that fail to enforce an algorithm allowlist will
    /// accept this token; the test asserts they reject.
    pub fn with_unsigned(mut self) -> Self;

    /// Sign with a kid that does NOT exist in the JWKS — exercises
    /// kid-mismatch rejection.
    pub fn with_unknown_kid(mut self) -> Self;

    /// Inject an additional top-level claim (negative-test for unknown
    /// claim acceptance, or positive-test for service-specific claims).
    pub fn with_extra_claim(mut self, key: &str, value: serde_json::Value) -> Self;

    /// Mint the token. Fails only on RSA signing errors (i.e. never
    /// in supported configs).
    pub fn mint(&self) -> String;
}

/// Identifies the single axis a mutation perturbs. Used in test
/// failure messages so a 1-of-N parametric test pinpoints which
/// strictness rule the validator broke.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MutationKind {
    AudMissing,
    AudWrongRealm,
    AudWrongService,
    TypMissing,
    TypNotBearer,
    AzpWrongClient,
    ScopeMissing,        // only emitted when baseline declares a required scope
    ScopeInsufficient,
    Expired1s,
    Expired1h,
    NotYetValid1m,
    AlgNone,             // alg=none attack
    AlgConfusionHs256,   // HS256 against an RS256-pinned validator
    UnknownKid,
    SubMissing,
    IssWrongRealm,
}

pub struct MutatedToken {
    pub kind: MutationKind,
    pub jwt: String,
    /// The expected `craig_common::error::ApiError` variant. Matched
    /// stringly by the harness because the variants are large and
    /// `PartialEq` is not derived.
    pub expected_api_error: &'static str,
}

/// Yield one [`MutatedToken`] per single-axis mutation against the
/// given baseline. The base must already mint a valid token against
/// the service under test.
pub fn mutation_matrix(base: ClaimsBuilder) -> impl Iterator<Item = MutatedToken>;

use craig_test_lib::jwt_mutation::{ClaimsBuilder, mutation_matrix};

#[test]
fn baseline_token_validates() {
    // Sanity check: the base case mints a token the validator accepts.
    let token = ClaimsBuilder::baseline("craig-cases").mint();
    let provider = test_provider_for_audience("craig-cases").await;
    assert!(provider.validate_token(&token).await.is_ok());
}

#[test]
fn every_single_axis_mutation_is_rejected_by_craig_cases_validator() {
    let base = ClaimsBuilder::baseline("craig-cases");
    let provider = test_provider_for_audience("craig-cases");
    let mut failures = Vec::new();
    for m in mutation_matrix(base) {
        match provider.validate_token(&m.jwt).await {
            Ok(_) => failures.push(format!("{:?} unexpectedly accepted", m.kind)),
            Err(e) if e.to_string().contains(m.expected_api_error) => {} // pass
            Err(e) => failures.push(
                format!("{:?} rejected with wrong error: got {e}, want {}",
                    m.kind, m.expected_api_error)),
        }
    }
    assert!(failures.is_empty(), "JWT mutation regressions: {failures:#?}");
}

/// Stable identifier for a fixture file. Variants map 1:1 to D6.1 entries.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FixtureName {
    PeDisguisedAsPdf,
    ElfDisguisedAsJpeg,
    ZipBombDisguisedAsCsv,
    ScriptDisguisedAsPng,
    TruncatedPdfFirst8Bytes,
    XmlWithExternalEntity,
    ValidPdf,
    ValidJpeg,
    ValidPng,
    ValidCsv,
}

/// Static fixture bytes. Compiled into the test binary via `include_bytes!`.
pub fn fixture(name: FixtureName) -> &'static [u8];

/// One spoof case: the bytes, the lying declared MIME, and the
/// `StoreError` variant the validator must surface.
pub struct SpoofFixture {
    pub name: FixtureName,
    pub declared_mime: &'static str,
    pub body: &'static [u8],
    /// Stringly matched against `StoreError::to_string()` because
    /// `StoreError` does not implement `PartialEq`.
    pub expected_rejection: &'static str,
}

/// Iterate every spoofing case (excludes the valid-companion fixtures).
/// 6 cases today; grows as new spoof classes are added.
pub fn enumerate_spoofs() -> impl Iterator<Item = SpoofFixture>;

/// Iterate every valid-companion fixture for happy-path tests.
pub fn enumerate_valid() -> impl Iterator<Item = SpoofFixture>; // body + true MIME

/// One filename-attack case. `expected_sanitized` is the exact bytes
/// `sanitize_filename` must return; `expected_disposition` is the exact
/// header value `RFC 5987` Content-Disposition encoding must produce
/// (None when the case is rejected outright).
pub struct FilenameCase {
    pub name: &'static str,
    pub raw: &'static str,
    pub expected_sanitized: Result<&'static str, &'static str>,
    pub expected_disposition: Option<&'static str>,
}

pub const CASES: &[FilenameCase] = &[
    FilenameCase {
        name: "double_quote",
        raw: r#"my"file.pdf"#,
        // Quote is preserved by sanitize_filename today. The download
        // path Content-Disposition encoder must escape it.
        expected_sanitized: Ok(r#"my"file.pdf"#),
        expected_disposition: Some(
            r#"attachment; filename="my\"file.pdf"; filename*=UTF-8''my%22file.pdf"#),
    },
    FilenameCase {
        name: "crlf_injection",
        raw: "ok.pdf\r\nSet-Cookie: x=y",
        // CRLF is not stripped today; the encoder is responsible for
        // % -encoding it. If sanitize_filename later starts rejecting
        // CRLF, flip expected_sanitized to Err and drop disposition.
        expected_sanitized: Ok("ok.pdfSet-Cookie: x=y"),
        expected_disposition: Some(
            r#"attachment; filename="ok.pdfSet-Cookie: x=y"; filename*=UTF-8''ok.pdf%0D%0ASet-Cookie%3A%20x%3Dy"#),
    },
    FilenameCase {
        name: "nul_byte",
        raw: "ok\0.pdf",
        expected_sanitized: Ok("ok.pdf"),
        expected_disposition: Some(r#"attachment; filename="ok.pdf"; filename*=UTF-8''ok.pdf"#),
    },
    FilenameCase {
        name: "backslash",
        raw: r"a\b\c.pdf",
        expected_sanitized: Ok("abc.pdf"),
        expected_disposition: Some(r#"attachment; filename="abc.pdf"; filename*=UTF-8''abc.pdf"#),
    },
    FilenameCase {
        name: "forward_slash",
        raw: "a/b/c.pdf",
        expected_sanitized: Ok("abc.pdf"),
        expected_disposition: Some(r#"attachment; filename="abc.pdf"; filename*=UTF-8''abc.pdf"#),
    },
    FilenameCase {
        name: "leading_trailing_whitespace",
        raw: "   spaced.pdf   ",
        expected_sanitized: Ok("spaced.pdf"),
        expected_disposition: Some(r#"attachment; filename="spaced.pdf"; filename*=UTF-8''spaced.pdf"#),
    },
    FilenameCase {
        name: "length_256",
        raw: "<256 'a' chars>.pdf",
        // 255-byte char-boundary truncation — see validation.rs
        // sanitize_truncates_at_char_boundary_for_multibyte_input.
        expected_sanitized: Ok("<255 'a' chars>"),
        expected_disposition: Some(r#"attachment; filename="<255 'a' chars>"; filename*=UTF-8''<...>"#),
    },
    FilenameCase {
        name: "unicode_resume",
        raw: "résumé.pdf",
        expected_sanitized: Ok("résumé.pdf"),
        expected_disposition: Some(r#"attachment; filename="r__sum__.pdf"; filename*=UTF-8''r%C3%A9sum%C3%A9.pdf"#),
    },
    FilenameCase {
        name: "rtlo_override",
        raw: "fdp.\u{202E}exe", // U+202E RIGHT-TO-LEFT OVERRIDE — renders "exe.pdf" in many UIs
        // RTLO must be stripped: it has no semantic in a filename and
        // the rendering surface gets to lie to the user.
        expected_sanitized: Ok("fdp.exe"),
        expected_disposition: Some(r#"attachment; filename="fdp.exe"; filename*=UTF-8''fdp.exe"#),
    },
    FilenameCase {
        name: "unc_path",
        raw: r"\\evil.example.com\share\f.pdf",
        expected_sanitized: Ok("evil.example.comsharef.pdf"),
        expected_disposition: Some(
            r#"attachment; filename="evil.example.comsharef.pdf"; filename*=UTF-8''evil.example.com%5Cshare%5Cf.pdf"#),
    },
    FilenameCase {
        name: "all_dots",
        raw: "...",
        expected_sanitized: Err("InvalidFilename"),
        expected_disposition: None,
    },
    FilenameCase {
        name: "fullwidth_dot",
        raw: "f\u{FF0E}exe", // U+FF0E FULLWIDTH FULL STOP — visually `.` but not the path-separator char
        expected_sanitized: Ok("f\u{FF0E}exe"),
        expected_disposition: Some(r#"attachment; filename="f.exe"; filename*=UTF-8''f%EF%BC%8Eexe"#),
    },
];

craig-cases → [dev-dep] → craig-test-lib → [dep] → craig-cases   # cycle

# crates/craig-cases-contracts/Cargo.toml (new)
[package]
name = "craig-cases-contracts"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { workspace = true, features = ["derive"] }
serde_json = { workspace = true }     # only if any DTO field needs Value
chrono = { workspace = true }
uuid = { workspace = true, features = ["serde"] }
utoipa = { workspace = true, features = ["chrono", "uuid"] }
craig-reference = { workspace = true } # if DTOs use shared enums
# NO dependency on craig-cases or craig-test-lib

// crates/craig-cases-contracts/src/lib.rs (new)
pub mod cases;
pub mod persons;
pub mod referrals;
// ... one module per api submodule with public DTOs

// services/craig-cases/Cargo.toml — add a non-dev dep
[dependencies]
craig-cases-contracts = { workspace = true }

// services/craig-cases/src/api/dto.rs (existing)
pub use craig_cases_contracts::cases::*;
pub use craig_cases_contracts::persons::*;
// internal re-export so existing handler code at `crate::api::dto::*` keeps working

// crates/craig-test-lib/Cargo.toml — add per-service contracts dev-deps only
[dev-dependencies]
craig-cases-contracts = { workspace = true }
craig-placement-contracts = { workspace = true }
craig-exchange-contracts = { workspace = true }
craig-financial-contracts = { workspace = true }
craig-reporting-contracts = { workspace = true }
craig-rules-contracts = { workspace = true }
craig-security-contracts = { workspace = true }
craig-intake-contracts = { workspace = true }

// crates/craig-test-lib/src/clients/cases.rs (rewritten in Step 9)
use craig_cases_contracts::cases::{CreateCaseRequest, CaseResponse};
use craig_cases_contracts::persons::{CreatePersonRequest, PersonResponse, ListPersonsResponse};
// no `use craig_cases::*;` — no cycle.

pub async fn search_persons(&self, params: &[(&str, &str)]) -> Result<ApiResponse<Value>> {
    self.inner
        .get_with_query("/v1/cases/persons", &params.to_vec())
        .await
}

use craig_cases::{ListPersonsResponse, ListPersonsQuery};

pub async fn search_persons(&self, query: &ListPersonsQuery) -> Result<ApiResponse<ListPersonsResponse>> {
    self.inner
        .get_with_query("/v1/cases/persons", &query.to_query_pairs())
        .await
}

// today
pub async fn create_person(&self, body: &Value) -> Result<ApiResponse<Value>> {
    self.inner.post("/v1/cases/persons", body).await
}

// tomorrow
use craig_cases::{CreatePersonRequest, PersonResponse};

pub async fn create_person(&self, body: &CreatePersonRequest) -> Result<ApiResponse<PersonResponse>> {
    self.inner.post("/v1/cases/persons", body).await
}

// tests/typed/cases_client.rs (lands with MR 1)

use craig_cases::{CreatePersonRequest, PersonResponse};
use craig_test_lib::{TestHarness, devstack_available};

#[tokio::test]
async fn create_person_typed_round_trip() {
    if !devstack_available().await { return; }
    let harness = TestHarness::new().await;
    let client = harness.caseworker_cases_client();

    let req = CreatePersonRequest {
        first_name: "Round".into(),
        last_name:  "Trip".into(),
        // … every required field. Compile fails if a field is missing
        // or renamed — caught in CI rather than in a flaky `null` deref.
    };
    let resp = client.create_person(&req).await.unwrap();
    assert_eq!(resp.status, reqwest::StatusCode::CREATED);

    let person: &PersonResponse = resp.body.as_ref().unwrap();
    assert_eq!(person.first_name, "Round");
    // No more `body["first_name"].as_str().unwrap()` — direct field access.
}

# Cargo.toml [workspace.dependencies]
# Property-based testing — used in `tests/properties/<prop>.rs` per testing.md.
proptest = "1.7"   # latest stable as of 2026-05; verify on commit via `cargo search proptest`

# crates/craig-store/Cargo.toml
[dev-dependencies]
proptest = { workspace = true }

use proptest::prelude::*;
// PaymentStatus actually lives at services/craig-financial/src/transitions.rs:11,
// NOT in craig-reference. Five variants only — no Draft, Disbursed, Reversed, Cancelled.
use craig_financial::transitions::{PaymentStatus, validate_payment_transition};

fn any_status() -> impl Strategy<Value = PaymentStatus> {
    prop_oneof![
        Just(PaymentStatus::Pending),
        Just(PaymentStatus::Approved),
        Just(PaymentStatus::Issued),
        Just(PaymentStatus::Cleared),
        Just(PaymentStatus::Voided),
    ]
}

proptest! {
    #![proptest_config(ProptestConfig::with_cases(512))]
    #[test]
    fn prop_payment_can_transition_matches_validator(
        from in any_status(),
        to in any_status(),
    ) {
        let enum_says = from.can_transition_to(to);
        let validator_result = validate_payment_transition(from.as_str(), to.as_str());
        prop_assert_eq!(enum_says, validator_result.is_ok(),
            "enum/validator disagree for {from:?} -> {to:?}");
    }
}

use proptest::prelude::*;
use craig_api::pagination::{PageRequest, paginate};

fn any_dataset() -> impl Strategy<Value = Vec<u64>> {
    proptest::collection::vec(0u64..1_000_000, 0..500)
        .prop_map(|mut v| { v.sort(); v.dedup(); v })
}

proptest! {
    #[test]
    fn prop_pagination_no_dupes_no_drops(
        data in any_dataset(),
        per_page in 1usize..50,
    ) {
        let total = data.len();
        let pages: Vec<_> = (1..=total.div_ceil(per_page).max(1))
            .map(|p| paginate(&data, PageRequest { page: p, per_page }))
            .collect();

        // each page len <= per_page
        for p in &pages { prop_assert!(p.items.len() <= per_page); }
        // ordering monotonic across pages
        let flat: Vec<_> = pages.iter().flat_map(|p| p.items.iter().copied()).collect();
        for w in flat.windows(2) { prop_assert!(w[0] <= w[1]); }
        // no duplicates across pages
        let mut seen = std::collections::HashSet::new();
        for x in &flat { prop_assert!(seen.insert(*x)); }
        // total reachable equals input
        prop_assert_eq!(flat.len(), total);
    }
}

use proptest::prelude::*;
use craig_store::validation::sanitize_filename;

proptest! {
    #![proptest_config(ProptestConfig::with_cases(1024))]
    #[test]
    fn prop_sanitize_filename_invariants(s in ".{0,256}") {
        let Ok(out) = sanitize_filename(&s) else {
            // Empty-after-sanitization → Err is correct behavior; skip this case.
            return Ok(());
        };
        for ch in out.chars() {
            prop_assert!(!matches!(ch, '/' | '\\' | '\0'),
                "forbidden char {ch:?} survived sanitization of {s:?}");
            prop_assert!(!ch.is_control(),
                "control char {ch:?} survived sanitization");
        }
        prop_assert!(!out.is_empty(), "Ok arm returned empty string");
        let twice = sanitize_filename(&out)
            .expect("Ok output must itself be sanitizable to Ok");
        prop_assert_eq!(twice, out, "non-idempotent: f(f(x)) != f(x)");
        prop_assert!(out.len() <= 255, "output exceeds 255-byte cap: {}", out.len());
    }
}

use proptest::prelude::*;
use craig_store::validation::content_disposition_attachment;

/// Reference parser using the `headers` crate (or hand-rolled per RFC 6266 §5).
fn parse_filename_star(header_value: &str) -> Option<String> { /* ... */ }

proptest! {
    #![proptest_config(ProptestConfig::with_cases(512))]
    #[test]
    fn prop_content_disposition_round_trip(name in "[\\PC]{1,200}") {
        // \PC = any non-control char, including non-ASCII for the filename* field.
        let header = content_disposition_attachment(&name);
        prop_assert!(header.starts_with("attachment;"),
            "header missing attachment disposition: {header}");
        prop_assert!(header.contains("filename*=UTF-8''"),
            "header missing RFC 5987 extended form: {header}");

        let recovered = parse_filename_star(&header)
            .expect("parser must recover filename*");
        prop_assert_eq!(recovered, name);
    }
}

use proptest::prelude::*;
use craig_signing::{canonicalize_json, hash_payload};
use serde_json::Value;

fn any_json_leaf() -> impl Strategy<Value = Value> {
    prop_oneof![
        Just(Value::Null),
        any::<bool>().prop_map(Value::Bool),
        (-1_000_000i64..1_000_000).prop_map(|n| Value::from(n)),
        "[\\PC]{0,32}".prop_map(Value::from),
    ]
}
fn any_json() -> impl Strategy<Value = Value> {
    let leaf = any_json_leaf();
    leaf.prop_recursive(4, 16, 8, |inner| {
        prop_oneof![
            proptest::collection::vec(inner.clone(), 0..6).prop_map(Value::Array),
            proptest::collection::hash_map("[a-z]{1,8}", inner, 0..6)
                .prop_map(|m| serde_json::to_value(m).unwrap()),
        ]
    })
}

proptest! {
    #![proptest_config(ProptestConfig::with_cases(256))]
    #[test]
    fn prop_canonical_hash_invariant_to_whitespace_and_key_order(v in any_json()) {
        let canonical_a = canonicalize_json(&v);
        let hash_a = hash_payload(&canonical_a);

        // Round-trip through pretty-printer reshuffles HashMap iteration order
        // and inserts whitespace; canonicalize must recover identical bytes.
        let pretty = serde_json::to_string_pretty(&v).unwrap();
        let v_round: Value = serde_json::from_str(&pretty).unwrap();
        let canonical_b = canonicalize_json(&v_round);
        let hash_b = hash_payload(&canonical_b);

        prop_assert_eq!(canonical_a, canonical_b,
            "canonical string changed under whitespace/key-order normalization");
        prop_assert_eq!(hash_a, hash_b,
            "hash changed under whitespace/key-order normalization");
    }
}

use proptest::prelude::*;
use craig_api::idempotency::body_fingerprint; // requires the pub-visibility flip noted above

proptest! {
    #![proptest_config(ProptestConfig::with_cases(512))]
    #[test]
    fn prop_fingerprint_equal_iff_bytes_equal(
        a in proptest::collection::vec(any::<u8>(), 0..2048),
        b in proptest::collection::vec(any::<u8>(), 0..2048),
    ) {
        let fa = body_fingerprint(&a);
        let fb = body_fingerprint(&b);
        prop_assert_eq!(fa == fb, a == b);
    }

    #[test]
    fn prop_fingerprint_one_byte_flip_differs(
        bytes in proptest::collection::vec(any::<u8>(), 1..1024),
        idx in any::<prop::sample::Index>(),
    ) {
        let i = idx.index(bytes.len());
        let mut flipped = bytes.clone();
        flipped[i] = flipped[i].wrapping_add(1);
        prop_assert_ne!(body_fingerprint(&bytes), body_fingerprint(&flipped));
    }
}

use proptest::prelude::*;
use std::str::FromStr;
use craig_reference::{
    PaymentStatus, PlacementStatus, ContactType, ReportStatus,
    AdminUnit, FipsCode, EventType,
};

macro_rules! prop_no_panic {
    ($t:ty, $name:ident) => {
        proptest! {
            #![proptest_config(ProptestConfig::with_cases(2048))]
            #[test]
            fn $name(s in ".{0,64}") {
                // Catch panics; success or failure is fine, panic is not.
                let _ = std::panic::catch_unwind(|| <$t>::from_str(&s));
            }
        }
    };
}

prop_no_panic!(PaymentStatus,    prop_payment_status_no_panic);
prop_no_panic!(PlacementStatus,  prop_placement_status_no_panic);
prop_no_panic!(ContactType,      prop_contact_type_no_panic);
prop_no_panic!(ReportStatus,     prop_report_status_no_panic);
prop_no_panic!(EventType,        prop_event_type_no_panic);
prop_no_panic!(FipsCode,         prop_fips_code_no_panic);

# .cargo/mutants.toml — workspace-level config (committed)
# cargo-mutants 25.x is the actively-maintained line as of 2026-05.
# Pin via `cargo install cargo-mutants --version "^25.0" --locked`.
timeout = 300                    # per-mutant cap (seconds); kills hangs
test_tool = "nextest"            # use the same runner as the rest of CRAIG
test_package = ["--locked"]
exclude_globs = [
    "**/tests/**",
    "**/examples/**",
    "**/benches/**",
    "**/build.rs",
    "**/main.rs",                # boot/wiring code; mutants here surface as test-harness gaps, not invariants
]

pub mod reliability;
pub mod contracts;
pub mod mutants;
pub mod coverage_matrix;
pub mod invariants;
pub mod quality_budgets;        // §D12

#[derive(Subcommand)]
pub enum Command {
    Dev(dev::DevArgs),
    Test(test::TestArgs),
    E2e(e2e::E2eArgs),
    Validate(validate::ValidateArgs),
    CheckDocs(check_docs::CheckDocsArgs),
    Perf(perf::PerfArgs),
    Security(security::SecurityArgs),
    Sbom,
    ApiDocs(api_docs::ApiDocsArgs),
    Reconcile(reconcile::ReconcileArgs),

    /// Run reliability suite (concurrency / recovery / fault / invariants / properties)
    Reliability(reliability::ReliabilityArgs),
    /// Run typed-client contract tests
    Contracts(contracts::ContractsArgs),
    /// Run cargo-mutants on the 5 critical crates (smoke) or workspace (--full)
    Mutants(mutants::MutantsArgs),
    /// Generate the route × test-axis coverage matrix
    CoverageMatrix(coverage_matrix::CoverageMatrixArgs),
    /// Run platform-invariant tests (atomic-claim, FUSL, processed-state, ...)
    Invariants(invariants::InvariantsArgs),
    /// Report or enforce code-quality budgets (§D12)
    QualityBudgets(quality_budgets::QualityBudgetsArgs),
}

use anyhow::{Context, Result, bail};
use clap::Args;
use std::process::Command;

const ENTRY_BANNER: &str =
    "Reliability suite (opt-in; not part of pre-push gate). \
     See plans/test-framework-hardening.adoc §D11.";

const NEXTEST_FILTER: &str = "test(::concurrency::) \
                            | test(::recovery::) \
                            | test(::fault::) \
                            | test(::invariants::) \
                            | test(::properties::)";

#[derive(Args)]
pub struct ReliabilityArgs {
    /// Optional nextest filter to AND with the default reliability filter.
    #[arg(long)]
    pub filter: Option<String>,
}

pub fn run(args: ReliabilityArgs) -> Result<()> {
    println!("=== {ENTRY_BANNER} ===");
    let mut filter = NEXTEST_FILTER.to_string();
    if let Some(extra) = args.filter {
        filter = format!("({filter}) & ({extra})");
    }
    let status = Command::new("cargo")
        .args(["nextest", "run", "--workspace", "--locked", "-E", &filter])
        .status()
        .context("spawn cargo nextest")?;
    if !status.success() { bail!("reliability suite failed with {status}"); }
    println!("=== Reliability OK ===");
    Ok(())
}

use anyhow::{Context, Result, bail};
use clap::Args;
use std::process::Command;

const SMOKE_CRATES: &[&str] = &[
    "crates/craig-api",
    "crates/craig-mq",
    "crates/craig-auth",
    "crates/craig-store",
    "services/craig-cases",
];

#[derive(Args)]
pub struct MutantsArgs {
    /// Run full workspace mutation testing (no per-crate filter)
    #[arg(long, conflicts_with = "smoke")]
    pub full: bool,
    /// Run the smoke profile against the 5 critical crates (default)
    #[arg(long)]
    pub smoke: bool,
}

pub fn run(args: MutantsArgs) -> Result<()> {
    println!("=== cargo-mutants (opt-in; not part of pre-push gate). \
              Surviving mutants catalogued in xtask/mutants-baseline.toml. ===");

    if !is_installed() {
        bail!("cargo-mutants is not installed. Install with:\n\
               cargo install cargo-mutants --version \"^25.0\" --locked");
    }

    let crates: Vec<&str> = if args.full { vec![] } else { SMOKE_CRATES.into() };

    if crates.is_empty() {
        run_one(None)?;
    } else {
        for c in &crates { run_one(Some(c))?; }
    }
    summarize()?;
    println!("=== Mutants OK (see target/mutants-summary.json) ===");
    Ok(())
}

fn is_installed() -> bool {
    Command::new("cargo").args(["mutants", "--version"]).output()
        .map(|o| o.status.success()).unwrap_or(false)
}
fn run_one(scope: Option<&str>) -> Result<()> { /* ... cargo mutants --in-place --jobs 1 [--in-dir scope] ... */ Ok(()) }
fn summarize() -> Result<()> { /* aggregate per-crate target/mutants-*/outcomes.json into target/mutants-summary.json */ Ok(()) }

use anyhow::{Context, Result, bail};
use clap::Args;
use std::process::Command;

#[derive(Args)]
pub struct ContractsArgs {
    /// Restrict to a specific service (cases, exchange, ...)
    #[arg(long)]
    pub service: Option<String>,
}

pub fn run(args: ContractsArgs) -> Result<()> {
    println!("=== Typed-client contract tests (opt-in; not part of pre-push gate). ===");
    let filter = match args.service.as_deref() {
        Some(s) => format!("test(::typed::{s}::)"),
        None    => "test(::typed::)".to_string(),
    };
    let status = Command::new("cargo")
        .args(["nextest", "run", "--workspace", "--locked", "-E", &filter])
        .status().context("spawn cargo nextest")?;
    if !status.success() { bail!("contracts suite failed"); }
    Ok(())
}

use anyhow::Result;
use clap::Args;

#[derive(Args)]
pub struct CoverageMatrixArgs { /* see §D13 */ }

pub fn run(args: CoverageMatrixArgs) -> Result<()> {
    println!("=== Coverage matrix (opt-in; report-only, no enforcement gate). ===");
    crate::cmd::coverage_matrix::generate(args)   // module-private fn from §D13
}

pub fn run(_: InvariantsArgs) -> Result<()> {
    println!("=== Invariant tests (opt-in; not part of pre-push gate). ===");
    let status = Command::new("cargo")
        .args(["nextest", "run", "--workspace", "--locked",
               "-E", "test(::invariants::)"])
        .status()?;
    if !status.success() { bail!("invariant suite failed"); }
    Ok(())
}

# xtask/quality-budgets.toml
# Code-quality budgets — report-only as of test-framework-hardening Step 13.
# `--fail-on-regression` reads thresholds; `--report` emits a table.

[B1.route_module_loc]
threshold = 500
glob      = ["services/*/src/api/*.rs", "services/craig-web/src/routes/*.rs"]
exceptions = [
    # Examples — empty initially; new exceptions require a reason field
    # { path = "services/craig-cases/src/api/reports.rs", reason = "tracked: split-pending #282" },
]

[B2.function_loc]
threshold = 100
glob      = ["**/*.rs"]
exclude   = ["**/tests/**"]

[B3.serde_json_value]
threshold_src   = 0
threshold_tests = 5
src_glob        = ["**/src/**/*.rs"]
src_exclude     = ["**/api/dto.rs", "**/api/dto/**/*.rs"]
tests_glob      = ["**/tests/**/*.rs"]

[B4.allow_attributes]
threshold = 20

[B5.unwrap_or_default]
threshold = 50
glob      = ["**/src/**/*.rs"]

[B6.duplicate_deps]
threshold = 0
# Baseline captured in xtask/quality-budgets.lock; B6 reports delta vs lock.

[B7.untyped_test_client_methods]
threshold = 0
# Counts methods returning `serde_json::Value` from craig-test-lib clients.
glob      = ["crates/craig-test-lib/src/clients/*.rs"]

# xtask/quality-budgets.lock — generated by `cargo xtask quality-budgets --report --write-lock`
# Tracks the COUNT (not threshold) at the time of the lock. Regression check
# under `--fail-on-regression` reads BOTH the threshold and the lock and fails
# if `count > max(threshold, lock)`.
[counts]
B1_route_module_loc      = 0      # LOC over threshold; populated on first run
B2_function_loc          = 0
B3_serde_json_value_src  = 0
B3_serde_json_value_test = 0
B4_allow_attributes      = 0
B5_unwrap_or_default     = 0
B6_duplicate_deps        = 0
B7_untyped_test_methods  = 0
generated_at = "2026-05-03T00:00:00Z"
generated_from_sha = "<git-rev>"

use anyhow::Result;
use clap::Args;

#[derive(Args)]
pub struct QualityBudgetsArgs {
    /// Print the budget table (default mode)
    #[arg(long, conflicts_with = "fail_on_regression")]
    pub report: bool,
    /// Exit non-zero if any budget exceeded (NOT run in pre-push today)
    #[arg(long)]
    pub fail_on_regression: bool,
    /// Update xtask/quality-budgets.lock with current counts
    #[arg(long, requires = "report")]
    pub write_lock: bool,
}

#[derive(Debug)]
struct BudgetReport {
    id: &'static str,
    name: &'static str,
    threshold: usize,
    locked: usize,
    actual: usize,
}

pub fn run(args: QualityBudgetsArgs) -> Result<()> {
    println!("=== Quality budgets (report-only; not a pre-push gate). ===");
    let cfg = read_config()?;
    let lock = read_lock()?;
    let reports = vec![
        run_b1_route_module_loc(&cfg, &lock)?,
        run_b2_function_loc(&cfg, &lock)?,
        run_b3_serde_json_value(&cfg, &lock)?,
        run_b4_allow_attributes(&cfg, &lock)?,
        run_b5_unwrap_or_default(&cfg, &lock)?,
        run_b6_duplicate_deps(&cfg, &lock)?,
        run_b7_untyped_test_methods(&cfg, &lock)?,
    ];
    print_table(&reports);
    if args.write_lock { write_lock(&reports)?; }
    if args.fail_on_regression {
        let regressed: Vec<_> = reports.iter()
            .filter(|r| r.actual > r.threshold.max(r.locked))
            .collect();
        if !regressed.is_empty() {
            anyhow::bail!("{} budget(s) regressed", regressed.len());
        }
    }
    Ok(())
}

fn print_table(rows: &[BudgetReport]) { /* tabled — same crate already in workspace */ }
fn read_config()  -> Result<Config> { /* parse xtask/quality-budgets.toml */ Ok(Default::default()) }
fn read_lock()    -> Result<Lock>   { /* parse xtask/quality-budgets.lock */ Ok(Default::default()) }
fn write_lock(_reports: &[BudgetReport]) -> Result<()> { Ok(()) }
fn run_b1_route_module_loc(_: &Config, _: &Lock) -> Result<BudgetReport> { todo!() }
// ... B2..B7

=== Quality budgets (report-only; not a pre-push gate). ===
+-----+----------------------------------+--------+--------+--------+--------+
| ID  | Name                             | Thresh | Locked | Actual | Status |
+-----+----------------------------------+--------+--------+--------+--------+
| B1  | Route module LOC                 |    500 |    893 |    893 | LOCKED |
| B2  | Function LOC                     |    100 |    142 |    142 | LOCKED |
| B3a | serde_json::Value in src         |      0 |     12 |     12 | LOCKED |
| B3b | serde_json::Value in tests       |      5 |    187 |    187 | LOCKED |
| B4  | #[allow(...)] count              |     20 |     34 |     34 | LOCKED |
| B5  | unwrap_or_default in production  |     50 |    101 |    101 | LOCKED |
| B6  | Duplicate dependency versions    |      0 |      2 |      2 | LOCKED |
| B7  | Untyped test-client methods      |      0 |     56 |     56 | LOCKED |
+-----+----------------------------------+--------+--------+--------+--------+
Status: LOCKED = at-or-below current lockfile baseline.
        OVER   = above lockfile baseline; explain in CR description.

# CRAIG Coverage Matrix
Generated: 2026-05-03T12:00:00Z
Route: 247 endpoints across 8 services
Risk axes: happy / sad / evil / concurrency / replay / fault

| Service | Method | Path | happy | sad | evil | conc | replay | fault |
|---------|--------|------|-------|-----|------|------|--------|-------|
| craig-cases | GET | /v1/cases       | ✓ |   |   |   |   |   |
| craig-cases | POST | /v1/cases      | ✓ | ✓ |   | ✓ |   |   |
| craig-cases | GET | /v1/cases/{id}  | ✓ |   |   |   |   |   |
| ...
**Risk-coverage score: 412 / 1482 cells (27.8%)**

use anyhow::{Context, Result};
use clap::Args;
use std::collections::BTreeMap;
use std::path::PathBuf;

#[derive(Args)]
pub struct CoverageMatrixArgs {
    /// Output path (default: target/coverage-matrix.md)
    #[arg(long, default_value = "target/coverage-matrix.md")]
    pub output: PathBuf,
    /// Base URL for OpenAPI scraping (default: http://localhost)
    #[arg(long, default_value = "http://localhost")]
    pub base_url: String,
    /// Skip OpenAPI fetch; use cached `target/openapi-cache.json`
    #[arg(long)]
    pub use_cache: bool,
}

#[derive(Debug, Clone)]
struct Route { service: String, method: String, path: String }

#[derive(Debug)]
struct Cell { axes: [bool; 6] }   // happy, sad, evil, conc, replay, fault

pub fn generate(args: CoverageMatrixArgs) -> Result<()> {
    println!("=== Coverage matrix (report-only). ===");
    let routes = if args.use_cache { read_cache()? }
                 else                { fetch_openapi(&args.base_url)? };
    let tests  = scan_tests()?;
    let matrix = build_matrix(&routes, &tests);
    write_markdown(&args.output, &routes, &matrix)?;
    let (filled, total) = score(&matrix);
    println!("=== Risk-coverage: {filled}/{total} ({:.1}%) — see {}",
             100.0 * filled as f64 / total as f64,
             args.output.display());
    Ok(())
}

fn fetch_openapi(_base: &str) -> Result<Vec<Route>> { /* see api_docs.rs:46-72 */ Ok(vec![]) }
fn scan_tests() -> Result<Vec<TestRef>> { /* walkdir + regex */ Ok(vec![]) }
fn build_matrix(_: &[Route], _: &[TestRef]) -> BTreeMap<(String,String,String), Cell> { Default::default() }
fn write_markdown(_: &std::path::Path, _: &[Route], _: &BTreeMap<(String,String,String), Cell>) -> Result<()> { Ok(()) }
fn score(m: &BTreeMap<(String,String,String), Cell>) -> (usize, usize) {
    let total = m.len() * 6;
    let filled: usize = m.values().map(|c| c.axes.iter().filter(|x| **x).count()).sum();
    (filled, total)
}

#[derive(Debug)] struct TestRef { /* axis, route_match */ }
fn read_cache() -> Result<Vec<Route>> { Ok(vec![]) }

#[derive(Args)]
pub struct CoverageMatrixArgs {
    /// Compare against a base ref (default: main). Prints filled/empty cell deltas.
    #[arg(long)]
    pub diff: Option<String>,
    // ...other args from D13.4
}

//! Hand-curated DB constraint test harness.
//!
//! For each constraint we want to verify, write one test in
//! `services/<svc>/tests/constraints/<constraint>.rs` that uses
//! `assert_constraint_violation_returns(...)` to drive an API request
//! known to violate the constraint and assert the resulting 4xx +
//! RFC 9457 problem-type URL.

use crate::client::TypedClient;
use reqwest::StatusCode;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ExpectedRejection {
    BadRequest400,
    UnprocessableEntity422,
    Conflict409,
    NotFound404,
}

impl From<ExpectedRejection> for StatusCode {
    fn from(e: ExpectedRejection) -> Self {
        match e {
            ExpectedRejection::BadRequest400         => StatusCode::BAD_REQUEST,
            ExpectedRejection::UnprocessableEntity422=> StatusCode::UNPROCESSABLE_ENTITY,
            ExpectedRejection::Conflict409           => StatusCode::CONFLICT,
            ExpectedRejection::NotFound404           => StatusCode::NOT_FOUND,
        }
    }
}

/// Drive `request` against `client`; assert the response carries
/// `expected` status and a problem+json body whose `type` field equals
/// `problem_type_url`.
///
/// `request` is a closure so the harness can rerun it (state-machine
/// constraint tests sometimes need a setup step before triggering).
pub async fn assert_constraint_violation_returns<R, Fut>(
    client: &TypedClient,
    request: R,
    expected: ExpectedRejection,
    problem_type_url: &str,
) where
    R: FnOnce(TypedClient) -> Fut,
    Fut: std::future::Future<Output = reqwest::Response>,
{
    let resp = request(client.clone()).await;
    let status = resp.status();
    let body: serde_json::Value = resp.json().await.expect("problem+json");
    assert_eq!(status, StatusCode::from(expected),
        "expected {expected:?} got {status}; body={body}");
    assert_eq!(body.get("type").and_then(|v| v.as_str()), Some(problem_type_url),
        "wrong problem type; full body: {body}");
}

// services/craig-financial/tests/constraints/payment_amount_positive.rs
use craig_test_lib::{
    constraints::{assert_constraint_violation_returns, ExpectedRejection},
    TestHarness,
};
use craig_test_lib::clients::caseworker_financial_client;

#[tokio::test]
async fn payment_amount_must_be_positive_evil() {
    let h = TestHarness::new().await;
    if !h.devstack_available().await { return; }
    let client = caseworker_financial_client(&h);

    assert_constraint_violation_returns(
        &client,
        |c| async move {
            c.create_payment_raw(serde_json::json!({
                "case_id":      h.fixtures.case_id,
                "placement_id": h.fixtures.placement_id,
                "amount":       -1,
                "kind":         "ive_maintenance",
            })).await
        },
        ExpectedRejection::BadRequest400,
        "https://docs.craig/problems/invalid-amount",
    ).await;
}

crates/craig-test-lib/src/evil/
├── mod.rs           — re-exports + EvilCase / EvilCategory / EvilPayload / ExpectedRejection
├── jwt.rs           — wraps Step-6 jwt_mutations; emits EvilCase::Jwt(JwtMutation)
├── upload.rs        — wraps Step-7 upload_fixtures; emits EvilCase::Upload(UploadFixture)
├── string.rs        — overlong / invalid-UTF-8 / NUL / CRLF / RTLO / ZWSP    (NEW)
├── uuid.rs          — wrong-version / wrong-length / all-zeros / non-hex     (NEW)
├── json.rs          — depth bomb / int overflow / extra fields / type swap   (NEW)
├── path.rs          — `../`, double-encoded, NUL-truncated, UNC, ADS         (NEW)
├── html.rs          — script tags, javascript: URLs, polyglot SVG/HTML       (NEW)
├── unicode.rs       — NFC vs NFD, homoglyph, BiDi override, BOM              (NEW)
├── enum_value.rs    — unknown / case-mismatched / boundary-adjacent          (NEW)
├── date.rs          — leap-second, year-9999, negative, fractional overflow  (NEW)
├── multipart.rs     — missing boundary, conflicting Content-Length, …        (NEW)
└── signature.rs     — wrong-length, wrong-key, replay, alg-confusion         (NEW)

// crates/craig-test-lib/src/evil/mod.rs
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum EvilCategory {
    Jwt, Upload, String, Uuid, Json, Path, Html, Unicode,
    EnumValue, Date, Multipart, Signature,
}

#[derive(Clone, Debug)]
pub struct EvilCase {
    /// Stable, human-meaningful identifier. Used as the test-block name when
    /// fed into `parametric_evil_test!`. Examples:
    ///   "string.overlong_1mb"
    ///   "json.depth_bomb_4096"
    ///   "path.dot_dot_double_url_encoded"
    pub name: &'static str,
    pub category: EvilCategory,
    pub payload: EvilPayload,
    pub expected: ExpectedRejection,
}

#[derive(Clone, Debug)]
pub enum EvilPayload {
    /// String body — fed as the field value in a request DTO.
    Str(String),
    /// Raw bytes — fed as a multipart body or as a typed Bytes argument.
    Bytes(Vec<u8>),
    /// JSON value — fed as a request body, typically with a wrapper DTO.
    Json(serde_json::Value),
    /// Pre-built JWT (header.payload.signature) — fed via Authorization header.
    BearerToken(String),
    /// Multipart fragment — already encoded; injected as the request body.
    MultipartRaw { content_type: String, body: Vec<u8> },
}

#[derive(Clone, Copy, Debug)]
pub enum ExpectedRejection {
    /// Any 4xx status acceptable — used for "reject with a clean error".
    AnyClientError,
    /// Specific 4xx status — used when the contract pins it (e.g. JWT → 401).
    Status(u16),
    /// 4xx with a specific RFC 9457 type pointer.
    ProblemType(&'static str),
}

pub fn all_evil_cases() -> impl Iterator<Item = EvilCase> { /* chain all categories */ }

pub fn evil_cases_for(category: EvilCategory) -> impl Iterator<Item = EvilCase> {
    all_evil_cases().filter(move |c| c.category == category)
}

// services/craig-cases/tests/api/evil_corpus.rs
use craig_test_lib::evil::{parametric_evil_test, EvilCategory};

parametric_evil_test! {
    name: cases_post_rejects_evil_inputs,
    endpoint: |client, case| async move {
        client.post_case_with_evil(case).await
    },
    skip_categories: [EvilCategory::Multipart, EvilCategory::Signature],
}

#[tokio::test]
async fn every_evil_case_is_rejected_at_public_intake() {
    if !devstack_available().await { return; }
    let h = TestHarness::new().await;
    let intake = h.public_intake_client();

    for case in craig_test_lib::evil::all_evil_cases() {
        let res = intake.submit_with_evil(&case).await;
        match (res.status().as_u16(), case.expected) {
            (s, ExpectedRejection::AnyClientError) if (400..500).contains(&s) => {}
            (s, ExpectedRejection::Status(want)) if s == want => {}
            // ProblemType: parse RFC 9457 body, compare type field
            (s, ExpectedRejection::ProblemType(t)) if (400..500).contains(&s) => {
                assert_problem_type(res, t).await;
            }
            (s, exp) => panic!(
                "evil case {:?} (cat={:?}) returned status {} (expected {:?}) — \
                 server accepted hostile input or 5xx-ed instead of clean reject",
                case.name, case.category, s, exp,
            ),
        }
    }
}

/// A semantic point at which the service simulates a crash. The injector at
/// this point hard-errors with a panic-equivalent (returns Err that the
/// surrounding code unwraps in test mode), forcing the in-flight tx to abort
/// and the calling fn to return.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum CrashPoint {
    /// Inside an attachment upload, after Phase 1 commit and BEFORE Phase 2 put.
    AttachmentMidUpload,
    /// Inside an attachment upload, after Phase 2 put and BEFORE status promote.
    AttachmentPostPut,
    /// Inside outbox drain, after publish() returns Ok and BEFORE post-publish UPDATE.
    OutboxPostPublish,
    /// Inside inbox handler, between handler success and processed_at UPDATE.
    InboxPostHandle,
    /// Inside exchange send, after adapter.send() returns Ok and BEFORE finalize tx.
    ExchangePostSend,
    /// Inside placement update, after update_placement succeeds and BEFORE event publish.
    PlacementPostUpdate,
    /// Generic — caller-supplied predicate (for ad-hoc test scenarios).
    Custom(&'static str),
}

/// Result of a simulated crash: the service was driven up to the crash point
/// and then forcibly errored. The DB / blob / queue state is whatever the
/// simulated point left behind.
pub struct SimulatedCrash {
    pub at: CrashPoint,
    pub error: anyhow::Error,
    /// Useful diagnostics — e.g. the row id that was being processed.
    pub artifact: Option<serde_json::Value>,
}

/// Drive a builder closure that constructs and exercises the service-under-test
/// up to `point`. Uses the Phase A.2 fault-injection harness to deliver the
/// crash at exactly the named site.
pub async fn simulate_crash_after<F, Fut>(
    point: CrashPoint,
    builder: F,
) -> SimulatedCrash
where
    F: FnOnce(CrashHarness) -> Fut,
    Fut: std::future::Future<Output = anyhow::Result<()>>;

/// Re-run a service's `main_inner(args, env)` (see §Open Questions) to drive
/// recovery sweeps after a simulated crash. Mocks the binary entrypoint without
/// spawning a process. Returns a handle that the test can await/cancel.
pub fn restart_service<F, Fut>(svc_main: F) -> SimulatedRestart
where
    F: FnOnce() -> Fut + Send + 'static,
    Fut: std::future::Future<Output = anyhow::Result<()>> + Send + 'static;

/// Poll until the system reaches the expected recovery state, or timeout.
/// `state` is a closure that queries DB / blob / queue and returns Ok(true)
/// when the invariant holds.
pub async fn assert_recovers_to<F, Fut>(
    state: F,
    timeout: Duration,
) -> anyhow::Result<()>
where
    F: Fn() -> Fut,
    Fut: std::future::Future<Output = anyhow::Result<bool>>;

// services/craig-cases/tests/api/contact_attachments_recovery.rs
#[tokio::test]
async fn upload_recovers_after_post_put_crash() {
    if !devstack_available().await { return; }

    let crash = simulate_crash_after(CrashPoint::AttachmentPostPut, |h| async move {
        let client = h.cases_client();
        client.upload_contact_attachment(case_id(), b"hello world").await?;
        Ok(())
    }).await;

    assert!(crash.error.to_string().contains("simulated"));

    // Now drive recovery — the AttachmentScanner re-runs and promotes the row.
    restart_service(|| async {
        craig_cases::main_inner(test_args(), test_env()).await
    });

    assert_recovers_to(|| async {
        let row = query_attachment_row(crash.artifact.as_ref().unwrap()).await?;
        Ok(row.object_status == "present")
    }, Duration::from_secs(30)).await.unwrap();
}

[invariants] craig-cases :: orphan_pending_attachments
  query: SELECT id, object_status, created_at FROM contact_attachments
         WHERE object_status='pending' AND created_at < now() - INTERVAL '24 hours'
  expected: 0 rows
  got: 3 rows
  sample: [
    { id: 0193…, object_status: "pending", created_at: "2026-05-01T…" },
    …
  ]
  remediation: see plans/platform-stabilization-2.adoc §D4.5 — scanner should
               have reaped this row; investigate scanner logs / DB connectivity.

pub async fn run(args: InvariantsArgs) -> anyhow::Result<()> {
    let services = enumerate_services(&args)?;        // default: all 8 stateful
    let mut all_passed = true;
    for svc in services {
        let pool = connect_to(&svc.dsn).await?;
        let invariants = load_invariants_for(&svc)?;  // §D17.3
        for inv in invariants {
            let rows = sqlx::query(&inv.sql)
                .fetch_all(&pool)
                .await
                .with_context(|| format!("running invariant {} on {}", inv.name, svc.name))?;
            if rows.is_empty() {
                println!("[invariants] {} :: {} OK", svc.name, inv.name);
            } else {
                all_passed = false;
                report_failure(&svc, &inv, &rows);
            }
        }
    }
    if !all_passed { std::process::exit(1); }
    Ok(())
}

crates/craig-test-lib/sql/invariants/
├── craig-cases/
│   ├── orphan_pending_attachments.sql
│   ├── duplicate_active_contact_persons.sql
│   └── audit_row_per_state_mutation.sql
├── craig-exchange/
│   ├── stuck_pending_transactions.sql
│   ├── stuck_in_flight_send_jobs.sql
│   └── orphan_pending_attachments.sql           — ICPC mirror
├── craig-mq/                                     — global cross-service
│   ├── unpublished_outbox_beyond_grace.sql
│   └── inbox_processed_with_failed.sql
├── craig-financial/…
├── craig-placement/…
├── craig-reporting/…
├── craig-rules/…
└── craig-security/…

-- name = "orphan_pending_attachments"
-- service = "craig-cases"
-- grace = "24h"
-- remediation = "plans/platform-stabilization-2.adoc#D4.5"
-- severity = "high"
SELECT id, object_status, created_at, file_name
FROM contact_attachments
WHERE object_status = 'pending'
  AND created_at < now() - INTERVAL '24 hours';

// crates/craig-common/src/constants.rs
use std::time::Duration;

pub const ORPHAN_PENDING_ATTACHMENT_GRACE: Duration = Duration::from_secs(24 * 60 * 60);
pub const OUTBOX_PENDING_GRACE: Duration = Duration::from_secs(5 * 60);
pub const STUCK_EXCHANGE_TX_GRACE: Duration = Duration::from_secs(6 * 60 * 60);
pub const STUCK_SEND_JOB_GRACE: Duration = Duration::from_secs(60);
pub const IDEMPOTENCY_CLAIM_TTL: Duration = Duration::from_secs(30);
pub const IDEMPOTENCY_PROCESSING_GRACE_PAST_TTL: Duration = Duration::from_secs(60);

// xtask/src/cmd/test.rs (extension)
if args.post_check {
    super::invariants::run(InvariantsArgs::default()).await?;
}

= Test Coverage Scorecard
:description: Risk-based coverage for the top 20 critical workflows.

[cols="3,1,1,1,1,1,1"]
|===
| Workflow | Happy | Sad | Evil | Concurrency | Replay | Fault

| Idempotent POST handler (cross-cutting)
| ✅ | ✅ | ✅ | ✅ | ✅ | ✅
| Outbox publish (cross-cutting)
| ✅ | ✅ | ⏳ | ✅ | ✅ | ✅
| Inbox handler (cross-cutting)
| ✅ | ✅ | ⏳ | ⏳ | ✅ | ✅
| Attachment upload (4 sites)
| ✅ | ✅ | ⏳ | ⏳ | ✅ | ✅
| Exchange send (1 path)
| ✅ | ✅ | ⏳ | ⏳ | ✅ | ✅
| Placement transition guard
| ✅ | ✅ | ⏳ | ✅ | ⏳ | ⏳
| BFF page render under upstream failure
| ✅ | ✅ | ⏳ | ⏳ | ⏳ | ✅
| Person match
| ✅ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳
| Rules evaluation
| ✅ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳
| Public intake submit
| ✅ | ✅ | ✅ | ⏳ | ⏳ | ⏳
| (10 more — see source) | | | | | | |
|===

Legend: ✅ covered, ⏳ planned, ❌ gap.