Skip to main content

qualia_core_db/q42/volume/
inspect.rs

1//! Truthful inspection of a unified Q42 volume. Cold path — may allocate.
2
3use std::io;
4use std::path::Path;
5
6use serde::Serialize;
7
8use super::super::{
9    Q42Volume, Q42VolumeHeader, FLAG_BLOCKS_LZ4, FLAG_FIELD_POSTINGS, FLAG_FIELD_RANGES,
10    FLAG_OBJECT_SORTED, FLAG_PAYLOAD_CATALOGUE, FLAG_PERMISSIVE_COMMONS, FLAG_SANCTUARY,
11    FLAG_VOLUME_ROOT, HEADER_SIZE,
12};
13use super::publication::{classify_q42_volume, PublicationIntent, Q42PublicationVerdict};
14/// One named byte interval inside the file.
15#[derive(Clone, Debug, Serialize)]
16pub struct Q42SectionReport {
17    pub name: String,
18    pub offset: u64,
19    pub length: u64,
20}
21
22/// Machine-readable inspect receipt. Empty lexicon and missing postings are
23/// named, not papered over.
24#[derive(Clone, Debug, Serialize)]
25pub struct Q42InspectReport {
26    pub path: String,
27    pub file_bytes: u64,
28    pub version: u16,
29    pub flags: u16,
30    pub flag_names: Vec<&'static str>,
31    pub block_count: u64,
32    pub block_size: u32,
33    pub quins_per_block: u32,
34    pub lexicon_bytes: u64,
35    pub lexicon_entries: Option<u64>,
36    /// True when this file stores no terms. Q42LEX is implemented; the artifact
37    /// was written hashed-only (or is a catalog root).
38    pub lexicon_has_no_terms: bool,
39    pub has_bidx: bool,
40    pub has_field_ranges: bool,
41    pub has_field_postings: bool,
42    pub has_payload_catalogue: bool,
43    pub payload_catalogue_bytes: u64,
44    pub payload_catalogue_entries: Option<u64>,
45    pub is_volume_root: bool,
46    pub publication_class: String,
47    pub publication_transport: String,
48    pub may_public_magnet: bool,
49    pub publication_reason: String,
50    pub sections: Vec<Q42SectionReport>,
51    pub honesty: Vec<String>,
52}
53
54impl Q42InspectReport {
55    /// Builds `Q42InspectReport` from `path`.
56    pub fn from_path(path: &Path) -> io::Result<Self> {
57        let file_bytes = std::fs::metadata(path)?.len();
58        let volume = Q42Volume::open(path)?;
59        Ok(Self::from_volume(path, file_bytes, &volume))
60    }
61
62    /// Builds `Q42InspectReport` from `volume`.
63    pub fn from_volume(path: &Path, file_bytes: u64, volume: &Q42Volume) -> Self {
64        let header = volume.header();
65        let flags = header.flags;
66        let lex_length = header.lex_length;
67        let version = header.version;
68        let block_count = header.block_count;
69        let block_size = header.block_size;
70        let quins_per_block = header.quins_per_block;
71        let lexicon_entries = volume.lex_view().ok().map(|lex| lex.entry_count() as u64);
72        let lexicon_has_no_terms = lexicon_entries == Some(0) || lex_length == 0;
73        let mut honesty = Vec::new();
74        let shared_lex_shards = volume
75            .volume_manifest()
76            .ok()
77            .flatten()
78            .map(|manifest| manifest.lexicon_segments.len() as u64)
79            .unwrap_or(0);
80        if lexicon_has_no_terms && block_count > 0 && shared_lex_shards == 0 {
81            honesty.push(
82                "This file has a valid Q42LEX with 0 terms. If it is a volume-set child, terms live in the root's lexicon shards; otherwise this artifact was written hashed-only."
83                    .into(),
84            );
85        }
86        if shared_lex_shards > 0 {
87            honesty.push(format!(
88                "Volume-set lexicon is sharded across {shared_lex_shards} child .q42 files named by this root. Local Q42LEX being empty here is expected."
89            ));
90        }
91        if flags & FLAG_FIELD_POSTINGS == 0 && block_count > 0 {
92            honesty.push(
93                "This file has no PIDX section. Newer writes include compact S/P/C postings; this artifact can be rewritten to add them."
94                    .into(),
95            );
96        }
97        if flags & FLAG_VOLUME_ROOT != 0 {
98            honesty.push(
99                "Volume root: the catalog is here; graph SuperBlocks are in the child .q42 segments it names."
100                    .into(),
101            );
102        }
103        if flags & FLAG_OBJECT_SORTED == 0 && block_count > 0 {
104            honesty.push(
105                "This file does not declare object sort order, so BIDX range pruning must not be trusted for it."
106                    .into(),
107            );
108        }
109        let publication = classify_q42_volume(volume, PublicationIntent::Default);
110        push_publication_notes(&mut honesty, &publication);
111        let pcat_range = super::payload_catalogue::header_payload_catalogue_range(header);
112        let has_payload_catalogue = pcat_range.is_some();
113        let payload_catalogue_bytes = pcat_range.map_or(0, |(_, len)| len);
114        let payload_catalogue_entries = if has_payload_catalogue {
115            volume
116                .read_payload_catalogue_entries()
117                .ok()
118                .map(|entries| entries.len() as u64)
119        } else {
120            None
121        };
122
123        Self {
124            path: path.display().to_string(),
125            file_bytes,
126            version,
127            flags,
128            flag_names: decode_flags(flags),
129            block_count,
130            block_size,
131            quins_per_block,
132            lexicon_bytes: lex_length,
133            lexicon_entries,
134            lexicon_has_no_terms,
135            has_bidx: header.bidx_length > 0,
136            has_field_ranges: flags & FLAG_FIELD_RANGES != 0,
137            has_field_postings: flags & FLAG_FIELD_POSTINGS != 0,
138            has_payload_catalogue,
139            payload_catalogue_bytes,
140            payload_catalogue_entries,
141            is_volume_root: flags & FLAG_VOLUME_ROOT != 0,
142            publication_class: publication.class.as_str().into(),
143            publication_transport: publication.transport.as_str().into(),
144            may_public_magnet: publication.may_emit_public_magnet,
145            publication_reason: publication.reason,
146            sections: collect_sections(header),
147            honesty,
148        }
149    }
150
151    /// Converts to `text`.
152    pub fn to_text(&self) -> String {
153        let mut out = String::new();
154        out.push_str(&format!("Q42  {}\n", self.path));
155        out.push_str(&format!("  file        {} bytes\n", self.file_bytes));
156        out.push_str(&format!(
157            "  version     {}   flags 0x{:04x} ({})\n",
158            self.version,
159            self.flags,
160            self.flag_names.join(" | ")
161        ));
162        out.push_str(&format!(
163            "  blocks      {} × {} bytes ({} Quins/block capacity)\n",
164            self.block_count, self.block_size, self.quins_per_block
165        ));
166        out.push_str(&format!(
167            "  lexicon     {} bytes, {} entries{}\n",
168            self.lexicon_bytes,
169            self.lexicon_entries
170                .map(|n| n.to_string())
171                .unwrap_or_else(|| "?".into()),
172            if self.lexicon_has_no_terms {
173                "  [0 terms in this file]"
174            } else {
175                ""
176            }
177        ));
178        out.push_str(&format!(
179            "  indexes     BIDX={}  FIDX={}  PIDX={}  PCAT={}  root={}\n",
180            yn(self.has_bidx),
181            yn(self.has_field_ranges),
182            yn(self.has_field_postings),
183            yn(self.has_payload_catalogue),
184            yn(self.is_volume_root)
185        ));
186        if self.has_payload_catalogue {
187            out.push_str(&format!(
188                "  pcat        {} bytes, {} entries\n",
189                self.payload_catalogue_bytes,
190                self.payload_catalogue_entries
191                    .map(|n| n.to_string())
192                    .unwrap_or_else(|| "?".into())
193            ));
194        }
195        out.push_str(&format!("  publication {}\n", self.publication_class));
196        out.push_str(&format!("  transport   {}\n", self.publication_transport));
197        out.push_str(&format!("  public magnet {}\n", yn(self.may_public_magnet)));
198        if !self.publication_reason.is_empty() {
199            out.push_str(&format!("  publish note {}\n", self.publication_reason));
200        }
201        out.push_str("  sections\n");
202        for section in &self.sections {
203            out.push_str(&format!(
204                "    {:<18} {:>12} + {}\n",
205                section.name, section.offset, section.length
206            ));
207        }
208        if !self.honesty.is_empty() {
209            out.push_str("  honesty\n");
210            for note in &self.honesty {
211                out.push_str(&format!("    - {note}\n"));
212            }
213        }
214        out
215    }
216}
217
218fn yn(value: bool) -> &'static str {
219    if value {
220        "yes"
221    } else {
222        "no"
223    }
224}
225
226fn push_publication_notes(honesty: &mut Vec<String>, publication: &Q42PublicationVerdict) {
227    match publication.class {
228        super::publication::Q42PublicationClass::UnmarkedLocal => honesty.push(
229            "Unmarked volume: no public magnet unless a human marks it as a Permissive Commons catalog (--commons or FLAG_PERMISSIVE_COMMONS). Personal and medical records stay local / SocialWebNet."
230                .into(),
231        ),
232        super::publication::Q42PublicationClass::Sanctuary => honesty.push(
233            "Sanctuary volume: public magnet, HTTP web-seed, and IPFS are denied. Transport is local or SocialWebNet (pairwise DID)."
234                .into(),
235        ),
236        super::publication::Q42PublicationClass::MixedFailClosed => honesty.push(
237            "Mixed volume: Commons and Selfhood Quins share one file. Split before any public hash is emitted."
238                .into(),
239        ),
240        super::publication::Q42PublicationClass::PermissiveCommons
241        | super::publication::Q42PublicationClass::CommonsGated => honesty.push(
242            "Permissive Commons transport (hash-addressed). This is not open-data: Selfhood stays out, and consume-side TrustGroup / billing gates still apply."
243                .into(),
244        ),
245    }
246}
247
248fn decode_flags(flags: u16) -> Vec<&'static str> {
249    let mut names = Vec::new();
250    if flags & FLAG_BLOCKS_LZ4 != 0 {
251        names.push("lz4");
252    }
253    if flags & FLAG_OBJECT_SORTED != 0 {
254        names.push("object-sorted");
255    }
256    if flags & FLAG_VOLUME_ROOT != 0 {
257        names.push("volume-root");
258    }
259    if flags & FLAG_FIELD_RANGES != 0 {
260        names.push("field-ranges");
261    }
262    if flags & FLAG_FIELD_POSTINGS != 0 {
263        names.push("field-postings");
264    }
265    if flags & FLAG_PERMISSIVE_COMMONS != 0 {
266        names.push("permissive-commons");
267    }
268    if flags & FLAG_SANCTUARY != 0 {
269        names.push("sanctuary");
270    }
271    if flags & FLAG_PAYLOAD_CATALOGUE != 0 {
272        names.push("payload-catalogue");
273    }
274    let known = FLAG_BLOCKS_LZ4
275        | FLAG_OBJECT_SORTED
276        | FLAG_VOLUME_ROOT
277        | FLAG_FIELD_RANGES
278        | FLAG_FIELD_POSTINGS
279        | FLAG_PERMISSIVE_COMMONS
280        | FLAG_SANCTUARY
281        | FLAG_PAYLOAD_CATALOGUE;
282    if flags & !known != 0 {
283        names.push("unknown");
284    }
285    if names.is_empty() {
286        names.push("none");
287    }
288    names
289}
290
291fn collect_sections(header: &Q42VolumeHeader) -> Vec<Q42SectionReport> {
292    let mut sections = vec![Q42SectionReport {
293        name: "header".into(),
294        offset: 0,
295        length: HEADER_SIZE as u64,
296    }];
297    let mut push = |name: &str, offset: u64, length: u64| {
298        if length > 0 {
299            sections.push(Q42SectionReport {
300                name: name.into(),
301                offset,
302                length,
303            });
304        }
305    };
306    push("lexicon", header.lex_offset, header.lex_length);
307    if let Some((offset, length)) = header.volume_manifest_range() {
308        push("volume-manifest", offset, length);
309    }
310    push("bidx", header.bidx_offset, header.bidx_length);
311    if let Some((offset, length)) = header.field_range_index_range() {
312        push("field-ranges", offset, length);
313    }
314    if let Some((offset, length)) = header.field_postings_range() {
315        push("field-postings", offset, length);
316    }
317    push(
318        "block-directory",
319        header.block_dir_offset,
320        header.block_dir_length,
321    );
322    push("block-data", header.data_offset, header.data_length);
323    push(
324        "temporal-index",
325        header.temporal_index_offset,
326        header.temporal_index_length,
327    );
328    push("merkle-dag", header.dag_root_offset, header.dag_root_length);
329    if let Some((offset, length)) = super::payload_catalogue::header_payload_catalogue_range(header)
330    {
331        push("payload-catalogue", offset, length);
332    }
333    sections
334}
335
336#[cfg(test)]
337mod tests {
338    use super::*;
339    use crate::q42_volume::{write_unified_volume, StreamingQ42VolumeWriter};
340    use crate::NQuin;
341    use std::collections::HashMap;
342
343    #[test]
344    fn inspect_names_empty_lex_and_streaming_postings() {
345        let file = tempfile::NamedTempFile::new().unwrap();
346        write_unified_volume(
347            file.path(),
348            &HashMap::new(),
349            &[(3, 3)],
350            &[vec![NQuin {
351                subject: 1,
352                predicate: 2,
353                object: 3,
354                context: 0,
355                metadata: 0,
356                parity: 0,
357            }]],
358        )
359        .unwrap();
360        let report = Q42InspectReport::from_path(file.path()).unwrap();
361        assert!(report.lexicon_has_no_terms);
362        assert!(report.honesty.iter().any(|n| n.contains("0 terms")));
363        assert_eq!(report.publication_class, "unmarked-local");
364        assert!(!report.may_public_magnet);
365
366        let streamed = tempfile::NamedTempFile::new().unwrap();
367        let mut lex = HashMap::new();
368        lex.insert(1, "s".into());
369        lex.insert(2, "p".into());
370        lex.insert(3, "o".into());
371        let mut writer = StreamingQ42VolumeWriter::new(&lex).unwrap();
372        writer
373            .push_block(
374                0,
375                &[NQuin {
376                    subject: 1,
377                    predicate: 2,
378                    object: 3,
379                    context: 0,
380                    metadata: 0,
381                    parity: 0,
382                }],
383            )
384            .unwrap();
385        writer.finish(streamed.path()).unwrap();
386        let good = Q42InspectReport::from_path(streamed.path()).unwrap();
387        assert!(good.has_field_postings);
388        assert!(!good.lexicon_has_no_terms);
389    }
390}