@feltdb/core 0.4.12 → 0.4.13

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

@@ -0,0 +1,286 @@
+/// 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

@@ -0,0 +1,192 @@
+/// 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"));
+    }
+}