Skip to main content

ruvector_proof_gate/
payload.rs

1use thiserror::Error;
2
3/// A vector write payload: the unit of admission through a WriteGate.
4#[derive(Debug, Clone)]
5pub struct WritePayload {
6    /// Monotonic identifier assigned by the caller.
7    pub id: u64,
8    /// The embedding vector (f32 components).
9    pub vector: Vec<f32>,
10    /// Arbitrary metadata bytes (e.g. JSON-encoded tags, namespace, etc.).
11    pub metadata: Vec<u8>,
12    /// Originating agent identifier (16 bytes, e.g. UUID without hyphens).
13    pub agent_id: [u8; 16],
14    /// UNIX timestamp in nanoseconds at the write site.
15    pub timestamp_ns: u64,
16}
17
18impl WritePayload {
19    pub fn new(id: u64, vector: Vec<f32>) -> Self {
20        Self {
21            id,
22            vector,
23            metadata: Vec::new(),
24            agent_id: [0u8; 16],
25            timestamp_ns: 0,
26        }
27    }
28
29    pub fn with_metadata(mut self, metadata: Vec<u8>) -> Self {
30        self.metadata = metadata;
31        self
32    }
33
34    pub fn with_agent(mut self, agent_id: [u8; 16]) -> Self {
35        self.agent_id = agent_id;
36        self
37    }
38
39    pub fn with_timestamp(mut self, timestamp_ns: u64) -> Self {
40        self.timestamp_ns = timestamp_ns;
41        self
42    }
43
44    /// SHA-256 of the canonical encoding, computed **without** allocating the
45    /// intermediate byte buffer — streams each field straight into the hasher.
46    /// Produces a digest identical to `Sha256::digest(self.canonical_bytes())`,
47    /// so it is a drop-in fast path (no on-disk/format change).
48    pub fn payload_hash(&self) -> [u8; 32] {
49        use sha2::{Digest, Sha256};
50        let mut h = Sha256::new();
51        h.update(self.id.to_le_bytes());
52        h.update((self.vector.len() as u32).to_le_bytes());
53        for f in &self.vector {
54            h.update(f.to_le_bytes());
55        }
56        h.update((self.metadata.len() as u32).to_le_bytes());
57        h.update(&self.metadata);
58        h.update(self.agent_id);
59        h.update(self.timestamp_ns.to_le_bytes());
60        h.finalize().into()
61    }
62
63    /// Canonical byte representation used as hash preimage.
64    ///
65    /// Fixed-structure concatenation: prevents length-extension issues
66    /// because each field has a deterministic length or delimiter.
67    pub fn canonical_bytes(&self) -> Vec<u8> {
68        let vec_len = self.vector.len() * 4;
69        let mut out = Vec::with_capacity(8 + vec_len + 4 + self.metadata.len() + 16 + 8);
70        out.extend_from_slice(&self.id.to_le_bytes());
71        // Dimension prefix prevents aliasing between different-length vectors
72        out.extend_from_slice(&(self.vector.len() as u32).to_le_bytes());
73        for f in &self.vector {
74            out.extend_from_slice(&f.to_le_bytes());
75        }
76        // Metadata length prefix
77        out.extend_from_slice(&(self.metadata.len() as u32).to_le_bytes());
78        out.extend_from_slice(&self.metadata);
79        out.extend_from_slice(&self.agent_id);
80        out.extend_from_slice(&self.timestamp_ns.to_le_bytes());
81        out
82    }
83}
84
85/// Which gate variant produced a receipt.
86#[derive(Debug, Clone, Copy, PartialEq, Eq)]
87#[repr(u8)]
88pub enum GateVariant {
89    /// No integrity check. Used only to establish baseline throughput.
90    Null = 0,
91    /// Sequential SHA-256 hash chain: each entry chains the previous hash.
92    HashChain = 1,
93    /// Merkle Mountain Range: append-only tree with O(log n) per insert.
94    Merkle = 2,
95}
96
97/// Cryptographic receipt returned by a WriteGate for each admitted payload.
98#[derive(Debug, Clone)]
99pub struct WriteReceipt {
100    /// Monotonically increasing write sequence number within this gate.
101    pub sequence: u64,
102    /// SHA-256 of the canonical payload bytes.
103    pub payload_hash: [u8; 32],
104    /// The gate's current chain commitment after this write.
105    /// - NullGate:      all zeros
106    /// - HashChainGate: SHA-256(prev_commitment || payload_hash || sequence)
107    /// - MerkleGate:    MMR root after this leaf was appended
108    pub chain_commitment: [u8; 32],
109    /// Gate variant that produced this receipt.
110    pub gate_variant: GateVariant,
111}
112
113/// Errors returned when a gate rejects an admission.
114#[derive(Debug, Error)]
115pub enum GateError {
116    #[error("admission denied: {0}")]
117    Denied(String),
118}