vyre-conform 0.1.0

//! Canonical [`ComponentSpec`] for the mutation gate.
//!
//! `harnesses::mutation::mutation_probe` is the honesty boundary for
//! mutation grading. It mutates source, runs the requested test command,
//! reports whether the mutation was killed, and restores the source even
//! on early exits. If it lies or leaves the tree dirty, every lower-level
//! mutation score becomes meaningless.
//!
//! [`ComponentSpec`]: crate::meta::component::ComponentSpec

use crate::meta::adversary::{AdversaryRef, BrokenComponent};
use crate::meta::component::{
    ComponentKind, ComponentSpec, ComponentSpecRow, Contract, ContractKind,
};
use crate::meta::mutation::MetaMutationClass;
use crate::meta::oracle::{MetaOracleKind, MetaVerdict};

/// Contracts the mutation gate obeys.
const CONTRACTS: &[Contract] = &[
    Contract {
        id: "post.restores_source_on_drop",
        kind: ContractKind::Post,
        description: "Every mutation probe must restore the original source bytes on \
             success, test failure, skipped mutation, command error, and guard \
             drop paths.",
    },
    Contract {
        id: "post.failed_test_reports_killed",
        kind: ContractKind::Post,
        description: "If cargo test fails only after applying an applicable mutation, the \
             probe must report Killed for that mutation.",
    },
    Contract {
        id: "post.passing_test_reports_survived",
        kind: ContractKind::Post,
        description: "If cargo test still passes under an applicable mutation, the probe \
             must report Survived rather than claiming the test killed it.",
    },
    Contract {
        id: "pre.mutation_is_applicable_or_skipped",
        kind: ContractKind::Pre,
        description: "A mutation whose target pattern is absent is an inapplicable input \
             and must be reported as Skipped without editing unrelated source.",
    },
];

/// Adversary corpus. Each entry is a deliberately-broken mutation probe a
/// good meta-test set MUST reject.
const ADV_FALSE_KILL: BrokenComponent = BrokenComponent {
    id: "reports_killed_when_test_passes",
    description: "Mutation probe reports Killed even though the mutated cargo test run \
         passed. Symptom: a surviving mutation is counted as killed and the \
         meta-gate certifies a dishonest test.",
    targets: "harnesses::mutation::mutation_probe",
    expected_failure_signature:
        "post.passing_test_reports_survived violated: got Killed for passing mutation",
    signature_match_policy: crate::meta::adversary::SignatureMatchPolicy::Substring,
    covers_classes: &[MetaMutationClass::GateCorruption],
    covers_contract_ids: &[
        "post.passing_test_reports_survived",
        "post.failed_test_reports_killed",
        "post.restores_source_on_drop",
    ],
};

const ADV_SKIP_RESTORE: BrokenComponent = BrokenComponent {
    id: "skips_source_restore",
    description: "Mutation probe leaves the mutated source on disk after reporting. \
         Symptom: the next probe or developer build observes a dirty tree that \
         came from the gate itself.",
    targets: "harnesses::mutation::mutation_probe",
    expected_failure_signature:
        "post.restores_source_on_drop violated: source bytes differ after probe",
    signature_match_policy: crate::meta::adversary::SignatureMatchPolicy::Substring,
    covers_classes: &[],
    covers_contract_ids: &[],
};

const ADVERSARIES: &[AdversaryRef] = &[&ADV_FALSE_KILL, &ADV_SKIP_RESTORE];

/// Meta-mutation classes this component's test set must kill.
const SENSITIVITY: &[MetaMutationClass] = &[MetaMutationClass::GateCorruption];

/// Didactic spec-table rows for the mutation gate.
const SPEC_TABLE: &[ComponentSpecRow] = &[
    ComponentSpecRow {
        input_id: "applicable_mutation_cargo_test_fails",
        expected: MetaVerdict::Counterexample { id: String::new() },
        rationale: "A mutation that makes the target cargo test fail is the canonical \
             killed path and proves the gate does not invert failure.",
        contract_ids: &["post.failed_test_reports_killed"],
        expected_boundaries: &[],
        witness_id: "applicable_mutation_killed",
    },
    ComponentSpecRow {
        input_id: "applicable_mutation_cargo_test_passes",
        expected: MetaVerdict::Verified {
            sampled_boundaries: Vec::new(),
        },
        rationale: "A mutation that leaves cargo test green is a survived mutation and \
             proves the gate reports weak tests honestly.",
        contract_ids: &[],
        expected_boundaries: &[],
        witness_id: "",
    },
    ComponentSpecRow {
        input_id: "inapplicable_mutation_target_missing",
        expected: MetaVerdict::PreconditionFailure {
            message: String::new(),
        },
        rationale: "A mutation whose syntax target is absent must be skipped cleanly \
             without editing unrelated files or claiming a kill.",
        contract_ids: &[],
        expected_boundaries: &[],
        witness_id: "",
    },
];

/// The [`ComponentSpec`] for the mutation probe.
pub const MUTATION_GATE_SPEC: ComponentSpec = ComponentSpec {
    name: "harnesses::mutation::mutation_probe",
    source_file: "src/verify/harnesses/mutation/probe/mutation_probe.rs",
    test_suite_filter: "h6_canary_mutation_applies_and_restores",
    kind: ComponentKind::MutationGate,
    contracts: CONTRACTS,
    adversaries: ADVERSARIES,
    meta_mutation_sensitivity: SENSITIVITY,
    spec_table: SPEC_TABLE,
    preferred_oracle: MetaOracleKind::Contract,
    docs_path: "docs/meta/components/mutation_gate.md",
    boundary_witnesses: &[],
};