pr4xis 0.27.0

//! The Constitution — pr4xis's five guarantees, and the machinery that binds
//! the test suite to them.
//!
//! The `ontology` submodule defines the five guarantees ([`Guarantee`]) as a first-class
//! ontology. This module adds the *self-binding* layer: every test in the
//! workspace declares the guarantee it witnesses with the
//! [`praxis_value`](crate::praxis_value) attribute, which registers a
//! [`GuaranteeTag`] into the [`CONSTITUTION_TESTS`] distributed slice at link
//! time. A `constitution_coverage` meta-test then folds that slice into a
//! per-guarantee partition of the suite — so a guarantee cannot silently lose
//! coverage and a new test cannot escape classification.
//!
//! The classification is declared, not reverse-engineered from test names: a
//! claim's guarantee is first-class and discoverable, the same discipline the
//! rest of pr4xis applies to domain knowledge.

mod ontology;

pub use ontology::{
    ConstitutionConcept, DeterminismEnablesVerificationAndExplanation,
    EveryAxiomCarriesItsExplanation, ExtensiblePreservesEveryGuarantee, Guarantee,
    HonestGroundsEveryGuarantee, OntologyBaseIsConsistent,
};

/// How strongly a test witnesses its guarantee.
///
/// An [`Example`](TestKind::Example) is a point-claim: it asserts the property
/// at one chosen input. A [`Property`](TestKind::Property) is a ∀-claim: a
/// `proptest!` that asserts the property for *every* input in a strategy's
/// domain, checked over many generated cases (proptest's default sample budget
/// is 256, configurable via `PROPTEST_CASES`). A property is a stronger witness
/// than an example — the case count is a sampling budget, not a test count, so
/// a property is still **one** test here, distinguished only by its kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TestKind {
    /// A point-claim: the property holds at one chosen input.
    Example,
    /// A ∀-claim: the property holds for every input in a generated domain.
    Property,
}

/// The constitutional guarantee(s) a single test witnesses.
///
/// `primary` is the guarantee the test most directly evidences — the partition
/// key, so every tagged test falls in exactly one bucket. `secondary` records
/// any further guarantees an irreducible test also witnesses (e.g. a property
/// asserting that a mutated `.prx` is always rejected witnesses Honesty
/// primarily, but also Verifiability and Determinism) without forcing an
/// artificial split. `kind` distinguishes a point-claim from a ∀-claim, so
/// coverage can report depth (how many witnesses are properties) as well as
/// breadth.
#[derive(Debug, Clone)]
pub struct GuaranteeTag {
    /// The guarantee this test most directly witnesses (the partition key).
    pub primary: Guarantee,
    /// Further guarantees the same test also witnesses, if any.
    pub secondary: &'static [Guarantee],
    /// Whether the test is an example (point-claim) or a property (∀-claim).
    pub kind: TestKind,
    /// The module the test lives in (`module_path!()` at the call site).
    pub module: &'static str,
    /// The test function's name.
    pub name: &'static str,
}

/// Every test tagged with [`praxis_value`](crate::praxis_value) or
/// [`register_praxis_value!`](crate::register_praxis_value), gathered at link
/// time.
///
/// Native targets only — `linkme` is unsupported on wasm32, where the slice is
/// empty (fail-closed: the coverage meta-test does not run there).
#[cfg(not(target_arch = "wasm32"))]
#[linkme::distributed_slice]
pub static CONSTITUTION_TESTS: [GuaranteeTag];

/// Register a test's constitutional guarantee(s) without an attribute.
///
/// Companion to the [`praxis_value`](crate::praxis_value) attribute for tests
/// the attribute cannot wrap — chiefly `proptest! { #[test] fn .. }` blocks,
/// where the test function is generated by another macro and so is not an
/// `ItemFn` the attribute can parse. Place the call at module scope, next to
/// the test:
///
/// ```text
/// proptest! {
///     #[test]
///     fn prop_mutated_prx_always_rejected(..) { .. }
/// }
/// pr4xis::register_praxis_value!(prop_mutated_prx_always_rejected, Honest, Verifiable, Deterministic);
/// ```
///
/// The first guarantee is primary; any others are secondary. The named
/// function is not checked to exist here — the completeness gate (registry
/// length vs the live `--list` count) is what catches an untagged test or a
/// tag whose name has no test.
#[macro_export]
macro_rules! register_praxis_value {
    ($name:ident, $primary:ident $(, $secondary:ident)* $(,)?) => {
        $crate::paste::paste! {
            #[cfg(not(target_arch = "wasm32"))]
            #[allow(non_upper_case_globals)]
            #[$crate::linkme::distributed_slice($crate::constitution::CONSTITUTION_TESTS)]
            #[linkme(crate = $crate::linkme)]
            static [<__PRAXIS_VALUE_ $name>]: $crate::constitution::GuaranteeTag =
                $crate::constitution::GuaranteeTag {
                    primary: $crate::constitution::Guarantee::$primary,
                    secondary: &[ $( $crate::constitution::Guarantee::$secondary ),* ],
                    // The declarative macro exists for proptest!/generated
                    // tests, which are ∀-claims.
                    kind: $crate::constitution::TestKind::Property,
                    module: module_path!(),
                    name: ::core::stringify!($name),
                };
        }
    };
}

/// Per-crate completeness-gate support: emit pr4xis-core's own tag set so
/// `scripts/constitution-gate.sh pr4xis` can diff it against `--list`. This
/// binds the substrate crate's tests to the constitution exactly as the domains
/// crate is bound — the constitution covers its own foundation, not only the
/// reasoning layer.
#[cfg(all(test, not(target_arch = "wasm32")))]
mod coverage_gate {
    extern crate std;
    use crate::constitution::CONSTITUTION_TESTS;
    use alloc::{format, string::String, vec::Vec};
    use std::{eprintln, fs};

    #[crate::praxis_value(Verifiable)]
    #[test]
    fn constitution_coverage() {
        let lines: Vec<String> = CONSTITUTION_TESTS
            .iter()
            .map(|t| format!("{}::{}", t.module, t.name))
            .collect();
        match std::env::var("PRAXIS_CONSTITUTION_TAGS_OUT") {
            Ok(path) => fs::write(&path, lines.join("\n")).expect("write constitution tags"),
            Err(_) => eprintln!("{}", lines.join("\n")),
        }
    }
}