Squashed 'vendor/ruvector/' content from commit b64c2172
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
This commit is contained in:
ruv
45
crates/cognitum-gate-kernel/Cargo.toml
Normal file
45
crates/cognitum-gate-kernel/Cargo.toml
Normal file
@@ -0,0 +1,45 @@
|
||||
[package]
|
||||
name = "cognitum-gate-kernel"
|
||||
version = "0.1.1"
|
||||
edition = "2021"
|
||||
rust-version = "1.75"
|
||||
license = "MIT OR Apache-2.0"
|
||||
authors = ["RuVector Contributors"]
|
||||
description = "No-std WASM kernel for 256-tile coherence gate fabric"
|
||||
keywords = ["wasm", "coherence", "mincut", "distributed", "no_std"]
|
||||
categories = ["algorithms", "no-std", "wasm"]
|
||||
repository = "https://github.com/ruvnet/ruvector"
|
||||
readme = "README.md"
|
||||
|
||||
[lib]
|
||||
crate-type = ["cdylib", "rlib"]
|
||||
|
||||
[dependencies]
|
||||
# Path dependency to ruvector-mincut for shared types (only for std builds)
|
||||
ruvector-mincut = { version = "2.0", path = "../ruvector-mincut", default-features = false, features = ["wasm"], optional = true }
|
||||
|
||||
# no_std compatible math
|
||||
libm = "0.2"
|
||||
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
# WASM-specific dependencies (none needed for core kernel)
|
||||
|
||||
[dev-dependencies]
|
||||
proptest = "1.4"
|
||||
criterion = { version = "0.5", features = ["html_reports"] }
|
||||
|
||||
[[bench]]
|
||||
name = "benchmarks"
|
||||
harness = false
|
||||
|
||||
[features]
|
||||
default = ["std"]
|
||||
std = ["ruvector-mincut"]
|
||||
canonical-witness = [] # Canonical pseudo-deterministic witness fragments
|
||||
|
||||
[profile.release]
|
||||
opt-level = "z" # Optimize for size
|
||||
lto = true # Enable LTO for smaller binaries
|
||||
codegen-units = 1 # Better optimization
|
||||
panic = "abort" # Smaller binary, no unwinding
|
||||
strip = true # Strip symbols
|
||||
980
crates/cognitum-gate-kernel/README.md
Normal file
980
crates/cognitum-gate-kernel/README.md
Normal file
@@ -0,0 +1,980 @@
|
||||
# cognitum-gate-kernel
|
||||
|
||||
[](https://crates.io/crates/cognitum-gate-kernel)
|
||||
[](https://docs.rs/cognitum-gate-kernel)
|
||||
[](LICENSE)
|
||||
[](https://github.com/ruvector/ruvector/actions)
|
||||
|
||||
A `no_std` WASM kernel for the **Anytime-Valid Coherence Gate** - a real-time permission system that decides "Is it safe to act right now, or should we pause or escalate?" The coherence gate provides formal safety guarantees for autonomous agent actions through continuous monitoring and evidence accumulation.
|
||||
|
||||
Think of it like a **smoke detector for AI agents**: it continuously monitors system coherence, can keep listening forever, and the moment it has enough evidence of instability, it triggers. Unlike traditional gating systems, you can stop the computation at any time and still trust the decision - that's what makes it "anytime-valid." The gate doesn't try to be smart; it tries to be **safe**, **calm**, and **correct** about permission.
|
||||
|
||||
The gate uses **three stacked filters** that must all agree before permitting an action: (1) **Structural** - graph coherence via dynamic min-cut to detect fragile partitions, (2) **Shift** - distribution monitoring to detect when the environment is changing, and (3) **Evidence** - e-value accumulation for sequential hypothesis testing with formal Type I error control. Every decision outputs a signed witness receipt explaining why.
|
||||
|
||||
> Created by [ruv.io](https://ruv.io) and [RuVector](https://github.com/ruvector/ruvector)
|
||||
|
||||
## Quick Start
|
||||
|
||||
Add to your `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
cognitum-gate-kernel = "0.1"
|
||||
```
|
||||
|
||||
Basic usage - create a worker tile, ingest graph deltas, tick, and get the report:
|
||||
|
||||
```rust
|
||||
use cognitum_gate_kernel::{TileState, Delta};
|
||||
|
||||
// Initialize a worker tile (ID 42 in the 256-tile fabric)
|
||||
let mut tile = TileState::new(42);
|
||||
|
||||
// Ingest graph deltas (edge additions, removals, weight updates)
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100)); // Add edge 0->1, weight 1.0
|
||||
tile.ingest_delta(&Delta::edge_add(1, 2, 150)); // Add edge 1->2, weight 1.5
|
||||
tile.ingest_delta(&Delta::edge_add(2, 0, 100)); // Complete the triangle
|
||||
|
||||
// Process one tick of the kernel
|
||||
let report = tile.tick(1);
|
||||
|
||||
// Check the coherence state
|
||||
println!("Vertices: {}, Edges: {}", report.num_vertices, report.num_edges);
|
||||
println!("Connected: {}", report.is_connected());
|
||||
println!("E-value: {:.2}", report.e_value_approx());
|
||||
|
||||
// Get the witness fragment for global aggregation
|
||||
let witness = tile.get_witness_fragment();
|
||||
println!("Local min-cut estimate: {}", witness.local_min_cut);
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><h2>Architecture</h2></summary>
|
||||
|
||||
### 256-Tile WASM Fabric
|
||||
|
||||
The coherence gate runs on a distributed fabric of 256 tiles, with TileZero acting as the central arbiter:
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------------------+
|
||||
| 256-TILE COGNITUM FABRIC |
|
||||
+-------------------------------------------------------------------------+
|
||||
| |
|
||||
| +-------------------------------------------------------------------+ |
|
||||
| | TILE ZERO (Arbiter) | |
|
||||
| | | |
|
||||
| | * Merge worker reports * Hierarchical min-cut | |
|
||||
| | * Global gate decision * Permit token issuance | |
|
||||
| | * Witness receipt log * Hash-chained eventlog | |
|
||||
| +-------------------------------+-----------------------------------+ |
|
||||
| | |
|
||||
| +--------------------+--------------------+ |
|
||||
| | | | |
|
||||
| v v v |
|
||||
| +----------------+ +----------------+ +----------------+ |
|
||||
| | Workers | | Workers | | Workers | ... |
|
||||
| | [1-85] | | [86-170] | | [171-255] | |
|
||||
| | | | | | | |
|
||||
| | Shard A | | Shard B | | Shard C | |
|
||||
| | Local cuts | | Local cuts | | Local cuts | |
|
||||
| | E-accum | | E-accum | | E-accum | |
|
||||
| +----------------+ +----------------+ +----------------+ |
|
||||
| |
|
||||
+-------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Worker Tile Responsibilities
|
||||
|
||||
Each of the 255 worker tiles maintains a **local shard** with:
|
||||
|
||||
- **CompactGraph** (~42KB): Vertices, edges, adjacency lists with union-find connectivity
|
||||
- **EvidenceAccumulator** (~2KB): Hypothesis tracking and sliding observation window
|
||||
- **Delta buffer** (1KB): Circular buffer for incoming graph updates
|
||||
- **Total**: ~46KB per tile, fitting within the 64KB WASM memory budget
|
||||
|
||||
Worker tiles perform:
|
||||
1. **Ingest deltas** - Edge additions, removals, weight updates, observations
|
||||
2. **Process ticks** - Deterministic tick loop updates local state
|
||||
3. **Produce reports** - 64-byte cache-aligned reports with coherence metrics
|
||||
4. **Emit witness fragments** - Boundary information for global aggregation
|
||||
|
||||
### TileZero Arbiter Role
|
||||
|
||||
TileZero collects reports from all worker tiles and:
|
||||
|
||||
1. **Merges reports** into a reduced supergraph
|
||||
2. **Applies three filters**: structural, shift, and evidence
|
||||
3. **Issues decisions**: `Permit`, `Defer`, or `Deny`
|
||||
4. **Signs permit tokens** with Ed25519
|
||||
5. **Maintains receipt log** with hash-chained audit trail
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
+-------------------+
|
||||
| Graph Updates |
|
||||
| (Edges, Weights) |
|
||||
+---------+---------+
|
||||
|
|
||||
v
|
||||
+---------------------------------------------------------------+
|
||||
| WORKER TILES [1-255] |
|
||||
| |
|
||||
| Delta --> CompactGraph --> Connectivity --> WitnessFragment |
|
||||
| --> EvidenceAccum --> LogEValue |
|
||||
| |
|
||||
+---------------------------+-----------------------------------+
|
||||
|
|
||||
TileReports (64 bytes each)
|
||||
|
|
||||
v
|
||||
+---------------------------------------------------------------+
|
||||
| TILEZERO ARBITER |
|
||||
| |
|
||||
| Structural Filter: global_cut >= min_cut_threshold? |
|
||||
| Shift Filter: shift_pressure < max_shift_threshold? |
|
||||
| Evidence Filter: e_aggregate in [tau_deny, tau_permit]? |
|
||||
| |
|
||||
| +-------> PERMIT (proceed autonomously) |
|
||||
| DECISION --+-------> DEFER (escalate to human) |
|
||||
| +-------> DENY (block the action) |
|
||||
| |
|
||||
+---------------------------+-----------------------------------+
|
||||
|
|
||||
v
|
||||
+-------------------+
|
||||
| PermitToken |
|
||||
| (signed + TTL) |
|
||||
+-------------------+
|
||||
|
|
||||
v
|
||||
+-------------------+
|
||||
| WitnessReceipt |
|
||||
| (hash-chained) |
|
||||
+-------------------+
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><h2>Technical Deep Dive</h2></summary>
|
||||
|
||||
### CompactGraph Internals
|
||||
|
||||
The `CompactGraph` structure is optimized for cache-efficient access on WASM:
|
||||
|
||||
```rust
|
||||
#[repr(C, align(64))] // Cache-line aligned
|
||||
pub struct CompactGraph {
|
||||
// HOT FIELDS (first cache line - 64 bytes)
|
||||
pub num_vertices: u16, // Active vertex count
|
||||
pub num_edges: u16, // Active edge count
|
||||
pub free_edge_head: u16, // Free list for edge reuse
|
||||
pub generation: u16, // Structural change counter
|
||||
pub num_components: u16, // Connected component count
|
||||
pub status: u16, // Dirty/connected flags
|
||||
_hot_pad: [u8; 52], // Padding to 64 bytes
|
||||
|
||||
// COLD FIELDS (subsequent cache lines)
|
||||
pub vertices: [VertexEntry; 256], // 256 * 8 = 2KB
|
||||
pub edges: [ShardEdge; 1024], // 1024 * 8 = 8KB
|
||||
pub adjacency: [[AdjEntry; 32]; 256], // 256 * 32 * 4 = 32KB
|
||||
}
|
||||
// Total: ~42KB
|
||||
```
|
||||
|
||||
**Key optimizations**:
|
||||
- `#[inline(always)]` on all hot-path accessors
|
||||
- Unsafe unchecked array access after bounds validation
|
||||
- Union-find with iterative path compression (no recursion)
|
||||
- Branchless flag manipulation for partition sides
|
||||
|
||||
### E-Value Accumulator Math
|
||||
|
||||
The evidence accumulator uses **fixed-point log2 representation** for numerical stability:
|
||||
|
||||
```rust
|
||||
pub type LogEValue = i32; // log2(e-value) * 65536
|
||||
|
||||
// Pre-computed threshold constants (avoid runtime log)
|
||||
pub const LOG_E_STRONG: LogEValue = 282944; // log2(20) * 65536
|
||||
pub const LOG_E_VERY_STRONG: LogEValue = 436906; // log2(100) * 65536
|
||||
pub const LOG_LR_CONNECTIVITY_POS: LogEValue = 38550; // log2(1.5) * 65536
|
||||
pub const LOG_LR_CONNECTIVITY_NEG: LogEValue = -65536; // log2(0.5) * 65536
|
||||
```
|
||||
|
||||
**E-value composition** (multiplicative):
|
||||
```
|
||||
log(e1 * e2) = log(e1) + log(e2)
|
||||
```
|
||||
|
||||
This enables efficient sequential evidence accumulation with saturating addition:
|
||||
```rust
|
||||
self.log_e_value = self.log_e_value.saturating_add(log_lr);
|
||||
```
|
||||
|
||||
**Anytime-valid property**: Because e-values are nonnegative supermartingales with E[E_0] = 1, the decision is valid at any stopping time:
|
||||
```
|
||||
P_H0(E_tau >= 1/alpha) <= alpha
|
||||
```
|
||||
|
||||
### TileReport Structure (64 bytes, cache-line aligned)
|
||||
|
||||
```rust
|
||||
#[repr(C, align(64))]
|
||||
pub struct TileReport {
|
||||
// Header (8 bytes)
|
||||
pub tile_id: u8, // Tile ID (0-255)
|
||||
pub status: TileStatus, // Processing status
|
||||
pub generation: u16, // Epoch number
|
||||
pub tick: u32, // Current tick
|
||||
|
||||
// Graph state (8 bytes)
|
||||
pub num_vertices: u16,
|
||||
pub num_edges: u16,
|
||||
pub num_components: u16,
|
||||
pub graph_flags: u16,
|
||||
|
||||
// Evidence state (8 bytes)
|
||||
pub log_e_value: LogEValue, // 4 bytes
|
||||
pub obs_count: u16,
|
||||
pub rejected_count: u16,
|
||||
|
||||
// Witness fragment (16 bytes)
|
||||
pub witness: WitnessFragment,
|
||||
|
||||
// Performance metrics (8 bytes)
|
||||
pub delta_time_us: u16,
|
||||
pub tick_time_us: u16,
|
||||
pub deltas_processed: u16,
|
||||
pub memory_kb: u16,
|
||||
|
||||
// Cross-tile coordination (8 bytes)
|
||||
pub ghost_vertices: u16,
|
||||
pub ghost_edges: u16,
|
||||
pub boundary_vertices: u16,
|
||||
pub pending_sync: u16,
|
||||
|
||||
// Reserved (8 bytes)
|
||||
pub _reserved: [u8; 8],
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Layout (~41KB per tile)
|
||||
|
||||
| Component | Size | Notes |
|
||||
|-----------|------|-------|
|
||||
| Graph shard | 42 KB | 256 vertices, 1024 edges, 32-degree adjacency |
|
||||
| Evidence accumulator | 2 KB | 16 hypotheses, 64-observation window |
|
||||
| Delta buffer | 1 KB | 64 deltas @ 16 bytes each |
|
||||
| TileState overhead | 1 KB | Metadata, status, counters |
|
||||
| **Total per worker** | **~46 KB** | Fits in 64KB WASM page |
|
||||
| **Total 255 workers** | **~11.5 MB** | |
|
||||
| TileZero state | ~1 MB | Supergraph + receipt log head |
|
||||
| **Total fabric** | **~13 MB** | |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><h2>Tutorials and Examples</h2></summary>
|
||||
|
||||
### Example 1: Network Security Gate
|
||||
|
||||
Protect network device configuration changes with coherence gating:
|
||||
|
||||
```rust
|
||||
use cognitum_gate_kernel::{TileState, Delta, Observation};
|
||||
use cognitum_gate_tilezero::{TileZero, GateThresholds, ActionContext, ActionTarget, ActionMetadata};
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
// Create gate with security-focused thresholds
|
||||
let thresholds = GateThresholds {
|
||||
tau_deny: 0.01, // Very conservative: 1% false alarm rate
|
||||
tau_permit: 100.0, // Require strong evidence for autonomous action
|
||||
min_cut: 10.0, // High structural integrity required
|
||||
max_shift: 0.3, // Low tolerance for distribution shift
|
||||
permit_ttl_ns: 60_000_000_000, // 60 second token lifetime
|
||||
};
|
||||
|
||||
let tilezero = TileZero::new(thresholds);
|
||||
let mut tile = TileState::new(1);
|
||||
|
||||
// Model network topology as graph
|
||||
// Devices are vertices, connections are edges
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100)); // core-router -> firewall
|
||||
tile.ingest_delta(&Delta::edge_add(1, 2, 100)); // firewall -> switch
|
||||
tile.ingest_delta(&Delta::edge_add(2, 3, 100)); // switch -> server-rack
|
||||
tile.ingest_delta(&Delta::edge_add(2, 4, 100)); // switch -> workstations
|
||||
|
||||
// Add connectivity hypothesis for firewall
|
||||
tile.evidence.add_connectivity_hypothesis(1);
|
||||
|
||||
// Add observations about healthy connectivity
|
||||
for tick in 1..=10 {
|
||||
let obs = Observation::connectivity(1, true); // firewall is connected
|
||||
tile.ingest_delta(&Delta::observation(obs));
|
||||
tile.tick(tick);
|
||||
}
|
||||
|
||||
// Now request permission to push a config change
|
||||
let ctx = ActionContext {
|
||||
action_id: "cfg-push-001".into(),
|
||||
action_type: "config_change".into(),
|
||||
target: ActionTarget {
|
||||
device: Some("firewall".into()),
|
||||
path: Some("/rules/allow-list".into()),
|
||||
extra: Default::default(),
|
||||
},
|
||||
context: ActionMetadata {
|
||||
agent_id: "netops-agent".into(),
|
||||
session_id: Some("session-123".into()),
|
||||
prior_actions: vec![],
|
||||
urgency: "normal".into(),
|
||||
},
|
||||
};
|
||||
|
||||
// Get decision
|
||||
let token = tilezero.decide(&ctx).await;
|
||||
|
||||
match token.decision {
|
||||
GateDecision::Permit => {
|
||||
println!("Action permitted. Token valid for {} ns", token.ttl_ns);
|
||||
println!("Witness hash: {:?}", &token.witness_hash[..8]);
|
||||
}
|
||||
GateDecision::Defer => {
|
||||
println!("Uncertain. Escalating to human operator.");
|
||||
// Wait for human approval...
|
||||
}
|
||||
GateDecision::Deny => {
|
||||
println!("Blocked: network topology unstable");
|
||||
}
|
||||
}
|
||||
|
||||
// Verify receipt exists
|
||||
if let Some(receipt) = tilezero.get_receipt(token.sequence).await {
|
||||
println!("Receipt sequence: {}", receipt.sequence);
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: Config Change Approval
|
||||
|
||||
Gate infrastructure changes based on dependency graph stability:
|
||||
|
||||
```rust
|
||||
use cognitum_gate_kernel::{TileState, Delta, Observation};
|
||||
|
||||
fn main() {
|
||||
let mut tile = TileState::new(1);
|
||||
|
||||
// Build dependency graph for microservices
|
||||
// Service 0: API Gateway
|
||||
// Service 1: Auth Service
|
||||
// Service 2: User Service
|
||||
// Service 3: Database
|
||||
|
||||
// Dependencies: API -> Auth, API -> User, Auth -> DB, User -> DB
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 200)); // API -> Auth (critical)
|
||||
tile.ingest_delta(&Delta::edge_add(0, 2, 150)); // API -> User
|
||||
tile.ingest_delta(&Delta::edge_add(1, 3, 200)); // Auth -> DB (critical)
|
||||
tile.ingest_delta(&Delta::edge_add(2, 3, 150)); // User -> DB
|
||||
|
||||
// Process initial state
|
||||
let report = tile.tick(1);
|
||||
println!("Connected: {}", report.is_connected());
|
||||
println!("Components: {}", report.num_components);
|
||||
assert!(report.is_connected());
|
||||
assert_eq!(report.num_components, 1);
|
||||
|
||||
// Add hypothesis to track auth connectivity
|
||||
tile.evidence.add_connectivity_hypothesis(1);
|
||||
|
||||
// Ingest recent health checks (all healthy)
|
||||
for tick in 2..=12 {
|
||||
let obs = Observation::connectivity(1, true);
|
||||
tile.ingest_delta(&Delta::observation(obs));
|
||||
tile.tick(tick);
|
||||
}
|
||||
|
||||
// Check if we have enough evidence to permit changes
|
||||
let e_value = tile.evidence.global_e_value();
|
||||
println!("Accumulated evidence: {:.2}", e_value);
|
||||
|
||||
if e_value > 20.0 {
|
||||
println!("Strong evidence of stability. Config change may proceed.");
|
||||
} else if e_value > 1.0 {
|
||||
println!("Some evidence of stability. Human review recommended.");
|
||||
} else {
|
||||
println!("Insufficient evidence. Config change blocked.");
|
||||
}
|
||||
|
||||
// Simulate removing a critical edge (partition risk)
|
||||
tile.ingest_delta(&Delta::edge_remove(1, 3)); // Remove Auth -> DB
|
||||
let report = tile.tick(13);
|
||||
|
||||
if !report.is_connected() {
|
||||
println!("ALERT: Graph partition detected! {} components",
|
||||
report.num_components);
|
||||
// Gate would DENY any action touching these services
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 3: Multi-Agent Coordination
|
||||
|
||||
Coordinate multiple agents through the coherence gate:
|
||||
|
||||
```rust
|
||||
use cognitum_gate_kernel::{TileState, Delta, Observation};
|
||||
use std::collections::HashMap;
|
||||
|
||||
struct AgentCoordinator {
|
||||
tiles: HashMap<u8, TileState>,
|
||||
}
|
||||
|
||||
impl AgentCoordinator {
|
||||
fn new(num_tiles: u8) -> Self {
|
||||
let mut tiles = HashMap::new();
|
||||
for id in 1..=num_tiles {
|
||||
tiles.insert(id, TileState::new(id));
|
||||
}
|
||||
Self { tiles }
|
||||
}
|
||||
|
||||
/// Model agent interactions as graph edges
|
||||
fn register_interaction(&mut self, agent_a: u16, agent_b: u16, tile_id: u8) {
|
||||
if let Some(tile) = self.tiles.get_mut(&tile_id) {
|
||||
tile.ingest_delta(&Delta::edge_add(agent_a, agent_b, 100));
|
||||
}
|
||||
}
|
||||
|
||||
/// Process a tick across all tiles
|
||||
fn tick_all(&mut self, tick: u32) -> Vec<(u8, bool)> {
|
||||
let mut results = vec![];
|
||||
for (&id, tile) in &mut self.tiles {
|
||||
let report = tile.tick(tick);
|
||||
results.push((id, report.is_connected()));
|
||||
}
|
||||
results
|
||||
}
|
||||
|
||||
/// Evaluate action safety based on tile coherence
|
||||
fn evaluate_action(&self, tile_id: u8) -> ActionResult {
|
||||
if let Some(tile) = self.tiles.get(&tile_id) {
|
||||
let witness = tile.get_witness_fragment();
|
||||
let e_value = tile.evidence.global_e_value();
|
||||
|
||||
if !tile.last_report.is_connected() {
|
||||
ActionResult::Deny("Tile graph disconnected".into())
|
||||
} else if witness.local_min_cut < 50 {
|
||||
ActionResult::Defer("Low min-cut detected".into())
|
||||
} else if e_value < 1.0 {
|
||||
ActionResult::Defer("Insufficient evidence".into())
|
||||
} else if e_value > 20.0 {
|
||||
ActionResult::Permit
|
||||
} else {
|
||||
ActionResult::Defer("Moderate evidence".into())
|
||||
}
|
||||
} else {
|
||||
ActionResult::Deny("Unknown tile".into())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
enum ActionResult {
|
||||
Permit,
|
||||
Defer(String),
|
||||
Deny(String),
|
||||
}
|
||||
|
||||
fn main() {
|
||||
let mut coordinator = AgentCoordinator::new(4);
|
||||
|
||||
// Register agent interactions across tiles
|
||||
coordinator.register_interaction(0, 1, 1); // Agents 0,1 interact on tile 1
|
||||
coordinator.register_interaction(1, 2, 1);
|
||||
coordinator.register_interaction(2, 3, 2); // Agents 2,3 interact on tile 2
|
||||
coordinator.register_interaction(3, 4, 2);
|
||||
|
||||
// Run simulation ticks
|
||||
for tick in 1..=20 {
|
||||
let results = coordinator.tick_all(tick);
|
||||
for (tile_id, connected) in results {
|
||||
if !connected {
|
||||
println!("Tick {}: Tile {} lost connectivity!", tick, tile_id);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Evaluate pending action on tile 1
|
||||
match coordinator.evaluate_action(1) {
|
||||
ActionResult::Permit => println!("Action on tile 1: PERMITTED"),
|
||||
ActionResult::Defer(reason) => println!("Action on tile 1: DEFERRED - {}", reason),
|
||||
ActionResult::Deny(reason) => println!("Action on tile 1: DENIED - {}", reason),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><h2>Super Advanced Usage</h2></summary>
|
||||
|
||||
### Custom Update Rules for E-Process
|
||||
|
||||
Extend the evidence accumulator with custom likelihood ratio functions:
|
||||
|
||||
```rust
|
||||
use cognitum_gate_kernel::evidence::{LogEValue, f32_to_log_e, LOG_E_STRONG};
|
||||
|
||||
/// Custom e-value update for domain-specific hypothesis testing
|
||||
pub trait CustomEUpdateRule {
|
||||
/// Compute log likelihood ratio for domain-specific observation
|
||||
fn compute_log_lr(&self, observation: &DomainObservation) -> LogEValue;
|
||||
|
||||
/// Apply custom stopping rule
|
||||
fn should_stop(&self, cumulative_log_e: LogEValue, obs_count: u32) -> StopDecision;
|
||||
}
|
||||
|
||||
/// Financial anomaly detection e-process
|
||||
struct FinancialAnomalyRule {
|
||||
baseline_volatility: f32,
|
||||
alert_multiplier: f32,
|
||||
}
|
||||
|
||||
impl CustomEUpdateRule for FinancialAnomalyRule {
|
||||
fn compute_log_lr(&self, obs: &DomainObservation) -> LogEValue {
|
||||
let volatility = obs.value as f32 / 1000.0;
|
||||
let ratio = volatility / self.baseline_volatility;
|
||||
|
||||
// Evidence for anomaly increases when volatility exceeds baseline
|
||||
if ratio > self.alert_multiplier {
|
||||
f32_to_log_e(ratio)
|
||||
} else {
|
||||
f32_to_log_e(1.0 / ratio) // Evidence against anomaly
|
||||
}
|
||||
}
|
||||
|
||||
fn should_stop(&self, cumulative_log_e: LogEValue, obs_count: u32) -> StopDecision {
|
||||
if obs_count < 10 {
|
||||
return StopDecision::Continue; // Minimum sample size
|
||||
}
|
||||
if cumulative_log_e > LOG_E_STRONG {
|
||||
StopDecision::Reject // Strong evidence of anomaly
|
||||
} else if cumulative_log_e < -LOG_E_STRONG {
|
||||
StopDecision::Accept // Strong evidence of normality
|
||||
} else {
|
||||
StopDecision::Continue
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
enum StopDecision { Continue, Accept, Reject }
|
||||
struct DomainObservation { value: u32 }
|
||||
```
|
||||
|
||||
### SIMD Optimization Hooks
|
||||
|
||||
For high-throughput scenarios, inject SIMD-optimized paths:
|
||||
|
||||
```rust
|
||||
#[cfg(target_arch = "x86_64")]
|
||||
mod simd_opt {
|
||||
use std::arch::x86_64::*;
|
||||
|
||||
/// Batch e-value computation with AVX2
|
||||
#[target_feature(enable = "avx2")]
|
||||
pub unsafe fn compute_log_lr_batch_avx2(
|
||||
h1: &[f64; 4],
|
||||
h0: &[f64; 4],
|
||||
) -> [f64; 4] {
|
||||
let v_h1 = _mm256_loadu_pd(h1.as_ptr());
|
||||
let v_h0 = _mm256_loadu_pd(h0.as_ptr());
|
||||
let ratio = _mm256_div_pd(v_h1, v_h0);
|
||||
|
||||
let mut out = [0f64; 4];
|
||||
_mm256_storeu_pd(out.as_mut_ptr(), ratio);
|
||||
out
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
mod simd_opt {
|
||||
use core::arch::wasm32::*;
|
||||
|
||||
/// WASM SIMD128 optimized log likelihood ratio
|
||||
#[target_feature(enable = "simd128")]
|
||||
pub unsafe fn compute_log_lr_simd128(h1: v128, h0: v128) -> v128 {
|
||||
f32x4_div(h1, h0)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Distributed Coordination with ruvector-raft
|
||||
|
||||
Integrate with RuVector's Raft consensus for distributed gate deployment:
|
||||
|
||||
```rust
|
||||
use cognitum_gate_tilezero::{TileZero, GateThresholds, GateDecision};
|
||||
|
||||
/// Distributed coherence gate with Raft consensus
|
||||
pub struct DistributedCoherenceGate {
|
||||
local_gate: TileZero,
|
||||
peers: Vec<String>,
|
||||
node_id: u64,
|
||||
}
|
||||
|
||||
impl DistributedCoherenceGate {
|
||||
pub async fn new(node_id: u64, peers: Vec<String>) -> Self {
|
||||
let thresholds = GateThresholds::default();
|
||||
Self {
|
||||
local_gate: TileZero::new(thresholds),
|
||||
peers,
|
||||
node_id,
|
||||
}
|
||||
}
|
||||
|
||||
/// Make a distributed decision (requires consensus)
|
||||
pub async fn decide_with_consensus(
|
||||
&self,
|
||||
ctx: &ActionContext,
|
||||
) -> Result<PermitToken, DistributedError> {
|
||||
// Step 1: Local evaluation
|
||||
let local_token = self.local_gate.decide(ctx).await;
|
||||
|
||||
// Step 2: Propose to Raft cluster
|
||||
let proposal = GateProposal {
|
||||
sequence: local_token.sequence,
|
||||
action_id: ctx.action_id.clone(),
|
||||
decision: local_token.decision,
|
||||
witness_hash: local_token.witness_hash,
|
||||
};
|
||||
|
||||
// Step 3: Wait for consensus (majority agreement)
|
||||
self.propose_and_wait(proposal).await?;
|
||||
|
||||
// Step 4: Return token only after consensus
|
||||
Ok(local_token)
|
||||
}
|
||||
|
||||
async fn propose_and_wait(&self, proposal: GateProposal) -> Result<(), DistributedError> {
|
||||
// In production, this would use ruvector-raft
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
struct GateProposal {
|
||||
sequence: u64,
|
||||
action_id: String,
|
||||
decision: GateDecision,
|
||||
witness_hash: [u8; 32],
|
||||
}
|
||||
struct DistributedError;
|
||||
struct ActionContext { action_id: String }
|
||||
struct PermitToken { sequence: u64, decision: GateDecision, witness_hash: [u8; 32] }
|
||||
```
|
||||
|
||||
### Hardware Integration (Cognitum Chip)
|
||||
|
||||
For deployment on dedicated Cognitum ASIC/FPGA:
|
||||
|
||||
```rust
|
||||
//! Hardware abstraction layer for Cognitum coherence gate chip
|
||||
|
||||
use cognitum_gate_kernel::{Delta, TileState};
|
||||
use cognitum_gate_kernel::report::TileReport;
|
||||
|
||||
/// Hardware register interface
|
||||
#[repr(C)]
|
||||
pub struct CognitumRegisters {
|
||||
pub control: u32,
|
||||
pub status: u32,
|
||||
pub delta_fifo_addr: u64,
|
||||
pub report_fifo_addr: u64,
|
||||
pub tile_config_base: u64,
|
||||
pub clock_mhz: u32,
|
||||
}
|
||||
|
||||
/// Hardware-accelerated tile driver
|
||||
pub struct HardwareTile {
|
||||
registers: *mut CognitumRegisters,
|
||||
tile_id: u8,
|
||||
}
|
||||
|
||||
impl HardwareTile {
|
||||
/// Initialize hardware tile
|
||||
pub unsafe fn new(base_addr: *mut u8, tile_id: u8) -> Self {
|
||||
Self {
|
||||
registers: base_addr as *mut CognitumRegisters,
|
||||
tile_id,
|
||||
}
|
||||
}
|
||||
|
||||
/// Submit delta to hardware FIFO
|
||||
pub fn submit_delta(&mut self, delta: &Delta) {
|
||||
unsafe {
|
||||
let fifo_addr = (*self.registers).delta_fifo_addr as *mut Delta;
|
||||
core::ptr::write_volatile(fifo_addr, *delta);
|
||||
}
|
||||
}
|
||||
|
||||
/// Trigger hardware tick
|
||||
pub fn trigger_tick(&mut self) {
|
||||
unsafe {
|
||||
(*self.registers).control |= 0x1;
|
||||
}
|
||||
}
|
||||
|
||||
/// Read report from hardware
|
||||
pub fn read_report(&self) -> TileReport {
|
||||
unsafe {
|
||||
let fifo_addr = (*self.registers).report_fifo_addr as *const TileReport;
|
||||
core::ptr::read_volatile(fifo_addr)
|
||||
}
|
||||
}
|
||||
|
||||
/// Check if tile is ready
|
||||
pub fn is_ready(&self) -> bool {
|
||||
unsafe { ((*self.registers).status & 0x1) != 0 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Extending the Witness Receipt Format
|
||||
|
||||
Add custom fields to witness receipts for domain-specific auditing:
|
||||
|
||||
```rust
|
||||
use cognitum_gate_tilezero::{WitnessReceipt, WitnessSummary, GateDecision};
|
||||
use serde::{Serialize, Deserialize};
|
||||
|
||||
/// Extended witness receipt with compliance fields
|
||||
#[derive(Clone, Serialize, Deserialize)]
|
||||
pub struct ComplianceWitnessReceipt {
|
||||
pub base: WitnessReceipt,
|
||||
pub jurisdiction: String,
|
||||
pub framework: String, // e.g., "SOC2", "GDPR", "HIPAA"
|
||||
pub controls_checked: Vec<String>,
|
||||
pub risk_score: u8, // 0-100
|
||||
pub human_reviewer: Option<String>,
|
||||
pub extended_signature: [u8; 64],
|
||||
}
|
||||
|
||||
impl ComplianceWitnessReceipt {
|
||||
pub fn from_base(base: WitnessReceipt, jurisdiction: &str, framework: &str) -> Self {
|
||||
Self {
|
||||
base,
|
||||
jurisdiction: jurisdiction.to_string(),
|
||||
framework: framework.to_string(),
|
||||
controls_checked: vec![],
|
||||
risk_score: 0,
|
||||
human_reviewer: None,
|
||||
extended_signature: [0u8; 64],
|
||||
}
|
||||
}
|
||||
|
||||
pub fn add_control(&mut self, control_id: &str) {
|
||||
self.controls_checked.push(control_id.to_string());
|
||||
}
|
||||
|
||||
/// Calculate risk score based on receipt data
|
||||
pub fn calculate_risk_score(&mut self) {
|
||||
let mut score: u32 = 0;
|
||||
|
||||
score += match self.base.token.decision {
|
||||
GateDecision::Permit => 0,
|
||||
GateDecision::Defer => 30,
|
||||
GateDecision::Deny => 70,
|
||||
};
|
||||
|
||||
if self.base.witness_summary.min_cut < 5.0 {
|
||||
score += 20;
|
||||
}
|
||||
|
||||
self.risk_score = score.min(100) as u8;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## API Reference
|
||||
|
||||
Full API documentation is available on [docs.rs/cognitum-gate-kernel](https://docs.rs/cognitum-gate-kernel).
|
||||
|
||||
### Key Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `TileState` | Main worker tile state containing graph, evidence, and delta buffer |
|
||||
| `Delta` | Tagged union for graph updates (edge add/remove, weight update, observation) |
|
||||
| `TileReport` | 64-byte cache-aligned report produced after each tick |
|
||||
| `WitnessFragment` | 16-byte fragment for global min-cut aggregation |
|
||||
| `CompactGraph` | ~42KB fixed-size graph shard with union-find connectivity |
|
||||
| `EvidenceAccumulator` | Hypothesis tracking with sliding window and e-value computation |
|
||||
|
||||
### WASM Exports
|
||||
|
||||
When compiled for WASM, the kernel exports:
|
||||
|
||||
```c
|
||||
void init_tile(uint8_t tile_id);
|
||||
int32_t ingest_delta(const uint8_t* ptr);
|
||||
int32_t tick(uint32_t tick_number, uint8_t* report_ptr);
|
||||
int32_t get_witness_fragment(uint8_t* fragment_ptr);
|
||||
uint8_t get_status();
|
||||
void reset_tile();
|
||||
uint32_t get_memory_usage();
|
||||
```
|
||||
|
||||
## Claude-Flow Integration
|
||||
|
||||
### Using as SDK
|
||||
|
||||
The coherence gate integrates with Claude-Flow for multi-agent coordination:
|
||||
|
||||
```javascript
|
||||
import { ClaudeFlow } from '@claude-flow/core';
|
||||
import { CoherenceGate } from '@ruvector/cognitum-gate';
|
||||
|
||||
const flow = new ClaudeFlow({
|
||||
topology: 'mesh',
|
||||
maxAgents: 8,
|
||||
});
|
||||
|
||||
// Initialize coherence gate
|
||||
const gate = new CoherenceGate({
|
||||
thresholds: {
|
||||
tauDeny: 0.01,
|
||||
tauPermit: 100.0,
|
||||
minCut: 5.0,
|
||||
maxShift: 0.5,
|
||||
},
|
||||
});
|
||||
|
||||
// Register gate with flow
|
||||
flow.use(gate.middleware());
|
||||
|
||||
// Gate evaluates agent actions before execution
|
||||
flow.onBeforeAction(async (action, context) => {
|
||||
const permit = await gate.evaluate(action, context);
|
||||
|
||||
if (permit.decision === 'DENY') {
|
||||
throw new ActionDeniedError(permit.reason);
|
||||
}
|
||||
|
||||
if (permit.decision === 'DEFER') {
|
||||
return await flow.escalate(action, permit);
|
||||
}
|
||||
|
||||
// Attach token for audit trail
|
||||
context.permitToken = permit.token;
|
||||
});
|
||||
```
|
||||
|
||||
### MCP Plugin Configuration
|
||||
|
||||
Configure the gate as an MCP server:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"coherence-gate": {
|
||||
"command": "cargo",
|
||||
"args": ["run", "-p", "mcp-gate", "--", "serve"],
|
||||
"env": {
|
||||
"GATE_TAU_DENY": "0.01",
|
||||
"GATE_TAU_PERMIT": "100.0",
|
||||
"GATE_MIN_CUT": "5.0",
|
||||
"GATE_MAX_SHIFT": "0.5",
|
||||
"GATE_SIGNING_KEY_PATH": "/etc/gate/keys/signing.key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example Swarm Coordination
|
||||
|
||||
Coordinate a research swarm with coherence gating:
|
||||
|
||||
```javascript
|
||||
import { ClaudeFlow, SwarmConfig } from '@claude-flow/core';
|
||||
|
||||
const config = {
|
||||
topology: 'hierarchical',
|
||||
agents: [
|
||||
{ role: 'researcher', count: 3 },
|
||||
{ role: 'coder', count: 2 },
|
||||
{ role: 'tester', count: 1 },
|
||||
],
|
||||
gate: {
|
||||
enabled: true,
|
||||
mode: 'strict', // All actions require permit
|
||||
escalation: {
|
||||
channel: 'human-operator',
|
||||
timeout: 300_000, // 5 minutes
|
||||
defaultOnTimeout: 'deny',
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
const flow = new ClaudeFlow(config);
|
||||
|
||||
// Gate tracks agent interactions as graph edges
|
||||
flow.onAgentInteraction((from, to, type) => {
|
||||
gate.recordInteraction(from.id, to.id, type);
|
||||
});
|
||||
|
||||
// Research tasks are gated
|
||||
await flow.spawn('researcher', {
|
||||
task: 'Analyze security vulnerabilities in auth module',
|
||||
gate: {
|
||||
requirePermit: true,
|
||||
minEvidence: 20.0, // Require strong evidence before proceeding
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### MCP Tools
|
||||
|
||||
The gate exposes three MCP tools:
|
||||
|
||||
```typescript
|
||||
// Request permission for an action
|
||||
permit_action({
|
||||
action_id: "cfg-push-001",
|
||||
action_type: "config_change",
|
||||
context: { agent_id: "ops-agent", target: "router-1" }
|
||||
}) -> { decision: "permit", token: "...", valid_until_ns: ... }
|
||||
|
||||
// Get witness receipt for audit
|
||||
get_receipt({ sequence: 1847394 }) -> {
|
||||
decision: "deny",
|
||||
witness: { structural: {...}, predictive: {...}, evidential: {...} },
|
||||
receipt_hash: "..."
|
||||
}
|
||||
|
||||
// Replay decision for debugging
|
||||
replay_decision({ sequence: 1847394, verify_chain: true }) -> {
|
||||
original_decision: "deny",
|
||||
replayed_decision: "deny",
|
||||
match_confirmed: true
|
||||
}
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Licensed under either of:
|
||||
|
||||
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
|
||||
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
|
||||
|
||||
at your option.
|
||||
|
||||
### Contribution
|
||||
|
||||
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
|
||||
1874
crates/cognitum-gate-kernel/SECURITY.md
Normal file
1874
crates/cognitum-gate-kernel/SECURITY.md
Normal file
File diff suppressed because it is too large
Load Diff
647
crates/cognitum-gate-kernel/benches/benchmarks.rs
Normal file
647
crates/cognitum-gate-kernel/benches/benchmarks.rs
Normal file
@@ -0,0 +1,647 @@
|
||||
//! Comprehensive benchmarks for cognitum-gate-kernel
|
||||
//!
|
||||
//! Target latencies:
|
||||
//! - Single edge insert: < 100ns
|
||||
//! - Batch 1000 edges: < 100us
|
||||
//! - Single tick: < 500us
|
||||
//! - Tick under 10K edges: < 5ms
|
||||
//! - TileReport serialization: < 1us
|
||||
//! - E-value update: < 50ns
|
||||
//! - Mixture e-value (SIMD): < 500ns for 16 hypotheses
|
||||
|
||||
use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
|
||||
|
||||
use cognitum_gate_kernel::{
|
||||
delta::{Delta, Observation},
|
||||
evidence::{
|
||||
f32_to_log_e, EvidenceAccumulator, HypothesisState, LogEValue, LOG_LR_CONNECTIVITY_POS,
|
||||
},
|
||||
report::TileReport,
|
||||
shard::{CompactGraph, MAX_SHARD_VERTICES},
|
||||
TileState, MAX_DELTA_BUFFER,
|
||||
};
|
||||
|
||||
// ============================================================================
|
||||
// Edge Operations Benchmarks
|
||||
// ============================================================================
|
||||
|
||||
/// Benchmark single edge insertion
|
||||
fn bench_edge_insert(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("edge_operations");
|
||||
group.throughput(Throughput::Elements(1));
|
||||
|
||||
// Benchmark on empty graph
|
||||
group.bench_function("insert_single_empty", |b| {
|
||||
b.iter_batched(
|
||||
CompactGraph::new,
|
||||
|mut graph| {
|
||||
black_box(graph.add_edge(0, 1, 100));
|
||||
graph
|
||||
},
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
});
|
||||
|
||||
// Benchmark on partially filled graph
|
||||
group.bench_function("insert_single_partial", |b| {
|
||||
b.iter_batched(
|
||||
|| {
|
||||
let mut graph = CompactGraph::new();
|
||||
for i in 0..100u16 {
|
||||
graph.add_edge(i, i + 1, 100);
|
||||
}
|
||||
graph
|
||||
},
|
||||
|mut graph| {
|
||||
black_box(graph.add_edge(200, 201, 100));
|
||||
graph
|
||||
},
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
});
|
||||
|
||||
// Benchmark edge removal
|
||||
group.bench_function("remove_single", |b| {
|
||||
b.iter_batched(
|
||||
|| {
|
||||
let mut graph = CompactGraph::new();
|
||||
graph.add_edge(0, 1, 100);
|
||||
graph.add_edge(1, 2, 100);
|
||||
graph.add_edge(2, 3, 100);
|
||||
graph
|
||||
},
|
||||
|mut graph| {
|
||||
black_box(graph.remove_edge(1, 2));
|
||||
graph
|
||||
},
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
});
|
||||
|
||||
// Benchmark edge lookup
|
||||
group.bench_function("find_edge", |b| {
|
||||
let mut graph = CompactGraph::new();
|
||||
for i in 0..200u16 {
|
||||
graph.add_edge(i, i + 1, 100);
|
||||
}
|
||||
b.iter(|| black_box(graph.find_edge(100, 101)))
|
||||
});
|
||||
|
||||
// Benchmark weight update
|
||||
group.bench_function("update_weight", |b| {
|
||||
let mut graph = CompactGraph::new();
|
||||
for i in 0..100u16 {
|
||||
graph.add_edge(i, i + 1, 100);
|
||||
}
|
||||
b.iter(|| {
|
||||
black_box(graph.update_weight(50, 51, 200));
|
||||
})
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
/// Benchmark batch edge insertion (1000 edges)
|
||||
fn bench_edge_batch(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("edge_batch");
|
||||
|
||||
for batch_size in [100, 500, 1000] {
|
||||
group.throughput(Throughput::Elements(batch_size as u64));
|
||||
|
||||
group.bench_with_input(
|
||||
BenchmarkId::new("insert_batch", batch_size),
|
||||
&batch_size,
|
||||
|b, &size| {
|
||||
b.iter_batched(
|
||||
CompactGraph::new,
|
||||
|mut graph| {
|
||||
for i in 0..size as u16 {
|
||||
// Use modular arithmetic to create varied edges within bounds
|
||||
let src = i % 200;
|
||||
let dst = (i % 200) + 1;
|
||||
graph.add_edge(src, dst, 100);
|
||||
}
|
||||
black_box(graph)
|
||||
},
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
// Benchmark batch with recompute_components
|
||||
group.bench_function("batch_1000_with_components", |b| {
|
||||
b.iter_batched(
|
||||
CompactGraph::new,
|
||||
|mut graph| {
|
||||
for i in 0..500u16 {
|
||||
let src = i % 200;
|
||||
let dst = (i % 200) + 1;
|
||||
graph.add_edge(src, dst, 100);
|
||||
}
|
||||
graph.recompute_components();
|
||||
black_box(graph)
|
||||
},
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Tick Cycle Benchmarks
|
||||
// ============================================================================
|
||||
|
||||
/// Benchmark single tick cycle
|
||||
fn bench_tick(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("tick_cycle");
|
||||
group.throughput(Throughput::Elements(1));
|
||||
|
||||
// Empty tick (no deltas)
|
||||
group.bench_function("tick_empty", |b| {
|
||||
let mut tile = TileState::new(0);
|
||||
b.iter(|| black_box(tile.tick(black_box(1))))
|
||||
});
|
||||
|
||||
// Tick with small graph
|
||||
group.bench_function("tick_small_graph", |b| {
|
||||
let mut tile = TileState::new(0);
|
||||
// Add some edges
|
||||
for i in 0..10u16 {
|
||||
tile.ingest_delta(&Delta::edge_add(i, i + 1, 100));
|
||||
}
|
||||
tile.tick(0); // Initial tick to process deltas
|
||||
|
||||
b.iter(|| black_box(tile.tick(black_box(1))))
|
||||
});
|
||||
|
||||
// Tick with pending deltas
|
||||
group.bench_function("tick_with_deltas", |b| {
|
||||
b.iter_batched(
|
||||
|| {
|
||||
let mut tile = TileState::new(0);
|
||||
for i in 0..10u16 {
|
||||
tile.ingest_delta(&Delta::edge_add(i, i + 1, 100));
|
||||
}
|
||||
tile
|
||||
},
|
||||
|mut tile| black_box(tile.tick(1)),
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
});
|
||||
|
||||
// Tick with observations
|
||||
group.bench_function("tick_with_observations", |b| {
|
||||
b.iter_batched(
|
||||
|| {
|
||||
let mut tile = TileState::new(0);
|
||||
tile.evidence.add_connectivity_hypothesis(5);
|
||||
for _ in 0..5 {
|
||||
let obs = Observation::connectivity(5, true);
|
||||
tile.ingest_delta(&Delta::observation(obs));
|
||||
}
|
||||
tile
|
||||
},
|
||||
|mut tile| black_box(tile.tick(1)),
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
/// Benchmark tick under heavy load (10K edges simulated via max graph)
|
||||
fn bench_tick_under_load(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("tick_under_load");
|
||||
group.sample_size(50); // Reduce sample size for expensive benchmarks
|
||||
|
||||
// Create a densely connected graph (approaching limits)
|
||||
for edge_count in [500, 800, 1000] {
|
||||
group.throughput(Throughput::Elements(edge_count as u64));
|
||||
|
||||
group.bench_with_input(
|
||||
BenchmarkId::new("edges", edge_count),
|
||||
&edge_count,
|
||||
|b, &count| {
|
||||
b.iter_batched(
|
||||
|| {
|
||||
let mut tile = TileState::new(0);
|
||||
// Create a connected graph
|
||||
for i in 0..count.min(1000) as u16 {
|
||||
let src = i % 250;
|
||||
let dst = (i + 1) % 250;
|
||||
if src != dst {
|
||||
tile.ingest_delta(&Delta::edge_add(src, dst, 100));
|
||||
}
|
||||
}
|
||||
tile.tick(0); // Process initial deltas
|
||||
|
||||
// Add some pending work
|
||||
tile.ingest_delta(&Delta::edge_add(0, 100, 150));
|
||||
tile.ingest_delta(&Delta::observation(Observation::connectivity(0, true)));
|
||||
tile
|
||||
},
|
||||
|mut tile| black_box(tile.tick(1)),
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
// Benchmark connected components recomputation at scale
|
||||
group.bench_function("recompute_components_800", |b| {
|
||||
b.iter_batched(
|
||||
|| {
|
||||
let mut graph = CompactGraph::new();
|
||||
// Create 4 disconnected clusters of 50 nodes each
|
||||
for cluster in 0..4u16 {
|
||||
let base = cluster * 60;
|
||||
for i in 0..50u16 {
|
||||
graph.add_edge(base + i, base + (i + 1) % 50, 100);
|
||||
}
|
||||
}
|
||||
graph
|
||||
},
|
||||
|mut graph| {
|
||||
black_box(graph.recompute_components());
|
||||
graph
|
||||
},
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Report Serialization Benchmarks
|
||||
// ============================================================================
|
||||
|
||||
/// Benchmark TileReport serialization
|
||||
fn bench_report_serialize(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("report_serialization");
|
||||
group.throughput(Throughput::Elements(1));
|
||||
|
||||
// Create a populated tile report
|
||||
let create_report = || {
|
||||
let mut tile = TileState::new(42);
|
||||
for i in 0..20u16 {
|
||||
tile.ingest_delta(&Delta::edge_add(i, i + 1, 100));
|
||||
}
|
||||
tile.tick(1)
|
||||
};
|
||||
|
||||
let report = create_report();
|
||||
|
||||
// Raw memory copy (baseline)
|
||||
group.bench_function("raw_copy_64_bytes", |b| {
|
||||
let report = create_report();
|
||||
b.iter(|| {
|
||||
let mut buffer = [0u8; 64];
|
||||
unsafe {
|
||||
let src = &report as *const TileReport as *const u8;
|
||||
core::ptr::copy_nonoverlapping(src, buffer.as_mut_ptr(), 64);
|
||||
}
|
||||
black_box(buffer)
|
||||
})
|
||||
});
|
||||
|
||||
// Report creation from scratch
|
||||
group.bench_function("create_new", |b| {
|
||||
b.iter(|| black_box(TileReport::new(black_box(42))))
|
||||
});
|
||||
|
||||
// Report field access patterns
|
||||
group.bench_function("access_witness", |b| {
|
||||
b.iter(|| black_box(report.get_witness()))
|
||||
});
|
||||
|
||||
group.bench_function("access_connected", |b| {
|
||||
b.iter(|| black_box(report.is_connected()))
|
||||
});
|
||||
|
||||
group.bench_function("e_value_approx", |b| {
|
||||
b.iter(|| black_box(report.e_value_approx()))
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// E-Value Computation Benchmarks
|
||||
// ============================================================================
|
||||
|
||||
/// Benchmark e-value accumulator update
|
||||
fn bench_evalue_update(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("evalue_update");
|
||||
group.throughput(Throughput::Elements(1));
|
||||
|
||||
// Single hypothesis update
|
||||
group.bench_function("hypothesis_update_f32", |b| {
|
||||
let mut hyp = HypothesisState::new(0, HypothesisState::TYPE_CONNECTIVITY);
|
||||
b.iter(|| black_box(hyp.update(black_box(1.5))))
|
||||
});
|
||||
|
||||
// Update with pre-computed log LR (faster path)
|
||||
group.bench_function("hypothesis_update_log_lr", |b| {
|
||||
let mut hyp = HypothesisState::new(0, HypothesisState::TYPE_CONNECTIVITY);
|
||||
b.iter(|| black_box(hyp.update_with_log_lr(black_box(LOG_LR_CONNECTIVITY_POS))))
|
||||
});
|
||||
|
||||
// f32 to log conversion
|
||||
group.bench_function("f32_to_log_e", |b| {
|
||||
b.iter(|| black_box(f32_to_log_e(black_box(1.5))))
|
||||
});
|
||||
|
||||
// f32 to log with common value (fast path)
|
||||
group.bench_function("f32_to_log_e_fast_path", |b| {
|
||||
b.iter(|| black_box(f32_to_log_e(black_box(2.0))))
|
||||
});
|
||||
|
||||
// Full accumulator observation processing
|
||||
group.bench_function("accumulator_process_obs", |b| {
|
||||
let mut acc = EvidenceAccumulator::new();
|
||||
acc.add_connectivity_hypothesis(5);
|
||||
let obs = Observation::connectivity(5, true);
|
||||
|
||||
b.iter(|| {
|
||||
acc.process_observation(black_box(obs), black_box(1));
|
||||
})
|
||||
});
|
||||
|
||||
// Multiple hypotheses
|
||||
for hyp_count in [1, 4, 8, 16] {
|
||||
group.bench_with_input(
|
||||
BenchmarkId::new("process_obs_hypotheses", hyp_count),
|
||||
&hyp_count,
|
||||
|b, &count| {
|
||||
let mut acc = EvidenceAccumulator::new();
|
||||
for v in 0..count as u16 {
|
||||
acc.add_connectivity_hypothesis(v);
|
||||
}
|
||||
let obs = Observation::connectivity(0, true);
|
||||
|
||||
b.iter(|| {
|
||||
acc.process_observation(black_box(obs), black_box(1));
|
||||
})
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
/// Benchmark mixture e-value computation (potential SIMD opportunity)
|
||||
fn bench_mixture_evalue(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("mixture_evalue");
|
||||
|
||||
// Simulated mixture: aggregate multiple log e-values
|
||||
// This is where SIMD can provide significant speedup
|
||||
|
||||
// Scalar baseline
|
||||
group.bench_function("aggregate_16_scalar", |b| {
|
||||
let log_e_values: [LogEValue; 16] = [
|
||||
65536, 38550, -65536, 65536, 38550, 65536, 38550, -32768, 65536, 65536, 38550, -65536,
|
||||
65536, 38550, 65536, 38550,
|
||||
];
|
||||
|
||||
b.iter(|| {
|
||||
let sum: LogEValue = log_e_values.iter().copied().sum();
|
||||
black_box(sum)
|
||||
})
|
||||
});
|
||||
|
||||
// Parallel lanes pattern (SIMD-friendly)
|
||||
group.bench_function("aggregate_16_parallel_lanes", |b| {
|
||||
let log_e_values: [LogEValue; 16] = [
|
||||
65536, 38550, -65536, 65536, 38550, 65536, 38550, -32768, 65536, 65536, 38550, -65536,
|
||||
65536, 38550, 65536, 38550,
|
||||
];
|
||||
|
||||
b.iter(|| {
|
||||
// Process in 4 lanes (potential SIMD with 128-bit registers)
|
||||
let mut lanes = [0i32; 4];
|
||||
for (i, &val) in log_e_values.iter().enumerate() {
|
||||
lanes[i % 4] = lanes[i % 4].saturating_add(val);
|
||||
}
|
||||
let sum = lanes.iter().sum::<i32>();
|
||||
black_box(sum)
|
||||
})
|
||||
});
|
||||
|
||||
// Chunked processing (auto-vectorization friendly)
|
||||
group.bench_function("aggregate_16_chunked", |b| {
|
||||
let log_e_values: [LogEValue; 16] = [
|
||||
65536, 38550, -65536, 65536, 38550, 65536, 38550, -32768, 65536, 65536, 38550, -65536,
|
||||
65536, 38550, 65536, 38550,
|
||||
];
|
||||
|
||||
b.iter(|| {
|
||||
let mut total = 0i32;
|
||||
for chunk in log_e_values.chunks(4) {
|
||||
let chunk_sum: i32 = chunk.iter().copied().sum();
|
||||
total = total.saturating_add(chunk_sum);
|
||||
}
|
||||
black_box(total)
|
||||
})
|
||||
});
|
||||
|
||||
// Scale to 255 tiles (realistic workload)
|
||||
group.bench_function("aggregate_255_tiles", |b| {
|
||||
let log_e_values: Vec<LogEValue> = (0..255)
|
||||
.map(|i| (i as i32 % 3 - 1) * 65536) // Varying positive/negative evidence
|
||||
.collect();
|
||||
|
||||
b.iter(|| {
|
||||
let sum: i64 = log_e_values.iter().map(|&v| v as i64).sum();
|
||||
black_box(sum)
|
||||
})
|
||||
});
|
||||
|
||||
// Mixture with product (exp-log pattern)
|
||||
group.bench_function("mixture_product_16", |b| {
|
||||
let log_e_values: [LogEValue; 16] = [
|
||||
65536, 38550, -65536, 65536, 38550, 65536, 38550, -32768, 65536, 65536, 38550, -65536,
|
||||
65536, 38550, 65536, 38550,
|
||||
];
|
||||
|
||||
b.iter(|| {
|
||||
// For product, sum the logs, then exp
|
||||
let log_sum: i64 = log_e_values.iter().map(|&v| v as i64).sum();
|
||||
// Approximate exp2 for final result
|
||||
let approx_result = (log_sum as f64) / 65536.0;
|
||||
black_box(approx_result)
|
||||
})
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Additional Performance Benchmarks
|
||||
// ============================================================================
|
||||
|
||||
/// Benchmark delta ingestion
|
||||
fn bench_delta_ingestion(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("delta_ingestion");
|
||||
group.throughput(Throughput::Elements(1));
|
||||
|
||||
group.bench_function("ingest_single", |b| {
|
||||
let mut tile = TileState::new(0);
|
||||
let delta = Delta::edge_add(0, 1, 100);
|
||||
|
||||
b.iter(|| {
|
||||
tile.reset();
|
||||
black_box(tile.ingest_delta(&delta))
|
||||
})
|
||||
});
|
||||
|
||||
// Fill buffer benchmark
|
||||
group.bench_function("fill_buffer_64", |b| {
|
||||
b.iter_batched(
|
||||
|| TileState::new(0),
|
||||
|mut tile| {
|
||||
for i in 0..MAX_DELTA_BUFFER as u16 {
|
||||
tile.ingest_delta(&Delta::edge_add(i, i + 1, 100));
|
||||
}
|
||||
black_box(tile)
|
||||
},
|
||||
criterion::BatchSize::SmallInput,
|
||||
)
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
/// Benchmark neighbor iteration
|
||||
fn bench_neighbor_iteration(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("neighbor_iteration");
|
||||
|
||||
// Create a graph with varying degree vertices
|
||||
let mut graph = CompactGraph::new();
|
||||
// Create a hub vertex with many neighbors
|
||||
for i in 1..25u16 {
|
||||
graph.add_edge(0, i, 100);
|
||||
}
|
||||
// Create a chain
|
||||
for i in 30..50u16 {
|
||||
graph.add_edge(i, i + 1, 100);
|
||||
}
|
||||
|
||||
group.bench_function("neighbors_hub_24", |b| {
|
||||
b.iter(|| {
|
||||
let neighbors = graph.neighbors(0);
|
||||
black_box(neighbors.len())
|
||||
})
|
||||
});
|
||||
|
||||
group.bench_function("neighbors_chain_2", |b| {
|
||||
b.iter(|| {
|
||||
let neighbors = graph.neighbors(35);
|
||||
black_box(neighbors.len())
|
||||
})
|
||||
});
|
||||
|
||||
group.bench_function("iterate_all_neighbors", |b| {
|
||||
b.iter(|| {
|
||||
let mut total = 0usize;
|
||||
for v in 0..50u16 {
|
||||
total += graph.neighbors(v).len();
|
||||
}
|
||||
black_box(total)
|
||||
})
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Memory and Cache Benchmarks
|
||||
// ============================================================================
|
||||
|
||||
/// Benchmark memory access patterns
|
||||
fn bench_memory_patterns(c: &mut Criterion) {
|
||||
let mut group = c.benchmark_group("memory_patterns");
|
||||
|
||||
// Sequential vertex access
|
||||
group.bench_function("sequential_vertex_scan", |b| {
|
||||
let mut graph = CompactGraph::new();
|
||||
for i in 0..200u16 {
|
||||
graph.add_edge(i, i + 1, 100);
|
||||
}
|
||||
|
||||
b.iter(|| {
|
||||
let mut active = 0u16;
|
||||
for i in 0..256u16 {
|
||||
if graph.vertices[i as usize].is_active() {
|
||||
active += 1;
|
||||
}
|
||||
}
|
||||
black_box(active)
|
||||
})
|
||||
});
|
||||
|
||||
// Random access pattern
|
||||
group.bench_function("random_vertex_access", |b| {
|
||||
let mut graph = CompactGraph::new();
|
||||
for i in 0..200u16 {
|
||||
graph.add_edge(i, i + 1, 100);
|
||||
}
|
||||
|
||||
// Pseudo-random access pattern
|
||||
let indices: Vec<u16> = (0..100).map(|i| (i * 37) % 256).collect();
|
||||
|
||||
b.iter(|| {
|
||||
let mut sum = 0u8;
|
||||
for &i in &indices {
|
||||
sum = sum.wrapping_add(graph.vertices[i as usize].degree);
|
||||
}
|
||||
black_box(sum)
|
||||
})
|
||||
});
|
||||
|
||||
// Edge array scan
|
||||
group.bench_function("edge_array_scan", |b| {
|
||||
let mut graph = CompactGraph::new();
|
||||
for i in 0..500u16 {
|
||||
let src = i % 200;
|
||||
let dst = (i % 200) + 1;
|
||||
if src != dst {
|
||||
graph.add_edge(src, dst, 100);
|
||||
}
|
||||
}
|
||||
|
||||
b.iter(|| {
|
||||
let mut active = 0u16;
|
||||
for edge in &graph.edges {
|
||||
if edge.is_active() {
|
||||
active += 1;
|
||||
}
|
||||
}
|
||||
black_box(active)
|
||||
})
|
||||
});
|
||||
|
||||
group.finish();
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Criterion Groups
|
||||
// ============================================================================
|
||||
|
||||
criterion_group!(edge_benches, bench_edge_insert, bench_edge_batch,);
|
||||
|
||||
criterion_group!(tick_benches, bench_tick, bench_tick_under_load,);
|
||||
|
||||
criterion_group!(evidence_benches, bench_evalue_update, bench_mixture_evalue,);
|
||||
|
||||
criterion_group!(
|
||||
misc_benches,
|
||||
bench_report_serialize,
|
||||
bench_delta_ingestion,
|
||||
bench_neighbor_iteration,
|
||||
bench_memory_patterns,
|
||||
);
|
||||
|
||||
criterion_main!(edge_benches, tick_benches, evidence_benches, misc_benches);
|
||||
682
crates/cognitum-gate-kernel/docs/SECURITY_AUDIT.md
Normal file
682
crates/cognitum-gate-kernel/docs/SECURITY_AUDIT.md
Normal file
@@ -0,0 +1,682 @@
|
||||
# Security Audit Report: Cognitum Gate Implementation
|
||||
|
||||
**Audit Date:** 2026-01-17
|
||||
**Auditor:** Claude Code Security Review Agent
|
||||
**Scope:** cognitum-gate-kernel, cognitum-gate-tilezero, mcp-gate
|
||||
**Risk Classification:** Uses CVSS-style severity (Critical/High/Medium/Low)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This security audit identified **17 security issues** across the cognitum-gate implementation:
|
||||
|
||||
| Severity | Count | Categories |
|
||||
|----------|-------|------------|
|
||||
| Critical | 2 | Cryptographic bypass, signature truncation |
|
||||
| High | 4 | Memory safety, unsafe code, race conditions |
|
||||
| Medium | 6 | Input validation, integer overflow, DoS vectors |
|
||||
| Low | 5 | Information disclosure, edge cases |
|
||||
|
||||
**Recommendation:** The Critical issues in `permit.rs` must be fixed before production deployment as they completely bypass signature verification.
|
||||
|
||||
---
|
||||
|
||||
## Critical Issues
|
||||
|
||||
### CGK-001: Signature Verification Bypass (CRITICAL)
|
||||
|
||||
**Severity:** Critical
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-tilezero/src/permit.rs:136-153`
|
||||
**CVSS:** 9.8 (Critical)
|
||||
|
||||
**Description:**
|
||||
The `Verifier::verify()` function does not actually verify signatures. It computes a hash from the token content and compares it to... the same hash computed from the same content. This comparison always succeeds.
|
||||
|
||||
```rust
|
||||
// Lines 147-151 - BROKEN VERIFICATION
|
||||
let expected_hash = blake3::hash(&content);
|
||||
if hash.as_bytes() != expected_hash.as_bytes() {
|
||||
return Err(VerifyError::HashMismatch);
|
||||
}
|
||||
// hash == expected_hash ALWAYS - computed from same content!
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
Any attacker can forge permit tokens. The cryptographic authentication is completely bypassed. All gate decisions can be spoofed.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
pub fn verify(&self, token: &PermitToken) -> Result<(), VerifyError> {
|
||||
let content = token.signable_content();
|
||||
let hash = blake3::hash(&content);
|
||||
|
||||
// Reconstruct full 64-byte signature
|
||||
// REQUIRES: Store full signature in token, not truncated 32 bytes
|
||||
let signature = ed25519_dalek::Signature::from_bytes(&token.signature)
|
||||
.map_err(|_| VerifyError::SignatureFailed)?;
|
||||
|
||||
// Actually verify the signature
|
||||
self.verifying_key
|
||||
.verify(hash.as_bytes(), &signature)
|
||||
.map_err(|_| VerifyError::SignatureFailed)?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-002: Ed25519 Signature Truncation (CRITICAL)
|
||||
|
||||
**Severity:** Critical
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-tilezero/src/permit.rs:103-111`
|
||||
**CVSS:** 9.1 (Critical)
|
||||
|
||||
**Description:**
|
||||
The `sign_token` function truncates the 64-byte Ed25519 signature to 32 bytes:
|
||||
|
||||
```rust
|
||||
// Line 109 - Discards half the signature!
|
||||
token.mac.copy_from_slice(&signature.to_bytes()[..32]);
|
||||
```
|
||||
|
||||
Ed25519 signatures are 64 bytes. Truncating to 32 bytes makes reconstruction impossible and verification meaningless.
|
||||
|
||||
**Impact:**
|
||||
Combined with CGK-001, this makes signature verification completely non-functional. Even if verification was fixed, the stored signature cannot be reconstructed.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
// In PermitToken struct - change mac field:
|
||||
pub signature: [u8; 64], // Full Ed25519 signature
|
||||
|
||||
// In sign_token:
|
||||
token.signature.copy_from_slice(&signature.to_bytes());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## High Severity Issues
|
||||
|
||||
### CGK-003: Unsafe Global Mutable State Without Synchronization
|
||||
|
||||
**Severity:** High
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-kernel/src/lib.rs:413`
|
||||
**CVSS:** 7.5
|
||||
|
||||
**Description:**
|
||||
The global `TILE_STATE` is accessed through `static mut` without any synchronization primitives:
|
||||
|
||||
```rust
|
||||
static mut TILE_STATE: Option<TileState> = None;
|
||||
```
|
||||
|
||||
All WASM export functions (`init_tile`, `ingest_delta`, `tick`, etc.) access this mutable static unsafely.
|
||||
|
||||
**Impact:**
|
||||
In multi-threaded contexts or if WASM threading is enabled, this creates data races leading to undefined behavior, memory corruption, or security bypasses.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
use core::cell::UnsafeCell;
|
||||
use core::sync::atomic::{AtomicBool, Ordering};
|
||||
|
||||
struct TileStateHolder {
|
||||
initialized: AtomicBool,
|
||||
state: UnsafeCell<Option<TileState>>,
|
||||
}
|
||||
|
||||
// Or for single-threaded WASM, use OnceCell pattern
|
||||
static TILE_STATE: once_cell::sync::OnceCell<RefCell<TileState>> = OnceCell::new();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-004: Unsafe Raw Pointer Dereference Without Validation
|
||||
|
||||
**Severity:** High
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-kernel/src/lib.rs:207-210`
|
||||
**CVSS:** 7.3
|
||||
|
||||
**Description:**
|
||||
The `ingest_delta_raw` function casts a raw pointer without checking alignment:
|
||||
|
||||
```rust
|
||||
pub unsafe fn ingest_delta_raw(&mut self, ptr: *const u8) -> bool {
|
||||
let delta = unsafe { &*(ptr as *const Delta) }; // No alignment check!
|
||||
self.ingest_delta(delta)
|
||||
}
|
||||
```
|
||||
|
||||
`Delta` likely requires alignment > 1 byte. Misaligned access is undefined behavior.
|
||||
|
||||
**Impact:**
|
||||
Misaligned memory access causes undefined behavior on some architectures, potentially leading to crashes or exploitable memory corruption.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
pub unsafe fn ingest_delta_raw(&mut self, ptr: *const u8) -> bool {
|
||||
// Check alignment
|
||||
if (ptr as usize) % core::mem::align_of::<Delta>() != 0 {
|
||||
return false;
|
||||
}
|
||||
// Check null
|
||||
if ptr.is_null() {
|
||||
return false;
|
||||
}
|
||||
let delta = unsafe { &*(ptr as *const Delta) };
|
||||
self.ingest_delta(delta)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-005: Bump Allocator Race Condition
|
||||
|
||||
**Severity:** High
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-kernel/src/lib.rs:70-99`
|
||||
**CVSS:** 7.0
|
||||
|
||||
**Description:**
|
||||
The bump allocator uses static mutable variables without synchronization:
|
||||
|
||||
```rust
|
||||
static mut HEAP: [u8; HEAP_SIZE] = [0; HEAP_SIZE];
|
||||
static mut HEAP_PTR: usize = 0;
|
||||
|
||||
unsafe impl GlobalAlloc for BumpAllocator {
|
||||
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
|
||||
unsafe {
|
||||
let aligned = (HEAP_PTR + align - 1) & !(align - 1); // Race condition!
|
||||
// ...
|
||||
HEAP_PTR = aligned + size; // Non-atomic update!
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
Concurrent allocations could return overlapping memory regions, leading to memory corruption.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
use core::sync::atomic::{AtomicUsize, Ordering};
|
||||
|
||||
static HEAP_PTR: AtomicUsize = AtomicUsize::new(0);
|
||||
|
||||
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
|
||||
loop {
|
||||
let current = HEAP_PTR.load(Ordering::Acquire);
|
||||
let aligned = (current + layout.align() - 1) & !(layout.align() - 1);
|
||||
let new_ptr = aligned + layout.size();
|
||||
|
||||
if new_ptr > HEAP_SIZE {
|
||||
return core::ptr::null_mut();
|
||||
}
|
||||
|
||||
if HEAP_PTR.compare_exchange_weak(current, new_ptr, Ordering::Release, Ordering::Relaxed).is_ok() {
|
||||
return unsafe { HEAP.as_mut_ptr().add(aligned) };
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-006: Unchecked Union Access in Delta Processing
|
||||
|
||||
**Severity:** High
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-kernel/src/lib.rs:288-321`
|
||||
**CVSS:** 6.8
|
||||
|
||||
**Description:**
|
||||
The `apply_delta` function uses unsafe union access based on a tag field:
|
||||
|
||||
```rust
|
||||
DeltaTag::EdgeAdd => {
|
||||
let ea = unsafe { delta.get_edge_add() }; // Trusts tag
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
If the tag is corrupted or maliciously set, accessing the wrong union variant leads to undefined behavior.
|
||||
|
||||
**Impact:**
|
||||
A malformed delta with mismatched tag/data could cause memory corruption or information disclosure.
|
||||
|
||||
**Recommended Fix:**
|
||||
- Add validation of delta integrity (checksum/hash)
|
||||
- Use a safe enum representation instead of tagged union where possible
|
||||
- Add bounds checking on union field values after extraction
|
||||
|
||||
---
|
||||
|
||||
## Medium Severity Issues
|
||||
|
||||
### CGK-007: Division by Zero in Threshold Computation
|
||||
|
||||
**Severity:** Medium
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-tilezero/src/decision.rs:223-228`
|
||||
**CVSS:** 5.9
|
||||
|
||||
**Description:**
|
||||
Pre-computed reciprocals can cause division by zero:
|
||||
|
||||
```rust
|
||||
let inv_min_cut = 1.0 / thresholds.min_cut; // Zero if min_cut == 0
|
||||
let inv_max_shift = 1.0 / thresholds.max_shift; // Zero if max_shift == 0
|
||||
let inv_tau_range = 1.0 / (thresholds.tau_permit - thresholds.tau_deny); // Zero if equal
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
Results in infinity/NaN values that propagate through decision logic, potentially causing incorrect permit/deny decisions.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
pub fn new(thresholds: GateThresholds) -> Result<Self, ThresholdError> {
|
||||
if thresholds.min_cut == 0.0 || thresholds.max_shift == 0.0 {
|
||||
return Err(ThresholdError::ZeroThreshold);
|
||||
}
|
||||
if (thresholds.tau_permit - thresholds.tau_deny).abs() < f64::EPSILON {
|
||||
return Err(ThresholdError::EqualTauRange);
|
||||
}
|
||||
// ... continue with safe reciprocal computation
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-008: Integer Overflow in Token TTL Check
|
||||
|
||||
**Severity:** Medium
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-tilezero/src/permit.rs:31-33`
|
||||
**CVSS:** 5.3
|
||||
|
||||
**Description:**
|
||||
The validity check can overflow:
|
||||
|
||||
```rust
|
||||
pub fn is_valid_time(&self, now_ns: u64) -> bool {
|
||||
now_ns <= self.timestamp + self.ttl_ns // Overflow possible!
|
||||
}
|
||||
```
|
||||
|
||||
If `timestamp + ttl_ns` overflows u64, the comparison becomes incorrect.
|
||||
|
||||
**Impact:**
|
||||
Tokens with very large timestamps or TTLs could have incorrect validity checks, either expiring immediately or never expiring.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
pub fn is_valid_time(&self, now_ns: u64) -> bool {
|
||||
self.timestamp.checked_add(self.ttl_ns)
|
||||
.map(|expiry| now_ns <= expiry)
|
||||
.unwrap_or(true) // If overflow, consider perpetually valid or use saturating
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-009: Unbounded History Growth / DoS Vector
|
||||
|
||||
**Severity:** Medium
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-tilezero/src/receipt.rs:124-132, 169-185`
|
||||
**CVSS:** 5.0
|
||||
|
||||
**Description:**
|
||||
The `ReceiptLog` uses a HashMap that grows unboundedly:
|
||||
|
||||
```rust
|
||||
pub struct ReceiptLog {
|
||||
receipts: HashMap<u64, WitnessReceipt>, // Grows forever
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Additionally, `verify_chain_to` iterates from 0 to sequence number, making it O(n) in chain length.
|
||||
|
||||
**Impact:**
|
||||
Memory exhaustion attack by generating many decisions. Chain verification becomes increasingly slow.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
const MAX_RECEIPTS: usize = 100_000;
|
||||
|
||||
pub fn append(&mut self, receipt: WitnessReceipt) -> Result<(), LogFullError> {
|
||||
if self.receipts.len() >= MAX_RECEIPTS {
|
||||
// Implement pruning or return error
|
||||
self.prune_old_receipts();
|
||||
}
|
||||
// ...
|
||||
}
|
||||
|
||||
// Use rolling window verification instead of full chain
|
||||
pub fn verify_recent(&self, window: usize) -> Result<(), ChainVerifyError> {
|
||||
let start = self.latest_sequence.saturating_sub(window as u64);
|
||||
// Verify only recent entries
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-010: Unchecked Array Index in Evidence Processing
|
||||
|
||||
**Severity:** Medium
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-kernel/src/evidence.rs:407-416`
|
||||
**CVSS:** 4.8
|
||||
|
||||
**Description:**
|
||||
Window access uses unchecked indexing:
|
||||
|
||||
```rust
|
||||
let idx = self.window_head as usize;
|
||||
// Line 410: Assumes idx < WINDOW_SIZE
|
||||
unsafe {
|
||||
*self.window.get_unchecked_mut(idx) = ObsRecord { obs, tick };
|
||||
}
|
||||
```
|
||||
|
||||
The bit masking on line 413 is correct, but it happens AFTER the unsafe access.
|
||||
|
||||
**Impact:**
|
||||
If `window_head` is corrupted, out-of-bounds write occurs.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
// Apply mask BEFORE access
|
||||
let idx = (self.window_head as usize) & (WINDOW_SIZE - 1);
|
||||
self.window[idx] = ObsRecord { obs, tick }; // Safe bounds-checked access
|
||||
self.window_head = (self.window_head + 1) as u16;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-011: Panic on System Time Before Epoch
|
||||
|
||||
**Severity:** Medium
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-tilezero/src/lib.rs:173-176`
|
||||
**CVSS:** 4.5
|
||||
|
||||
**Description:**
|
||||
The time computation can panic:
|
||||
|
||||
```rust
|
||||
let now = std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap() // Panics if system time < epoch!
|
||||
.as_nanos() as u64;
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
If system time is misconfigured (before 1970), the gate panics and becomes unavailable.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
let now = std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap_or(std::time::Duration::ZERO)
|
||||
.as_nanos() as u64;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-012: Processing Rate Division by Zero
|
||||
|
||||
**Severity:** Medium
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-kernel/src/report.rs:284-289`
|
||||
**CVSS:** 4.0
|
||||
|
||||
**Description:**
|
||||
```rust
|
||||
pub fn processing_rate(&self) -> f32 {
|
||||
if self.tick_time_us == 0 {
|
||||
0.0 // Handled correctly
|
||||
} else {
|
||||
(self.deltas_processed as f32) / (self.tick_time_us as f32)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is actually handled correctly. However, the check should use floating point division behavior documentation.
|
||||
|
||||
**Status:** No action required - correctly implemented.
|
||||
|
||||
---
|
||||
|
||||
## Low Severity Issues
|
||||
|
||||
### CGK-013: Tick Time Truncation
|
||||
|
||||
**Severity:** Low
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-kernel/src/lib.rs:257`
|
||||
**CVSS:** 3.5
|
||||
|
||||
**Description:**
|
||||
Tick time is cast from u32 to u16:
|
||||
|
||||
```rust
|
||||
report.tick_time_us = (tick_end - tick_start) as u16; // Truncates if > 65535
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
Ticks longer than ~65ms will have incorrect timing metrics, affecting performance analysis.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
report.tick_time_us = (tick_end - tick_start).min(u16::MAX as u32) as u16;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-014: Silent JSON Serialization Failure
|
||||
|
||||
**Severity:** Low
|
||||
**Location:** `/home/user/ruvector/crates/cognitum-gate-tilezero/src/receipt.rs:82-83`
|
||||
**CVSS:** 3.1
|
||||
|
||||
**Description:**
|
||||
```rust
|
||||
pub fn hash(&self) -> [u8; 32] {
|
||||
let json = serde_json::to_vec(self).unwrap_or_default(); // Silent failure!
|
||||
*blake3::hash(&json).as_bytes()
|
||||
}
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
If serialization fails, an empty hash is computed, potentially causing hash collisions.
|
||||
|
||||
**Recommended Fix:**
|
||||
```rust
|
||||
pub fn hash(&self) -> Result<[u8; 32], HashError> {
|
||||
let json = serde_json::to_vec(self)?;
|
||||
Ok(*blake3::hash(&json).as_bytes())
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CGK-015: Information Disclosure in Error Messages
|
||||
|
||||
**Severity:** Low
|
||||
**Location:** `/home/user/ruvector/crates/mcp-gate/src/tools.rs:292-355`
|
||||
**CVSS:** 3.0
|
||||
|
||||
**Description:**
|
||||
Error messages expose internal state details:
|
||||
|
||||
```rust
|
||||
format!("Min-cut {:.3} below threshold {:.3}", mincut_value, self.thresholds.min_cut)
|
||||
format!("E-value {:.4} indicates strong evidence of incoherence", summary.evidential.e_value)
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
Exposes exact threshold values and internal metrics to clients, aiding targeted attacks.
|
||||
|
||||
**Recommended Fix:**
|
||||
Return generic error codes to external clients; log detailed messages internally only.
|
||||
|
||||
---
|
||||
|
||||
### CGK-016: No Input Size Limits on Tool Calls
|
||||
|
||||
**Severity:** Low
|
||||
**Location:** `/home/user/ruvector/crates/mcp-gate/src/tools.rs:126-159`
|
||||
**CVSS:** 2.8
|
||||
|
||||
**Description:**
|
||||
The `call_tool` function deserializes JSON without size limits:
|
||||
|
||||
```rust
|
||||
let request: PermitActionRequest = serde_json::from_value(call.arguments)
|
||||
.map_err(|e| McpError::InvalidRequest(e.to_string()))?;
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
Very large JSON payloads could cause memory exhaustion.
|
||||
|
||||
**Recommended Fix:**
|
||||
Add a size limit check before deserialization or use `serde_json` with size limits.
|
||||
|
||||
---
|
||||
|
||||
### CGK-017: Hardcoded Escalation Timeout
|
||||
|
||||
**Severity:** Low
|
||||
**Location:** `/home/user/ruvector/crates/mcp-gate/src/tools.rs:194`
|
||||
**CVSS:** 2.5
|
||||
|
||||
**Description:**
|
||||
```rust
|
||||
timeout_ns: 300_000_000_000, // 5 minutes - hardcoded
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
Cannot adjust escalation timeout without code changes; not a direct security issue but affects operational security.
|
||||
|
||||
**Recommended Fix:**
|
||||
Make configurable via `GateThresholds` or environment variable.
|
||||
|
||||
---
|
||||
|
||||
## Recommendations Summary
|
||||
|
||||
### Immediate Actions (Critical/High)
|
||||
|
||||
1. **Fix signature verification** (CGK-001, CGK-002) - This is a complete authentication bypass
|
||||
2. **Add synchronization to global state** (CGK-003, CGK-005) - Prevents data races
|
||||
3. **Add alignment/null checks to raw pointer operations** (CGK-004)
|
||||
4. **Add validation to delta processing** (CGK-006)
|
||||
|
||||
### Short-term Actions (Medium)
|
||||
|
||||
5. **Validate thresholds before computing reciprocals** (CGK-007)
|
||||
6. **Use checked arithmetic for token TTL** (CGK-008)
|
||||
7. **Bound receipt log size and optimize chain verification** (CGK-009)
|
||||
8. **Reorder bit masking in evidence window** (CGK-010)
|
||||
9. **Handle system time edge cases** (CGK-011)
|
||||
|
||||
### Long-term Actions (Low)
|
||||
|
||||
10. **Sanitize error messages for external clients** (CGK-015)
|
||||
11. **Add input size limits** (CGK-016)
|
||||
12. **Make operational parameters configurable** (CGK-017)
|
||||
|
||||
---
|
||||
|
||||
## Unsafe Code Audit Summary
|
||||
|
||||
| File | Unsafe Blocks | Safety Concerns |
|
||||
|------|---------------|-----------------|
|
||||
| kernel/lib.rs | 8 | Global state, raw pointers, union access |
|
||||
| kernel/shard.rs | 14 | Unchecked array indexing (performance-critical) |
|
||||
| kernel/evidence.rs | 4 | Unchecked window access |
|
||||
| kernel/report.rs | 0 | None |
|
||||
| tilezero/lib.rs | 0 | None |
|
||||
| tilezero/permit.rs | 0 | None (but cryptographic issues) |
|
||||
| tilezero/receipt.rs | 0 | None |
|
||||
| tilezero/decision.rs | 0 | None |
|
||||
| mcp-gate/tools.rs | 0 | None |
|
||||
|
||||
The kernel crate uses unsafe code extensively for performance optimization. Each instance should be audited against its safety invariants.
|
||||
|
||||
---
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
1. **Fuzzing:** Apply `cargo-fuzz` to delta parsing and token decoding
|
||||
2. **Property testing:** Use `proptest` for invariant validation
|
||||
3. **Miri:** Run `cargo miri test` to detect undefined behavior
|
||||
4. **Memory sanitizers:** Test with AddressSanitizer and MemorySanitizer
|
||||
|
||||
---
|
||||
|
||||
## Compliance Notes
|
||||
|
||||
- **No timing attacks identified** in the cryptographic code (uses constant-time libraries)
|
||||
- **Key generation** uses `OsRng` which is cryptographically secure
|
||||
- **Hash function** (blake3) is modern and appropriate
|
||||
- **Signature scheme** (Ed25519) is appropriate but implementation is broken
|
||||
|
||||
---
|
||||
|
||||
## Appendix A: Delta Module Analysis
|
||||
|
||||
**File:** `/home/user/ruvector/crates/cognitum-gate-kernel/src/delta.rs`
|
||||
|
||||
The delta module implements a tagged union (`DeltaPayload`) for graph updates. The design is sound but has some security considerations:
|
||||
|
||||
### Union Safety
|
||||
|
||||
The `DeltaPayload` union is correctly sized (8 bytes for all variants) with compile-time assertions. The unsafe accessor methods (`get_edge_add`, `get_edge_remove`, etc.) correctly require the caller to verify the tag before access.
|
||||
|
||||
**Current Implementation (Lines 379-401):**
|
||||
```rust
|
||||
/// Get the edge add payload (unsafe: caller must verify tag)
|
||||
pub unsafe fn get_edge_add(&self) -> &EdgeAdd {
|
||||
unsafe { &self.payload.edge_add }
|
||||
}
|
||||
```
|
||||
|
||||
**Recommendation:** Consider adding debug assertions:
|
||||
```rust
|
||||
#[inline]
|
||||
pub unsafe fn get_edge_add(&self) -> &EdgeAdd {
|
||||
debug_assert_eq!(self.tag, DeltaTag::EdgeAdd, "Invalid tag for EdgeAdd access");
|
||||
unsafe { &self.payload.edge_add }
|
||||
}
|
||||
```
|
||||
|
||||
### Alignment Considerations
|
||||
|
||||
The `Delta` struct is aligned to 16 bytes (`#[repr(C, align(16))]`), which is correct for WASM and most architectures. However, when deserializing from raw bytes (as in `ingest_delta_raw`), alignment must be verified.
|
||||
|
||||
---
|
||||
|
||||
## Appendix B: Threat Model Summary
|
||||
|
||||
| Threat | Likelihood | Impact | Mitigation Status |
|
||||
|--------|------------|--------|------------------|
|
||||
| Token forgery (CGK-001/002) | High | Critical | NOT MITIGATED |
|
||||
| Memory corruption via malformed delta | Medium | High | Partial (tag check, no integrity check) |
|
||||
| DoS via memory exhaustion | Medium | Medium | Partial (fixed buffers, but unbounded log) |
|
||||
| Race condition exploitation | Low | High | NOT MITIGATED (single-threaded WASM assumed) |
|
||||
| Timing side-channel | Low | Low | Mitigated (constant-time crypto libs) |
|
||||
|
||||
---
|
||||
|
||||
## Appendix C: Verification Status of Unsafe Code Invariants
|
||||
|
||||
| Location | Invariant | Verified By |
|
||||
|----------|-----------|-------------|
|
||||
| shard.rs:450 | source < MAX_SHARD_VERTICES | Bounds check at line 445 |
|
||||
| shard.rs:457 | degree <= MAX_DEGREE | Struct invariant (add_edge checks) |
|
||||
| shard.rs:576-577 | root < MAX_SHARD_VERTICES | Loop construction |
|
||||
| evidence.rs:410 | idx < WINDOW_SIZE | **BROKEN** - mask applied after access |
|
||||
| lib.rs:208 | ptr aligned to Delta alignment | **NOT VERIFIED** |
|
||||
| lib.rs:292 | tag matches payload variant | Tag set during construction only |
|
||||
|
||||
---
|
||||
|
||||
*Report generated by Claude Code Security Review Agent*
|
||||
*Classification: Internal Security Document*
|
||||
913
crates/cognitum-gate-kernel/src/canonical_witness.rs
Normal file
913
crates/cognitum-gate-kernel/src/canonical_witness.rs
Normal file
@@ -0,0 +1,913 @@
|
||||
//! Canonical witness fragments using pseudo-deterministic min-cut.
|
||||
//!
|
||||
//! Produces reproducible, hash-stable witness fragments by computing
|
||||
//! a canonical min-cut partition via lexicographic tie-breaking.
|
||||
//!
|
||||
//! All structures are `#[repr(C)]` aligned, use fixed-size arrays, and
|
||||
//! operate entirely on the stack (no heap allocation). This module is
|
||||
//! designed for no_std WASM tiles with a ~2.1KB temporary memory footprint.
|
||||
|
||||
#![allow(missing_docs)]
|
||||
|
||||
use crate::shard::{CompactGraph, MAX_SHARD_VERTICES};
|
||||
use core::mem::size_of;
|
||||
|
||||
// ============================================================================
|
||||
// Fixed-point weight for deterministic comparison
|
||||
// ============================================================================
|
||||
|
||||
/// Fixed-point weight for deterministic, total-order comparison.
|
||||
///
|
||||
/// Uses 16.16 fixed-point representation (upper 16 bits integer, lower 16
|
||||
/// bits fractional). This avoids floating-point non-determinism in
|
||||
/// partition comparisons.
|
||||
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
|
||||
#[repr(transparent)]
|
||||
pub struct FixedPointWeight(pub u32);
|
||||
|
||||
impl FixedPointWeight {
|
||||
/// Zero weight constant
|
||||
pub const ZERO: Self = Self(0);
|
||||
|
||||
/// One (1.0) in 16.16 fixed-point
|
||||
pub const ONE: Self = Self(65536);
|
||||
|
||||
/// Maximum representable weight
|
||||
pub const MAX: Self = Self(u32::MAX);
|
||||
|
||||
/// Convert from a `ShardEdge` weight (u16, 0.01 precision) to fixed-point.
|
||||
///
|
||||
/// The shard weight is scaled up by shifting left 8 bits, mapping
|
||||
/// the 0-65535 range into the 16.16 fixed-point space.
|
||||
#[inline(always)]
|
||||
pub const fn from_u16_weight(w: u16) -> Self {
|
||||
Self((w as u32) << 8)
|
||||
}
|
||||
|
||||
/// Saturating addition (clamps at `u32::MAX`)
|
||||
#[inline(always)]
|
||||
pub const fn saturating_add(self, other: Self) -> Self {
|
||||
Self(self.0.saturating_add(other.0))
|
||||
}
|
||||
|
||||
/// Saturating subtraction (clamps at 0)
|
||||
#[inline(always)]
|
||||
pub const fn saturating_sub(self, other: Self) -> Self {
|
||||
Self(self.0.saturating_sub(other.0))
|
||||
}
|
||||
|
||||
/// Truncate to u16 by shifting right 8 bits (inverse of `from_u16_weight`)
|
||||
#[inline(always)]
|
||||
pub const fn to_u16(self) -> u16 {
|
||||
(self.0 >> 8) as u16
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Cactus node and arena
|
||||
// ============================================================================
|
||||
|
||||
/// A single node in the arena-allocated cactus tree.
|
||||
///
|
||||
/// Represents a vertex (or contracted 2-edge-connected component) in the
|
||||
/// simplified cactus structure derived from the tile's compact graph.
|
||||
#[derive(Debug, Copy, Clone)]
|
||||
#[repr(C)]
|
||||
pub struct CactusNode {
|
||||
/// Vertex ID in the original graph
|
||||
pub id: u16,
|
||||
/// Parent index in `ArenaCactus::nodes` (0xFFFF = root / no parent)
|
||||
pub parent: u16,
|
||||
/// Degree in the cactus tree
|
||||
pub degree: u8,
|
||||
/// Flags (reserved)
|
||||
pub flags: u8,
|
||||
/// Weight of the edge connecting this node to its parent
|
||||
pub weight_to_parent: FixedPointWeight,
|
||||
}
|
||||
|
||||
impl CactusNode {
|
||||
/// Sentinel value indicating no parent (root node)
|
||||
pub const NO_PARENT: u16 = 0xFFFF;
|
||||
|
||||
/// Create an empty / default node
|
||||
#[inline(always)]
|
||||
pub const fn empty() -> Self {
|
||||
Self {
|
||||
id: 0,
|
||||
parent: Self::NO_PARENT,
|
||||
degree: 0,
|
||||
flags: 0,
|
||||
weight_to_parent: FixedPointWeight::ZERO,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Compile-time size check: repr(C) layout is 12 bytes
|
||||
// (u16 + u16 + u8 + u8 + 2-pad + u32 = 12, aligned to 4)
|
||||
// 256 nodes * 12 = 3072 bytes (~3KB), fits in 14.5KB headroom.
|
||||
const _: () = assert!(size_of::<CactusNode>() == 12, "CactusNode must be 12 bytes");
|
||||
|
||||
/// Arena-allocated cactus tree for a single tile (up to 256 vertices).
|
||||
///
|
||||
/// The cactus captures the 2-edge-connected component structure of the
|
||||
/// tile's local graph. It is built entirely on the stack (~2KB) and used
|
||||
/// to derive a canonical min-cut partition.
|
||||
#[repr(C)]
|
||||
pub struct ArenaCactus {
|
||||
/// Node storage (one per vertex in the original graph)
|
||||
pub nodes: [CactusNode; 256],
|
||||
/// Number of active nodes
|
||||
pub n_nodes: u16,
|
||||
/// Root node index
|
||||
pub root: u16,
|
||||
/// Value of the global minimum cut found
|
||||
pub min_cut_value: FixedPointWeight,
|
||||
}
|
||||
|
||||
impl ArenaCactus {
|
||||
/// Build a cactus from the tile's `CompactGraph`.
|
||||
///
|
||||
/// Algorithm (simplified):
|
||||
/// 1. BFS spanning tree from the lowest-ID active vertex.
|
||||
/// 2. Identify back edges and compute 2-edge-connected components
|
||||
/// via low-link (Tarjan-style on edges).
|
||||
/// 3. Contract each 2-edge-connected component into a single cactus
|
||||
/// node; the inter-component bridge edges become cactus edges.
|
||||
/// 4. Track the minimum-weight bridge as the global min-cut value.
|
||||
pub fn build_from_compact_graph(graph: &CompactGraph) -> Self {
|
||||
let mut cactus = ArenaCactus {
|
||||
nodes: [CactusNode::empty(); 256],
|
||||
n_nodes: 0,
|
||||
root: 0xFFFF,
|
||||
min_cut_value: FixedPointWeight::MAX,
|
||||
};
|
||||
|
||||
if graph.num_vertices == 0 {
|
||||
cactus.min_cut_value = FixedPointWeight::ZERO;
|
||||
return cactus;
|
||||
}
|
||||
|
||||
// ---- Phase 1: BFS spanning tree ----
|
||||
// BFS queue (fixed-size ring buffer)
|
||||
let mut queue = [0u16; 256];
|
||||
let mut q_head: usize = 0;
|
||||
let mut q_tail: usize = 0;
|
||||
|
||||
// Per-vertex BFS state
|
||||
let mut visited = [false; MAX_SHARD_VERTICES];
|
||||
let mut parent = [0xFFFFu16; MAX_SHARD_VERTICES];
|
||||
let mut depth = [0u16; MAX_SHARD_VERTICES];
|
||||
// Component ID for 2-edge-connected grouping
|
||||
let mut comp_id = [0xFFFFu16; MAX_SHARD_VERTICES];
|
||||
|
||||
// Find lowest-ID active vertex as root
|
||||
let mut root_v = 0xFFFFu16;
|
||||
for v in 0..MAX_SHARD_VERTICES {
|
||||
if graph.vertices[v].is_active() {
|
||||
root_v = v as u16;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if root_v == 0xFFFF {
|
||||
cactus.min_cut_value = FixedPointWeight::ZERO;
|
||||
return cactus;
|
||||
}
|
||||
|
||||
// BFS
|
||||
visited[root_v as usize] = true;
|
||||
parent[root_v as usize] = 0xFFFF;
|
||||
queue[q_tail] = root_v;
|
||||
q_tail += 1;
|
||||
|
||||
while q_head < q_tail {
|
||||
let u = queue[q_head] as usize;
|
||||
q_head += 1;
|
||||
|
||||
let neighbors = graph.neighbors(u as u16);
|
||||
for adj in neighbors {
|
||||
let w = adj.neighbor as usize;
|
||||
if !visited[w] {
|
||||
visited[w] = true;
|
||||
parent[w] = u as u16;
|
||||
depth[w] = depth[u] + 1;
|
||||
if q_tail < 256 {
|
||||
queue[q_tail] = w as u16;
|
||||
q_tail += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---- Phase 2: Identify 2-edge-connected components ----
|
||||
// For each back edge (u,w) where w is an ancestor of u in the BFS tree,
|
||||
// all vertices on the path from u to w belong to the same 2-edge-connected
|
||||
// component. We perform path marking for each back edge.
|
||||
let mut next_comp: u16 = 0;
|
||||
|
||||
// Mark tree edges as bridges initially; back edges will un-bridge them
|
||||
// We iterate edges and find back edges (both endpoints visited, not parent-child)
|
||||
for e_idx in 0..graph.edges.len() {
|
||||
let edge = &graph.edges[e_idx];
|
||||
if !edge.is_active() {
|
||||
continue;
|
||||
}
|
||||
let u = edge.source as usize;
|
||||
let w = edge.target as usize;
|
||||
|
||||
if !visited[u] || !visited[w] {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check if this is a back edge (non-tree edge)
|
||||
let is_tree = (parent[w] == u as u16 && depth[w] == depth[u] + 1)
|
||||
|| (parent[u] == w as u16 && depth[u] == depth[w] + 1);
|
||||
|
||||
if is_tree {
|
||||
continue; // Skip tree edges
|
||||
}
|
||||
|
||||
// Back edge found: mark the path from u to w as same component
|
||||
// Walk u and w up to their LCA, assigning a single component ID
|
||||
let c = if comp_id[u] != 0xFFFF {
|
||||
comp_id[u]
|
||||
} else if comp_id[w] != 0xFFFF {
|
||||
comp_id[w]
|
||||
} else {
|
||||
let c = next_comp;
|
||||
next_comp = next_comp.saturating_add(1);
|
||||
c
|
||||
};
|
||||
|
||||
// Walk from u towards root, marking component
|
||||
let mut a = u as u16;
|
||||
while a != 0xFFFF && comp_id[a as usize] != c {
|
||||
if comp_id[a as usize] == 0xFFFF {
|
||||
comp_id[a as usize] = c;
|
||||
}
|
||||
a = parent[a as usize];
|
||||
}
|
||||
|
||||
// Walk from w towards root, marking component
|
||||
let mut b = w as u16;
|
||||
while b != 0xFFFF && comp_id[b as usize] != c {
|
||||
if comp_id[b as usize] == 0xFFFF {
|
||||
comp_id[b as usize] = c;
|
||||
}
|
||||
b = parent[b as usize];
|
||||
}
|
||||
}
|
||||
|
||||
// Assign each unmarked visited vertex its own component
|
||||
for v in 0..MAX_SHARD_VERTICES {
|
||||
if visited[v] && comp_id[v] == 0xFFFF {
|
||||
comp_id[v] = next_comp;
|
||||
next_comp = next_comp.saturating_add(1);
|
||||
}
|
||||
}
|
||||
|
||||
// ---- Phase 3: Build cactus from component structure ----
|
||||
// Each unique comp_id becomes a cactus node.
|
||||
// The representative vertex is the lowest-ID vertex in the component.
|
||||
let mut comp_repr = [0xFFFFu16; 256]; // comp_id -> representative vertex
|
||||
let mut comp_to_node = [0xFFFFu16; 256]; // comp_id -> cactus node index
|
||||
|
||||
// Find representative (lowest vertex ID) for each component
|
||||
for v in 0..MAX_SHARD_VERTICES {
|
||||
if !visited[v] {
|
||||
continue;
|
||||
}
|
||||
let c = comp_id[v] as usize;
|
||||
if c < 256 && (comp_repr[c] == 0xFFFF || (v as u16) < comp_repr[c]) {
|
||||
comp_repr[c] = v as u16;
|
||||
}
|
||||
}
|
||||
|
||||
// Create cactus nodes for each component
|
||||
let mut n_cactus: u16 = 0;
|
||||
for c in 0..next_comp.min(256) as usize {
|
||||
if comp_repr[c] != 0xFFFF {
|
||||
let idx = n_cactus as usize;
|
||||
if idx < 256 {
|
||||
cactus.nodes[idx] = CactusNode {
|
||||
id: comp_repr[c],
|
||||
parent: CactusNode::NO_PARENT,
|
||||
degree: 0,
|
||||
flags: 0,
|
||||
weight_to_parent: FixedPointWeight::ZERO,
|
||||
};
|
||||
comp_to_node[c] = n_cactus;
|
||||
n_cactus += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
cactus.n_nodes = n_cactus;
|
||||
|
||||
// Set root to the node containing root_v
|
||||
let root_comp = comp_id[root_v as usize] as usize;
|
||||
if root_comp < 256 {
|
||||
cactus.root = comp_to_node[root_comp];
|
||||
}
|
||||
|
||||
// ---- Phase 4: Connect cactus nodes via bridge edges ----
|
||||
// A tree edge (parent[v] -> v) where comp_id[parent[v]] != comp_id[v]
|
||||
// is a bridge. It becomes a cactus edge.
|
||||
for v in 0..MAX_SHARD_VERTICES {
|
||||
if !visited[v] || parent[v] == 0xFFFF {
|
||||
continue;
|
||||
}
|
||||
let p = parent[v] as usize;
|
||||
let cv = comp_id[v] as usize;
|
||||
let cp = comp_id[p] as usize;
|
||||
|
||||
if cv != cp && cv < 256 && cp < 256 {
|
||||
let node_v = comp_to_node[cv];
|
||||
let node_p = comp_to_node[cp];
|
||||
|
||||
if node_v < 256
|
||||
&& node_p < 256
|
||||
&& cactus.nodes[node_v as usize].parent == CactusNode::NO_PARENT
|
||||
&& node_v != cactus.root
|
||||
{
|
||||
// Compute bridge weight: sum of edge weights between the
|
||||
// two components along this boundary
|
||||
let bridge_weight = Self::compute_bridge_weight(graph, v as u16, parent[v]);
|
||||
|
||||
cactus.nodes[node_v as usize].parent = node_p;
|
||||
cactus.nodes[node_v as usize].weight_to_parent = bridge_weight;
|
||||
cactus.nodes[node_p as usize].degree += 1;
|
||||
cactus.nodes[node_v as usize].degree += 1;
|
||||
|
||||
// Track minimum cut
|
||||
if bridge_weight < cactus.min_cut_value {
|
||||
cactus.min_cut_value = bridge_weight;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// If no bridges found, min cut is sum of all edge weights (graph is
|
||||
// 2-edge-connected) or zero if there are no edges
|
||||
if cactus.min_cut_value == FixedPointWeight::MAX {
|
||||
if graph.num_edges == 0 {
|
||||
cactus.min_cut_value = FixedPointWeight::ZERO;
|
||||
} else {
|
||||
// 2-edge-connected: min cut is at least the minimum degree
|
||||
// weight sum. Compute as total weight / 2 as rough upper bound
|
||||
// or just report the minimum vertex weighted degree.
|
||||
cactus.min_cut_value = Self::min_vertex_weight_degree(graph);
|
||||
}
|
||||
}
|
||||
|
||||
cactus
|
||||
}
|
||||
|
||||
/// Compute bridge weight between two vertices that are in different
|
||||
/// 2-edge-connected components.
|
||||
fn compute_bridge_weight(graph: &CompactGraph, v: u16, p: u16) -> FixedPointWeight {
|
||||
// Find the edge between v and p and return its weight
|
||||
if let Some(eid) = graph.find_edge(v, p) {
|
||||
FixedPointWeight::from_u16_weight(graph.edges[eid as usize].weight)
|
||||
} else {
|
||||
FixedPointWeight::ONE
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute minimum vertex weighted degree in the graph.
|
||||
fn min_vertex_weight_degree(graph: &CompactGraph) -> FixedPointWeight {
|
||||
let mut min_weight = FixedPointWeight::MAX;
|
||||
|
||||
for v in 0..MAX_SHARD_VERTICES {
|
||||
if !graph.vertices[v].is_active() || graph.vertices[v].degree == 0 {
|
||||
continue;
|
||||
}
|
||||
let mut weight_sum = FixedPointWeight::ZERO;
|
||||
let neighbors = graph.neighbors(v as u16);
|
||||
for adj in neighbors {
|
||||
let eid = adj.edge_id as usize;
|
||||
if eid < graph.edges.len() && graph.edges[eid].is_active() {
|
||||
weight_sum = weight_sum
|
||||
.saturating_add(FixedPointWeight::from_u16_weight(graph.edges[eid].weight));
|
||||
}
|
||||
}
|
||||
if weight_sum < min_weight {
|
||||
min_weight = weight_sum;
|
||||
}
|
||||
}
|
||||
|
||||
if min_weight == FixedPointWeight::MAX {
|
||||
FixedPointWeight::ZERO
|
||||
} else {
|
||||
min_weight
|
||||
}
|
||||
}
|
||||
|
||||
/// Derive the canonical (lex-smallest) partition from this cactus.
|
||||
///
|
||||
/// Finds the minimum-weight edge in the cactus, removes it to create
|
||||
/// two subtrees, and assigns the subtree with the lex-smallest vertex
|
||||
/// set to side A. Ties are broken by selecting the edge whose removal
|
||||
/// yields the lex-smallest side-A bitset.
|
||||
pub fn canonical_partition(&self) -> CanonicalPartition {
|
||||
let mut best = CanonicalPartition::empty();
|
||||
|
||||
if self.n_nodes <= 1 {
|
||||
// Trivial: all vertices on side A
|
||||
best.cardinality_a = self.n_nodes;
|
||||
best.cut_value = FixedPointWeight::ZERO;
|
||||
best.compute_hash();
|
||||
return best;
|
||||
}
|
||||
|
||||
// Find the minimum-weight cactus edge. For each non-root node whose
|
||||
// edge to its parent has weight == min_cut_value, compute the
|
||||
// resulting partition and keep the lex-smallest.
|
||||
let mut found = false;
|
||||
|
||||
for i in 0..self.n_nodes as usize {
|
||||
let node = &self.nodes[i];
|
||||
if node.parent == CactusNode::NO_PARENT {
|
||||
continue; // Root has no parent edge
|
||||
}
|
||||
if node.weight_to_parent != self.min_cut_value {
|
||||
continue; // Not a minimum edge
|
||||
}
|
||||
|
||||
// Removing this edge splits the cactus into:
|
||||
// subtree rooted at node i vs everything else
|
||||
let mut candidate = CanonicalPartition::empty();
|
||||
candidate.cut_value = self.min_cut_value;
|
||||
|
||||
// Mark the subtree rooted at node i as side B
|
||||
self.mark_subtree(i as u16, &mut candidate);
|
||||
|
||||
// Count cardinalities
|
||||
candidate.recount();
|
||||
|
||||
// Ensure canonical orientation: side A should have lex-smallest
|
||||
// vertex set. If side B is lex-smaller, flip.
|
||||
if !candidate.is_canonical() {
|
||||
candidate.flip();
|
||||
}
|
||||
|
||||
candidate.compute_hash();
|
||||
|
||||
if !found || candidate.side < best.side {
|
||||
best = candidate;
|
||||
found = true;
|
||||
}
|
||||
}
|
||||
|
||||
if !found {
|
||||
best.compute_hash();
|
||||
}
|
||||
|
||||
best
|
||||
}
|
||||
|
||||
/// Mark all nodes in the subtree rooted at `start` to side B.
|
||||
fn mark_subtree(&self, start: u16, partition: &mut CanonicalPartition) {
|
||||
// The cactus tree has parent pointers, so we find all nodes
|
||||
// whose ancestor chain leads to `start` (before reaching the root
|
||||
// or a node not descended from `start`).
|
||||
partition.set_side(self.nodes[start as usize].id, true);
|
||||
|
||||
for i in 0..self.n_nodes as usize {
|
||||
if i == start as usize {
|
||||
continue;
|
||||
}
|
||||
// Walk ancestor chain to see if this node is in start's subtree
|
||||
let mut cur = i as u16;
|
||||
let mut in_subtree = false;
|
||||
let mut steps = 0u16;
|
||||
while cur != CactusNode::NO_PARENT && steps < 256 {
|
||||
if cur == start {
|
||||
in_subtree = true;
|
||||
break;
|
||||
}
|
||||
cur = self.nodes[cur as usize].parent;
|
||||
steps += 1;
|
||||
}
|
||||
if in_subtree {
|
||||
partition.set_side(self.nodes[i].id, true);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute a 16-bit digest of the cactus structure for embedding
|
||||
/// in the witness fragment.
|
||||
pub fn digest(&self) -> u16 {
|
||||
let mut hash: u32 = 0x811c9dc5;
|
||||
for i in 0..self.n_nodes as usize {
|
||||
let node = &self.nodes[i];
|
||||
hash ^= node.id as u32;
|
||||
hash = hash.wrapping_mul(0x01000193);
|
||||
hash ^= node.parent as u32;
|
||||
hash = hash.wrapping_mul(0x01000193);
|
||||
hash ^= node.weight_to_parent.0;
|
||||
hash = hash.wrapping_mul(0x01000193);
|
||||
}
|
||||
(hash & 0xFFFF) as u16
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Canonical partition
|
||||
// ============================================================================
|
||||
|
||||
/// A canonical two-way partition of vertices into sides A and B.
|
||||
///
|
||||
/// The bitset encodes 256 vertices (1 bit each = 32 bytes). A cleared
|
||||
/// bit means side A, a set bit means side B. The canonical orientation
|
||||
/// guarantees that side A contains the lex-smallest vertex set.
|
||||
#[derive(Debug, Copy, Clone)]
|
||||
#[repr(C)]
|
||||
pub struct CanonicalPartition {
|
||||
/// Bitset: 256 vertices, 1 bit each (0 = side A, 1 = side B)
|
||||
pub side: [u8; 32],
|
||||
/// Number of vertices on side A
|
||||
pub cardinality_a: u16,
|
||||
/// Number of vertices on side B
|
||||
pub cardinality_b: u16,
|
||||
/// Cut value (weight of edges crossing the partition)
|
||||
pub cut_value: FixedPointWeight,
|
||||
/// 32-bit FNV-1a hash of the `side` bitset
|
||||
pub canonical_hash: [u8; 4],
|
||||
}
|
||||
|
||||
impl CanonicalPartition {
|
||||
/// Create an empty partition (all vertices on side A)
|
||||
#[inline]
|
||||
pub const fn empty() -> Self {
|
||||
Self {
|
||||
side: [0u8; 32],
|
||||
cardinality_a: 0,
|
||||
cardinality_b: 0,
|
||||
cut_value: FixedPointWeight::ZERO,
|
||||
canonical_hash: [0u8; 4],
|
||||
}
|
||||
}
|
||||
|
||||
/// Set which side a vertex belongs to.
|
||||
///
|
||||
/// `side_b = false` means side A, `side_b = true` means side B.
|
||||
#[inline]
|
||||
pub fn set_side(&mut self, vertex: u16, side_b: bool) {
|
||||
if vertex >= 256 {
|
||||
return;
|
||||
}
|
||||
let byte_idx = (vertex / 8) as usize;
|
||||
let bit_idx = vertex % 8;
|
||||
if side_b {
|
||||
self.side[byte_idx] |= 1 << bit_idx;
|
||||
} else {
|
||||
self.side[byte_idx] &= !(1 << bit_idx);
|
||||
}
|
||||
}
|
||||
|
||||
/// Get which side a vertex belongs to (false = A, true = B).
|
||||
#[inline]
|
||||
pub fn get_side(&self, vertex: u16) -> bool {
|
||||
if vertex >= 256 {
|
||||
return false;
|
||||
}
|
||||
let byte_idx = (vertex / 8) as usize;
|
||||
let bit_idx = vertex % 8;
|
||||
(self.side[byte_idx] >> bit_idx) & 1 != 0
|
||||
}
|
||||
|
||||
/// Compute the FNV-1a hash of the side bitset.
|
||||
pub fn compute_hash(&mut self) {
|
||||
self.canonical_hash = fnv1a_hash(&self.side);
|
||||
}
|
||||
|
||||
/// Check if this partition is in canonical orientation.
|
||||
///
|
||||
/// Canonical means: side A (the cleared bits) represents the
|
||||
/// lex-smallest vertex set. Equivalently, the first set bit in
|
||||
/// the bitset must be 1 (vertex 0 is on side A) OR, if vertex 0
|
||||
/// is on side B, we should flip.
|
||||
///
|
||||
/// More precisely: the complement of `side` (i.e. the A-set bitset)
|
||||
/// must be lex-smaller-or-equal to `side` (the B-set bitset).
|
||||
pub fn is_canonical(&self) -> bool {
|
||||
// Compare side vs. its complement byte-by-byte.
|
||||
// The complement represents side-A. If complement < side, canonical.
|
||||
// If complement > side, not canonical (should flip).
|
||||
// If equal, canonical by convention.
|
||||
for i in 0..32 {
|
||||
let complement = !self.side[i];
|
||||
if complement < self.side[i] {
|
||||
return true;
|
||||
}
|
||||
if complement > self.side[i] {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
true // Equal (symmetric partition)
|
||||
}
|
||||
|
||||
/// Flip the partition so that side A and side B swap.
|
||||
pub fn flip(&mut self) {
|
||||
for i in 0..32 {
|
||||
self.side[i] = !self.side[i];
|
||||
}
|
||||
let tmp = self.cardinality_a;
|
||||
self.cardinality_a = self.cardinality_b;
|
||||
self.cardinality_b = tmp;
|
||||
}
|
||||
|
||||
/// Recount cardinalities from the bitset.
|
||||
pub fn recount(&mut self) {
|
||||
let mut count_b: u16 = 0;
|
||||
for i in 0..32 {
|
||||
count_b += self.side[i].count_ones() as u16;
|
||||
}
|
||||
self.cardinality_b = count_b;
|
||||
// cardinality_a is total vertices minus B, but we only know
|
||||
// about the vertices that were explicitly placed. We approximate
|
||||
// with 256 - B here; the caller may adjust.
|
||||
self.cardinality_a = 256u16.saturating_sub(count_b);
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Canonical witness fragment
|
||||
// ============================================================================
|
||||
|
||||
/// Canonical witness fragment (16 bytes, same as `WitnessFragment`).
|
||||
///
|
||||
/// Extends the original witness fragment with pseudo-deterministic
|
||||
/// partition information derived from the cactus tree.
|
||||
#[derive(Debug, Copy, Clone, Default)]
|
||||
#[repr(C, align(16))]
|
||||
pub struct CanonicalWitnessFragment {
|
||||
/// Tile ID (0-255)
|
||||
pub tile_id: u8,
|
||||
/// Truncated epoch (tick & 0xFF)
|
||||
pub epoch: u8,
|
||||
/// Vertices on side A of the canonical partition
|
||||
pub cardinality_a: u16,
|
||||
/// Vertices on side B of the canonical partition
|
||||
pub cardinality_b: u16,
|
||||
/// Cut value (original weight format, truncated)
|
||||
pub cut_value: u16,
|
||||
/// FNV-1a hash of the canonical partition bitset
|
||||
pub canonical_hash: [u8; 4],
|
||||
/// Number of boundary edges
|
||||
pub boundary_edges: u16,
|
||||
/// Truncated hash of the cactus structure
|
||||
pub cactus_digest: u16,
|
||||
}
|
||||
|
||||
// Compile-time size assertion
|
||||
const _: () = assert!(
|
||||
size_of::<CanonicalWitnessFragment>() == 16,
|
||||
"CanonicalWitnessFragment must be exactly 16 bytes"
|
||||
);
|
||||
|
||||
// ============================================================================
|
||||
// FNV-1a hash (no_std, no allocation)
|
||||
// ============================================================================
|
||||
|
||||
/// Compute a 32-bit FNV-1a hash of the given byte slice.
|
||||
///
|
||||
/// FNV-1a is a simple, fast, non-cryptographic hash with good
|
||||
/// distribution properties. It is fully deterministic and portable.
|
||||
#[inline]
|
||||
pub fn fnv1a_hash(data: &[u8]) -> [u8; 4] {
|
||||
let mut hash: u32 = 0x811c9dc5; // FNV offset basis
|
||||
for &byte in data {
|
||||
hash ^= byte as u32;
|
||||
hash = hash.wrapping_mul(0x01000193); // FNV prime
|
||||
}
|
||||
hash.to_le_bytes()
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Tests
|
||||
// ============================================================================
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::shard::CompactGraph;
|
||||
use crate::TileState;
|
||||
use core::mem::size_of;
|
||||
|
||||
#[test]
|
||||
fn test_fixed_point_weight_ordering() {
|
||||
let a = FixedPointWeight(100);
|
||||
let b = FixedPointWeight(200);
|
||||
let c = FixedPointWeight(100);
|
||||
|
||||
assert!(a < b);
|
||||
assert!(b > a);
|
||||
assert_eq!(a, c);
|
||||
assert!(a <= c);
|
||||
assert!(a >= c);
|
||||
|
||||
// Check from_u16_weight ordering
|
||||
let w1 = FixedPointWeight::from_u16_weight(50);
|
||||
let w2 = FixedPointWeight::from_u16_weight(100);
|
||||
assert!(w1 < w2);
|
||||
|
||||
// Saturating add
|
||||
let sum = w1.saturating_add(w2);
|
||||
assert_eq!(sum, FixedPointWeight((50u32 << 8) + (100u32 << 8)));
|
||||
|
||||
// Saturating add at max
|
||||
let max_sum = FixedPointWeight::MAX.saturating_add(FixedPointWeight::ONE);
|
||||
assert_eq!(max_sum, FixedPointWeight::MAX);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_canonical_partition_determinism() {
|
||||
// Build the same graph twice, verify same partition hash
|
||||
let build_graph = || {
|
||||
let mut g = CompactGraph::new();
|
||||
g.add_edge(0, 1, 100);
|
||||
g.add_edge(1, 2, 100);
|
||||
g.add_edge(2, 3, 100);
|
||||
g.add_edge(3, 0, 100);
|
||||
g.add_edge(0, 2, 50); // Diagonal, lighter weight
|
||||
g.recompute_components();
|
||||
g
|
||||
};
|
||||
|
||||
let g1 = build_graph();
|
||||
let g2 = build_graph();
|
||||
|
||||
let c1 = ArenaCactus::build_from_compact_graph(&g1);
|
||||
let c2 = ArenaCactus::build_from_compact_graph(&g2);
|
||||
|
||||
let p1 = c1.canonical_partition();
|
||||
let p2 = c2.canonical_partition();
|
||||
|
||||
assert_eq!(p1.canonical_hash, p2.canonical_hash);
|
||||
assert_eq!(p1.side, p2.side);
|
||||
assert_eq!(p1.cut_value, p2.cut_value);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_fnv1a_known_values() {
|
||||
// Empty input
|
||||
let h0 = fnv1a_hash(&[]);
|
||||
assert_eq!(
|
||||
u32::from_le_bytes(h0),
|
||||
0x811c9dc5,
|
||||
"FNV-1a of empty should be the offset basis"
|
||||
);
|
||||
|
||||
// Single zero byte
|
||||
let h1 = fnv1a_hash(&[0]);
|
||||
let expected = 0x811c9dc5u32 ^ 0;
|
||||
let expected = expected.wrapping_mul(0x01000193);
|
||||
assert_eq!(u32::from_le_bytes(h1), expected);
|
||||
|
||||
// Determinism: same input -> same output
|
||||
let data = [1, 2, 3, 4, 5, 6, 7, 8];
|
||||
let a = fnv1a_hash(&data);
|
||||
let b = fnv1a_hash(&data);
|
||||
assert_eq!(a, b);
|
||||
|
||||
// Different input -> (almost certainly) different output
|
||||
let c = fnv1a_hash(&[8, 7, 6, 5, 4, 3, 2, 1]);
|
||||
assert_ne!(a, c);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_arena_cactus_simple_triangle() {
|
||||
let mut g = CompactGraph::new();
|
||||
g.add_edge(0, 1, 100);
|
||||
g.add_edge(1, 2, 100);
|
||||
g.add_edge(2, 0, 100);
|
||||
g.recompute_components();
|
||||
|
||||
let cactus = ArenaCactus::build_from_compact_graph(&g);
|
||||
|
||||
// A triangle is 2-edge-connected, so the cactus should have
|
||||
// a single node (all 3 vertices collapsed into one component).
|
||||
assert!(
|
||||
cactus.n_nodes >= 1,
|
||||
"Triangle cactus should have at least 1 node"
|
||||
);
|
||||
|
||||
// The partition should be trivial since there is only one component
|
||||
let partition = cactus.canonical_partition();
|
||||
partition.canonical_hash; // Just ensure it doesn't panic
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_canonical_witness_fragment_size() {
|
||||
assert_eq!(
|
||||
size_of::<CanonicalWitnessFragment>(),
|
||||
16,
|
||||
"CanonicalWitnessFragment must be exactly 16 bytes"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_canonical_witness_reproducibility() {
|
||||
// Build two identical tile states and verify they produce the
|
||||
// same canonical witness fragment.
|
||||
let build_tile = || {
|
||||
let mut tile = TileState::new(42);
|
||||
tile.ingest_delta(&crate::delta::Delta::edge_add(0, 1, 100));
|
||||
tile.ingest_delta(&crate::delta::Delta::edge_add(1, 2, 100));
|
||||
tile.ingest_delta(&crate::delta::Delta::edge_add(2, 3, 200));
|
||||
tile.ingest_delta(&crate::delta::Delta::edge_add(3, 0, 200));
|
||||
tile.tick(10);
|
||||
tile
|
||||
};
|
||||
|
||||
let t1 = build_tile();
|
||||
let t2 = build_tile();
|
||||
|
||||
let w1 = t1.canonical_witness();
|
||||
let w2 = t2.canonical_witness();
|
||||
|
||||
assert_eq!(w1.tile_id, w2.tile_id);
|
||||
assert_eq!(w1.epoch, w2.epoch);
|
||||
assert_eq!(w1.cardinality_a, w2.cardinality_a);
|
||||
assert_eq!(w1.cardinality_b, w2.cardinality_b);
|
||||
assert_eq!(w1.cut_value, w2.cut_value);
|
||||
assert_eq!(w1.canonical_hash, w2.canonical_hash);
|
||||
assert_eq!(w1.boundary_edges, w2.boundary_edges);
|
||||
assert_eq!(w1.cactus_digest, w2.cactus_digest);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_partition_set_get_side() {
|
||||
let mut p = CanonicalPartition::empty();
|
||||
|
||||
// All on side A initially
|
||||
for v in 0..256u16 {
|
||||
assert!(!p.get_side(v), "vertex {} should be on side A", v);
|
||||
}
|
||||
|
||||
// Set some to side B
|
||||
p.set_side(0, true);
|
||||
p.set_side(7, true);
|
||||
p.set_side(8, true);
|
||||
p.set_side(255, true);
|
||||
|
||||
assert!(p.get_side(0));
|
||||
assert!(p.get_side(7));
|
||||
assert!(p.get_side(8));
|
||||
assert!(p.get_side(255));
|
||||
assert!(!p.get_side(1));
|
||||
assert!(!p.get_side(254));
|
||||
|
||||
// Clear
|
||||
p.set_side(0, false);
|
||||
assert!(!p.get_side(0));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_partition_flip() {
|
||||
let mut p = CanonicalPartition::empty();
|
||||
p.set_side(0, true);
|
||||
p.set_side(1, true);
|
||||
p.cardinality_a = 254;
|
||||
p.cardinality_b = 2;
|
||||
|
||||
p.flip();
|
||||
|
||||
assert!(!p.get_side(0));
|
||||
assert!(!p.get_side(1));
|
||||
assert!(p.get_side(2));
|
||||
assert_eq!(p.cardinality_a, 2);
|
||||
assert_eq!(p.cardinality_b, 254);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_empty_graph_cactus() {
|
||||
let g = CompactGraph::new();
|
||||
let cactus = ArenaCactus::build_from_compact_graph(&g);
|
||||
assert_eq!(cactus.n_nodes, 0);
|
||||
assert_eq!(cactus.min_cut_value, FixedPointWeight::ZERO);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_single_edge_cactus() {
|
||||
let mut g = CompactGraph::new();
|
||||
g.add_edge(0, 1, 150);
|
||||
g.recompute_components();
|
||||
|
||||
let cactus = ArenaCactus::build_from_compact_graph(&g);
|
||||
assert!(
|
||||
cactus.n_nodes >= 2,
|
||||
"Single edge should have 2 cactus nodes"
|
||||
);
|
||||
|
||||
let partition = cactus.canonical_partition();
|
||||
// One vertex on each side
|
||||
assert!(
|
||||
partition.cardinality_b >= 1,
|
||||
"Should have at least 1 vertex on side B"
|
||||
);
|
||||
}
|
||||
}
|
||||
464
crates/cognitum-gate-kernel/src/delta.rs
Normal file
464
crates/cognitum-gate-kernel/src/delta.rs
Normal file
@@ -0,0 +1,464 @@
|
||||
//! Delta types for incremental graph updates
|
||||
//!
|
||||
//! Defines the message types that tiles receive from the coordinator.
|
||||
//! All types are `#[repr(C)]` for FFI compatibility and fixed-size
|
||||
//! for deterministic memory allocation.
|
||||
|
||||
#![allow(missing_docs)]
|
||||
|
||||
use core::mem::size_of;
|
||||
|
||||
/// Compact vertex identifier (16-bit for tile-local addressing)
|
||||
pub type TileVertexId = u16;
|
||||
|
||||
/// Compact edge identifier (16-bit for tile-local addressing)
|
||||
pub type TileEdgeId = u16;
|
||||
|
||||
/// Fixed-point weight (16-bit, 0.01 precision)
|
||||
/// Actual weight = raw_weight / 100.0
|
||||
pub type FixedWeight = u16;
|
||||
|
||||
/// Convert fixed-point weight to f32
|
||||
#[inline(always)]
|
||||
pub const fn weight_to_f32(w: FixedWeight) -> f32 {
|
||||
(w as f32) / 100.0
|
||||
}
|
||||
|
||||
/// Convert f32 weight to fixed-point (saturating)
|
||||
#[inline(always)]
|
||||
pub const fn f32_to_weight(w: f32) -> FixedWeight {
|
||||
let scaled = (w * 100.0) as i32;
|
||||
if scaled < 0 {
|
||||
0
|
||||
} else if scaled > 65535 {
|
||||
65535
|
||||
} else {
|
||||
scaled as u16
|
||||
}
|
||||
}
|
||||
|
||||
/// Delta operation tag
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
#[repr(u8)]
|
||||
pub enum DeltaTag {
|
||||
/// No operation (padding/sentinel)
|
||||
Nop = 0,
|
||||
/// Add an edge to the graph
|
||||
EdgeAdd = 1,
|
||||
/// Remove an edge from the graph
|
||||
EdgeRemove = 2,
|
||||
/// Update the weight of an existing edge
|
||||
WeightUpdate = 3,
|
||||
/// Observation for evidence accumulation
|
||||
Observation = 4,
|
||||
/// Batch boundary marker
|
||||
BatchEnd = 5,
|
||||
/// Checkpoint request
|
||||
Checkpoint = 6,
|
||||
/// Reset tile state
|
||||
Reset = 7,
|
||||
}
|
||||
|
||||
impl From<u8> for DeltaTag {
|
||||
fn from(v: u8) -> Self {
|
||||
match v {
|
||||
1 => DeltaTag::EdgeAdd,
|
||||
2 => DeltaTag::EdgeRemove,
|
||||
3 => DeltaTag::WeightUpdate,
|
||||
4 => DeltaTag::Observation,
|
||||
5 => DeltaTag::BatchEnd,
|
||||
6 => DeltaTag::Checkpoint,
|
||||
7 => DeltaTag::Reset,
|
||||
_ => DeltaTag::Nop,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Edge addition delta
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C)]
|
||||
pub struct EdgeAdd {
|
||||
/// Source vertex (tile-local ID)
|
||||
pub source: TileVertexId,
|
||||
/// Target vertex (tile-local ID)
|
||||
pub target: TileVertexId,
|
||||
/// Edge weight (fixed-point)
|
||||
pub weight: FixedWeight,
|
||||
/// Edge flags (reserved for future use)
|
||||
pub flags: u16,
|
||||
}
|
||||
|
||||
impl EdgeAdd {
|
||||
/// Create a new edge addition
|
||||
#[inline]
|
||||
pub const fn new(source: TileVertexId, target: TileVertexId, weight: FixedWeight) -> Self {
|
||||
Self {
|
||||
source,
|
||||
target,
|
||||
weight,
|
||||
flags: 0,
|
||||
}
|
||||
}
|
||||
|
||||
/// Create from f32 weight
|
||||
#[inline]
|
||||
pub const fn with_f32_weight(source: TileVertexId, target: TileVertexId, weight: f32) -> Self {
|
||||
Self::new(source, target, f32_to_weight(weight))
|
||||
}
|
||||
}
|
||||
|
||||
/// Edge removal delta
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C)]
|
||||
pub struct EdgeRemove {
|
||||
/// Source vertex (tile-local ID)
|
||||
pub source: TileVertexId,
|
||||
/// Target vertex (tile-local ID)
|
||||
pub target: TileVertexId,
|
||||
/// Reserved padding for alignment
|
||||
pub _reserved: u32,
|
||||
}
|
||||
|
||||
impl EdgeRemove {
|
||||
/// Create a new edge removal
|
||||
#[inline]
|
||||
pub const fn new(source: TileVertexId, target: TileVertexId) -> Self {
|
||||
Self {
|
||||
source,
|
||||
target,
|
||||
_reserved: 0,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Weight update delta
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C)]
|
||||
pub struct WeightUpdate {
|
||||
/// Source vertex (tile-local ID)
|
||||
pub source: TileVertexId,
|
||||
/// Target vertex (tile-local ID)
|
||||
pub target: TileVertexId,
|
||||
/// New weight (fixed-point)
|
||||
pub new_weight: FixedWeight,
|
||||
/// Delta mode: 0 = absolute, 1 = relative add, 2 = relative multiply
|
||||
pub mode: u8,
|
||||
/// Reserved padding
|
||||
pub _reserved: u8,
|
||||
}
|
||||
|
||||
impl WeightUpdate {
|
||||
/// Absolute weight update mode
|
||||
pub const MODE_ABSOLUTE: u8 = 0;
|
||||
/// Relative addition mode
|
||||
pub const MODE_ADD: u8 = 1;
|
||||
/// Relative multiply mode (fixed-point: value/100)
|
||||
pub const MODE_MULTIPLY: u8 = 2;
|
||||
|
||||
/// Create an absolute weight update
|
||||
#[inline]
|
||||
pub const fn absolute(source: TileVertexId, target: TileVertexId, weight: FixedWeight) -> Self {
|
||||
Self {
|
||||
source,
|
||||
target,
|
||||
new_weight: weight,
|
||||
mode: Self::MODE_ABSOLUTE,
|
||||
_reserved: 0,
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a relative weight addition
|
||||
#[inline]
|
||||
pub const fn add(source: TileVertexId, target: TileVertexId, delta: FixedWeight) -> Self {
|
||||
Self {
|
||||
source,
|
||||
target,
|
||||
new_weight: delta,
|
||||
mode: Self::MODE_ADD,
|
||||
_reserved: 0,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Observation for evidence accumulation
|
||||
///
|
||||
/// Represents a measurement or event that affects the e-value calculation.
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C)]
|
||||
pub struct Observation {
|
||||
/// Vertex or region this observation applies to
|
||||
pub vertex: TileVertexId,
|
||||
/// Observation type/category
|
||||
pub obs_type: u8,
|
||||
/// Observation flags
|
||||
pub flags: u8,
|
||||
/// Observation value (interpretation depends on obs_type)
|
||||
pub value: u32,
|
||||
}
|
||||
|
||||
impl Observation {
|
||||
/// Observation type: connectivity evidence
|
||||
pub const TYPE_CONNECTIVITY: u8 = 0;
|
||||
/// Observation type: cut membership evidence
|
||||
pub const TYPE_CUT_MEMBERSHIP: u8 = 1;
|
||||
/// Observation type: flow evidence
|
||||
pub const TYPE_FLOW: u8 = 2;
|
||||
/// Observation type: witness evidence
|
||||
pub const TYPE_WITNESS: u8 = 3;
|
||||
|
||||
/// Create a connectivity observation
|
||||
#[inline]
|
||||
pub const fn connectivity(vertex: TileVertexId, connected: bool) -> Self {
|
||||
Self {
|
||||
vertex,
|
||||
obs_type: Self::TYPE_CONNECTIVITY,
|
||||
flags: if connected { 1 } else { 0 },
|
||||
value: 0,
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a cut membership observation
|
||||
#[inline]
|
||||
pub const fn cut_membership(vertex: TileVertexId, side: u8, confidence: u16) -> Self {
|
||||
Self {
|
||||
vertex,
|
||||
obs_type: Self::TYPE_CUT_MEMBERSHIP,
|
||||
flags: side,
|
||||
value: confidence as u32,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Unified delta message (8 bytes, cache-aligned for batching)
|
||||
///
|
||||
/// Tagged union for all delta types. The layout is optimized for
|
||||
/// WASM memory access patterns.
|
||||
#[derive(Clone, Copy)]
|
||||
#[repr(C)]
|
||||
pub union DeltaPayload {
|
||||
/// Edge addition payload
|
||||
pub edge_add: EdgeAdd,
|
||||
/// Edge removal payload
|
||||
pub edge_remove: EdgeRemove,
|
||||
/// Weight update payload
|
||||
pub weight_update: WeightUpdate,
|
||||
/// Observation payload
|
||||
pub observation: Observation,
|
||||
/// Raw bytes for custom payloads
|
||||
pub raw: [u8; 8],
|
||||
}
|
||||
|
||||
impl Default for DeltaPayload {
|
||||
fn default() -> Self {
|
||||
Self { raw: [0u8; 8] }
|
||||
}
|
||||
}
|
||||
|
||||
/// Complete delta message with tag
|
||||
#[derive(Clone, Copy)]
|
||||
#[repr(C, align(16))]
|
||||
pub struct Delta {
|
||||
/// Delta operation tag
|
||||
pub tag: DeltaTag,
|
||||
/// Sequence number for ordering
|
||||
pub sequence: u8,
|
||||
/// Source tile ID (for cross-tile deltas)
|
||||
pub source_tile: u8,
|
||||
/// Reserved for future use
|
||||
pub _reserved: u8,
|
||||
/// Timestamp (lower 32 bits of tick counter)
|
||||
pub timestamp: u32,
|
||||
/// Delta payload
|
||||
pub payload: DeltaPayload,
|
||||
}
|
||||
|
||||
impl Default for Delta {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
tag: DeltaTag::Nop,
|
||||
sequence: 0,
|
||||
source_tile: 0,
|
||||
_reserved: 0,
|
||||
timestamp: 0,
|
||||
payload: DeltaPayload::default(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Delta {
|
||||
/// Create a NOP delta
|
||||
#[inline]
|
||||
pub const fn nop() -> Self {
|
||||
Self {
|
||||
tag: DeltaTag::Nop,
|
||||
sequence: 0,
|
||||
source_tile: 0,
|
||||
_reserved: 0,
|
||||
timestamp: 0,
|
||||
payload: DeltaPayload { raw: [0u8; 8] },
|
||||
}
|
||||
}
|
||||
|
||||
/// Create an edge add delta
|
||||
#[inline]
|
||||
pub fn edge_add(source: TileVertexId, target: TileVertexId, weight: FixedWeight) -> Self {
|
||||
Self {
|
||||
tag: DeltaTag::EdgeAdd,
|
||||
sequence: 0,
|
||||
source_tile: 0,
|
||||
_reserved: 0,
|
||||
timestamp: 0,
|
||||
payload: DeltaPayload {
|
||||
edge_add: EdgeAdd::new(source, target, weight),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/// Create an edge remove delta
|
||||
#[inline]
|
||||
pub fn edge_remove(source: TileVertexId, target: TileVertexId) -> Self {
|
||||
Self {
|
||||
tag: DeltaTag::EdgeRemove,
|
||||
sequence: 0,
|
||||
source_tile: 0,
|
||||
_reserved: 0,
|
||||
timestamp: 0,
|
||||
payload: DeltaPayload {
|
||||
edge_remove: EdgeRemove::new(source, target),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a weight update delta
|
||||
#[inline]
|
||||
pub fn weight_update(source: TileVertexId, target: TileVertexId, weight: FixedWeight) -> Self {
|
||||
Self {
|
||||
tag: DeltaTag::WeightUpdate,
|
||||
sequence: 0,
|
||||
source_tile: 0,
|
||||
_reserved: 0,
|
||||
timestamp: 0,
|
||||
payload: DeltaPayload {
|
||||
weight_update: WeightUpdate::absolute(source, target, weight),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/// Create an observation delta
|
||||
#[inline]
|
||||
pub fn observation(obs: Observation) -> Self {
|
||||
Self {
|
||||
tag: DeltaTag::Observation,
|
||||
sequence: 0,
|
||||
source_tile: 0,
|
||||
_reserved: 0,
|
||||
timestamp: 0,
|
||||
payload: DeltaPayload { observation: obs },
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a batch end marker
|
||||
#[inline]
|
||||
pub const fn batch_end() -> Self {
|
||||
Self {
|
||||
tag: DeltaTag::BatchEnd,
|
||||
sequence: 0,
|
||||
source_tile: 0,
|
||||
_reserved: 0,
|
||||
timestamp: 0,
|
||||
payload: DeltaPayload { raw: [0u8; 8] },
|
||||
}
|
||||
}
|
||||
|
||||
/// Check if this is a NOP
|
||||
#[inline]
|
||||
pub const fn is_nop(&self) -> bool {
|
||||
matches!(self.tag, DeltaTag::Nop)
|
||||
}
|
||||
|
||||
/// Get the edge add payload (unsafe: caller must verify tag)
|
||||
#[inline]
|
||||
pub unsafe fn get_edge_add(&self) -> &EdgeAdd {
|
||||
unsafe { &self.payload.edge_add }
|
||||
}
|
||||
|
||||
/// Get the edge remove payload (unsafe: caller must verify tag)
|
||||
#[inline]
|
||||
pub unsafe fn get_edge_remove(&self) -> &EdgeRemove {
|
||||
unsafe { &self.payload.edge_remove }
|
||||
}
|
||||
|
||||
/// Get the weight update payload (unsafe: caller must verify tag)
|
||||
#[inline]
|
||||
pub unsafe fn get_weight_update(&self) -> &WeightUpdate {
|
||||
unsafe { &self.payload.weight_update }
|
||||
}
|
||||
|
||||
/// Get the observation payload (unsafe: caller must verify tag)
|
||||
#[inline]
|
||||
pub unsafe fn get_observation(&self) -> &Observation {
|
||||
unsafe { &self.payload.observation }
|
||||
}
|
||||
}
|
||||
|
||||
// Compile-time size assertions
|
||||
const _: () = assert!(size_of::<EdgeAdd>() == 8, "EdgeAdd must be 8 bytes");
|
||||
const _: () = assert!(size_of::<EdgeRemove>() == 8, "EdgeRemove must be 8 bytes");
|
||||
const _: () = assert!(
|
||||
size_of::<WeightUpdate>() == 8,
|
||||
"WeightUpdate must be 8 bytes"
|
||||
);
|
||||
const _: () = assert!(size_of::<Observation>() == 8, "Observation must be 8 bytes");
|
||||
const _: () = assert!(size_of::<Delta>() == 16, "Delta must be 16 bytes");
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_weight_conversion() {
|
||||
assert_eq!(weight_to_f32(100), 1.0);
|
||||
assert_eq!(weight_to_f32(50), 0.5);
|
||||
assert_eq!(weight_to_f32(0), 0.0);
|
||||
|
||||
assert_eq!(f32_to_weight(1.0), 100);
|
||||
assert_eq!(f32_to_weight(0.5), 50);
|
||||
assert_eq!(f32_to_weight(0.0), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_delta_tag_roundtrip() {
|
||||
for i in 0..=7 {
|
||||
let tag = DeltaTag::from(i);
|
||||
assert_eq!(tag as u8, i);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_edge_add_creation() {
|
||||
let ea = EdgeAdd::new(1, 2, 150);
|
||||
assert_eq!(ea.source, 1);
|
||||
assert_eq!(ea.target, 2);
|
||||
assert_eq!(ea.weight, 150);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_delta_edge_add() {
|
||||
let delta = Delta::edge_add(5, 10, 200);
|
||||
assert_eq!(delta.tag, DeltaTag::EdgeAdd);
|
||||
unsafe {
|
||||
let ea = delta.get_edge_add();
|
||||
assert_eq!(ea.source, 5);
|
||||
assert_eq!(ea.target, 10);
|
||||
assert_eq!(ea.weight, 200);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_observation_creation() {
|
||||
let obs = Observation::connectivity(42, true);
|
||||
assert_eq!(obs.vertex, 42);
|
||||
assert_eq!(obs.obs_type, Observation::TYPE_CONNECTIVITY);
|
||||
assert_eq!(obs.flags, 1);
|
||||
}
|
||||
}
|
||||
851
crates/cognitum-gate-kernel/src/evidence.rs
Normal file
851
crates/cognitum-gate-kernel/src/evidence.rs
Normal file
@@ -0,0 +1,851 @@
|
||||
//! Evidence accumulator for anytime-valid coherence gate
|
||||
//!
|
||||
//! Implements sequential testing with e-values for the coherence gate.
|
||||
//! The accumulator maintains running e-value products that can be queried
|
||||
//! at any time to determine if the coherence hypothesis should be rejected.
|
||||
//!
|
||||
//! ## Performance Optimizations
|
||||
//!
|
||||
//! - Pre-computed log threshold constants (avoid runtime log calculations)
|
||||
//! - Fixed-point arithmetic for e-values (numerical stability + performance)
|
||||
//! - `#[inline(always)]` on hot path functions
|
||||
//! - Cache-aligned accumulator structure
|
||||
//! - Branchless observation processing where possible
|
||||
|
||||
#![allow(missing_docs)]
|
||||
|
||||
use crate::delta::{Observation, TileVertexId};
|
||||
use core::mem::size_of;
|
||||
|
||||
/// Maximum number of tracked hypotheses per tile
|
||||
pub const MAX_HYPOTHESES: usize = 16;
|
||||
|
||||
/// Maximum observations in sliding window
|
||||
pub const WINDOW_SIZE: usize = 64;
|
||||
|
||||
/// Fixed-point e-value representation (32-bit, log scale)
|
||||
/// Stored as log2(e-value) * 65536 for numerical stability
|
||||
pub type LogEValue = i32;
|
||||
|
||||
// ============================================================================
|
||||
// PRE-COMPUTED THRESHOLD CONSTANTS (avoid runtime log calculations)
|
||||
// ============================================================================
|
||||
|
||||
/// log2(20) * 65536 = 282944 (strong evidence threshold: e > 20)
|
||||
/// Pre-computed to avoid runtime log calculation
|
||||
pub const LOG_E_STRONG: LogEValue = 282944;
|
||||
|
||||
/// log2(100) * 65536 = 436906 (very strong evidence threshold: e > 100)
|
||||
pub const LOG_E_VERY_STRONG: LogEValue = 436906;
|
||||
|
||||
/// log2(1.5) * 65536 = 38550 (connectivity positive evidence)
|
||||
pub const LOG_LR_CONNECTIVITY_POS: LogEValue = 38550;
|
||||
|
||||
/// log2(0.5) * 65536 = -65536 (connectivity negative evidence)
|
||||
pub const LOG_LR_CONNECTIVITY_NEG: LogEValue = -65536;
|
||||
|
||||
/// log2(2.0) * 65536 = 65536 (witness positive evidence)
|
||||
pub const LOG_LR_WITNESS_POS: LogEValue = 65536;
|
||||
|
||||
/// log2(0.5) * 65536 = -65536 (witness negative evidence)
|
||||
pub const LOG_LR_WITNESS_NEG: LogEValue = -65536;
|
||||
|
||||
/// Fixed-point scale factor
|
||||
pub const FIXED_SCALE: i32 = 65536;
|
||||
|
||||
// ============================================================================
|
||||
// SIMD-OPTIMIZED E-VALUE AGGREGATION
|
||||
// ============================================================================
|
||||
|
||||
/// Aggregate log e-values using SIMD-friendly parallel lanes
|
||||
///
|
||||
/// This function is optimized for vectorization by processing values
|
||||
/// in parallel lanes, allowing the compiler to generate SIMD instructions.
|
||||
///
|
||||
/// OPTIMIZATION: Uses 4 parallel lanes for 128-bit SIMD (SSE/NEON) or
|
||||
/// 8 lanes for 256-bit SIMD (AVX2). The compiler can auto-vectorize
|
||||
/// this pattern effectively.
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `log_e_values` - Slice of log e-values (fixed-point, 16.16 format)
|
||||
///
|
||||
/// # Returns
|
||||
/// The sum of all log e-values (product in log space)
|
||||
#[inline]
|
||||
pub fn simd_aggregate_log_e(log_e_values: &[LogEValue]) -> i64 {
|
||||
// Use 4 parallel accumulator lanes for 128-bit SIMD
|
||||
// This allows the compiler to vectorize the inner loop
|
||||
let mut lanes = [0i64; 4];
|
||||
|
||||
// Process in chunks of 4 for optimal SIMD usage
|
||||
let chunks = log_e_values.chunks_exact(4);
|
||||
let remainder = chunks.remainder();
|
||||
|
||||
for chunk in chunks {
|
||||
// SAFETY: chunks_exact guarantees 4 elements
|
||||
lanes[0] += chunk[0] as i64;
|
||||
lanes[1] += chunk[1] as i64;
|
||||
lanes[2] += chunk[2] as i64;
|
||||
lanes[3] += chunk[3] as i64;
|
||||
}
|
||||
|
||||
// Handle remainder
|
||||
for (i, &val) in remainder.iter().enumerate() {
|
||||
lanes[i % 4] += val as i64;
|
||||
}
|
||||
|
||||
// Reduce lanes to single value
|
||||
lanes[0] + lanes[1] + lanes[2] + lanes[3]
|
||||
}
|
||||
|
||||
/// Aggregate log e-values using 8 parallel lanes for AVX2
|
||||
///
|
||||
/// OPTIMIZATION: Uses 8 lanes for 256-bit SIMD (AVX2/AVX-512).
|
||||
/// Falls back gracefully on platforms without AVX.
|
||||
#[inline]
|
||||
pub fn simd_aggregate_log_e_wide(log_e_values: &[LogEValue]) -> i64 {
|
||||
// Use 8 parallel accumulator lanes for 256-bit SIMD
|
||||
let mut lanes = [0i64; 8];
|
||||
|
||||
let chunks = log_e_values.chunks_exact(8);
|
||||
let remainder = chunks.remainder();
|
||||
|
||||
for chunk in chunks {
|
||||
// Unrolled for better codegen
|
||||
lanes[0] += chunk[0] as i64;
|
||||
lanes[1] += chunk[1] as i64;
|
||||
lanes[2] += chunk[2] as i64;
|
||||
lanes[3] += chunk[3] as i64;
|
||||
lanes[4] += chunk[4] as i64;
|
||||
lanes[5] += chunk[5] as i64;
|
||||
lanes[6] += chunk[6] as i64;
|
||||
lanes[7] += chunk[7] as i64;
|
||||
}
|
||||
|
||||
// Handle remainder
|
||||
for (i, &val) in remainder.iter().enumerate() {
|
||||
lanes[i % 8] += val as i64;
|
||||
}
|
||||
|
||||
// Tree reduction for lane aggregation
|
||||
let sum_0_3 = lanes[0] + lanes[1] + lanes[2] + lanes[3];
|
||||
let sum_4_7 = lanes[4] + lanes[5] + lanes[6] + lanes[7];
|
||||
sum_0_3 + sum_4_7
|
||||
}
|
||||
|
||||
/// Aggregate mixture e-values for a tile set
|
||||
///
|
||||
/// Computes the product of e-values across tiles using log-space arithmetic
|
||||
/// for numerical stability. This is the key operation for coherence gate
|
||||
/// aggregation.
|
||||
///
|
||||
/// OPTIMIZATION:
|
||||
/// - Uses SIMD-friendly parallel lanes
|
||||
/// - Processes 255 tile e-values efficiently
|
||||
/// - Returns in fixed-point log format for further processing
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `tile_log_e_values` - Array of 255 tile log e-values
|
||||
///
|
||||
/// # Returns
|
||||
/// Aggregated log e-value (can be converted to f32 with log_e_to_f32)
|
||||
#[inline]
|
||||
pub fn aggregate_tile_evidence(tile_log_e_values: &[LogEValue; 255]) -> i64 {
|
||||
simd_aggregate_log_e(tile_log_e_values)
|
||||
}
|
||||
|
||||
/// Convert log e-value to approximate f32
|
||||
///
|
||||
/// OPTIMIZATION: Marked #[inline(always)] for hot path usage
|
||||
#[inline(always)]
|
||||
pub const fn log_e_to_f32(log_e: LogEValue) -> f32 {
|
||||
// log2(e) = log_e / 65536
|
||||
// e = 2^(log_e / 65536)
|
||||
// Approximation for no_std
|
||||
let log2_val = (log_e as f32) / 65536.0;
|
||||
// 2^x approximation using e^(x * ln(2))
|
||||
// For simplicity, we just return the log value scaled
|
||||
log2_val
|
||||
}
|
||||
|
||||
/// Convert f32 e-value to log representation
|
||||
///
|
||||
/// OPTIMIZATION: Early exit for common cases, marked #[inline(always)]
|
||||
#[inline(always)]
|
||||
pub fn f32_to_log_e(e: f32) -> LogEValue {
|
||||
if e <= 0.0 {
|
||||
i32::MIN
|
||||
} else if e == 1.0 {
|
||||
0 // Fast path for neutral evidence
|
||||
} else if e == 2.0 {
|
||||
FIXED_SCALE // Fast path for common LR=2
|
||||
} else if e == 0.5 {
|
||||
-FIXED_SCALE // Fast path for common LR=0.5
|
||||
} else {
|
||||
// log2(e) * 65536
|
||||
let log2_e = libm::log2f(e);
|
||||
(log2_e * 65536.0) as i32
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute log likelihood ratio directly in fixed-point
|
||||
/// Avoids f32 conversion for common cases
|
||||
///
|
||||
/// OPTIMIZATION: Returns pre-computed constants for known observation types
|
||||
#[inline(always)]
|
||||
pub const fn log_lr_for_obs_type(obs_type: u8, flags: u8, value: u16) -> LogEValue {
|
||||
match obs_type {
|
||||
Observation::TYPE_CONNECTIVITY => {
|
||||
if flags != 0 {
|
||||
LOG_LR_CONNECTIVITY_POS
|
||||
} else {
|
||||
LOG_LR_CONNECTIVITY_NEG
|
||||
}
|
||||
}
|
||||
Observation::TYPE_WITNESS => {
|
||||
if flags != 0 {
|
||||
LOG_LR_WITNESS_POS
|
||||
} else {
|
||||
LOG_LR_WITNESS_NEG
|
||||
}
|
||||
}
|
||||
// For other types, return 0 (neutral) - caller should use f32 path
|
||||
_ => 0,
|
||||
}
|
||||
}
|
||||
|
||||
/// Hypothesis state for tracking
|
||||
///
|
||||
/// Size: 16 bytes, aligned for efficient cache access
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
#[repr(C, align(16))]
|
||||
pub struct HypothesisState {
|
||||
/// Current accumulated log e-value (hot field, first for cache)
|
||||
pub log_e_value: LogEValue,
|
||||
/// Number of observations processed
|
||||
pub obs_count: u32,
|
||||
/// Hypothesis ID
|
||||
pub id: u16,
|
||||
/// Target vertex (for vertex-specific hypotheses)
|
||||
pub target: TileVertexId,
|
||||
/// Threshold vertex (for cut hypotheses)
|
||||
pub threshold: TileVertexId,
|
||||
/// Hypothesis type (0 = connectivity, 1 = cut, 2 = flow)
|
||||
pub hyp_type: u8,
|
||||
/// Status flags
|
||||
pub flags: u8,
|
||||
}
|
||||
|
||||
impl Default for HypothesisState {
|
||||
#[inline]
|
||||
fn default() -> Self {
|
||||
Self::new(0, 0)
|
||||
}
|
||||
}
|
||||
|
||||
impl HypothesisState {
|
||||
/// Hypothesis is active
|
||||
pub const FLAG_ACTIVE: u8 = 0x01;
|
||||
/// Hypothesis is rejected (e-value crossed threshold)
|
||||
pub const FLAG_REJECTED: u8 = 0x02;
|
||||
/// Hypothesis evidence is strong (e > 20)
|
||||
pub const FLAG_STRONG: u8 = 0x04;
|
||||
/// Hypothesis evidence is very strong (e > 100)
|
||||
pub const FLAG_VERY_STRONG: u8 = 0x08;
|
||||
|
||||
/// Type: connectivity hypothesis
|
||||
pub const TYPE_CONNECTIVITY: u8 = 0;
|
||||
/// Type: cut membership hypothesis
|
||||
pub const TYPE_CUT: u8 = 1;
|
||||
/// Type: flow hypothesis
|
||||
pub const TYPE_FLOW: u8 = 2;
|
||||
|
||||
/// Create a new hypothesis
|
||||
#[inline(always)]
|
||||
pub const fn new(id: u16, hyp_type: u8) -> Self {
|
||||
Self {
|
||||
log_e_value: 0, // e = 1 (neutral)
|
||||
obs_count: 0,
|
||||
id,
|
||||
target: 0,
|
||||
threshold: 0,
|
||||
hyp_type,
|
||||
flags: Self::FLAG_ACTIVE,
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a connectivity hypothesis for a vertex
|
||||
#[inline(always)]
|
||||
pub const fn connectivity(id: u16, vertex: TileVertexId) -> Self {
|
||||
Self {
|
||||
log_e_value: 0,
|
||||
obs_count: 0,
|
||||
id,
|
||||
target: vertex,
|
||||
threshold: 0,
|
||||
hyp_type: Self::TYPE_CONNECTIVITY,
|
||||
flags: Self::FLAG_ACTIVE,
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a cut membership hypothesis
|
||||
#[inline(always)]
|
||||
pub const fn cut_membership(id: u16, vertex: TileVertexId, threshold: TileVertexId) -> Self {
|
||||
Self {
|
||||
log_e_value: 0,
|
||||
obs_count: 0,
|
||||
id,
|
||||
target: vertex,
|
||||
threshold,
|
||||
hyp_type: Self::TYPE_CUT,
|
||||
flags: Self::FLAG_ACTIVE,
|
||||
}
|
||||
}
|
||||
|
||||
/// Check if hypothesis is active
|
||||
///
|
||||
/// OPTIMIZATION: #[inline(always)] - called in every hypothesis loop
|
||||
#[inline(always)]
|
||||
pub const fn is_active(&self) -> bool {
|
||||
self.flags & Self::FLAG_ACTIVE != 0
|
||||
}
|
||||
|
||||
/// Check if hypothesis is rejected
|
||||
#[inline(always)]
|
||||
pub const fn is_rejected(&self) -> bool {
|
||||
self.flags & Self::FLAG_REJECTED != 0
|
||||
}
|
||||
|
||||
/// Check if hypothesis can be updated (active and not rejected)
|
||||
///
|
||||
/// OPTIMIZATION: Combined check to reduce branch mispredictions
|
||||
#[inline(always)]
|
||||
pub const fn can_update(&self) -> bool {
|
||||
// Active AND not rejected = (flags & ACTIVE) != 0 && (flags & REJECTED) == 0
|
||||
(self.flags & (Self::FLAG_ACTIVE | Self::FLAG_REJECTED)) == Self::FLAG_ACTIVE
|
||||
}
|
||||
|
||||
/// Get e-value as approximate f32 (2^(log_e/65536))
|
||||
#[inline(always)]
|
||||
pub fn e_value_approx(&self) -> f32 {
|
||||
let log2_val = (self.log_e_value as f32) / 65536.0;
|
||||
libm::exp2f(log2_val)
|
||||
}
|
||||
|
||||
/// Update with a new observation (f32 likelihood ratio)
|
||||
/// Returns true if the hypothesis is now rejected
|
||||
///
|
||||
/// OPTIMIZATION: Uses pre-computed threshold constants
|
||||
#[inline]
|
||||
pub fn update(&mut self, likelihood_ratio: f32) -> bool {
|
||||
if !self.can_update() {
|
||||
return self.is_rejected();
|
||||
}
|
||||
|
||||
// Update log e-value: log(e') = log(e) + log(LR)
|
||||
let log_lr = f32_to_log_e(likelihood_ratio);
|
||||
self.update_with_log_lr(log_lr)
|
||||
}
|
||||
|
||||
/// Update with a pre-computed log likelihood ratio (fixed-point)
|
||||
/// Returns true if the hypothesis is now rejected
|
||||
///
|
||||
/// OPTIMIZATION: Avoids f32->log conversion when log_lr is pre-computed
|
||||
#[inline(always)]
|
||||
pub fn update_with_log_lr(&mut self, log_lr: LogEValue) -> bool {
|
||||
self.log_e_value = self.log_e_value.saturating_add(log_lr);
|
||||
self.obs_count += 1;
|
||||
|
||||
// Update strength flags using pre-computed constants
|
||||
// OPTIMIZATION: Single comparison chain with constants
|
||||
if self.log_e_value > LOG_E_VERY_STRONG {
|
||||
self.flags |= Self::FLAG_VERY_STRONG | Self::FLAG_STRONG;
|
||||
} else if self.log_e_value > LOG_E_STRONG {
|
||||
self.flags |= Self::FLAG_STRONG;
|
||||
self.flags &= !Self::FLAG_VERY_STRONG;
|
||||
} else {
|
||||
self.flags &= !(Self::FLAG_STRONG | Self::FLAG_VERY_STRONG);
|
||||
}
|
||||
|
||||
// Check rejection threshold (alpha = 0.05 => e > 20)
|
||||
if self.log_e_value > LOG_E_STRONG {
|
||||
self.flags |= Self::FLAG_REJECTED;
|
||||
return true;
|
||||
}
|
||||
|
||||
false
|
||||
}
|
||||
|
||||
/// Reset the hypothesis
|
||||
#[inline]
|
||||
pub fn reset(&mut self) {
|
||||
self.log_e_value = 0;
|
||||
self.obs_count = 0;
|
||||
self.flags = Self::FLAG_ACTIVE;
|
||||
}
|
||||
}
|
||||
|
||||
/// Observation record for sliding window
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C)]
|
||||
pub struct ObsRecord {
|
||||
/// Observation data
|
||||
pub obs: Observation,
|
||||
/// Timestamp (tick)
|
||||
pub tick: u32,
|
||||
}
|
||||
|
||||
/// Evidence accumulator for tile-local e-value tracking
|
||||
///
|
||||
/// OPTIMIZATION: Cache-line aligned (64 bytes) with hot fields first
|
||||
#[derive(Clone)]
|
||||
#[repr(C, align(64))]
|
||||
pub struct EvidenceAccumulator {
|
||||
// === HOT FIELDS (frequently accessed) ===
|
||||
/// Global accumulated log e-value
|
||||
pub global_log_e: LogEValue,
|
||||
/// Total observations processed
|
||||
pub total_obs: u32,
|
||||
/// Current tick
|
||||
pub current_tick: u32,
|
||||
/// Window head pointer (circular buffer)
|
||||
pub window_head: u16,
|
||||
/// Window count (number of valid entries)
|
||||
pub window_count: u16,
|
||||
/// Number of active hypotheses
|
||||
pub num_hypotheses: u8,
|
||||
/// Reserved padding
|
||||
pub _reserved: [u8; 1],
|
||||
/// Rejected hypothesis count
|
||||
pub rejected_count: u16,
|
||||
/// Status flags
|
||||
pub status: u16,
|
||||
/// Padding to align cold fields
|
||||
_hot_pad: [u8; 40],
|
||||
|
||||
// === COLD FIELDS ===
|
||||
/// Active hypotheses
|
||||
pub hypotheses: [HypothesisState; MAX_HYPOTHESES],
|
||||
/// Sliding window of recent observations
|
||||
pub window: [ObsRecord; WINDOW_SIZE],
|
||||
}
|
||||
|
||||
impl Default for EvidenceAccumulator {
|
||||
#[inline]
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
impl EvidenceAccumulator {
|
||||
/// Status: accumulator is active
|
||||
pub const STATUS_ACTIVE: u16 = 0x0001;
|
||||
/// Status: at least one hypothesis rejected
|
||||
pub const STATUS_HAS_REJECTION: u16 = 0x0002;
|
||||
/// Status: global evidence is significant
|
||||
pub const STATUS_SIGNIFICANT: u16 = 0x0004;
|
||||
|
||||
/// Create a new accumulator
|
||||
pub const fn new() -> Self {
|
||||
Self {
|
||||
global_log_e: 0,
|
||||
total_obs: 0,
|
||||
current_tick: 0,
|
||||
window_head: 0,
|
||||
window_count: 0,
|
||||
num_hypotheses: 0,
|
||||
_reserved: [0; 1],
|
||||
rejected_count: 0,
|
||||
status: Self::STATUS_ACTIVE,
|
||||
_hot_pad: [0; 40],
|
||||
hypotheses: [HypothesisState::new(0, 0); MAX_HYPOTHESES],
|
||||
window: [ObsRecord {
|
||||
obs: Observation {
|
||||
vertex: 0,
|
||||
obs_type: 0,
|
||||
flags: 0,
|
||||
value: 0,
|
||||
},
|
||||
tick: 0,
|
||||
}; WINDOW_SIZE],
|
||||
}
|
||||
}
|
||||
|
||||
/// Add a new hypothesis to track
|
||||
pub fn add_hypothesis(&mut self, hypothesis: HypothesisState) -> bool {
|
||||
if self.num_hypotheses as usize >= MAX_HYPOTHESES {
|
||||
return false;
|
||||
}
|
||||
|
||||
self.hypotheses[self.num_hypotheses as usize] = hypothesis;
|
||||
self.num_hypotheses += 1;
|
||||
true
|
||||
}
|
||||
|
||||
/// Add a connectivity hypothesis
|
||||
pub fn add_connectivity_hypothesis(&mut self, vertex: TileVertexId) -> bool {
|
||||
let id = self.num_hypotheses as u16;
|
||||
self.add_hypothesis(HypothesisState::connectivity(id, vertex))
|
||||
}
|
||||
|
||||
/// Add a cut membership hypothesis
|
||||
pub fn add_cut_hypothesis(&mut self, vertex: TileVertexId, threshold: TileVertexId) -> bool {
|
||||
let id = self.num_hypotheses as u16;
|
||||
self.add_hypothesis(HypothesisState::cut_membership(id, vertex, threshold))
|
||||
}
|
||||
|
||||
/// Process an observation
|
||||
///
|
||||
/// OPTIMIZATION: Uses fixed-point log LR for common observation types,
|
||||
/// avoids f32 conversion where possible
|
||||
#[inline]
|
||||
pub fn process_observation(&mut self, obs: Observation, tick: u32) {
|
||||
self.current_tick = tick;
|
||||
self.total_obs += 1;
|
||||
|
||||
// Add to sliding window using wrapping arithmetic
|
||||
// OPTIMIZATION: Avoid modulo with power-of-2 window size
|
||||
let idx = self.window_head as usize;
|
||||
// SAFETY: WINDOW_SIZE is 64, idx < 64
|
||||
unsafe {
|
||||
*self.window.get_unchecked_mut(idx) = ObsRecord { obs, tick };
|
||||
}
|
||||
// OPTIMIZATION: Bit mask for power-of-2 wrap (64 = 0x40, mask = 0x3F)
|
||||
self.window_head = ((self.window_head + 1) & (WINDOW_SIZE as u16 - 1));
|
||||
if (self.window_count as usize) < WINDOW_SIZE {
|
||||
self.window_count += 1;
|
||||
}
|
||||
|
||||
// Compute log likelihood ratio in fixed-point where possible
|
||||
// OPTIMIZATION: Use pre-computed constants for common types
|
||||
let log_lr = self.compute_log_likelihood_ratio(&obs);
|
||||
|
||||
// Update global e-value
|
||||
self.global_log_e = self.global_log_e.saturating_add(log_lr);
|
||||
|
||||
// Update relevant hypotheses
|
||||
// OPTIMIZATION: Cache num_hypotheses to avoid repeated load
|
||||
let num_hyp = self.num_hypotheses as usize;
|
||||
for i in 0..num_hyp {
|
||||
// SAFETY: i < num_hypotheses <= MAX_HYPOTHESES
|
||||
let hyp = unsafe { self.hypotheses.get_unchecked(i) };
|
||||
|
||||
// OPTIMIZATION: Use combined can_update check
|
||||
if !hyp.can_update() {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check if observation is relevant to this hypothesis
|
||||
// OPTIMIZATION: Early exit on type mismatch (most common case)
|
||||
let is_relevant = self.is_obs_relevant(hyp, &obs);
|
||||
|
||||
if is_relevant {
|
||||
// SAFETY: i < num_hypotheses
|
||||
let hyp_mut = unsafe { self.hypotheses.get_unchecked_mut(i) };
|
||||
if hyp_mut.update_with_log_lr(log_lr) {
|
||||
self.rejected_count += 1;
|
||||
self.status |= Self::STATUS_HAS_REJECTION;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Update significance status using pre-computed constant
|
||||
if self.global_log_e > LOG_E_STRONG {
|
||||
self.status |= Self::STATUS_SIGNIFICANT;
|
||||
}
|
||||
}
|
||||
|
||||
/// Check if observation is relevant to hypothesis
|
||||
///
|
||||
/// OPTIMIZATION: Inlined for hot path
|
||||
#[inline(always)]
|
||||
fn is_obs_relevant(&self, hyp: &HypothesisState, obs: &Observation) -> bool {
|
||||
match (hyp.hyp_type, obs.obs_type) {
|
||||
(HypothesisState::TYPE_CONNECTIVITY, Observation::TYPE_CONNECTIVITY) => {
|
||||
obs.vertex == hyp.target
|
||||
}
|
||||
(HypothesisState::TYPE_CUT, Observation::TYPE_CUT_MEMBERSHIP) => {
|
||||
obs.vertex == hyp.target
|
||||
}
|
||||
(HypothesisState::TYPE_FLOW, Observation::TYPE_FLOW) => obs.vertex == hyp.target,
|
||||
_ => false,
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute log likelihood ratio in fixed-point
|
||||
///
|
||||
/// OPTIMIZATION: Returns pre-computed constants for common types,
|
||||
/// only falls back to f32 for complex calculations
|
||||
#[inline(always)]
|
||||
fn compute_log_likelihood_ratio(&self, obs: &Observation) -> LogEValue {
|
||||
match obs.obs_type {
|
||||
Observation::TYPE_CONNECTIVITY => {
|
||||
// Use pre-computed constants
|
||||
if obs.flags != 0 {
|
||||
LOG_LR_CONNECTIVITY_POS // 1.5
|
||||
} else {
|
||||
LOG_LR_CONNECTIVITY_NEG // 0.5
|
||||
}
|
||||
}
|
||||
Observation::TYPE_WITNESS => {
|
||||
// Use pre-computed constants
|
||||
if obs.flags != 0 {
|
||||
LOG_LR_WITNESS_POS // 2.0
|
||||
} else {
|
||||
LOG_LR_WITNESS_NEG // 0.5
|
||||
}
|
||||
}
|
||||
Observation::TYPE_CUT_MEMBERSHIP => {
|
||||
// Confidence-based: 1.0 + confidence (1.0 to 2.0)
|
||||
// log2(1 + x) where x in [0,1]
|
||||
// Approximation: x * 65536 / ln(2) for small x
|
||||
let confidence_fixed = (obs.value as i32) >> 1; // Scale 0-65535 to ~0-32768
|
||||
confidence_fixed
|
||||
}
|
||||
Observation::TYPE_FLOW => {
|
||||
// Flow-based: needs f32 path
|
||||
let flow = (obs.value as f32) / 1000.0;
|
||||
let lr = if flow > 0.5 {
|
||||
1.0 + flow
|
||||
} else {
|
||||
1.0 / (1.0 + flow)
|
||||
};
|
||||
f32_to_log_e(lr)
|
||||
}
|
||||
_ => 0, // Neutral
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute likelihood ratio for an observation (f32 version for compatibility)
|
||||
#[inline]
|
||||
fn compute_likelihood_ratio(&self, obs: &Observation) -> f32 {
|
||||
match obs.obs_type {
|
||||
Observation::TYPE_CONNECTIVITY => {
|
||||
if obs.flags != 0 {
|
||||
1.5
|
||||
} else {
|
||||
0.5
|
||||
}
|
||||
}
|
||||
Observation::TYPE_CUT_MEMBERSHIP => {
|
||||
let confidence = (obs.value as f32) / 65535.0;
|
||||
1.0 + confidence
|
||||
}
|
||||
Observation::TYPE_FLOW => {
|
||||
let flow = (obs.value as f32) / 1000.0;
|
||||
if flow > 0.5 {
|
||||
1.0 + flow
|
||||
} else {
|
||||
1.0 / (1.0 + flow)
|
||||
}
|
||||
}
|
||||
Observation::TYPE_WITNESS => {
|
||||
if obs.flags != 0 {
|
||||
2.0
|
||||
} else {
|
||||
0.5
|
||||
}
|
||||
}
|
||||
_ => 1.0,
|
||||
}
|
||||
}
|
||||
|
||||
/// Get global e-value as approximate f32
|
||||
#[inline(always)]
|
||||
pub fn global_e_value(&self) -> f32 {
|
||||
let log2_val = (self.global_log_e as f32) / 65536.0;
|
||||
libm::exp2f(log2_val)
|
||||
}
|
||||
|
||||
/// Check if any hypothesis is rejected
|
||||
#[inline(always)]
|
||||
pub fn has_rejection(&self) -> bool {
|
||||
self.status & Self::STATUS_HAS_REJECTION != 0
|
||||
}
|
||||
|
||||
/// Check if evidence is significant (e > 20)
|
||||
#[inline(always)]
|
||||
pub fn is_significant(&self) -> bool {
|
||||
self.status & Self::STATUS_SIGNIFICANT != 0
|
||||
}
|
||||
|
||||
/// Reset all hypotheses
|
||||
pub fn reset(&mut self) {
|
||||
for h in self.hypotheses[..self.num_hypotheses as usize].iter_mut() {
|
||||
h.reset();
|
||||
}
|
||||
self.window_head = 0;
|
||||
self.window_count = 0;
|
||||
self.global_log_e = 0;
|
||||
self.rejected_count = 0;
|
||||
self.status = Self::STATUS_ACTIVE;
|
||||
}
|
||||
|
||||
/// Process a batch of observations efficiently
|
||||
///
|
||||
/// OPTIMIZATION: Batch processing reduces function call overhead and
|
||||
/// allows better cache utilization by processing observations in bulk.
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `observations` - Slice of (observation, tick) pairs
|
||||
#[inline]
|
||||
pub fn process_observation_batch(&mut self, observations: &[(Observation, u32)]) {
|
||||
// Pre-compute all log LRs for the batch
|
||||
// This allows potential vectorization of LR computation
|
||||
let batch_size = observations.len().min(64);
|
||||
|
||||
// Process in cache-friendly order
|
||||
for &(obs, tick) in observations.iter().take(batch_size) {
|
||||
self.process_observation(obs, tick);
|
||||
}
|
||||
}
|
||||
|
||||
/// Aggregate all hypothesis e-values using SIMD
|
||||
///
|
||||
/// OPTIMIZATION: Uses SIMD-friendly parallel lane accumulation
|
||||
/// to sum all active hypothesis log e-values efficiently.
|
||||
///
|
||||
/// # Returns
|
||||
/// Total accumulated log e-value across all hypotheses
|
||||
#[inline]
|
||||
pub fn aggregate_hypotheses_simd(&self) -> i64 {
|
||||
let mut lanes = [0i64; 4];
|
||||
let num_hyp = self.num_hypotheses as usize;
|
||||
|
||||
// Process hypotheses in 4-lane parallel pattern
|
||||
for i in 0..num_hyp {
|
||||
let hyp = &self.hypotheses[i];
|
||||
if hyp.is_active() {
|
||||
lanes[i % 4] += hyp.log_e_value as i64;
|
||||
}
|
||||
}
|
||||
|
||||
lanes[0] + lanes[1] + lanes[2] + lanes[3]
|
||||
}
|
||||
|
||||
/// Fast check if evidence level exceeds threshold
|
||||
///
|
||||
/// OPTIMIZATION: Uses pre-computed log threshold constants
|
||||
/// to avoid expensive exp2f conversion.
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `threshold_log` - Log threshold (e.g., LOG_E_STRONG for alpha=0.05)
|
||||
///
|
||||
/// # Returns
|
||||
/// true if global evidence exceeds threshold
|
||||
#[inline(always)]
|
||||
pub fn exceeds_threshold(&self, threshold_log: LogEValue) -> bool {
|
||||
self.global_log_e > threshold_log
|
||||
}
|
||||
|
||||
/// Get memory size
|
||||
pub const fn memory_size() -> usize {
|
||||
size_of::<Self>()
|
||||
}
|
||||
}
|
||||
|
||||
// Compile-time size assertions
|
||||
const _: () = assert!(
|
||||
size_of::<HypothesisState>() == 16,
|
||||
"HypothesisState must be 16 bytes"
|
||||
);
|
||||
const _: () = assert!(size_of::<ObsRecord>() == 12, "ObsRecord must be 12 bytes");
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_log_e_conversion() {
|
||||
// e = 1 => log = 0
|
||||
assert_eq!(f32_to_log_e(1.0), 0);
|
||||
|
||||
// e = 2 => log2(2) * 65536 = 65536
|
||||
let log_2 = f32_to_log_e(2.0);
|
||||
assert!((log_2 - 65536).abs() < 100);
|
||||
|
||||
// e = 4 => log2(4) * 65536 = 131072
|
||||
let log_4 = f32_to_log_e(4.0);
|
||||
assert!((log_4 - 131072).abs() < 100);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_hypothesis_state() {
|
||||
let mut hyp = HypothesisState::new(0, HypothesisState::TYPE_CONNECTIVITY);
|
||||
assert!(hyp.is_active());
|
||||
assert!(!hyp.is_rejected());
|
||||
assert_eq!(hyp.obs_count, 0);
|
||||
|
||||
// Update with LR = 2 a few times
|
||||
for _ in 0..5 {
|
||||
hyp.update(2.0);
|
||||
}
|
||||
assert_eq!(hyp.obs_count, 5);
|
||||
assert!(hyp.e_value_approx() > 20.0); // 2^5 = 32 > 20
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_hypothesis_rejection() {
|
||||
let mut hyp = HypothesisState::new(0, HypothesisState::TYPE_CUT);
|
||||
|
||||
// Keep updating until rejection
|
||||
for _ in 0..10 {
|
||||
if hyp.update(2.0) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
assert!(hyp.is_rejected());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_accumulator_new() {
|
||||
let acc = EvidenceAccumulator::new();
|
||||
assert_eq!(acc.num_hypotheses, 0);
|
||||
assert_eq!(acc.total_obs, 0);
|
||||
assert!(!acc.has_rejection());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_add_hypothesis() {
|
||||
let mut acc = EvidenceAccumulator::new();
|
||||
assert!(acc.add_connectivity_hypothesis(5));
|
||||
assert!(acc.add_cut_hypothesis(10, 15));
|
||||
assert_eq!(acc.num_hypotheses, 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_process_observation() {
|
||||
let mut acc = EvidenceAccumulator::new();
|
||||
acc.add_connectivity_hypothesis(5);
|
||||
|
||||
// Process observations
|
||||
for tick in 0..10 {
|
||||
let obs = Observation::connectivity(5, true);
|
||||
acc.process_observation(obs, tick);
|
||||
}
|
||||
|
||||
assert_eq!(acc.total_obs, 10);
|
||||
assert!(acc.global_e_value() > 1.0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_sliding_window() {
|
||||
let mut acc = EvidenceAccumulator::new();
|
||||
|
||||
// Fill window
|
||||
for tick in 0..(WINDOW_SIZE as u32 + 10) {
|
||||
let obs = Observation::connectivity(0, true);
|
||||
acc.process_observation(obs, tick);
|
||||
}
|
||||
|
||||
assert_eq!(acc.window_count, WINDOW_SIZE as u16);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_memory_size() {
|
||||
let size = EvidenceAccumulator::memory_size();
|
||||
// Should be reasonable for tile budget
|
||||
assert!(size < 4096, "EvidenceAccumulator too large: {} bytes", size);
|
||||
}
|
||||
}
|
||||
745
crates/cognitum-gate-kernel/src/lib.rs
Normal file
745
crates/cognitum-gate-kernel/src/lib.rs
Normal file
@@ -0,0 +1,745 @@
|
||||
//! Cognitum Gate Kernel
|
||||
//!
|
||||
//! A no_std WASM kernel for worker tiles in a 256-tile coherence gate fabric.
|
||||
//! Each tile maintains a local graph shard, accumulates evidence for sequential
|
||||
//! testing, and produces witness fragments for aggregation.
|
||||
//!
|
||||
//! # Architecture
|
||||
//!
|
||||
//! The coherence gate consists of 256 worker tiles, each running this kernel.
|
||||
//! Tiles receive delta updates (edge additions, removals, weight changes) and
|
||||
//! observations, process them through a deterministic tick loop, and produce
|
||||
//! reports containing:
|
||||
//!
|
||||
//! - Local graph state (vertices, edges, components)
|
||||
//! - Evidence accumulation (e-values for hypothesis testing)
|
||||
//! - Witness fragments (for global min-cut aggregation)
|
||||
//!
|
||||
//! # Memory Budget
|
||||
//!
|
||||
//! Each tile operates within a ~64KB memory budget:
|
||||
//! - CompactGraph: ~42KB (vertices, edges, adjacency)
|
||||
//! - EvidenceAccumulator: ~2KB (hypotheses, sliding window)
|
||||
//! - TileState: ~1KB (configuration, buffers)
|
||||
//! - Stack/Control: ~19KB (remaining)
|
||||
//!
|
||||
//! # WASM Exports
|
||||
//!
|
||||
//! The kernel exports three main functions for the WASM interface:
|
||||
//!
|
||||
//! - `ingest_delta`: Process incoming delta updates
|
||||
//! - `tick`: Execute one step of the deterministic tick loop
|
||||
//! - `get_witness_fragment`: Retrieve the current witness fragment
|
||||
//!
|
||||
//! # Example
|
||||
//!
|
||||
//! ```ignore
|
||||
//! // Initialize tile
|
||||
//! let tile = TileState::new(42); // Tile ID 42
|
||||
//!
|
||||
//! // Ingest deltas
|
||||
//! tile.ingest_delta(&Delta::edge_add(0, 1, 100));
|
||||
//! tile.ingest_delta(&Delta::edge_add(1, 2, 100));
|
||||
//!
|
||||
//! // Process tick
|
||||
//! let report = tile.tick(1);
|
||||
//!
|
||||
//! // Get witness
|
||||
//! let witness = tile.get_witness_fragment();
|
||||
//! ```
|
||||
|
||||
#![cfg_attr(not(feature = "std"), no_std)]
|
||||
#![deny(unsafe_op_in_unsafe_fn)]
|
||||
#![warn(missing_docs)]
|
||||
#![allow(clippy::missing_safety_doc)]
|
||||
|
||||
#[cfg(not(feature = "std"))]
|
||||
extern crate alloc;
|
||||
|
||||
// Global allocator for no_std builds
|
||||
#[cfg(all(not(feature = "std"), not(test)))]
|
||||
mod allocator {
|
||||
use core::alloc::{GlobalAlloc, Layout};
|
||||
|
||||
/// A simple bump allocator for no_std WASM builds
|
||||
/// In production, this would be replaced with wee_alloc or similar
|
||||
struct BumpAllocator;
|
||||
|
||||
// 64KB heap for each tile
|
||||
const HEAP_SIZE: usize = 65536;
|
||||
static mut HEAP: [u8; HEAP_SIZE] = [0; HEAP_SIZE];
|
||||
static mut HEAP_PTR: usize = 0;
|
||||
|
||||
unsafe impl GlobalAlloc for BumpAllocator {
|
||||
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
|
||||
let size = layout.size();
|
||||
let align = layout.align();
|
||||
|
||||
unsafe {
|
||||
// Align the heap pointer
|
||||
let aligned = (HEAP_PTR + align - 1) & !(align - 1);
|
||||
|
||||
if aligned + size > HEAP_SIZE {
|
||||
core::ptr::null_mut()
|
||||
} else {
|
||||
HEAP_PTR = aligned + size;
|
||||
HEAP.as_mut_ptr().add(aligned)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe fn dealloc(&self, _ptr: *mut u8, _layout: Layout) {
|
||||
// Bump allocator doesn't deallocate
|
||||
// This is fine for short-lived WASM kernels
|
||||
}
|
||||
}
|
||||
|
||||
#[global_allocator]
|
||||
static ALLOCATOR: BumpAllocator = BumpAllocator;
|
||||
}
|
||||
|
||||
// Panic handler for no_std builds (not needed for tests or std builds)
|
||||
#[cfg(all(not(feature = "std"), not(test), target_arch = "wasm32"))]
|
||||
#[panic_handler]
|
||||
fn panic(_info: &core::panic::PanicInfo) -> ! {
|
||||
// In WASM, we can use unreachable to trap
|
||||
core::arch::wasm32::unreachable()
|
||||
}
|
||||
|
||||
// For non-wasm no_std builds without test
|
||||
#[cfg(all(not(feature = "std"), not(test), not(target_arch = "wasm32")))]
|
||||
#[panic_handler]
|
||||
fn panic(_info: &core::panic::PanicInfo) -> ! {
|
||||
loop {}
|
||||
}
|
||||
|
||||
pub mod delta;
|
||||
pub mod evidence;
|
||||
pub mod report;
|
||||
pub mod shard;
|
||||
|
||||
#[cfg(feature = "canonical-witness")]
|
||||
pub mod canonical_witness;
|
||||
|
||||
#[cfg(feature = "canonical-witness")]
|
||||
pub use canonical_witness::{
|
||||
ArenaCactus, CactusNode, CanonicalPartition, CanonicalWitnessFragment, FixedPointWeight,
|
||||
};
|
||||
|
||||
use crate::delta::{Delta, DeltaTag};
|
||||
use crate::evidence::EvidenceAccumulator;
|
||||
use crate::report::{TileReport, TileStatus, WitnessFragment};
|
||||
use crate::shard::CompactGraph;
|
||||
use core::mem::size_of;
|
||||
|
||||
/// Maximum deltas in ingestion buffer
|
||||
pub const MAX_DELTA_BUFFER: usize = 64;
|
||||
|
||||
/// Tile state containing all local state for a worker tile
|
||||
#[repr(C)]
|
||||
pub struct TileState {
|
||||
/// Tile identifier (0-255)
|
||||
pub tile_id: u8,
|
||||
/// Status flags
|
||||
pub status: u8,
|
||||
/// Current tick number
|
||||
pub tick: u32,
|
||||
/// Generation number (incremented on structural changes)
|
||||
pub generation: u16,
|
||||
/// Reserved padding
|
||||
pub _reserved: [u8; 2],
|
||||
/// Local graph shard
|
||||
pub graph: CompactGraph,
|
||||
/// Evidence accumulator
|
||||
pub evidence: EvidenceAccumulator,
|
||||
/// Delta ingestion buffer
|
||||
pub delta_buffer: [Delta; MAX_DELTA_BUFFER],
|
||||
/// Number of deltas in buffer
|
||||
pub delta_count: u16,
|
||||
/// Buffer head pointer
|
||||
pub delta_head: u16,
|
||||
/// Last report produced
|
||||
pub last_report: TileReport,
|
||||
}
|
||||
|
||||
impl TileState {
|
||||
/// Status: tile is initialized
|
||||
pub const STATUS_INITIALIZED: u8 = 0x01;
|
||||
/// Status: tile has pending deltas
|
||||
pub const STATUS_HAS_DELTAS: u8 = 0x02;
|
||||
/// Status: tile needs recomputation
|
||||
pub const STATUS_DIRTY: u8 = 0x04;
|
||||
/// Status: tile is in error state
|
||||
pub const STATUS_ERROR: u8 = 0x80;
|
||||
|
||||
/// Create a new tile state
|
||||
pub fn new(tile_id: u8) -> Self {
|
||||
Self {
|
||||
tile_id,
|
||||
status: Self::STATUS_INITIALIZED,
|
||||
tick: 0,
|
||||
generation: 0,
|
||||
_reserved: [0; 2],
|
||||
graph: CompactGraph::new(),
|
||||
evidence: EvidenceAccumulator::new(),
|
||||
delta_buffer: [Delta::nop(); MAX_DELTA_BUFFER],
|
||||
delta_count: 0,
|
||||
delta_head: 0,
|
||||
last_report: TileReport::new(tile_id),
|
||||
}
|
||||
}
|
||||
|
||||
/// Ingest a delta into the buffer
|
||||
///
|
||||
/// Returns true if the delta was successfully buffered.
|
||||
/// Returns false if the buffer is full.
|
||||
pub fn ingest_delta(&mut self, delta: &Delta) -> bool {
|
||||
if self.delta_count as usize >= MAX_DELTA_BUFFER {
|
||||
return false;
|
||||
}
|
||||
|
||||
let idx = (self.delta_head as usize + self.delta_count as usize) % MAX_DELTA_BUFFER;
|
||||
self.delta_buffer[idx] = *delta;
|
||||
self.delta_count += 1;
|
||||
self.status |= Self::STATUS_HAS_DELTAS;
|
||||
true
|
||||
}
|
||||
|
||||
/// Ingest a delta from raw bytes
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The caller must ensure that `ptr` points to a valid `Delta` structure
|
||||
/// and that the pointer is properly aligned.
|
||||
#[inline]
|
||||
pub unsafe fn ingest_delta_raw(&mut self, ptr: *const u8) -> bool {
|
||||
let delta = unsafe { &*(ptr as *const Delta) };
|
||||
self.ingest_delta(delta)
|
||||
}
|
||||
|
||||
/// Process one tick of the kernel
|
||||
///
|
||||
/// This is the main entry point for the tick loop. It:
|
||||
/// 1. Processes all buffered deltas
|
||||
/// 2. Updates the evidence accumulator
|
||||
/// 3. Recomputes graph connectivity if needed
|
||||
/// 4. Produces a tile report
|
||||
pub fn tick(&mut self, tick_number: u32) -> TileReport {
|
||||
self.tick = tick_number;
|
||||
let tick_start = self.current_time_us();
|
||||
|
||||
// Process buffered deltas
|
||||
let deltas_processed = self.process_deltas();
|
||||
|
||||
// Recompute connectivity if graph is dirty
|
||||
if self.graph.status & CompactGraph::STATUS_DIRTY != 0 {
|
||||
self.graph.recompute_components();
|
||||
}
|
||||
|
||||
// Build report
|
||||
let mut report = TileReport::new(self.tile_id);
|
||||
report.tick = tick_number;
|
||||
report.generation = self.generation;
|
||||
report.status = TileStatus::Complete;
|
||||
|
||||
// Graph state
|
||||
report.num_vertices = self.graph.num_vertices;
|
||||
report.num_edges = self.graph.num_edges;
|
||||
report.num_components = self.graph.num_components;
|
||||
report.set_connected(self.graph.is_connected());
|
||||
|
||||
if self.graph.status & CompactGraph::STATUS_DIRTY != 0 {
|
||||
report.graph_flags |= TileReport::GRAPH_DIRTY;
|
||||
}
|
||||
|
||||
// Evidence state
|
||||
report.log_e_value = self.evidence.global_log_e;
|
||||
report.obs_count = self.evidence.total_obs as u16;
|
||||
report.rejected_count = self.evidence.rejected_count;
|
||||
|
||||
// Witness fragment
|
||||
report.witness = self.compute_witness_fragment();
|
||||
|
||||
// Performance metrics
|
||||
let tick_end = self.current_time_us();
|
||||
report.tick_time_us = (tick_end - tick_start) as u16;
|
||||
report.deltas_processed = deltas_processed as u16;
|
||||
report.memory_kb = (Self::memory_size() / 1024) as u16;
|
||||
|
||||
self.last_report = report;
|
||||
report
|
||||
}
|
||||
|
||||
/// Get the current witness fragment
|
||||
pub fn get_witness_fragment(&self) -> WitnessFragment {
|
||||
self.last_report.witness
|
||||
}
|
||||
|
||||
/// Process all buffered deltas
|
||||
fn process_deltas(&mut self) -> usize {
|
||||
let mut processed = 0;
|
||||
|
||||
while self.delta_count > 0 {
|
||||
let delta = self.delta_buffer[self.delta_head as usize];
|
||||
self.delta_head = ((self.delta_head as usize + 1) % MAX_DELTA_BUFFER) as u16;
|
||||
self.delta_count -= 1;
|
||||
|
||||
self.apply_delta(&delta);
|
||||
processed += 1;
|
||||
}
|
||||
|
||||
self.status &= !Self::STATUS_HAS_DELTAS;
|
||||
processed
|
||||
}
|
||||
|
||||
/// Apply a single delta to the tile state
|
||||
fn apply_delta(&mut self, delta: &Delta) {
|
||||
match delta.tag {
|
||||
DeltaTag::Nop => {}
|
||||
DeltaTag::EdgeAdd => {
|
||||
let ea = unsafe { delta.get_edge_add() };
|
||||
self.graph.add_edge(ea.source, ea.target, ea.weight);
|
||||
self.generation = self.generation.wrapping_add(1);
|
||||
}
|
||||
DeltaTag::EdgeRemove => {
|
||||
let er = unsafe { delta.get_edge_remove() };
|
||||
self.graph.remove_edge(er.source, er.target);
|
||||
self.generation = self.generation.wrapping_add(1);
|
||||
}
|
||||
DeltaTag::WeightUpdate => {
|
||||
let wu = unsafe { delta.get_weight_update() };
|
||||
self.graph
|
||||
.update_weight(wu.source, wu.target, wu.new_weight);
|
||||
}
|
||||
DeltaTag::Observation => {
|
||||
let obs = unsafe { *delta.get_observation() };
|
||||
self.evidence.process_observation(obs, self.tick);
|
||||
}
|
||||
DeltaTag::BatchEnd => {
|
||||
// Trigger recomputation
|
||||
self.status |= Self::STATUS_DIRTY;
|
||||
}
|
||||
DeltaTag::Checkpoint => {
|
||||
// TODO: Implement checkpointing
|
||||
}
|
||||
DeltaTag::Reset => {
|
||||
self.graph.clear();
|
||||
self.evidence.reset();
|
||||
self.generation = 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute the witness fragment for the current state
|
||||
fn compute_witness_fragment(&self) -> WitnessFragment {
|
||||
// Find the vertex with minimum degree (likely on cut boundary)
|
||||
let mut min_degree = u8::MAX;
|
||||
let mut seed = 0u16;
|
||||
|
||||
for v in 0..shard::MAX_SHARD_VERTICES {
|
||||
if self.graph.vertices[v].is_active() {
|
||||
let degree = self.graph.vertices[v].degree;
|
||||
if degree < min_degree && degree > 0 {
|
||||
min_degree = degree;
|
||||
seed = v as u16;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Count boundary vertices (vertices with edges to other tiles would be marked ghost)
|
||||
let mut boundary = 0u16;
|
||||
for v in 0..shard::MAX_SHARD_VERTICES {
|
||||
if self.graph.vertices[v].is_active()
|
||||
&& (self.graph.vertices[v].flags & shard::VertexEntry::FLAG_BOUNDARY) != 0
|
||||
{
|
||||
boundary += 1;
|
||||
}
|
||||
}
|
||||
|
||||
// Estimate local min cut as minimum vertex degree * average edge weight
|
||||
// This is a heuristic; actual min-cut requires more computation
|
||||
let local_min_cut = if min_degree == u8::MAX {
|
||||
0
|
||||
} else {
|
||||
// Average weight (assuming uniform for simplicity)
|
||||
min_degree as u16 * 100 // weight scale factor
|
||||
};
|
||||
|
||||
let mut fragment =
|
||||
WitnessFragment::new(seed, boundary, self.graph.num_vertices, local_min_cut);
|
||||
fragment.component = self.graph.num_components;
|
||||
fragment.compute_hash();
|
||||
|
||||
fragment
|
||||
}
|
||||
|
||||
/// Get current time in microseconds (stub for no_std)
|
||||
#[inline]
|
||||
fn current_time_us(&self) -> u32 {
|
||||
// In actual WASM, this would call a host function
|
||||
// For now, return tick-based time
|
||||
self.tick * 1000
|
||||
}
|
||||
|
||||
/// Get total memory size of tile state
|
||||
pub const fn memory_size() -> usize {
|
||||
size_of::<Self>()
|
||||
}
|
||||
|
||||
/// Reset the tile to initial state
|
||||
pub fn reset(&mut self) {
|
||||
self.graph.clear();
|
||||
self.evidence.reset();
|
||||
self.delta_count = 0;
|
||||
self.delta_head = 0;
|
||||
self.tick = 0;
|
||||
self.generation = 0;
|
||||
self.status = Self::STATUS_INITIALIZED;
|
||||
}
|
||||
|
||||
/// Check if tile has pending deltas
|
||||
#[inline]
|
||||
pub fn has_pending_deltas(&self) -> bool {
|
||||
self.delta_count > 0
|
||||
}
|
||||
|
||||
/// Check if tile is in error state
|
||||
#[inline]
|
||||
pub fn is_error(&self) -> bool {
|
||||
self.status & Self::STATUS_ERROR != 0
|
||||
}
|
||||
|
||||
/// Compute a canonical witness fragment for the current tile state.
|
||||
///
|
||||
/// This produces a reproducible, hash-stable 16-byte witness by:
|
||||
/// 1. Building a cactus tree from the `CompactGraph`
|
||||
/// 2. Deriving a canonical (lex-smallest) min-cut partition
|
||||
/// 3. Packing the result into a `CanonicalWitnessFragment`
|
||||
///
|
||||
/// Temporary stack usage: ~2.1KB (fits in the 14.5KB remaining headroom).
|
||||
#[cfg(feature = "canonical-witness")]
|
||||
pub fn canonical_witness(&self) -> canonical_witness::CanonicalWitnessFragment {
|
||||
let cactus = canonical_witness::ArenaCactus::build_from_compact_graph(&self.graph);
|
||||
let partition = cactus.canonical_partition();
|
||||
|
||||
canonical_witness::CanonicalWitnessFragment {
|
||||
tile_id: self.tile_id,
|
||||
epoch: (self.tick & 0xFF) as u8,
|
||||
cardinality_a: partition.cardinality_a,
|
||||
cardinality_b: partition.cardinality_b,
|
||||
cut_value: cactus.min_cut_value.to_u16(),
|
||||
canonical_hash: partition.canonical_hash,
|
||||
boundary_edges: self.graph.num_edges,
|
||||
cactus_digest: cactus.digest(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// WASM Exports
|
||||
// ============================================================================
|
||||
|
||||
/// Global tile state (single tile per WASM instance)
|
||||
static mut TILE_STATE: Option<TileState> = None;
|
||||
|
||||
/// Initialize the tile with the given ID
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// This function modifies global state. It should only be called once
|
||||
/// during module initialization.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn init_tile(tile_id: u8) {
|
||||
unsafe {
|
||||
TILE_STATE = Some(TileState::new(tile_id));
|
||||
}
|
||||
}
|
||||
|
||||
/// Ingest a delta from raw memory
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// - `ptr` must point to a valid `Delta` structure
|
||||
/// - The tile must be initialized
|
||||
///
|
||||
/// Returns 1 on success, 0 if buffer is full or tile not initialized.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn ingest_delta(ptr: *const u8) -> i32 {
|
||||
unsafe {
|
||||
match TILE_STATE.as_mut() {
|
||||
Some(tile) => {
|
||||
if tile.ingest_delta_raw(ptr) {
|
||||
1
|
||||
} else {
|
||||
0
|
||||
}
|
||||
}
|
||||
None => 0,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Execute one tick of the kernel
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// - `report_ptr` must point to a buffer of at least 64 bytes
|
||||
/// - The tile must be initialized
|
||||
///
|
||||
/// Returns 1 on success, 0 if tile not initialized.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn tick(tick_number: u32, report_ptr: *mut u8) -> i32 {
|
||||
unsafe {
|
||||
match TILE_STATE.as_mut() {
|
||||
Some(tile) => {
|
||||
let report = tile.tick(tick_number);
|
||||
// Copy report to output buffer
|
||||
let report_bytes =
|
||||
core::slice::from_raw_parts(&report as *const TileReport as *const u8, 64);
|
||||
core::ptr::copy_nonoverlapping(report_bytes.as_ptr(), report_ptr, 64);
|
||||
1
|
||||
}
|
||||
None => 0,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Get the current witness fragment
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// - `fragment_ptr` must point to a buffer of at least 16 bytes
|
||||
/// - The tile must be initialized
|
||||
///
|
||||
/// Returns 1 on success, 0 if tile not initialized.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn get_witness_fragment(fragment_ptr: *mut u8) -> i32 {
|
||||
unsafe {
|
||||
match TILE_STATE.as_ref() {
|
||||
Some(tile) => {
|
||||
let fragment = tile.get_witness_fragment();
|
||||
let fragment_bytes = core::slice::from_raw_parts(
|
||||
&fragment as *const WitnessFragment as *const u8,
|
||||
16,
|
||||
);
|
||||
core::ptr::copy_nonoverlapping(fragment_bytes.as_ptr(), fragment_ptr, 16);
|
||||
1
|
||||
}
|
||||
None => 0,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Get tile status
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The tile must be initialized.
|
||||
///
|
||||
/// Returns status byte, or 0xFF if not initialized.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn get_status() -> u8 {
|
||||
unsafe {
|
||||
match TILE_STATE.as_ref() {
|
||||
Some(tile) => tile.status,
|
||||
None => 0xFF,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Reset the tile state
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// The tile must be initialized.
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn reset_tile() {
|
||||
unsafe {
|
||||
if let Some(tile) = TILE_STATE.as_mut() {
|
||||
tile.reset();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Get memory usage in bytes
|
||||
#[no_mangle]
|
||||
pub extern "C" fn get_memory_usage() -> u32 {
|
||||
TileState::memory_size() as u32
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Tests
|
||||
// ============================================================================
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::delta::Observation;
|
||||
|
||||
#[test]
|
||||
fn test_tile_state_new() {
|
||||
let tile = TileState::new(42);
|
||||
assert_eq!(tile.tile_id, 42);
|
||||
assert_eq!(tile.tick, 0);
|
||||
assert_eq!(tile.delta_count, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_ingest_delta() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
let delta = Delta::edge_add(1, 2, 100);
|
||||
assert!(tile.ingest_delta(&delta));
|
||||
assert_eq!(tile.delta_count, 1);
|
||||
assert!(tile.has_pending_deltas());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_ingest_buffer_full() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
// Fill buffer
|
||||
for i in 0..MAX_DELTA_BUFFER {
|
||||
let delta = Delta::edge_add(i as u16, (i + 1) as u16, 100);
|
||||
assert!(tile.ingest_delta(&delta));
|
||||
}
|
||||
|
||||
// Should fail when full
|
||||
let delta = Delta::edge_add(100, 101, 100);
|
||||
assert!(!tile.ingest_delta(&delta));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tick_processes_deltas() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
// Add some edges
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100));
|
||||
tile.ingest_delta(&Delta::edge_add(1, 2, 100));
|
||||
tile.ingest_delta(&Delta::edge_add(2, 0, 100));
|
||||
|
||||
// Process tick
|
||||
let report = tile.tick(1);
|
||||
|
||||
assert_eq!(report.tile_id, 0);
|
||||
assert_eq!(report.tick, 1);
|
||||
assert_eq!(report.status, TileStatus::Complete);
|
||||
assert_eq!(report.num_vertices, 3);
|
||||
assert_eq!(report.num_edges, 3);
|
||||
assert_eq!(report.deltas_processed, 3);
|
||||
assert!(!tile.has_pending_deltas());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tick_connectivity() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
// Create a connected graph
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100));
|
||||
tile.ingest_delta(&Delta::edge_add(1, 2, 100));
|
||||
|
||||
let report = tile.tick(1);
|
||||
assert!(report.is_connected());
|
||||
assert_eq!(report.num_components, 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tick_disconnected() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
// Create two disconnected components
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100));
|
||||
tile.ingest_delta(&Delta::edge_add(2, 3, 100));
|
||||
|
||||
let report = tile.tick(1);
|
||||
assert!(!report.is_connected());
|
||||
assert_eq!(report.num_components, 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_observation_processing() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
// Add hypothesis
|
||||
tile.evidence.add_connectivity_hypothesis(5);
|
||||
|
||||
// Process observations
|
||||
for i in 0..5 {
|
||||
let obs = Observation::connectivity(5, true);
|
||||
tile.ingest_delta(&Delta::observation(obs));
|
||||
tile.tick(i);
|
||||
}
|
||||
|
||||
assert!(tile.evidence.global_e_value() > 1.0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_witness_fragment() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100));
|
||||
tile.ingest_delta(&Delta::edge_add(1, 2, 100));
|
||||
tile.ingest_delta(&Delta::edge_add(2, 0, 100));
|
||||
|
||||
tile.tick(1);
|
||||
let witness = tile.get_witness_fragment();
|
||||
|
||||
assert!(!witness.is_empty());
|
||||
assert_eq!(witness.cardinality, 3);
|
||||
assert_ne!(witness.hash, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_reset() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100));
|
||||
tile.tick(1);
|
||||
|
||||
assert_eq!(tile.graph.num_edges, 1);
|
||||
|
||||
tile.reset();
|
||||
|
||||
assert_eq!(tile.graph.num_edges, 0);
|
||||
assert_eq!(tile.graph.num_vertices, 0);
|
||||
assert_eq!(tile.tick, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_memory_size() {
|
||||
let size = TileState::memory_size();
|
||||
// Should fit in 64KB tile budget
|
||||
assert!(size <= 65536, "TileState exceeds 64KB: {} bytes", size);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_edge_removal() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100));
|
||||
tile.ingest_delta(&Delta::edge_add(1, 2, 100));
|
||||
tile.tick(1);
|
||||
|
||||
assert_eq!(tile.graph.num_edges, 2);
|
||||
|
||||
tile.ingest_delta(&Delta::edge_remove(0, 1));
|
||||
tile.tick(2);
|
||||
|
||||
assert_eq!(tile.graph.num_edges, 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_weight_update() {
|
||||
let mut tile = TileState::new(0);
|
||||
|
||||
tile.ingest_delta(&Delta::edge_add(0, 1, 100));
|
||||
tile.tick(1);
|
||||
|
||||
assert_eq!(tile.graph.edge_weight(0, 1), Some(100));
|
||||
|
||||
tile.ingest_delta(&Delta::weight_update(0, 1, 200));
|
||||
tile.tick(2);
|
||||
|
||||
assert_eq!(tile.graph.edge_weight(0, 1), Some(200));
|
||||
}
|
||||
}
|
||||
490
crates/cognitum-gate-kernel/src/report.rs
Normal file
490
crates/cognitum-gate-kernel/src/report.rs
Normal file
@@ -0,0 +1,490 @@
|
||||
//! Tile report structures for coherence gate coordination
|
||||
//!
|
||||
//! Defines the 64-byte cache-line aligned report structure that tiles
|
||||
//! produce after each tick. These reports are aggregated by the coordinator
|
||||
//! to form witness fragments for the coherence gate.
|
||||
|
||||
#![allow(missing_docs)]
|
||||
|
||||
use crate::delta::TileVertexId;
|
||||
use crate::evidence::LogEValue;
|
||||
use core::mem::size_of;
|
||||
|
||||
/// Tile status codes
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
#[repr(u8)]
|
||||
pub enum TileStatus {
|
||||
/// Tile is idle (no work)
|
||||
Idle = 0,
|
||||
/// Tile is processing deltas
|
||||
Processing = 1,
|
||||
/// Tile completed tick successfully
|
||||
Complete = 2,
|
||||
/// Tile encountered an error
|
||||
Error = 3,
|
||||
/// Tile is waiting for synchronization
|
||||
Waiting = 4,
|
||||
/// Tile is checkpointing
|
||||
Checkpointing = 5,
|
||||
/// Tile is recovering from checkpoint
|
||||
Recovering = 6,
|
||||
/// Tile is shutting down
|
||||
Shutdown = 7,
|
||||
}
|
||||
|
||||
impl From<u8> for TileStatus {
|
||||
fn from(v: u8) -> Self {
|
||||
match v {
|
||||
0 => TileStatus::Idle,
|
||||
1 => TileStatus::Processing,
|
||||
2 => TileStatus::Complete,
|
||||
3 => TileStatus::Error,
|
||||
4 => TileStatus::Waiting,
|
||||
5 => TileStatus::Checkpointing,
|
||||
6 => TileStatus::Recovering,
|
||||
7 => TileStatus::Shutdown,
|
||||
_ => TileStatus::Error,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Witness fragment for aggregation
|
||||
///
|
||||
/// Compact representation of local cut/partition information
|
||||
/// that can be merged across tiles.
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C, align(8))]
|
||||
pub struct WitnessFragment {
|
||||
/// Seed vertex for this fragment
|
||||
pub seed: TileVertexId,
|
||||
/// Boundary size (cut edges crossing fragment)
|
||||
pub boundary_size: u16,
|
||||
/// Cardinality (vertices in fragment)
|
||||
pub cardinality: u16,
|
||||
/// Fragment hash for consistency checking
|
||||
pub hash: u16,
|
||||
/// Local minimum cut value (fixed-point)
|
||||
pub local_min_cut: u16,
|
||||
/// Component ID this fragment belongs to
|
||||
pub component: u16,
|
||||
/// Reserved padding
|
||||
pub _reserved: u16,
|
||||
}
|
||||
|
||||
impl WitnessFragment {
|
||||
/// Create a new witness fragment
|
||||
#[inline]
|
||||
pub const fn new(
|
||||
seed: TileVertexId,
|
||||
boundary_size: u16,
|
||||
cardinality: u16,
|
||||
local_min_cut: u16,
|
||||
) -> Self {
|
||||
Self {
|
||||
seed,
|
||||
boundary_size,
|
||||
cardinality,
|
||||
hash: 0,
|
||||
local_min_cut,
|
||||
component: 0,
|
||||
_reserved: 0,
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute fragment hash
|
||||
pub fn compute_hash(&mut self) {
|
||||
let mut h = self.seed as u32;
|
||||
h = h.wrapping_mul(31).wrapping_add(self.boundary_size as u32);
|
||||
h = h.wrapping_mul(31).wrapping_add(self.cardinality as u32);
|
||||
h = h.wrapping_mul(31).wrapping_add(self.local_min_cut as u32);
|
||||
self.hash = (h & 0xFFFF) as u16;
|
||||
}
|
||||
|
||||
/// Check if fragment is empty
|
||||
#[inline]
|
||||
pub const fn is_empty(&self) -> bool {
|
||||
self.cardinality == 0
|
||||
}
|
||||
}
|
||||
|
||||
/// Tile report produced after each tick (64 bytes, cache-line aligned)
|
||||
///
|
||||
/// This structure is designed to fit exactly in one cache line for
|
||||
/// efficient memory access patterns in the coordinator.
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
#[repr(C, align(64))]
|
||||
pub struct TileReport {
|
||||
// --- Header (8 bytes) ---
|
||||
/// Tile ID (0-255)
|
||||
pub tile_id: u8,
|
||||
/// Tile status
|
||||
pub status: TileStatus,
|
||||
/// Generation/epoch number
|
||||
pub generation: u16,
|
||||
/// Current tick number
|
||||
pub tick: u32,
|
||||
|
||||
// --- Graph state (8 bytes) ---
|
||||
/// Number of active vertices
|
||||
pub num_vertices: u16,
|
||||
/// Number of active edges
|
||||
pub num_edges: u16,
|
||||
/// Number of connected components
|
||||
pub num_components: u16,
|
||||
/// Graph flags
|
||||
pub graph_flags: u16,
|
||||
|
||||
// --- Evidence state (8 bytes) ---
|
||||
/// Global log e-value (tile-local)
|
||||
pub log_e_value: LogEValue,
|
||||
/// Number of observations processed
|
||||
pub obs_count: u16,
|
||||
/// Number of rejected hypotheses
|
||||
pub rejected_count: u16,
|
||||
|
||||
// --- Witness fragment (16 bytes) ---
|
||||
/// Primary witness fragment
|
||||
pub witness: WitnessFragment,
|
||||
|
||||
// --- Performance metrics (8 bytes) ---
|
||||
/// Delta processing time (microseconds)
|
||||
pub delta_time_us: u16,
|
||||
/// Tick processing time (microseconds)
|
||||
pub tick_time_us: u16,
|
||||
/// Deltas processed this tick
|
||||
pub deltas_processed: u16,
|
||||
/// Memory usage (KB)
|
||||
pub memory_kb: u16,
|
||||
|
||||
// --- Cross-tile coordination (8 bytes) ---
|
||||
/// Number of ghost vertices
|
||||
pub ghost_vertices: u16,
|
||||
/// Number of ghost edges
|
||||
pub ghost_edges: u16,
|
||||
/// Boundary vertices (shared with other tiles)
|
||||
pub boundary_vertices: u16,
|
||||
/// Pending sync messages
|
||||
pub pending_sync: u16,
|
||||
|
||||
// --- Reserved for future use (8 bytes) ---
|
||||
/// Reserved fields
|
||||
pub _reserved: [u8; 8],
|
||||
}
|
||||
|
||||
impl Default for TileReport {
|
||||
fn default() -> Self {
|
||||
Self::new(0)
|
||||
}
|
||||
}
|
||||
|
||||
impl TileReport {
|
||||
/// Graph flag: graph is connected
|
||||
pub const GRAPH_CONNECTED: u16 = 0x0001;
|
||||
/// Graph flag: graph is dirty (needs recomputation)
|
||||
pub const GRAPH_DIRTY: u16 = 0x0002;
|
||||
/// Graph flag: graph is at capacity
|
||||
pub const GRAPH_FULL: u16 = 0x0004;
|
||||
/// Graph flag: graph has ghost edges
|
||||
pub const GRAPH_HAS_GHOSTS: u16 = 0x0008;
|
||||
|
||||
/// Create a new report for a tile
|
||||
#[inline]
|
||||
pub const fn new(tile_id: u8) -> Self {
|
||||
Self {
|
||||
tile_id,
|
||||
status: TileStatus::Idle,
|
||||
generation: 0,
|
||||
tick: 0,
|
||||
num_vertices: 0,
|
||||
num_edges: 0,
|
||||
num_components: 0,
|
||||
graph_flags: 0,
|
||||
log_e_value: 0,
|
||||
obs_count: 0,
|
||||
rejected_count: 0,
|
||||
witness: WitnessFragment {
|
||||
seed: 0,
|
||||
boundary_size: 0,
|
||||
cardinality: 0,
|
||||
hash: 0,
|
||||
local_min_cut: 0,
|
||||
component: 0,
|
||||
_reserved: 0,
|
||||
},
|
||||
delta_time_us: 0,
|
||||
tick_time_us: 0,
|
||||
deltas_processed: 0,
|
||||
memory_kb: 0,
|
||||
ghost_vertices: 0,
|
||||
ghost_edges: 0,
|
||||
boundary_vertices: 0,
|
||||
pending_sync: 0,
|
||||
_reserved: [0; 8],
|
||||
}
|
||||
}
|
||||
|
||||
/// Mark report as complete
|
||||
#[inline]
|
||||
pub fn set_complete(&mut self) {
|
||||
self.status = TileStatus::Complete;
|
||||
}
|
||||
|
||||
/// Mark report as error
|
||||
#[inline]
|
||||
pub fn set_error(&mut self) {
|
||||
self.status = TileStatus::Error;
|
||||
}
|
||||
|
||||
/// Set connected flag
|
||||
#[inline]
|
||||
pub fn set_connected(&mut self, connected: bool) {
|
||||
if connected {
|
||||
self.graph_flags |= Self::GRAPH_CONNECTED;
|
||||
} else {
|
||||
self.graph_flags &= !Self::GRAPH_CONNECTED;
|
||||
}
|
||||
}
|
||||
|
||||
/// Check if graph is connected
|
||||
#[inline]
|
||||
pub const fn is_connected(&self) -> bool {
|
||||
self.graph_flags & Self::GRAPH_CONNECTED != 0
|
||||
}
|
||||
|
||||
/// Check if graph is dirty
|
||||
#[inline]
|
||||
pub const fn is_dirty(&self) -> bool {
|
||||
self.graph_flags & Self::GRAPH_DIRTY != 0
|
||||
}
|
||||
|
||||
/// Get e-value as approximate f32
|
||||
pub fn e_value_approx(&self) -> f32 {
|
||||
let log2_val = (self.log_e_value as f32) / 65536.0;
|
||||
libm::exp2f(log2_val)
|
||||
}
|
||||
|
||||
/// Update witness fragment
|
||||
pub fn set_witness(&mut self, witness: WitnessFragment) {
|
||||
self.witness = witness;
|
||||
}
|
||||
|
||||
/// Get the witness fragment
|
||||
#[inline]
|
||||
pub const fn get_witness(&self) -> &WitnessFragment {
|
||||
&self.witness
|
||||
}
|
||||
|
||||
/// Check if tile has any rejections
|
||||
#[inline]
|
||||
pub const fn has_rejections(&self) -> bool {
|
||||
self.rejected_count > 0
|
||||
}
|
||||
|
||||
/// Get processing rate (deltas per microsecond)
|
||||
pub fn processing_rate(&self) -> f32 {
|
||||
if self.tick_time_us == 0 {
|
||||
0.0
|
||||
} else {
|
||||
(self.deltas_processed as f32) / (self.tick_time_us as f32)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Report aggregator for combining multiple tile reports
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C)]
|
||||
pub struct AggregatedReport {
|
||||
/// Total vertices across all tiles
|
||||
pub total_vertices: u32,
|
||||
/// Total edges across all tiles
|
||||
pub total_edges: u32,
|
||||
/// Total components across all tiles
|
||||
pub total_components: u16,
|
||||
/// Number of tiles reporting
|
||||
pub tiles_reporting: u16,
|
||||
/// Tiles with errors
|
||||
pub tiles_with_errors: u16,
|
||||
/// Tiles with rejections
|
||||
pub tiles_with_rejections: u16,
|
||||
/// Global log e-value (sum of tile e-values)
|
||||
pub global_log_e: i64,
|
||||
/// Minimum local cut across tiles
|
||||
pub global_min_cut: u16,
|
||||
/// Tile with minimum cut
|
||||
pub min_cut_tile: u8,
|
||||
/// Reserved padding
|
||||
pub _reserved: u8,
|
||||
/// Total processing time (microseconds)
|
||||
pub total_time_us: u32,
|
||||
/// Tick number
|
||||
pub tick: u32,
|
||||
}
|
||||
|
||||
impl AggregatedReport {
|
||||
/// Create a new aggregated report
|
||||
pub const fn new(tick: u32) -> Self {
|
||||
Self {
|
||||
total_vertices: 0,
|
||||
total_edges: 0,
|
||||
total_components: 0,
|
||||
tiles_reporting: 0,
|
||||
tiles_with_errors: 0,
|
||||
tiles_with_rejections: 0,
|
||||
global_log_e: 0,
|
||||
global_min_cut: u16::MAX,
|
||||
min_cut_tile: 0,
|
||||
_reserved: 0,
|
||||
total_time_us: 0,
|
||||
tick,
|
||||
}
|
||||
}
|
||||
|
||||
/// Merge a tile report into the aggregate
|
||||
pub fn merge(&mut self, report: &TileReport) {
|
||||
self.total_vertices += report.num_vertices as u32;
|
||||
self.total_edges += report.num_edges as u32;
|
||||
self.total_components += report.num_components;
|
||||
self.tiles_reporting += 1;
|
||||
|
||||
if report.status == TileStatus::Error {
|
||||
self.tiles_with_errors += 1;
|
||||
}
|
||||
|
||||
if report.rejected_count > 0 {
|
||||
self.tiles_with_rejections += 1;
|
||||
}
|
||||
|
||||
self.global_log_e += report.log_e_value as i64;
|
||||
|
||||
if report.witness.local_min_cut < self.global_min_cut {
|
||||
self.global_min_cut = report.witness.local_min_cut;
|
||||
self.min_cut_tile = report.tile_id;
|
||||
}
|
||||
|
||||
self.total_time_us = self.total_time_us.max(report.tick_time_us as u32);
|
||||
}
|
||||
|
||||
/// Check if all tiles completed successfully
|
||||
pub fn all_complete(&self, expected_tiles: u16) -> bool {
|
||||
self.tiles_reporting == expected_tiles && self.tiles_with_errors == 0
|
||||
}
|
||||
|
||||
/// Get global e-value as approximate f64
|
||||
pub fn global_e_value(&self) -> f64 {
|
||||
let log2_val = (self.global_log_e as f64) / 65536.0;
|
||||
libm::exp2(log2_val)
|
||||
}
|
||||
}
|
||||
|
||||
// Compile-time size assertions
|
||||
const _: () = assert!(
|
||||
size_of::<TileReport>() == 64,
|
||||
"TileReport must be exactly 64 bytes"
|
||||
);
|
||||
const _: () = assert!(
|
||||
size_of::<WitnessFragment>() == 16,
|
||||
"WitnessFragment must be 16 bytes"
|
||||
);
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_tile_report_size() {
|
||||
assert_eq!(size_of::<TileReport>(), 64);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tile_report_alignment() {
|
||||
assert_eq!(core::mem::align_of::<TileReport>(), 64);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_witness_fragment_size() {
|
||||
assert_eq!(size_of::<WitnessFragment>(), 16);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_new_report() {
|
||||
let report = TileReport::new(5);
|
||||
assert_eq!(report.tile_id, 5);
|
||||
assert_eq!(report.status, TileStatus::Idle);
|
||||
assert_eq!(report.tick, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_set_status() {
|
||||
let mut report = TileReport::new(0);
|
||||
report.set_complete();
|
||||
assert_eq!(report.status, TileStatus::Complete);
|
||||
|
||||
report.set_error();
|
||||
assert_eq!(report.status, TileStatus::Error);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_connected_flag() {
|
||||
let mut report = TileReport::new(0);
|
||||
assert!(!report.is_connected());
|
||||
|
||||
report.set_connected(true);
|
||||
assert!(report.is_connected());
|
||||
|
||||
report.set_connected(false);
|
||||
assert!(!report.is_connected());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_witness_fragment() {
|
||||
let mut frag = WitnessFragment::new(10, 5, 20, 100);
|
||||
assert_eq!(frag.seed, 10);
|
||||
assert_eq!(frag.boundary_size, 5);
|
||||
assert_eq!(frag.cardinality, 20);
|
||||
assert_eq!(frag.local_min_cut, 100);
|
||||
|
||||
frag.compute_hash();
|
||||
assert_ne!(frag.hash, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_aggregated_report() {
|
||||
let mut agg = AggregatedReport::new(1);
|
||||
|
||||
let mut report1 = TileReport::new(0);
|
||||
report1.num_vertices = 50;
|
||||
report1.num_edges = 100;
|
||||
report1.witness.local_min_cut = 200;
|
||||
|
||||
let mut report2 = TileReport::new(1);
|
||||
report2.num_vertices = 75;
|
||||
report2.num_edges = 150;
|
||||
report2.witness.local_min_cut = 150;
|
||||
|
||||
agg.merge(&report1);
|
||||
agg.merge(&report2);
|
||||
|
||||
assert_eq!(agg.tiles_reporting, 2);
|
||||
assert_eq!(agg.total_vertices, 125);
|
||||
assert_eq!(agg.total_edges, 250);
|
||||
assert_eq!(agg.global_min_cut, 150);
|
||||
assert_eq!(agg.min_cut_tile, 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tile_status_roundtrip() {
|
||||
for i in 0..=7 {
|
||||
let status = TileStatus::from(i);
|
||||
assert_eq!(status as u8, i);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_processing_rate() {
|
||||
let mut report = TileReport::new(0);
|
||||
report.deltas_processed = 100;
|
||||
report.tick_time_us = 50;
|
||||
|
||||
assert!((report.processing_rate() - 2.0).abs() < 0.01);
|
||||
}
|
||||
}
|
||||
982
crates/cognitum-gate-kernel/src/shard.rs
Normal file
982
crates/cognitum-gate-kernel/src/shard.rs
Normal file
@@ -0,0 +1,982 @@
|
||||
//! Compact graph shard for tile-local storage
|
||||
//!
|
||||
//! Implements a fixed-size graph representation optimized for WASM tiles.
|
||||
//! Each tile maintains a ~32KB graph shard with deterministic memory layout.
|
||||
//!
|
||||
//! ## Performance Optimizations
|
||||
//!
|
||||
//! This module is heavily optimized for hot paths:
|
||||
//! - `#[inline(always)]` on all accessors and flag checks
|
||||
//! - Unsafe unchecked array access where bounds are pre-validated
|
||||
//! - Cache-line aligned structures (64-byte alignment)
|
||||
//! - Fixed-point arithmetic (no floats in hot paths)
|
||||
//! - Zero allocations in tight loops
|
||||
|
||||
#![allow(missing_docs)]
|
||||
|
||||
use crate::delta::{FixedWeight, TileEdgeId, TileVertexId};
|
||||
use core::mem::size_of;
|
||||
|
||||
/// Cache line size for alignment (64 bytes on most modern CPUs)
|
||||
const CACHE_LINE_SIZE: usize = 64;
|
||||
|
||||
/// Maximum vertices per tile shard
|
||||
pub const MAX_SHARD_VERTICES: usize = 256;
|
||||
|
||||
/// Maximum edges per tile shard
|
||||
pub const MAX_SHARD_EDGES: usize = 1024;
|
||||
|
||||
/// Maximum neighbors per vertex (degree limit)
|
||||
pub const MAX_DEGREE: usize = 32;
|
||||
|
||||
/// Compact edge in shard storage
|
||||
///
|
||||
/// Size: 8 bytes, cache-friendly for sequential iteration
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C, align(8))]
|
||||
pub struct ShardEdge {
|
||||
/// Source vertex (tile-local)
|
||||
pub source: TileVertexId,
|
||||
/// Target vertex (tile-local)
|
||||
pub target: TileVertexId,
|
||||
/// Edge weight (fixed-point)
|
||||
pub weight: FixedWeight,
|
||||
/// Edge flags
|
||||
pub flags: u16,
|
||||
}
|
||||
|
||||
impl ShardEdge {
|
||||
/// Edge is active
|
||||
pub const FLAG_ACTIVE: u16 = 0x0001;
|
||||
/// Edge is in current cut
|
||||
pub const FLAG_IN_CUT: u16 = 0x0002;
|
||||
/// Edge is a tree edge in spanning forest
|
||||
pub const FLAG_TREE: u16 = 0x0004;
|
||||
/// Edge crosses tile boundary (ghost edge)
|
||||
pub const FLAG_GHOST: u16 = 0x0008;
|
||||
|
||||
/// Create a new active edge
|
||||
#[inline(always)]
|
||||
pub const fn new(source: TileVertexId, target: TileVertexId, weight: FixedWeight) -> Self {
|
||||
Self {
|
||||
source,
|
||||
target,
|
||||
weight,
|
||||
flags: Self::FLAG_ACTIVE,
|
||||
}
|
||||
}
|
||||
|
||||
/// Check if edge is active
|
||||
///
|
||||
/// OPTIMIZATION: #[inline(always)] - called in every iteration of edge loops
|
||||
#[inline(always)]
|
||||
pub const fn is_active(&self) -> bool {
|
||||
self.flags & Self::FLAG_ACTIVE != 0
|
||||
}
|
||||
|
||||
/// Check if edge is in cut
|
||||
///
|
||||
/// OPTIMIZATION: #[inline(always)] - called in mincut algorithms
|
||||
#[inline(always)]
|
||||
pub const fn is_in_cut(&self) -> bool {
|
||||
self.flags & Self::FLAG_IN_CUT != 0
|
||||
}
|
||||
|
||||
/// Check if edge is a tree edge
|
||||
#[inline(always)]
|
||||
pub const fn is_tree(&self) -> bool {
|
||||
self.flags & Self::FLAG_TREE != 0
|
||||
}
|
||||
|
||||
/// Check if edge is a ghost edge
|
||||
#[inline(always)]
|
||||
pub const fn is_ghost(&self) -> bool {
|
||||
self.flags & Self::FLAG_GHOST != 0
|
||||
}
|
||||
|
||||
/// Mark edge as inactive (deleted)
|
||||
#[inline(always)]
|
||||
pub fn deactivate(&mut self) {
|
||||
self.flags &= !Self::FLAG_ACTIVE;
|
||||
}
|
||||
|
||||
/// Mark edge as in cut
|
||||
#[inline(always)]
|
||||
pub fn mark_in_cut(&mut self) {
|
||||
self.flags |= Self::FLAG_IN_CUT;
|
||||
}
|
||||
|
||||
/// Clear cut membership
|
||||
#[inline(always)]
|
||||
pub fn clear_cut(&mut self) {
|
||||
self.flags &= !Self::FLAG_IN_CUT;
|
||||
}
|
||||
}
|
||||
|
||||
/// Vertex adjacency entry
|
||||
///
|
||||
/// Size: 8 bytes, aligned for efficient access
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C, align(8))]
|
||||
pub struct VertexEntry {
|
||||
/// Degree (number of active neighbors)
|
||||
pub degree: u8,
|
||||
/// Vertex flags
|
||||
pub flags: u8,
|
||||
/// Component ID (for connectivity tracking)
|
||||
pub component: u16,
|
||||
/// First edge index in adjacency list
|
||||
pub first_edge_idx: u16,
|
||||
/// Reserved for alignment
|
||||
pub _reserved: u16,
|
||||
}
|
||||
|
||||
impl VertexEntry {
|
||||
/// Vertex is active
|
||||
pub const FLAG_ACTIVE: u8 = 0x01;
|
||||
/// Vertex is on cut boundary
|
||||
pub const FLAG_BOUNDARY: u8 = 0x02;
|
||||
/// Vertex side in partition (0 or 1)
|
||||
pub const FLAG_SIDE: u8 = 0x04;
|
||||
/// Vertex is a ghost (owned by another tile)
|
||||
pub const FLAG_GHOST: u8 = 0x08;
|
||||
|
||||
/// Create a new active vertex
|
||||
#[inline(always)]
|
||||
pub const fn new() -> Self {
|
||||
Self {
|
||||
degree: 0,
|
||||
flags: Self::FLAG_ACTIVE,
|
||||
component: 0,
|
||||
first_edge_idx: 0xFFFF, // Invalid index
|
||||
_reserved: 0,
|
||||
}
|
||||
}
|
||||
|
||||
/// Check if vertex is active
|
||||
///
|
||||
/// OPTIMIZATION: #[inline(always)] - called in every vertex iteration
|
||||
#[inline(always)]
|
||||
pub const fn is_active(&self) -> bool {
|
||||
self.flags & Self::FLAG_ACTIVE != 0
|
||||
}
|
||||
|
||||
/// Get partition side (0 or 1)
|
||||
///
|
||||
/// OPTIMIZATION: Branchless version using bit manipulation
|
||||
#[inline(always)]
|
||||
pub const fn side(&self) -> u8 {
|
||||
// Branchless: extract bit 2, shift to position 0
|
||||
(self.flags & Self::FLAG_SIDE) >> 2
|
||||
}
|
||||
|
||||
/// Set partition side
|
||||
///
|
||||
/// OPTIMIZATION: Branchless flag update
|
||||
#[inline(always)]
|
||||
pub fn set_side(&mut self, side: u8) {
|
||||
// Branchless: clear flag, then set if side != 0
|
||||
self.flags = (self.flags & !Self::FLAG_SIDE) | ((side & 1) << 2);
|
||||
}
|
||||
}
|
||||
|
||||
/// Adjacency list entry (neighbor + edge reference)
|
||||
#[derive(Debug, Clone, Copy, Default)]
|
||||
#[repr(C)]
|
||||
pub struct AdjEntry {
|
||||
/// Neighbor vertex ID
|
||||
pub neighbor: TileVertexId,
|
||||
/// Edge ID in edge array
|
||||
pub edge_id: TileEdgeId,
|
||||
}
|
||||
|
||||
/// Compact graph shard for tile-local storage
|
||||
///
|
||||
/// Memory layout (~32KB total):
|
||||
/// - Vertex entries: 256 * 8 = 2KB
|
||||
/// - Edge storage: 1024 * 8 = 8KB
|
||||
/// - Adjacency lists: 256 * 32 * 4 = 32KB
|
||||
/// Total: ~42KB (fits in 64KB tile budget with room for other state)
|
||||
///
|
||||
/// OPTIMIZATION: Cache-line aligned (64 bytes) for efficient CPU cache usage.
|
||||
/// Hot fields (num_vertices, num_edges, status) are grouped together.
|
||||
///
|
||||
/// Note: Actual size is optimized by packing adjacency lists more efficiently.
|
||||
#[repr(C, align(64))]
|
||||
pub struct CompactGraph {
|
||||
// === HOT FIELDS (first cache line) ===
|
||||
/// Number of active vertices
|
||||
pub num_vertices: u16,
|
||||
/// Number of active edges
|
||||
pub num_edges: u16,
|
||||
/// Free edge list head (for reuse)
|
||||
pub free_edge_head: u16,
|
||||
/// Graph generation (incremented on structural changes)
|
||||
pub generation: u16,
|
||||
/// Component count
|
||||
pub num_components: u16,
|
||||
/// Status flags
|
||||
pub status: u16,
|
||||
/// Padding to fill cache line
|
||||
_hot_pad: [u8; 52],
|
||||
|
||||
// === COLD FIELDS (subsequent cache lines) ===
|
||||
/// Vertex metadata array
|
||||
pub vertices: [VertexEntry; MAX_SHARD_VERTICES],
|
||||
/// Edge storage array
|
||||
pub edges: [ShardEdge; MAX_SHARD_EDGES],
|
||||
/// Packed adjacency lists
|
||||
/// Layout: for each vertex, up to MAX_DEGREE neighbors
|
||||
pub adjacency: [[AdjEntry; MAX_DEGREE]; MAX_SHARD_VERTICES],
|
||||
}
|
||||
|
||||
impl Default for CompactGraph {
|
||||
#[inline]
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
impl CompactGraph {
|
||||
/// Status: graph is valid
|
||||
pub const STATUS_VALID: u16 = 0x0001;
|
||||
/// Status: graph needs recomputation
|
||||
pub const STATUS_DIRTY: u16 = 0x0002;
|
||||
/// Status: graph is connected
|
||||
pub const STATUS_CONNECTED: u16 = 0x0004;
|
||||
|
||||
/// Create a new empty graph
|
||||
pub const fn new() -> Self {
|
||||
Self {
|
||||
num_vertices: 0,
|
||||
num_edges: 0,
|
||||
free_edge_head: 0xFFFF,
|
||||
generation: 0,
|
||||
num_components: 0,
|
||||
status: Self::STATUS_VALID,
|
||||
_hot_pad: [0; 52],
|
||||
vertices: [VertexEntry {
|
||||
degree: 0,
|
||||
flags: 0, // Start inactive
|
||||
component: 0,
|
||||
first_edge_idx: 0xFFFF,
|
||||
_reserved: 0,
|
||||
}; MAX_SHARD_VERTICES],
|
||||
edges: [ShardEdge {
|
||||
source: 0,
|
||||
target: 0,
|
||||
weight: 0,
|
||||
flags: 0,
|
||||
}; MAX_SHARD_EDGES],
|
||||
adjacency: [[AdjEntry {
|
||||
neighbor: 0,
|
||||
edge_id: 0,
|
||||
}; MAX_DEGREE]; MAX_SHARD_VERTICES],
|
||||
}
|
||||
}
|
||||
|
||||
/// Clear the graph
|
||||
pub fn clear(&mut self) {
|
||||
for v in self.vertices.iter_mut() {
|
||||
*v = VertexEntry::new();
|
||||
v.flags = 0; // Mark as inactive
|
||||
}
|
||||
for e in self.edges.iter_mut() {
|
||||
e.flags = 0;
|
||||
}
|
||||
self.num_vertices = 0;
|
||||
self.num_edges = 0;
|
||||
self.free_edge_head = 0xFFFF;
|
||||
self.generation = self.generation.wrapping_add(1);
|
||||
self.num_components = 0;
|
||||
self.status = Self::STATUS_VALID | Self::STATUS_DIRTY;
|
||||
}
|
||||
|
||||
/// Add or activate a vertex
|
||||
pub fn add_vertex(&mut self, v: TileVertexId) -> bool {
|
||||
if v as usize >= MAX_SHARD_VERTICES {
|
||||
return false;
|
||||
}
|
||||
|
||||
let entry = &mut self.vertices[v as usize];
|
||||
if entry.is_active() {
|
||||
return false; // Already active
|
||||
}
|
||||
|
||||
entry.flags = VertexEntry::FLAG_ACTIVE;
|
||||
entry.degree = 0;
|
||||
entry.component = 0;
|
||||
entry.first_edge_idx = 0xFFFF;
|
||||
self.num_vertices += 1;
|
||||
self.status |= Self::STATUS_DIRTY;
|
||||
true
|
||||
}
|
||||
|
||||
/// Remove a vertex (marks as inactive)
|
||||
pub fn remove_vertex(&mut self, v: TileVertexId) -> bool {
|
||||
if v as usize >= MAX_SHARD_VERTICES {
|
||||
return false;
|
||||
}
|
||||
|
||||
let entry = &mut self.vertices[v as usize];
|
||||
if !entry.is_active() {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Deactivate all incident edges
|
||||
for i in 0..entry.degree as usize {
|
||||
let adj = &self.adjacency[v as usize][i];
|
||||
if adj.edge_id < MAX_SHARD_EDGES as u16 {
|
||||
self.edges[adj.edge_id as usize].deactivate();
|
||||
self.num_edges = self.num_edges.saturating_sub(1);
|
||||
}
|
||||
}
|
||||
|
||||
entry.flags = 0;
|
||||
entry.degree = 0;
|
||||
self.num_vertices = self.num_vertices.saturating_sub(1);
|
||||
self.status |= Self::STATUS_DIRTY;
|
||||
self.generation = self.generation.wrapping_add(1);
|
||||
true
|
||||
}
|
||||
|
||||
/// Add an edge between two vertices
|
||||
pub fn add_edge(
|
||||
&mut self,
|
||||
source: TileVertexId,
|
||||
target: TileVertexId,
|
||||
weight: FixedWeight,
|
||||
) -> Option<TileEdgeId> {
|
||||
// Validate vertices
|
||||
if source as usize >= MAX_SHARD_VERTICES || target as usize >= MAX_SHARD_VERTICES {
|
||||
return None;
|
||||
}
|
||||
if source == target {
|
||||
return None; // No self-loops
|
||||
}
|
||||
|
||||
// Ensure vertices are active
|
||||
if !self.vertices[source as usize].is_active() {
|
||||
self.add_vertex(source);
|
||||
}
|
||||
if !self.vertices[target as usize].is_active() {
|
||||
self.add_vertex(target);
|
||||
}
|
||||
|
||||
// Check degree limits
|
||||
let src_entry = &self.vertices[source as usize];
|
||||
let tgt_entry = &self.vertices[target as usize];
|
||||
if src_entry.degree as usize >= MAX_DEGREE || tgt_entry.degree as usize >= MAX_DEGREE {
|
||||
return None;
|
||||
}
|
||||
|
||||
// Allocate edge slot
|
||||
let edge_id = self.allocate_edge()?;
|
||||
|
||||
// Create edge
|
||||
self.edges[edge_id as usize] = ShardEdge::new(source, target, weight);
|
||||
|
||||
// Update adjacency lists
|
||||
let src_deg = self.vertices[source as usize].degree as usize;
|
||||
self.adjacency[source as usize][src_deg] = AdjEntry {
|
||||
neighbor: target,
|
||||
edge_id,
|
||||
};
|
||||
self.vertices[source as usize].degree += 1;
|
||||
|
||||
let tgt_deg = self.vertices[target as usize].degree as usize;
|
||||
self.adjacency[target as usize][tgt_deg] = AdjEntry {
|
||||
neighbor: source,
|
||||
edge_id,
|
||||
};
|
||||
self.vertices[target as usize].degree += 1;
|
||||
|
||||
self.num_edges += 1;
|
||||
self.status |= Self::STATUS_DIRTY;
|
||||
self.generation = self.generation.wrapping_add(1);
|
||||
|
||||
Some(edge_id)
|
||||
}
|
||||
|
||||
/// Remove an edge
|
||||
pub fn remove_edge(&mut self, source: TileVertexId, target: TileVertexId) -> bool {
|
||||
// Find edge in source's adjacency
|
||||
let edge_id = self.find_edge(source, target);
|
||||
if edge_id.is_none() {
|
||||
return false;
|
||||
}
|
||||
let edge_id = edge_id.unwrap();
|
||||
|
||||
// Deactivate edge
|
||||
self.edges[edge_id as usize].deactivate();
|
||||
|
||||
// Remove from adjacency lists (swap-remove pattern)
|
||||
self.remove_from_adjacency(source, target, edge_id);
|
||||
self.remove_from_adjacency(target, source, edge_id);
|
||||
|
||||
// Add to free list
|
||||
self.free_edge(edge_id);
|
||||
|
||||
self.num_edges = self.num_edges.saturating_sub(1);
|
||||
self.status |= Self::STATUS_DIRTY;
|
||||
self.generation = self.generation.wrapping_add(1);
|
||||
true
|
||||
}
|
||||
|
||||
/// Update edge weight
|
||||
pub fn update_weight(
|
||||
&mut self,
|
||||
source: TileVertexId,
|
||||
target: TileVertexId,
|
||||
new_weight: FixedWeight,
|
||||
) -> bool {
|
||||
if let Some(edge_id) = self.find_edge(source, target) {
|
||||
self.edges[edge_id as usize].weight = new_weight;
|
||||
self.status |= Self::STATUS_DIRTY;
|
||||
true
|
||||
} else {
|
||||
false
|
||||
}
|
||||
}
|
||||
|
||||
/// Find edge between two vertices
|
||||
///
|
||||
/// OPTIMIZATION: Uses unsafe unchecked access after bounds validation.
|
||||
/// The adjacency scan is a hot path in graph algorithms.
|
||||
#[inline]
|
||||
pub fn find_edge(&self, source: TileVertexId, target: TileVertexId) -> Option<TileEdgeId> {
|
||||
if source as usize >= MAX_SHARD_VERTICES {
|
||||
return None;
|
||||
}
|
||||
|
||||
// SAFETY: source bounds checked above
|
||||
let entry = unsafe { self.vertices.get_unchecked(source as usize) };
|
||||
if !entry.is_active() {
|
||||
return None;
|
||||
}
|
||||
|
||||
let degree = entry.degree as usize;
|
||||
// SAFETY: source bounds checked, degree <= MAX_DEGREE by invariant
|
||||
let adj_list = unsafe { self.adjacency.get_unchecked(source as usize) };
|
||||
|
||||
for i in 0..degree {
|
||||
// SAFETY: i < degree <= MAX_DEGREE
|
||||
let adj = unsafe { adj_list.get_unchecked(i) };
|
||||
if adj.neighbor == target {
|
||||
return Some(adj.edge_id);
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
/// Find edge between two vertices (unchecked version)
|
||||
///
|
||||
/// SAFETY: Caller must ensure source < MAX_SHARD_VERTICES and vertex is active
|
||||
#[inline(always)]
|
||||
pub unsafe fn find_edge_unchecked(
|
||||
&self,
|
||||
source: TileVertexId,
|
||||
target: TileVertexId,
|
||||
) -> Option<TileEdgeId> {
|
||||
unsafe {
|
||||
let entry = self.vertices.get_unchecked(source as usize);
|
||||
let degree = entry.degree as usize;
|
||||
let adj_list = self.adjacency.get_unchecked(source as usize);
|
||||
|
||||
for i in 0..degree {
|
||||
let adj = adj_list.get_unchecked(i);
|
||||
if adj.neighbor == target {
|
||||
return Some(adj.edge_id);
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
}
|
||||
|
||||
/// Get edge weight
|
||||
pub fn edge_weight(&self, source: TileVertexId, target: TileVertexId) -> Option<FixedWeight> {
|
||||
self.find_edge(source, target)
|
||||
.map(|eid| self.edges[eid as usize].weight)
|
||||
}
|
||||
|
||||
/// Get vertex degree
|
||||
///
|
||||
/// OPTIMIZATION: Uses unsafe unchecked access after bounds check
|
||||
#[inline(always)]
|
||||
pub fn degree(&self, v: TileVertexId) -> u8 {
|
||||
if v as usize >= MAX_SHARD_VERTICES {
|
||||
return 0;
|
||||
}
|
||||
// SAFETY: bounds checked above
|
||||
let entry = unsafe { self.vertices.get_unchecked(v as usize) };
|
||||
if entry.is_active() {
|
||||
entry.degree
|
||||
} else {
|
||||
0
|
||||
}
|
||||
}
|
||||
|
||||
/// Get neighbors of a vertex
|
||||
///
|
||||
/// OPTIMIZATION: Uses unsafe unchecked slice creation after bounds check
|
||||
#[inline]
|
||||
pub fn neighbors(&self, v: TileVertexId) -> &[AdjEntry] {
|
||||
if v as usize >= MAX_SHARD_VERTICES {
|
||||
return &[];
|
||||
}
|
||||
// SAFETY: bounds checked above
|
||||
let entry = unsafe { self.vertices.get_unchecked(v as usize) };
|
||||
if !entry.is_active() {
|
||||
return &[];
|
||||
}
|
||||
let degree = entry.degree as usize;
|
||||
// SAFETY: bounds checked, degree <= MAX_DEGREE by invariant
|
||||
unsafe {
|
||||
self.adjacency
|
||||
.get_unchecked(v as usize)
|
||||
.get_unchecked(..degree)
|
||||
}
|
||||
}
|
||||
|
||||
/// Get neighbors of a vertex (unchecked version)
|
||||
///
|
||||
/// SAFETY: Caller must ensure v < MAX_SHARD_VERTICES and vertex is active
|
||||
#[inline(always)]
|
||||
pub unsafe fn neighbors_unchecked(&self, v: TileVertexId) -> &[AdjEntry] {
|
||||
unsafe {
|
||||
let entry = self.vertices.get_unchecked(v as usize);
|
||||
let degree = entry.degree as usize;
|
||||
self.adjacency
|
||||
.get_unchecked(v as usize)
|
||||
.get_unchecked(..degree)
|
||||
}
|
||||
}
|
||||
|
||||
/// Check if graph is connected (cached, call recompute_components first)
|
||||
#[inline]
|
||||
pub fn is_connected(&self) -> bool {
|
||||
self.status & Self::STATUS_CONNECTED != 0
|
||||
}
|
||||
|
||||
/// Compute connected components using union-find
|
||||
///
|
||||
/// OPTIMIZATION: Uses iterative path compression (no recursion),
|
||||
/// unsafe unchecked access, and processes only active edges.
|
||||
pub fn recompute_components(&mut self) -> u16 {
|
||||
// Simple union-find with path compression
|
||||
let mut parent = [0u16; MAX_SHARD_VERTICES];
|
||||
let mut rank = [0u8; MAX_SHARD_VERTICES];
|
||||
|
||||
// Initialize parent array
|
||||
// OPTIMIZATION: Unrolled initialization
|
||||
for i in 0..MAX_SHARD_VERTICES {
|
||||
parent[i] = i as u16;
|
||||
}
|
||||
|
||||
// Find with iterative path compression (no recursion overhead)
|
||||
// OPTIMIZATION: Iterative instead of recursive, unsafe unchecked access
|
||||
#[inline(always)]
|
||||
fn find(parent: &mut [u16; MAX_SHARD_VERTICES], mut x: u16) -> u16 {
|
||||
// Find root
|
||||
let mut root = x;
|
||||
// SAFETY: x < MAX_SHARD_VERTICES by construction
|
||||
while unsafe { *parent.get_unchecked(root as usize) } != root {
|
||||
root = unsafe { *parent.get_unchecked(root as usize) };
|
||||
}
|
||||
// Path compression
|
||||
while x != root {
|
||||
let next = unsafe { *parent.get_unchecked(x as usize) };
|
||||
unsafe { *parent.get_unchecked_mut(x as usize) = root };
|
||||
x = next;
|
||||
}
|
||||
root
|
||||
}
|
||||
|
||||
// Union by rank
|
||||
// OPTIMIZATION: Inlined, uses unsafe unchecked access
|
||||
#[inline(always)]
|
||||
fn union(
|
||||
parent: &mut [u16; MAX_SHARD_VERTICES],
|
||||
rank: &mut [u8; MAX_SHARD_VERTICES],
|
||||
x: u16,
|
||||
y: u16,
|
||||
) {
|
||||
let px = find(parent, x);
|
||||
let py = find(parent, y);
|
||||
if px == py {
|
||||
return;
|
||||
}
|
||||
// SAFETY: px, py < MAX_SHARD_VERTICES by construction
|
||||
unsafe {
|
||||
let rpx = *rank.get_unchecked(px as usize);
|
||||
let rpy = *rank.get_unchecked(py as usize);
|
||||
if rpx < rpy {
|
||||
*parent.get_unchecked_mut(px as usize) = py;
|
||||
} else if rpx > rpy {
|
||||
*parent.get_unchecked_mut(py as usize) = px;
|
||||
} else {
|
||||
*parent.get_unchecked_mut(py as usize) = px;
|
||||
*rank.get_unchecked_mut(px as usize) = rpx + 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Process edges - only iterate up to num_edges for early termination
|
||||
// OPTIMIZATION: Use pointer iteration for better codegen
|
||||
for edge in self.edges.iter() {
|
||||
if edge.is_active() {
|
||||
union(&mut parent, &mut rank, edge.source, edge.target);
|
||||
}
|
||||
}
|
||||
|
||||
// Count components and assign component IDs
|
||||
let mut component_count = 0u16;
|
||||
let mut component_map = [0xFFFFu16; MAX_SHARD_VERTICES];
|
||||
|
||||
for i in 0..MAX_SHARD_VERTICES {
|
||||
// SAFETY: i < MAX_SHARD_VERTICES
|
||||
let vertex = unsafe { self.vertices.get_unchecked_mut(i) };
|
||||
if vertex.is_active() {
|
||||
let root = find(&mut parent, i as u16);
|
||||
// SAFETY: root < MAX_SHARD_VERTICES
|
||||
let mapped = unsafe { *component_map.get_unchecked(root as usize) };
|
||||
if mapped == 0xFFFF {
|
||||
unsafe { *component_map.get_unchecked_mut(root as usize) = component_count };
|
||||
vertex.component = component_count;
|
||||
component_count += 1;
|
||||
} else {
|
||||
vertex.component = mapped;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
self.num_components = component_count;
|
||||
if component_count <= 1 && self.num_vertices > 0 {
|
||||
self.status |= Self::STATUS_CONNECTED;
|
||||
} else {
|
||||
self.status &= !Self::STATUS_CONNECTED;
|
||||
}
|
||||
self.status &= !Self::STATUS_DIRTY;
|
||||
|
||||
component_count
|
||||
}
|
||||
|
||||
/// Allocate an edge slot
|
||||
fn allocate_edge(&mut self) -> Option<TileEdgeId> {
|
||||
// First, try free list
|
||||
if self.free_edge_head != 0xFFFF {
|
||||
let edge_id = self.free_edge_head;
|
||||
// Read next from free list (stored in source field of inactive edge)
|
||||
self.free_edge_head = self.edges[edge_id as usize].source;
|
||||
return Some(edge_id);
|
||||
}
|
||||
|
||||
// Otherwise, find first inactive edge
|
||||
for i in 0..MAX_SHARD_EDGES {
|
||||
if !self.edges[i].is_active() {
|
||||
return Some(i as TileEdgeId);
|
||||
}
|
||||
}
|
||||
|
||||
None // No space
|
||||
}
|
||||
|
||||
/// Return edge to free list
|
||||
fn free_edge(&mut self, edge_id: TileEdgeId) {
|
||||
// Use source field to store next pointer
|
||||
self.edges[edge_id as usize].source = self.free_edge_head;
|
||||
self.free_edge_head = edge_id;
|
||||
}
|
||||
|
||||
/// Remove from adjacency list using swap-remove
|
||||
fn remove_from_adjacency(
|
||||
&mut self,
|
||||
v: TileVertexId,
|
||||
neighbor: TileVertexId,
|
||||
edge_id: TileEdgeId,
|
||||
) {
|
||||
if v as usize >= MAX_SHARD_VERTICES {
|
||||
return;
|
||||
}
|
||||
let degree = self.vertices[v as usize].degree as usize;
|
||||
|
||||
for i in 0..degree {
|
||||
if self.adjacency[v as usize][i].neighbor == neighbor
|
||||
&& self.adjacency[v as usize][i].edge_id == edge_id
|
||||
{
|
||||
// Swap with last
|
||||
if i < degree - 1 {
|
||||
self.adjacency[v as usize][i] = self.adjacency[v as usize][degree - 1];
|
||||
}
|
||||
self.vertices[v as usize].degree -= 1;
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Get memory size of the graph structure
|
||||
pub const fn memory_size() -> usize {
|
||||
size_of::<Self>()
|
||||
}
|
||||
|
||||
// ========================================================================
|
||||
// CACHE-FRIENDLY OPTIMIZATIONS
|
||||
// ========================================================================
|
||||
|
||||
/// Iterate over active vertices with cache-prefetching
|
||||
///
|
||||
/// OPTIMIZATION: Uses software prefetching hints to reduce cache misses
|
||||
/// when iterating over vertices sequentially.
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `f` - Callback function receiving (vertex_id, degree, component)
|
||||
#[inline]
|
||||
pub fn for_each_active_vertex<F>(&self, mut f: F)
|
||||
where
|
||||
F: FnMut(TileVertexId, u8, u16),
|
||||
{
|
||||
// Process vertices in cache-line-sized chunks
|
||||
const CHUNK_SIZE: usize = 8; // 8 * 8 bytes = 64 bytes = 1 cache line
|
||||
|
||||
for chunk_start in (0..MAX_SHARD_VERTICES).step_by(CHUNK_SIZE) {
|
||||
// Process current chunk
|
||||
let chunk_end = (chunk_start + CHUNK_SIZE).min(MAX_SHARD_VERTICES);
|
||||
|
||||
for i in chunk_start..chunk_end {
|
||||
// SAFETY: i < MAX_SHARD_VERTICES by loop bounds
|
||||
let entry = unsafe { self.vertices.get_unchecked(i) };
|
||||
if entry.is_active() {
|
||||
f(i as TileVertexId, entry.degree, entry.component);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Iterate over active edges with cache-prefetching
|
||||
///
|
||||
/// OPTIMIZATION: Processes edges in cache-line order for better locality.
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `f` - Callback receiving (edge_id, source, target, weight)
|
||||
#[inline]
|
||||
pub fn for_each_active_edge<F>(&self, mut f: F)
|
||||
where
|
||||
F: FnMut(TileEdgeId, TileVertexId, TileVertexId, FixedWeight),
|
||||
{
|
||||
// Process edges in cache-line-sized chunks (8 edges = 64 bytes)
|
||||
const CHUNK_SIZE: usize = 8;
|
||||
|
||||
for chunk_start in (0..MAX_SHARD_EDGES).step_by(CHUNK_SIZE) {
|
||||
let chunk_end = (chunk_start + CHUNK_SIZE).min(MAX_SHARD_EDGES);
|
||||
|
||||
for i in chunk_start..chunk_end {
|
||||
let edge = &self.edges[i];
|
||||
if edge.is_active() {
|
||||
f(i as TileEdgeId, edge.source, edge.target, edge.weight);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Batch add multiple edges for improved throughput
|
||||
///
|
||||
/// OPTIMIZATION: Reduces per-edge overhead by batching operations:
|
||||
/// - Single dirty flag update
|
||||
/// - Deferred component recomputation
|
||||
/// - Better cache utilization
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `edges` - Slice of (source, target, weight) tuples
|
||||
///
|
||||
/// # Returns
|
||||
/// Number of successfully added edges
|
||||
#[inline]
|
||||
pub fn add_edges_batch(
|
||||
&mut self,
|
||||
edges: &[(TileVertexId, TileVertexId, FixedWeight)],
|
||||
) -> usize {
|
||||
let mut added = 0usize;
|
||||
|
||||
for &(source, target, weight) in edges {
|
||||
if self.add_edge(source, target, weight).is_some() {
|
||||
added += 1;
|
||||
}
|
||||
}
|
||||
|
||||
// Single generation increment for batch
|
||||
if added > 0 {
|
||||
self.generation = self.generation.wrapping_add(1);
|
||||
}
|
||||
|
||||
added
|
||||
}
|
||||
|
||||
/// Get edge weights as a contiguous slice for SIMD processing
|
||||
///
|
||||
/// OPTIMIZATION: Returns a view of edge weights suitable for
|
||||
/// SIMD operations (e.g., computing total weight, min/max).
|
||||
///
|
||||
/// # Returns
|
||||
/// Iterator of weights from active edges
|
||||
#[inline]
|
||||
pub fn active_edge_weights(&self) -> impl Iterator<Item = FixedWeight> + '_ {
|
||||
self.edges
|
||||
.iter()
|
||||
.filter(|e| e.is_active())
|
||||
.map(|e| e.weight)
|
||||
}
|
||||
|
||||
/// Compute total edge weight using SIMD-friendly accumulation
|
||||
///
|
||||
/// OPTIMIZATION: Uses parallel lane accumulation for better vectorization.
|
||||
#[inline]
|
||||
pub fn total_weight_simd(&self) -> u64 {
|
||||
let mut lanes = [0u64; 4];
|
||||
|
||||
for (i, edge) in self.edges.iter().enumerate() {
|
||||
if edge.is_active() {
|
||||
lanes[i % 4] += edge.weight as u64;
|
||||
}
|
||||
}
|
||||
|
||||
lanes[0] + lanes[1] + lanes[2] + lanes[3]
|
||||
}
|
||||
|
||||
/// Find minimum degree vertex efficiently
|
||||
///
|
||||
/// OPTIMIZATION: Uses branch prediction hints and early exit
|
||||
/// for finding cut boundary candidates.
|
||||
///
|
||||
/// # Returns
|
||||
/// (vertex_id, degree) of minimum degree active vertex, or None
|
||||
#[inline]
|
||||
pub fn min_degree_vertex(&self) -> Option<(TileVertexId, u8)> {
|
||||
let mut min_v: Option<TileVertexId> = None;
|
||||
let mut min_deg = u8::MAX;
|
||||
|
||||
for i in 0..MAX_SHARD_VERTICES {
|
||||
let entry = &self.vertices[i];
|
||||
// Likely hint: most vertices are inactive in sparse graphs
|
||||
if entry.is_active() && entry.degree > 0 && entry.degree < min_deg {
|
||||
min_deg = entry.degree;
|
||||
min_v = Some(i as TileVertexId);
|
||||
|
||||
// Early exit: can't do better than degree 1
|
||||
if min_deg == 1 {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
min_v.map(|v| (v, min_deg))
|
||||
}
|
||||
}
|
||||
|
||||
// Compile-time size assertions
|
||||
const _: () = assert!(size_of::<ShardEdge>() == 8, "ShardEdge must be 8 bytes");
|
||||
const _: () = assert!(size_of::<VertexEntry>() == 8, "VertexEntry must be 8 bytes");
|
||||
const _: () = assert!(size_of::<AdjEntry>() == 4, "AdjEntry must be 4 bytes");
|
||||
// Note: CompactGraph is ~42KB which fits in our 64KB tile budget
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_new_graph() {
|
||||
let g = CompactGraph::new();
|
||||
assert_eq!(g.num_vertices, 0);
|
||||
assert_eq!(g.num_edges, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_add_vertex() {
|
||||
let mut g = CompactGraph::new();
|
||||
assert!(g.add_vertex(0));
|
||||
assert!(g.add_vertex(1));
|
||||
assert!(!g.add_vertex(0)); // Already exists
|
||||
assert_eq!(g.num_vertices, 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_add_edge() {
|
||||
let mut g = CompactGraph::new();
|
||||
let edge_id = g.add_edge(0, 1, 100);
|
||||
assert!(edge_id.is_some());
|
||||
assert_eq!(g.num_edges, 1);
|
||||
assert_eq!(g.num_vertices, 2);
|
||||
assert_eq!(g.degree(0), 1);
|
||||
assert_eq!(g.degree(1), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_find_edge() {
|
||||
let mut g = CompactGraph::new();
|
||||
g.add_edge(0, 1, 100);
|
||||
assert!(g.find_edge(0, 1).is_some());
|
||||
assert!(g.find_edge(1, 0).is_some());
|
||||
assert!(g.find_edge(0, 2).is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_remove_edge() {
|
||||
let mut g = CompactGraph::new();
|
||||
g.add_edge(0, 1, 100);
|
||||
assert!(g.remove_edge(0, 1));
|
||||
assert_eq!(g.num_edges, 0);
|
||||
assert_eq!(g.degree(0), 0);
|
||||
assert_eq!(g.degree(1), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_update_weight() {
|
||||
let mut g = CompactGraph::new();
|
||||
g.add_edge(0, 1, 100);
|
||||
assert!(g.update_weight(0, 1, 200));
|
||||
assert_eq!(g.edge_weight(0, 1), Some(200));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_neighbors() {
|
||||
let mut g = CompactGraph::new();
|
||||
g.add_edge(0, 1, 100);
|
||||
g.add_edge(0, 2, 200);
|
||||
g.add_edge(0, 3, 300);
|
||||
|
||||
let neighbors = g.neighbors(0);
|
||||
assert_eq!(neighbors.len(), 3);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_connected_components() {
|
||||
let mut g = CompactGraph::new();
|
||||
// Component 1: 0-1-2
|
||||
g.add_edge(0, 1, 100);
|
||||
g.add_edge(1, 2, 100);
|
||||
// Component 2: 3-4
|
||||
g.add_edge(3, 4, 100);
|
||||
|
||||
let count = g.recompute_components();
|
||||
assert_eq!(count, 2);
|
||||
assert!(!g.is_connected());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_connected_graph() {
|
||||
let mut g = CompactGraph::new();
|
||||
g.add_edge(0, 1, 100);
|
||||
g.add_edge(1, 2, 100);
|
||||
g.add_edge(2, 0, 100);
|
||||
|
||||
let count = g.recompute_components();
|
||||
assert_eq!(count, 1);
|
||||
assert!(g.is_connected());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_memory_size() {
|
||||
// Verify our memory budget
|
||||
let size = CompactGraph::memory_size();
|
||||
assert!(size <= 65536, "CompactGraph exceeds 64KB: {} bytes", size);
|
||||
}
|
||||
}
|
||||
86
crates/cognitum-gate-kernel/tests/canonical_witness_bench.rs
Normal file
86
crates/cognitum-gate-kernel/tests/canonical_witness_bench.rs
Normal file
@@ -0,0 +1,86 @@
|
||||
//! Performance benchmark for canonical witness fragments.
|
||||
//! Run with: cargo test -p cognitum-gate-kernel --features "std,canonical-witness" --test canonical_witness_bench --release -- --nocapture
|
||||
|
||||
#[cfg(feature = "canonical-witness")]
|
||||
mod bench {
|
||||
use cognitum_gate_kernel::canonical_witness::{ArenaCactus, CanonicalWitnessFragment};
|
||||
use cognitum_gate_kernel::shard::CompactGraph;
|
||||
use cognitum_gate_kernel::TileState;
|
||||
use std::time::Instant;
|
||||
|
||||
#[test]
|
||||
fn bench_witness_fragment_64v() {
|
||||
// Build a CompactGraph with 64 vertices
|
||||
let mut graph = CompactGraph::new();
|
||||
for i in 0..64u16 {
|
||||
graph.add_edge(i, (i + 1) % 64, 100);
|
||||
}
|
||||
for i in 0..64u16 {
|
||||
graph.add_edge(i, (i + 13) % 64, 50);
|
||||
}
|
||||
graph.recompute_components();
|
||||
|
||||
// Warm up
|
||||
let _ = ArenaCactus::build_from_compact_graph(&graph);
|
||||
|
||||
// Benchmark ArenaCactus construction
|
||||
let n_iter = 1000;
|
||||
let start = Instant::now();
|
||||
for _ in 0..n_iter {
|
||||
let cactus = ArenaCactus::build_from_compact_graph(&graph);
|
||||
std::hint::black_box(&cactus);
|
||||
}
|
||||
let avg_cactus_us = start.elapsed().as_micros() as f64 / n_iter as f64;
|
||||
|
||||
// Benchmark canonical partition
|
||||
let cactus = ArenaCactus::build_from_compact_graph(&graph);
|
||||
let start = Instant::now();
|
||||
for _ in 0..n_iter {
|
||||
let p = cactus.canonical_partition();
|
||||
std::hint::black_box(&p);
|
||||
}
|
||||
let avg_partition_us = start.elapsed().as_micros() as f64 / n_iter as f64;
|
||||
|
||||
// Full witness via TileState
|
||||
let mut tile = TileState::new(42);
|
||||
for i in 0..64u16 {
|
||||
tile.graph.add_edge(i, (i + 1) % 64, 100);
|
||||
tile.graph.add_edge(i, (i + 13) % 64, 50);
|
||||
}
|
||||
tile.graph.recompute_components();
|
||||
|
||||
let start = Instant::now();
|
||||
for _ in 0..n_iter {
|
||||
let f = tile.canonical_witness();
|
||||
std::hint::black_box(&f);
|
||||
}
|
||||
let avg_witness_us = start.elapsed().as_micros() as f64 / n_iter as f64;
|
||||
|
||||
// Determinism check
|
||||
let ref_f = tile.canonical_witness();
|
||||
for _ in 0..100 {
|
||||
let f = tile.canonical_witness();
|
||||
assert_eq!(f.canonical_hash, ref_f.canonical_hash);
|
||||
assert_eq!(f.cactus_digest, ref_f.cactus_digest);
|
||||
}
|
||||
|
||||
println!("\n=== Canonical Witness Fragment (64 vertices) ===");
|
||||
println!(" ArenaCactus build: {:.1} µs", avg_cactus_us);
|
||||
println!(" Partition extract: {:.1} µs", avg_partition_us);
|
||||
println!(
|
||||
" Full witness: {:.1} µs (target: < 50 µs)",
|
||||
avg_witness_us
|
||||
);
|
||||
println!(
|
||||
" Fragment size: {} bytes",
|
||||
std::mem::size_of::<CanonicalWitnessFragment>()
|
||||
);
|
||||
println!(" Cut value: {}", ref_f.cut_value);
|
||||
|
||||
assert!(
|
||||
avg_witness_us < 50.0,
|
||||
"Witness exceeded 50µs target: {:.1} µs",
|
||||
avg_witness_us
|
||||
);
|
||||
}
|
||||
}
|
||||
250
crates/cognitum-gate-kernel/tests_disabled/evidence_tests.rs
Normal file
250
crates/cognitum-gate-kernel/tests_disabled/evidence_tests.rs
Normal file
@@ -0,0 +1,250 @@
|
||||
//! Comprehensive tests for E-value accumulator
|
||||
//!
|
||||
//! Tests cover:
|
||||
//! - E-value bounds (E[e] <= 1 under null)
|
||||
//! - Overflow/underflow protection
|
||||
//! - Update rules (Product, Average, ExponentialMoving, Maximum)
|
||||
//! - Stopping rules
|
||||
|
||||
use cognitum_gate_kernel::evidence::{
|
||||
EValueAccumulator, EValueError, StoppingDecision, StoppingRule, UpdateRule,
|
||||
E_VALUE_MAX, E_VALUE_MIN,
|
||||
};
|
||||
|
||||
#[cfg(test)]
|
||||
mod basic_operations {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_accumulator_creation() {
|
||||
let acc = EValueAccumulator::new();
|
||||
assert_eq!(acc.current_value(), 1.0);
|
||||
assert_eq!(acc.observation_count(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_observe_updates_count() {
|
||||
let mut acc = EValueAccumulator::new();
|
||||
acc.observe(0.5);
|
||||
assert_eq!(acc.observation_count(), 1);
|
||||
acc.observe(0.7);
|
||||
assert_eq!(acc.observation_count(), 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_reset() {
|
||||
let mut acc = EValueAccumulator::new();
|
||||
acc.observe(0.5);
|
||||
acc.reset();
|
||||
assert_eq!(acc.current_value(), 1.0);
|
||||
assert_eq!(acc.observation_count(), 0);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod update_rules {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_product_rule() {
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Product);
|
||||
acc.observe_evalue(2.0);
|
||||
assert!((acc.current_value() - 2.0).abs() < 0.001);
|
||||
acc.observe_evalue(3.0);
|
||||
assert!((acc.current_value() - 6.0).abs() < 0.001);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_average_rule() {
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Average);
|
||||
acc.observe_evalue(2.0);
|
||||
acc.observe_evalue(4.0);
|
||||
assert!((acc.current_value() - 3.0).abs() < 0.001);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_exponential_moving() {
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::ExponentialMoving { lambda: 0.5 });
|
||||
acc.observe_evalue(2.0);
|
||||
acc.observe_evalue(4.0);
|
||||
assert!((acc.current_value() - 3.0).abs() < 0.001);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_maximum_rule() {
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Maximum);
|
||||
acc.observe_evalue(2.0);
|
||||
acc.observe_evalue(5.0);
|
||||
acc.observe_evalue(3.0);
|
||||
assert_eq!(acc.current_value(), 5.0);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod bounds_and_overflow {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_e_value_clamping_high() {
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Product);
|
||||
acc.observe_evalue(1e20);
|
||||
assert!(acc.current_value() <= E_VALUE_MAX);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_e_value_clamping_low() {
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Product);
|
||||
acc.observe_evalue(1e-20);
|
||||
assert!(acc.current_value() >= E_VALUE_MIN);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_product_overflow_protection() {
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Product);
|
||||
for _ in 0..100 {
|
||||
acc.observe_evalue(100.0);
|
||||
}
|
||||
assert!(acc.current_value() <= E_VALUE_MAX);
|
||||
assert!(acc.current_value().is_finite());
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod likelihood_ratio {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_valid_likelihood_ratio() {
|
||||
let result = EValueAccumulator::from_likelihood_ratio(0.9, 0.1);
|
||||
assert!(result.is_ok());
|
||||
assert!((result.unwrap() - 9.0).abs() < 0.001);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_zero_denominator() {
|
||||
let result = EValueAccumulator::from_likelihood_ratio(0.5, 0.0);
|
||||
assert_eq!(result, Err(EValueError::DivisionByZero));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_nan_input() {
|
||||
let result = EValueAccumulator::from_likelihood_ratio(f64::NAN, 0.5);
|
||||
assert_eq!(result, Err(EValueError::InvalidInput));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod mixture_evalue {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_uniform_mixture() {
|
||||
let components = [2.0, 4.0, 6.0];
|
||||
let weights = [1.0, 1.0, 1.0];
|
||||
let result = EValueAccumulator::mixture(&components, &weights);
|
||||
assert!(result.is_ok());
|
||||
assert!((result.unwrap() - 4.0).abs() < 0.001);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_empty_mixture() {
|
||||
let result = EValueAccumulator::mixture(&[], &[]);
|
||||
assert_eq!(result, Err(EValueError::InvalidInput));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod stopping_rules {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_continue_decision() {
|
||||
let rule = StoppingRule::new(100.0);
|
||||
let acc = EValueAccumulator::new();
|
||||
assert_eq!(rule.check(&acc), StoppingDecision::Continue);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_accept_decision() {
|
||||
let rule = StoppingRule::new(100.0);
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Product);
|
||||
for _ in 0..10 {
|
||||
acc.observe_evalue(2.0);
|
||||
}
|
||||
assert!(acc.current_value() > 100.0);
|
||||
assert_eq!(rule.check(&acc), StoppingDecision::Accept);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_reject_decision() {
|
||||
let rule = StoppingRule::with_accept(100.0, 0.01);
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Product);
|
||||
for _ in 0..10 {
|
||||
acc.observe_evalue(0.1);
|
||||
}
|
||||
assert!(acc.current_value() < 0.01);
|
||||
assert_eq!(rule.check(&acc), StoppingDecision::Reject);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_confidence_calculation() {
|
||||
let rule = StoppingRule::default();
|
||||
let mut acc = EValueAccumulator::new();
|
||||
assert_eq!(rule.confidence(&acc), 0.0);
|
||||
acc.observe_evalue(2.0);
|
||||
assert!((rule.confidence(&acc) - 0.5).abs() < 0.001);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod combine_evalues {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_combine_basic() {
|
||||
let combined = EValueAccumulator::combine(2.0, 3.0);
|
||||
assert_eq!(combined, 6.0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_combine_overflow_clamped() {
|
||||
let combined = EValueAccumulator::combine(1e10, 1e10);
|
||||
assert!(combined <= E_VALUE_MAX);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod property_tests {
|
||||
use super::*;
|
||||
use proptest::prelude::*;
|
||||
|
||||
proptest! {
|
||||
#[test]
|
||||
fn prop_e_value_always_positive(score in 0.0f64..1.0) {
|
||||
let acc = EValueAccumulator::new();
|
||||
let e = acc.compute_e_value(score);
|
||||
assert!(e > 0.0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prop_e_value_bounded(score in 0.0f64..1.0) {
|
||||
let acc = EValueAccumulator::new();
|
||||
let e = acc.compute_e_value(score);
|
||||
assert!(e >= E_VALUE_MIN);
|
||||
assert!(e <= E_VALUE_MAX);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prop_maximum_never_decreases(observations in proptest::collection::vec(0.1f64..10.0, 1..20)) {
|
||||
let mut acc = EValueAccumulator::with_rule(UpdateRule::Maximum);
|
||||
let mut max_seen = 0.0f64;
|
||||
|
||||
for o in observations {
|
||||
acc.observe_evalue(o);
|
||||
let current = acc.current_value();
|
||||
assert!(current >= max_seen);
|
||||
max_seen = current;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
302
crates/cognitum-gate-kernel/tests_disabled/integration.rs
Normal file
302
crates/cognitum-gate-kernel/tests_disabled/integration.rs
Normal file
@@ -0,0 +1,302 @@
|
||||
//! Integration tests for full tick cycle
|
||||
//!
|
||||
//! Tests cover:
|
||||
//! - Complete WorkerTileState lifecycle
|
||||
//! - Delta processing sequences
|
||||
//! - Tick report generation
|
||||
//! - Multiple tile coordination scenarios
|
||||
|
||||
use cognitum_gate_kernel::{
|
||||
Delta, DeltaError, WorkerTileState,
|
||||
shard::{Edge, EdgeId, VertexId, Weight},
|
||||
report::{TileReport, TileStatus},
|
||||
};
|
||||
|
||||
#[cfg(test)]
|
||||
mod worker_tile_lifecycle {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_tile_creation() {
|
||||
let tile = WorkerTileState::new(42);
|
||||
assert_eq!(tile.tile_id, 42);
|
||||
assert_eq!(tile.coherence, 0);
|
||||
assert_eq!(tile.tick, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_initial_report() {
|
||||
let mut tile = WorkerTileState::new(5);
|
||||
let report = tile.tick(1000);
|
||||
assert_eq!(report.tile_id, 5);
|
||||
assert_eq!(report.status, TileStatus::Active);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod delta_processing {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_edge_add_delta() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
let delta = Delta::EdgeAdd { edge, weight: Weight(100) };
|
||||
|
||||
assert!(tile.ingest_delta(&delta).is_ok());
|
||||
assert_eq!(tile.graph_shard.edge_count(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_edge_remove_delta() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
|
||||
tile.ingest_delta(&Delta::EdgeAdd { edge, weight: Weight(100) }).unwrap();
|
||||
tile.ingest_delta(&Delta::EdgeRemove { edge: EdgeId(0) }).unwrap();
|
||||
|
||||
assert_eq!(tile.graph_shard.edge_count(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_weight_update_delta() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
|
||||
tile.ingest_delta(&Delta::EdgeAdd { edge, weight: Weight(100) }).unwrap();
|
||||
tile.ingest_delta(&Delta::WeightUpdate { edge: EdgeId(0), weight: Weight(200) }).unwrap();
|
||||
|
||||
assert_eq!(tile.graph_shard.get_weight(EdgeId(0)), Some(Weight(200)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_observation_delta() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
tile.ingest_delta(&Delta::Observation { score: 0.8 }).unwrap();
|
||||
assert_eq!(tile.e_accumulator.observation_count(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_self_loop_rejected() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
let edge = Edge::new(VertexId(5), VertexId(5));
|
||||
let delta = Delta::EdgeAdd { edge, weight: Weight(100) };
|
||||
assert_eq!(tile.ingest_delta(&delta), Err(DeltaError::InvalidEdge));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tick_cycle {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_single_tick() {
|
||||
let mut tile = WorkerTileState::new(10);
|
||||
let report = tile.tick(1000);
|
||||
assert_eq!(report.tile_id, 10);
|
||||
assert_eq!(tile.tick, 1000);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tick_updates_timestamp() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
tile.tick(1000);
|
||||
assert_eq!(tile.tick, 1000);
|
||||
tile.tick(2000);
|
||||
assert_eq!(tile.tick, 2000);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tick_after_deltas() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
|
||||
tile.ingest_delta(&Delta::EdgeAdd {
|
||||
edge: Edge::new(VertexId(0), VertexId(1)),
|
||||
weight: Weight(100),
|
||||
}).unwrap();
|
||||
tile.ingest_delta(&Delta::Observation { score: 0.9 }).unwrap();
|
||||
|
||||
let report = tile.tick(1000);
|
||||
assert!(report.is_healthy());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_multiple_tick_cycles() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
|
||||
for i in 0..10 {
|
||||
tile.ingest_delta(&Delta::EdgeAdd {
|
||||
edge: Edge::new(VertexId(i as u8), VertexId((i + 1) as u8)),
|
||||
weight: Weight(100),
|
||||
}).unwrap();
|
||||
tile.ingest_delta(&Delta::Observation { score: 0.8 }).unwrap();
|
||||
let report = tile.tick((i + 1) * 1000);
|
||||
assert!(report.is_healthy());
|
||||
}
|
||||
|
||||
assert_eq!(tile.graph_shard.edge_count(), 10);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod e_value_accumulation {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_e_value_in_report() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
|
||||
for _ in 0..5 {
|
||||
tile.ingest_delta(&Delta::Observation { score: 0.9 }).unwrap();
|
||||
}
|
||||
|
||||
let report = tile.tick(1000);
|
||||
assert!(report.e_value > 0.0);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod multi_tile_scenario {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_deterministic_across_tiles() {
|
||||
let deltas = [
|
||||
Delta::EdgeAdd { edge: Edge::new(VertexId(0), VertexId(1)), weight: Weight(100) },
|
||||
Delta::EdgeAdd { edge: Edge::new(VertexId(1), VertexId(2)), weight: Weight(150) },
|
||||
Delta::Observation { score: 0.9 },
|
||||
];
|
||||
|
||||
let mut tile1 = WorkerTileState::new(0);
|
||||
let mut tile2 = WorkerTileState::new(0);
|
||||
|
||||
for delta in &deltas {
|
||||
tile1.ingest_delta(delta).unwrap();
|
||||
tile2.ingest_delta(delta).unwrap();
|
||||
}
|
||||
|
||||
let report1 = tile1.tick(1000);
|
||||
let report2 = tile2.tick(1000);
|
||||
|
||||
assert_eq!(report1.coherence, report2.coherence);
|
||||
assert!((report1.e_value - report2.e_value).abs() < 0.001);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tile_network() {
|
||||
let mut tiles: Vec<WorkerTileState> = (0..10)
|
||||
.map(|id| WorkerTileState::new(id))
|
||||
.collect();
|
||||
|
||||
for (tile_idx, tile) in tiles.iter_mut().enumerate() {
|
||||
let base = (tile_idx * 10) as u8;
|
||||
for i in 0..5u8 {
|
||||
let _ = tile.ingest_delta(&Delta::EdgeAdd {
|
||||
edge: Edge::new(VertexId(base + i), VertexId(base + i + 1)),
|
||||
weight: Weight(100),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
let reports: Vec<TileReport> = tiles
|
||||
.iter_mut()
|
||||
.enumerate()
|
||||
.map(|(idx, tile)| tile.tick((idx as u64) * 100))
|
||||
.collect();
|
||||
|
||||
for report in &reports {
|
||||
assert!(report.is_healthy());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod edge_cases {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_empty_tile_tick() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
let report = tile.tick(1000);
|
||||
assert!(report.is_healthy());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tile_with_only_observations() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
|
||||
for _ in 0..100 {
|
||||
tile.ingest_delta(&Delta::Observation { score: 0.5 }).unwrap();
|
||||
}
|
||||
|
||||
let report = tile.tick(1000);
|
||||
assert!(report.is_healthy());
|
||||
assert_eq!(tile.graph_shard.edge_count(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_tick_at_max() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
let report = tile.tick(u64::MAX);
|
||||
assert_eq!(tile.tick, u64::MAX);
|
||||
assert!(report.is_healthy());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_alternating_add_remove() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
|
||||
for _ in 0..100 {
|
||||
tile.ingest_delta(&Delta::EdgeAdd {
|
||||
edge: Edge::new(VertexId(0), VertexId(1)),
|
||||
weight: Weight(100),
|
||||
}).unwrap();
|
||||
tile.ingest_delta(&Delta::EdgeRemove { edge: EdgeId(0) }).unwrap();
|
||||
}
|
||||
|
||||
assert!(tile.tick(1000).is_healthy());
|
||||
assert_eq!(tile.graph_shard.edge_count(), 0);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod stress_tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_high_volume_deltas() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
|
||||
for i in 0..1000 {
|
||||
let src = (i % 200) as u8;
|
||||
let dst = ((i + 1) % 200) as u8;
|
||||
|
||||
if src != dst {
|
||||
let _ = tile.ingest_delta(&Delta::EdgeAdd {
|
||||
edge: Edge::new(VertexId(src), VertexId(dst)),
|
||||
weight: Weight(100),
|
||||
});
|
||||
}
|
||||
|
||||
if i % 10 == 0 {
|
||||
let _ = tile.ingest_delta(&Delta::Observation { score: 0.8 });
|
||||
}
|
||||
}
|
||||
|
||||
assert!(tile.tick(10000).is_healthy());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_rapid_tick_cycles() {
|
||||
let mut tile = WorkerTileState::new(0);
|
||||
|
||||
tile.ingest_delta(&Delta::EdgeAdd {
|
||||
edge: Edge::new(VertexId(0), VertexId(1)),
|
||||
weight: Weight(100),
|
||||
}).unwrap();
|
||||
|
||||
for i in 0..1000u64 {
|
||||
assert!(tile.tick(i).is_healthy());
|
||||
}
|
||||
}
|
||||
}
|
||||
249
crates/cognitum-gate-kernel/tests_disabled/report_tests.rs
Normal file
249
crates/cognitum-gate-kernel/tests_disabled/report_tests.rs
Normal file
@@ -0,0 +1,249 @@
|
||||
//! Comprehensive tests for TileReport generation and serialization
|
||||
//!
|
||||
//! Tests cover:
|
||||
//! - Report creation and initialization
|
||||
//! - Serialization/deserialization roundtrips
|
||||
//! - Checksum verification
|
||||
//! - WitnessFragment operations
|
||||
|
||||
use cognitum_gate_kernel::report::{TileReport, TileStatus, WitnessFragment};
|
||||
use cognitum_gate_kernel::shard::EdgeId;
|
||||
|
||||
#[cfg(test)]
|
||||
mod tile_status {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_status_values() {
|
||||
assert_eq!(TileStatus::Active as u8, 0);
|
||||
assert_eq!(TileStatus::Idle as u8, 1);
|
||||
assert_eq!(TileStatus::Recovery as u8, 2);
|
||||
assert_eq!(TileStatus::Error as u8, 3);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_status_from_u8() {
|
||||
assert_eq!(TileStatus::from_u8(0), Some(TileStatus::Active));
|
||||
assert_eq!(TileStatus::from_u8(1), Some(TileStatus::Idle));
|
||||
assert_eq!(TileStatus::from_u8(255), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_is_healthy() {
|
||||
assert!(TileStatus::Active.is_healthy());
|
||||
assert!(TileStatus::Idle.is_healthy());
|
||||
assert!(!TileStatus::Error.is_healthy());
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod witness_fragment {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_fragment_creation() {
|
||||
let frag = WitnessFragment::new(42);
|
||||
assert_eq!(frag.tile_id, 42);
|
||||
assert_eq!(frag.min_cut_value, 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_is_fragile() {
|
||||
let mut frag = WitnessFragment::new(0);
|
||||
frag.min_cut_value = 5;
|
||||
assert!(frag.is_fragile(10));
|
||||
assert!(!frag.is_fragile(5));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_fragment_hash_deterministic() {
|
||||
let frag = WitnessFragment::new(5);
|
||||
assert_eq!(frag.compute_hash(), frag.compute_hash());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_fragment_hash_unique() {
|
||||
let frag1 = WitnessFragment::new(1);
|
||||
let frag2 = WitnessFragment::new(2);
|
||||
assert_ne!(frag1.compute_hash(), frag2.compute_hash());
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tile_report_creation {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_new_report() {
|
||||
let report = TileReport::new(5);
|
||||
assert_eq!(report.tile_id, 5);
|
||||
assert_eq!(report.status, TileStatus::Active);
|
||||
assert!(report.is_healthy());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_error_report() {
|
||||
let report = TileReport::error(10);
|
||||
assert_eq!(report.status, TileStatus::Error);
|
||||
assert!(!report.is_healthy());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_idle_report() {
|
||||
let report = TileReport::idle(15);
|
||||
assert_eq!(report.status, TileStatus::Idle);
|
||||
assert!(report.is_healthy());
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod report_health_checks {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_needs_attention_boundary_moved() {
|
||||
let mut report = TileReport::new(0);
|
||||
assert!(!report.needs_attention());
|
||||
report.boundary_moved = true;
|
||||
assert!(report.needs_attention());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_needs_attention_negative_coherence() {
|
||||
let mut report = TileReport::new(0);
|
||||
report.coherence = -100;
|
||||
assert!(report.needs_attention());
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod coherence_conversion {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_coherence_f32_values() {
|
||||
let mut report = TileReport::new(0);
|
||||
|
||||
report.coherence = 0;
|
||||
assert!((report.coherence_f32() - 0.0).abs() < 0.001);
|
||||
|
||||
report.coherence = 256;
|
||||
assert!((report.coherence_f32() - 1.0).abs() < 0.01);
|
||||
|
||||
report.coherence = -128;
|
||||
assert!((report.coherence_f32() - (-0.5)).abs() < 0.01);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod serialization {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_to_bytes_size() {
|
||||
let report = TileReport::new(0);
|
||||
let bytes = report.to_bytes();
|
||||
assert_eq!(bytes.len(), 64);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_roundtrip_basic() {
|
||||
let report = TileReport::new(42);
|
||||
let bytes = report.to_bytes();
|
||||
let restored = TileReport::from_bytes(&bytes).unwrap();
|
||||
assert_eq!(report.tile_id, restored.tile_id);
|
||||
assert_eq!(report.status, restored.status);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_roundtrip_with_data() {
|
||||
let mut report = TileReport::new(100);
|
||||
report.coherence = 512;
|
||||
report.e_value = 2.5;
|
||||
report.boundary_moved = true;
|
||||
report.suspicious_edges[0] = EdgeId(100);
|
||||
|
||||
let bytes = report.to_bytes();
|
||||
let restored = TileReport::from_bytes(&bytes).unwrap();
|
||||
|
||||
assert_eq!(restored.coherence, 512);
|
||||
assert!((restored.e_value - 2.5).abs() < 0.001);
|
||||
assert!(restored.boundary_moved);
|
||||
assert_eq!(restored.suspicious_edges[0], EdgeId(100));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod checksum {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_checksum_deterministic() {
|
||||
let report = TileReport::new(42);
|
||||
assert_eq!(report.checksum(), report.checksum());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_checksum_different_reports() {
|
||||
let r1 = TileReport::new(1);
|
||||
let r2 = TileReport::new(2);
|
||||
assert_ne!(r1.checksum(), r2.checksum());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_verify_checksum() {
|
||||
let report = TileReport::new(42);
|
||||
let cs = report.checksum();
|
||||
assert!(report.verify_checksum(cs));
|
||||
assert!(!report.verify_checksum(0));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod report_size {
|
||||
use super::*;
|
||||
use std::mem::size_of;
|
||||
|
||||
#[test]
|
||||
fn test_report_fits_cache_line() {
|
||||
assert!(size_of::<TileReport>() <= 64);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod property_tests {
|
||||
use super::*;
|
||||
use proptest::prelude::*;
|
||||
|
||||
proptest! {
|
||||
#[test]
|
||||
fn prop_serialization_roundtrip(
|
||||
tile_id in 0u8..255,
|
||||
coherence in i16::MIN..i16::MAX,
|
||||
e_value in 0.0f32..100.0,
|
||||
boundary_moved: bool
|
||||
) {
|
||||
let mut report = TileReport::new(tile_id);
|
||||
report.coherence = coherence;
|
||||
report.e_value = e_value;
|
||||
report.boundary_moved = boundary_moved;
|
||||
|
||||
let bytes = report.to_bytes();
|
||||
let restored = TileReport::from_bytes(&bytes).unwrap();
|
||||
|
||||
assert_eq!(report.tile_id, restored.tile_id);
|
||||
assert_eq!(report.coherence, restored.coherence);
|
||||
assert_eq!(report.boundary_moved, restored.boundary_moved);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prop_checksum_changes_with_data(a: i16, b: i16) {
|
||||
prop_assume!(a != b);
|
||||
let mut r1 = TileReport::new(0);
|
||||
let mut r2 = TileReport::new(0);
|
||||
r1.coherence = a;
|
||||
r2.coherence = b;
|
||||
assert_ne!(r1.checksum(), r2.checksum());
|
||||
}
|
||||
}
|
||||
}
|
||||
299
crates/cognitum-gate-kernel/tests_disabled/shard_tests.rs
Normal file
299
crates/cognitum-gate-kernel/tests_disabled/shard_tests.rs
Normal file
@@ -0,0 +1,299 @@
|
||||
//! Comprehensive tests for CompactGraph operations
|
||||
//!
|
||||
//! Tests cover:
|
||||
//! - Edge add/remove operations
|
||||
//! - Weight updates
|
||||
//! - Boundary edge management
|
||||
//! - Edge cases (empty graph, max capacity, boundary conditions)
|
||||
//! - Property-based tests for invariant verification
|
||||
|
||||
use cognitum_gate_kernel::shard::{CompactGraph, Edge, EdgeId, VertexId, Weight};
|
||||
use cognitum_gate_kernel::{DeltaError, MAX_EDGES, MAX_VERTICES};
|
||||
|
||||
#[cfg(test)]
|
||||
mod basic_operations {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_empty_graph() {
|
||||
let graph = CompactGraph::new();
|
||||
assert!(graph.is_empty());
|
||||
assert_eq!(graph.edge_count(), 0);
|
||||
assert_eq!(graph.vertex_count(), 0);
|
||||
assert!(!graph.is_full());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_add_single_edge() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
let weight = Weight(100);
|
||||
|
||||
let result = graph.add_edge(edge, weight);
|
||||
assert!(result.is_ok());
|
||||
|
||||
let edge_id = result.unwrap();
|
||||
assert_eq!(graph.edge_count(), 1);
|
||||
assert_eq!(graph.vertex_count(), 2);
|
||||
assert_eq!(graph.get_weight(edge_id), Some(weight));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_add_multiple_edges() {
|
||||
let mut graph = CompactGraph::new();
|
||||
|
||||
let edges = [
|
||||
(Edge::new(VertexId(0), VertexId(1)), Weight(100)),
|
||||
(Edge::new(VertexId(1), VertexId(2)), Weight(200)),
|
||||
(Edge::new(VertexId(2), VertexId(3)), Weight(300)),
|
||||
];
|
||||
|
||||
for (edge, weight) in edges {
|
||||
let result = graph.add_edge(edge, weight);
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
|
||||
assert_eq!(graph.edge_count(), 3);
|
||||
assert_eq!(graph.vertex_count(), 4);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_remove_edge() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
let edge_id = graph.add_edge(edge, Weight(100)).unwrap();
|
||||
|
||||
let result = graph.remove_edge(edge_id);
|
||||
assert!(result.is_ok());
|
||||
assert_eq!(graph.edge_count(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_remove_nonexistent_edge() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let result = graph.remove_edge(EdgeId(999));
|
||||
assert_eq!(result, Err(DeltaError::EdgeNotFound));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_update_weight() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
let edge_id = graph.add_edge(edge, Weight(100)).unwrap();
|
||||
|
||||
let result = graph.update_weight(edge_id, Weight(500));
|
||||
assert!(result.is_ok());
|
||||
assert_eq!(graph.get_weight(edge_id), Some(Weight(500)));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod edge_canonicalization {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_canonical_ordering() {
|
||||
let e1 = Edge::new(VertexId(5), VertexId(3));
|
||||
let e2 = Edge::new(VertexId(3), VertexId(5));
|
||||
|
||||
assert_eq!(e1.canonical(), e2.canonical());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_self_loop_rejected() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let edge = Edge::new(VertexId(5), VertexId(5));
|
||||
|
||||
let result = graph.add_edge(edge, Weight(100));
|
||||
assert_eq!(result, Err(DeltaError::InvalidEdge));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_duplicate_edge_updates_weight() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let e1 = Edge::new(VertexId(0), VertexId(1));
|
||||
let e2 = Edge::new(VertexId(1), VertexId(0));
|
||||
|
||||
let id1 = graph.add_edge(e1, Weight(100)).unwrap();
|
||||
let id2 = graph.add_edge(e2, Weight(200)).unwrap();
|
||||
|
||||
assert_eq!(id1, id2);
|
||||
assert_eq!(graph.edge_count(), 1);
|
||||
assert_eq!(graph.get_weight(id1), Some(Weight(200)));
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod boundary_edges {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_mark_boundary() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
let edge_id = graph.add_edge(edge, Weight(100)).unwrap();
|
||||
|
||||
assert_eq!(graph.total_internal_weight(), 100);
|
||||
assert_eq!(graph.total_boundary_weight(), 0);
|
||||
|
||||
graph.mark_boundary(edge_id).unwrap();
|
||||
|
||||
assert_eq!(graph.total_internal_weight(), 0);
|
||||
assert_eq!(graph.total_boundary_weight(), 100);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_unmark_boundary() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
let edge_id = graph.add_edge(edge, Weight(100)).unwrap();
|
||||
|
||||
graph.mark_boundary(edge_id).unwrap();
|
||||
graph.unmark_boundary(edge_id).unwrap();
|
||||
|
||||
assert_eq!(graph.total_boundary_weight(), 0);
|
||||
assert_eq!(graph.total_internal_weight(), 100);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_boundary_changed_flag() {
|
||||
let mut graph = CompactGraph::new();
|
||||
let edge = Edge::new(VertexId(0), VertexId(1));
|
||||
let edge_id = graph.add_edge(edge, Weight(100)).unwrap();
|
||||
|
||||
graph.clear_boundary_changed();
|
||||
assert!(!graph.boundary_changed_since_last_update());
|
||||
|
||||
graph.mark_boundary(edge_id).unwrap();
|
||||
assert!(graph.boundary_changed_since_last_update());
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod weight_operations {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_weight_from_f32() {
|
||||
let w = Weight::from_f32(1.0);
|
||||
assert_eq!(w.0, 256);
|
||||
|
||||
let w2 = Weight::from_f32(2.0);
|
||||
assert_eq!(w2.0, 512);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_weight_to_f32() {
|
||||
let w = Weight(256);
|
||||
assert!((w.to_f32() - 1.0).abs() < 0.01);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_weight_saturating_operations() {
|
||||
let w1 = Weight(u16::MAX - 10);
|
||||
let w2 = Weight(100);
|
||||
let sum = w1.saturating_add(w2);
|
||||
assert_eq!(sum, Weight::MAX);
|
||||
|
||||
let w3 = Weight(10);
|
||||
let diff = w3.saturating_sub(w2);
|
||||
assert_eq!(diff, Weight::ZERO);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod vertex_degree {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_vertex_degree_after_add() {
|
||||
let mut graph = CompactGraph::new();
|
||||
|
||||
graph.add_edge(Edge::new(VertexId(0), VertexId(1)), Weight(100)).unwrap();
|
||||
graph.add_edge(Edge::new(VertexId(0), VertexId(2)), Weight(100)).unwrap();
|
||||
graph.add_edge(Edge::new(VertexId(0), VertexId(3)), Weight(100)).unwrap();
|
||||
|
||||
assert_eq!(graph.vertex_degree(VertexId(0)), 3);
|
||||
assert_eq!(graph.vertex_degree(VertexId(1)), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_vertex_degree_after_remove() {
|
||||
let mut graph = CompactGraph::new();
|
||||
|
||||
let id1 = graph.add_edge(Edge::new(VertexId(0), VertexId(1)), Weight(100)).unwrap();
|
||||
graph.add_edge(Edge::new(VertexId(0), VertexId(2)), Weight(100)).unwrap();
|
||||
|
||||
graph.remove_edge(id1).unwrap();
|
||||
assert_eq!(graph.vertex_degree(VertexId(0)), 1);
|
||||
assert_eq!(graph.vertex_degree(VertexId(1)), 0);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod min_cut_estimation {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_min_cut_empty_graph() {
|
||||
let graph = CompactGraph::new();
|
||||
assert_eq!(graph.local_min_cut(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_min_cut_single_edge() {
|
||||
let mut graph = CompactGraph::new();
|
||||
graph.add_edge(Edge::new(VertexId(0), VertexId(1)), Weight(100)).unwrap();
|
||||
assert_eq!(graph.local_min_cut(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_min_cut_clique() {
|
||||
let mut graph = CompactGraph::new();
|
||||
|
||||
for i in 0..4u8 {
|
||||
for j in (i + 1)..4 {
|
||||
graph.add_edge(Edge::new(VertexId(i), VertexId(j)), Weight(100)).unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
assert_eq!(graph.local_min_cut(), 3);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod property_tests {
|
||||
use super::*;
|
||||
use proptest::prelude::*;
|
||||
|
||||
proptest! {
|
||||
#[test]
|
||||
fn prop_add_remove_invariant(src in 0u8..250, dst in 0u8..250, weight in 1u16..1000) {
|
||||
prop_assume!(src != dst);
|
||||
|
||||
let mut graph = CompactGraph::new();
|
||||
let edge = Edge::new(VertexId(src), VertexId(dst));
|
||||
let id = graph.add_edge(edge, Weight(weight)).unwrap();
|
||||
|
||||
assert_eq!(graph.edge_count(), 1);
|
||||
graph.remove_edge(id).unwrap();
|
||||
assert_eq!(graph.edge_count(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prop_canonical_symmetry(a in 0u8..250, b in 0u8..250) {
|
||||
prop_assume!(a != b);
|
||||
|
||||
let e1 = Edge::new(VertexId(a), VertexId(b));
|
||||
let e2 = Edge::new(VertexId(b), VertexId(a));
|
||||
assert_eq!(e1.canonical(), e2.canonical());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prop_weight_roundtrip(f in 0.0f32..200.0) {
|
||||
let weight = Weight::from_f32(f);
|
||||
let back = weight.to_f32();
|
||||
assert!((f - back).abs() < 0.01 || back >= 255.0);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user