hyphae_engine/retrieval_proof/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! Canonical durable-retrieval proofs and complete offline verification.
4
5mod codec;
6mod model;
7mod verify;
8
9pub use model::{
10    EXACT_RETRIEVAL_SEMANTICS_VERSION, ExactRetrievalProof, ExactRetrievalProofArtifact,
11    ExactRetrievalVerificationReport, HYBRID_RETRIEVAL_SEMANTICS_VERSION, HybridRetrievalProof,
12    HybridRetrievalProofArtifact, HybridRetrievalVerificationReport,
13    LEXICAL_RETRIEVAL_SEMANTICS_VERSION, LexicalRetrievalProof, LexicalRetrievalProofArtifact,
14    LexicalRetrievalVerificationReport, MAX_RETRIEVAL_PROOF_BYTES, RETRIEVAL_PROOF_FORMAT_VERSION,
15    RetrievalProofAnchor, RetrievalProofError, RetrievalVerificationLimits,
16};
17pub use verify::{
18    read_exact_retrieval_proof, read_hybrid_retrieval_proof, read_lexical_retrieval_proof,
19    verify_exact_retrieval_proof, verify_hybrid_retrieval_proof, verify_lexical_retrieval_proof,
20    write_exact_retrieval_proof, write_hybrid_retrieval_proof, write_lexical_retrieval_proof,
21};
22
23use hyphae_retrieval::{
24    ExactRetrievalOutcome, ExactRetrievalRequest, HybridOutcome, HybridRequest, LexicalOutcome,
25    LexicalRequest,
26};
27use hyphae_storage::SnapshotInfo;
28
29use self::codec::{
30    decode_hybrid_proof, decode_lexical_proof, decode_proof, encode_hybrid_proof,
31    encode_lexical_proof, encode_proof, finalize_hybrid_proof, finalize_lexical_proof,
32    finalize_proof,
33};
34
35impl ExactRetrievalProof {
36    /// Creates a canonical exact proof over a format-2 snapshot.
37    ///
38    /// # Errors
39    ///
40    /// Returns an error for a legacy witness, invalid model, or proof bound.
41    pub fn new(
42        snapshot: &SnapshotInfo,
43        request: ExactRetrievalRequest,
44        outcome: ExactRetrievalOutcome,
45    ) -> Result<Self, RetrievalProofError> {
46        if snapshot.disk_format_version != 2 {
47            return Err(RetrievalProofError::SnapshotFormatMismatch);
48        }
49        finalize_proof(
50            RetrievalProofAnchor::from_snapshot(snapshot),
51            request,
52            outcome,
53        )
54    }
55
56    /// Encodes the complete proof into canonical portable bytes.
57    ///
58    /// # Errors
59    ///
60    /// Returns an error for an invalid model or exceeded hard bound.
61    pub fn to_bytes(&self) -> Result<Vec<u8>, RetrievalProofError> {
62        encode_proof(self)
63    }
64
65    /// Verifies and decodes canonical proof bytes.
66    ///
67    /// # Errors
68    ///
69    /// Returns a framing, version, canonicality, checksum, or digest error.
70    pub fn from_bytes(encoded: &[u8]) -> Result<Self, RetrievalProofError> {
71        decode_proof(encoded)
72    }
73}
74
75impl LexicalRetrievalProof {
76    /// Creates a canonical lexical proof over a format-2 snapshot.
77    ///
78    /// # Errors
79    ///
80    /// Returns an error for a legacy witness, invalid model, or proof bound.
81    pub fn new(
82        snapshot: &SnapshotInfo,
83        request: LexicalRequest,
84        outcome: LexicalOutcome,
85    ) -> Result<Self, RetrievalProofError> {
86        if snapshot.disk_format_version != 2 {
87            return Err(RetrievalProofError::SnapshotFormatMismatch);
88        }
89        finalize_lexical_proof(
90            RetrievalProofAnchor::from_snapshot(snapshot),
91            request,
92            outcome,
93        )
94    }
95
96    /// Encodes the complete proof into canonical portable bytes.
97    ///
98    /// # Errors
99    ///
100    /// Returns an error for an invalid model or exceeded hard bound.
101    pub fn to_bytes(&self) -> Result<Vec<u8>, RetrievalProofError> {
102        encode_lexical_proof(self)
103    }
104
105    /// Verifies and decodes canonical lexical proof bytes.
106    ///
107    /// # Errors
108    ///
109    /// Returns a framing, version, canonicality, checksum, or digest error.
110    pub fn from_bytes(encoded: &[u8]) -> Result<Self, RetrievalProofError> {
111        decode_lexical_proof(encoded)
112    }
113}
114
115impl HybridRetrievalProof {
116    /// Creates a canonical hybrid proof over a format-2 snapshot.
117    ///
118    /// # Errors
119    ///
120    /// Returns an error for a legacy witness, invalid branch/fusion model, or
121    /// proof bound.
122    #[allow(clippy::too_many_arguments)]
123    pub fn new(
124        snapshot: &SnapshotInfo,
125        lexical_request: LexicalRequest,
126        lexical_outcome: LexicalOutcome,
127        vector_request: ExactRetrievalRequest,
128        vector_outcome: ExactRetrievalOutcome,
129        fusion_request: HybridRequest,
130        outcome: HybridOutcome,
131    ) -> Result<Self, RetrievalProofError> {
132        if snapshot.disk_format_version != 2 {
133            return Err(RetrievalProofError::SnapshotFormatMismatch);
134        }
135        finalize_hybrid_proof(
136            RetrievalProofAnchor::from_snapshot(snapshot),
137            lexical_request,
138            lexical_outcome,
139            vector_request,
140            vector_outcome,
141            fusion_request,
142            outcome,
143        )
144    }
145
146    /// Encodes the complete proof into canonical portable bytes.
147    ///
148    /// # Errors
149    ///
150    /// Returns an error for an invalid model or exceeded hard bound.
151    pub fn to_bytes(&self) -> Result<Vec<u8>, RetrievalProofError> {
152        encode_hybrid_proof(self)
153    }
154
155    /// Verifies and decodes canonical hybrid proof bytes.
156    ///
157    /// # Errors
158    ///
159    /// Returns a framing, version, canonicality, checksum, or digest error.
160    pub fn from_bytes(encoded: &[u8]) -> Result<Self, RetrievalProofError> {
161        decode_hybrid_proof(encoded)
162    }
163}
hyphae_engine/retrieval_proof/mod.rs

hyphae_engine/retrieval_proof/
mod.rs
