//! Cryptographic commitment layer (L4) for the ontoref verifiable substrate.
//!
//! Maintains a per-cell `(entity, attribute) -> value` map and computes a
//! deterministic state root as a binary Merkle tree over the sorted set of
//! cell-key+value pairs. The same set of cells yields the same root on any
//! instance — this is the load-bearing property that makes external
//! verification (witness + root attestation) meaningful.
//!
//! G5 ships a hand-rolled binary Merkle tree rather than wiring NOMT
//! ([plan §9 R1](../../.coder/2026-05-25-implementation-final.plan.md)).
//! NOMT optimises for SSD-resident massive state and adds substantial API
//! surface; the prototype's gate (correctness of `determinism`,
//! `witness_verify`, `cross_instance`) is satisfied by any deterministic
//! commitment scheme, so the simpler choice removes external-dep risk.
//! The public API (`apply`, `root`, `witness`, `verify_witness`) is the
//! contract any later backend (NOMT, sparse-merkle-tree, jmt) must honour.

#![forbid(unsafe_code)]
#![warn(missing_docs)]

pub mod error;
pub mod layer;
pub mod tree;

pub use error::{Error, Result};
pub use layer::{BinaryMerkle, CellMergeKind, MergePolicy};
use ontoref_types::{AttrId, EntityId, Operation};
pub use tree::{cell_key, empty_root, verify_witness, CellKey, PathStep, StateRoot, Witness};

/// Pluggable commitment-backend trait (ADR-026 / D15).
///
/// The runtime is parameterised over any type implementing this trait.
/// [`BinaryMerkle`] is the default impl shipped with the substrate;
/// alternative backends (NOMT, sparse-merkle-tree, jmt) can be wired in
/// once trigger thresholds in `docs/validation/spike-triggers.md` are
/// exceeded.
///
/// Contract any backend MUST honour:
///
/// 1. `apply(op)` is the only mutation channel; calling it with the same
///    sequence of operations from any initial state must yield the same state
///    root.
/// 2. `root()` is deterministic — no clock, no randomness, no instance-specific
///    state may influence the bytes.
/// 3. A witness emitted by `witness(entity, attr)` MUST verify against the root
///    returned by the same instance immediately after the call.
/// 4. `verify_witness(w, r)` is a pure function — backends MUST NOT consult any
///    external state and MUST return the same bool for the same inputs.
pub trait CommitmentBackend {
    /// Apply one operation. Successful application updates internal state
    /// such that `root()` reflects the operation's effects.
    fn apply(&mut self, op: &Operation);

    /// Current commitment root over all applied operations.
    fn root(&self) -> StateRoot;

    /// Build an inclusion witness for the cell identified by
    /// `(entity, attr)`.
    ///
    /// # Errors
    ///
    /// Implementations MUST return an error when the cell has never been
    /// asserted under this backend instance.
    fn witness(&self, entity: &EntityId, attr: &AttrId) -> Result<Witness>;

    /// Verify a witness against a state root. Pure function — independent
    /// of any specific backend instance.
    fn verify_witness(witness: &Witness, root: &StateRoot) -> bool;
}

/// Backwards-compatible alias for the previous default backend name.
///
/// The struct was renamed to [`BinaryMerkle`] when the
/// [`CommitmentBackend`] trait was extracted (ADR-026 / D15). Existing
/// call sites continue to work without modification.
pub type CommitLayer = BinaryMerkle;
