@feltdb/core 0.15.0 → 0.16.1

package/dist/create/server-source/crates/feltdb/src/acquisition.rs

@@ -1,286 +0,0 @@
-/// Content acquisition and materialization module
-/// Handles distributed content transfer, verification, and local materialization
-use crate::{ContentIdentity, FlowRef, PeerId};
-use serde::{Deserialize, Serialize};
-use std::collections::HashMap;
-use std::sync::{Arc, Mutex};
-use std::time::SystemTime;
-use std::time::UNIX_EPOCH;
-
-/// Policy for acquiring content from the distributed fabric
-#[derive(Debug, Clone, Copy, Serialize, Deserialize, Eq, PartialEq)]
-pub enum AcquisitionPolicy {
-    /// Fail if content is not available locally
-    LocalOnly,
-    /// Prefer local, fall back to remote if needed
-    PreferLocal,
-    /// Allow automatic remote acquisition
-    RemoteAllowed,
-    /// Block until content is available (required)
-    Required,
-}
-
-impl Default for AcquisitionPolicy {
-    fn default() -> Self {
-        AcquisitionPolicy::PreferLocal
-    }
-}
-
-/// Error types for content acquisition
-#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq)]
-pub enum ContentTransferError {
-    /// Content not found on provider
-    NotFound,
-    /// Access denied to content
-    Unauthorized,
-    /// Provider temporarily unavailable
-    Unavailable,
-    /// Content hash does not match expected
-    HashMismatch { expected: String, computed: String },
-    /// Requested version not available
-    VersionUnavailable,
-    /// Generic acquisition error
-    AcquisitionError(String),
-}
-
-impl std::fmt::Display for ContentTransferError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            ContentTransferError::NotFound => write!(f, "Content not found"),
-            ContentTransferError::Unauthorized => write!(f, "Access denied"),
-            ContentTransferError::Unavailable => write!(f, "Provider unavailable"),
-            ContentTransferError::HashMismatch { expected, computed } => {
-                write!(f, "Hash mismatch: expected {}, got {}", expected, computed)
-            }
-            ContentTransferError::VersionUnavailable => write!(f, "Version unavailable"),
-            ContentTransferError::AcquisitionError(msg) => write!(f, "Acquisition error: {}", msg),
-        }
-    }
-}
-
-impl std::error::Error for ContentTransferError {}
-
-/// Request for content from a remote peer
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ContentRequest {
-    /// Unique request ID for correlation
-    pub request_id: String,
-    /// Reference to the content being requested
-    pub flow_ref: FlowRef,
-    /// Expected content identity for verification
-    pub content_identity: Option<ContentIdentity>,
-}
-
-impl ContentRequest {
-    /// Create a new content request
-    pub fn new(
-        request_id: String,
-        flow_ref: FlowRef,
-        content_identity: Option<ContentIdentity>,
-    ) -> Self {
-        Self {
-            request_id,
-            flow_ref,
-            content_identity,
-        }
-    }
-}
-
-/// Response containing acquired content
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ContentResponse {
-    /// Correlation ID matching the request
-    pub request_id: String,
-    /// Content identity of the payload
-    pub content_identity: ContentIdentity,
-    /// The actual content bytes
-    pub payload: Vec<u8>,
-    /// Peer that provided this content
-    pub provider: PeerId,
-    /// Timestamp when content was acquired
-    pub acquired_at_ms: u128,
-}
-
-impl ContentResponse {
-    /// Create a new content response
-    pub fn new(
-        request_id: String,
-        content_identity: ContentIdentity,
-        payload: Vec<u8>,
-        provider: PeerId,
-    ) -> Self {
-        let now_ms = SystemTime::now()
-            .duration_since(UNIX_EPOCH)
-            .map(|d| d.as_millis())
-            .unwrap_or(0);
-
-        Self {
-            request_id,
-            content_identity,
-            payload,
-            provider,
-            acquired_at_ms: now_ms,
-        }
-    }
-}
-
-/// Result of content acquisition attempt
-#[derive(Debug, Clone)]
-pub struct AcquisitionResult {
-    /// The acquired content
-    pub payload: Vec<u8>,
-    /// Where the content came from
-    pub source_peer: PeerId,
-    /// When it was acquired
-    pub acquired_at_ms: u128,
-}
-
-impl AcquisitionResult {
-    /// Create a new acquisition result
-    pub fn new(payload: Vec<u8>, source_peer: PeerId) -> Self {
-        let now_ms = SystemTime::now()
-            .duration_since(UNIX_EPOCH)
-            .map(|d| d.as_millis())
-            .unwrap_or(0);
-
-        Self {
-            payload,
-            source_peer,
-            acquired_at_ms: now_ms,
-        }
-    }
-}
-
-/// In-flight acquisition tracking for deduplication
-#[derive(Clone)]
-pub struct AcquisitionDeduplicator {
-    /// Map from acquisition key to in-flight acquisitions
-    in_flight: Arc<
-        Mutex<
-            HashMap<
-                String,
-                Vec<
-                    tokio::sync::oneshot::Receiver<Result<AcquisitionResult, ContentTransferError>>,
-                >,
-            >,
-        >,
-    >,
-}
-
-impl AcquisitionDeduplicator {
-    /// Create a new acquisition deduplicator
-    pub fn new() -> Self {
-        Self {
-            in_flight: Arc::new(Mutex::new(HashMap::new())),
-        }
-    }
-
-    /// Check if an acquisition is already in flight
-    pub fn is_in_flight(&self, key: &str) -> Result<bool, String> {
-        let in_flight = self.in_flight.lock().map_err(|e| e.to_string())?;
-        Ok(in_flight.contains_key(key) && !in_flight[key].is_empty())
-    }
-
-    /// Register a new in-flight acquisition
-    /// Returns true if this is the first acquisition, false if joining existing
-    pub fn register_acquisition(
-        &self,
-        key: String,
-        receiver: tokio::sync::oneshot::Receiver<Result<AcquisitionResult, ContentTransferError>>,
-    ) -> Result<bool, String> {
-        let mut in_flight = self.in_flight.lock().map_err(|e| e.to_string())?;
-        let is_first = !in_flight.contains_key(&key) || in_flight[&key].is_empty();
-
-        in_flight.entry(key).or_insert_with(Vec::new).push(receiver);
-
-        Ok(is_first)
-    }
-
-    /// Mark an acquisition as complete and notify all waiters
-    pub fn mark_complete(
-        &self,
-        key: &str,
-        _result: Result<AcquisitionResult, ContentTransferError>,
-    ) -> Result<(), String> {
-        // In a real implementation, we would notify all waiting receivers
-        // For now, we just remove the entry
-        let mut in_flight = self.in_flight.lock().map_err(|e| e.to_string())?;
-        in_flight.remove(key);
-        Ok(())
-    }
-}
-
-impl Default for AcquisitionDeduplicator {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_acquisition_policy_default() {
-        assert_eq!(AcquisitionPolicy::default(), AcquisitionPolicy::PreferLocal);
-    }
-
-    #[test]
-    fn test_content_request_creation() {
-        let flow_ref = FlowRef::new("docs", "123");
-        let content_id = ContentIdentity::new("abc123");
-
-        let request = ContentRequest::new("req-1".to_string(), flow_ref.clone(), Some(content_id));
-
-        assert_eq!(request.request_id, "req-1");
-        assert_eq!(request.flow_ref.object_id, "123");
-    }
-
-    #[test]
-    fn test_content_response_creation() {
-        let content_id = ContentIdentity::new("abc123");
-        let peer = PeerId::new("peer-a");
-        let payload = vec![1, 2, 3];
-
-        let response = ContentResponse::new(
-            "req-1".to_string(),
-            content_id,
-            payload.clone(),
-            peer.clone(),
-        );
-
-        assert_eq!(response.request_id, "req-1");
-        assert_eq!(response.payload, payload);
-        assert_eq!(response.provider, peer);
-    }
-
-    #[test]
-    fn test_acquisition_result_creation() {
-        let peer = PeerId::new("peer-a");
-        let payload = vec![1, 2, 3];
-
-        let result = AcquisitionResult::new(payload.clone(), peer.clone());
-
-        assert_eq!(result.payload, payload);
-        assert_eq!(result.source_peer, peer);
-        assert!(result.acquired_at_ms > 0);
-    }
-
-    #[test]
-    fn test_acquisition_deduplicator_creation() {
-        let dedup = AcquisitionDeduplicator::new();
-        assert!(!dedup.is_in_flight("key-1").unwrap());
-    }
-
-    #[test]
-    fn test_content_transfer_error_display() {
-        let err = ContentTransferError::NotFound;
-        assert_eq!(err.to_string(), "Content not found");
-
-        let err = ContentTransferError::HashMismatch {
-            expected: "abc".to_string(),
-            computed: "def".to_string(),
-        };
-        assert!(err.to_string().contains("abc"));
-    }
-}

package/dist/create/server-source/crates/feltdb/src/admission.rs

@@ -1,185 +0,0 @@
-/// Production admission contract for FeltDB
-///
-/// Defines explicit, machine-readable submission semantics.
-/// Never silently drops operations. Rejection is explicit and retryable.
-use serde::{Deserialize, Serialize};
-use std::fmt;
-
-/// Outcome of a submission attempt
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub enum SubmissionOutcome {
-    /// Operation accepted for processing
-    /// Operations are accepted in order but may not yet be committed.
-    /// Caller should wait for CommitAck before assuming durability.
-    Accepted { operation_id: u64 },
-
-    /// Operation rejected due to backpressure
-    /// Caller should retry with backoff
-    Rejected(RejectionReason),
-}
-
-impl SubmissionOutcome {
-    pub fn is_accepted(&self) -> bool {
-        matches!(self, SubmissionOutcome::Accepted { .. })
-    }
-
-    pub fn is_rejected(&self) -> bool {
-        matches!(self, SubmissionOutcome::Rejected(_))
-    }
-}
-
-/// Explicit reason for rejection
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub enum RejectionReason {
-    /// Admission path saturated due to lock contention
-    /// Safe to retry. Caller should apply exponential backoff.
-    AdmissionBackpressure {
-        /// Microseconds to wait before retry
-        retry_after_us: u64,
-        /// Suggested backoff for caller's exponential strategy (milliseconds)
-        suggested_backoff_ms: u32,
-    },
-
-    /// Transient lock contention at submission time
-    /// Immediate retry likely to succeed
-    TransientLockContention,
-
-    /// Operation queue at capacity
-    /// Rare in normal operation; indicates severe overload
-    QueueFull,
-
-    /// Deduplication rejected duplicate (same content_hash already processed)
-    /// Not an error; operation will be applied exactly once
-    DuplicateDetected {
-        /// The original operation_id that processed this content
-        original_operation_id: u64,
-    },
-}
-
-impl fmt::Display for RejectionReason {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self {
-            RejectionReason::AdmissionBackpressure {
-                retry_after_us,
-                suggested_backoff_ms,
-            } => write!(
-                f,
-                "admission backpressure (retry after {}µs, suggested backoff {}ms)",
-                retry_after_us, suggested_backoff_ms
-            ),
-            RejectionReason::TransientLockContention => {
-                write!(f, "transient lock contention")
-            }
-            RejectionReason::QueueFull => write!(f, "admission queue full"),
-            RejectionReason::DuplicateDetected {
-                original_operation_id,
-            } => write!(
-                f,
-                "duplicate detected (original op_id: {})",
-                original_operation_id
-            ),
-        }
-    }
-}
-
-/// Production retry/backoff policy for admission
-/// Bounded, non-infinite, based on measured contention curve
-pub struct ProductionRetryPolicy {
-    /// Maximum number of lock acquisition attempts
-    pub max_attempts: usize,
-    /// Backoff durations (microseconds) for each attempt
-    pub backoff_sequence: Vec<u64>,
-}
-
-impl ProductionRetryPolicy {
-    /// Create the standard production policy
-    /// Based on Gate 14A-SYNC measurements:
-    /// - 3 retries → ~1% rejection at 8 writers
-    /// - 4 retries → near-zero rejection at intended operating envelope
-    pub fn standard() -> Self {
-        ProductionRetryPolicy {
-            max_attempts: 4,
-            backoff_sequence: vec![
-                0,   // Attempt 1: no backoff (immediate)
-                100, // Attempt 2: 100µs
-                200, // Attempt 3: 200µs
-                400, // Attempt 4: 400µs
-                     // Total: 700µs of bounded admission attempts
-            ],
-        }
-    }
-
-    /// Create a policy for testing/stress scenarios
-    /// Higher attempts for high-concurrency testing
-    pub fn stress_test() -> Self {
-        ProductionRetryPolicy {
-            max_attempts: 10,
-            backoff_sequence: vec![0, 50, 100, 150, 200, 250, 300, 350, 400, 450],
-        }
-    }
-
-    /// Get suggested backoff for a given attempt number
-    pub fn backoff_for_attempt(&self, attempt: usize) -> u64 {
-        if attempt == 0 {
-            0
-        } else if attempt <= self.backoff_sequence.len() {
-            self.backoff_sequence[attempt - 1]
-        } else {
-            // Beyond configured attempts, suggest exponential backoff to caller
-            self.backoff_sequence.last().copied().unwrap_or(400) * 2
-        }
-    }
-
-    /// Total admission time budget (sum of all backoffs)
-    pub fn total_budget_us(&self) -> u64 {
-        self.backoff_sequence.iter().sum()
-    }
-}
-
-impl Default for ProductionRetryPolicy {
-    fn default() -> Self {
-        Self::standard()
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn production_policy_is_bounded() {
-        let policy = ProductionRetryPolicy::standard();
-        assert_eq!(policy.max_attempts, 4);
-        assert_eq!(policy.backoff_sequence.len(), 4);
-        assert_eq!(policy.total_budget_us(), 700);
-    }
-
-    #[test]
-    fn stress_policy_has_higher_budget() {
-        let prod = ProductionRetryPolicy::standard();
-        let stress = ProductionRetryPolicy::stress_test();
-        assert!(stress.total_budget_us() > prod.total_budget_us());
-    }
-
-    #[test]
-    fn outcome_accessors_work() {
-        let accepted = SubmissionOutcome::Accepted { operation_id: 123 };
-        assert!(accepted.is_accepted());
-        assert!(!accepted.is_rejected());
-
-        let rejected = SubmissionOutcome::Rejected(RejectionReason::TransientLockContention);
-        assert!(!rejected.is_accepted());
-        assert!(rejected.is_rejected());
-    }
-
-    #[test]
-    fn rejection_reason_display() {
-        let backpressure = RejectionReason::AdmissionBackpressure {
-            retry_after_us: 1000,
-            suggested_backoff_ms: 10,
-        };
-        let msg = format!("{}", backpressure);
-        assert!(msg.contains("backpressure"));
-        assert!(msg.contains("1000µs"));
-    }
-}