@feltdb/core 0.9.1 → 0.10.0

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

@@ -1,14 +1,17 @@
+use feltdb::{
+    workload::DURABLE_WORK_COLLECTION, AtomicMutation, AtomicPrecondition, FeltDb,
+    TransactionAttribution,
+};
 use rand::{distributions::Alphanumeric, Rng};
 use serde::{Deserialize, Serialize};
-use serde_json::Value;
-use std::{
-    collections::BTreeMap,
-    fs,
-    path::PathBuf,
-    sync::{Arc, RwLock},
-    time::{SystemTime, UNIX_EPOCH},
-};
-#[derive(Debug, Clone, Serialize, Deserialize)]
+use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
+use std::{collections::BTreeMap, fs, path::Path};
+
+const CAUSAL_METADATA_COLLECTION: &str = "system_causal_metadata";
+const MIGRATION_EVIDENCE_COLLECTION: &str = "system_migration_evidence";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct CausalEvent {
     pub event_id: String,
     pub causal_id: String,
@@ -37,182 +40,940 @@ pub struct CausalEvent {
     pub metadata: BTreeMap<String, Value>,
     pub schema_version: u32,
 }
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CausalContext {
     pub causal_id: String,
     pub parent_event_id: Option<String>,
 }
-#[derive(Debug, Default, Serialize, Deserialize)]
-struct Records {
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum CausalClassification {
+    Authoritative,
+    CausalMetadata,
+    ExecutionFact,
+    Telemetry,
+    NotNeeded,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct LegacyRecords {
     events: Vec<CausalEvent>,
 }
+
+/// Adapter over canonical FeltDB commits. It has no independent event
+/// sequence or persistence: ordering, replay, and provenance come from the
+/// canonical transaction log.
 #[derive(Clone)]
-pub struct CausalStore {
-    path: PathBuf,
-    records: Arc<RwLock<Records>>,
-}
-fn now() -> u64 {
-    SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .unwrap_or_default()
-        .as_secs()
-}
-fn id(prefix: &str) -> String {
-    format!(
-        "{prefix}_{}",
-        rand::thread_rng()
-            .sample_iter(&Alphanumeric)
-            .take(18)
-            .map(char::from)
-            .collect::<String>()
-    )
+pub struct CanonicalEventAuthority {
+    db: FeltDb,
 }
-impl CausalStore {
-    pub fn load(path: impl Into<PathBuf>) -> Result<Self, String> {
-        let path = path.into();
-        let records = if path.exists() {
-            serde_json::from_slice(&fs::read(&path).map_err(|e| e.to_string())?)
-                .map_err(|e| e.to_string())?
-        } else {
-            Records::default()
-        };
-        Ok(Self {
-            path,
-            records: Arc::new(RwLock::new(records)),
-        })
+
+impl CanonicalEventAuthority {
+    pub fn new(db: FeltDb) -> Self {
+        Self { db }
     }
-    fn persist(&self, r: &Records) -> Result<(), String> {
-        if let Some(p) = self.path.parent() {
-            fs::create_dir_all(p).map_err(|e| e.to_string())?
-        }
-        let tmp = self.path.with_extension("tmp");
-        fs::write(
-            &tmp,
-            serde_json::to_vec_pretty(r).map_err(|e| e.to_string())?,
+
+    pub fn migrate_legacy_file(&self, path: &Path) -> Result<(), String> {
+        let legacy: LegacyRecords = serde_json::from_slice(
+            &fs::read(path).map_err(|error| error.to_string())?,
         )
-        .map_err(|e| e.to_string())?;
-        fs::rename(tmp, &self.path).map_err(|e| e.to_string())
+        .map_err(|error| error.to_string())?;
+        for event in legacy.events {
+            validate_scope(&event)?;
+            if event.event_id.is_empty() {
+                return Err("legacy causal record has no stable event identity".into());
+            }
+            let classification = self.classify(&event);
+            self.record_classification(&event, classification)?;
+            match classification {
+                CausalClassification::CausalMetadata => {
+                    self.commit_metadata(event, classification, "causal_event_migration")?;
+                }
+                CausalClassification::Authoritative
+                | CausalClassification::ExecutionFact
+                | CausalClassification::Telemetry
+                | CausalClassification::NotNeeded => {}
+            }
+        }
+        Ok(())
     }
+
     pub fn append(&self, mut event: CausalEvent) -> Result<CausalEvent, String> {
+        validate_scope(&event)?;
+        let classification = self.classify(&event);
+        if matches!(classification, CausalClassification::Authoritative) {
+            return Err("authoritative events are projections of their existing canonical commit".into());
+        }
+        if matches!(classification, CausalClassification::ExecutionFact) {
+            return Err("execution facts must commit through canonical Durable Work".into());
+        }
+        if matches!(classification, CausalClassification::Telemetry | CausalClassification::NotNeeded) {
+            return Err("telemetry and non-semantic events are not durable application authority".into());
+        }
+        if event.event_id.is_empty() {
+            event.event_id = random_id("event");
+        }
         if event.causal_id.is_empty() {
-            event.causal_id = id("causal")
+            event.causal_id = random_id("causal");
         }
-        event.event_id = if event.event_id.is_empty() {
-            id("event")
-        } else {
-            event.event_id
-        };
-        event.timestamp = if event.timestamp == 0 {
-            now()
-        } else {
-            event.timestamp
-        };
         event.schema_version = 1;
-        let mut r = self
-            .records
-            .write()
-            .map_err(|_| "causal store lock poisoned")?;
-        if r.events.iter().any(|e| e.event_id == event.event_id) {
-            return Ok(event);
-        }
-        r.events.push(event.clone());
-        self.persist(&r)?;
+        self.commit_metadata(event.clone(), classification, "causal_metadata_recorded")?;
         Ok(event)
     }
-    pub fn list(&self, causal_id: &str) -> Vec<CausalEvent> {
-        self.records
-            .read()
-            .map(|r| {
-                r.events
-                    .iter()
-                    .filter(|e| e.causal_id == causal_id)
-                    .cloned()
-                    .collect()
-            })
-            .unwrap_or_default()
-    }
-    pub fn workload(&self, id: &str) -> Vec<CausalEvent> {
-        self.records
-            .read()
-            .map(|r| {
-                r.events
-                    .iter()
-                    .filter(|e| e.workload_id.as_deref() == Some(id))
-                    .cloned()
-                    .collect()
+
+    pub fn all(&self) -> Result<Vec<CausalEvent>, String> {
+        Ok(self
+            .db
+            .committed_transactions_after(0, usize::MAX)
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .map(project_transaction)
+            .collect())
+    }
+
+    pub fn after(&self, revision: u64, limit: usize) -> Result<Vec<CausalEvent>, String> {
+        Ok(self
+            .db
+            .committed_transactions_after(revision, limit)
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .map(project_transaction)
+            .collect())
+    }
+
+    pub fn list(&self, causal_id: &str) -> Result<Vec<CausalEvent>, String> {
+        Ok(self
+            .all()?
+            .into_iter()
+            .filter(|event| event.causal_id == causal_id)
+            .collect())
+    }
+
+    pub fn workload(&self, id: &str) -> Result<Vec<CausalEvent>, String> {
+        Ok(self
+            .all()?
+            .into_iter()
+            .filter(|event| event.workload_id.as_deref() == Some(id))
+            .collect())
+    }
+
+    pub fn execution(&self, id: &str) -> Result<Vec<CausalEvent>, String> {
+        Ok(self
+            .all()?
+            .into_iter()
+            .filter(|event| event.execution_id.as_deref() == Some(id))
+            .collect())
+    }
+
+    pub fn revision(&self, id: &str) -> Result<Vec<CausalEvent>, String> {
+        Ok(self
+            .all()?
+            .into_iter()
+            .filter(|event| event.revision_id.as_deref() == Some(id))
+            .collect())
+    }
+
+    fn classify(&self, event: &CausalEvent) -> CausalClassification {
+        if event.revision_id.is_some()
+            || event.state_version.is_some()
+            || !event.operation_ids.is_empty()
+        {
+            CausalClassification::Authoritative
+        } else if event.workload_id.is_some()
+            || event.attempt_id.is_some()
+            || event.result_id.is_some()
+        {
+            CausalClassification::ExecutionFact
+        } else if event.worker_id.is_some()
+            || event.connection_id.is_some()
+            || event.execution_id.is_some()
+        {
+            CausalClassification::Telemetry
+        } else if event.parent_event_id.is_some() || !event.causal_id.is_empty() {
+            CausalClassification::CausalMetadata
+        } else {
+            CausalClassification::NotNeeded
+        }
+    }
+
+    fn commit_metadata(
+        &self,
+        event: CausalEvent,
+        classification: CausalClassification,
+        kind: &str,
+    ) -> Result<(), String> {
+        let key = format!(
+            "{}/{}/{}",
+            event.tenant_id, event.application_id, event.event_id
+        );
+        let source_digest = format!(
+            "sha256:{:x}",
+            Sha256::digest(
+                serde_json::to_vec(&event).map_err(|error| error.to_string())?
+            )
+        );
+        if let Some(existing) = self
+            .db
+            .list_collection(CAUSAL_METADATA_COLLECTION)
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .find(|row| row.key == key)
+        {
+            if existing.value.get("event")
+                == Some(&serde_json::to_value(&event).map_err(|error| error.to_string())?)
+                && existing.value.get("source_digest") == Some(&Value::String(source_digest.clone()))
+            {
+                return Ok(());
+            }
+            return Err(format!(
+                "causal metadata identity conflict: {}",
+                event.event_id
+            ));
+        }
+        self.db
+            .apply_atomic_transaction(
+                &format!("causal:{}", event.event_id),
+                None,
+                &[AtomicPrecondition {
+                    capability: CAUSAL_METADATA_COLLECTION.into(),
+                    key: key.clone(),
+                    expected_version: None,
+                }],
+                &[AtomicMutation {
+                    capability: CAUSAL_METADATA_COLLECTION.into(),
+                    key,
+                    value: Some(json!({
+                        "classification": classification,
+                        "event": event,
+                        "source_digest": source_digest,
+                    })),
+                }],
+                Some(json!({
+                    "kind": kind,
+                    "subject": event.subject_id,
+                    "tenant": event.tenant_id,
+                    "application": event.application_id,
+                    "legacy_event": event,
+                    "classification": classification,
+                    "source_kind": "CausalStore",
+                    "source_identity": event.event_id,
+                    "source_digest": source_digest,
+                    "migration_outcome": (kind == "causal_event_migration").then_some("imported"),
+                })),
+            )
+            .map_err(|error| error.to_string())?;
+        Ok(())
+    }
+
+    fn record_classification(
+        &self,
+        event: &CausalEvent,
+        classification: CausalClassification,
+    ) -> Result<(), String> {
+        validate_scope(event)?;
+        let mut resolved = match classification {
+            CausalClassification::Authoritative => self.resolve_authoritative(event)?,
+            CausalClassification::ExecutionFact => vec![self.resolve_execution_fact(event)?],
+            _ => Vec::new(),
+        };
+        if let Some(decision_id) = event.authorization_decision_id.as_deref() {
+            let transaction = self.resolve_audit_reference(
+                event,
+                "authorization_decision_id",
+                decision_id,
+            )?;
+            if !resolved.contains(&transaction) {
+                resolved.push(transaction);
+            }
+        }
+        let source_digest = format!(
+            "sha256:{:x}",
+            Sha256::digest(serde_json::to_vec(event).map_err(|error| error.to_string())?)
+        );
+        let key = format!("CausalStore/{}", event.event_id);
+        let evidence = json!({
+            "source_kind": "CausalStore",
+            "source_identity": event.event_id,
+            "tenant_id": event.tenant_id,
+            "application_id": event.application_id,
+            "source_digest": source_digest,
+            "classification": classification,
+            "canonical_transaction_ids": resolved,
+            "outcome": if matches!(classification, CausalClassification::Telemetry | CausalClassification::NotNeeded) { "classified_not_migrated" } else { "verified_or_imported" },
+        });
+        if let Some(existing) = self
+            .db
+            .list_collection(MIGRATION_EVIDENCE_COLLECTION)
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .find(|row| row.key == key)
+        {
+            let mut held = existing.value;
+            if let Some(object) = held.as_object_mut() {
+                object.remove("__version");
+            }
+            if held == evidence {
+                return Ok(());
+            }
+            return Err(format!("causal classification conflict: {}", event.event_id));
+        }
+        self.db
+            .apply_atomic_transaction(
+                &format!("causal_classification:{}", event.event_id),
+                None,
+                &[AtomicPrecondition {
+                    capability: MIGRATION_EVIDENCE_COLLECTION.into(),
+                    key: key.clone(),
+                    expected_version: None,
+                }],
+                &[AtomicMutation {
+                    capability: MIGRATION_EVIDENCE_COLLECTION.into(),
+                    key,
+                    value: Some(evidence),
+                }],
+                Some(json!({
+                    "kind": "causal_classification",
+                    "subject": event.subject_id,
+                    "tenant": event.tenant_id,
+                    "application": event.application_id,
+                    "source_identity": event.event_id,
+                    "source_digest": source_digest,
+                    "classification": classification,
+                })),
+            )
+            .map_err(|error| error.to_string())?;
+        Ok(())
+    }
+
+    fn resolve_authoritative(&self, event: &CausalEvent) -> Result<Vec<String>, String> {
+        let mut references = event.operation_ids.clone();
+        references.extend(event.revision_id.clone());
+        references.extend(event.state_version.clone());
+        let history = self
+            .db
+            .committed_transactions_after(0, usize::MAX)
+            .map_err(|error| error.to_string())?;
+        let mut resolved = Vec::new();
+        for reference in references {
+            let transaction = history.iter().find(|transaction| {
+                transaction_scope_matches(transaction, event)
+                    && (transaction.transaction_id == reference
+                        || transaction.operation_ids.iter().any(|id| id == &reference)
+                        || parse_revision_reference(&reference)
+                            .is_some_and(|revision| transaction.commit_revision == revision))
+            });
+            let Some(transaction) = transaction else {
+                return Err(format!(
+                    "authoritative causal reference is unresolved: {reference}"
+                ));
+            };
+            if !resolved.contains(&transaction.transaction_id) {
+                resolved.push(transaction.transaction_id.clone());
+            }
+        }
+        if resolved.is_empty() {
+            return Err("authoritative causal record has no canonical reference".into());
+        }
+        Ok(resolved)
+    }
+
+    fn resolve_execution_fact(&self, event: &CausalEvent) -> Result<String, String> {
+        let workload_id = event
+            .workload_id
+            .as_deref()
+            .ok_or("execution fact has no workload identity")?;
+        let workload = self
+            .db
+            .list_collection(DURABLE_WORK_COLLECTION)
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .find(|row| {
+                row.value.get("workload_id").and_then(Value::as_str) == Some(workload_id)
+                    && row.value.get("tenant_id").and_then(Value::as_str)
+                        == Some(event.tenant_id.as_str())
+                    && row.value.get("application_id").and_then(Value::as_str)
+                        == Some(event.application_id.as_str())
             })
-            .unwrap_or_default()
-    }
-    pub fn execution(&self, id: &str) -> Vec<CausalEvent> {
-        self.records
-            .read()
-            .map(|r| {
-                r.events
-                    .iter()
-                    .filter(|e| e.execution_id.as_deref() == Some(id))
-                    .cloned()
-                    .collect()
+            .ok_or_else(|| format!("execution fact workload is unresolved: {workload_id}"))?;
+        if let Some(attempt_id) = event.attempt_id.as_deref() {
+            let found = workload
+                .value
+                .get("attempts")
+                .and_then(Value::as_array)
+                .is_some_and(|attempts| {
+                    attempts.iter().any(|attempt| {
+                        attempt.get("attempt_id").and_then(Value::as_str) == Some(attempt_id)
+                    })
+                });
+            if !found {
+                return Err(format!("execution fact attempt is unresolved: {attempt_id}"));
+            }
+        }
+        if let Some(result_id) = event.result_id.as_deref() {
+            if workload.value.pointer("/result/result_id").and_then(Value::as_str)
+                != Some(result_id)
+            {
+                return Err(format!("execution fact result is unresolved: {result_id}"));
+            }
+        }
+        self.db
+            .committed_transactions_after(0, usize::MAX)
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .rev()
+            .find(|transaction| {
+                transaction.work_id.as_deref() == Some(workload_id)
+                    && transaction_scope_matches(transaction, event)
             })
-            .unwrap_or_default()
-    }
-    pub fn revision(&self, id: &str) -> Vec<CausalEvent> {
-        self.records
-            .read()
-            .map(|r| {
-                r.events
-                    .iter()
-                    .filter(|e| e.revision_id.as_deref() == Some(id))
-                    .cloned()
-                    .collect()
+            .map(|transaction| transaction.transaction_id)
+            .ok_or_else(|| format!("execution fact has no canonical transaction: {workload_id}"))
+    }
+
+    fn resolve_audit_reference(
+        &self,
+        event: &CausalEvent,
+        field: &str,
+        reference: &str,
+    ) -> Result<String, String> {
+        self.db
+            .committed_transactions_after(0, usize::MAX)
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .find(|transaction| {
+                transaction_scope_matches(transaction, event)
+                    && transaction
+                        .audit
+                        .as_ref()
+                        .and_then(|audit| audit.get(field))
+                        .and_then(Value::as_str)
+                        == Some(reference)
             })
-            .unwrap_or_default()
+            .map(|transaction| transaction.transaction_id)
+            .ok_or_else(|| format!("causal {field} reference is unresolved: {reference}"))
     }
-    pub fn all(&self) -> Vec<CausalEvent> {
-        self.records
-            .read()
-            .map(|r| r.events.clone())
-            .unwrap_or_default()
+}
+
+fn validate_scope(event: &CausalEvent) -> Result<(), String> {
+    if event.tenant_id.trim().is_empty() || event.application_id.trim().is_empty() {
+        return Err("causal record requires tenant and application scope".into());
     }
+    Ok(())
+}
+
+fn transaction_scope_matches(
+    transaction: &TransactionAttribution,
+    event: &CausalEvent,
+) -> bool {
+    transaction.tenant_id.as_deref() == Some(event.tenant_id.as_str())
+        && transaction.application_id.as_deref() == Some(event.application_id.as_str())
+}
+
+pub fn encode_cursor(revision: u64) -> String {
+    format!("fh1-{revision:016x}")
 }
+
+pub fn decode_cursor(cursor: &str) -> Result<u64, String> {
+    let value = cursor
+        .strip_prefix("fh1-")
+        .ok_or("invalid event cursor")?;
+    u64::from_str_radix(value, 16).map_err(|_| "invalid event cursor".into())
+}
+
+/// Public cursor bound to one durable authority and application scope.
+/// Consumers treat the complete value as opaque.
+pub fn encode_scoped_cursor(scope: &str, revision: u64) -> String {
+    let digest = format!("{:x}", Sha256::digest(scope.as_bytes()));
+    format!("fh1-{}-{revision:016x}", &digest[..16])
+}
+
+pub fn decode_scoped_cursor(scope: &str, cursor: &str) -> Result<u64, String> {
+    let expected_prefix = encode_scoped_cursor(scope, 0)
+        .rsplit_once('-')
+        .map(|(prefix, _)| format!("{prefix}-"))
+        .expect("scoped cursor has revision suffix");
+    let revision = cursor
+        .strip_prefix(&expected_prefix)
+        .ok_or_else(|| {
+            if cursor.starts_with("fh1-") {
+                "CURSOR_SCOPE_VIOLATION".to_string()
+            } else {
+                "INVALID_CURSOR".to_string()
+            }
+        })?;
+    if revision.len() != 16 {
+        return Err("INVALID_CURSOR".into());
+    }
+    u64::from_str_radix(revision, 16).map_err(|_| "INVALID_CURSOR".into())
+}
+
+fn parse_revision_reference(reference: &str) -> Option<u64> {
+    reference
+        .strip_prefix("revision-")
+        .or_else(|| reference.strip_prefix("commit-"))
+        .unwrap_or(reference)
+        .parse()
+        .ok()
+        .or_else(|| decode_cursor(reference).ok())
+}
+
+fn project_transaction(transaction: TransactionAttribution) -> CausalEvent {
+    if let Some(mut event) = transaction
+        .audit
+        .as_ref()
+        .and_then(|audit| audit.get("legacy_event"))
+        .and_then(|event| serde_json::from_value::<CausalEvent>(event.clone()).ok())
+    {
+        event.state_version = Some(transaction.commit_revision.to_string());
+        event.revision_id = Some(format!("revision-{}", transaction.commit_revision));
+        event.operation_ids = transaction.operation_ids.clone();
+        event
+            .metadata
+            .extend(event_metadata(&transaction, transaction.commit_revision));
+        return event;
+    }
+    let audit = transaction.audit.as_ref();
+    let text = |field: &str| {
+        audit
+            .and_then(|value| value.get(field))
+            .and_then(Value::as_str)
+            .map(str::to_string)
+    };
+    let revision = transaction.commit_revision;
+    CausalEvent {
+        event_id: format!("commit-{revision}"),
+        causal_id: text("causal_id").unwrap_or_else(|| transaction.transaction_id.clone()),
+        parent_event_id: text("parent_event_id"),
+        timestamp: (transaction.unix_ms / 1000) as u64,
+        tenant_id: transaction.tenant_id.clone().unwrap_or_default(),
+        application_id: transaction.application_id.clone().unwrap_or_default(),
+        revision_id: Some(format!("revision-{revision}")),
+        subject_id: transaction.subject.clone().unwrap_or_default(),
+        subject_type: text("subject_type").unwrap_or_else(|| "principal".into()),
+        authorization_decision_id: text("authorization_decision_id"),
+        capability: text("capability"),
+        resource: text("resource"),
+        operation: text("kind").unwrap_or_else(|| "state.committed".into()),
+        workload_id: text("work_id").or_else(|| text("workload_id")),
+        attempt_id: text("attempt_id"),
+        worker_id: text("worker_id"),
+        connection_id: text("connection_id"),
+        execution_id: text("execution_id"),
+        state_version: Some(revision.to_string()),
+        operation_ids: transaction.operation_ids.clone(),
+        artifact_ids: Vec::new(),
+        result_id: text("result_id"),
+        status: "committed".into(),
+        error_code: None,
+        metadata: event_metadata(&transaction, revision),
+        schema_version: 1,
+    }
+}
+
+fn event_metadata(transaction: &TransactionAttribution, revision: u64) -> BTreeMap<String, Value> {
+    // Managed application transaction ids are scoped internally so two
+    // applications cannot collide in one substrate log. The caller's stable
+    // transaction identity remains in the durable audit and is the public
+    // identity used by transaction responses, provenance lookup, and events.
+    let public_transaction_id = transaction
+        .audit
+        .as_ref()
+        .and_then(|audit| audit.get("transaction_id"))
+        .and_then(Value::as_str)
+        .unwrap_or(&transaction.transaction_id);
+    let mut metadata = BTreeMap::from([
+        ("cursor".into(), Value::String(encode_cursor(revision))),
+        (
+            "transaction_id".into(),
+            Value::String(public_transaction_id.to_string()),
+        ),
+        (
+            "revision_id".into(),
+            Value::String(format!("revision-{revision}")),
+        ),
+    ]);
+    for (name, value) in [
+        ("principal_id", transaction.principal_id.as_ref()),
+        ("agent_id", transaction.agent_id.as_ref()),
+        ("session_id", transaction.session_id.as_ref()),
+        ("delegator_id", transaction.delegator_id.as_ref()),
+        ("work_id", transaction.work_id.as_ref()),
+    ] {
+        if let Some(value) = value {
+            metadata.insert(name.into(), Value::String(value.clone()));
+        }
+    }
+    metadata
+}
+
+fn random_id(prefix: &str) -> String {
+    format!(
+        "{prefix}_{}",
+        rand::thread_rng()
+            .sample_iter(&Alphanumeric)
+            .take(18)
+            .map(char::from)
+            .collect::<String>()
+    )
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
-    #[test]
-    fn causal_chain_is_durable_idempotent_and_queryable() {
-        let p = std::env::temp_dir().join(format!("causal-{}", now()));
-        let s = CausalStore::load(&p).unwrap();
-        let e = CausalEvent {
-            event_id: "e1".into(),
-            causal_id: "c1".into(),
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    fn event(id: &str) -> CausalEvent {
+        CausalEvent {
+            event_id: id.into(),
+            causal_id: String::new(),
             parent_event_id: None,
-            timestamp: 0,
+            timestamp: 1,
             tenant_id: "t".into(),
-            application_id: "a".into(),
-            revision_id: Some("r".into()),
-            subject_id: "u".into(),
-            subject_type: "human".into(),
+            application_id: "app".into(),
+            revision_id: None,
+            subject_id: "agent-1".into(),
+            subject_type: "agent".into(),
             authorization_decision_id: None,
             capability: None,
             resource: None,
             operation: "test".into(),
-            workload_id: Some("w".into()),
+            workload_id: None,
+            attempt_id: None,
+            worker_id: None,
+            connection_id: None,
+            execution_id: None,
+            state_version: None,
+            operation_ids: Vec::new(),
+            artifact_ids: Vec::new(),
+            result_id: None,
+            status: "committed".into(),
+            error_code: None,
+            metadata: BTreeMap::new(),
+            schema_version: 1,
+        }
+    }
+
+    #[test]
+    fn cursor_is_canonical_and_restartable() {
+        let cursor = encode_cursor(42);
+        assert_eq!(decode_cursor(&cursor).unwrap(), 42);
+        assert!(decode_cursor("42").is_err());
+        let scoped = encode_scoped_cursor("authority-1:app-1", 42);
+        assert_eq!(
+            decode_scoped_cursor("authority-1:app-1", &scoped).unwrap(),
+            42
+        );
+        assert_eq!(
+            decode_scoped_cursor("authority-1:app-2", &scoped).unwrap_err(),
+            "CURSOR_SCOPE_VIOLATION"
+        );
+    }
+
+    #[test]
+    fn canonical_projection_survives_source_deletion_and_restart() {
+        let nonce = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let root = std::env::temp_dir().join(format!("feltdb-causal-authority-{nonce}"));
+        fs::create_dir_all(&root).unwrap();
+        let data = root.join("state.log");
+        let legacy = root.join("causal-events.json");
+        let db = FeltDb::open(&data).unwrap();
+        db.apply_atomic_transaction(
+            "source-tx",
+            None,
+            &[],
+            &[AtomicMutation {
+                capability: "orders".into(),
+                key: "one".into(),
+                value: Some(json!({"status": "paid"})),
+            }],
+            Some(json!({"subject":"agent-1","tenant":"t","application":"app"})),
+        )
+        .unwrap();
+        let event = CausalEvent {
+            event_id: "legacy-event".into(),
+            causal_id: "cause-1".into(),
+            parent_event_id: None,
+            timestamp: 1,
+            tenant_id: "t".into(),
+            application_id: "app".into(),
+            revision_id: None,
+            subject_id: "agent-1".into(),
+            subject_type: "agent".into(),
+            authorization_decision_id: None,
+            capability: None,
+            resource: None,
+            operation: "order.paid".into(),
+            workload_id: None,
             attempt_id: None,
             worker_id: None,
             connection_id: None,
             execution_id: None,
             state_version: None,
-            operation_ids: vec![],
-            artifact_ids: vec![],
+            operation_ids: Vec::new(),
+            artifact_ids: Vec::new(),
             result_id: None,
-            status: "succeeded".into(),
+            status: "committed".into(),
             error_code: None,
             metadata: BTreeMap::new(),
-            schema_version: 0,
+            schema_version: 1,
         };
-        s.append(e.clone()).unwrap();
-        s.append(e).unwrap();
-        assert_eq!(s.list("c1").len(), 1);
-        assert_eq!(s.workload("w").len(), 1);
-        let _ = fs::remove_file(p);
+        fs::write(&legacy, serde_json::to_vec(&json!({"events":[event]})).unwrap()).unwrap();
+        let authority = CanonicalEventAuthority::new(db);
+        authority.migrate_legacy_file(&legacy).unwrap();
+        authority.migrate_legacy_file(&legacy).unwrap();
+        fs::remove_file(&legacy).unwrap();
+        drop(authority);
+
+        let recovered = CanonicalEventAuthority::new(FeltDb::open(&data).unwrap());
+        let chain = recovered.list("cause-1").unwrap();
+        assert_eq!(chain.len(), 1);
+        assert_eq!(chain[0].event_id, "legacy-event");
+        assert!(!legacy.exists());
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[test]
+    fn every_legacy_class_is_evidenced_without_copying_execution_facts() {
+        let nonce = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let root = std::env::temp_dir().join(format!("feltdb-causal-classes-{nonce}"));
+        fs::create_dir_all(&root).unwrap();
+        let data = root.join("state.log");
+        let legacy = root.join("causal-events.json");
+        let db = FeltDb::open(&data).unwrap();
+        db.apply_atomic_transaction(
+            "source-tx",
+            None,
+            &[],
+            &[AtomicMutation {
+                capability: "orders".into(),
+                key: "one".into(),
+                value: Some(json!({"status":"paid"})),
+            }],
+            Some(json!({"subject":"agent-1","tenant":"t","application":"app"})),
+        )
+        .unwrap();
+        db.apply_atomic_transaction(
+            "work-tx",
+            None,
+            &[],
+            &[AtomicMutation {
+                capability: DURABLE_WORK_COLLECTION.into(),
+                key: "t/app/work-1".into(),
+                value: Some(json!({
+                    "workload_id":"work-1",
+                    "tenant_id":"t",
+                    "application_id":"app",
+                    "attempts":[{"attempt_id":"attempt-1"}],
+                    "result":{"result_id":"result-1"}
+                })),
+            }],
+            Some(json!({
+                "subject":"agent-1", "tenant":"t", "application":"app",
+                "work_id":"work-1", "agent_id":"agent-1", "session_id":"session-1",
+                "delegator_id":"human-1"
+            })),
+        )
+        .unwrap();
+
+        let source = db.transaction_attribution("source-tx").unwrap().unwrap();
+        let mut authoritative = event("authoritative");
+        authoritative.operation_ids = vec![source.operation_ids[0].clone()];
+        let mut execution = event("execution");
+        execution.workload_id = Some("work-1".into());
+        execution.attempt_id = Some("attempt-1".into());
+        execution.result_id = Some("result-1".into());
+        let mut telemetry = event("telemetry");
+        telemetry.causal_id = "telemetry-correlation".into();
+        telemetry.execution_id = Some("runtime-only".into());
+        let mut metadata = event("metadata");
+        metadata.causal_id = "cause-1".into();
+        let not_needed = event("not-needed");
+        fs::write(
+            &legacy,
+            serde_json::to_vec(&json!({
+                "events":[authoritative, execution, telemetry, metadata, not_needed]
+            }))
+            .unwrap(),
+        )
+        .unwrap();
+
+        let authority = CanonicalEventAuthority::new(db.clone());
+        authority.migrate_legacy_file(&legacy).unwrap();
+        let evidence = db.list_collection(MIGRATION_EVIDENCE_COLLECTION).unwrap();
+        assert_eq!(evidence.len(), 5);
+        let classes = evidence
+            .iter()
+            .map(|row| row.value["classification"].as_str().unwrap())
+            .collect::<std::collections::BTreeSet<_>>();
+        assert_eq!(
+            classes,
+            [
+                "AUTHORITATIVE",
+                "CAUSAL_METADATA",
+                "EXECUTION_FACT",
+                "NOT_NEEDED",
+                "TELEMETRY",
+            ]
+            .into()
+        );
+        let metadata_rows = db.list_collection(CAUSAL_METADATA_COLLECTION).unwrap();
+        assert_eq!(metadata_rows.len(), 1);
+        assert_eq!(metadata_rows[0].value["event"]["event_id"], "metadata");
+        assert!(!metadata_rows.iter().any(|row| {
+            row.value["event"]["event_id"] == Value::String("execution".into())
+        }));
+        drop((authority, db));
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[test]
+    fn unresolved_authority_and_execution_references_fail_closed() {
+        let root = std::env::temp_dir().join(format!(
+            "feltdb-causal-unresolved-{}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&root).unwrap();
+        let authority = CanonicalEventAuthority::new(FeltDb::open(root.join("state.log")).unwrap());
+        let mut authoritative = event("bad-authority");
+        authoritative.operation_ids = vec!["missing-operation".into()];
+        assert!(authority
+            .record_classification(&authoritative, CausalClassification::Authoritative)
+            .unwrap_err()
+            .contains("unresolved"));
+        let mut execution = event("bad-execution");
+        execution.workload_id = Some("missing-work".into());
+        assert!(authority
+            .record_classification(&execution, CausalClassification::ExecutionFact)
+            .unwrap_err()
+            .contains("unresolved"));
+        assert!(authority.append(execution).unwrap_err().contains("Durable Work"));
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[test]
+    fn revision_and_decision_resolution_is_tenant_application_scoped() {
+        let root = std::env::temp_dir().join(format!(
+            "feltdb-causal-scope-{}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&root).unwrap();
+        let db = FeltDb::open(root.join("state.log")).unwrap();
+        db.apply_atomic_transaction(
+            "scoped-transaction",
+            None,
+            &[],
+            &[AtomicMutation {
+                capability: "orders".into(),
+                key: "one".into(),
+                value: Some(json!({"status":"paid"})),
+            }],
+            Some(json!({
+                "subject":"agent-1", "tenant":"t", "application":"app",
+                "authorization_decision_id":"decision-1"
+            })),
+        )
+        .unwrap();
+        let authority = CanonicalEventAuthority::new(db);
+        let mut scoped = event("scoped");
+        scoped.state_version = Some("1".into());
+        scoped.authorization_decision_id = Some("decision-1".into());
+        authority
+            .record_classification(&scoped, CausalClassification::Authoritative)
+            .unwrap();
+
+        let mut cross_scope = scoped;
+        cross_scope.event_id = "cross-scope".into();
+        cross_scope.application_id = "other-app".into();
+        assert!(authority
+            .record_classification(&cross_scope, CausalClassification::Authoritative)
+            .unwrap_err()
+            .contains("unresolved"));
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[test]
+    fn projected_identity_and_provenance_are_distinct_and_restartable() {
+        let root = std::env::temp_dir().join(format!(
+            "feltdb-event-provenance-{}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&root).unwrap();
+        let data = root.join("state.log");
+        let db = FeltDb::open(&data).unwrap();
+        db.apply_atomic_transaction(
+            "transaction-1",
+            None,
+            &[],
+            &[AtomicMutation {
+                capability: "orders".into(),
+                key: "one".into(),
+                value: Some(json!({"status":"paid"})),
+            }],
+            Some(json!({
+                "subject":"agent-1", "tenant":"t", "application":"app",
+                "principal_id":"agent-1", "agent_id":"agent-1",
+                "session_id":"session-1", "delegator_id":"human-1", "work_id":"work-1"
+            })),
+        )
+        .unwrap();
+        drop(db);
+
+        let recovered = CanonicalEventAuthority::new(FeltDb::open(&data).unwrap());
+        let projected = recovered.after(0, 10).unwrap().remove(0);
+        assert_eq!(projected.event_id, "commit-1");
+        assert_eq!(projected.revision_id.as_deref(), Some("revision-1"));
+        assert_eq!(projected.metadata["transaction_id"], "transaction-1");
+        assert_ne!(projected.operation_ids[0], "transaction-1");
+        assert_eq!(projected.metadata["session_id"], "session-1");
+        assert_eq!(projected.metadata["agent_id"], "agent-1");
+        assert_eq!(projected.metadata["delegator_id"], "human-1");
+        assert_eq!(projected.metadata["work_id"], "work-1");
+        assert_eq!(projected.metadata["cursor"], encode_cursor(1));
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[test]
+    fn projected_events_expose_the_public_transaction_identity() {
+        let root = std::env::temp_dir().join(format!(
+            "feltdb-event-public-transaction-{}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&root).unwrap();
+        let db = FeltDb::open(root.join("state.log")).unwrap();
+        db.apply_atomic_transaction(
+            "txscope_private_public-transaction",
+            None,
+            &[],
+            &[AtomicMutation {
+                capability: "records".into(),
+                key: "one".into(),
+                value: Some(json!({"id":"one"})),
+            }],
+            Some(json!({
+                "transaction_id":"public-transaction",
+                "subject":"service-1",
+                "tenant":"tenant-1",
+                "application":"app-1"
+            })),
+        )
+        .unwrap();
+
+        let event = CanonicalEventAuthority::new(db)
+            .after(0, 1)
+            .unwrap()
+            .remove(0);
+        assert_eq!(event.metadata["transaction_id"], "public-transaction");
+        assert_ne!(
+            event.metadata["transaction_id"],
+            "txscope_private_public-transaction"
+        );
+        let _ = fs::remove_dir_all(root);
     }
 }