bcinr-cmca 26.10.11

//! # CMCA: Chatman Multifractal Consequence Allocation
//!
//! `bcinr-cmca` is an authoritative systems library implementing deterministic,
//! branchless, and allocation-free algorithms for runtime telemetry, calibration,
//! monitoring, and cascade allocation (see [`allocator`]) of bounded computational
//! systems. "Covariance Monitoring and Calibration Assessment" was this crate's
//! earlier, calibration-only framing; see `docs/CMCA_EXPLANATION.md` for the
//! canonical-name reconciliation across this crate's calibration (`observatory`)
//! and cascade-allocation (`allocator`) responsibilities.
//!
//! Under the strict constraints of the **Radon Law** (Cyclomatic Complexity $CC=1$),
//! this module provides tools to audit the health and stability of mathematical
//! substrates without introducing timing side-channels, dynamic heap allocations,
//! or panic-prone execution paths.
//!
//! ## Architectural Foundations
//!
//! The crate enforces an autonomic feedback loop structured around the standard **MAPE-K**
//! (Monitor, Analyze, Plan, Execute, Shared Knowledge) control loop:
//! 1. **Observe**: Collect telemetry metrics (such as scaling factors, condition bounds, and drift metrics).
//! 2. **Infer**: Compute safety flags branchlessly using fixed-point arithmetic invariants.
//! 3. **Propose**: Report validation states indicating whether to proceed or trigger recertification.
//!
//! ## Key Modules
//!
//! * [`fixed`]: Q16.16 fixed-point arithmetic implementation designed for $CC=1$ operations.
//! * [`allocator`]: Linear bounds-checked and panic-free bump allocators.
//! * [`observatory`]: The evaluation engine that computes calibration safety flags based on mathematical thresholds.
//! * [`dme_route`]: Canonical content-addressed DME route selector. It performs SELECT only;
//!   its decisions carry no authority and cannot execute consequences.
//!
//! ## `allocator::allocate` is fixed to this crate's own `N=8`/`K=4`/`Q=4` shape (CMCA-108)
//!
//! [`allocator::allocate`] and [`allocator::allocate_single_lens`] -- this crate's
//! certified, branchless, allocation-free allocation path -- are compiled
//! against this crate's own object/measure/lens counts (`N = 8`, `K = 4`,
//! `Q = 4`, from `generated::consequence_mass::case_studies`), **not**
//! generic over caller-chosen sizes. A caller can supply different factor
//! *values* but not a different *shape* without this crate being
//! regenerated against a different `ontology/*.ttl`. See
//! [`allocator::allocate`]'s doc comment for why (the branchless kernel
//! beneath it unrolls against the literal constants 8/4/4) and for
//! `cascade::consequence_mass`, the escape hatch for arbitrary tree
//! shapes.
//!
//! ## Which entry point do I want? (CMCA-119)
//!
//! Five overlapping ways to get an allocation share out of this crate --
//! this section is a navigation aid, not a restatement of each one's own
//! doc comment (follow the links below for the real detail):
//!
//! * [`allocator::allocate`] -- **start here** for the common case: one
//!   LAMBDA-weighted allocation vector across the whole `N`/`K`/`Q` object
//!   registry, evaluated against `FeasibleRegion::CURRENT`. See
//!   `examples/basic_allocation.rs` for a full runnable walkthrough.
//! * [`allocator::allocate_in`] -- the same computation as `allocate`, but
//!   over a caller-chosen [`allocator::FeasibleRegion`] instead of always
//!   `CURRENT`; use this when evaluating a hypothetical/candidate region
//!   rather than the live one.
//! * [`allocator::allocate_single_lens`] -- returns exactly one lens's
//!   allocation vector for one measure, bypassing the LAMBDA blend across
//!   all `K x Q` pairs; use this to inspect "what would lens `q` alone
//!   say" instead of the combined answer.
//! * `cascade::consequence_mass` (requires `alloc`) -- the escape hatch
//!   for tree shapes other than this crate's fixed `N = 8`/`K = 4`/`Q = 4`;
//!   use this when the object/measure/lens counts aren't the ones this
//!   crate was regenerated against.
//! * `escort::escort_distribution` (requires `alloc`) -- the
//!   fractional-exponent escort distribution `L_q(i) = p_i^q / SUM_j p_j^q`
//!   built directly on [`allocator::power`]; use this when you need an
//!   escort weighting over an arbitrary mass vector, independent of the
//!   object-registry allocation machinery above.
//!
//! ## Example Usage
//!
//! ```rust
//! use bcinr_cmca::fixed::NonNegativeFixed;
//! use bcinr_cmca::observatory::{evaluate_calibration, ObservatoryFlag};
//!
//! let kappa_hat = NonNegativeFixed::from_bits(131072);
//! let kappa_under = NonNegativeFixed::from_bits(131072);
//! let epsilon_on = NonNegativeFixed::from_bits(65536);
//! let gamma_min_plus_hat = NonNegativeFixed::from_bits(131072);
//! let gamma_min_plus_under = NonNegativeFixed::from_bits(131072);
//! let epsilon_gram = NonNegativeFixed::from_bits(65536);
//! let d_js = NonNegativeFixed::ZERO;
//! let epsilon_drift = NonNegativeFixed::from_bits(65536);
//! let s_meas = NonNegativeFixed::ONE;
//! let s_leaf = NonNegativeFixed::from_bits(32768);
//!
//! use bcinr_cmca::observatory::{MeasurementArtifact, SupportStanding, ModeDelta};
//! let artifact = MeasurementArtifact {
//!     point_estimate: kappa_hat,
//!     lower_bound: kappa_under,
//!     upper_bound: kappa_hat,
//!     support_standing: SupportStanding { is_supported: true, smoothing_applied: false },
//!     effective_sample_size: NonNegativeFixed::ONE,
//!     dependence_standing: 0,
//!     numeric_error: NonNegativeFixed::ZERO,
//!     drift: d_js,
//!     gram_lower_bound: gamma_min_plus_under,
//!     graph_digest: 0,
//!     control_mode_digest: 42,
//!     proposal: ModeDelta::ProposeDelta,
//! };
//! let status = evaluate_calibration(
//!     &artifact, epsilon_on, epsilon_gram, epsilon_drift, s_meas, s_leaf,
//! );
//! # if cfg!(any(
//! #     feature = "mutant_1", feature = "mutant_2", feature = "mutant_3",
//! #     feature = "mutant_4", feature = "mutant_5", feature = "mutant_6",
//! #     feature = "mutant_7", feature = "mutant_8", feature = "mutant_9",
//! #     feature = "mutant_10", feature = "mutant_11"
//! # )) { return; }
//! assert!(status.is_ok());
//! ```

#![cfg_attr(not(feature = "std"), no_std)]
#![deny(unsafe_code)]

#[cfg(feature = "std")]
extern crate std;

pub mod allocation_receipt;
pub mod allocator;
#[cfg(feature = "alloc")]
pub mod cascade;
/// DME route selection: deterministic SELECT over admitted bounded execution classes.
/// This module grants no authority and contains no execution/DO surface.
pub mod dme_route;
/// Fractional-exponent escort distribution (`L_q(i) = p_i^q / SUM_j p_j^q`)
/// built on [`allocator::power`]. See the module docs for why this exists
/// alongside `cascade::escort_weight`, which only covers integer `q`.
#[cfg(feature = "alloc")]
pub mod escort;
pub mod fixed;
pub mod generated;
pub mod generated_profile;
pub mod lrc;
pub mod observatory;
/// Hand-transcribed exact-rational reference oracle for the CMCA escort
/// distribution, mirroring `~/mfw`'s `MFW/CMCA/Semantics/Escort.lean`. Not a
/// machine-checked bridge -- see the module docs for exact scope.
#[cfg(feature = "alloc")]
pub mod reference_escort;
/// Authority-free SA2A resource-allocation consumer boundary.
pub mod sa2a;
pub mod stability_theorem;

pub use allocator::{
    check_hierarchy_acyclic, HierarchyRefusal, LensSelectionRefusal, StabilityRefusal,
};
pub use dme_route::{
    select_dme_route, select_gall_route, verify_dme_route_decision, verify_gall_route_decision,
    AuthorityStanding, ConsequenceClass, DmeRouteDecision, DmeRouteRefusal, DmeRouteRequest,
    GallRouteDecision, GallRouteRefusal, GallRouteRequest, GallWorkIdentity, RouteCandidate,
    RouteClass, RouteExplanation, WorkKnowledge, WorkStanding,
};

// INTEGRATION NOTE (v26.7.24, re-fenced explicitly per CMCA-102 Branch B):
// Recovery-only authority modules remain defined in allocator.rs and deliberately
// NOT re-exported from this crate root pending their formal dependency-closure proof.

/// A branchless mock/dummy function utilized in tests and contract validation.
pub fn dummy_branchless(val: u64) -> u64 {
    val.wrapping_add(1)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_dummy_branchless() {
        assert_eq!(dummy_branchless(0), 1);
        assert_eq!(dummy_branchless(42), 43);
        assert_eq!(dummy_branchless(u64::MAX), 0);
    }
}