Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/examples/exo-ai-2025/architecture/ARCHITECTURE.md

@@ -0,0 +1,805 @@
+# EXO-AI 2025: System Architecture
+
+## SPARC Phase 3: Architecture Design
+
+### Executive Summary
+
+This document defines the modular architecture for an experimental cognitive substrate platform, consuming the ruvector ecosystem as an SDK while exploring technologies projected for 2035-2060.
+
+---
+
+## 1. Architectural Principles
+
+### 1.1 Core Design Tenets
+
+| Principle | Description | Implementation |
+|-----------|-------------|----------------|
+| **SDK Consumer** | No modifications to ruvector crates | Clean dependency boundaries |
+| **Backend Agnostic** | Hardware abstraction via traits | PIM, neuromorphic, photonic backends |
+| **Substrate-First** | Data and compute unified | In-memory operations where possible |
+| **Topology Native** | Hypergraph as primary structure | Edges span arbitrary entity sets |
+| **Temporal Coherent** | Causal memory by default | Every operation timestamped |
+
+### 1.2 Layer Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    APPLICATION LAYER                             │
+│  ┌─────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
+│  │ Agent SDK   │ │ Query Engine │ │ Federation Gateway        │ │
+│  └─────────────┘ └──────────────┘ └───────────────────────────┘ │
+├─────────────────────────────────────────────────────────────────┤
+│                    SUBSTRATE LAYER                               │
+│  ┌─────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
+│  │ Manifold    │ │ Hypergraph   │ │ Temporal Memory           │ │
+│  │ Engine      │ │ Substrate    │ │ Coordinator               │ │
+│  └─────────────┘ └──────────────┘ └───────────────────────────┘ │
+├─────────────────────────────────────────────────────────────────┤
+│                    BACKEND ABSTRACTION                           │
+│  ┌─────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
+│  │ Classical   │ │ Neuromorphic │ │ Photonic                  │ │
+│  │ (ruvector)  │ │ (Future)     │ │ (Future)                  │ │
+│  └─────────────┘ └──────────────┘ └───────────────────────────┘ │
+├─────────────────────────────────────────────────────────────────┤
+│                    INFRASTRUCTURE                                │
+│  ┌─────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
+│  │ WASM        │ │ NAPI-RS      │ │ Native                    │ │
+│  │ Runtime     │ │ Bindings     │ │ Binaries                  │ │
+│  └─────────────┘ └──────────────┘ └───────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Module Design
+
+### 2.1 Core Modules
+
+```
+exo-ai-2025/
+├── crates/
+│   ├── exo-core/              # Core traits and types
+│   ├── exo-manifold/          # Learned manifold engine
+│   ├── exo-hypergraph/        # Hypergraph substrate
+│   ├── exo-temporal/          # Temporal memory coordinator
+│   ├── exo-federation/        # Federated mesh networking
+│   ├── exo-backend-classical/ # Classical backend (ruvector)
+│   ├── exo-backend-sim/       # Neuromorphic/photonic simulator
+│   ├── exo-wasm/              # WASM bindings
+│   └── exo-node/              # NAPI-RS bindings
+├── examples/
+├── docs/
+└── research/
+```
+
+### 2.2 exo-core: Foundational Traits
+
+```rust
+//! Core trait definitions for backend abstraction
+
+/// Backend trait for substrate compute operations
+pub trait SubstrateBackend: Send + Sync {
+    type Error: std::error::Error;
+
+    /// Execute similarity search on substrate
+    fn similarity_search(
+        &self,
+        query: &[f32],
+        k: usize,
+        filter: Option<&Filter>,
+    ) -> Result<Vec<SearchResult>, Self::Error>;
+
+    /// Deform manifold to incorporate new pattern
+    fn manifold_deform(
+        &self,
+        pattern: &Pattern,
+        learning_rate: f32,
+    ) -> Result<ManifoldDelta, Self::Error>;
+
+    /// Execute hyperedge query
+    fn hyperedge_query(
+        &self,
+        query: &TopologicalQuery,
+    ) -> Result<HyperedgeResult, Self::Error>;
+}
+
+/// Temporal context for causal operations
+pub trait TemporalContext {
+    /// Get current substrate time
+    fn now(&self) -> SubstrateTime;
+
+    /// Query with causal cone constraints
+    fn causal_query(
+        &self,
+        query: &Query,
+        cone: &CausalCone,
+    ) -> Result<Vec<CausalResult>, Error>;
+
+    /// Predictive pre-fetch based on anticipated queries
+    fn anticipate(&self, hints: &[AnticipationHint]) -> Result<(), Error>;
+}
+
+/// Pattern representation in substrate
+#[derive(Clone, Debug)]
+pub struct Pattern {
+    /// Vector embedding
+    pub embedding: Vec<f32>,
+    /// Metadata
+    pub metadata: Metadata,
+    /// Temporal origin
+    pub timestamp: SubstrateTime,
+    /// Causal antecedents
+    pub antecedents: Vec<PatternId>,
+}
+
+/// Topological query specification
+#[derive(Clone, Debug)]
+pub enum TopologicalQuery {
+    /// Find persistent homology features
+    PersistentHomology {
+        dimension: usize,
+        epsilon_range: (f32, f32),
+    },
+    /// Find N-dimensional holes in structure
+    BettiNumbers {
+        max_dimension: usize,
+    },
+    /// Sheaf consistency check
+    SheafConsistency {
+        local_sections: Vec<SectionId>,
+    },
+}
+```
+
+### 2.3 exo-manifold: Learned Representation Engine
+
+```rust
+//! Continuous manifold storage replacing discrete indices
+
+use burn::prelude::*;
+use crate::core::{Pattern, SubstrateBackend, ManifoldDelta};
+
+/// Implicit Neural Representation for manifold storage
+pub struct ManifoldEngine<B: Backend> {
+    /// Neural network representing the manifold
+    network: LearnedManifold<B>,
+    /// Tensor Train decomposition for compression
+    tt_decomposition: Option<TensorTrainConfig>,
+    /// Consolidation scheduler
+    consolidation: ConsolidationPolicy,
+}
+
+impl<B: Backend> ManifoldEngine<B> {
+    /// Query manifold via gradient descent
+    pub fn retrieve(
+        &self,
+        query: Tensor<B, 1>,
+        k: usize,
+    ) -> Vec<(Pattern, f32)> {
+        // Initialize at query position
+        let mut position = query.clone();
+
+        // Gradient descent toward relevant memories
+        for _ in 0..self.config.max_descent_steps {
+            let relevance = self.network.forward(position.clone());
+            let gradient = relevance.backward();
+            position = position - self.config.learning_rate * gradient;
+
+            if gradient.norm() < self.config.convergence_threshold {
+                break;
+            }
+        }
+
+        // Extract patterns from converged region
+        self.extract_patterns_near(position, k)
+    }
+
+    /// Continuous manifold deformation (replaces insert)
+    pub fn deform(&mut self, pattern: Pattern, salience: f32) {
+        let embedding = Tensor::from_floats(&pattern.embedding);
+
+        // Deformation = gradient update to manifold weights
+        let loss = self.deformation_loss(embedding, salience);
+        let gradients = loss.backward();
+
+        self.optimizer.step(gradients);
+    }
+
+    /// Strategic forgetting via manifold smoothing
+    pub fn forget(&mut self, region: &ManifoldRegion, decay_rate: f32) {
+        // Smooth the manifold in low-salience regions
+        self.apply_forgetting_kernel(region, decay_rate);
+    }
+}
+
+/// Learned manifold network architecture
+#[derive(Module)]
+pub struct LearnedManifold<B: Backend> {
+    /// SIREN-style sinusoidal layers
+    layers: Vec<SirenLayer<B>>,
+    /// Fourier feature encoding
+    fourier_features: FourierEncoding<B>,
+}
+```
+
+### 2.4 exo-hypergraph: Topological Substrate
+
+```rust
+//! Hypergraph substrate for higher-order relations
+
+use petgraph::Graph;
+use simplicial_topology::SimplicialComplex;
+use ruvector_graph::{GraphDatabase, HyperedgeSupport};
+
+/// Hypergraph substrate extending ruvector-graph
+pub struct HypergraphSubstrate {
+    /// Base graph from ruvector-graph
+    base: GraphDatabase,
+    /// Hyperedge index (relations spanning >2 entities)
+    hyperedges: HyperedgeIndex,
+    /// Simplicial complex for TDA
+    topology: SimplicialComplex,
+    /// Sheaf structure for consistency
+    sheaf: Option<SheafStructure>,
+}
+
+impl HypergraphSubstrate {
+    /// Create hyperedge spanning multiple entities
+    pub fn create_hyperedge(
+        &mut self,
+        entities: &[EntityId],
+        relation: &Relation,
+    ) -> Result<HyperedgeId, Error> {
+        // Validate entity existence
+        for entity in entities {
+            self.base.get_node(*entity)?;
+        }
+
+        // Create hyperedge in index
+        let hyperedge_id = self.hyperedges.insert(entities, relation);
+
+        // Update simplicial complex
+        self.topology.add_simplex(entities);
+
+        // Update sheaf sections if enabled
+        if let Some(ref mut sheaf) = self.sheaf {
+            sheaf.update_sections(hyperedge_id, entities)?;
+        }
+
+        Ok(hyperedge_id)
+    }
+
+    /// Topological query: find persistent features
+    pub fn persistent_homology(
+        &self,
+        dimension: usize,
+        epsilon_range: (f32, f32),
+    ) -> PersistenceDiagram {
+        use teia::persistence::compute_persistence;
+
+        let filtration = self.topology.filtration(epsilon_range);
+        compute_persistence(&filtration, dimension)
+    }
+
+    /// Query Betti numbers (topological invariants)
+    pub fn betti_numbers(&self, max_dim: usize) -> Vec<usize> {
+        (0..=max_dim)
+            .map(|d| self.topology.betti_number(d))
+            .collect()
+    }
+
+    /// Sheaf consistency: check local-to-global coherence
+    pub fn check_sheaf_consistency(
+        &self,
+        sections: &[SectionId],
+    ) -> SheafConsistencyResult {
+        match &self.sheaf {
+            Some(sheaf) => sheaf.check_consistency(sections),
+            None => SheafConsistencyResult::NotConfigured,
+        }
+    }
+}
+
+/// Hyperedge index structure
+struct HyperedgeIndex {
+    /// Hyperedge storage
+    edges: DashMap<HyperedgeId, Hyperedge>,
+    /// Inverted index: entity -> hyperedges containing it
+    entity_index: DashMap<EntityId, Vec<HyperedgeId>>,
+    /// Relation type index
+    relation_index: DashMap<RelationType, Vec<HyperedgeId>>,
+}
+```
+
+### 2.5 exo-temporal: Causal Memory Coordinator
+
+```rust
+//! Temporal memory with causal structure
+
+use std::collections::BTreeMap;
+use ruvector_core::VectorIndex;
+
+/// Temporal memory coordinator
+pub struct TemporalMemory {
+    /// Short-term volatile memory
+    short_term: ShortTermBuffer,
+    /// Long-term consolidated memory
+    long_term: LongTermStore,
+    /// Causal graph tracking antecedent relationships
+    causal_graph: CausalGraph,
+    /// Temporal knowledge graph (Zep-inspired)
+    tkg: TemporalKnowledgeGraph,
+}
+
+impl TemporalMemory {
+    /// Store with causal context
+    pub fn store(
+        &mut self,
+        pattern: Pattern,
+        antecedents: &[PatternId],
+    ) -> Result<PatternId, Error> {
+        // Add to short-term buffer
+        let id = self.short_term.insert(pattern.clone());
+
+        // Record causal relationships
+        for antecedent in antecedents {
+            self.causal_graph.add_edge(*antecedent, id);
+        }
+
+        // Update TKG with temporal relations
+        self.tkg.add_temporal_fact(id, &pattern, antecedents)?;
+
+        // Schedule consolidation if buffer full
+        if self.short_term.should_consolidate() {
+            self.trigger_consolidation();
+        }
+
+        Ok(id)
+    }
+
+    /// Causal cone query: retrieve within light-cone constraints
+    pub fn causal_query(
+        &self,
+        query: &Query,
+        reference_time: SubstrateTime,
+        cone_type: CausalConeType,
+    ) -> Vec<CausalResult> {
+        // Determine valid time range based on cone
+        let time_range = match cone_type {
+            CausalConeType::Past => (SubstrateTime::MIN, reference_time),
+            CausalConeType::Future => (reference_time, SubstrateTime::MAX),
+            CausalConeType::LightCone { velocity } => {
+                self.compute_light_cone(reference_time, velocity)
+            }
+        };
+
+        // Query with temporal filter
+        self.long_term
+            .search_with_time_range(query, time_range)
+            .into_iter()
+            .map(|r| CausalResult {
+                pattern: r.pattern,
+                causal_distance: self.causal_graph.distance(r.id, query.origin),
+                temporal_distance: (r.timestamp - reference_time).abs(),
+            })
+            .collect()
+    }
+
+    /// Anticipatory pre-fetch for predictive retrieval
+    pub fn anticipate(&mut self, hints: &[AnticipationHint]) {
+        for hint in hints {
+            // Pre-compute likely future queries
+            let predicted_queries = self.predict_future_queries(hint);
+
+            // Warm cache with predicted results
+            for query in predicted_queries {
+                self.prefetch_cache.insert(query.hash(),
+                    self.long_term.search(&query));
+            }
+        }
+    }
+
+    /// Memory consolidation: short-term -> long-term
+    fn consolidate(&mut self) {
+        // Identify salient patterns
+        let salient = self.short_term
+            .drain()
+            .filter(|p| p.salience > self.consolidation_threshold);
+
+        // Compress via manifold integration
+        for pattern in salient {
+            self.long_term.integrate(pattern);
+        }
+
+        // Strategic forgetting in long-term
+        self.long_term.decay_low_salience(self.decay_rate);
+    }
+}
+
+/// Causal graph for tracking antecedent relationships
+struct CausalGraph {
+    /// Forward edges: cause -> effects
+    forward: DashMap<PatternId, Vec<PatternId>>,
+    /// Backward edges: effect -> causes
+    backward: DashMap<PatternId, Vec<PatternId>>,
+}
+```
+
+### 2.6 exo-federation: Distributed Cognitive Mesh
+
+```rust
+//! Federated substrate with cryptographic sovereignty
+
+use ruvector_raft::{RaftNode, RaftConfig};
+use ruvector_cluster::ClusterManager;
+use kyberlib::{keypair, encapsulate, decapsulate};
+
+/// Federated cognitive mesh
+pub struct FederatedMesh {
+    /// Local substrate instance
+    local: Arc<SubstrateInstance>,
+    /// Raft consensus for local cluster
+    consensus: RaftNode,
+    /// Federation gateway
+    gateway: FederationGateway,
+    /// Post-quantum keypair
+    pq_keys: PostQuantumKeypair,
+}
+
+impl FederatedMesh {
+    /// Join federation with cryptographic handshake
+    pub async fn join_federation(
+        &mut self,
+        peer: &PeerAddress,
+    ) -> Result<FederationToken, Error> {
+        // Post-quantum key exchange
+        let (ciphertext, shared_secret) = encapsulate(&peer.public_key)?;
+
+        // Establish encrypted channel
+        let channel = self.gateway.establish_channel(
+            peer,
+            ciphertext,
+            shared_secret,
+        ).await?;
+
+        // Exchange federation capabilities
+        let token = channel.negotiate_federation().await?;
+
+        Ok(token)
+    }
+
+    /// Federated query with privacy preservation
+    pub async fn federated_query(
+        &self,
+        query: &Query,
+        scope: FederationScope,
+    ) -> Vec<FederatedResult> {
+        // Route through onion network for intent privacy
+        let onion_query = self.gateway.onion_wrap(query, scope)?;
+
+        // Broadcast to federation peers
+        let responses = self.gateway.broadcast(onion_query).await;
+
+        // CRDT reconciliation for eventual consistency
+        let reconciled = self.reconcile_crdt(responses)?;
+
+        reconciled
+    }
+
+    /// Byzantine fault tolerant consensus on shared state
+    pub async fn byzantine_commit(
+        &self,
+        update: &StateUpdate,
+    ) -> Result<CommitProof, Error> {
+        // Require 2f+1 agreement for n=3f+1 nodes
+        let threshold = (self.peer_count() * 2 / 3) + 1;
+
+        // Propose update
+        let proposal = self.consensus.propose(update)?;
+
+        // Collect votes
+        let votes = self.gateway.collect_votes(proposal).await;
+
+        if votes.len() >= threshold {
+            Ok(CommitProof::from_votes(votes))
+        } else {
+            Err(Error::InsufficientConsensus)
+        }
+    }
+}
+
+/// Post-quantum cryptographic keypair
+struct PostQuantumKeypair {
+    /// CRYSTALS-Kyber public key
+    public: [u8; 1184],
+    /// CRYSTALS-Kyber secret key
+    secret: [u8; 2400],
+}
+```
+
+---
+
+## 3. Backend Abstraction Layer
+
+### 3.1 Classical Backend (ruvector SDK)
+
+```rust
+//! Classical backend consuming ruvector crates
+
+use ruvector_core::{VectorIndex, HnswConfig};
+use ruvector_graph::GraphDatabase;
+use ruvector_gnn::GnnLayer;
+
+/// Classical substrate backend using ruvector
+pub struct ClassicalBackend {
+    /// Vector index from ruvector-core
+    vector_index: VectorIndex,
+    /// Graph database from ruvector-graph
+    graph_db: GraphDatabase,
+    /// GNN layer from ruvector-gnn
+    gnn: Option<GnnLayer>,
+}
+
+impl SubstrateBackend for ClassicalBackend {
+    type Error = ruvector_core::Error;
+
+    fn similarity_search(
+        &self,
+        query: &[f32],
+        k: usize,
+        filter: Option<&Filter>,
+    ) -> Result<Vec<SearchResult>, Self::Error> {
+        // Direct delegation to ruvector-core
+        let results = match filter {
+            Some(f) => self.vector_index.search_with_filter(query, k, f)?,
+            None => self.vector_index.search(query, k)?,
+        };
+
+        Ok(results.into_iter().map(SearchResult::from).collect())
+    }
+
+    fn manifold_deform(
+        &self,
+        pattern: &Pattern,
+        _learning_rate: f32,
+    ) -> Result<ManifoldDelta, Self::Error> {
+        // Classical backend: discrete insert
+        let id = self.vector_index.insert(&pattern.embedding, &pattern.metadata)?;
+
+        Ok(ManifoldDelta::DiscreteInsert { id })
+    }
+
+    fn hyperedge_query(
+        &self,
+        query: &TopologicalQuery,
+    ) -> Result<HyperedgeResult, Self::Error> {
+        // Use ruvector-graph hyperedge support
+        match query {
+            TopologicalQuery::PersistentHomology { .. } => {
+                // Compute via graph traversal
+                unimplemented!("TDA on classical backend")
+            }
+            TopologicalQuery::BettiNumbers { .. } => {
+                // Approximate via connected components
+                unimplemented!("Betti numbers on classical backend")
+            }
+            TopologicalQuery::SheafConsistency { .. } => {
+                // Not supported on classical backend
+                Ok(HyperedgeResult::NotSupported)
+            }
+        }
+    }
+}
+```
+
+### 3.2 Future Backend Traits
+
+```rust
+//! Placeholder traits for future hardware backends
+
+/// Processing-in-Memory backend interface
+pub trait PimBackend: SubstrateBackend {
+    /// Execute operation in memory bank
+    fn execute_in_memory(&self, op: &MemoryOperation) -> Result<(), Error>;
+
+    /// Query memory bank location for data
+    fn data_location(&self, pattern_id: PatternId) -> MemoryBank;
+}
+
+/// Neuromorphic backend interface
+pub trait NeuromorphicBackend: SubstrateBackend {
+    /// Encode vector as spike train
+    fn encode_spikes(&self, vector: &[f32]) -> SpikeTrain;
+
+    /// Decode spike train to vector
+    fn decode_spikes(&self, spikes: &SpikeTrain) -> Vec<f32>;
+
+    /// Submit spike computation
+    fn submit_spike_compute(&self, input: SpikeTrain) -> Result<SpikeTrain, Error>;
+}
+
+/// Photonic backend interface
+pub trait PhotonicBackend: SubstrateBackend {
+    /// Optical matrix-vector multiply
+    fn optical_matmul(&self, matrix: &OpticalMatrix, vector: &[f32]) -> Vec<f32>;
+
+    /// Configure optical interference pattern
+    fn configure_mzi(&self, config: &MziConfig) -> Result<(), Error>;
+}
+```
+
+---
+
+## 4. WASM & NAPI-RS Integration
+
+### 4.1 WASM Module Structure
+
+```rust
+//! WASM bindings for browser/edge deployment
+
+use wasm_bindgen::prelude::*;
+use crate::core::{Pattern, Query};
+
+#[wasm_bindgen]
+pub struct ExoSubstrate {
+    inner: Arc<SubstrateInstance>,
+}
+
+#[wasm_bindgen]
+impl ExoSubstrate {
+    #[wasm_bindgen(constructor)]
+    pub fn new(config: JsValue) -> Result<ExoSubstrate, JsError> {
+        let config: SubstrateConfig = serde_wasm_bindgen::from_value(config)?;
+        let inner = SubstrateInstance::new(config)?;
+        Ok(Self { inner: Arc::new(inner) })
+    }
+
+    #[wasm_bindgen]
+    pub async fn query(&self, embedding: Float32Array, k: u32) -> Result<JsValue, JsError> {
+        let query = Query::from_embedding(embedding.to_vec());
+        let results = self.inner.search(query, k as usize).await?;
+        Ok(serde_wasm_bindgen::to_value(&results)?)
+    }
+
+    #[wasm_bindgen]
+    pub fn store(&self, pattern: JsValue) -> Result<String, JsError> {
+        let pattern: Pattern = serde_wasm_bindgen::from_value(pattern)?;
+        let id = self.inner.store(pattern)?;
+        Ok(id.to_string())
+    }
+}
+```
+
+### 4.2 NAPI-RS Bindings
+
+```rust
+//! Node.js bindings via NAPI-RS
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+#[napi]
+pub struct ExoSubstrateNode {
+    inner: Arc<RwLock<SubstrateInstance>>,
+}
+
+#[napi]
+impl ExoSubstrateNode {
+    #[napi(constructor)]
+    pub fn new(config: serde_json::Value) -> Result<Self> {
+        let config: SubstrateConfig = serde_json::from_value(config)?;
+        let inner = SubstrateInstance::new(config)?;
+        Ok(Self { inner: Arc::new(RwLock::new(inner)) })
+    }
+
+    #[napi]
+    pub async fn search(&self, embedding: Float32Array, k: u32) -> Result<Vec<SearchResultJs>> {
+        let guard = self.inner.read().await;
+        let results = guard.search(
+            Query::from_embedding(embedding.to_vec()),
+            k as usize,
+        ).await?;
+        Ok(results.into_iter().map(SearchResultJs::from).collect())
+    }
+
+    #[napi]
+    pub async fn hypergraph_query(&self, query: String) -> Result<serde_json::Value> {
+        let guard = self.inner.read().await;
+        let topo_query: TopologicalQuery = serde_json::from_str(&query)?;
+        let result = guard.hypergraph.query(&topo_query).await?;
+        Ok(serde_json::to_value(result)?)
+    }
+}
+```
+
+---
+
+## 5. Deployment Targets
+
+### 5.1 Build Configurations
+
+```toml
+# Cargo.toml feature flags
+
+[features]
+default = ["classical-backend"]
+
+# Backends
+classical-backend = ["ruvector-core", "ruvector-graph", "ruvector-gnn"]
+sim-neuromorphic = []
+sim-photonic = []
+
+# Deployment targets
+wasm = ["wasm-bindgen", "getrandom/js"]
+napi = ["napi", "napi-derive"]
+
+# Experimental features
+tensor-train = []
+sheaf-consistency = []
+post-quantum = ["kyberlib", "pqcrypto"]
+```
+
+### 5.2 Platform Matrix
+
+| Target | Backend | Features | Size |
+|--------|---------|----------|------|
+| `wasm32-unknown-unknown` | Classical (memory-only) | Core substrate | ~2MB |
+| `x86_64-unknown-linux-gnu` | Classical (full) | All features | ~15MB |
+| `aarch64-apple-darwin` | Classical (full) | All features | ~12MB |
+| Node.js (NAPI) | Classical (full) | All features | ~8MB |
+
+---
+
+## 6. Future Architecture Extensions
+
+### 6.1 PIM Integration Path
+
+```
+Phase 1: Abstraction (Current)
+├── Define PimBackend trait
+├── Implement simulation mode
+└── Profile classical baseline
+
+Phase 2: Emulation
+├── UPMEM SDK integration
+├── Performance modeling
+└── Hybrid execution strategies
+
+Phase 3: Native Hardware
+├── Custom PIM firmware
+├── Memory bank allocation
+└── Direct execution path
+```
+
+### 6.2 Consciousness Metrics (Research)
+
+```rust
+//! Experimental: Integrated Information metrics
+
+/// Compute Phi (integrated information) for substrate region
+pub fn compute_phi(
+    substrate: &SubstrateRegion,
+    partition_strategy: PartitionStrategy,
+) -> f64 {
+    // Compute information generated by whole
+    let whole_info = substrate.effective_information();
+
+    // Compute information generated by parts
+    let partitions = partition_strategy.partition(substrate);
+    let parts_info: f64 = partitions
+        .iter()
+        .map(|p| p.effective_information())
+        .sum();
+
+    // Phi = whole - parts (simplified IIT measure)
+    (whole_info - parts_info).max(0.0)
+}
+```
+
+---
+
+## References
+
+- SPARC Specification: `specs/SPECIFICATION.md`
+- Research Papers: `research/PAPERS.md`
+- Rust Libraries: `research/RUST_LIBRARIES.md`