Collecting and Merging Tile Reports

Worker tiles continuously monitor their local patch of the coherence graph. TileZero collects these reports and maintains a global view.

use cognitum_gate_tilezero::{TileZero, TileReport, WitnessFragment, GateThresholds};

#[tokio::main]
async fn main() {
    let tilezero = TileZero::new(GateThresholds::default());

    // Simulate reports from worker tiles
    let reports = vec![
        TileReport {
            tile_id: 1,
            coherence: 0.95,
            boundary_moved: false,
            suspicious_edges: vec![],
            e_value: 1.0,
            witness_fragment: None,
        },
        TileReport {
            tile_id: 2,
            coherence: 0.87,
            boundary_moved: true,
            suspicious_edges: vec![42, 43],
            e_value: 0.8,
            witness_fragment: Some(WitnessFragment {
                tile_id: 2,
                boundary_edges: vec![42, 43],
                cut_value: 5.2,
            }),
        },
    ];

    // Merge reports into supergraph
    tilezero.collect_reports(&reports).await;

    println!("Reports collected from {} tiles", reports.len());
}

Key Concepts:

• boundary_moved: Indicates structural change requiring supergraph update
• witness_fragment: Contains boundary information for witness computation
• e_value: Local evidence accumulator for statistical testing

Token Verification and Validation

Permit tokens are Ed25519 signed and time-bounded. Recipients should verify before acting.

use cognitum_gate_tilezero::{TileZero, GateThresholds, Verifier};

#[tokio::main]
async fn main() {
    let tilezero = TileZero::new(GateThresholds::default());

    // Get the verifier (contains public key)
    let verifier: Verifier = tilezero.verifier();

    // Later, when receiving a token...
    let action = create_action();
    let token = tilezero.decide(&action).await;

    // Verify signature
    match verifier.verify(&token) {
        Ok(()) => println!("✅ Valid signature"),
        Err(e) => println!("❌ Invalid: {:?}", e),
    }

    // Check time validity
    let now_ns = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap()
        .as_nanos() as u64;

    if token.timestamp + token.ttl_ns > now_ns {
        println!("⏰ Token still valid");
    } else {
        println!("⏰ Token expired");
    }
}

Tamper-Evident Decision Logging

Every decision is logged in a Blake3 hash chain for compliance and debugging.

use cognitum_gate_tilezero::{TileZero, GateThresholds};

#[tokio::main]
async fn main() {
    let tilezero = TileZero::new(GateThresholds::default());

    // Make several decisions
    for i in 0..5 {
        let action = ActionContext {
            action_id: format!("action-{}", i),
            action_type: "test".to_string(),
            target: Default::default(),
            context: Default::default(),
        };
        let _ = tilezero.decide(&action).await;
    }

    // Retrieve specific receipt
    if let Some(receipt) = tilezero.get_receipt(2).await {
        println!("Receipt #2:");
        println!("  Decision: {:?}", receipt.token.decision);
        println!("  Timestamp: {}", receipt.token.timestamp);
        println!("  Previous hash: {:x?}", &receipt.previous_hash[..8]);
    }

    // Verify chain integrity
    match tilezero.verify_receipt_chain().await {
        Ok(()) => println!("✅ Hash chain intact"),
        Err(e) => println!("❌ Chain broken: {:?}", e),
    }

    // Export for audit
    let json = tilezero.export_receipts_json().await.unwrap();
    println!("Exported {} bytes of audit data", json.len());
}

Tuning the Decision Pipeline

Adjust thresholds based on your security requirements and system characteristics.

use cognitum_gate_tilezero::{TileZero, GateThresholds};

fn main() {
    // Conservative settings (more DENY/DEFER)
    let conservative = GateThresholds {
        min_cut: 10.0,           // Higher min-cut requirement
        max_shift: 0.1,          // Lower tolerance for distribution shift
        tau_deny: 0.001,         // Lower e-value triggers DENY
        tau_permit: 1000.0,      // Higher e-value needed for PERMIT
        permit_ttl_ns: 100_000,  // Shorter token validity (100μs)
    };

    // Permissive settings (more PERMIT)
    let permissive = GateThresholds {
        min_cut: 3.0,            // Lower connectivity requirement
        max_shift: 0.5,          // Higher tolerance for shift
        tau_deny: 0.0001,        // Very low e-value for DENY
        tau_permit: 10.0,        // Lower e-value sufficient for PERMIT
        permit_ttl_ns: 10_000_000, // Longer validity (10ms)
    };

    // Production defaults
    let default = GateThresholds::default();

    println!("Conservative min_cut: {}", conservative.min_cut);
    println!("Permissive min_cut: {}", permissive.min_cut);
    println!("Default min_cut: {}", default.min_cut);
}

Threshold Guidelines:

Handling Uncertain Situations

When TileZero returns DEFER, escalate to a human operator.

use cognitum_gate_tilezero::{TileZero, GateDecision, EscalationInfo};

async fn handle_action(tilezero: &TileZero, action: ActionContext) {
    let token = tilezero.decide(&action).await;

    match token.decision {
        GateDecision::Permit => {
            // Auto-approve
            execute_action(&action).await;
        }
        GateDecision::Deny => {
            // Auto-reject
            log_rejection(&action, "Structural issue detected");
        }
        GateDecision::Defer => {
            // Escalate to human
            let escalation = EscalationInfo {
                to: "security-team@example.com".to_string(),
                context_url: format!("https://dashboard/actions/{}", action.action_id),
                timeout_ns: 60_000_000_000, // 60 seconds
                default_on_timeout: "deny".to_string(),
            };

            match await_human_decision(&escalation).await {
                HumanDecision::Approve => execute_action(&action).await,
                HumanDecision::Reject => log_rejection(&action, "Human rejected"),
                HumanDecision::Timeout => log_rejection(&action, "Escalation timeout"),
            }
        }
    }
}

GateDecision

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GateDecision {
    /// All filters pass - action is permitted
    Permit,
    /// Uncertainty - defer to human or wait
    Defer,
    /// Structural issue - deny action
    Deny,
}

GateThresholds

pub struct GateThresholds {
    /// Minimum global min-cut value for PERMIT
    pub min_cut: f64,
    /// Maximum allowed shift pressure
    pub max_shift: f64,
    /// E-value below which to DENY
    pub tau_deny: f64,
    /// E-value above which to PERMIT
    pub tau_permit: f64,
    /// Permit token time-to-live in nanoseconds
    pub permit_ttl_ns: u64,
}

PermitToken

pub struct PermitToken {
    /// The gate decision
    pub decision: GateDecision,
    /// ID of the action this token authorizes
    pub action_id: ActionId,
    /// Unix timestamp in nanoseconds
    pub timestamp: u64,
    /// Time-to-live in nanoseconds
    pub ttl_ns: u64,
    /// Blake3 hash of witness state
    pub witness_hash: [u8; 32],
    /// Sequence number in receipt log
    pub sequence: u64,
    /// Ed25519 signature
    pub signature: [u8; 64],
}

Constructor

impl TileZero {
    /// Create a new TileZero arbiter with given thresholds
    pub fn new(thresholds: GateThresholds) -> Self;
}

Core Methods

impl TileZero {
    /// Collect reports from worker tiles
    pub async fn collect_reports(&self, reports: &[TileReport]);

    /// Make a gate decision for an action
    pub async fn decide(&self, action_ctx: &ActionContext) -> PermitToken;

    /// Get a receipt by sequence number
    pub async fn get_receipt(&self, sequence: u64) -> Option<WitnessReceipt>;

    /// Verify hash chain integrity
    pub async fn verify_chain_to(&self, sequence: u64) -> Result<(), ChainVerifyError>;

    /// Get the token verifier (public key)
    pub fn verifier(&self) -> Verifier;

    /// Export receipts as JSON for audit
    pub async fn export_receipts_json(&self) -> Result<String, serde_json::Error>;
}