persistent-homology

name	persistent-homology
description	Topological data analysis for stable feature verification across filtrations of code complexity.
license	UNLICENSED
metadata	{"source":"local"}

Persistent Homology Skill: Stable Feature Verification

Status: ✅ Production Ready Trit: -1 (MINUS - validator/analyzer) Color: #2626D8 (Blue) Principle: Stable features → Robust structure Frame: Filtration with persistence diagrams

---

Overview

Persistent Homology identifies topological features that persist across scales. Implements:

1. Filtration: Nested sequence of complexes by parameter
2. Betti numbers: β₀ (components), β₁ (holes), β₂ (voids)
3. Persistence diagrams: Birth-death pairs for features
4. radare2 integration: Binary analysis for structure holes

Correct by construction: Features with long persistence are stable/significant; short-lived features are noise.

Core Formula

Filtration: K₀ ⊆ K₁ ⊆ ... ⊆ Kₙ  (by threshold ε)
Homology:   H_k(K_i) for each level
Persistence: (birth_i, death_j) for each feature

Stability Theorem:
  d_B(Dgm(f), Dgm(g)) ≤ ||f - g||_∞

For code complexity:

# Filtration by cyclomatic complexity threshold
filtration = [
  threshold_0: simple_functions,
  threshold_5: moderate_functions,
  threshold_10: complex_functions,
  threshold_20: very_complex_functions
]

# Persistent features survive across thresholds
stable_structure = features.select { |f| f.persistence > 5 }

Why Persistent Homology for Code?

1. Complexity filtration: Track structure across complexity levels
2. Structural holes: β₁ > 0 means cyclic dependencies
3. Stability: Long-lived features are fundamental
4. Noise filtering: Short-lived features are incidental

Gadgets

1. ComplexityFiltration

Build filtration from code complexity:

filtration = PersistentHomology::ComplexityFiltration.new(
  source: :codebase,
  metric: :cyclomatic_complexity
)
filtration.add_file("src/core.clj")
filtration.build!

filtration.levels           # => [0, 5, 10, 15, 20]
filtration.complex_at(10)   # => simplicial complex at threshold 10
filtration.inclusion(5, 10) # => inclusion map K_5 → K_10

2. BettiCalculator

Compute Betti numbers across filtration:

betti = PersistentHomology::BettiCalculator.new(filtration)
betti.compute!

betti.beta_0(level: 5)   # => connected components
betti.beta_1(level: 10)  # => 1-dimensional holes (cycles)
betti.beta_2(level: 15)  # => 2-dimensional voids
betti.euler_characteristic(level: 10)  # => χ = β₀ - β₁ + β₂

3. PersistenceDiagram

Track feature birth/death:

diagram = PersistentHomology::PersistenceDiagram.new(filtration)
diagram.compute!

diagram.pairs           # => [(birth, death), ...]
diagram.dimension(1)    # => 1-dim features only
diagram.persistence(feature)  # => death - birth
diagram.stable_features(threshold: 5)  # => long-lived only
diagram.bottleneck_distance(other_diagram)  # => stability metric

4. Radare2Analyzer

Integration with radare2 for binary analysis:

analyzer = PersistentHomology::Radare2Analyzer.new(
  binary_path: "/path/to/binary",
  analysis_level: 2
)
analyzer.analyze!

analyzer.function_call_graph    # => build complex from CFG
analyzer.complexity_filtration  # => filter by function size
analyzer.structural_holes       # => β₁ features (circular calls)
analyzer.persistence_diagram    # => stable binary structures

5. StabilityVerifier

Verify structural stability:

verifier = PersistentHomology::StabilityVerifier.new
verifier.add_version(:v1, filtration_v1)
verifier.add_version(:v2, filtration_v2)

result = verifier.verify!
result[:bottleneck_distance]     # => how different
result[:stable_preserved]        # => long-lived features kept
result[:new_stable_features]     # => emerged stable features
result[:lost_stable_features]    # => disappeared features
result[:gf3_conserved]           # => triad conservation

Commands

# Compute persistent features
just homology-persist

# Analyze specific codebase
just homology-filter src/

# Binary analysis with radare2
just homology-binary /path/to/binary

# Compare versions
just homology-diff v1 v2

API

require 'persistent_homology'

# Create analyzer
analyzer = PersistentHomology::Analyzer.new(
  trit: -1,
  filtration_metric: :complexity
)

# Build filtration
analyzer.add_codebase("src/")
filtration = analyzer.build_filtration!

# Compute persistence
diagram = analyzer.compute_persistence!

# Get stable features
stable = diagram.stable_features(threshold: 5)
stable.each do |feature|
  puts "#{feature.dimension}-dim: born=#{feature.birth}, died=#{feature.death}"
end

Integration with GF(3) Triads

Forms valid triads with ERGODIC (0) and PLUS (+1) skills:

persistent-homology (-1) ⊗ acsets (0) ⊗ gay-mcp (+1) = 0 ✓
persistent-homology (-1) ⊗ unworld (0) ⊗ cider-clojure (+1) = 0 ✓
persistent-homology (-1) ⊗ glass-bead-game (0) ⊗ rubato-composer (+1) = 0 ✓

Mathematical Foundation

Simplicial Homology

Chain complex: C_n(K) → C_{n-1}(K) → ... → C_0(K)
Boundary map:  ∂_n: C_n → C_{n-1}
Cycles:        Z_n = ker(∂_n)
Boundaries:    B_n = im(∂_{n+1})
Homology:      H_n = Z_n / B_n
Betti number:  β_n = dim(H_n)

Persistence Module

Filtration: K_0 ⊆ K_1 ⊆ ... ⊆ K_n
Induced maps: H_k(K_i) → H_k(K_j) for i ≤ j
Persistence: feature born at i, dies at j

Stability Theorem

d_B(Dgm(f), Dgm(g)) ≤ ||f - g||_∞

Where d_B is bottleneck distance between diagrams

Betti Numbers Interpretation

β₀ = connected components (clusters)
β₁ = 1-dimensional holes (loops, cycles)
β₂ = 2-dimensional voids (cavities)
β_n = n-dimensional holes

Example Output

─── Persistent Homology Analysis ───
Source: src/ (42 files, 1337 functions)
Metric: Cyclomatic complexity
Filtration levels: [0, 5, 10, 15, 20, 25]

Betti Numbers by Level:
  Level  0: β₀=42  β₁=0   β₂=0   (42 isolated functions)
  Level  5: β₀=15  β₁=3   β₂=0   (modules forming, 3 cycles)
  Level 10: β₀=8   β₁=5   β₂=1   (more structure)
  Level 15: β₀=3   β₁=7   β₂=2   (complex dependencies)
  Level 20: β₀=1   β₁=12  β₂=3   (highly connected)

Persistence Diagram (1-dim):
  Feature A: born=5,  died=20  (persistence=15) ★ STABLE
  Feature B: born=10, died=25  (persistence=15) ★ STABLE
  Feature C: born=15, died=17  (persistence=2)  (noise)

Stable Features (persistence > 5):
  ★ 2 stable 1-dimensional holes (cyclic dependencies)
  ★ 1 stable 2-dimensional void (higher-order structure)

Structural Assessment:
  Cyclic dependencies detected: 2 persistent cycles
  Recommendation: Refactor cycles at birth level 5, 10

GF(3) Trit: -1 (MINUS/Analyzer)

---

Skill Name: persistent-homology Type: Topological Data Analysis / Stable Feature Verification Trit: -1 (MINUS) Color: #2626D8 (Blue) GF(3): Forms valid triads with ERGODIC + PLUS skills Stability: Bottleneck distance bounds feature perturbation