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}