@feltdb/core 0.8.3 → 0.8.5

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

@@ -25,7 +25,8 @@ use crate::{
     policy_evaluation::{
         Actor, AuthorizationState, PolicyEvaluator, PolicySubject, RecordAuthorizationContext,
     },
-    AtomicMutation, AtomicPrecondition, FeltDb, StoredRow,
+    AtomicMutation, AtomicPrecondition, FeltDb, FlowError, PreconditionFailure, RecordPrecondition,
+    StoredRow,
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
@@ -853,6 +854,12 @@ pub struct StateFailure {
     pub transaction: Option<String>,
     #[serde(default)]
     pub causal_position: Option<u64>,
+    /// The structured predicate failure, when the refusal was a record
+    /// precondition. Named `failure` because that is what the direct
+    /// authority's refused transaction already calls it: one refusal, one
+    /// shape, whichever endpoint answered.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub failure: Option<Value>,
 }
 impl StateFailure {
     fn new(code: &str, message: &str) -> Self {
@@ -864,6 +871,7 @@ impl StateFailure {
             resource: None,
             transaction: None,
             causal_position: None,
+            failure: None,
         }
     }
     fn storage(error: impl std::fmt::Display) -> Self {
@@ -1611,10 +1619,47 @@ pub struct TransactionOperation {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case")]
 pub enum TransactionPrecondition {
-    CollectionVersion { collection: String, version: u64 },
-    StateVersion { version: u64 },
-    ApplicationRevision { revision_id: String },
-    CausalCursor { cursor: BTreeMap<String, u64> },
+    CollectionVersion {
+        collection: String,
+        version: u64,
+    },
+    StateVersion {
+        version: u64,
+    },
+    ApplicationRevision {
+        revision_id: String,
+    },
+    CausalCursor {
+        cursor: BTreeMap<String, u64>,
+    },
+    /// What must be true of one record for the transaction to commit.
+    ///
+    /// Distinct from every variant above, and evaluated in a different place
+    /// for a reason: those compare counters that can be read before the commit
+    /// lock is taken, while this one compares the fields a caller reads back —
+    /// the document's `__version`, its authority epoch, its lease — and must
+    /// therefore be evaluated *inside* the same lock as the writes. Checking it
+    /// against the pre-commit snapshot would be a client-side check wearing the
+    /// authority's name: between the read and the write, another writer
+    /// commits.
+    ///
+    /// It is also what makes `putIfAbsent` and `updateIfVersion` mean the same
+    /// thing against a managed authority as against the file runtime. Mapping
+    /// a caller's `expectedVersion` onto `if_version` would not: that fences
+    /// the row's internal storage sequence, which is a different number that
+    /// happens to share a name.
+    Record {
+        collection: String,
+        id: String,
+        #[serde(default)]
+        require_absent: bool,
+        #[serde(default)]
+        expected_version: Option<u64>,
+        #[serde(default)]
+        expected_epoch: Option<u64>,
+        #[serde(default)]
+        expected_lease_id: Option<String>,
+    },
 }
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TransactionRequest {
@@ -2056,8 +2101,47 @@ fn execute_transaction_with_policies(
         });
     }
     let snapshot = db.state_rows().map_err(StateFailure::storage)?;
+    let namespace = request
+        .state_namespace
+        .as_deref()
+        .unwrap_or(&request.application_id)
+        .to_string();
+    // Record preconditions are collected here and evaluated by the store,
+    // inside the same lock as the writes. Evaluating them against `snapshot`
+    // alongside the counters below would reintroduce exactly the gap they
+    // exist to close.
+    let mut record_preconditions: Vec<RecordPrecondition> = Vec::new();
     for condition in &request.preconditions {
         let (resource, expected, actual, passed) = match condition {
+            TransactionPrecondition::Record {
+                collection,
+                id,
+                require_absent,
+                expected_version,
+                expected_epoch,
+                expected_lease_id,
+            } => {
+                let precondition = RecordPrecondition {
+                    capability: format!("{namespace}:{collection}"),
+                    key: id.clone(),
+                    require_absent: *require_absent,
+                    expected_version: *expected_version,
+                    expected_epoch: *expected_epoch,
+                    expected_lease_id: expected_lease_id.clone(),
+                };
+                if precondition.is_empty() {
+                    // Refused rather than ignored: a precondition that
+                    // constrains nothing reads as protection and provides none.
+                    let mut failure = StateFailure::new(
+                        "VALIDATION_FAILED",
+                        &format!("precondition on {collection}:{id} constrains nothing"),
+                    );
+                    failure.resource = Some(format!("{collection}:{id}"));
+                    return Err(failure);
+                }
+                record_preconditions.push(precondition);
+                continue;
+            }
             TransactionPrecondition::CollectionVersion {
                 collection,
                 version,
@@ -2350,15 +2434,37 @@ fn execute_transaction_with_policies(
         }
     }
     let commit = db
-        .apply_atomic_transaction_content_addressed(
+        .apply_atomic_transaction_guarded(
             &storage_transaction_id,
             Some(&payload_hash),
             request.causal_parent,
             &preconditions,
+            &record_preconditions,
             &mutations,
             Some(serde_json::json!({"transaction_id":transaction_id.clone(),"subject":request.authorization.subject.clone(),"tenant":request.tenant_id.clone(),"application":request.application_id.clone(),"revision":request.revision_id.clone(),"schema_version":request.schema_version,"operations":request.operations.len(),"authorization_decisions":["state:write allowed"],"causal_parent":request.causal_parent,"result":"committed"})),
         )
         .map_err(|error| {
+            // A record precondition that did not hold is a lost race, and it
+            // says which predicate failed and what the authority holds. That
+            // detail is the difference between "re-read and decide again" and
+            // "this deployment is broken", so it is carried through as
+            // structure rather than flattened into the message.
+            if let FlowError::PreconditionFailed(refusal) = &error {
+                let mut failure =
+                    StateFailure::new("PRECONDITION_FAILED", &error.to_string());
+                failure.transaction = Some(transaction_id.clone());
+                failure.causal_position = db.sequence().ok();
+                failure.resource = Some(refusal.key().to_string());
+                failure.failure = serde_json::to_value(refusal.as_ref()).ok();
+                if let PreconditionFailure::Version {
+                    expected, actual, ..
+                } = refusal.as_ref()
+                {
+                    failure.expected = Some(Value::from(*expected));
+                    failure.actual = Some(Value::from(*actual));
+                }
+                return failure;
+            }
             let text = error.to_string();
             if text.contains("PRECONDITION_FAILED") {
                 let mut failure = StateFailure::new("PRECONDITION_FAILED", &text);
@@ -2665,6 +2771,199 @@ mod tests {
             "CONFLICT"
         );
     }
+    /// A conditional write through the canonical contract has to mean the same
+    /// thing it means everywhere else in FeltDB, or `putIfAbsent` and
+    /// `updateIfVersion` become file-runtime privileges.
+    ///
+    /// The predicate under test is the document's `__version` -- the number a
+    /// caller reads back -- not the row's internal storage sequence. Those are
+    /// two different numbers that happen to share a name, and a fence on the
+    /// wrong one is worse than no fence, because it reads as protection.
+    #[test]
+    fn a_record_precondition_fences_the_document_version() {
+        let db = db("record-precondition");
+        let schema = schema();
+        let write = |id: &str,
+                     transaction: &str,
+                     title: &str,
+                     preconditions: Vec<TransactionPrecondition>,
+                     kind: TransactionOperationKind| {
+            execute_transaction(
+                &db,
+                &schema,
+                &TransactionRequest {
+                    transaction_id: Some(transaction.into()),
+                    tenant_id: "tenant".into(),
+                    application_id: "app".into(),
+                    revision_id: "rev".into(),
+                    schema_version: 1,
+                    state_namespace: None,
+                    causal_parent: None,
+                    authorization: auth(),
+                    preconditions,
+                    operations: vec![TransactionOperation {
+                        kind,
+                        collection: "incidents".into(),
+                        id: id.into(),
+                        value: serde_json::json!({ "title": title }),
+                        if_version: None,
+                    }],
+                },
+                None,
+            )
+        };
+        let fence = |version: Option<u64>, absent: bool| {
+            vec![TransactionPrecondition::Record {
+                collection: "incidents".into(),
+                id: "i1".into(),
+                require_absent: absent,
+                expected_version: version,
+                expected_epoch: None,
+                expected_lease_id: None,
+            }]
+        };
+        let version = || {
+            db.state_rows()
+                .unwrap()
+                .into_iter()
+                .find(|row| row.capability == "app:incidents" && row.key == "i1" && !row.deleted)
+                .and_then(|row| row.value.get("__version").and_then(Value::as_u64))
+        };
+
+        // A conditional create is a create at version 1.
+        write(
+            "i1",
+            "create",
+            "First",
+            fence(None, true),
+            TransactionOperationKind::Insert,
+        )
+        .expect("the record is absent, so the create commits");
+        assert_eq!(version(), Some(1));
+
+        // The same create again is a lost race. Whichever check catches it,
+        // the answer is a conflict and nothing was written.
+        let refused = write(
+            "i1",
+            "create-again",
+            "Second",
+            fence(None, true),
+            TransactionOperationKind::Insert,
+        )
+        .expect_err("the record now exists");
+        assert!(
+            refused.code == "CONFLICT" || refused.code == "PRECONDITION_FAILED",
+            "a lost creation race is a conflict, got {}",
+            refused.code,
+        );
+        assert_eq!(version(), Some(1), "a refused transaction writes nothing");
+
+        // A guard on a record the transaction does not write is evaluated
+        // inside the commit lock, and says which predicate failed.
+        let guarded = write(
+            "i2",
+            "guarded",
+            "Other",
+            fence(None, true),
+            TransactionOperationKind::Insert,
+        )
+        .expect_err("i1 exists, so the guard fails and i2 is never written");
+        assert_eq!(guarded.code, "PRECONDITION_FAILED");
+        assert_eq!(
+            guarded
+                .failure
+                .as_ref()
+                .and_then(|value| value.get("predicate").and_then(Value::as_str)),
+            Some("present"),
+        );
+        assert!(
+            db.state_rows()
+                .unwrap()
+                .iter()
+                .all(|row| row.key != "i2" || row.deleted),
+            "a refused guard leaves the staged write unwritten",
+        );
+
+        // A stale fence conflicts and names what the authority actually holds.
+        let stale = write(
+            "i1",
+            "stale",
+            "Third",
+            fence(Some(7), false),
+            TransactionOperationKind::Update,
+        )
+        .expect_err("version 7 is not the version on record");
+        assert_eq!(stale.code, "PRECONDITION_FAILED");
+        assert_eq!(stale.expected, Some(Value::from(7)));
+        assert_eq!(stale.actual, Some(Value::from(1)));
+        assert_eq!(version(), Some(1));
+
+        // The fenced write commits and the authority owns the next version.
+        write(
+            "i1",
+            "fenced",
+            "Fourth",
+            fence(Some(1), false),
+            TransactionOperationKind::Update,
+        )
+        .expect("version 1 is the version on record");
+        assert_eq!(version(), Some(2));
+
+        // Replaying a committed transaction id applies nothing, so it cannot
+        // advance the version a second time.
+        write(
+            "i1",
+            "fenced",
+            "Fourth",
+            fence(Some(1), false),
+            TransactionOperationKind::Update,
+        )
+        .expect("a duplicate transaction id is not a failure");
+        assert_eq!(version(), Some(2));
+    }
+
+    /// A precondition that constrains nothing is refused rather than accepted,
+    /// because one that is silently ignored reads as protection and provides
+    /// none.
+    #[test]
+    fn an_empty_record_precondition_is_refused() {
+        let db = db("empty-precondition");
+        let schema = schema();
+        let failure = execute_transaction(
+            &db,
+            &schema,
+            &TransactionRequest {
+                transaction_id: Some("empty".into()),
+                tenant_id: "tenant".into(),
+                application_id: "app".into(),
+                revision_id: "rev".into(),
+                schema_version: 1,
+                state_namespace: None,
+                causal_parent: None,
+                authorization: auth(),
+                preconditions: vec![TransactionPrecondition::Record {
+                    collection: "incidents".into(),
+                    id: "i1".into(),
+                    require_absent: false,
+                    expected_version: None,
+                    expected_epoch: None,
+                    expected_lease_id: None,
+                }],
+                operations: vec![TransactionOperation {
+                    kind: TransactionOperationKind::Insert,
+                    collection: "incidents".into(),
+                    id: "i1".into(),
+                    value: serde_json::json!({ "title": "First" }),
+                    if_version: None,
+                }],
+            },
+            None,
+        )
+        .expect_err("a precondition that constrains nothing is a caller error");
+        assert_eq!(failure.code, "VALIDATION_FAILED");
+        assert!(db.state_rows().unwrap().iter().all(|row| row.deleted));
+    }
+
     #[test]
     fn validation_failure_rolls_back_every_operation() {
         let db = db("rollback");

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

@@ -0,0 +1,222 @@
+//! The deterministic contract behind FeltDB's semantic state diff.
+//!
+//! This is the second specimen of the pattern established by
+//! [`crate::trigger_contract`]: a decision FeltDB already makes, drawn behind a
+//! runtime-independent boundary so that more than one implementation can be
+//! held to it.
+//!
+//! ```text
+//!        canonical state A  +  canonical state B
+//!                        │
+//!         ┌──────────────┴──────────────┐
+//!         │                             │
+//!   native evaluation             WASM evaluation
+//!         │                             │
+//!         └──────────────┬──────────────┘
+//!                        │
+//!               canonical diff bytes
+//! ```
+//!
+//! # This module adds no diff semantics
+//!
+//! [`SemanticDiff::compute`] is untouched and remains authoritative. Everything
+//! here is envelope: identity, version, canonical encoding, and the decision to
+//! report an unusable input rather than fail. If this module and
+//! `SemanticDiff::compute` ever disagree, `SemanticDiff::compute` is right.
+//!
+//! # Determinism budget
+//!
+//! Evaluation reads nothing but its two states. No clock, filesystem, network,
+//! random source, process identity, authentication context, authority metadata
+//! or process-global mutable state participates, and the audit that produced
+//! this contract found none in the implementation either.
+//!
+//! # What the audit established about the semantics
+//!
+//! These are properties of the existing implementation, recorded here because
+//! the contract is defined against them rather than against an idea of what a
+//! diff should do:
+//!
+//! - **Arrays are positional.** A reorder is not detected; `[1,2] -> [2,1]`
+//!   reports `Changed` at index 0 and at index 1. Elements past the shorter
+//!   length become `Added` or `Removed` at their index.
+//! - **Absence and null are different, in both directions.** `missing -> value`
+//!   is `Added`, `null -> value` is `Changed`, `value -> missing` is `Removed`,
+//!   `value -> null` is `Changed`.
+//! - **`old_value` and `new_value` are `Option`, encoded as `null` when absent.**
+//!   That is ambiguous with a JSON null on its own, and `kind` is what
+//!   disambiguates: `missing -> null` is `Added` with `new_value: null`.
+//! - **Numbers compare by `serde_json` variant.** `42` and `42.0` differ, so
+//!   they report `Changed`; `-0` is a float and so differs from the integer
+//!   `0`; `-0.0` and `0.0` are equal under IEEE equality and report nothing.
+//! - **A type transition is one `Changed`,** carrying both whole values, at the
+//!   path where it happens — including at the empty path, for the states
+//!   themselves.
+//! - **Ordering is total.** Changes sort by path, then by kind. Paths are
+//!   unique within one diff, so the ordering does not depend on sort stability.
+
+use crate::state_model::SemanticDiff;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+
+/// Stable identity of this contract.
+pub const STATE_DIFF_CONTRACT_ID: &str = "feltdb.state.diff";
+
+/// Version of this contract's input shape, output shape and semantics.
+///
+/// The output shape is [`SemanticDiff`]'s own serialization, so a change to
+/// that type is a change to this contract and must bump this.
+pub const STATE_DIFF_CONTRACT_VERSION: u32 = 1;
+
+/// The complete deterministic input: two states, and the contract's identity.
+///
+/// Members are declared alphabetically so the canonical struct encoding matches
+/// the sorted-key encoding `serde_json` gives every JSON object.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateDiffInput {
+    pub contract: String,
+    pub state_a: Value,
+    pub state_b: Value,
+    pub version: u32,
+}
+
+impl StateDiffInput {
+    /// Builds an input stamped with this contract's identity and version.
+    pub fn new(state_a: Value, state_b: Value) -> Self {
+        Self {
+            contract: STATE_DIFF_CONTRACT_ID.to_string(),
+            state_a,
+            state_b,
+            version: STATE_DIFF_CONTRACT_VERSION,
+        }
+    }
+}
+
+/// Why an input could not be evaluated.
+///
+/// Three codes, matching the vocabulary [`crate::trigger_contract`] uses. As
+/// there, an error carries a code and nothing else: a free-form message would
+/// be a divergence surface between implementations that says nothing about the
+/// semantics under test.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum ContractErrorCode {
+    /// The bytes are not a well-formed instance of this contract's input.
+    ContractInputInvalid,
+    /// The input declares a different contract.
+    ContractIdMismatch,
+    /// The input declares a version this implementation does not implement.
+    ContractVersionUnsupported,
+}
+
+/// The error body of a contract output.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ContractErrorBody {
+    pub code: ContractErrorCode,
+}
+
+/// The complete deterministic output.
+///
+/// Exactly one of `diff` and `error` is present. `diff` is [`SemanticDiff`]
+/// serialized exactly as it already serializes — this contract does not
+/// reshape it, because the existing semantic result *is* the contract.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateDiffOutput {
+    pub contract: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub diff: Option<SemanticDiff>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error: Option<ContractErrorBody>,
+    pub version: u32,
+}
+
+impl StateDiffOutput {
+    fn computed(diff: SemanticDiff) -> Self {
+        Self {
+            contract: STATE_DIFF_CONTRACT_ID.to_string(),
+            diff: Some(diff),
+            error: None,
+            version: STATE_DIFF_CONTRACT_VERSION,
+        }
+    }
+
+    fn failure(code: ContractErrorCode) -> Self {
+        Self {
+            contract: STATE_DIFF_CONTRACT_ID.to_string(),
+            diff: None,
+            error: Some(ContractErrorBody { code }),
+            version: STATE_DIFF_CONTRACT_VERSION,
+        }
+    }
+}
+
+/// The runtime that executed a contract, recorded in evidence.
+///
+/// Only [`ContractRuntime::Native`] is wired anywhere. As with the trigger
+/// contract, the WASM variant exists so a recorded runtime can be named
+/// honestly; it is not a selection switch.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ContractRuntime {
+    Native,
+    Wasm,
+}
+
+impl ContractRuntime {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Native => "native",
+            Self::Wasm => "wasm",
+        }
+    }
+}
+
+/// The deterministic contract, natively implemented.
+///
+/// A thin adapter over the existing implementation, deliberately holding no
+/// diff logic of its own.
+pub fn diff_states(state_a: &Value, state_b: &Value) -> SemanticDiff {
+    SemanticDiff::compute(state_a, state_b)
+}
+
+/// The canonical byte encoding of a contract input.
+pub fn canonical_input_bytes(input: &StateDiffInput) -> Vec<u8> {
+    serde_json::to_vec(input).expect("contract input is always serializable")
+}
+
+/// The canonical byte encoding of a contract output.
+pub fn canonical_output_bytes(output: &StateDiffOutput) -> Vec<u8> {
+    serde_json::to_vec(output).expect("contract output is always serializable")
+}
+
+/// Content identity of a contract input, for provenance.
+pub fn input_digest(input: &StateDiffInput) -> String {
+    format!("sha256:{:x}", Sha256::digest(canonical_input_bytes(input)))
+}
+
+/// The runtime-independent entry point: canonical bytes in, canonical bytes out.
+///
+/// This is the exact shape a foreign runtime implements. It never panics and
+/// never returns anything but a canonical output encoding, so an unusable input
+/// is a contract decision rather than a host-specific failure mode.
+pub fn evaluate_canonical(input: &[u8]) -> Vec<u8> {
+    canonical_output_bytes(&evaluate_canonical_output(input))
+}
+
+/// [`evaluate_canonical`] before encoding, for callers that want the value.
+pub fn evaluate_canonical_output(input: &[u8]) -> StateDiffOutput {
+    let Ok(parsed) = serde_json::from_slice::<StateDiffInput>(input) else {
+        return StateDiffOutput::failure(ContractErrorCode::ContractInputInvalid);
+    };
+    if parsed.contract != STATE_DIFF_CONTRACT_ID {
+        return StateDiffOutput::failure(ContractErrorCode::ContractIdMismatch);
+    }
+    if parsed.version != STATE_DIFF_CONTRACT_VERSION {
+        return StateDiffOutput::failure(ContractErrorCode::ContractVersionUnsupported);
+    }
+    StateDiffOutput::computed(diff_states(&parsed.state_a, &parsed.state_b))
+}