create-feltdb 0.8.8 → 0.9.0

package/dist/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.8.8';
+export const FELTDB_PACKAGE_VERSION = '0.9.0';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

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

@@ -278,7 +278,7 @@ use serde_json::Value;
 use sha2::{Digest, Sha256};
 use std::any::type_name;
 use std::collections::hash_map::DefaultHasher;
-use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
+use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque};
 use std::fmt::{Display, Formatter};
 use std::fs::{self, OpenOptions};
 use std::hash::{Hash, Hasher};
@@ -390,6 +390,19 @@ struct Inner {
     applied_transactions: HashSet<String>,
     transaction_payload_hashes: HashMap<String, String>,
     transaction_revisions: HashMap<String, (u64, u64)>,
+    /// Recent commits, and who asked for them.
+    ///
+    /// Every transaction already records its actor: the audit document written
+    /// into the durable log carries `subject`, tenant, application and
+    /// revision. Until this existed that document was written and never read
+    /// back — replay parsed the record and discarded the audit — so the
+    /// database could say *what* changed and never *who changed it*.
+    ///
+    /// Bounded on purpose. This answers "who did this, recently", which is the
+    /// question a human asks while operating a running system; it is not an
+    /// 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>,
     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
@@ -737,6 +750,102 @@ pub enum JsonCasResult {
     },
     NotFound,
 }
+/// How many recent commits keep their attribution in memory.
+///
+/// Sized to cover what an operator reads in one sitting rather than to be a
+/// log. A larger window costs memory on every instance to answer a question the
+/// durable log already answers more completely.
+const TRANSACTION_ATTRIBUTION_WINDOW: usize = 512;
+
+/// How many mutated keys one attribution names before it stops listing them.
+///
+/// A bulk transaction can touch thousands of records; naming them all would
+/// make one commit's attribution larger than the rest of the window. The count
+/// is always exact, so a truncated list is visible as a truncated list.
+const TRANSACTION_ATTRIBUTION_KEYS: usize = 32;
+
+/// Who committed a transaction, and what it touched.
+///
+/// Projected from the audit document the transaction already writes. It carries
+/// no record values: attribution answers *who, when, and to what*, and the
+/// values are reachable through the record and revision APIs that authorize
+/// each read.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct TransactionAttribution {
+    pub transaction_id: String,
+    /// The actor the caller authenticated as, when the transaction named one.
+    pub subject: Option<String>,
+    pub tenant_id: Option<String>,
+    pub application_id: Option<String>,
+    /// The application contract revision the transaction was executed against.
+    pub application_revision: Option<String>,
+    pub base_revision: u64,
+    pub commit_revision: u64,
+    pub state_before: u64,
+    pub state_after: u64,
+    /// `capability:key` for each mutation, truncated at
+    /// [`TRANSACTION_ATTRIBUTION_KEYS`].
+    pub keys: Vec<String>,
+    /// How many mutations the transaction made, whether or not `keys` lists
+    /// them all.
+    pub operations: usize,
+    /// Milliseconds since the epoch, matching `StoredRow::unix_ms`.
+    pub unix_ms: u128,
+}
+
+impl TransactionAttribution {
+    /// Builds an attribution from a transaction record's own audit document.
+    fn from_record(
+        transaction_id: &str,
+        audit: Option<&Value>,
+        base_revision: u64,
+        commit_revision: u64,
+        state_before: u64,
+        state_after: u64,
+        rows: &[StoredRow],
+        unix_ms: u128,
+    ) -> Self {
+        let text = |field: &str| {
+            audit
+                .and_then(|value| value.get(field))
+                .and_then(Value::as_str)
+                .map(str::to_string)
+        };
+        TransactionAttribution {
+            transaction_id: transaction_id.to_string(),
+            subject: text("subject"),
+            tenant_id: text("tenant"),
+            application_id: text("application"),
+            application_revision: text("revision"),
+            base_revision,
+            commit_revision,
+            state_before,
+            state_after,
+            keys: rows
+                .iter()
+                .take(TRANSACTION_ATTRIBUTION_KEYS)
+                .map(|row| format!("{}:{}", row.capability, row.key))
+                .collect(),
+            operations: rows.len(),
+            unix_ms,
+        }
+    }
+
+    /// Whether this transaction touched a record, as far as `keys` records it.
+    pub fn touched(&self, capability: &str, key: &str) -> bool {
+        let target = format!("{capability}:{key}");
+        self.keys.iter().any(|held| *held == target)
+    }
+}
+
+/// Records an attribution, discarding the oldest once the window is full.
+fn remember_attribution(inner: &mut Inner, attribution: TransactionAttribution) {
+    if inner.transaction_attributions.len() >= TRANSACTION_ATTRIBUTION_WINDOW {
+        inner.transaction_attributions.pop_front();
+    }
+    inner.transaction_attributions.push_back(attribution);
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct TransactionLogRecord {
     record_type: String,
@@ -2827,6 +2936,22 @@ impl FeltDb {
                 bookkeeping_nanos += began.elapsed().as_nanos().min(u64::MAX as u128) as u64;
             }
             append_transaction(&inner.path, &record)?;
+            // Retained from the record that was just made durable, so the
+            // in-memory answer to "who committed this" cannot describe a
+            // transaction the log does not hold.
+            remember_attribution(
+                &mut inner,
+                TransactionAttribution::from_record(
+                    transaction_id,
+                    record.audit.as_ref(),
+                    base_revision,
+                    base_revision + 1,
+                    state_before,
+                    next_sequence,
+                    &record.rows,
+                    now_ms(),
+                ),
+            );
             inner.authority_revision = base_revision + 1;
             inner.sequence = next_sequence;
             for row in &rows {
@@ -3809,6 +3934,71 @@ impl FeltDb {
     }
 
     /// Earliest operation still available for incremental replay, by origin.
+    /// Recent commits and who made them, newest first.
+    ///
+    /// Bounded by [`TRANSACTION_ATTRIBUTION_WINDOW`]. A transaction older than
+    /// the window is not absent from history — it is in the durable log — it is
+    /// simply no longer answerable from memory, and callers that present this
+    /// to a human must say which of the two they are showing.
+    pub fn recent_transactions(&self, limit: usize) -> Result<Vec<TransactionAttribution>> {
+        let inner = self.state();
+        Ok(inner
+            .transaction_attributions
+            .iter()
+            .rev()
+            .take(limit)
+            .cloned()
+            .collect())
+    }
+
+    /// One transaction's attribution, if it is still inside the window.
+    pub fn transaction_attribution(
+        &self,
+        transaction_id: &str,
+    ) -> Result<Option<TransactionAttribution>> {
+        let inner = self.state();
+        Ok(inner
+            .transaction_attributions
+            .iter()
+            .rev()
+            .find(|attribution| attribution.transaction_id == transaction_id)
+            .cloned())
+    }
+
+    /// Recent 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.
+    pub fn transactions_touching(
+        &self,
+        capability: &str,
+        key: &str,
+        limit: usize,
+    ) -> Result<Vec<TransactionAttribution>> {
+        let inner = self.state();
+        Ok(inner
+            .transaction_attributions
+            .iter()
+            .rev()
+            .filter(|attribution| attribution.touched(capability, key))
+            .take(limit)
+            .cloned()
+            .collect())
+    }
+
+    /// How much of the attribution window is in use, and what it can hold.
+    ///
+    /// Reported so a reader can tell an idle system from a window that has
+    /// already rolled over.
+    pub fn transaction_attribution_window(&self) -> Result<(usize, usize)> {
+        let inner = self.state();
+        Ok((
+            inner.transaction_attributions.len(),
+            TRANSACTION_ATTRIBUTION_WINDOW,
+        ))
+    }
+
     pub fn retained_operation_floors(&self) -> Result<HashMap<String, u64>> {
         let inner = self.state();
         Ok(inner.change_log.retained_from())
@@ -4693,6 +4883,24 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
                     .transaction_payload_hashes
                     .insert(transaction.transaction_id.clone(), hash);
             }
+            // Attribution is restored on replay for the same reason it is kept
+            // on commit: an operator who restarts a server must not lose the
+            // answer to "who did this" for work the server already holds.
+            let attribution = TransactionAttribution::from_record(
+                &transaction.transaction_id,
+                transaction.audit.as_ref(),
+                base_revision,
+                inner.authority_revision,
+                transaction.state_before,
+                transaction.state_after,
+                &transaction.rows,
+                transaction
+                    .rows
+                    .first()
+                    .map(|row| row.unix_ms)
+                    .unwrap_or_default(),
+            );
+            remember_attribution(inner, attribution);
             if inner
                 .applied_transactions
                 .insert(transaction.transaction_id)
@@ -4987,6 +5195,140 @@ mod tests {
         ))
     }
 
+    /// A commit is attributable: the audit document a transaction already
+    /// writes is retained, so a human can ask who made a change.
+    #[test]
+    fn a_committed_transaction_records_who_committed_it() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        db.apply_atomic_transaction(
+            "tx_agent_1",
+            None,
+            &[],
+            &[AtomicMutation {
+                capability: "billing:Customer".into(),
+                key: "cus_1".into(),
+                value: Some(serde_json::json!({"name": "Ada", "status": "active"})),
+            }],
+            Some(serde_json::json!({
+                "subject": "agent_data_cleanup",
+                "tenant": "acme",
+                "application": "app_billing",
+                "revision": "rev_7",
+            })),
+        )
+        .expect("commit");
+
+        let recent = db.recent_transactions(10).expect("attributions");
+        assert_eq!(recent.len(), 1);
+        assert_eq!(recent[0].transaction_id, "tx_agent_1");
+        assert_eq!(recent[0].subject.as_deref(), Some("agent_data_cleanup"));
+        assert_eq!(recent[0].application_id.as_deref(), Some("app_billing"));
+        assert_eq!(recent[0].operations, 1);
+        assert_eq!(recent[0].keys, vec!["billing:Customer:cus_1".to_string()]);
+        // Attribution says who and what, never what was written.
+        assert!(!serde_json::to_string(&recent[0]).unwrap().contains("Ada"));
+
+        let touching = db
+            .transactions_touching("billing:Customer", "cus_1", 10)
+            .expect("touching");
+        assert_eq!(touching.len(), 1);
+        assert_eq!(touching[0].transaction_id, "tx_agent_1");
+        assert!(db
+            .transactions_touching("billing:Customer", "cus_2", 10)
+            .expect("touching")
+            .is_empty());
+
+        assert_eq!(
+            db.transaction_attribution("tx_agent_1")
+                .expect("lookup")
+                .map(|value| value.subject)
+                .flatten()
+                .as_deref(),
+            Some("agent_data_cleanup")
+        );
+
+        // Attribution survives a restart, because it is rebuilt from the same
+        // durable records the rest of recovery replays.
+        drop(db);
+        let reopened = open(&path).expect("reopen");
+        let after = reopened.recent_transactions(10).expect("attributions");
+        assert_eq!(after.len(), 1);
+        assert_eq!(after[0].subject.as_deref(), Some("agent_data_cleanup"));
+        assert_eq!(after[0].keys, vec!["billing:Customer:cus_1".to_string()]);
+        drop(reopened);
+        let _ = fs::remove_file(path);
+    }
+
+    /// The window is bounded, and reports that it is.
+    #[test]
+    fn transaction_attribution_is_bounded_and_newest_first() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let commits = TRANSACTION_ATTRIBUTION_WINDOW + 5;
+        for index in 0..commits {
+            db.apply_atomic_transaction(
+                &format!("tx_{index}"),
+                None,
+                &[],
+                &[AtomicMutation {
+                    capability: "app:Note".into(),
+                    key: format!("note_{index}"),
+                    value: Some(serde_json::json!({"index": index})),
+                }],
+                Some(serde_json::json!({"subject": format!("actor_{index}")})),
+            )
+            .expect("commit");
+        }
+        let (held, capacity) = db.transaction_attribution_window().expect("window");
+        assert_eq!(capacity, TRANSACTION_ATTRIBUTION_WINDOW);
+        assert_eq!(held, TRANSACTION_ATTRIBUTION_WINDOW);
+        let recent = db.recent_transactions(3).expect("attributions");
+        assert_eq!(
+            recent.iter().map(|value| value.transaction_id.clone()).collect::<Vec<_>>(),
+            vec![
+                format!("tx_{}", commits - 1),
+                format!("tx_{}", commits - 2),
+                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());
+        drop(db);
+        let _ = fs::remove_file(path);
+    }
+
+    /// 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() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let mutations = (0..TRANSACTION_ATTRIBUTION_KEYS + 20)
+            .map(|index| AtomicMutation {
+                capability: "app:Customer".into(),
+                key: format!("cus_{index}"),
+                value: Some(serde_json::json!({"index": index})),
+            })
+            .collect::<Vec<_>>();
+        db.apply_atomic_transaction(
+            "tx_bulk",
+            None,
+            &[],
+            &mutations,
+            Some(serde_json::json!({"subject": "migration_agent"})),
+        )
+        .expect("commit");
+        let attribution = db
+            .transaction_attribution("tx_bulk")
+            .expect("lookup")
+            .expect("held");
+        assert_eq!(attribution.operations, mutations.len());
+        assert_eq!(attribution.keys.len(), TRANSACTION_ATTRIBUTION_KEYS);
+        drop(db);
+        let _ = fs::remove_file(path);
+    }
+
     #[test]
     fn open_is_zero_init_and_creates_store() {
         let path = temp_file();

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

@@ -1089,9 +1089,22 @@ pub fn reconcile(
 /// Proven for this type: durable single-writer append, retrieval by identity
 /// across restart, ancestry by parent traversal, and independence between
 /// records. **Not** proven and not claimed: multi-writer persistence semantics,
-/// concurrent revision creation, authorization, resource isolation, garbage
-/// collection, server lifecycle integration, current/head semantics, and
+/// concurrent revision creation, resource isolation, garbage collection, and
 /// distributed replication of revision history.
+///
+/// Two entries left that list when `/v1/state/*` began serving this type.
+/// *Server lifecycle integration*: `feltdb-server` opens a store over its own
+/// `FeltDb` through [`crate::FeltDBStateSystem`] and serves history, diff,
+/// classification and reconciliation from it. *Authorization*: those routes are
+/// authorized like every other route — `state:read` to read, `state:write` to
+/// commit — which is authorization **at the route**, not in this type. This
+/// type still has none of its own, and a caller holding a `StateStore` still
+/// reaches every resource in it.
+///
+/// *Current/head semantics* also left, but only partly, and the distinction
+/// matters: [`head_of`](Self::head_of) answers "the newest retained revision of
+/// this resource, by sequence". That is not a branch head and there is still no
+/// ref anything can move.
 pub struct StateStore {
     backing: Backing,
 }