wifi-densepose/examples/prime-radiant/docs/ddd/domain-model.md

Prime-Radiant Domain Model

Overview

Prime-Radiant is a mathematical framework for AI interpretability, built on rigorous foundations from algebraic topology, category theory, and quantum mechanics. This document describes the domain model using Domain-Driven Design (DDD) principles.

---

Bounded Contexts

1. Cohomology Context

Purpose: Analyze topological structure of representations and detect coherence failures.

Aggregates

Sheaf (Aggregate Root)

• Contains: Presheaf, Sections, RestrictionMaps
• Invariants: Gluing axioms, locality conditions
• Behavior: Compute cohomology, detect obstructions

ChainComplex

• Contains: ChainGroups, BoundaryMaps
• Invariants: d^2 = 0 (boundary of boundary is zero)
• Behavior: Compute homology groups

Value Objects

• Section: Data over an open set
• RestrictionMap: Linear map between stalks
• BettiNumbers: Topological invariants
• PersistenceDiagram: Multi-scale topology

Domain Events

• CoherenceViolationDetected: When H^1 is non-trivial
• TopologyChanged: When underlying graph structure changes
• SectionUpdated: When local data is modified

---

2. Category Context

Purpose: Model compositional structure and preserve mathematical properties.

Aggregates

Category (Aggregate Root)

• Contains: Objects, Morphisms
• Invariants: Identity, associativity
• Behavior: Compose morphisms, verify laws

Topos (Aggregate Root)

• Contains: Category, SubobjectClassifier, Products, Exponentials
• Invariants: Finite limits, exponentials exist
• Behavior: Internal logic, subobject classification

Entities

• Object: An element of the category
• Morphism: A transformation between objects
• Functor: Structure-preserving map between categories
• NaturalTransformation: Morphism between functors

Value Objects

• MorphismId: Unique identifier
• ObjectId: Unique identifier
• CompositionResult: Result of morphism composition

Domain Events

• MorphismAdded: New morphism in category
• FunctorApplied: Functor maps between categories
• CoherenceVerified: Axioms confirmed

---

3. HoTT Context (Homotopy Type Theory)

Purpose: Provide type-theoretic foundations for proofs and equivalences.

Aggregates

TypeUniverse (Aggregate Root)

• Contains: Types, Terms, Judgments
• Invariants: Type formation rules
• Behavior: Type checking, univalence

Path (Entity)

• Properties: Start, End, Homotopy
• Invariants: Endpoints match types
• Behavior: Concatenation, inversion, transport

Value Objects

• Type: A type in the universe
• Term: An element of a type
• Equivalence: Bidirectional map with proofs
• IdentityType: The type of paths between terms

Domain Services

• PathInduction: J-eliminator for paths
• Transport: Move values along paths
• Univalence: Equivalence = Identity

---

4. Spectral Context

Purpose: Analyze eigenvalue structure and spectral invariants.

Aggregates

SpectralDecomposition (Aggregate Root)

• Contains: Eigenvalues, Eigenvectors
• Invariants: Orthogonality, completeness
• Behavior: Compute spectrum, effective dimension

Value Objects

• Eigenspace: Subspace for eigenvalue
• SpectralGap: Distance between eigenvalues
• SpectralFingerprint: Comparison signature
• ConditionNumber: Numerical stability measure

Domain Services

• LanczosIteration: Efficient eigenvalue computation
• CheegerAnalysis: Spectral gap and graph cuts

---

5. Causal Context

Purpose: Implement causal abstraction for mechanistic interpretability.

Aggregates

CausalModel (Aggregate Root)

• Contains: Variables, Edges, StructuralEquations
• Invariants: DAG structure (no cycles)
• Behavior: Intervention, counterfactual reasoning

CausalAbstraction (Aggregate Root)

• Contains: LowModel, HighModel, VariableMapping
• Invariants: Interventional consistency
• Behavior: Verify abstraction, compute IIA

Entities

• Variable: A node in the causal graph
• Intervention: An action on a variable
• Circuit: Minimal subnetwork for behavior

Value Objects

• StructuralEquation: Functional relationship
• InterventionResult: Outcome of intervention
• AlignmentScore: How well mechanisms match

Domain Events

• InterventionApplied: Variable was modified
• CircuitDiscovered: Minimal mechanism found
• AbstractionViolation: Models disagree under intervention

---

6. Quantum Context

Purpose: Apply quantum-inspired methods to representation analysis.

Aggregates

QuantumState (Aggregate Root)

• Contains: Amplitudes
• Invariants: Normalization
• Behavior: Measure, evolve, entangle

DensityMatrix (Aggregate Root)

• Contains: Matrix elements
• Invariants: Positive semi-definite, trace 1
• Behavior: Entropy, purity, partial trace

Value Objects

• Entanglement: Correlation measure
• TopologicalInvariant: Robust property
• BerryPhase: Geometric phase

Domain Services

• EntanglementAnalysis: Compute entanglement measures
• TDAService: Topological data analysis

---

Cross-Cutting Concerns

Error Handling

All contexts use a unified error type hierarchy:

pub enum PrimeRadiantError {
    Cohomology(CohomologyError),
    Category(CategoryError),
    HoTT(HoTTError),
    Spectral(SpectralError),
    Causal(CausalError),
    Quantum(QuantumError),
}

Numerical Precision

• Default epsilon: 1e-10
• Configurable per computation
• Automatic condition number checking

Serialization

All value objects and aggregates implement:

• serde::Serialize and serde::Deserialize
• Custom formats for mathematical objects

---

Context Map

┌─────────────────────────────────────────────────────────────────┐
│                     Prime-Radiant Core                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
│  │ Cohomology  │────▶│  Category   │────▶│    HoTT     │       │
│  │   Context   │     │   Context   │     │   Context   │       │
│  └─────────────┘     └─────────────┘     └─────────────┘       │
│         │                   │                   │               │
│         │                   │                   │               │
│         ▼                   ▼                   ▼               │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
│  │  Spectral   │────▶│   Causal    │────▶│   Quantum   │       │
│  │   Context   │     │   Context   │     │   Context   │       │
│  └─────────────┘     └─────────────┘     └─────────────┘       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Relationships:
─────────────
Cohomology ──[U]──▶ Category  : Sheaves are presheaves + gluing (Upstream/Downstream)
Category   ──[U]──▶ HoTT      : Categories model type theory
Spectral   ──[S]──▶ Cohomology: Laplacian eigenvalues for cohomology (Shared Kernel)
Causal     ──[C]──▶ Category  : Causal abstraction as functors (Conformist)
Quantum    ──[P]──▶ Category  : Quantum channels as morphisms (Partnership)

---

Ubiquitous Language

Term	Definition
Sheaf	Assignment of data to open sets satisfying gluing axioms
Cohomology	Measure of obstruction to extending local sections globally
Morphism	Structure-preserving map between objects
Functor	Structure-preserving map between categories
Path	Continuous map from interval, proof of equality in HoTT
Equivalence	Bidirectional map with inverse proofs
Spectral Gap	Difference between consecutive eigenvalues
Intervention	Fixing a variable to a value (do-operator)
Entanglement	Non-local correlation in quantum states
Betti Number	Dimension of homology group

---

Implementation Guidelines

Aggregate Design

1. Keep aggregates small and focused
2. Use value objects for immutable data
3. Enforce invariants in aggregate root
4. Emit domain events for state changes

Repository Pattern

Each aggregate root has a repository:

pub trait SheafRepository {
    fn find_by_id(&self, id: SheafId) -> Option<Sheaf>;
    fn save(&mut self, sheaf: Sheaf) -> Result<(), Error>;
    fn find_by_topology(&self, graph: &Graph) -> Vec<Sheaf>;
}

Factory Pattern

Complex aggregates use factories:

pub struct SheafFactory {
    pub fn from_neural_network(network: &NeuralNetwork) -> Sheaf;
    pub fn from_knowledge_graph(kg: &KnowledgeGraph) -> Sheaf;
}

Domain Services

Cross-aggregate operations use services:

pub struct CoherenceService {
    pub fn check_global_consistency(sheaf: &Sheaf) -> CoherenceReport;
    pub fn optimize_sections(sheaf: &mut Sheaf) -> OptimizationResult;
}