@feltdb/core 0.12.1 → 0.13.0

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

@@ -5,7 +5,8 @@
 //! the socket boundary.
 
 use crate::{
-    AtomicCommit, AtomicMutation, AtomicPrecondition, FeltDb, RecordPrecondition, StoredRow,
+    AtomicCommit, AtomicMutation, AtomicPrecondition, FeltDb, PayloadBinding, RecordPrecondition,
+    StoredRow,
 };
 use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
@@ -120,8 +121,78 @@ impl EmbeddedAuthority {
     }
 }
 
+/// Names the construction of the payload digest the authority binds ids to.
+///
+/// The prefix is stored with the digest in the durable transaction record, so a
+/// digest written by a different construction is recognizable as one this
+/// build cannot judge, instead of being read as a mismatch.
+const PAYLOAD_DIGEST_PREFIX: &str = "authority-tx1:sha256:";
+
+/// Canonical text of a JSON value: object members sorted by name at every
+/// depth, array order preserved. Written out here rather than left to
+/// `serde_json`'s map ordering, which is a build feature that another crate in
+/// the dependency graph can change.
+fn canonical_json(value: &Value, out: &mut String) {
+    match value {
+        Value::Object(map) => {
+            let mut keys: Vec<&String> = map.keys().collect();
+            keys.sort();
+            out.push('{');
+            for (index, key) in keys.into_iter().enumerate() {
+                if index > 0 {
+                    out.push(',');
+                }
+                out.push_str(&Value::String(key.clone()).to_string());
+                out.push(':');
+                canonical_json(&map[key], out);
+            }
+            out.push('}');
+        }
+        Value::Array(items) => {
+            out.push('[');
+            for (index, item) in items.iter().enumerate() {
+                if index > 0 {
+                    out.push(',');
+                }
+                canonical_json(item, out);
+            }
+            out.push(']');
+        }
+        other => out.push_str(&other.to_string()),
+    }
+}
+
+/// The digest an id is bound to: everything the commit acts on or records, and
+/// not the id itself. `audit` is included because it is committed evidence the
+/// caller supplied, not transport metadata; two requests that record different
+/// audit facts under one id are different requests.
+fn payload_digest(transaction: &AuthorityTransaction) -> Result<String, AuthorityError> {
+    let semantic = serde_json::json!({
+        "base_revision": transaction.base_revision,
+        "preconditions": transaction.preconditions,
+        "record_preconditions": transaction.record_preconditions,
+        "mutations": transaction.mutations,
+        "audit": transaction.audit,
+    });
+    let mut canonical = String::new();
+    canonical_json(&semantic, &mut canonical);
+    Ok(format!(
+        "{PAYLOAD_DIGEST_PREFIX}{:x}",
+        Sha256::digest(canonical.as_bytes())
+    ))
+}
+
 fn authority_error(error: crate::FlowError) -> AuthorityError {
     match error {
+        crate::FlowError::TransactionIdPayloadMismatch { transaction_id: id } => {
+            AuthorityError {
+                code: "IDEMPOTENCY_CONFLICT".into(),
+                message: format!(
+                    "transaction {id} was already committed with a different payload"
+                ),
+                authoritative_revision: None,
+            }
+        }
         crate::FlowError::RevisionConflict {
             expected: _,
             actual,
@@ -152,17 +223,54 @@ impl FeltDbAuthority for EmbeddedAuthority {
         &self,
         transaction: AuthorityTransaction,
     ) -> Result<AtomicCommit, AuthorityError> {
-        self.db
+        let digest = payload_digest(&transaction)?;
+        // How the id is already known, if it is. A recorded hash never changes
+        // and a missing one never appears, so this read cannot be invalidated
+        // by a concurrent commit: the comparison that matters -- the id against
+        // the digest of this request -- is made by the core, atomically with
+        // the commit, under the lock that serializes every writer.
+        let id = transaction.transaction_id.as_str();
+        let applied = self.db.has_applied_transaction(id).map_err(authority_error)?;
+        let recorded = if applied {
+            self.db
+                .applied_transaction_payload_hash(id)
+                .map_err(authority_error)?
+        } else {
+            None
+        };
+        let (bound, legacy) = match (applied, recorded) {
+            (false, _) => (Some(digest), false),
+            // Committed before ids were bound: the id is all there is to compare.
+            (true, None) => (None, true),
+            (true, Some(hash)) if hash.starts_with(PAYLOAD_DIGEST_PREFIX) => (Some(digest), false),
+            // Recorded by a construction this build does not know, or by another
+            // writer's: neither a match nor a mismatch can be established.
+            (true, Some(_)) => {
+                return Err(AuthorityError {
+                    code: "IDEMPOTENCY_UNVERIFIABLE".into(),
+                    message: format!(
+                        "transaction {id} exists, but its recorded payload identity cannot be verified by this build"
+                    ),
+                    authoritative_revision: None,
+                })
+            }
+        };
+        let mut commit = self
+            .db
             .apply_atomic_transaction_guarded(
-                &transaction.transaction_id,
-                None,
+                id,
+                bound.as_deref(),
                 transaction.base_revision,
                 &transaction.preconditions,
                 &transaction.record_preconditions,
                 &transaction.mutations,
-                transaction.audit,
+                transaction.audit.clone(),
             )
-            .map_err(authority_error)
+            .map_err(authority_error)?;
+        if legacy && commit.duplicate {
+            commit.payload_binding = Some(PayloadBinding::LegacyUnverified);
+        }
+        Ok(commit)
     }
 }
 
@@ -267,6 +375,17 @@ impl AuthorityClient {
     }
 
     async fn request(&self, request: Request) -> Result<Response, AuthorityError> {
+        // Once a commit has been handed to the authority it may have been
+        // applied whether or not an answer comes back, so every failure from
+        // that point is an unknown outcome, not a failure.
+        let is_commit = matches!(request, Request::Commit { .. });
+        let unknown = |detail: String| AuthorityError {
+            code: "COMMIT_OUTCOME_UNKNOWN".into(),
+            message: format!(
+                "the commit may or may not have been applied ({detail}); retry with the same transaction id and payload"
+            ),
+            authoritative_revision: None,
+        };
         let mut stream = UnixStream::connect(&self.socket_path)
             .await
             .map_err(|error| AuthorityError {
@@ -283,17 +402,26 @@ impl AuthorityClient {
                 })?,
             )
             .await
-            .map_err(io_authority_error)?;
-        stream.write_all(b"\n").await.map_err(io_authority_error)?;
+            .map_err(|error| if is_commit { unknown(error.to_string()) } else { io_authority_error(error) })?;
+        stream
+            .write_all(b"\n")
+            .await
+            .map_err(|error| if is_commit { unknown(error.to_string()) } else { io_authority_error(error) })?;
         let mut response = String::new();
         BufReader::new(stream)
             .read_line(&mut response)
             .await
-            .map_err(io_authority_error)?;
-        match serde_json::from_str(&response).map_err(|error| AuthorityError {
-            code: "INVALID_RESPONSE".into(),
-            message: error.to_string(),
-            authoritative_revision: None,
+            .map_err(|error| if is_commit { unknown(error.to_string()) } else { io_authority_error(error) })?;
+        match serde_json::from_str(&response).map_err(|error| {
+            if is_commit {
+                unknown(format!("unreadable response: {error}"))
+            } else {
+                AuthorityError {
+                    code: "INVALID_RESPONSE".into(),
+                    message: error.to_string(),
+                    authoritative_revision: None,
+                }
+            }
         })? {
             Response::Error(error) => Err(error),
             response => Ok(response),
@@ -340,8 +468,10 @@ impl FeltDbAuthority for AuthorityClient {
         match self.request(Request::Commit { transaction }).await? {
             Response::Commit(commit) => Ok(commit),
             _ => Err(AuthorityError {
-                code: "INVALID_RESPONSE".into(),
-                message: "expected authority commit".into(),
+                code: "COMMIT_OUTCOME_UNKNOWN".into(),
+                message: "the authority answered a commit with something other than a commit; \
+                          its outcome is unknown, retry with the same transaction id and payload"
+                    .into(),
                 authoritative_revision: None,
             }),
         }

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

@@ -1,10 +1,158 @@
+//! # FeltDB
+//!
+//! A durable, embedded state store. Records live under a *capability* (the part of a key before
+//! the first `:`, so `"orders:o-1"` is record `o-1` of capability `orders`). Every write goes
+//! through a durable log; several records can be changed in one atomic transaction; an update can
+//! be made conditional on the version you read; and a transaction can carry an identity so that a
+//! retry after an uncertain outcome is recognized instead of applied twice.
+//!
+//! ```
+//! use feltdb::{AtomicMutation, FeltDb, FlowError, PayloadBinding, RecordPrecondition};
+//! use serde_json::{json, Value};
+//!
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! let dir = tempfile::tempdir()?;
+//! let path = dir.path().join("app.db");
+//! let db = FeltDb::open(&path)?;
+//!
+//! // Create a record only if it is absent: a second create is refused, and refused in a way a
+//! // caller can branch on.
+//! db.insert_if_absent("orders:o-1", json!({ "status": "pending" }))?;
+//! assert!(matches!(
+//!     db.insert_if_absent("orders:o-1", json!({})),
+//!     Err(FlowError::PreconditionFailed(_))
+//! ));
+//!
+//! // Change several records atomically, and name the transaction so a retry is safe. The payload
+//! // hash is yours to compute: FeltDB stores it and compares it for equality.
+//! let ship = |hash: &str| {
+//!     db.apply_atomic_transaction_content_addressed(
+//!         "ship-o-1",
+//!         Some(hash),
+//!         None,
+//!         &[],
+//!         &[
+//!             AtomicMutation {
+//!                 capability: "orders".into(),
+//!                 key: "orders:o-1".into(),
+//!                 value: Some(json!({ "status": "shipped" })),
+//!             },
+//!             AtomicMutation {
+//!                 capability: "audit".into(),
+//!                 key: "audit:a-1".into(),
+//!                 value: Some(json!({ "order": "o-1", "event": "shipped" })),
+//!             },
+//!         ],
+//!         None,
+//!     )
+//! };
+//! let first = ship("sha256:payload-v1")?;
+//! assert!(!first.duplicate);
+//!
+//! // The same request again is recognized as the original, not applied a second time.
+//! let retry = ship("sha256:payload-v1")?;
+//! assert!(retry.duplicate);
+//! assert_eq!(retry.payload_binding, Some(PayloadBinding::Verified));
+//! assert_eq!(retry.commit_revision, first.commit_revision);
+//!
+//! // The same id with a different payload is refused, with a typed error. Nothing is written.
+//! assert!(matches!(
+//!     ship("sha256:payload-v2"),
+//!     Err(FlowError::TransactionIdPayloadMismatch { .. })
+//! ));
+//!
+//! // Close and reopen: what was acknowledged is there.
+//! drop(db);
+//! let db = FeltDb::open(&path)?;
+//! assert_eq!(db.get::<Value>("orders:o-1")?, Some(json!({ "status": "shipped" })));
+//! # let _ = RecordPrecondition::default();
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ## What is supported
+//!
+//! Only the items in this table are covered by the compatibility policy
+//! ([`docs/reference/feltdb-rust-api.md`] in the repository). While the version is `0.x`, a breaking
+//! change to them is a minor-version bump and is recorded in the changelog; everything else may
+//! change in any release.
+//!
+//! | To | Use |
+//! | --- | --- |
+//! | open, recover, reopen | [`FeltDb::open`], [`FeltDb::log_recovery`], [`FeltDb::health`] |
+//! | read | [`FeltDb::get`], [`FeltDb::query`] |
+//! | write unconditionally | [`FeltDb::insert`], [`FeltDb::update`], [`FeltDb::delete`] (all three are plain writes: see below) |
+//! | create only if absent | [`FeltDb::insert_if_absent`] |
+//! | update only if unchanged | [`FeltDb::compare_and_set_json`] → [`JsonCasResult`] |
+//! | change several records atomically | [`FeltDb::apply_atomic_transaction`], [`FeltDb::apply_atomic_transaction_guarded`] with [`AtomicMutation`] and [`RecordPrecondition`] → [`AtomicCommit`] |
+//! | make a retry safe | [`FeltDb::apply_atomic_transaction_content_addressed`], [`FeltDb::has_applied_transaction`], [`FeltDb::applied_transaction_payload_hash`], [`PayloadBinding`] |
+//! | tell failures apart | [`FlowError`] and its variants, [`PreconditionFailure`] |
+//! | a durable authority for several processes | the [`authority`] module (Unix) |
+//!
+//! **Behavior to know before relying on it.**
+//! `insert`, `update` and `delete` are unconditional: `insert` replaces an existing record, `update`
+//! of a missing key *creates* it, and `delete` of a missing key succeeds. A fenced write
+//! ([`FeltDb::compare_and_set_json`], a [`RecordPrecondition`] with `expected_version`) treats a record
+//! that has never been through one as version 1, and a record's `__version` becomes visible in its JSON
+//! after its first fenced write. A transaction refused for a failed precondition writes nothing.
+//! A transaction id committed *without* a payload hash can be retried (it is a duplicate, with no
+//! [`PayloadBinding`]), but retrying it *with* a hash is refused, because there is nothing to verify against.
+//!
+//! ## Durability
+//!
+//! An acknowledged write survives the process being killed. Whether it survives the machine losing
+//! power depends on the operating system and drive honouring a flush, and is **not** established.
+//! A log ending in an incomplete append is recovered by discarding that append, which was never
+//! acknowledged: [`FeltDb::log_recovery`] says so. A corrupt log, or one in a format this build does
+//! not understand, refuses to open and is left as found.
+//!
+//! ## Stability tiers
+//!
+//! * **Supported**: the table above.
+//! * **Experimental**: [`agent_state`], [`agent_transition_contract`], the deterministic-contract
+//!   adapters, [`semantic_decision`] and [`semantic_query`]. Public so they can be used, but they
+//!   may change shape before they are stabilized.
+//! * **Not yet classified**: the other public modules. They are public today and carry no promise;
+//!   each is listed with the decision still needed in the repository's Rust API audit.
+//! * **Internals**: implementation, fault-injection and diagnostic modules are private unless the
+//!   `unstable-internals` feature is enabled, and nothing behind that feature is covered by any promise.
+//!
+//! `FlowError` is `#[non_exhaustive]`: match on its variants, always with a catch-all arm, and never
+//! on message text.
+//!
+//! [`docs/reference/feltdb-rust-api.md`]: https://github.com/rkendel1/flow_db/blob/main/docs/reference/feltdb-rust-api.md
+
+macro_rules! unstable_internal_modules {
+    ($($name:ident),* $(,)?) => {
+        $(
+            #[cfg(feature = "unstable-internals")]
+            pub mod $name;
+            #[cfg(not(feature = "unstable-internals"))]
+            #[allow(dead_code, unused_imports)]
+            mod $name;
+        )*
+    };
+}
+
+unstable_internal_modules! {
+    adversarial_transport,
+    concurrency_fuzzing,
+    crash_injection,
+    replay_fuzzing,
+    permutation_scheduler,
+    persistence_reality,
+    in_process_transport,
+    query_execution_diagnostics,
+    workload_diagnostics,
+    cardinality_endpoint,
+}
+
 #[cfg(test)]
 mod acceptance_tests;
 mod acquisition;
 pub mod admission;
 #[cfg(test)]
 mod admission_contract_tests;
-pub mod adversarial_transport;
 pub mod analytics;
 pub mod application;
 pub mod application_runtime;
@@ -17,33 +165,32 @@ mod authorization_security_tests;
 pub mod capabilities;
 mod capability;
 mod cardinality_diagnostics;
-pub mod cardinality_endpoint;
-pub mod causal_backlog_bound;
+#[cfg(test)]
+mod causal_backlog_bound;
 pub mod causal_dependency_barrier;
 #[cfg(test)]
 mod causal_dependency_barrier_phase_7_1;
-pub mod concurrency_fuzzing;
 pub mod consistency_contract;
 mod content_distribution;
 pub mod convergence;
 pub mod crash_atomic_boundary;
-pub mod crash_injection;
 #[cfg(test)]
 mod crash_recovery_tests;
 mod cron;
-pub mod dedup_bound_investigation;
+#[cfg(test)]
+mod dedup_bound_investigation;
 pub mod distributed_indexing;
 #[cfg(test)]
 mod distributed_tests;
 pub mod distributed_transactions;
 pub mod durability_guarantees;
 pub mod durable_dedup_set;
-pub mod durable_operation_identity;
+#[cfg(test)]
+mod durable_operation_identity;
 pub mod durable_operation_log;
 pub mod durable_sync;
 pub mod equality_index;
 mod execution;
-pub mod in_process_transport;
 pub mod indexing;
 #[cfg(test)]
 mod managed_cas_tests;
@@ -55,12 +202,12 @@ pub mod observability;
 mod operation;
 pub mod operation_algebra;
 pub mod operation_log;
-pub mod p1_application_atomicity;
-pub mod p1_atomicity_acceptance;
+#[cfg(test)]
+mod p1_application_atomicity;
+#[cfg(test)]
+mod p1_atomicity_acceptance;
 pub mod partition_reconciliation;
 mod peer_registry;
-pub mod permutation_scheduler;
-pub mod persistence_reality;
 #[cfg(test)]
 mod phase1b_acceptance;
 #[cfg(test)]
@@ -99,11 +246,10 @@ mod phase_5_soak;
 pub mod policy_evaluation;
 pub mod production_api;
 mod provenance;
-pub mod query_execution_diagnostics;
 pub mod query_performance;
-pub mod read_basis;
+#[cfg(test)]
+mod read_basis;
 mod references;
-pub mod replay_fuzzing;
 pub mod replica_acknowledgements;
 pub mod replica_membership;
 pub mod replication_manager;
@@ -112,6 +258,8 @@ mod routing;
 pub mod semantic_decision;
 pub mod semantic_query;
 pub mod sharding;
+pub mod agent_state;
+pub mod agent_transition_contract;
 pub mod state_conflict_contract;
 pub mod state_contract;
 pub mod state_diff_contract;
@@ -129,7 +277,8 @@ pub mod tcp_transport;
 pub mod transaction_api;
 #[cfg(test)]
 mod transaction_invariants;
-pub mod transaction_preconditions;
+#[cfg(test)]
+mod transaction_preconditions;
 pub mod transactions;
 mod trigger;
 pub mod trigger_contract;
@@ -141,13 +290,13 @@ mod workflow_acceptance_tests;
 mod workflow_integration;
 mod workflow_runtime;
 pub mod workload;
-pub mod workload_diagnostics;
 
 pub use acquisition::{
     AcquisitionDeduplicator, AcquisitionPolicy, AcquisitionResult, ContentRequest, ContentResponse,
     ContentTransferError,
 };
 pub use admission::{ProductionRetryPolicy, RejectionReason, SubmissionOutcome};
+#[cfg(feature = "unstable-internals")]
 pub use adversarial_transport::{
     AdversarialTransport, ConnectionId, ConnectivityMatrix, FaultSeed, InMemoryTransport,
     LinkState, MessageId, NetworkEvent, NetworkSchedule, NodeId, ReplicationTransport,
@@ -210,7 +359,9 @@ pub use partition_reconciliation::{
     ReconciliationResult, ReplicaPartition,
 };
 pub use peer_registry::PeerRegistry;
+#[cfg(feature = "unstable-internals")]
 pub use permutation_scheduler::{OperationSchedule, PermutationScheduler, ScheduleStrategy};
+#[cfg(feature = "unstable-internals")]
 pub use persistence_reality::{
     CorruptionDetectionResult, DurablePersistenceLayer, FsyncDurabilityResult,
     PersistenceContractVerifier, PersistenceCrashPoint, RecoveryResult, WALEntry, WriteResult,
@@ -325,7 +476,14 @@ use tokio::sync::broadcast;
 
 pub type Result<T> = std::result::Result<T, FlowError>;
 
+/// Why an operation failed.
+///
+/// Branch on the variant, never on message text. The enum is `#[non_exhaustive]`: a later release
+/// may add variants, so a `match` needs a catch-all arm. `CapabilityError` carries a human-readable
+/// message, some of which begin with an upper-case code (`INVALID_READ_SET:`, `EMPTY_PRECONDITION:`);
+/// those prefixes are **not** a supported way to tell failures apart and may change.
 #[derive(Debug)]
+#[non_exhaustive]
 pub enum FlowError {
     Io(std::io::Error),
     Serde(serde_json::Error),
@@ -337,6 +495,16 @@ pub enum FlowError {
     /// outcome of a race and a caller is meant to branch on it, while a
     /// capability error is not.
     PreconditionFailed(Box<PreconditionFailure>),
+    /// A transaction id was already committed with a **different** payload. Nothing was written, and
+    /// the id still names the original transaction.
+    ///
+    /// Returned when a payload hash is supplied for an id that was committed with another one, and
+    /// also when an id that was committed *without* a hash is retried *with* one, since there is
+    /// nothing recorded to verify against. Retrying with the same id cannot succeed: use a new id
+    /// for a new transaction, or resend the original payload to confirm the original.
+    TransactionIdPayloadMismatch {
+        transaction_id: String,
+    },
     /// The transaction was based on a revision which is no longer current.
     RevisionConflict {
         expected: u64,
@@ -360,6 +528,10 @@ impl Display for FlowError {
             FlowError::CorruptLogLine(corruption) => write!(f, "CORRUPT_DURABLE_LOG: {corruption}"),
             FlowError::CapabilityError(msg) => write!(f, "capability error: {msg}"),
             FlowError::PreconditionFailed(failure) => write!(f, "PRECONDITION_FAILED: {failure}"),
+            FlowError::TransactionIdPayloadMismatch { transaction_id } => write!(
+                f,
+                "IDEMPOTENCY_CONFLICT: transaction {transaction_id} was already committed with a different payload"
+            ),
             FlowError::RevisionConflict { expected, actual } => write!(
                 f,
                 "REVISION_CONFLICT: expected authority revision {expected}, current revision is {actual}"
@@ -1012,6 +1184,23 @@ pub struct AtomicCommit {
     pub state_after: u64,
     pub rows: Vec<StoredRow>,
     pub duplicate: bool,
+    /// How a duplicate was recognized. Present only on a duplicate, and only
+    /// when the caller's request could be compared with what was committed
+    /// (`Verified`) or was deliberately judged by id alone (`LegacyUnverified`).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub payload_binding: Option<PayloadBinding>,
+}
+
+/// What a duplicate transaction id was checked against.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum PayloadBinding {
+    /// The id and the payload hash both match what was committed: this request
+    /// is the original one.
+    Verified,
+    /// The id was committed without a payload hash, so only the id could be
+    /// checked. The caller must not read this as proof the payload matches.
+    LegacyUnverified,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
@@ -3204,9 +3393,9 @@ impl FeltDb {
                         .map(String::as_str)
                         != Some(expected_hash)
                     {
-                        return Err(FlowError::CapabilityError(format!(
-                            "TRANSACTION_ID_PAYLOAD_MISMATCH:{transaction_id}"
-                        )));
+                        return Err(FlowError::TransactionIdPayloadMismatch {
+                            transaction_id: transaction_id.to_string(),
+                        });
                     }
                 }
                 let (base_revision, commit_revision) = inner
@@ -3229,6 +3418,7 @@ impl FeltDb {
                     state_after,
                     rows: vec![],
                     duplicate: true,
+                    payload_binding: payload_hash.map(|_| PayloadBinding::Verified),
                 });
             }
             // Record preconditions, evaluated before anything is staged and
@@ -3599,6 +3789,7 @@ impl FeltDb {
                     state_after: inner.sequence,
                     rows,
                     duplicate: false,
+                    payload_binding: None,
                 },
                 events,
             )
@@ -3962,6 +4153,15 @@ impl FeltDb {
         Ok(inner.sync_state.clone())
     }
 
+    /// The authority's wall-clock time in milliseconds.
+    ///
+    /// The same reading the commit-time lease predicate uses, exposed so a
+    /// decision that depends on lease expiry can be made against the clock that
+    /// will later judge the commit. A caller's own clock is never a substitute.
+    pub fn authority_time_ms(&self) -> u64 {
+        now_ms() as u64
+    }
+
     /// Read an untyped value for protocol adapters such as the HTTP server.
     pub fn get_value(&self, key: &str) -> Result<Option<Value>> {
         self.get::<Value>(key)
@@ -6116,9 +6316,13 @@ mod tests {
                 None,
             )
             .unwrap_err();
-        assert!(conflict
-            .to_string()
-            .contains("TRANSACTION_ID_PAYLOAD_MISMATCH:"));
+        assert!(
+            matches!(
+                &conflict,
+                FlowError::TransactionIdPayloadMismatch { transaction_id } if transaction_id == "managed-idempotency-1"
+            ),
+            "expected the typed idempotency conflict, got {conflict:?}"
+        );
         let _ = fs::remove_file(sync_metadata_path(&path));
         let _ = fs::remove_file(path);
     }

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

@@ -1603,11 +1603,7 @@ pub(crate) mod durable {
                 | PreconditionFailure::Version { .. } => Refusal::Changed,
                 other => Refusal::Failed(format!("{other:?}")),
             },
-            FlowError::CapabilityError(message)
-                if message.starts_with("TRANSACTION_ID_PAYLOAD_MISMATCH") =>
-            {
-                Refusal::OtherRequest
-            }
+            FlowError::TransactionIdPayloadMismatch { .. } => Refusal::OtherRequest,
             other => Refusal::Failed(other.to_string()),
         }
     }