Skip to main content

hyprstream_bench/
manifest.rs

1//! The frozen item manifest: per-item blake3 hashes, family designations,
2//! generation config, and license/disclosure pointers.
3//!
4//! **Freeze rule (plan v1.6): the manifest is frozen before any P1.3
5//! synthesis run.** P1.3 consumes this artifact — the family firewall is "a
6//! consumed artifact, not a promise": gate families are never synthesized
7//! into training data, and no training item may hash-collide with (or
8//! duplicate) a manifest item.
9
10use std::fmt::Write as _;
11
12use serde::{Deserialize, Serialize};
13
14use crate::family::{Designation, Family};
15use crate::gen::{generate_all, BenchConfig};
16use crate::item::Item;
17
18/// Release id of the frozen benchmark.
19pub const RELEASE: &str = "vob-1.1";
20
21/// One manifest row per item.
22#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
23pub struct ManifestItem {
24    /// Item id.
25    pub id: String,
26    /// blake3 hex digest of the item's canonical bytes.
27    pub blake3: String,
28    /// Family id.
29    pub family: String,
30    /// Stratum wire form (`clean` / `nearmiss` / `perm-N`).
31    pub stratum: String,
32    /// Permutation group id.
33    pub group: String,
34    /// Question kind (`noul` / `choice` / `score`).
35    pub kind: String,
36    /// Correct label index in canonical label order.
37    pub truth: usize,
38}
39
40/// Family designation row — the family-level holdout firewall.
41#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
42pub struct FamilyRow {
43    /// Family id.
44    pub id: String,
45    /// `open` (train-usable) or `gate` (never synthesized; zero-shot gate).
46    pub designation: String,
47}
48
49/// The frozen manifest.
50#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
51pub struct Manifest {
52    /// Release id ([`RELEASE`]).
53    pub release: String,
54    /// Harness crate + version that generated this manifest.
55    pub harness: String,
56    /// Pinned generation config.
57    pub config: ManifestConfig,
58    /// Family designations (the firewall).
59    pub families: Vec<FamilyRow>,
60    /// License pointers: harness Apache-2.0, items CC-BY-4.0.
61    pub license: ManifestLicense,
62    /// Path of the pre-committed disclosure text + its blake3 digest.
63    pub disclosure: ManifestDisclosure,
64    /// Total item count.
65    pub item_count: usize,
66    /// Per-item rows, in generation order.
67    pub items: Vec<ManifestItem>,
68}
69
70/// Pinned generation config inside the manifest.
71#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
72pub struct ManifestConfig {
73    /// Base items per (family, base stratum, kind).
74    pub seeds_per_stratum: u32,
75    /// Seed stream base (hex).
76    pub seed_base: String,
77}
78
79/// License pointers inside the manifest.
80#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
81pub struct ManifestLicense {
82    /// Harness license (Apache-2.0).
83    pub harness: String,
84    /// Generated-items license (CC-BY-4.0).
85    pub items: String,
86}
87
88/// Disclosure pointer inside the manifest.
89#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
90pub struct ManifestDisclosure {
91    /// Repo-relative path of the disclosure text.
92    pub path: String,
93    /// blake3 hex digest of the disclosure file at freeze time.
94    pub blake3: String,
95}
96
97/// Errors from manifest verification.
98#[derive(Debug, Clone, PartialEq, Eq)]
99pub enum VerifyError {
100    /// Manifest release id mismatch.
101    ReleaseMismatch { expected: String, found: String },
102    /// Item count mismatch.
103    CountMismatch { expected: usize, found: usize },
104    /// Item at `index` diverged (first divergence reported).
105    ItemMismatch { index: usize, id: String },
106    /// A family designation changed (firewall violation).
107    DesignationChanged { family: String },
108}
109
110impl std::fmt::Display for VerifyError {
111    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
112        match self {
113            Self::ReleaseMismatch { expected, found } => {
114                write!(f, "release mismatch: expected {expected}, found {found}")
115            }
116            Self::CountMismatch { expected, found } => {
117                write!(f, "item count mismatch: expected {expected}, found {found}")
118            }
119            Self::ItemMismatch { index, id } => {
120                write!(f, "item #{index} ({id}) diverged from the frozen manifest")
121            }
122            Self::DesignationChanged { family } => {
123                write!(
124                    f,
125                    "family {family} designation changed — firewall violation"
126                )
127            }
128        }
129    }
130}
131
132impl std::error::Error for VerifyError {}
133
134/// Build the manifest from a fresh generation run.
135pub fn build(config: &BenchConfig, items: &[Item], disclosure_blake3: String) -> Manifest {
136    Manifest {
137        release: RELEASE.to_owned(),
138        harness: format!("hyprstream-bench {}", env!("CARGO_PKG_VERSION")),
139        config: ManifestConfig {
140            seeds_per_stratum: config.seeds_per_stratum,
141            seed_base: format!("0x{:x}", config.seed_base),
142        },
143        families: Family::ALL
144            .iter()
145            .map(|family| FamilyRow {
146                id: family.as_str().to_owned(),
147                designation: family.designation().as_str().to_owned(),
148            })
149            .collect(),
150        license: ManifestLicense {
151            harness: "Apache-2.0".to_owned(),
152            items: "CC-BY-4.0".to_owned(),
153        },
154        disclosure: ManifestDisclosure {
155            path: "crates/hyprstream-bench/DISCLOSURE.md".to_owned(),
156            blake3: disclosure_blake3,
157        },
158        item_count: items.len(),
159        items: items
160            .iter()
161            .map(|item| ManifestItem {
162                id: item.id.clone(),
163                blake3: item.hash(),
164                family: item.family.as_str().to_owned(),
165                stratum: item.stratum.as_str(),
166                group: item.group.clone(),
167                kind: item.question.kind.as_str().to_owned(),
168                truth: item.truth,
169            })
170            .collect(),
171    }
172}
173
174impl Manifest {
175    /// The firewalled gate families (P1.4 leg-e measurement surface).
176    pub fn gate_families(&self) -> Vec<Family> {
177        self.families
178            .iter()
179            .filter(|row| row.designation == Designation::Gate.as_str())
180            .filter_map(|row| Family::from_id(&row.id))
181            .collect()
182    }
183
184    /// Whether `hash` belongs to a frozen item (P1.3 item-level firewall).
185    pub fn contains_hash(&self, hash: &str) -> bool {
186        self.items.iter().any(|item| item.blake3 == hash)
187    }
188
189    /// Deterministic pretty JSON (2-space, trailing newline).
190    pub fn to_json(&self) -> String {
191        match serde_json::to_string_pretty(self) {
192            Ok(mut out) => {
193                out.push('\n');
194                out
195            }
196            // Manifest derives Serialize over JSON-safe fields only.
197            Err(_) => unreachable!("manifest serialization is infallible"),
198        }
199    }
200
201    /// Parse a manifest from JSON.
202    pub fn from_json(text: &str) -> Result<Self, serde_json::Error> {
203        serde_json::from_str(text)
204    }
205
206    /// Re-generate from `config` and verify every row against this manifest.
207    pub fn verify(&self, config: &BenchConfig) -> Result<(), VerifyError> {
208        if self.release != RELEASE {
209            return Err(VerifyError::ReleaseMismatch {
210                expected: RELEASE.to_owned(),
211                found: self.release.clone(),
212            });
213        }
214        let fresh = generate_all(config);
215        if fresh.len() != self.item_count {
216            return Err(VerifyError::CountMismatch {
217                expected: self.item_count,
218                found: fresh.len(),
219            });
220        }
221        for (index, (row, item)) in self.items.iter().zip(fresh.iter()).enumerate() {
222            if row.id != item.id || row.blake3 != item.hash() {
223                return Err(VerifyError::ItemMismatch {
224                    index,
225                    id: row.id.clone(),
226                });
227            }
228        }
229        for row in &self.families {
230            if let Some(family) = Family::from_id(&row.id) {
231                if row.designation != family.designation().as_str() {
232                    return Err(VerifyError::DesignationChanged {
233                        family: row.id.clone(),
234                    });
235                }
236            }
237        }
238        Ok(())
239    }
240}
241
242/// blake3 hex digest of a file's bytes (used to pin DISCLOSURE.md).
243pub fn blake3_hex(bytes: &[u8]) -> String {
244    let mut hex = String::with_capacity(64);
245    for byte in blake3::hash(bytes).as_bytes() {
246        let _ = write!(hex, "{byte:02x}");
247    }
248    hex
249}
250
251#[cfg(test)]
252#[allow(clippy::unwrap_used, clippy::expect_used)]
253mod tests {
254    use super::*;
255    use crate::gen::generate_all;
256
257    #[test]
258    fn manifest_roundtrip_json() {
259        let config = BenchConfig {
260            seeds_per_stratum: 2,
261            seed_base: 0x06,
262        };
263        let items = generate_all(&config);
264        let manifest = build(&config, &items, "0".repeat(64));
265        let parsed = Manifest::from_json(&manifest.to_json()).unwrap();
266        assert_eq!(manifest, parsed);
267    }
268
269    #[test]
270    fn verify_detects_regeneration_and_tamper() {
271        let config = BenchConfig {
272            seeds_per_stratum: 2,
273            seed_base: 0x06,
274        };
275        let items = generate_all(&config);
276        let manifest = build(&config, &items, "0".repeat(64));
277        manifest.verify(&config).unwrap();
278
279        let mut tampered = manifest.clone();
280        tampered.items[0].blake3 = "f".repeat(64);
281        assert!(matches!(
282            tampered.verify(&config),
283            Err(VerifyError::ItemMismatch { index: 0, .. })
284        ));
285    }
286
287    #[test]
288    fn gate_families_match_designation() {
289        let config = BenchConfig::default();
290        let items = generate_all(&config);
291        let manifest = build(&config, &items, "0".repeat(64));
292        assert_eq!(
293            manifest.gate_families(),
294            vec![Family::Temporal, Family::Syllogism]
295        );
296    }
297}