create-feltdb 0.9.1 → 0.11.0

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

@@ -130,6 +130,7 @@ pub mod transaction_preconditions;
 pub mod transactions;
 mod trigger;
 pub mod trigger_contract;
+pub mod versioned_object_substrate;
 pub mod worker_mesh;
 mod workflow;
 #[cfg(test)]
@@ -238,9 +239,11 @@ pub use state_facade::FeltDBStateSystem;
 pub use state_hash::{CanonicalState, StateHash};
 pub use state_model::{
     apply_reconciliation_plan, path_relation, paths_overlap, reconcile, resolve_path, ChangeKind,
-    ConflictClass, ConflictClassification, PathComponent, PathConflict, PathRelation,
-    ReconciliationPlan, Relationship, SemanticChange, SemanticDiff, StateId,
-    StateReconciliationResult, StateRevision, StateStore, StateTopology, STATE_MODEL_VERSION,
+    ConflictClass, ConflictClassification, GarbageCollectionError, GarbageCollectionReport,
+    MaterializationError, MaterializationProjection, PathComponent, PathConflict, PathRelation,
+    ReconciliationPlan, RefError, Relationship, SemanticChange, SemanticDiff, StateId, StateObject,
+    StateReconciliationResult, StateRef, StateRevision, StateStore, StateTopology,
+    STATE_MODEL_VERSION,
 };
 pub use state_transition_store::{MemoryStateTransitionStore, StateTransitionRecord};
 pub use state_trigger::{
@@ -262,6 +265,10 @@ pub use trigger_contract::{
     ContractRuntime, ContractTrigger, MatchOutcome, MatchReason, TriggerMatchInput,
     TriggerMatchOutput, TRIGGER_MATCH_CONTRACT_ID, TRIGGER_MATCH_CONTRACT_VERSION,
 };
+pub use versioned_object_substrate::{
+    DurableObjectStore, DurableRef, LocalObjectStore, Reachability, S3CompatibleBucket,
+    S3CompatibleObjectStore, SubstrateError, VersionedObjectSubstrate,
+};
 pub use workflow::{
     BlockedReason, WorkflowGraph, WorkflowInstance, WorkflowNode, WorkflowOperation, WorkflowRef,
     WorkflowState, WorkflowStepRef, WorkflowStepState,
@@ -280,12 +287,12 @@ use std::any::type_name;
 use std::collections::hash_map::DefaultHasher;
 use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque};
 use std::fmt::{Display, Formatter};
-use std::fs::{self, OpenOptions};
+use std::fs::{self, File, OpenOptions};
 use std::hash::{Hash, Hasher};
 use std::io::{BufRead, BufReader, Write};
 use std::ops::Bound::{Excluded, Unbounded};
 use std::path::{Path, PathBuf};
-use std::sync::{Arc, Mutex};
+use std::sync::{Arc, Mutex, OnceLock, Weak};
 use std::time::{SystemTime, UNIX_EPOCH};
 use tokio::sync::broadcast;
 
@@ -362,8 +369,17 @@ impl From<String> for FlowError {
 pub struct FeltDb {
     inner: Arc<Mutex<Inner>>,
     event_tx: broadcast::Sender<ChangeEvent>,
+    _ownership: Arc<File>,
+}
+
+struct OpenDatabase {
+    inner: Weak<Mutex<Inner>>,
+    event_tx: broadcast::Sender<ChangeEvent>,
+    ownership: Weak<File>,
 }
 
+static OPEN_DATABASES: OnceLock<Mutex<HashMap<PathBuf, OpenDatabase>>> = OnceLock::new();
+
 #[derive(Default)]
 #[allow(dead_code)] // Reserved runtime subsystems are initialized before their public APIs land.
 struct Inner {
@@ -403,6 +419,10 @@ struct Inner {
     /// audit archive, and the durable log remains the record of what happened.
     /// Keeping it bounded is what makes it safe to maintain on the commit path.
     transaction_attributions: VecDeque<TransactionAttribution>,
+    /// Complete committed transaction order, rebuilt exclusively from the
+    /// durable transaction log. Unlike the bounded operator window above this
+    /// is the canonical replay/provenance index.
+    transaction_history: Vec<TransactionAttribution>,
     collection_cardinality: HashMap<String, u64>,
     /// Derived equality index over `rows`. Never durable, never replicated, and
     /// never consulted for anything but candidate selection: it is maintained
@@ -505,6 +525,12 @@ impl Inner {
         let bucket = self.rows.entry(capability.clone()).or_default();
         let previous = bucket.insert(key.clone(), row);
         drop(mutation);
+        if previous.is_none() {
+            *self
+                .collection_cardinality
+                .entry(capability.clone())
+                .or_default() += 1;
+        }
         if !indexed {
             return previous.is_none();
         }
@@ -543,6 +569,11 @@ impl Inner {
             return false;
         };
         drop(mutation);
+        let count = self
+            .collection_cardinality
+            .entry(capability.to_string())
+            .or_default();
+        *count = count.saturating_sub(1);
         let _index = workload_diagnostics::span(workload_diagnostics::Phase::IndexMaintenance);
         self.equality_index
             .remove_record(capability, key, &removed.value);
@@ -552,6 +583,7 @@ impl Inner {
     /// Drop all records, as a snapshot install does. The index follows.
     fn clear_rows(&mut self) {
         self.rows.clear();
+        self.collection_cardinality.clear();
         self.equality_index.clear();
     }
 }
@@ -773,6 +805,10 @@ const TRANSACTION_ATTRIBUTION_KEYS: usize = 32;
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct TransactionAttribution {
     pub transaction_id: String,
+    /// Stable operation identities assigned to the rows in this transaction.
+    /// These are distinct from both transaction and revision identity.
+    #[serde(default)]
+    pub operation_ids: Vec<String>,
     /// The actor the caller authenticated as, when the transaction named one.
     pub subject: Option<String>,
     pub tenant_id: Option<String>,
@@ -789,8 +825,23 @@ pub struct TransactionAttribution {
     /// How many mutations the transaction made, whether or not `keys` lists
     /// them all.
     pub operations: usize,
+    #[serde(default)]
+    pub principal_id: Option<String>,
+    #[serde(default)]
+    pub agent_id: Option<String>,
+    #[serde(default)]
+    pub session_id: Option<String>,
+    #[serde(default)]
+    pub delegator_id: Option<String>,
+    #[serde(default)]
+    pub work_id: Option<String>,
     /// Milliseconds since the epoch, matching `StoredRow::unix_ms`.
     pub unix_ms: u128,
+    /// Canonical transaction metadata exactly as committed. Record values are
+    /// deliberately absent; stable work/session/agent/operation references
+    /// live here so historical provenance survives process loss.
+    #[serde(default)]
+    pub audit: Option<Value>,
 }
 
 impl TransactionAttribution {
@@ -813,6 +864,13 @@ impl TransactionAttribution {
         };
         TransactionAttribution {
             transaction_id: transaction_id.to_string(),
+            operation_ids: rows
+                .iter()
+                .filter_map(|row| row.operation.as_ref())
+                .map(|operation| {
+                    format!("operation:{}:{}", operation.instance_id, operation.sequence)
+                })
+                .collect(),
             subject: text("subject"),
             tenant_id: text("tenant"),
             application_id: text("application"),
@@ -827,7 +885,13 @@ impl TransactionAttribution {
                 .map(|row| format!("{}:{}", row.capability, row.key))
                 .collect(),
             operations: rows.len(),
+            principal_id: text("principal_id"),
+            agent_id: text("agent_id"),
+            session_id: text("session_id"),
+            delegator_id: text("delegator_id"),
+            work_id: text("work_id").or_else(|| text("workload_id")),
             unix_ms,
+            audit: audit.cloned(),
         }
     }
 
@@ -838,14 +902,84 @@ impl TransactionAttribution {
     }
 }
 
+/// Upgrade compacted attribution written before operation identities became a
+/// first-class part of canonical history. The mapping is deterministic from
+/// durable transaction data, so reopening never regenerates a different ID.
+fn normalize_transaction_attribution(
+    mut attribution: TransactionAttribution,
+) -> TransactionAttribution {
+    if attribution.operation_ids.is_empty() {
+        if attribution.transaction_id.starts_with("operation:") {
+            let operation_id = attribution.transaction_id.clone();
+            attribution.transaction_id = operation_id.replacen("operation:", "transaction:", 1);
+            attribution.operation_ids.push(operation_id);
+        } else {
+            attribution.operation_ids = (1..=attribution.operations)
+                .map(|index| {
+                    format!(
+                        "operation:legacy-transaction:{}:{index}",
+                        attribution.transaction_id
+                    )
+                })
+                .collect();
+        }
+    }
+    attribution
+}
+
 /// Records an attribution, discarding the oldest once the window is full.
 fn remember_attribution(inner: &mut Inner, attribution: TransactionAttribution) {
+    inner.transaction_history.push(attribution.clone());
     if inner.transaction_attributions.len() >= TRANSACTION_ATTRIBUTION_WINDOW {
         inner.transaction_attributions.pop_front();
     }
     inner.transaction_attributions.push_back(attribution);
 }
 
+fn remember_operation_attribution(
+    inner: &mut Inner,
+    row: &StoredRow,
+    base_revision: u64,
+    commit_revision: u64,
+) {
+    let Some(operation) = row.operation.as_ref() else {
+        return;
+    };
+    remember_attribution(
+        inner,
+        TransactionAttribution {
+            transaction_id: format!(
+                "transaction:{}:{}",
+                operation.instance_id, operation.sequence
+            ),
+            operation_ids: vec![format!(
+                "operation:{}:{}",
+                operation.instance_id, operation.sequence
+            )],
+            subject: None,
+            tenant_id: None,
+            application_id: None,
+            application_revision: operation
+                .revision
+                .as_ref()
+                .map(|revision| revision.id.clone()),
+            base_revision,
+            commit_revision,
+            state_before: operation.sequence.saturating_sub(1),
+            state_after: operation.sequence,
+            keys: vec![format!("{}:{}", row.capability, row.key)],
+            operations: 1,
+            principal_id: None,
+            agent_id: None,
+            session_id: None,
+            delegator_id: None,
+            work_id: None,
+            unix_ms: row.unix_ms,
+            audit: None,
+        },
+    );
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct TransactionLogRecord {
     record_type: String,
@@ -1551,6 +1685,15 @@ struct LogHeader {
     /// which deserialize as 0 and are classified as unversioned.
     #[serde(default)]
     format_version: u32,
+    /// Canonical commit provenance retained when operation-log compaction
+    /// rewrites current state. This is history, not a derived event store.
+    #[serde(default)]
+    transaction_history: Vec<TransactionAttribution>,
+    /// Durable binding between a caller transaction identity and its semantic
+    /// request. Compaction must retain this or an old id could be reused for a
+    /// different mutation after restart.
+    #[serde(default)]
+    transaction_payload_hashes: HashMap<String, String>,
 }
 
 #[derive(Debug, Default, Serialize, Deserialize)]
@@ -1834,7 +1977,56 @@ struct RetentionRecord {
 
 impl FeltDb {
     pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
-        let path = path.as_ref().to_path_buf();
+        let requested_path = path.as_ref();
+        let parent = requested_path
+            .parent()
+            .filter(|parent| !parent.as_os_str().is_empty())
+            .unwrap_or_else(|| Path::new("."));
+        fs::create_dir_all(parent)?;
+        let path = if requested_path.exists() {
+            fs::canonicalize(requested_path)?
+        } else {
+            let file_name = requested_path.file_name().ok_or_else(|| {
+                std::io::Error::new(
+                    std::io::ErrorKind::InvalidInput,
+                    "FeltDB database path has no file name",
+                )
+            })?;
+            fs::canonicalize(parent)?.join(file_name)
+        };
+
+        let databases = OPEN_DATABASES.get_or_init(|| Mutex::new(HashMap::new()));
+        let mut databases = databases.lock().expect("open database registry poisoned");
+        if let Some(open) = databases.get(&path) {
+            if let (Some(inner), Some(ownership)) =
+                (open.inner.upgrade(), open.ownership.upgrade())
+            {
+                return Ok(Self {
+                    inner,
+                    event_tx: open.event_tx.clone(),
+                    _ownership: ownership,
+                });
+            }
+        }
+        databases.remove(&path);
+
+        let mut ownership_path = path.as_os_str().to_os_string();
+        ownership_path.push(".lock");
+        let ownership = OpenOptions::new()
+            .create(true)
+            .read(true)
+            .write(true)
+            .open(PathBuf::from(ownership_path))?;
+        ownership.try_lock().map_err(|error| match error {
+            std::fs::TryLockError::WouldBlock => std::io::Error::new(
+                std::io::ErrorKind::WouldBlock,
+                format!(
+                    "FeltDB database {} is already owned by another process",
+                    path.display()
+                ),
+            ),
+            std::fs::TryLockError::Error(error) => error,
+        })?;
 
         // Fail closed. The format is decided before any record is interpreted
         // and before anything is written, so a database this build does not
@@ -1847,9 +2039,6 @@ impl FeltDb {
             FormatCompatibility::Compatible(format) => format,
         };
 
-        if let Some(parent) = path.parent() {
-            fs::create_dir_all(parent)?;
-        }
         if !path.exists() {
             let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
             // A new database states its format in its first record, so it never
@@ -1885,10 +2074,20 @@ impl FeltDb {
 
         let (event_tx, _) = broadcast::channel(1024);
 
-        Ok(Self {
+        let database = Self {
             inner: Arc::new(Mutex::new(inner)),
             event_tx,
-        })
+            _ownership: Arc::new(ownership),
+        };
+        databases.insert(
+            path,
+            OpenDatabase {
+                inner: Arc::downgrade(&database.inner),
+                event_tx: database.event_tx.clone(),
+                ownership: Arc::downgrade(&database._ownership),
+            },
+        );
+        Ok(database)
     }
 
     /// Write a self-contained durable backup artifact.
@@ -2130,10 +2329,21 @@ impl FeltDb {
             .map(|(cap, _)| cap)
             .unwrap_or("default")
             .to_string();
-        self.insert_internal(capability, key.to_string(), value)?;
+        self.insert_internal(capability, key.to_string(), value, false)?;
         Ok(())
     }
 
+    /// Insert only if the logical record is absent, deciding presence under the
+    /// same lock that appends the operation and mints its first revision.
+    pub fn insert_if_absent<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
+        let capability = key
+            .split_once(':')
+            .map(|(cap, _)| cap)
+            .unwrap_or("default")
+            .to_string();
+        self.insert_internal(capability, key.to_string(), value, true)
+    }
+
     /// Update an existing record with vector clock tracking
     pub fn update<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
         let capability = key
@@ -2346,7 +2556,7 @@ impl FeltDb {
         }
 
         // Authorized: apply mutation
-        self.insert_internal(capability, key.to_string(), value)?;
+        self.insert_internal(capability, key.to_string(), value, false)?;
         Ok(())
     }
 
@@ -2658,13 +2868,19 @@ impl FeltDb {
                     .get(transaction_id)
                     .copied()
                     .unwrap_or((inner.authority_revision, inner.authority_revision));
+                let (state_before, state_after) = inner
+                    .transaction_history
+                    .iter()
+                    .find(|attribution| attribution.transaction_id == transaction_id)
+                    .map(|attribution| (attribution.state_before, attribution.state_after))
+                    .unwrap_or((inner.sequence, inner.sequence));
                 return Ok(AtomicCommit {
                     transaction_id: transaction_id.into(),
                     base_revision,
                     commit_revision,
                     status: TransactionStatus::Committed,
-                    state_before: inner.sequence,
-                    state_after: inner.sequence,
+                    state_before,
+                    state_after,
                     rows: vec![],
                     duplicate: true,
                 });
@@ -2960,26 +3176,11 @@ impl FeltDb {
                 }
                 if row.deleted {
                     inner.remove_row(&row.capability, &row.key);
-                    // Decrement cardinality on delete
-                    let count = inner
-                        .collection_cardinality
-                        .entry(row.capability.clone())
-                        .or_default();
-                    *count = count.saturating_sub(1);
                 } else {
                     // Record and index change together, inside the commit that
                     // is already holding the state lock: a transaction that is
                     // refused leaves neither, and one that commits publishes both.
-                    let is_insert = inner.put_row(row.clone());
-
-                    // Increment cardinality only on insert, not update
-                    if is_insert {
-                        let count = inner
-                            .collection_cardinality
-                            .entry(row.capability.clone())
-                            .or_default();
-                        *count = count.saturating_add(1);
-                    }
+                    inner.put_row(row.clone());
                 }
             }
             let tail_began = workload_diagnostics::enabled().then(std::time::Instant::now);
@@ -3070,6 +3271,7 @@ impl FeltDb {
         capability: String,
         key: String,
         value: T,
+        require_absent: bool,
     ) -> Result<()> {
         let rust_type = type_name::<T>().to_string();
         let value_json = serde_json::to_value(value)?;
@@ -3091,6 +3293,21 @@ impl FeltDb {
         {
             let mut inner = self.state();
 
+            if require_absent
+                && inner
+                    .rows
+                    .get(&capability)
+                    .and_then(|bucket| bucket.get(&key))
+                    .is_some()
+            {
+                return Err(FlowError::PreconditionFailed(Box::new(
+                    PreconditionFailure::Present {
+                        collection: capability,
+                        key,
+                    },
+                )));
+            }
+
             // Increment sequence number
             inner.sequence += 1;
 
@@ -3123,7 +3340,14 @@ impl FeltDb {
             inner.change_log.add_operation(op.clone());
 
             append_event_locked(&mut inner, &row)?;
+            let base_revision = inner.authority_revision;
             inner.authority_revision += 1;
+            remember_operation_attribution(
+                &mut inner,
+                &row,
+                base_revision,
+                base_revision + 1,
+            );
             inner.put_row(row);
             if let Some(revision) = planned {
                 persist_revision_locked(&mut inner, revision)?;
@@ -3202,7 +3426,14 @@ impl FeltDb {
             inner.change_log.add_operation(op.clone());
 
             append_event_locked(&mut inner, &row)?;
+            let base_revision = inner.authority_revision;
             inner.authority_revision += 1;
+            remember_operation_attribution(
+                &mut inner,
+                &row,
+                base_revision,
+                base_revision + 1,
+            );
             inner.put_row(row);
             if let Some(revision) = planned {
                 persist_revision_locked(&mut inner, revision)?;
@@ -3270,7 +3501,14 @@ impl FeltDb {
                 operation: Some(op),
             };
             append_event(&inner.path, &tombstone)?;
+            let base_revision = inner.authority_revision;
             inner.authority_revision += 1;
+            remember_operation_attribution(
+                &mut inner,
+                &tombstone,
+                base_revision,
+                base_revision + 1,
+            );
 
             // Remove from in-memory store, index entries included.
             inner.remove_row(&capability, &key);
@@ -3879,6 +4117,8 @@ impl FeltDb {
                 format_version: DURABLE_FORMAT_VERSION,
                 local_sequence: inner.sequence,
                 observed_versions: snapshot.versions.clone(),
+                transaction_history: Vec::new(),
+                transaction_payload_hashes: HashMap::new(),
             },
         )?;
         for row in &snapshot.rows {
@@ -3951,25 +4191,43 @@ impl FeltDb {
             .collect())
     }
 
-    /// One transaction's attribution, if it is still inside the window.
+    /// One transaction's durable attribution, regardless of the operator
+    /// window. This lookup is canonical historical provenance.
     pub fn transaction_attribution(
         &self,
         transaction_id: &str,
     ) -> Result<Option<TransactionAttribution>> {
         let inner = self.state();
         Ok(inner
-            .transaction_attributions
+            .transaction_history
             .iter()
             .rev()
             .find(|attribution| attribution.transaction_id == transaction_id)
             .cloned())
     }
 
-    /// Recent commits that named this record, newest first.
+    /// Canonical commit history in authority order, suitable for resumable
+    /// event projection and historical provenance reconstruction.
+    pub fn committed_transactions_after(
+        &self,
+        commit_revision: u64,
+        limit: usize,
+    ) -> Result<Vec<TransactionAttribution>> {
+        let inner = self.state();
+        Ok(inner
+            .transaction_history
+            .iter()
+            .filter(|transaction| transaction.commit_revision > commit_revision)
+            .take(limit)
+            .cloned()
+            .collect())
+    }
+
+    /// Durable commits that named this record, newest first.
     ///
-    /// This is how "who last changed this record" is answered without scanning
-    /// the durable log: a transaction names the keys it mutated, so the join is
-    /// over data the commit already recorded.
+    /// This deliberately reads complete canonical history rather than the
+    /// bounded operator window. Historical provenance must not disappear when
+    /// a cache rolls over.
     pub fn transactions_touching(
         &self,
         capability: &str,
@@ -3978,7 +4236,7 @@ impl FeltDb {
     ) -> Result<Vec<TransactionAttribution>> {
         let inner = self.state();
         Ok(inner
-            .transaction_attributions
+            .transaction_history
             .iter()
             .rev()
             .filter(|attribution| attribution.touched(capability, key))
@@ -4076,6 +4334,8 @@ impl FeltDb {
                 format_version: DURABLE_FORMAT_VERSION,
                 local_sequence: inner.sequence,
                 observed_versions: inner.change_log.versions(),
+                transaction_history: inner.transaction_history.clone(),
+                transaction_payload_hashes: inner.transaction_payload_hashes.clone(),
             },
         )?;
         for operation in inner.change_log.pending_operations() {
@@ -4329,7 +4589,7 @@ impl Capability {
             key
         };
         self.db
-            .insert_internal(self.name.clone(), key.clone(), value)?;
+            .insert_internal(self.name.clone(), key.clone(), value, false)?;
         Ok(key)
     }
 
@@ -4339,7 +4599,8 @@ impl Capability {
         } else {
             format!("{}:{key}", self.name)
         };
-        self.db.insert_internal(self.name.clone(), full_key, value)
+        self.db
+            .insert_internal(self.name.clone(), full_key, value, false)
     }
 
     pub fn update<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
@@ -4846,6 +5107,25 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
                 .map_err(|error| corruption(line, &format!("malformed log header: {error}")))?;
             inner.sequence = inner.sequence.max(header.local_sequence);
             inner.change_log.observed_versions = header.observed_versions;
+            for attribution in header.transaction_history {
+                let attribution = normalize_transaction_attribution(attribution);
+                inner.authority_revision = inner
+                    .authority_revision
+                    .max(attribution.commit_revision);
+                inner
+                    .transaction_revisions
+                    .insert(
+                        attribution.transaction_id.clone(),
+                        (attribution.base_revision, attribution.commit_revision),
+                    );
+                inner
+                    .applied_transactions
+                    .insert(attribution.transaction_id.clone());
+                remember_attribution(inner, attribution);
+            }
+            inner
+                .transaction_payload_hashes
+                .extend(header.transaction_payload_hashes);
             inner.bootstrapped = true;
             snapshot_log = true;
             continue;
@@ -4925,6 +5205,7 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
         }
         let row: StoredRow = serde_json::from_value(value)
             .map_err(|_| corruption(line, "not a durable record this build understands"))?;
+        let derived_revision = row.capability == "state" && row.operation.is_none();
         if let Some(operation) = row.operation.clone() {
             // A revision is a deterministic function of the operation that
             // produced it, so it never has to be lost. If the crash landed
@@ -4942,12 +5223,23 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
                 inner.sync_state.merge_vector_clock(clock);
             }
             inner.change_log.add_operation(operation);
-        } else if !snapshot_log {
+        } else if !snapshot_log && !derived_revision {
             // Pre-operation-envelope logs were produced only by this local
             // store. Preserve a monotonic sequence when upgrading them.
             inner.sequence += 1;
         }
-        inner.authority_revision += 1;
+        if !derived_revision {
+            let base_revision = inner.authority_revision;
+            inner.authority_revision += 1;
+            if !snapshot_log {
+                remember_operation_attribution(
+                    inner,
+                    &row,
+                    base_revision,
+                    base_revision + 1,
+                );
+            }
+        }
         if let Some(id) = row
             .key
             .rsplit_once(':')
@@ -5292,13 +5584,232 @@ mod tests {
                 format!("tx_{}", commits - 3),
             ]
         );
-        // The oldest commits rolled out of the window rather than being kept
-        // forever; the durable log still holds them.
-        assert!(db.transaction_attribution("tx_0").expect("lookup").is_none());
+        // The oldest commit rolled out of the recent window but remains
+        // addressable through canonical history.
+        assert!(db
+            .transaction_attribution("tx_0")
+            .expect("lookup")
+            .is_some());
+        drop(db);
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn canonical_transaction_history_survives_window_restart_and_compaction() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let commits = TRANSACTION_ATTRIBUTION_WINDOW + 1;
+        for index in 0..commits {
+            db.apply_atomic_transaction(
+                &format!("history_tx_{index}"),
+                None,
+                &[],
+                &[AtomicMutation {
+                    capability: "history:Note".into(),
+                    key: format!("note_{index}"),
+                    value: Some(serde_json::json!({"index": index})),
+                }],
+                Some(serde_json::json!({"subject": "agent", "work_id": "work-1"})),
+            )
+            .expect("commit");
+        }
+        let complete = db.committed_transactions_after(0, usize::MAX).unwrap();
+        assert_eq!(complete.len(), commits);
+        assert_eq!(complete[0].transaction_id, "history_tx_0");
+        assert_eq!(complete[0].operation_ids.len(), 1);
+        assert_ne!(complete[0].operation_ids[0], complete[0].transaction_id);
+        assert_eq!(complete[0].work_id.as_deref(), Some("work-1"));
+        assert_eq!(
+            db.transactions_touching("history:Note", "note_0", 1)
+                .unwrap()[0]
+                .transaction_id,
+            "history_tx_0"
+        );
+        assert_eq!(
+            db.transaction_attribution("history_tx_0")
+                .unwrap()
+                .unwrap()
+                .audit
+                .unwrap()["work_id"],
+            "work-1"
+        );
+        let versions = db.operation_versions().unwrap();
+        db.acknowledge_peer_versions("history-peer".into(), versions)
+            .unwrap();
+        db.compact_operation_log(&["history-peer".into()]).unwrap();
+        drop(db);
+
+        let reopened = open(&path).expect("reopen");
+        assert_eq!(
+            reopened
+                .committed_transactions_after(0, usize::MAX)
+                .unwrap()
+                .len(),
+            commits
+        );
+        assert!(reopened
+            .transaction_attribution("history_tx_0")
+            .unwrap()
+            .is_some());
+        assert_eq!(
+            reopened
+                .transactions_touching("history:Note", "note_0", 1)
+                .unwrap()[0]
+                .transaction_id,
+            "history_tx_0"
+        );
+        assert_eq!(
+            reopened
+                .transaction_attribution("history_tx_0")
+                .unwrap()
+                .unwrap()
+                .operation_ids,
+            complete[0].operation_ids
+        );
+        let _ = fs::remove_file(sync_metadata_path(&path));
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn transaction_payload_binding_survives_restart_and_compaction() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let mutation = AtomicMutation {
+            capability: "managed:State".into(),
+            key: "record-1".into(),
+            value: Some(serde_json::json!({"value": 1})),
+        };
+        let first = db
+            .apply_atomic_transaction_content_addressed(
+                "managed-idempotency-1",
+                Some("sha256:request-a"),
+                None,
+                &[],
+                &[mutation.clone()],
+                None,
+            )
+            .expect("initial commit");
+        let duplicate = db
+            .apply_atomic_transaction_content_addressed(
+                "managed-idempotency-1",
+                Some("sha256:request-a"),
+                None,
+                &[],
+                &[mutation.clone()],
+                None,
+            )
+            .expect("same semantic request");
+        assert!(duplicate.duplicate);
+        assert_eq!(duplicate.base_revision, first.base_revision);
+        assert_eq!(duplicate.commit_revision, first.commit_revision);
+        assert_eq!(duplicate.state_before, first.state_before);
+        assert_eq!(duplicate.state_after, first.state_after);
+
+        let versions = db.operation_versions().unwrap();
+        db.acknowledge_peer_versions("managed-peer".into(), versions)
+            .unwrap();
+        db.compact_operation_log(&["managed-peer".into()]).unwrap();
         drop(db);
+
+        let reopened = open(&path).expect("restart");
+        let replay = reopened
+            .apply_atomic_transaction_content_addressed(
+                "managed-idempotency-1",
+                Some("sha256:request-a"),
+                None,
+                &[],
+                &[mutation.clone()],
+                None,
+            )
+            .expect("retry after restart");
+        assert!(replay.duplicate);
+        assert_eq!(replay.commit_revision, first.commit_revision);
+        let conflict = reopened
+            .apply_atomic_transaction_content_addressed(
+                "managed-idempotency-1",
+                Some("sha256:request-b"),
+                None,
+                &[],
+                &[mutation],
+                None,
+            )
+            .unwrap_err();
+        assert!(conflict
+            .to_string()
+            .contains("TRANSACTION_ID_PAYLOAD_MISMATCH:"));
+        let _ = fs::remove_file(sync_metadata_path(&path));
         let _ = fs::remove_file(path);
     }
 
+    #[test]
+    fn single_record_commits_are_canonical_history_positions() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        db.insert("orders:one", serde_json::json!({"status":"paid"}))
+            .unwrap();
+        let history = db.committed_transactions_after(0, 10).unwrap();
+        assert_eq!(history.len(), 1);
+        assert!(history[0].transaction_id.starts_with("transaction:"));
+        assert!(history[0].operation_ids[0].starts_with("operation:"));
+        assert_ne!(history[0].transaction_id, history[0].operation_ids[0]);
+        assert_eq!(history[0].keys, vec!["orders:orders:one"]);
+        drop(db);
+        let reopened = open(&path).unwrap();
+        assert_eq!(
+            reopened.committed_transactions_after(0, 10).unwrap()[0].transaction_id,
+            history[0].transaction_id
+        );
+        assert_eq!(
+            reopened.committed_transactions_after(0, 10).unwrap()[0].operation_ids,
+            history[0].operation_ids
+        );
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn compacted_legacy_attribution_gets_stable_distinct_operation_identity() {
+        let legacy = TransactionAttribution {
+            transaction_id: "legacy-transaction".into(),
+            operation_ids: Vec::new(),
+            subject: Some("agent-1".into()),
+            tenant_id: Some("tenant-1".into()),
+            application_id: Some("app-1".into()),
+            application_revision: None,
+            base_revision: 4,
+            commit_revision: 5,
+            state_before: 4,
+            state_after: 5,
+            keys: vec!["orders:one".into()],
+            operations: 2,
+            principal_id: None,
+            agent_id: Some("agent-1".into()),
+            session_id: None,
+            delegator_id: None,
+            work_id: None,
+            unix_ms: 1,
+            audit: None,
+        };
+        let first = normalize_transaction_attribution(legacy.clone());
+        let second = normalize_transaction_attribution(legacy);
+        assert_eq!(first, second);
+        assert_eq!(first.transaction_id, "legacy-transaction");
+        assert_eq!(first.operation_ids.len(), 2);
+        assert!(first
+            .operation_ids
+            .iter()
+            .all(|operation| operation.starts_with("operation:legacy-transaction:")));
+
+        let single = TransactionAttribution {
+            transaction_id: "operation:authority:9".into(),
+            operation_ids: Vec::new(),
+            operations: 1,
+            ..first
+        };
+        let upgraded = normalize_transaction_attribution(single);
+        assert_eq!(upgraded.transaction_id, "transaction:authority:9");
+        assert_eq!(upgraded.operation_ids, vec!["operation:authority:9"]);
+    }
+
     /// A bulk transaction names a bounded sample of keys and an exact count.
     #[test]
     fn a_bulk_transaction_truncates_its_key_list_and_keeps_the_count() {