feat: implement Verity truth engine Phase 1 (kernel, outcomes, integrity)

Rust workspace with three foundational crates:

- verity-kernel: Money (integer minor units, checked arithmetic, bps
  splits), BasisPoints (0-10000), type-safe IDs with format validation,
  CanonicalTimestamp (UTC-only), deterministic JSON serialization with
  sorted keys, SHA-256 canonical hashing

- verity-outcomes: Outcome state machine (UNKNOWN → SUCCESS/FAIL/
  PARTIAL/TIMEOUT/DISPUTED, DISPUTED → resolution, SUCCESS/FAIL/
  PARTIAL → REVERSED, TIMEOUT → DISPUTED), DecisionType enum (7 types),
  transition history tracking

- verity-integrity: Hash chains (append-only, tamper detection),
  replay hash computation and verification, Ed25519 signing with
  VeritySigner, Merkle tree for batch proofs

68 tests pass, zero clippy warnings.

Author: omoshola-o

verity-engine/Cargo.toml

@@ -0,0 +1,24 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/verity-kernel",
+    "crates/verity-outcomes",
+    "crates/verity-integrity",
+]
+
+[workspace.package]
+version = "0.2.0"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/agentralabs/verity-engine"
+
+[workspace.dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+sha2 = "0.10"
+ed25519-dalek = { version = "2", features = ["serde"] }
+rand = "0.8"
+thiserror = "1"
+chrono = { version = "0.4", features = ["serde"] }
+hex = "0.4"
+base64 = "0.22"

verity-engine/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentra Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

verity-engine/crates/verity-integrity/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "verity-integrity"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Hash chains, replay proofs, and cryptographic signing for Verity"
+
+[dependencies]
+verity-kernel = { path = "../verity-kernel" }
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+ed25519-dalek.workspace = true
+rand.workspace = true
+thiserror.workspace = true
+hex.workspace = true
+base64.workspace = true

verity-engine/crates/verity-integrity/src/chain.rs

@@ -0,0 +1,183 @@
+use serde::Serialize;
+use verity_kernel::{VerityId, SettlementId, VerityError, canonical_hash};
+
+/// A chain of VerityReceipts for a single settlement.
+/// Each receipt's hash includes the previous receipt's hash.
+/// Invariant 8: Truth history is append-only.
+pub struct VerityChain {
+    settlement_id: SettlementId,
+    entries: Vec<ChainEntry>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ChainEntry {
+    pub position: u32,
+    pub verity_id: VerityId,
+    pub content_hash: String,
+    pub previous_hash: Option<String>,
+    pub chain_hash: String,
+}
+
+impl VerityChain {
+    pub fn new(settlement_id: SettlementId) -> Self {
+        Self {
+            settlement_id,
+            entries: Vec::new(),
+        }
+    }
+
+    /// Append a new entry to the chain. Returns the chain_hash.
+    pub fn append(
+        &mut self,
+        verity_id: VerityId,
+        content: &impl Serialize,
+    ) -> Result<String, VerityError> {
+        let content_hash = canonical_hash(content)?;
+        let previous_hash = self.entries.last().map(|e| e.chain_hash.clone());
+        let position = (self.entries.len() as u32) + 1;
+
+        let chain_input = ChainHashInput {
+            content_hash: &content_hash,
+            previous_hash: previous_hash.as_deref(),
+        };
+        let chain_hash = canonical_hash(&chain_input)?;
+
+        let entry = ChainEntry {
+            position,
+            verity_id,
+            content_hash,
+            previous_hash,
+            chain_hash: chain_hash.clone(),
+        };
+        self.entries.push(entry);
+        Ok(chain_hash)
+    }
+
+    /// Verify the entire chain is intact (no gaps, no tampering).
+    pub fn verify(&self) -> Result<bool, VerityError> {
+        for (i, entry) in self.entries.iter().enumerate() {
+            // Check position is sequential
+            if entry.position != (i as u32) + 1 {
+                return Ok(false);
+            }
+
+            // Check previous_hash linkage
+            if i == 0 {
+                if entry.previous_hash.is_some() {
+                    return Ok(false);
+                }
+            } else if entry.previous_hash.as_ref() != Some(&self.entries[i - 1].chain_hash) {
+                return Ok(false);
+            }
+
+            // Recompute chain_hash and verify
+            let chain_input = ChainHashInput {
+                content_hash: &entry.content_hash,
+                previous_hash: entry.previous_hash.as_deref(),
+            };
+            let expected = canonical_hash(&chain_input)?;
+            if entry.chain_hash != expected {
+                return Ok(false);
+            }
+        }
+        Ok(true)
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    pub fn latest_hash(&self) -> Option<&str> {
+        self.entries.last().map(|e| e.chain_hash.as_str())
+    }
+
+    pub fn settlement_id(&self) -> &SettlementId {
+        &self.settlement_id
+    }
+
+    pub fn entries(&self) -> &[ChainEntry] {
+        &self.entries
+    }
+}
+
+#[derive(Serialize)]
+struct ChainHashInput<'a> {
+    content_hash: &'a str,
+    previous_hash: Option<&'a str>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn test_settlement_id() -> SettlementId {
+        SettlementId::new("stl_4b7c9e2f").unwrap()
+    }
+
+    #[test]
+    fn test_append_and_verify() {
+        let mut chain = VerityChain::new(test_settlement_id());
+        let v1 = VerityId::new("vrt_a1b2c3d4").unwrap();
+        let v2 = VerityId::new("vrt_e5f6a7b8").unwrap();
+
+        chain.append(v1, &json!({"decision": "release"})).unwrap();
+        chain.append(v2, &json!({"decision": "split"})).unwrap();
+
+        assert_eq!(chain.len(), 2);
+        assert!(chain.verify().unwrap());
+    }
+
+    #[test]
+    fn test_first_entry_no_previous() {
+        let mut chain = VerityChain::new(test_settlement_id());
+        let v1 = VerityId::new("vrt_a1b2c3d4").unwrap();
+        chain.append(v1, &json!({"test": true})).unwrap();
+
+        assert!(chain.entries()[0].previous_hash.is_none());
+    }
+
+    #[test]
+    fn test_subsequent_entries_link() {
+        let mut chain = VerityChain::new(test_settlement_id());
+        let v1 = VerityId::new("vrt_a1b2c3d4").unwrap();
+        let v2 = VerityId::new("vrt_e5f6a7b8").unwrap();
+
+        chain.append(v1, &json!({"step": 1})).unwrap();
+        chain.append(v2, &json!({"step": 2})).unwrap();
+
+        assert_eq!(
+            chain.entries()[1].previous_hash.as_ref().unwrap(),
+            &chain.entries()[0].chain_hash
+        );
+    }
+
+    #[test]
+    fn test_tamper_detection() {
+        let mut chain = VerityChain::new(test_settlement_id());
+        let v1 = VerityId::new("vrt_a1b2c3d4").unwrap();
+        let v2 = VerityId::new("vrt_e5f6a7b8").unwrap();
+
+        chain.append(v1, &json!({"step": 1})).unwrap();
+        chain.append(v2, &json!({"step": 2})).unwrap();
+
+        // Tamper with first entry's content_hash
+        chain.entries[0].content_hash = "sha256:0000000000000000000000000000000000000000000000000000000000000000".to_string();
+
+        assert!(!chain.verify().unwrap());
+    }
+
+    #[test]
+    fn test_latest_hash() {
+        let mut chain = VerityChain::new(test_settlement_id());
+        assert!(chain.latest_hash().is_none());
+
+        let v1 = VerityId::new("vrt_a1b2c3d4").unwrap();
+        let hash = chain.append(v1, &json!({"test": true})).unwrap();
+        assert_eq!(chain.latest_hash().unwrap(), hash);
+    }
+}

verity-engine/crates/verity-integrity/src/lib.rs

@@ -0,0 +1,9 @@
+mod chain;
+mod replay;
+mod signing;
+mod merkle;
+
+pub use chain::{VerityChain, ChainEntry};
+pub use replay::{compute_replay_hash, verify_replay_hash};
+pub use signing::{VeritySigner, verify_signature};
+pub use merkle::MerkleTree;

verity-engine/crates/verity-integrity/src/merkle.rs

@@ -0,0 +1,133 @@
+use sha2::{Sha256, Digest};
+use verity_kernel::VerityError;
+
+/// Merkle tree for batch inclusion proofs.
+/// In v1.0, we support single-entry proof. Full batch proofs in v1.1.
+pub struct MerkleTree {
+    leaves: Vec<String>,
+    root: Option<String>,
+}
+
+impl MerkleTree {
+    pub fn new() -> Self {
+        Self {
+            leaves: Vec::new(),
+            root: None,
+        }
+    }
+
+    pub fn add_leaf(&mut self, hash: String) {
+        self.leaves.push(hash);
+        self.root = None; // invalidate cached root
+    }
+
+    pub fn compute_root(&mut self) -> Result<String, VerityError> {
+        if self.leaves.is_empty() {
+            return Err(VerityError::ChainIntegrityError(
+                "cannot compute root of empty tree".to_string(),
+            ));
+        }
+
+        let mut current_level: Vec<String> = self.leaves.clone();
+
+        while current_level.len() > 1 {
+            let mut next_level = Vec::new();
+            for chunk in current_level.chunks(2) {
+                let combined = if chunk.len() == 2 {
+                    format!("{}{}", chunk[0], chunk[1])
+                } else {
+                    // Odd node: duplicate it
+                    format!("{}{}", chunk[0], chunk[0])
+                };
+                let mut hasher = Sha256::new();
+                hasher.update(combined.as_bytes());
+                let hash = hasher.finalize();
+                next_level.push(format!("sha256:{}", hex::encode(hash)));
+            }
+            current_level = next_level;
+        }
+
+        let root = current_level.into_iter().next().unwrap();
+        self.root = Some(root.clone());
+        Ok(root)
+    }
+
+    pub fn root(&self) -> Option<&str> {
+        self.root.as_deref()
+    }
+
+    pub fn len(&self) -> usize {
+        self.leaves.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.leaves.is_empty()
+    }
+}
+
+impl Default for MerkleTree {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_single_leaf() {
+        let mut tree = MerkleTree::new();
+        tree.add_leaf("sha256:abc123".to_string());
+        let root = tree.compute_root().unwrap();
+        assert!(root.starts_with("sha256:"));
+    }
+
+    #[test]
+    fn test_multiple_leaves() {
+        let mut tree = MerkleTree::new();
+        tree.add_leaf("sha256:aaa".to_string());
+        tree.add_leaf("sha256:bbb".to_string());
+        tree.add_leaf("sha256:ccc".to_string());
+        let root = tree.compute_root().unwrap();
+        assert!(root.starts_with("sha256:"));
+    }
+
+    #[test]
+    fn test_root_changes_with_leaf() {
+        let mut tree1 = MerkleTree::new();
+        tree1.add_leaf("sha256:aaa".to_string());
+        tree1.add_leaf("sha256:bbb".to_string());
+        let root1 = tree1.compute_root().unwrap();
+
+        let mut tree2 = MerkleTree::new();
+        tree2.add_leaf("sha256:aaa".to_string());
+        tree2.add_leaf("sha256:ccc".to_string());
+        let root2 = tree2.compute_root().unwrap();
+
+        assert_ne!(root1, root2);
+    }
+
+    #[test]
+    fn test_empty_tree_errors() {
+        let mut tree = MerkleTree::new();
+        assert!(tree.compute_root().is_err());
+    }
+
+    #[test]
+    fn test_root_cached() {
+        let mut tree = MerkleTree::new();
+        tree.add_leaf("sha256:aaa".to_string());
+        tree.compute_root().unwrap();
+        assert!(tree.root().is_some());
+    }
+
+    #[test]
+    fn test_root_invalidated_on_add() {
+        let mut tree = MerkleTree::new();
+        tree.add_leaf("sha256:aaa".to_string());
+        tree.compute_root().unwrap();
+        tree.add_leaf("sha256:bbb".to_string());
+        assert!(tree.root().is_none());
+    }
+}