1use 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#[derive(Clone, Debug, Serialize)]
16pub struct Q42SectionReport {
17 pub name: String,
18 pub offset: u64,
19 pub length: u64,
20}
21
22#[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 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 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 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 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}