d803bfe2b1
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
322 lines
9.7 KiB
Markdown
322 lines
9.7 KiB
Markdown
# 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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
pub struct CoherenceService {
|
|
pub fn check_global_consistency(sheaf: &Sheaf) -> CoherenceReport;
|
|
pub fn optimize_sections(sheaf: &mut Sheaf) -> OptimizationResult;
|
|
}
|
|
```
|