uor-foundation 0.1.2

// @generated by uor-crate from uor-ontology — do not edit manually

//! `cohomology/` namespace — Cochain complexes, sheaf cohomology, and local-to-global obstruction detection..
//!
//! Space: Bridge

use crate::Primitives;

/// A cochain group: the dual of a chain group, maps chains to coefficients.
pub trait CochainGroup<P: Primitives> {
    /// The degree k of this cochain group C^k.
    fn cochain_degree(&self) -> P::Integer;
    /// The rank (dimension) of this cochain group.
    fn cochain_rank(&self) -> P::NonNegativeInteger;
    /// Associated type for `ChainGroup`.
    type ChainGroup: crate::bridge::homology::ChainGroup<P>;
    /// The chain group that this cochain group is dual to.
    fn dual_of(&self) -> &Self::ChainGroup;
}

/// The coboundary operator δ^k: C^k → C^{k+1}. Satisfies δ² = 0.
pub trait CoboundaryOperator<P: Primitives> {
    /// Associated type for `CochainGroup`.
    type CochainGroup: CochainGroup<P>;
    /// The source cochain group of this coboundary operator.
    fn coboundary_source(&self) -> &Self::CochainGroup;
    /// The target cochain group of this coboundary operator.
    fn coboundary_target(&self) -> &Self::CochainGroup;
    /// Whether this coboundary operator satisfies δ² = 0.
    fn satisfies_coboundary_squared_zero(&self) -> P::Boolean;
}

/// A cochain complex: a sequence of cochain groups connected by coboundary operators.
pub trait CochainComplex<P: Primitives> {
    /// Associated type for `CochainGroup`.
    type CochainGroup: CochainGroup<P>;
    /// A cochain group belonging to this cochain complex.
    fn has_cochain_group(&self) -> &[Self::CochainGroup];
    /// Associated type for `CoboundaryOperator`.
    type CoboundaryOperator: CoboundaryOperator<P>;
    /// A coboundary operator belonging to this cochain complex.
    fn has_coboundary(&self) -> &[Self::CoboundaryOperator];
}

/// The k-th cohomology group H^k = ker(δ^k) / im(δ^{k-1}). Measures k-dimensional obstructions.
pub trait CohomologyGroup<P: Primitives> {
    /// The degree k of this cohomology group H^k.
    fn cohomology_degree(&self) -> P::Integer;
    /// The rank (dimension) of this cohomology group.
    fn cohomology_rank(&self) -> P::NonNegativeInteger;
}

/// A sheaf F over a simplicial complex: assigns data to each simplex with restriction maps.
pub trait Sheaf<P: Primitives> {
    /// Associated type for `SimplicialComplex`.
    type SimplicialComplex: crate::bridge::homology::SimplicialComplex<P>;
    /// The simplicial complex that this sheaf is defined over.
    fn sheaf_over(&self) -> &Self::SimplicialComplex;
    /// Associated type for `Ring`.
    type Ring: crate::kernel::schema::Ring<P>;
    /// The coefficient ring of this sheaf.
    fn coefficient_in(&self) -> &Self::Ring;
    /// Associated type for `Stalk`.
    type Stalk: Stalk<P>;
    /// A stalk belonging to this sheaf.
    fn has_stalks(&self) -> &[Self::Stalk];
    /// Associated type for `Section`.
    type Section: Section<P>;
    /// A global section of this sheaf.
    fn has_global_section(&self) -> &[Self::Section];
}

/// A stalk F_σ: the local data of a sheaf at a simplex σ.
pub trait Stalk<P: Primitives> {
    /// Associated type for `Simplex`.
    type Simplex: crate::bridge::homology::Simplex<P>;
    /// The simplex at which this stalk is located.
    fn stalk_at(&self) -> &Self::Simplex;
}

/// A global section of a sheaf: a consistent choice of local data across all simplices.
pub trait Section<P: Primitives> {}

/// A local section: a consistent choice of data over a subcomplex.
pub trait LocalSection<P: Primitives>: Section<P> {}

/// A restriction map ρ_{σ,τ}: maps data from a simplex to a face.
pub trait RestrictionMap<P: Primitives> {
    /// Associated type for `Simplex`.
    type Simplex: crate::bridge::homology::Simplex<P>;
    /// The source simplex of this restriction map.
    fn restricts_from(&self) -> &Self::Simplex;
    /// The target simplex (face) of this restriction map.
    fn restricts_to(&self) -> &Self::Simplex;
}

/// A gluing obstruction: a cohomology class that detects when local sections fail to glue.
pub trait GluingObstruction<P: Primitives> {
    /// Associated type for `CohomologyGroup`.
    type CohomologyGroup: CohomologyGroup<P>;
    /// The cohomology class that this gluing obstruction represents.
    fn obstruction_class(&self) -> &Self::CohomologyGroup;
    /// Associated type for `RefinementSuggestion`.
    type RefinementSuggestion: crate::bridge::resolver::RefinementSuggestion<P>;
    /// The refinement suggestion that, if applied, would resolve this gluing obstruction. Computed by the kernel when ψ₆ detects H^1 ≠ 0: the obstruction class indexes the fiber pair that is incompatible, and the suggestion targets that pair with a new bridging constraint.
    fn addresses_suggestion(&self) -> &[Self::RefinementSuggestion];
}

/// δ² = 0: the coboundary of a coboundary is zero.
pub mod coboundary_squared_zero {
    /// `forAll`
    pub const FOR_ALL: &str = "f ∈ C^k";
    /// `lhs`
    pub const LHS: &str = "δ^{k+1}(δ^k(f))";
    /// `rhs`
    pub const RHS: &str = "0";
    /// `verificationDomain` -> `Topological`
    pub const VERIFICATION_DOMAIN: &str = "https://uor.foundation/op/Topological";
    /// `verificationPathNote`
    pub const VERIFICATION_PATH_NOTE: &str = "CochainComplex → CoboundaryOperator → δ² = 0";
}

/// Discrete de Rham duality: H^k ≅ Hom(H_k, R).
pub mod de_rham_duality {
    /// `forAll`
    pub const FOR_ALL: &str = "simplicial complex K, ring R";
    /// `lhs`
    pub const LHS: &str = "H^k(K; R)";
    /// `rhs`
    pub const RHS: &str = "Hom(H_k(K), R)";
    /// `verificationDomain` -> `Topological`
    pub const VERIFICATION_DOMAIN: &str = "https://uor.foundation/op/Topological";
    /// `verificationPathNote`
    pub const VERIFICATION_PATH_NOTE: &str = "CohomologyGroup ≅ dual(HomologyGroup)";
}

/// Sheaf cohomology equals simplicial cohomology for constant sheaves.
pub mod sheaf_cohomology_bridge {
    /// `forAll`
    pub const FOR_ALL: &str = "constant sheaf F_R over K";
    /// `lhs`
    pub const LHS: &str = "H^k(K; F_R)";
    /// `rhs`
    pub const RHS: &str = "H^k(K; R)";
    /// `verificationDomain` -> `Topological`
    pub const VERIFICATION_DOMAIN: &str = "https://uor.foundation/op/Topological";
    /// `verificationPathNote`
    pub const VERIFICATION_PATH_NOTE: &str = "Sheaf → constant coefficient → CochainComplex";
}

/// Local-global principle: H^1(K; F) = 0 implies all local sections glue to global sections.
pub mod local_global_principle {
    /// `forAll`
    pub const FOR_ALL: &str = "sheaf F over K";
    /// `lhs`
    pub const LHS: &str = "H^1(K; F) = 0";
    /// `rhs`
    pub const RHS: &str = "all local sections glue";
    /// `verificationDomain` -> `Topological`
    pub const VERIFICATION_DOMAIN: &str = "https://uor.foundation/op/Topological";
    /// `verificationPathNote`
    pub const VERIFICATION_PATH_NOTE: &str = "CohomologyGroup → GluingObstruction → vanishing";
}