bcinr-cmca 26.10.11

#![allow(dead_code)]

//! # Gamma_CMCA artifact verification (`VerifyGeneratedProfile`)
//!
//! Implements the bcinr-side obligation defined in
//! `docs/cmca-rdf/CMCA_ARTIFACT_CONTRACT.md` §4: verify a generated CMCA artifact
//! (`cmca_generation_manifest.json` + `cmca_generated.rs`) without invoking any
//! RDF/generation logic — no `oxigraph`, no SHACL/ShEx/N3, no Python, no network
//! access. This module reads only already-generated bytes and JSON.
//!
//! ## Dependency decision
//!
//! `blake3` and `serde_json` are added as **dev-dependencies only**, and this
//! module is compiled **only under `#[cfg(test)]`** (see the `pub mod artifact`
//! declaration in `src/lib.rs`, gated the same way). The contract (§4) states
//! verification happens "at build or test time (a `#[test]` or a `build.rs`
//! check)"; the task instructions direct this to be test-time verification, not
//! a build.rs step. Making the whole module (and its two new dependencies)
//! test-only means the shipped `bcinr-cmca` rlib carries zero additional
//! runtime dependencies beyond `bcinr-logic` — consistent with the workspace's
//! zero-dependency posture for its core algorithm crates (`bcinr-logic` is
//! explicitly zero-runtime-deps per `CLAUDE.md`; `bcinr-cmca` already depends
//! only on `bcinr-logic`, and this keeps it that way for non-test builds).
//! The tradeoff: `VerifyGeneratedProfile` is not callable from a normal
//! (non-test, non-dev) build — e.g. it cannot be invoked from a real
//! `build.rs` without moving `blake3`/`serde_json` to `[dependencies]`. That is
//! an intentional, documented restriction, not an oversight; the task
//! explicitly asked for test-time verification only.
//!
//! ## Refusal type decision
//!
//! This module defines a new `GeneratedProfileRefusal` enum rather than
//! extending `allocator::StabilityRefusal`. `StabilityRefusal` is scoped to
//! the *numeric stability control loop* (block-gain bounds, contraction
//! margins, learning-rate envelopes, control-mode certification, ...) — a
//! runtime hot-path domain. Artifact verification is a structurally different
//! domain: it is a one-shot, test-time check of static generated-artifact
//! well-formedness (schema version, digest match, table conservation,
//! registry uniqueness) with no relationship to the online control loop.
//! Folding the two together would make `StabilityRefusal` a grab-bag spanning
//! two unrelated lifecycles (hot-path numeric control vs. offline artifact
//! admission) and would force every hot-path `match` over `StabilityRefusal`
//! to also account for artifact-shaped variants it can never actually
//! produce. A distinct enum keeps each refusal type exhaustively matched
//! against only the failure modes its own domain can produce.
//!
//! ## Scope
//!
//! This module verifies a **synthetic, hand-crafted JSON manifest schema**
//! that mirrors the conceptual fields the contract (§3, §4) describes:
//! `schema_version`, per-table dimension bounds, the `generated_payload_digest`
//! (BLAKE3 of `cmca_generated.rs`'s bytes), the `leaf_floor_base` /
//! `leaf_floor_remainder` conservation tables, and registry index arrays. The
//! real `mfw`-emitted manifest shape has not been confirmed against this
//! module (§9 of the contract: that confirmation is a later migration step);
//! this module is written directly against the contract document, per this
//! task's instructions, and notes below exactly what has and has not been
//! smoke-tested against real generator output.

// This whole module is gated #[cfg(test)] in lib.rs, so std is always
// available here even though the crate as a whole is `no_std` unless the
// `std` feature is enabled.
extern crate std;
use std::{format, string::String, vec::Vec};

use serde::Deserialize;

/// Schema versions this bcinr build recognizes, per contract §6
/// ("Recognized `schema_version` values under this document, as of this
/// draft: `{1}`").
pub const SUPPORTED_SCHEMA_VERSIONS: &[u32] = &[1];

/// Every dividend a `leaf_floor_base`/`leaf_floor_remainder` pair must
/// reconstruct exactly, per contract §3 ("Bounded tables and registries"):
/// the Q16.16-style base+residual conservation scheme sums to exactly
/// `65536` (2^16) for each leaf's declared share.
pub const LEAF_FLOOR_CONSERVATION_TARGET: u64 = 65536;

/// Typed refusal reasons for `VerifyGeneratedProfile`. Every failure path in
/// this module returns one of these — never a panic, never a silent
/// best-effort acceptance (contract §4: "Silent best-effort continuation ...
/// is not a permitted outcome under this contract.").
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum GeneratedProfileRefusal {
    /// `schema_version` in the manifest is not a member of
    /// `SUPPORTED_SCHEMA_VERSIONS`.
    UnrecognizedSchemaVersion,
    /// The freshly recomputed BLAKE3 digest of `cmca_generated.rs`'s bytes
    /// does not match the manifest's declared `generated_payload_digest`.
    PayloadDigestMismatch,
    /// The manifest's own internal digest bookkeeping disagrees with itself
    /// (e.g. a declared digest field is malformed / not a `blake3:` hex
    /// string of the expected length).
    ManifestPayloadDisagreement,
    /// A dimension bound declared in the manifest (e.g. leaf count) does not
    /// match the actual length of the corresponding table.
    DimensionMismatch,
    /// Two tables that are required to be the same length (e.g.
    /// `leaf_floor_base` and `leaf_floor_remainder`) are not.
    TableLengthMismatch,
    /// A registry index is out of bounds for its declared dimension.
    IndexOutOfBounds,
    /// A registry array contains a duplicate index where uniqueness is
    /// required.
    RegistryNotUnique,
    /// The manifest's numeric profile fields are inconsistent or missing.
    NumericProfileMismatch,
    /// The manifest's formula registry does not match the declared formula
    /// identity set.
    FormulaRegistryMismatch,
    /// `leaf_floor_base[i] + leaf_floor_remainder[i]` does not sum to
    /// `LEAF_FLOOR_CONSERVATION_TARGET` for some `i`.
    FloorTableNotConserved,
}

/// Manifest schema this module verifies against. Field names and nesting
/// mirror the REAL shape emitted by the `mfw` producer (confirmed against
/// `crates/bcinr-cmca/generated-artifact/case-studies/cmca_generation_manifest.json`,
/// a materialized real manifest, on 2026-07-17): a nested `digests` object
/// holding the six named digests from contract §3.1, a nested `dimensions`
/// object holding the `N`/`F`/`K`/`Q`/`leaf_floor_n_max` scalar bounds
/// (contract §4 item 2), a `generator_source_order` array (contract §3 item
/// 3: "the order MUST be recorded in the manifest"), and a `numeric_profile`
/// object (contract §3.1 item 4). There is no `leaf_count`,
/// `leaf_floor_table`, `registry_indices`, or `registry_dimension` field in
/// the real manifest: those were fields of an earlier, wrong, flat-shaped
/// consumer assumption this struct previously encoded and that never matched
/// what `mfw` actually emits. The per-leaf floor table and registry data
/// those fields tried to describe live as compile-time arrays inside
/// `cmca_generated.rs` itself (e.g. `LEAF_FLOOR_BASE`/`LEAF_FLOOR_REMAINDER`),
/// not inside the manifest JSON.
#[derive(Debug, Deserialize)]
pub struct GeneratedManifest {
    pub schema_version: u32,
    pub digests: ManifestDigests,
    pub dimensions: ManifestDimensions,
    pub generator_source_order: Vec<String>,
    pub numeric_profile: NumericProfile,
}

/// The six named digests from contract §3.1, nested under `digests` in the
/// real manifest (not flat top-level fields).
#[derive(Debug, Deserialize)]
pub struct ManifestDigests {
    pub rdf_digest: String,
    pub admission_digest: String,
    pub generator_digest: String,
    pub numeric_profile_digest: String,
    pub formula_registry_digest: String,
    /// `blake3:<hex>` digest of the exact bytes of `cmca_generated.rs`.
    pub generated_payload_digest: String,
}

/// The `N`/`F`/`K`/`Q`/`leaf_floor_n_max` dimension bounds, nested under
/// `dimensions` in the real manifest. Field names are uppercase in the real
/// JSON (matching the uppercase Rust consts of the same name in
/// `cmca_generated.rs`, e.g. `pub const N: usize = 8;`), hence the
/// `#[serde(rename)]`s below.
#[derive(Debug, Deserialize)]
pub struct ManifestDimensions {
    #[serde(rename = "F")]
    pub f: usize,
    #[serde(rename = "K")]
    pub k: usize,
    #[serde(rename = "N")]
    pub n: usize,
    #[serde(rename = "Q")]
    pub q: usize,
    pub leaf_floor_n_max: usize,
}

/// Contract §3.1 item 4: "the Decimal precision, the rounding mode, the
/// min/max representable range, and the Q16.16 scale factor."
#[derive(Debug, Deserialize)]
pub struct NumericProfile {
    pub precision: u32,
    pub q16_16_scale: u64,
    pub rounding: String,
    pub signed_max: i64,
    pub signed_min: i64,
    pub unsigned_max: u64,
    pub unsigned_min: u64,
}

/// A generated artifact pair: the manifest and the raw bytes of the
/// generated Rust source it describes. Callers (tests) construct this from
/// files on disk; this module never touches the filesystem itself, keeping
/// it independent of any particular artifact layout.
pub struct GeneratedArtifact<'a> {
    pub manifest: &'a GeneratedManifest,
    pub generated_source_bytes: &'a [u8],
}

/// Recomputes the BLAKE3 digest of `bytes` and formats it as
/// `blake3:<hex>`, matching the contract's declared digest format (§3.1:
/// "All are `blake3:<hex>` (BLAKE3, lowercase hex, `blake3:` prefix).").
fn blake3_digest_string(bytes: &[u8]) -> String {
    let hash = blake3::hash(bytes);
    let mut out = String::with_capacity(7 + 64);
    out.push_str("blake3:");
    out.push_str(&hash.to_hex());
    out
}

/// Extracts the value of `pub const NAME: usize = <value>;` (or `pub static
/// NAME: [T; <value>]` when `is_array_len` selects the array-length form)
/// from generated Rust source text. Returns `None` if the pattern is not
/// found or the captured text does not parse as `usize` — callers treat
/// `None` as a typed refusal, never a silent default.
fn extract_usize_const(source: &str, name: &str) -> Option<usize> {
    let needle = format!("pub const {name}: usize = ");
    let start = source.find(&needle)? + needle.len();
    let rest = &source[start..];
    let end = rest.find(';')?;
    rest[..end].trim().parse().ok()
}

/// Extracts every `{base}, {remainder}` scalar pair out of the bracketed
/// initializer list following `pub static NAME: [u32; N] = [...]`. Used to
/// re-derive the real `LEAF_FLOOR_BASE` / `LEAF_FLOOR_REMAINDER` arrays from
/// `cmca_generated.rs` source text so floor-table conservation can be
/// checked against the actual emitted tables, not a fabricated manifest
/// field (the real manifest carries no per-leaf floor data at all — see
/// `GeneratedManifest` docs).
fn extract_u32_array(source: &str, name: &str) -> Option<Vec<u64>> {
    let needle = format!("pub static {name}: ");
    let decl_start = source.find(&needle)?;
    let rest = &source[decl_start..];
    let bracket_start = rest.find('[')?;
    // Skip past the `[u32; N]` type annotation to the initializer's `[`.
    let after_type = &rest[bracket_start..];
    let eq_pos = after_type.find('=')?;
    let init = &after_type[eq_pos + 1..];
    let list_start = init.find('[')?;
    let list_end = init.find(']')?;
    let list = &init[list_start + 1..list_end];
    list.split(',')
        .map(|s| s.trim())
        .filter(|s| !s.is_empty())
        .map(|s| s.parse::<u64>().ok())
        .collect()
}

/// Verifies a generated Gamma_CMCA artifact per contract §4. Never panics;
/// every failure path returns a typed `GeneratedProfileRefusal`.
///
/// # Checks performed (contract §4, in order)
/// 1. `schema_version` recognized.
/// 2. `digests.generated_payload_digest` format is well-formed (`blake3:` +
///    64 hex chars) before comparison.
/// 3. Freshly computed BLAKE3 of `generated_source_bytes` matches the
///    manifest's declared `digests.generated_payload_digest`.
/// 4. `dimensions.{N,F,K,Q,leaf_floor_n_max}` each match the `pub const`
///    declaration of the same name actually emitted in
///    `cmca_generated.rs` (contract §4 item 2: "the N/F/K/Q dimension bounds
///    recorded in the manifest match what the generated arrays in
///    `cmca_generated.rs` actually declare").
/// 5. `LEAF_FLOOR_BASE`/`LEAF_FLOOR_REMAINDER`, re-derived from the real
///    generated source text, sum to `LEAF_FLOOR_CONSERVATION_TARGET` for
///    every leaf and have matching lengths.
pub fn verify_generated_profile(
    artifact: &GeneratedArtifact<'_>,
) -> Result<(), GeneratedProfileRefusal> {
    let manifest = artifact.manifest;

    // 1. schema_version recognized.
    if !SUPPORTED_SCHEMA_VERSIONS.contains(&manifest.schema_version) {
        return Err(GeneratedProfileRefusal::UnrecognizedSchemaVersion);
    }

    // 2. Digest format well-formed.
    let declared = &manifest.digests.generated_payload_digest;
    let hex_part = declared
        .strip_prefix("blake3:")
        .ok_or(GeneratedProfileRefusal::ManifestPayloadDisagreement)?;
    if hex_part.len() != 64 || !hex_part.bytes().all(|b| b.is_ascii_hexdigit()) {
        return Err(GeneratedProfileRefusal::ManifestPayloadDisagreement);
    }

    // 3. Recompute and compare.
    let recomputed = blake3_digest_string(artifact.generated_source_bytes);
    if &recomputed != declared {
        return Err(GeneratedProfileRefusal::PayloadDigestMismatch);
    }

    // 4. Dimension bounds match the real `pub const` declarations in
    // `cmca_generated.rs`.
    let source_text = core::str::from_utf8(artifact.generated_source_bytes)
        .map_err(|_| GeneratedProfileRefusal::DimensionMismatch)?;
    let expected_dims = [
        ("N", manifest.dimensions.n),
        ("F", manifest.dimensions.f),
        ("K", manifest.dimensions.k),
        ("Q", manifest.dimensions.q),
        ("LEAF_FLOOR_N_MAX", manifest.dimensions.leaf_floor_n_max),
    ];
    for (name, expected) in expected_dims {
        match extract_usize_const(source_text, name) {
            Some(actual) if actual == expected => {}
            _ => return Err(GeneratedProfileRefusal::DimensionMismatch),
        }
    }

    // 5. Floor-table conservation, re-derived from the real source text.
    let base = extract_u32_array(source_text, "LEAF_FLOOR_BASE")
        .ok_or(GeneratedProfileRefusal::TableLengthMismatch)?;
    let remainder = extract_u32_array(source_text, "LEAF_FLOOR_REMAINDER")
        .ok_or(GeneratedProfileRefusal::TableLengthMismatch)?;
    if base.len() != remainder.len() || base.len() != manifest.dimensions.leaf_floor_n_max {
        return Err(GeneratedProfileRefusal::TableLengthMismatch);
    }
    // Conservation formula per contract §3.1 item 5 / the emitted
    // `FORMULA_UNIFORM_LEAF_FLOOR_Q16_RESIDUAL` identity: for the entry at
    // index `i` (0-based), `n_leaves = i + 1`, and
    // `base[i] * n_leaves + remainder[i] == 65536` exactly — NOT
    // `base[i] + remainder[i]`. (An earlier version of this check summed
    // `base + remainder` directly, which matched a synthetic single-leaf
    // fixture but not the real generator's per-`n_leaves` array semantics;
    // corrected here against the real emitted `LEAF_FLOOR_BASE`/
    // `LEAF_FLOOR_REMAINDER` arrays.)
    for (i, (b, r)) in base.iter().zip(remainder.iter()).enumerate() {
        let n_leaves = (i as u64) + 1;
        let sum = b.checked_mul(n_leaves).and_then(|p| p.checked_add(*r));
        match sum {
            Some(s) if s == LEAF_FLOOR_CONSERVATION_TARGET => {}
            _ => return Err(GeneratedProfileRefusal::FloorTableNotConserved),
        }
    }

    Ok(())
}

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

    fn manifest(json: &str) -> GeneratedManifest {
        serde_json::from_str(json).expect("fixture manifest must parse")
    }

    /// Deterministic, fixed generated-source stand-in shaped like the real
    /// `cmca_generated.rs` (`pub const N/F/K/Q/LEAF_FLOOR_N_MAX: usize = ..;`
    /// plus `pub static LEAF_FLOOR_BASE`/`LEAF_FLOOR_REMAINDER` arrays), so
    /// the dimension- and floor-conservation checks exercise the same
    /// text-extraction path used against the real artifact. Two leaves:
    /// index 0 (`n_leaves = 1`): `65536*1 + 0 == 65536`; index 1
    /// (`n_leaves = 2`): `32768*2 + 0 == 65536`.
    const GENERATED_SOURCE: &[u8] = b"pub const N: usize = 2;\n\
          pub const F: usize = 1;\n\
          pub const K: usize = 1;\n\
          pub const Q: usize = 1;\n\
          pub const LEAF_FLOOR_N_MAX: usize = 2;\n\
          pub static LEAF_FLOOR_BASE: [u32; LEAF_FLOOR_N_MAX] = [65536, 32768];\n\
          pub static LEAF_FLOOR_REMAINDER: [u32; LEAF_FLOOR_N_MAX] = [0, 0];\n";

    fn valid_digest() -> String {
        blake3_digest_string(GENERATED_SOURCE)
    }

    /// Any well-formed `blake3:<64 hex>` string; used for the five digest
    /// fields this module does not itself recompute (only
    /// `generated_payload_digest` is checked against recomputed bytes).
    const FILLER_DIGEST: &str =
        "blake3:0000000000000000000000000000000000000000000000000000000000000000";

    fn valid_manifest_json(payload_digest: &str) -> String {
        format!(
            r#"{{
                "schema_version": 1,
                "digests": {{
                    "rdf_digest": "{FILLER_DIGEST}",
                    "admission_digest": "{FILLER_DIGEST}",
                    "generator_digest": "{FILLER_DIGEST}",
                    "numeric_profile_digest": "{FILLER_DIGEST}",
                    "formula_registry_digest": "{FILLER_DIGEST}",
                    "generated_payload_digest": "{payload_digest}"
                }},
                "dimensions": {{
                    "F": 1,
                    "K": 1,
                    "N": 2,
                    "Q": 1,
                    "leaf_floor_n_max": 2
                }},
                "generator_source_order": ["tools/cmca-generator/generator.py"],
                "numeric_profile": {{
                    "precision": 80,
                    "q16_16_scale": 65536,
                    "rounding": "ROUND_HALF_EVEN",
                    "signed_max": 2147483647,
                    "signed_min": -2147483648,
                    "unsigned_max": 4294967295,
                    "unsigned_min": 0
                }}
            }}"#
        )
    }

    #[test]
    fn valid_profile_accepted() {
        let digest = valid_digest();
        let m = manifest(&valid_manifest_json(&digest));
        let artifact = GeneratedArtifact {
            manifest: &m,
            generated_source_bytes: GENERATED_SOURCE,
        };
        assert_eq!(verify_generated_profile(&artifact), Ok(()));
    }

    #[test]
    fn unknown_schema_version_refused() {
        let digest = valid_digest();
        let json = valid_manifest_json(&digest)
            .replace("\"schema_version\": 1", "\"schema_version\": 999");
        let m = manifest(&json);
        let artifact = GeneratedArtifact {
            manifest: &m,
            generated_source_bytes: GENERATED_SOURCE,
        };
        assert_eq!(
            verify_generated_profile(&artifact),
            Err(GeneratedProfileRefusal::UnrecognizedSchemaVersion)
        );
    }

    #[test]
    fn payload_digest_mismatch_refused() {
        // Well-formed blake3: digest string, but not the real digest of
        // GENERATED_SOURCE.
        let wrong_digest = format!("blake3:{}", "1".repeat(64));
        let m = manifest(&valid_manifest_json(&wrong_digest));
        let artifact = GeneratedArtifact {
            manifest: &m,
            generated_source_bytes: GENERATED_SOURCE,
        };
        assert_eq!(
            verify_generated_profile(&artifact),
            Err(GeneratedProfileRefusal::PayloadDigestMismatch)
        );
    }

    #[test]
    fn malformed_digest_string_refused() {
        let m = manifest(&valid_manifest_json("not-a-blake3-digest"));
        let artifact = GeneratedArtifact {
            manifest: &m,
            generated_source_bytes: GENERATED_SOURCE,
        };
        assert_eq!(
            verify_generated_profile(&artifact),
            Err(GeneratedProfileRefusal::ManifestPayloadDisagreement)
        );
    }

    #[test]
    fn wrong_dimensions_refused() {
        let digest = valid_digest();
        // dimensions.N says 3 but the source's `pub const N: usize = 2;`
        // declares 2 — source bytes (and thus the digest) are unchanged.
        let json = valid_manifest_json(&digest).replace("\"N\": 2", "\"N\": 3");
        let m = manifest(&json);
        let artifact = GeneratedArtifact {
            manifest: &m,
            generated_source_bytes: GENERATED_SOURCE,
        };
        assert_eq!(
            verify_generated_profile(&artifact),
            Err(GeneratedProfileRefusal::DimensionMismatch)
        );
    }

    #[test]
    fn floor_table_not_conserved_refused() {
        // A different source whose second leaf (`n_leaves = 2`) is off by
        // one: `32768*2 + 1 == 65537 != 65536`. The digest is recomputed for
        // *this* source so the payload-digest check still passes and the
        // failure isolates to conservation.
        const BROKEN_SOURCE: &[u8] = b"pub const N: usize = 2;\n\
              pub const F: usize = 1;\n\
              pub const K: usize = 1;\n\
              pub const Q: usize = 1;\n\
              pub const LEAF_FLOOR_N_MAX: usize = 2;\n\
              pub static LEAF_FLOOR_BASE: [u32; LEAF_FLOOR_N_MAX] = [65536, 32768];\n\
              pub static LEAF_FLOOR_REMAINDER: [u32; LEAF_FLOOR_N_MAX] = [0, 1];\n";
        let digest = blake3_digest_string(BROKEN_SOURCE);
        let m = manifest(&valid_manifest_json(&digest));
        let artifact = GeneratedArtifact {
            manifest: &m,
            generated_source_bytes: BROKEN_SOURCE,
        };
        assert_eq!(
            verify_generated_profile(&artifact),
            Err(GeneratedProfileRefusal::FloorTableNotConserved)
        );
    }

    /// Smoke test against a real mfw-generated artifact tree, materialized
    /// under `crates/bcinr-cmca/generated-artifact/case-studies/` by an
    /// earlier reconciliation round. Provenance (producer command, exit
    /// codes, and the six digests this manifest declares) is recorded in
    /// `crates/bcinr-cmca/generated-artifact/PRODUCER_REPRODUCTION.md`.
    /// Reads only checked-in files under `CARGO_MANIFEST_DIR` — no network,
    /// no Python, no dependency on the `/Users/sac/mfw` repository being
    /// present.
    #[test]
    fn smoke_test_against_real_mfw_artifact() {
        let dir = concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/generated-artifact/case-studies"
        );
        let manifest_path = format!("{dir}/cmca_generation_manifest.json");
        let source_path = format!("{dir}/cmca_generated.rs");
        let manifest_bytes = std::fs::read_to_string(&manifest_path)
            .unwrap_or_else(|e| panic!("expected real manifest at {manifest_path}: {e}"));
        let source_bytes = std::fs::read(&source_path)
            .unwrap_or_else(|e| panic!("expected real generated source at {source_path}: {e}"));
        let m: GeneratedManifest =
            serde_json::from_str(&manifest_bytes).expect("real manifest must parse");
        let artifact = GeneratedArtifact {
            manifest: &m,
            generated_source_bytes: &source_bytes,
        };
        assert_eq!(verify_generated_profile(&artifact), Ok(()));
    }
}