@feltdb/core 0.6.13 → 0.7.0

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

@@ -24,6 +24,7 @@ pub mod analytics;
 pub mod distributed_indexing;
 pub mod indexing;
 pub mod sharding;
+pub mod transaction_preconditions;
 pub mod transactions;
 pub mod state_hash;
 pub mod crash_injection;
@@ -43,11 +44,16 @@ pub mod crash_atomic_boundary;
 pub mod multi_operation_transaction;
 pub mod p1_atomicity_acceptance;
 pub mod p1_application_atomicity;
+pub mod causal_backlog_bound;
+pub mod dedup_bound_investigation;
+pub mod durable_operation_identity;
 pub mod causal_dependency_barrier;
 pub mod partition_reconciliation;
 pub mod consistency_contract;
 pub mod persistence_reality;
 pub mod adversarial_transport;
+pub mod replica_membership;
+pub mod replica_acknowledgements;
 pub mod replication_manager;
 pub mod metrics;
 pub mod query_performance;
@@ -250,6 +256,12 @@ pub enum FlowError {
     Serde(serde_json::Error),
     CorruptLogLine(String),
     CapabilityError(String),
+    /// A transaction precondition did not hold. Nothing was written.
+    ///
+    /// Separate from `CapabilityError` because a conflict is an expected
+    /// outcome of a race and a caller is meant to branch on it, while a
+    /// capability error is not.
+    PreconditionFailed(Box<PreconditionFailure>),
 }
 
 impl Display for FlowError {
@@ -259,6 +271,7 @@ impl Display for FlowError {
             FlowError::Serde(e) => write!(f, "serde error: {e}"),
             FlowError::CorruptLogLine(line) => write!(f, "corrupt log line: {line}"),
             FlowError::CapabilityError(msg) => write!(f, "capability error: {msg}"),
+            FlowError::PreconditionFailed(failure) => write!(f, "PRECONDITION_FAILED: {failure}"),
         }
     }
 }
@@ -326,6 +339,109 @@ pub struct AtomicPrecondition {
     pub key: String,
     pub expected_version: Option<u64>,
 }
+
+/// What must be true of one record for a transaction to commit.
+///
+/// Distinct from `AtomicPrecondition`, and deliberately so. That one compares
+/// the row's internal operation *sequence*, and `None` on it means "this record
+/// must not exist". This one compares the fields a caller can actually read
+/// back -- the document's `__version`, its authority epoch, its lease -- which
+/// are the same fields single-record CAS compares. Plumbing a caller's
+/// `expectedVersion` into the sequence check would have compared a document
+/// version against a storage sequence: two different numbers that happen to
+/// share a name.
+///
+/// Every predicate is optional and only a supplied one is checked. That differs
+/// from CAS, where an absent `expected_lease_id` asserts the record is *not*
+/// leased; here an absent predicate asserts nothing at all. The difference is
+/// deliberate -- a transaction precondition is a fence the caller opts into,
+/// not a full description of the record -- and it is why the fields are named
+/// `expected_*` rather than describing a state.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct RecordPrecondition {
+    pub capability: String,
+    pub key: String,
+    /// The record must not exist. Mutually exclusive with the predicates below.
+    #[serde(default)]
+    pub require_absent: bool,
+    /// The document's `__version`, as `updateIfVersion` compares it.
+    #[serde(default)]
+    pub expected_version: Option<u64>,
+    /// The record's authority epoch, at `/authority/epoch`.
+    #[serde(default)]
+    pub expected_epoch: Option<u64>,
+    /// The id of an unexpired lease held on the record.
+    #[serde(default)]
+    pub expected_lease_id: Option<String>,
+}
+
+impl RecordPrecondition {
+    /// True when this precondition asks for nothing, which is a caller error
+    /// rather than a satisfied fence: a precondition that constrains nothing
+    /// would read as protection and provide none.
+    pub fn is_empty(&self) -> bool {
+        !self.require_absent
+            && self.expected_version.is_none()
+            && self.expected_epoch.is_none()
+            && self.expected_lease_id.is_none()
+    }
+}
+
+/// Which predicate failed, and what the authority actually holds.
+///
+/// Structured rather than a formatted string, because the caller has to tell a
+/// lost race from a broken deployment: the first is retried with fresh state,
+/// the second is not retried at all.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", tag = "predicate")]
+pub enum PreconditionFailure {
+    /// Required absent, but the record exists.
+    Present { collection: String, key: String },
+    /// A predicate was given for a record that does not exist.
+    Missing { collection: String, key: String },
+    Version { collection: String, key: String, expected: u64, actual: u64 },
+    Epoch { collection: String, key: String, expected: u64, actual: u64 },
+    Lease { collection: String, key: String, expected: String, actual: Option<String> },
+}
+
+impl PreconditionFailure {
+    pub fn collection(&self) -> &str {
+        match self {
+            Self::Present { collection, .. }
+            | Self::Missing { collection, .. }
+            | Self::Version { collection, .. }
+            | Self::Epoch { collection, .. }
+            | Self::Lease { collection, .. } => collection,
+        }
+    }
+    /// The storage key, which is namespaced as `collection:id`.
+    pub fn key(&self) -> &str {
+        match self {
+            Self::Present { key, .. }
+            | Self::Missing { key, .. }
+            | Self::Version { key, .. }
+            | Self::Epoch { key, .. }
+            | Self::Lease { key, .. } => key,
+        }
+    }
+}
+
+impl Display for PreconditionFailure {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Present { collection, key } =>
+                write!(f, "{collection}/{key} was required to be absent but exists"),
+            Self::Missing { collection, key } =>
+                write!(f, "{collection}/{key} does not exist"),
+            Self::Version { collection, key, expected, actual } =>
+                write!(f, "{collection}/{key} is at version {actual}, expected {expected}"),
+            Self::Epoch { collection, key, expected, actual } =>
+                write!(f, "{collection}/{key} is at epoch {actual}, expected {expected}"),
+            Self::Lease { collection, key, expected, actual } =>
+                write!(f, "{collection}/{key} holds lease {actual:?}, expected {expected}"),
+        }
+    }
+}
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AtomicCommit {
     pub transaction_id: String,
@@ -927,6 +1043,40 @@ impl FeltDb {
         preconditions: &[AtomicPrecondition],
         mutations: &[AtomicMutation],
         audit: Option<Value>,
+    ) -> Result<AtomicCommit> {
+        self.apply_atomic_transaction_guarded(
+            transaction_id,
+            payload_hash,
+            expected_parent,
+            preconditions,
+            &[],
+            mutations,
+            audit,
+        )
+    }
+
+    /// Commit a transaction only if every record precondition holds.
+    ///
+    /// The preconditions are evaluated inside the same lock as the writes and
+    /// before any of them, so there is no state in which one record is checked
+    /// while the others commit. A failure returns
+    /// `FlowError::PreconditionFailed` and applies nothing -- not a prefix, not
+    /// the guarded record, nothing.
+    ///
+    /// A failed precondition does **not** consume the transaction id. The id is
+    /// recorded only after a commit, so a caller that loses a race may retry
+    /// the same id once it has re-read state, and a caller that wants the
+    /// retry to be a distinct decision may use a new one. Both work; the choice
+    /// is the caller's and is asserted in the tests rather than left implied.
+    pub fn apply_atomic_transaction_guarded(
+        &self,
+        transaction_id: &str,
+        payload_hash: Option<&str>,
+        expected_parent: Option<u64>,
+        preconditions: &[AtomicPrecondition],
+        record_preconditions: &[RecordPrecondition],
+        mutations: &[AtomicMutation],
+        audit: Option<Value>,
     ) -> Result<AtomicCommit> {
         let (commit, events) = {
             let mut inner = self.inner.lock().expect("lock poisoned");
@@ -944,6 +1094,140 @@ impl FeltDb {
                     duplicate: true,
                 });
             }
+            // Record preconditions, evaluated before anything is staged and
+            // under the same lock the writes take. A caller reads state,
+            // decides, and commits; this is the fence that makes the decision
+            // still true at the moment of the write.
+            for condition in record_preconditions {
+                if condition.is_empty() {
+                    return Err(FlowError::CapabilityError(format!(
+                        "EMPTY_PRECONDITION:{}:{}",
+                        condition.capability, condition.key
+                    )));
+                }
+                let collection = condition.capability.clone();
+                let key = condition.key.clone();
+                let current = inner
+                    .rows
+                    .get(&condition.capability)
+                    .and_then(|bucket| bucket.get(&condition.key));
+
+                if condition.require_absent {
+                    if current.is_some() {
+                        return Err(FlowError::PreconditionFailed(Box::new(
+                            PreconditionFailure::Present { collection, key },
+                        )));
+                    }
+                    continue;
+                }
+
+                let Some(current) = current else {
+                    return Err(FlowError::PreconditionFailed(Box::new(
+                        PreconditionFailure::Missing { collection, key },
+                    )));
+                };
+
+                // The same fields single-record CAS compares, read the same way.
+                if let Some(expected) = condition.expected_version {
+                    let actual = current
+                        .value
+                        .get("__version")
+                        .and_then(Value::as_u64)
+                        .unwrap_or(1);
+                    if actual != expected {
+                        return Err(FlowError::PreconditionFailed(Box::new(
+                            PreconditionFailure::Version { collection, key, expected, actual },
+                        )));
+                    }
+                }
+                if let Some(expected) = condition.expected_epoch {
+                    let actual = current
+                        .value
+                        .pointer("/authority/epoch")
+                        .and_then(Value::as_u64)
+                        .unwrap_or(0);
+                    if actual != expected {
+                        return Err(FlowError::PreconditionFailed(Box::new(
+                            PreconditionFailure::Epoch { collection, key, expected, actual },
+                        )));
+                    }
+                }
+                if let Some(expected) = &condition.expected_lease_id {
+                    let lease = current.value.get("lease").filter(|lease| !lease.is_null());
+                    let held = lease.and_then(|lease| {
+                        lease.get("leaseId").and_then(Value::as_str).map(str::to_string)
+                    });
+                    // An expired lease is not held, so naming it is a conflict:
+                    // the caller believes it owns something it no longer does.
+                    let unexpired = lease
+                        .and_then(|lease| lease.get("expiresAt").and_then(Value::as_u64))
+                        .is_some_and(|expires_at| expires_at > now_ms() as u64);
+                    if held.as_deref() != Some(expected.as_str()) || !unexpired {
+                        return Err(FlowError::PreconditionFailed(Box::new(
+                            PreconditionFailure::Lease {
+                                collection,
+                                key,
+                                expected: expected.clone(),
+                                actual: held,
+                            },
+                        )));
+                    }
+                }
+            }
+
+            // Every precondition held. A write fenced by `expected_version` is a
+            // conditional replacement and behaves as `updateIfVersion` does:
+            // the authority validated version N above and writes N + 1 here,
+            // inside the same lock, so the check and the advance cannot be
+            // separated by another writer.
+            //
+            // Only a version-fenced write advances. An unconditional write
+            // stores the caller's object verbatim, which is what preserves
+            // every existing transaction caller, and a guard-only precondition
+            // writes nothing at all. See
+            // docs/architecture/transaction-version-contract.md.
+            let mut advanced: Vec<AtomicMutation> = Vec::new();
+            let fenced: HashMap<(&str, &str), u64> = record_preconditions
+                .iter()
+                .filter_map(|condition| {
+                    condition
+                        .expected_version
+                        .map(|version| ((condition.capability.as_str(), condition.key.as_str()), version))
+                })
+                .collect();
+            let mutations: &[AtomicMutation] = if fenced.is_empty() {
+                mutations
+            } else {
+                advanced = mutations
+                    .iter()
+                    .map(|mutation| {
+                        let Some(expected) =
+                            fenced.get(&(mutation.capability.as_str(), mutation.key.as_str()))
+                        else {
+                            return mutation.clone();
+                        };
+                        // A delete has no record left to carry a version, so a
+                        // fenced delete is fence-then-remove and nothing more.
+                        let Some(Value::Object(fields)) = mutation.value.clone() else {
+                            return mutation.clone();
+                        };
+                        let mut fields = fields;
+                        // The authority owns the transition. A `__version` the
+                        // caller put in the value is replaced rather than
+                        // honoured, exactly as updateIfVersion strips it,
+                        // because a caller that computes a different next
+                        // version must not be able to install it.
+                        fields.insert("__version".to_string(), Value::from(expected + 1));
+                        AtomicMutation {
+                            capability: mutation.capability.clone(),
+                            key: mutation.key.clone(),
+                            value: Some(Value::Object(fields)),
+                        }
+                    })
+                    .collect();
+                &advanced
+            };
+
             if let Some(expected) = expected_parent {
                 if expected != inner.sequence {
                     return Err(FlowError::CapabilityError(format!(