@feltdb/core 0.6.14 → 0.7.0

package/README.md

@@ -75,6 +75,38 @@ Browser mutations resolve after their IndexedDB transaction commits. The
 durable change journal replays after reload and coordinates live collections
 across tabs through `BroadcastChannel` when available.
 
+## Atomic conditional transactions
+
+Core 0.7.0 can fence a multi-record transaction on the exact version read by
+the caller. The transaction either commits every operation or writes nothing:
+
+```typescript
+import { ConditionalConflictError } from '@feltdb/core';
+
+const current = await db.collection('accounts').get('primary');
+
+try {
+  await db.transaction({
+    transactionId: 'transfer-42',
+    preconditions: [
+      { collection: 'accounts', id: 'primary', ifVersion: current.__version },
+    ],
+    operations: [
+      { collection: 'accounts', id: 'primary', value: { balance: 90 } },
+      { collection: 'ledger', id: 'transfer-42', requireAbsent: true, value: { amount: 10 } },
+    ],
+  });
+} catch (error) {
+  if (error instanceof ConditionalConflictError) {
+    console.log(error.conflict);
+  }
+}
+```
+
+Reusing a successful `transactionId` safely replays its result without
+advancing record versions twice. This API requires a FeltDB authority that
+supports transaction-level `ifVersion` preconditions.
+
 ## Durable Operation Management
 
 FeltDB provides atomic operation admission and lifecycle management for systems that need to survive process crashes with guaranteed identity stability.

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

@@ -51,6 +51,7 @@ use feltdb::distributed_transactions::{
     SubmitOutcome,
 };
 use feltdb::replication_protocol::ProtocolTransport;
+use feltdb::replica_acknowledgements::{AcknowledgementStore, ReclamationEvidence, ReplicaAcknowledgement};
 use feltdb::replica_membership::MembershipStore;
 use feltdb::state_hash::StateHash;
 use feltdb::tcp_transport::TcpTransport;
@@ -252,6 +253,18 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     )
     .map_err(|e| e.to_string())?;
 
+    // Acknowledgements are durable and shared with the receive tasks, because
+    // they arrive on the socket rather than through a command.
+    let acknowledgements = Arc::new(Mutex::new(
+        AcknowledgementStore::open(
+            data_dir
+                .as_ref()
+                .map(|dir| dir.join("acknowledgements.json"))
+                .unwrap_or_else(|| PathBuf::from("acknowledgements.json")),
+        )
+        .map_err(|e| e.to_string())?,
+    ));
+
     let initial_state = StateHash::from_hex("0".repeat(64));
     let mut executor =
         DistributedTransactionExecutor::with_log(node_id.clone(), initial_state.clone(), log_path.clone())?;
@@ -354,6 +367,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         let peer = link.peer.clone();
         let held = held.clone();
         let backpressured = backpressured.clone();
+        let acknowledgements = acknowledgements.clone();
         tokio::spawn(async move {
             while !exit.load(Ordering::Relaxed) {
                 {
@@ -396,6 +410,15 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
                     match transport.receive().await {
                         Ok(messages) => {
+                            // Acknowledgements arrive interleaved with
+                            // envelopes on the same connection. They are
+                            // durable before they count as evidence.
+                            for ack in transport.take_acknowledgements().await {
+                                let mut store = acknowledgements.lock().await;
+                                if let Err(error) = store.record(ack) {
+                                    eprintln!("acknowledgement not recorded: {error}");
+                                }
+                            }
                             for message in messages {
                                 {
                                     let mut hold = held.lock().await;
@@ -792,6 +815,99 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                 io::stdout().flush().ok();
             }
 
+            // Report what this node has durably applied, to every peer.
+            //
+            // The frontier is read from the executor, where it advances only in
+            // record_applied -- after an fsynced envelope is applied. So the
+            // statement "durably applied through this frontier" is true by
+            // construction rather than by assertion.
+            "ack-broadcast" => {
+                let (frontier, marks) = {
+                    let guard = core.lock().await;
+                    let (executor, _) = &*guard;
+                    (executor.causal_frontier().clone(), executor.origin_sequence_high_water())
+                };
+                let view: Vec<String> = membership
+                    .get_members()
+                    .into_iter()
+                    .map(|replica| replica.replica_id)
+                    .collect();
+                let replica_id = membership
+                    .get_members()
+                    .into_iter()
+                    .find(|replica| replica.node_id == node_id)
+                    .map(|replica| replica.replica_id)
+                    .unwrap_or_else(|| node_id.clone());
+
+                let ack = ReplicaAcknowledgement::new(
+                    replica_id.clone(),
+                    node_id.clone(),
+                    frontier,
+                    marks,
+                    view,
+                );
+
+                // A node's own acknowledgement is evidence it holds first-hand:
+                // it knows its own durable frontier without being told. Without
+                // this a node would be permanently blocked on itself, since
+                // nothing else can report on its behalf.
+                {
+                    let mut store = acknowledgements.lock().await;
+                    let _ = store.record(ack.clone());
+                }
+
+                let mut delivered = Vec::new();
+                for link in &send_links {
+                    if link.io.send_acknowledgement(ack.clone()).await.is_ok() {
+                        delivered.push(link.peer.clone());
+                    } else if connect_with_retry(link, 3).await
+                        && link.io.send_acknowledgement(ack.clone()).await.is_ok()
+                    {
+                        delivered.push(link.peer.clone());
+                    }
+                }
+                println!(
+                    "ACK_SENT {}",
+                    json!({
+                        "replica_id": replica_id,
+                        "frontier": ack.applied_frontier.clocks,
+                        "delivered": delivered,
+                    })
+                );
+                io::stdout().flush().ok();
+            }
+
+            "acknowledgements" => {
+                let store = acknowledgements.lock().await;
+                println!("ACKS {}", json!({ "acknowledgements": store.all() }));
+                io::stdout().flush().ok();
+            }
+
+            // What this node's evidence permits. Computes; reclaims nothing.
+            "reclamation-evidence" => {
+                let local: Vec<String> = membership
+                    .get_required_replicas()
+                    .into_iter()
+                    .map(|replica| replica.replica_id)
+                    .collect();
+                let store = acknowledgements.lock().await;
+                let report = match store.evidence(&local) {
+                    ReclamationEvidence::Blocked { waiting_on } => json!({
+                        "state": "BLOCKED",
+                        "waiting_on": waiting_on,
+                        "required_union": store.required_union(&local),
+                    }),
+                    ReclamationEvidence::SafeThrough { frontier, covered } => json!({
+                        "state": "SAFE_THROUGH",
+                        "frontier": frontier.clocks,
+                        "covered": covered,
+                        "required_union": store.required_union(&local),
+                    }),
+                };
+                println!("EVIDENCE {}", report);
+                io::stdout().flush().ok();
+            }
+
             "members" => {
                 println!(
                     "MEMBERS {}",

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

@@ -385,6 +385,25 @@ impl DistributedTransactionExecutor {
     // that decision alone.
     // ---------------------------------------------------------------------
 
+    /// The highest identity committed to the durable log, per origin.
+    ///
+    /// For this node it is its own identity high-water mark; for others it is
+    /// how far this replica's log carries their identities. A checkpoint that
+    /// discards log prefix must preserve these, because the log is also the
+    /// source `next_origin_sequence` is recovered from.
+    pub fn origin_sequence_high_water(&self) -> std::collections::BTreeMap<String, u64> {
+        let mut marks = std::collections::BTreeMap::new();
+        let Some(ref log) = self.operation_log else { return marks };
+        let Ok(envelopes) = log.load_all() else { return marks };
+        for envelope in envelopes {
+            let entry = marks
+                .entry(envelope.envelope_id.originating_node.clone())
+                .or_insert(0u64);
+            *entry = (*entry).max(envelope.envelope_id.sequence);
+        }
+        marks
+    }
+
     /// The next identity this node would issue.
     pub fn next_origin_sequence(&self) -> u64 {
         self.next_origin_sequence

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;
@@ -52,6 +53,7 @@ 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;
@@ -254,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 {
@@ -263,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}"),
         }
     }
 }
@@ -330,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,
@@ -931,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");
@@ -948,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!(