saorsa-core: Instructions file for Codex

Agent Guidelines for Saorsa Core

DHT Phonebook + Trust Signals (Current Direction)

Core Responsibilities

• DHT is a peer phonebook only (peer records, routing, discovery).
• User data storage lives in saorsa-node via send_message-style APIs.
• Trust remains in saorsa-core: saorsa-node reports data availability outcomes so EigenTrust can downscore nodes that fail to serve expected data.

Trust Signal Hook (saorsa-node → saorsa-core)

use saorsa_core::adaptive::{EigenTrustEngine, NodeStatisticsUpdate};

// After a data fetch attempt in saorsa-node:
trust_engine
    .update_node_stats(&peer_id, NodeStatisticsUpdate::CorrectResponse)
    .await;
// or on failure:
trust_engine
    .update_node_stats(&peer_id, NodeStatisticsUpdate::FailedResponse)
    .await;

Build/Test Commands

• Build: cargo build --all-features (release: cargo build --release)
• Test All: cargo test --all-features (doc tests: cargo test --doc)
• Single Test: cargo test test_function_name or cargo test --test integration_test_name
• Lint: cargo clippy --all-features -- -D clippy::panic -D clippy::unwrap_used -D clippy::expect_used
• Format: cargo fmt --all -- --check (apply: cargo fmt --all)
• Local CI: ./scripts/local_ci.sh (runs fmt, clippy, build, tests safely)

Code Style Guidelines

Error Handling (ZERO PANICS in production)

• NEVER use: .unwrap(), .expect(), panic!() in library/production code
• Use instead: ? operator, .ok_or(), .context() from anyhow
• Tests OK: .unwrap()/.expect() allowed in #[cfg(test)] blocks
• Error types: P2PError enum with structured variants, thiserror for derives

Imports & Dependencies

• Core async: tokio, futures, async-trait
• Serialization: serde with derive features
• Error handling: anyhow, thiserror
• Logging: tracing (never println! in production)
• Crypto: saorsa-pqc (primary), saorsa-transport (QUIC transport)