Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

examples/exo-ai-2025/architecture/PSEUDOCODE.md

@@ -0,0 +1,645 @@
+# EXO-AI 2025: Pseudocode Design
+
+## SPARC Phase 2: Algorithm Design
+
+This document presents high-level pseudocode for the core algorithms in the EXO-AI cognitive substrate.
+
+---
+
+## 1. Learned Manifold Engine
+
+### 1.1 Manifold Retrieval via Gradient Descent
+
+```pseudocode
+FUNCTION ManifoldRetrieve(query_vector, k, manifold_network):
+    // Initialize search position at query
+    position = query_vector
+    visited_positions = []
+
+    // Gradient descent toward high-relevance regions
+    FOR step IN 1..MAX_DESCENT_STEPS:
+        // Forward pass through learned manifold
+        relevance_field = manifold_network.forward(position)
+
+        // Compute gradient of relevance
+        gradient = manifold_network.backward(relevance_field)
+
+        // Update position following relevance gradient
+        position = position - LEARNING_RATE * gradient
+        visited_positions.append(position)
+
+        // Check convergence
+        IF norm(gradient) < CONVERGENCE_THRESHOLD:
+            BREAK
+
+    // Extract k nearest patterns from converged region
+    results = []
+    FOR pos IN visited_positions.last(k):
+        patterns = ExtractPatternsNear(pos, manifold_network)
+        results.extend(patterns)
+
+    RETURN TopK(results, k)
+```
+
+### 1.2 Continuous Manifold Deformation
+
+```pseudocode
+FUNCTION ManifoldDeform(pattern, salience, manifold_network, optimizer):
+    // No discrete insert - continuous deformation instead
+
+    // Encode pattern as tensor
+    embedding = Tensor(pattern.embedding)
+
+    // Compute deformation loss
+    // Loss = how much the manifold needs to change to represent this pattern
+    current_relevance = manifold_network.forward(embedding)
+    target_relevance = salience
+    deformation_loss = (current_relevance - target_relevance)^2
+
+    // Add regularization for manifold smoothness
+    smoothness_loss = ManifoldCurvatureRegularizer(manifold_network)
+    total_loss = deformation_loss + LAMBDA * smoothness_loss
+
+    // Gradient update to manifold weights
+    gradients = total_loss.backward()
+    optimizer.step(gradients)
+
+    // Return delta for logging
+    RETURN ManifoldDelta(embedding, salience, total_loss)
+```
+
+### 1.3 Strategic Forgetting
+
+```pseudocode
+FUNCTION StrategicForget(manifold_network, decay_rate, salience_threshold):
+    // Identify low-salience regions
+    low_salience_regions = []
+
+    FOR region IN manifold_network.sample_regions():
+        avg_salience = ComputeAverageSalience(region)
+        IF avg_salience < salience_threshold:
+            low_salience_regions.append(region)
+
+    // Apply smoothing kernel to low-salience regions
+    // This effectively "forgets" by reducing specificity
+    FOR region IN low_salience_regions:
+        ForgetKernel = GaussianKernel(sigma=decay_rate)
+        manifold_network.apply_kernel(region, ForgetKernel)
+
+    // Optional: prune near-zero weights
+    manifold_network.prune_weights(threshold=1e-6)
+```
+
+---
+
+## 2. Hypergraph Substrate
+
+### 2.1 Hyperedge Creation
+
+```pseudocode
+FUNCTION CreateHyperedge(entities, relation, hypergraph):
+    // Validate all entities exist
+    FOR entity IN entities:
+        IF NOT hypergraph.base_graph.contains(entity):
+            RAISE EntityNotFoundError(entity)
+
+    // Generate hyperedge ID
+    hyperedge_id = GenerateUUID()
+
+    // Create hyperedge record
+    hyperedge = Hyperedge(
+        id = hyperedge_id,
+        entities = entities,
+        relation = relation,
+        created_at = NOW(),
+        weight = 1.0
+    )
+
+    // Insert into hyperedge storage
+    hypergraph.hyperedges.insert(hyperedge_id, hyperedge)
+
+    // Update inverted index (entity -> hyperedges)
+    FOR entity IN entities:
+        hypergraph.entity_index[entity].append(hyperedge_id)
+
+    // Update relation type index
+    hypergraph.relation_index[relation.type].append(hyperedge_id)
+
+    // Update simplicial complex for TDA
+    simplex = entities.as_simplex()
+    hypergraph.topology.add_simplex(simplex)
+
+    RETURN hyperedge_id
+```
+
+### 2.2 Persistent Homology Computation
+
+```pseudocode
+FUNCTION ComputePersistentHomology(hypergraph, dimension, epsilon_range):
+    // Build filtration (nested sequence of simplicial complexes)
+    filtration = BuildFiltration(hypergraph.topology, epsilon_range)
+
+    // Initialize boundary matrix for column reduction
+    boundary_matrix = BuildBoundaryMatrix(filtration, dimension)
+
+    // Column reduction algorithm (standard persistent homology)
+    reduced_matrix = ColumnReduction(boundary_matrix)
+
+    // Extract persistence pairs
+    pairs = []
+    FOR col_j IN reduced_matrix.columns:
+        IF reduced_matrix.low(j) != NULL:
+            i = reduced_matrix.low(j)
+            birth = filtration.birth_time(i)
+            death = filtration.birth_time(j)
+            pairs.append((birth, death))
+        ELSE IF col_j is a cycle:
+            birth = filtration.birth_time(j)
+            death = INFINITY  // Essential feature
+            pairs.append((birth, death))
+
+    // Build persistence diagram
+    diagram = PersistenceDiagram(
+        pairs = pairs,
+        dimension = dimension
+    )
+
+    RETURN diagram
+
+FUNCTION ColumnReduction(matrix):
+    // Standard algorithm from computational topology
+    FOR j IN 1..matrix.num_cols:
+        WHILE EXISTS j' < j WITH low(j') = low(j):
+            // Add column j' to column j to reduce
+            matrix.column(j) = matrix.column(j) XOR matrix.column(j')
+    RETURN matrix
+```
+
+### 2.3 Sheaf Consistency Check
+
+```pseudocode
+FUNCTION CheckSheafConsistency(sheaf, sections):
+    // Sheaf consistency: local sections should agree on overlaps
+
+    inconsistencies = []
+
+    // Check all pairs of overlapping sections
+    FOR (section_a, section_b) IN Pairs(sections):
+        overlap = section_a.domain.intersect(section_b.domain)
+
+        IF overlap.is_empty():
+            CONTINUE
+
+        // Restriction maps
+        restricted_a = sheaf.restrict(section_a, overlap)
+        restricted_b = sheaf.restrict(section_b, overlap)
+
+        // Check agreement
+        IF NOT ApproximatelyEqual(restricted_a, restricted_b, tolerance=EPSILON):
+            inconsistencies.append(
+                SheafInconsistency(
+                    sections = (section_a, section_b),
+                    overlap = overlap,
+                    discrepancy = Distance(restricted_a, restricted_b)
+                )
+            )
+
+    IF inconsistencies.is_empty():
+        RETURN SheafConsistencyResult.Consistent
+    ELSE:
+        RETURN SheafConsistencyResult.Inconsistent(inconsistencies)
+```
+
+---
+
+## 3. Temporal Memory Coordinator
+
+### 3.1 Causal Cone Query
+
+```pseudocode
+FUNCTION CausalQuery(query, reference_time, cone_type, temporal_memory):
+    // Determine valid time range based on causal cone
+    SWITCH cone_type:
+        CASE Past:
+            time_range = (MIN_TIME, reference_time)
+        CASE Future:
+            time_range = (reference_time, MAX_TIME)
+        CASE LightCone(velocity):
+            // Relativistic constraint: |delta_x| <= c * |delta_t|
+            time_range = ComputeLightCone(reference_time, query.origin, velocity)
+
+    // Filter candidates by time range
+    candidates = temporal_memory.long_term.filter_by_time(time_range)
+
+    // Similarity search within temporal constraint
+    similarities = []
+    FOR candidate IN candidates:
+        sim = CosineSimilarity(query.embedding, candidate.embedding)
+        causal_dist = temporal_memory.causal_graph.shortest_path(
+            query.origin,
+            candidate.id
+        )
+        similarities.append((candidate, sim, causal_dist))
+
+    // Rank by combined temporal and causal relevance
+    scored = []
+    FOR (candidate, sim, causal_dist) IN similarities:
+        temporal_score = 1.0 / (1.0 + abs(candidate.timestamp - reference_time))
+        causal_score = 1.0 / (1.0 + causal_dist) IF causal_dist != INF ELSE 0.0
+
+        combined = ALPHA * sim + BETA * temporal_score + GAMMA * causal_score
+        scored.append((candidate, combined))
+
+    RETURN sorted(scored, by=combined, descending=True)
+```
+
+### 3.2 Memory Consolidation
+
+```pseudocode
+FUNCTION Consolidate(temporal_memory):
+    // Biological-inspired memory consolidation
+    // Short-term -> Long-term with salience filtering
+
+    // Compute salience for all short-term items
+    salience_scores = []
+    FOR item IN temporal_memory.short_term:
+        salience = ComputeSalience(item, temporal_memory)
+        salience_scores.append((item, salience))
+
+    // Salience computation factors:
+    // - Frequency of access
+    // - Recency of access
+    // - Causal importance (how many things depend on it)
+    // - Surprise (deviation from expected)
+
+    FUNCTION ComputeSalience(item, memory):
+        access_freq = memory.access_counts[item.id]
+        recency = 1.0 / (1.0 + (NOW() - item.last_accessed))
+        causal_importance = memory.causal_graph.out_degree(item.id)
+        surprise = ComputeSurprise(item, memory.long_term)
+
+        RETURN W1*access_freq + W2*recency + W3*causal_importance + W4*surprise
+
+    // Filter by salience threshold
+    salient_items = [item FOR (item, s) IN salience_scores IF s > THRESHOLD]
+
+    // Integrate into long-term (manifold deformation)
+    FOR item IN salient_items:
+        temporal_memory.long_term.manifold.deform(item, salience)
+
+    // Strategic forgetting for low-salience items
+    FOR item IN temporal_memory.short_term:
+        IF item NOT IN salient_items:
+            // Don't integrate - let it decay
+            PASS
+
+    // Clear short-term buffer
+    temporal_memory.short_term.clear()
+
+    // Decay low-salience regions in long-term
+    temporal_memory.long_term.strategic_forget(DECAY_RATE)
+```
+
+### 3.3 Predictive Anticipation
+
+```pseudocode
+FUNCTION Anticipate(hints, temporal_memory):
+    // Pre-compute likely future queries based on hints
+    // This enables "predictive retrieval before queries are issued"
+
+    predicted_queries = []
+
+    FOR hint IN hints:
+        SWITCH hint.type:
+            CASE SequentialPattern:
+                // If A then B pattern detected
+                recent = temporal_memory.recent_queries()
+                FOR pattern IN temporal_memory.sequential_patterns:
+                    IF pattern.matches_prefix(recent):
+                        predicted = pattern.next_likely_query()
+                        predicted_queries.append(predicted)
+
+            CASE TemporalCycle:
+                // Time-of-day or periodic patterns
+                current_phase = GetTemporalPhase(NOW())
+                historical = temporal_memory.queries_at_phase(current_phase)
+                predicted_queries.extend(historical.top_k(5))
+
+            CASE CausalChain:
+                // Causal dependencies predict next queries
+                current_context = hint.current_context
+                downstream = temporal_memory.causal_graph.downstream(current_context)
+                FOR node IN downstream:
+                    predicted_queries.append(QueryFor(node))
+
+    // Pre-fetch and cache
+    FOR query IN predicted_queries:
+        cache_key = Hash(query)
+        IF cache_key NOT IN temporal_memory.prefetch_cache:
+            result = temporal_memory.long_term.search(query)
+            temporal_memory.prefetch_cache[cache_key] = result
+```
+
+---
+
+## 4. Federated Cognitive Mesh
+
+### 4.1 Post-Quantum Federation Handshake
+
+```pseudocode
+FUNCTION JoinFederation(local_node, peer_address):
+    // CRYSTALS-Kyber key exchange
+
+    // Generate ephemeral keypair
+    (local_public, local_secret) = Kyber.KeyGen()
+
+    // Send public key to peer
+    SendMessage(peer_address, FederationRequest(local_public))
+
+    // Receive peer's encapsulated shared secret
+    response = ReceiveMessage(peer_address)
+    ciphertext = response.ciphertext
+
+    // Decapsulate to get shared secret
+    shared_secret = Kyber.Decapsulate(ciphertext, local_secret)
+
+    // Derive session keys from shared secret
+    (encrypt_key, mac_key) = DeriveKeys(shared_secret)
+
+    // Establish encrypted channel
+    channel = EncryptedChannel(peer_address, encrypt_key, mac_key)
+
+    // Exchange capabilities and negotiate federation terms
+    local_caps = local_node.capabilities()
+    peer_caps = channel.exchange(local_caps)
+
+    terms = NegotiateFederationTerms(local_caps, peer_caps)
+
+    // Create federation token
+    token = FederationToken(
+        peer = peer_address,
+        channel = channel,
+        terms = terms,
+        expires = NOW() + TOKEN_VALIDITY
+    )
+
+    RETURN token
+```
+
+### 4.2 Onion-Routed Query
+
+```pseudocode
+FUNCTION OnionQuery(query, destination, relay_nodes, local_keys):
+    // Privacy-preserving query routing through onion network
+
+    // Build onion layers (innermost to outermost)
+    layers = [destination] + relay_nodes  // Reverse order for wrapping
+
+    // Start with plaintext query
+    current_payload = SerializeQuery(query)
+
+    // Wrap in layers
+    FOR node IN layers:
+        // Encrypt with node's public key
+        encrypted = AsymmetricEncrypt(current_payload, node.public_key)
+
+        // Add routing header
+        header = OnionHeader(
+            next_hop = node.address,
+            payload_type = "onion_layer"
+        )
+
+        current_payload = header + encrypted
+
+    // Send to first relay
+    first_relay = relay_nodes.last()
+    SendMessage(first_relay, current_payload)
+
+    // Receive response (also onion-wrapped)
+    encrypted_response = ReceiveMessage(first_relay)
+
+    // Unwrap response layers
+    current_response = encrypted_response
+    FOR node IN reverse(relay_nodes):
+        current_response = AsymmetricDecrypt(current_response, local_keys.secret)
+
+    // Final decryption with destination's response
+    result = DeserializeResponse(current_response)
+
+    RETURN result
+```
+
+### 4.3 CRDT Reconciliation
+
+```pseudocode
+FUNCTION ReconcileCRDT(responses, local_state):
+    // Conflict-free merge of federated query results
+
+    // Use G-Set CRDT for search results (grow-only set)
+    merged_results = GSet()
+
+    FOR response IN responses:
+        FOR result IN response.results:
+            // G-Set merge: union operation
+            merged_results.add(result)
+
+    // For rankings, use LWW-Register (last-writer-wins)
+    ranking_map = LWWMap()
+
+    FOR response IN responses:
+        FOR (result_id, score, timestamp) IN response.rankings:
+            ranking_map.set(result_id, score, timestamp)
+
+    // Combine: results from G-Set, scores from LWW-Map
+    final_results = []
+    FOR result IN merged_results:
+        score = ranking_map.get(result.id)
+        final_results.append((result, score))
+
+    // Sort by reconciled scores
+    final_results.sort(by=score, descending=True)
+
+    RETURN final_results
+```
+
+### 4.4 Byzantine Fault Tolerant Commit
+
+```pseudocode
+FUNCTION ByzantineCommit(update, federation):
+    // PBFT-style consensus for state updates
+    n = federation.node_count()
+    f = (n - 1) / 3  // Maximum Byzantine faults tolerable
+    threshold = 2*f + 1  // Required agreement
+
+    // Phase 1: Pre-prepare (leader proposes)
+    IF federation.is_leader():
+        proposal = SignedProposal(update, sequence_number=NEXT_SEQ)
+        Broadcast(federation.nodes, PrePrepare(proposal))
+
+    // Phase 2: Prepare (nodes acknowledge receipt)
+    pre_prepare = ReceivePrePrepare()
+    IF ValidateProposal(pre_prepare):
+        prepare_msg = Prepare(pre_prepare.digest, federation.local_id)
+        Broadcast(federation.nodes, prepare_msg)
+
+    // Collect prepare messages
+    prepares = CollectMessages(type=Prepare, count=threshold)
+
+    IF len(prepares) < threshold:
+        RETURN CommitResult.InsufficientPrepares
+
+    // Phase 3: Commit (nodes commit to proposal)
+    commit_msg = Commit(pre_prepare.digest, federation.local_id)
+    Broadcast(federation.nodes, commit_msg)
+
+    // Collect commit messages
+    commits = CollectMessages(type=Commit, count=threshold)
+
+    IF len(commits) >= threshold:
+        // Execute update
+        federation.apply_update(update)
+        proof = CommitProof(commits)
+        RETURN CommitResult.Success(proof)
+    ELSE:
+        RETURN CommitResult.InsufficientCommits
+```
+
+---
+
+## 5. Backend Abstraction
+
+### 5.1 Backend Selection
+
+```pseudocode
+FUNCTION SelectBackend(requirements, available_backends):
+    // Automatic backend selection based on requirements
+
+    scored_backends = []
+
+    FOR backend IN available_backends:
+        score = 0.0
+
+        // Evaluate against requirements
+        IF requirements.latency_target:
+            latency_score = 1.0 / backend.expected_latency
+            score += W_LATENCY * latency_score
+
+        IF requirements.energy_target:
+            energy_score = 1.0 / backend.expected_energy
+            score += W_ENERGY * energy_score
+
+        IF requirements.accuracy_target:
+            accuracy_score = backend.expected_accuracy
+            score += W_ACCURACY * accuracy_score
+
+        IF requirements.scale_target:
+            scale_score = backend.max_scale / requirements.scale_target
+            score += W_SCALE * min(scale_score, 1.0)
+
+        // Check hard constraints
+        IF requirements.wasm_required AND NOT backend.supports_wasm:
+            CONTINUE
+
+        IF requirements.post_quantum_required AND NOT backend.supports_pq:
+            CONTINUE
+
+        scored_backends.append((backend, score))
+
+    // Select highest scoring backend
+    best_backend = max(scored_backends, by=score)
+
+    RETURN best_backend
+```
+
+### 5.2 Hybrid Execution
+
+```pseudocode
+FUNCTION HybridExecute(operation, backends):
+    // Execute across multiple backends, combine results
+
+    // Partition operation if possible
+    partitions = PartitionOperation(operation)
+
+    // Assign partitions to backends based on suitability
+    assignments = []
+    FOR partition IN partitions:
+        best_backend = SelectBackendForPartition(partition, backends)
+        assignments.append((partition, best_backend))
+
+    // Execute in parallel
+    futures = []
+    FOR (partition, backend) IN assignments:
+        future = backend.execute_async(partition)
+        futures.append(future)
+
+    // Await all results
+    results = AwaitAll(futures)
+
+    // Merge partition results
+    merged = MergePartitionResults(results, operation.type)
+
+    RETURN merged
+```
+
+---
+
+## 6. Consciousness Metrics (Research)
+
+### 6.1 Phi (Integrated Information) Approximation
+
+```pseudocode
+FUNCTION ApproximatePhi(substrate_region):
+    // Compute integrated information (IIT-inspired)
+    // Full Phi computation is intractable; this is an approximation
+
+    // Step 1: Compute whole-system effective information
+    whole_state = substrate_region.current_state()
+    perturbed_states = []
+    FOR _ IN 1..NUM_PERTURBATIONS:
+        perturbed = ApplyRandomPerturbation(whole_state)
+        evolved = substrate_region.evolve(perturbed)
+        perturbed_states.append(evolved)
+
+    whole_EI = MutualInformation(whole_state, perturbed_states)
+
+    // Step 2: Find minimum information partition (MIP)
+    partitions = GeneratePartitions(substrate_region)
+    min_partition_EI = INFINITY
+
+    FOR partition IN partitions:
+        partition_EI = 0.0
+        FOR part IN partition:
+            part_state = part.current_state()
+            part_perturbed = [ApplyRandomPerturbation(part_state) FOR _ IN 1..NUM_PERTURBATIONS]
+            part_evolved = [part.evolve(p) FOR p IN part_perturbed]
+            partition_EI += MutualInformation(part_state, part_evolved)
+
+        IF partition_EI < min_partition_EI:
+            min_partition_EI = partition_EI
+            mip = partition
+
+    // Step 3: Phi = whole - minimum partition
+    phi = whole_EI - min_partition_EI
+
+    RETURN max(phi, 0.0)  // Phi cannot be negative
+```
+
+---
+
+## Summary
+
+These pseudocode algorithms define the core computational patterns for the EXO-AI cognitive substrate:
+
+| Component | Key Algorithm | Complexity |
+|-----------|---------------|------------|
+| Manifold Engine | Gradient descent retrieval | O(k × d × steps) |
+| Hypergraph | Persistent homology | O(n³) worst case |
+| Temporal Memory | Causal cone query | O(n × log n) |
+| Federation | Byzantine consensus | O(n²) messages |
+| Phi Metric | Partition enumeration | O(B(n)) Bell numbers |
+
+Where:
+- k = number of results
+- d = embedding dimension
+- n = number of entities/nodes
+- steps = gradient descent iterations