moonlight-homology

Part of Moonlight, the sheaf-theoretic computation layer beneath Melusine and Pale Meridian.

The homology foundation for Pale Meridian. Finite chain complexes, validated boundary-incidence matrices, phase-gated rank/homology backends, exact and spectral sequences, discrete Morse reductions, persistence, and finite topological carriers: the homological invariants the sheaf, derived, e-graph, geometry, and analysis layers build on.

Built on moonlight-core, moonlight-algebra, and moonlight-linalg.

What it provides

• Finite chain complexes. FiniteChainComplex over any coefficient ring: a top homological degree plus a validated boundary-incidence matrix at each degree. Construction is total and explicit-error: malformed shapes are rejected as typed failures.
• Phase-gated homology. Every Betti/homology computation is unlocked by a capability value that first verifies boundary nilpotence (∂ ∘ ∂ = 0). A complex that fails the law returns a law violation before backend dispatch.
• Coefficient backends. One runHomologyBackend dispatcher over three regimes: Smith-normal-form integral homology (with torsion), rational field ranks, and GF(2) field ranks. A GADT ties each backend to its coefficient type, so a mismatched backend is a compile error.
• Exact and spectral sequences. Filtered spectral families with page-by-page reduction and convergence tracking; exact-sequence helpers; Block–Schur reductions.
• Persistence. One- and two-parameter filtered complexes and mod-2 persistence pairs.
• Discrete Morse theory. Acyclic matchings that reduce a complex to its critical cells while preserving homology.
• Topological carriers. Cell complexes, graph 1-skeletons, Reeb/macro-scaffold structures, graph-Laplacian spectral modes, an observation EDSL over topology witnesses, and declarative topological constraints.
• Cell-complex categories. CellComplex2D is available as a narrow public component, and ComplexCat derives its finite incidence category without importing the matrix or spectral topology closure.

Key operations

Build a finite chain complex

The foundational object is the finite chain complex: a top degree together with a validated boundary-incidence matrix at each degree. Present a circle as a triangle: three vertices, three oriented edges glued head to tail. The degree-1 boundary sends each oriented edge to head − tail; every degree above 1 is empty.

{-# LANGUAGE DataKinds #-}

import Moonlight.Homology

circle :: Either BoundaryIncidenceShapeError (FiniteChainComplex Rational)
circle = do
  d1 <-
    mkBoundaryIncidence 3 3
      [ mkBoundaryEntry 0 0 (-1), mkBoundaryEntry 0 1 1,
        mkBoundaryEntry 1 1 (-1), mkBoundaryEntry 1 2 1,
        mkBoundaryEntry 2 2 (-1), mkBoundaryEntry 2 0 1
      ]
  pure $
    mkFiniteChainComplex (HomologicalDegree 1) $ \degree ->
      case degree of
        HomologicalDegree 1 -> d1
        HomologicalDegree 0 -> emptyBoundaryIncidenceOf 3 0
        _                   -> emptyBoundaryIncidence

mkBoundaryIncidence sourceDim targetDim entries builds the validated matrix of ∂ₙ, the boundary map from the sourceDim cells of degree n to the targetDim cells of degree n − 1. Each mkBoundaryEntry source target coefficient is one nonzero incidence: the degree-n cell source contains the degree-(n − 1) cell target in its boundary with that coefficient. Edge 0, entries (0, 0, -1) and (0, 1, 1), encodes ∂(edge₀) = vertex₁ − vertex₀, running from vertex 0 (tail, -1) to vertex 1 (head, +1); edges 1 and 2 close the loop v₀ → v₁ → v₂ → v₀. Construction is total: mismatched shapes are rejected as BoundaryIncidenceShapeError. emptyBoundaryIncidenceOf sourceDim targetDim is the zero map of that shape (here ∂₀, three vertices to nothing), and emptyBoundaryIncidence the empty map used above the top degree. mkFiniteChainComplex topDegree atDegree then assembles the complex from its boundary at each degree: a top degree and one ∂ per degree.

Betti numbers over a field

computeBettiNumbers is phase-gated: it verifies boundary nilpotence before any rank backend runs, so a BettiCapability is the only key that unlocks the count. For the circle, fmap freeRank on the result is [1, 1]: b₀ = 1 (one component), b₁ = 1 (one loop).

betti :: FiniteChainComplex Rational -> Either HomologyFailure [HomologyGroup Rational]
betti =
  computeBettiNumbers
    (fieldBettiCapability RationalFieldRankBackend :: BettiCapability 'Phase2 Rational)

The gate is total: a malformed complex yields Left (InvalidTopologyInput …), and a non-nilpotent boundary yields Left (ChainComplexNilpotenceViolation d), naming the lower degree of the offending composite — the same constructor the checked constructor path reports. A BettiCapability is required for the count.

Integral homology and torsion

Field ranks see only free rank; torsion is invisible to them. To recover the full finitely-generated decomposition, run the Smith-normal-form backend. The real projective plane RP² is the canonical witness: one cell in each degree 0, 1, and 2, with the 2-cell attached by a degree-2 map, giving H₁(RP²) = ℤ/2.

{-# LANGUAGE DataKinds #-}

import Moonlight.Homology

realProjectivePlane :: Either BoundaryIncidenceShapeError (FiniteChainComplex Integer)
realProjectivePlane = do
  d2 <- mkBoundaryIncidence 1 1 [mkBoundaryEntry 0 0 2]
  pure $
    mkFiniteChainComplex (HomologicalDegree 2) $ \degree ->
      case degree of
        HomologicalDegree 2 -> d2
        HomologicalDegree 1 -> emptyBoundaryIncidenceOf 1 1
        HomologicalDegree 0 -> emptyBoundaryIncidenceOf 1 0
        _                   -> emptyBoundaryIncidence

integralHomology ::
  FiniteChainComplex Integer -> Either HomologyFailure [HomologyGroup Integer]
integralHomology =
  runHomologyBackend (IntegralSmithBackend :: HomologyBackend Integer Integer)

On the result, fmap freeRank is [1, 0, 0] and fmap torsionInvariants is [[], [2], []]: the ℤ/2 in degree 1 missed by rational and mod-2 Betti counts.

Choosing a rank backend

runHomologyBackend unifies all three coefficient regimes behind one call. The HomologyBackend GADT ties each backend to the coefficient type it accepts, so the compiler rejects a backend applied to the wrong complex.

Backend	Complex	Result
IntegralSmithBackend	FiniteChainComplex over any Integral	full groups with torsionInvariants
RationalRankBackend	FiniteChainComplex Rational	rational Betti (freeRank)
GF2RankBackend	FiniteChainComplex GF2	mod-2 Betti (freeRank)

homologyBackendTag recovers the HomologyBackendTag for logging or downstream dispatch.

Beyond Betti

The same finite chain complex feeds the higher invariants. Each is reachable from the Moonlight.Homology umbrella, or from the narrower module noted below.

• Persistence. mkFilteredFiniteChainComplex builds a filtered complex; mod2PersistentPairs reads its birth/death pairs, and BiPersistencePair carries the two-parameter case. In Moonlight.Homology.Persistence.
• Spectral sequences. mkSpectralSource and spectralFamilyPages produce the page-by-page family; spectralFamilyLimitPage, spectralFamilyStableFrom, and convergenceDepth track convergence. In Moonlight.Homology.Sequence.
• Discrete Morse. morseComplex (and morseComplexWith / refinedMorseComplex) reduce a complex to its critical cells while preserving homology; refinedMatchingCriticalCells and finalRefinedCriticalCellCount read the reduction.
• Topological carriers & constraints. mkCellCarrier and graph skeletons build topology witnesses; macro-scaffold observers (observeBettiVector, observeIntegralHomology, observeHarmonicCount) interrogate them; and evaluateTopologicalConstraint checks a declarative TopologicalConstraint.

Components

The pure core is carved into four private domain sublibraries along an acyclic dependency DAG (chain ← matrix ← topology ← sequence), two narrow public topology components, a public entry point, and a public law harness:

• moonlight-homology-chain: base vocabulary and chain algebra: degrees, groups, phases, failures, cell carriers, filtration values, the Chain algebra, reductions, graded torsion, and finite abelian groups.
• moonlight-homology-matrix: boundary matrices and rank: boundary incidence, Smith normal form, sparse and validated matrices, field and GF(2) rank backends, the phase-gated Betti reducer, and effective homology.
• moonlight-homology-topology: the topology subsystem: cell complexes, graph skeletons, Reeb/macro-scaffold structures, discrete Morse, persistence, graph-Laplacian spectral modes, observers, and the integral-homology backend dispatcher.
• moonlight-homology-sequence: exact sequences and filtered spectral sequences.
• cell-complex: the generic CellComplex2D incidence interface.
• cell-category: the finite, path-sensitive incidence category derived from any CellComplex2D.
• moonlight-homology: the public entry point below.
• moonlight-homology-laws: public law harness: boundary nilpotence, reduction, normalization, determinism.

Downstream packages import the public modules below.

Public modules

Module	Surface
Moonlight.Homology	Broad convenience surface over every module below.
Moonlight.Homology.Boundary	Boundary incidence, finite chain complexes, linear-algebra and Smith-normal-form helpers.
Moonlight.Homology.Boundary.GraphGF2	GF(2) boundary construction from graph data.
Moonlight.Homology.Chain	Degrees, groups, reductions, effective homology, graded torsion, phase-gated witnesses.
Moonlight.Homology.Matrix	Validated matrix construction and projections.
Moonlight.Homology.Rank	Field and GF(2) rank backends; Betti-capability construction.
Moonlight.Homology.Rank.Field	Rational/field rank-backend surface.
Moonlight.Homology.Rank.GF2	GF(2) rank-backend surface.
Moonlight.Homology.Backend	The HomologyBackend dispatcher: Smith / rational / GF(2).
Moonlight.Homology.Sequence	Exact and spectral sequences, Block–Schur reductions, graph spectral helpers.
Moonlight.Homology.Topology	Cell complexes, graph skeletons, macro-scaffolds, discrete Morse, persistence values, observers, and constraints.
Moonlight.Homology.Persistence	Filtered complexes and mod-2 persistence pairs.
Moonlight.Homology.Pure.Topology.CellComplex	Generic two-dimensional cell incidence; requires moonlight-homology:cell-complex.
Moonlight.Homology.Pure.Topology.CellCategory	Finite incidence category for a CellComplex2D; requires moonlight-homology:cell-category.
Moonlight.Homology.Effect.Laws	Boundary-nilpotence and reduction law harnesses.
Moonlight.Homology.Effect.Determinism	Deterministic fingerprints for bases, incidences, and complexes.

Benchmarks

tasty-bench covers boundary construction, rank backends, reductions, and persistence helpers.

License

MIT; see LICENSE. Third-party notes in THIRD_PARTY_NOTICES.md.

cabal install moonlight-homology