Skip to main content

qualia_client_core/wellfair/api/
library.rs

1//! Hypermedia asset library: ingest, search, CML, COF
2
3use super::*;
4
5impl WebizenHostApi {
6    // --- Hypermedia asset library: ingest a document → make it searchable by meaning ---
7
8    fn library(&self) -> Result<super::super::hypermedia_store::HypermediaStore, String> {
9        super::super::hypermedia_store::HypermediaStore::open(&self.storage_root)
10            .map_err(|e| e.to_string())
11    }
12
13    /// **Ingest a text document** into the library: derive its topics + searchable text, bind them into a
14    /// hypermedia container, persist it (findable by meaning), and — if `guardian_did` is set (the principal
15    /// is under a guardianship relation) and a flag is raised — notify the guardian **and record it in the
16    /// tamper-evident ledger**. Returns a summary (topics, flags, any guardian notifications).
17    pub fn ingest_document(
18        &self,
19        uri: &str,
20        media_type: &str,
21        text: &str,
22        guardian_did: Option<String>,
23    ) -> Result<serde_json::Value, String> {
24        self.ingest_bytes(
25            uri,
26            media_type,
27            text.as_bytes(),
28            text,
29            &ManualFacets::default(),
30            guardian_did,
31        )
32    }
33
34    /// Ingest a text document **with person-authored facets** — an optional date (→ timeline), place
35    /// (→ map), project and purpose the person chooses to attach. The document's derived topics still come
36    /// from its content; these facets are added on top (the person authoring meaning, not being defined).
37    pub fn ingest_document_annotated(
38        &self,
39        uri: &str,
40        media_type: &str,
41        text: &str,
42        manual: &ManualFacets,
43        guardian_did: Option<String>,
44    ) -> Result<serde_json::Value, String> {
45        self.ingest_bytes(uri, media_type, text.as_bytes(), text, manual, guardian_did)
46    }
47
48    /// **Ingest any asset bytes** (a document, a **photo**, an audio clip) into the library. The processor
49    /// registered for `media_type` derives searchability — a text doc → topics; a **JPEG/PNG → its EXIF
50    /// capture time (timeline) + GPS place (map)**; a WAV → duration + dominant frequency — and it all folds
51    /// into the container so the original is findable by meaning. `excerpt_source` is a short human string for
52    /// the results list (the text for a doc; a caption/filename for binary). Guardianship + ledger hook as
53    /// [`Self::ingest_document`].
54    pub fn ingest_bytes(
55        &self,
56        uri: &str,
57        media_type: &str,
58        bytes: &[u8],
59        excerpt_source: &str,
60        manual: &ManualFacets,
61        guardian_did: Option<String>,
62    ) -> Result<serde_json::Value, String> {
63        use qualia_core_db::hypermedia::processors::processor_for;
64        use qualia_core_db::hypermedia::{
65            content_digest, descriptors_to_nquins, ingest_with, Descriptors, FlagSeverity, Place,
66        };
67
68        let proc = processor_for(media_type)
69            .ok_or_else(|| format!("no ingest processor for media type '{media_type}'"))?;
70        let digest = content_digest(bytes);
71        let out = proc.process(uri, bytes, media_type);
72        let mut r = ingest_with(proc.as_ref(), uri, media_type, digest, bytes);
73        let now = Self::now_unix();
74        let primary_subject = r.container.primary.subject();
75
76        // Merge the person-authored facets as additional descriptor edges on the primary asset. A processor's
77        // own derivation (a photo's EXIF) takes precedence for its fields; manual facets fill / extend.
78        let manual_place = match (manual.lat, manual.lon) {
79            (Some(lat), Some(lon)) => Some(Place {
80                label: manual
81                    .place_label
82                    .clone()
83                    .unwrap_or_else(|| format!("{lat:.5},{lon:.5}")),
84                lat,
85                lon,
86            }),
87            _ => None,
88        };
89        if !manual.is_empty() {
90            let extra = Descriptors {
91                occurred_at: manual
92                    .occurred_at
93                    .filter(|_| out.descriptors.occurred_at.is_none()),
94                place: if out.descriptors.place.is_none() {
95                    manual_place.clone()
96                } else {
97                    None
98                },
99                projects: manual.projects.clone(),
100                purposes: manual.purposes.clone(),
101                ..Default::default()
102            };
103            let (eq, _lex) = descriptors_to_nquins(primary_subject, &extra);
104            r.quins.extend(eq);
105        }
106
107        let flags: Vec<super::super::hypermedia_store::LibraryFlag> = out
108            .flags
109            .iter()
110            .map(|f| super::super::hypermedia_store::LibraryFlag {
111                kind: f.kind.clone(),
112                severity_level: f.severity.level(),
113                detail: f.detail.clone(),
114            })
115            .collect();
116
117        // Effective facets for the entry's display fields: processor-derived first, else the person's.
118        let eff_occurred_at = out.descriptors.occurred_at.or(manual.occurred_at);
119        let eff_place = out.descriptors.place.clone().or(manual_place);
120        let (lat, lon) = eff_place
121            .as_ref()
122            .map(|p| (Some(p.lat), Some(p.lon)))
123            .unwrap_or((None, None));
124        let mut projects = out.descriptors.projects.clone();
125        projects.extend(manual.projects.iter().cloned());
126
127        let purposes = manual.purposes.clone();
128        let sensitivity = super::super::hypermedia_store::normalize_sensitivity(
129            manual.sensitivity.as_deref().unwrap_or("public"),
130        );
131        let commons = super::super::hypermedia_store::CommonsVisibility::parse(
132            manual.commons_visibility.as_deref().unwrap_or("none"),
133        );
134        // Rust-native CML context graph for text-like assets (TEXT→CONCEPT→LOGIC, cml:Proposed).
135        let mut cml_topics = Vec::new();
136        let mut cml_purposes = purposes.clone();
137        let mut cml_signals = Vec::new();
138        let mut cml_concept_count = 0u32;
139        let mut cml_n3 = String::new();
140        let mut cml_quins = Vec::new();
141        if media_type.starts_with("text/")
142            || media_type.contains("json")
143            || media_type.contains("markdown")
144        {
145            let text = String::from_utf8_lossy(bytes);
146            let units = super::super::cml_context::units_from_headings(&text);
147            let g = super::super::cml_context::build_document_context(uri, excerpt_source, &units);
148            cml_topics = g.topics.clone();
149            for p in &g.purposes {
150                if !cml_purposes.iter().any(|x| x == p) {
151                    cml_purposes.push(p.clone());
152                }
153            }
154            cml_signals = g.signal_tags.clone();
155            cml_concept_count = g.concepts.len() as u32;
156            cml_n3 = if g.n3.len() > 48_000 {
157                format!("{}…\n# [cml_n3 truncated]", &g.n3[..48_000])
158            } else {
159                g.n3
160            };
161            cml_quins = g.quins;
162        }
163
164        let mut topics = out.descriptors.topics.clone();
165        for t in cml_topics {
166            if !topics.iter().any(|x| x == &t) {
167                topics.push(t);
168            }
169        }
170
171        let mut all_quins = r.quins;
172        all_quins.extend(cml_quins);
173
174        let mut entry = super::super::hypermedia_store::LibraryEntry {
175            asset_uri: uri.to_string(),
176            primary_subject,
177            media_type: media_type.to_string(),
178            quins: all_quins,
179            topics,
180            projects,
181            purposes: cml_purposes,
182            place: eff_place.as_ref().map(|p| p.label.clone()),
183            occurred_at: eff_occurred_at,
184            lat,
185            lon,
186            flags: flags.clone(),
187            ingested_unix: now,
188            excerpt: excerpt_source.chars().take(160).collect(),
189            sensitivity: sensitivity.clone(),
190            section: manual.section.clone().unwrap_or_else(|| "personal".into()),
191            commons_visibility: commons,
192            cml_signals,
193            cml_concept_count,
194            cml_n3,
195            cof_html: String::new(),
196            cof_segment_count: 0,
197            cof_segment_index: 0,
198            cof_profile: String::new(),
199        };
200
201        // COF HTML+RDFa package (token-bounded segments) for text assets.
202        let mut cof_segment_count = 0u32;
203        let mut cof_profile = String::new();
204        let mut cof_body_segments: Vec<super::super::cml_context::CofSegment> = Vec::new();
205        if media_type.starts_with("text/") {
206            let text = String::from_utf8_lossy(bytes);
207            let units = super::super::cml_context::units_from_headings(&text);
208            let pkg = super::super::cml_context::build_cof_package(
209                uri,
210                excerpt_source,
211                &units,
212                super::super::cml_context::DEFAULT_SEGMENT_MAX_CHARS,
213                super::super::cml_context::CofStyle::AgentLean,
214            );
215            cof_segment_count = pkg.segments.len() as u32;
216            cof_profile = pkg.profile.clone();
217            entry.cof_segment_count = cof_segment_count;
218            entry.cof_profile = cof_profile.clone();
219            if let Some(index_seg) = pkg.segments.iter().find(|s| s.is_index) {
220                entry.cof_html = index_seg.html.clone();
221                entry.cof_segment_index = 0;
222            } else if let Some(first) = pkg.segments.first() {
223                entry.cof_html = first.html.clone();
224                entry.cof_segment_index = first.index;
225            }
226            cof_body_segments = pkg.segments.into_iter().filter(|s| !s.is_index).collect();
227        }
228
229        entry.recompute_section();
230        // High sensitivity can never be commons.
231        if entry.is_secret() {
232            entry.commons_visibility = super::super::hypermedia_store::CommonsVisibility::None;
233        }
234        let section = entry.section.clone();
235        let commons_visibility = entry.commons_visibility;
236        let entry_topics = entry.topics.clone();
237        let entry_purposes = entry.purposes.clone();
238        let store = self.library()?;
239        store.add(entry).map_err(|e| e.to_string())?;
240
241        // Sibling COF body segments — load only the budget needed for a turn.
242        for seg in &cof_body_segments {
243            let seg_uri = format!("{uri}#cof-seg-{}", seg.index);
244            let mut se = super::super::hypermedia_store::LibraryEntry {
245                asset_uri: seg_uri.clone(),
246                primary_subject: qualia_core_db::hypermedia::fnv60(seg_uri.as_bytes()),
247                media_type: super::super::cml_context::MEDIA_TYPE_COF.into(),
248                quins: Vec::new(),
249                topics: entry_topics.clone(),
250                projects: Vec::new(),
251                purposes: entry_purposes.clone(),
252                place: None,
253                occurred_at: None,
254                lat: None,
255                lon: None,
256                flags: Vec::new(),
257                ingested_unix: now,
258                excerpt: format!(
259                    "COF segment {}/{} · ~{} tokens · units: {}",
260                    seg.index + 1,
261                    seg.total,
262                    seg.approx_tokens,
263                    seg.unit_frags.join(", ")
264                ),
265                sensitivity: sensitivity.clone(),
266                section: section.clone(),
267                commons_visibility,
268                cml_signals: Vec::new(),
269                cml_concept_count: seg.unit_frags.len() as u32,
270                cml_n3: String::new(),
271                cof_html: seg.html.clone(),
272                cof_segment_count,
273                cof_segment_index: seg.index,
274                cof_profile: cof_profile.clone(),
275            };
276            se.recompute_section();
277            store.add(se).map_err(|e| e.to_string())?;
278        }
279
280        // Guardianship hook: a flagged ingest under a guardianship relation notifies + records.
281        let mut notified = Vec::new();
282        if let Some(g) = &guardian_did {
283            if !out.flags.is_empty() {
284                let ns = super::super::ingest_guardian::guardian_notifications(
285                    &out.flags,
286                    uri,
287                    g,
288                    &self.owner_did,
289                    FlagSeverity::Notice,
290                    now,
291                );
292                self.record_guardian_notifications(&ns)?;
293                notified = ns;
294            }
295        }
296        Ok(serde_json::json!({
297            "asset_uri": uri,
298            "topics": entry_topics,
299            "occurred_at": eff_occurred_at,
300            "place": eff_place.as_ref().map(|p| &p.label),
301            "lat": lat,
302            "lon": lon,
303            "flags": flags,
304            "guardian_notifications": notified,
305            "section": section,
306            "sensitivity": sensitivity,
307            "commons_visibility": commons_visibility,
308            "purposes": entry_purposes,
309            "cml_concept_count": cml_concept_count,
310            "cof_segment_count": cof_segment_count,
311            "cof_profile": cof_profile,
312        }))
313    }
314
315    /// **Ingest a photo/audio file from hex-encoded bytes** — the boundary form for the desktop, which reads a
316    /// picked file and passes its bytes as hex (a JPEG is not valid utf-8, so it cannot come through the text
317    /// path). A photo's EXIF capture-time + GPS auto-populate the timeline + map. `caption` is the short
318    /// display string. Same derive + persist + guardian hook as [`Self::ingest_bytes`].
319    pub fn ingest_file_hex(
320        &self,
321        uri: &str,
322        media_type: &str,
323        bytes_hex: &str,
324        caption: &str,
325        guardian_did: Option<String>,
326    ) -> Result<serde_json::Value, String> {
327        let bytes = decode_hex(bytes_hex).map_err(|e| format!("bad hex: {e}"))?;
328        self.ingest_bytes(
329            uri,
330            media_type,
331            &bytes,
332            caption,
333            &ManualFacets::default(),
334            guardian_did,
335        )
336    }
337
338    /// Search the library by facet (`topic` | `depicts` | `place` | `project` | `purpose`). Returns per-entry
339    /// summaries (not the raw quins).
340    pub fn search_library(
341        &self,
342        facet: &str,
343        value: &str,
344    ) -> Result<Vec<serde_json::Value>, String> {
345        let entries = self
346            .library()?
347            .search(facet, value)
348            .map_err(|e| e.to_string())?;
349        Ok(entries.iter().map(library_summary).collect())
350    }
351
352    /// The **timeline** query — entries whose event instant falls within `[start, end]` (unix seconds).
353    pub fn search_library_time(
354        &self,
355        start: i64,
356        end: i64,
357    ) -> Result<Vec<serde_json::Value>, String> {
358        let entries = self
359            .library()?
360            .search_time_range(start, end)
361            .map_err(|e| e.to_string())?;
362        Ok(entries.iter().map(library_summary).collect())
363    }
364
365    /// Everything in the library (newest first), as summaries.
366    /// Optional `section` filters to secret | wellfair | personal | work | commons.
367    pub fn list_library(&self) -> Result<Vec<serde_json::Value>, String> {
368        self.list_library_section(None)
369    }
370
371    /// Lists a library section.
372    pub fn list_library_section(
373        &self,
374        section: Option<&str>,
375    ) -> Result<Vec<serde_json::Value>, String> {
376        let store = self.library()?;
377        let entries = match section {
378            Some(s) if !s.is_empty() && s != "all" => store
379                .by_section(super::super::hypermedia_store::LibrarySection::parse(s))
380                .map_err(|e| e.to_string())?,
381            _ => store.all().map_err(|e| e.to_string())?,
382        };
383        Ok(entries.iter().map(library_summary).collect())
384    }
385
386    /// Free-text search over uri / excerpt / topics / projects / place.
387    pub fn search_library_text(&self, query: &str) -> Result<Vec<serde_json::Value>, String> {
388        let entries = self
389            .library()?
390            .search_text(query)
391            .map_err(|e| e.to_string())?;
392        Ok(entries.iter().map(library_summary).collect())
393    }
394
395    /// Multi-facet library query with sort. `filter_json` is a [`FacetFilter`] object;
396    /// `sort` is newest|oldest|title_asc|title_desc|media_type|category.
397    pub fn query_library_faceted(
398        &self,
399        filter_json: &str,
400        sort: &str,
401    ) -> Result<serde_json::Value, String> {
402        let filter: super::super::hypermedia_store::FacetFilter = if filter_json.trim().is_empty() {
403            Default::default()
404        } else {
405            serde_json::from_str(filter_json).map_err(|e| format!("facet filter json: {e}"))?
406        };
407        let sort = super::super::hypermedia_store::LibrarySort::parse(sort);
408        let store = self.library()?;
409        let entries = store
410            .query_faceted(&filter, sort)
411            .map_err(|e| e.to_string())?;
412        let counts = store.facet_counts(&filter).map_err(|e| e.to_string())?;
413        Ok(serde_json::json!({
414            "entries": entries.iter().map(library_summary).collect::<Vec<_>>(),
415            "total": entries.len(),
416            "sort": sort.as_str(),
417            "filter": filter,
418            "facets": counts,
419        }))
420    }
421
422    /// Facet value counts for chip UI (optionally narrowed by the same filter JSON).
423    pub fn library_facet_counts(&self, filter_json: &str) -> Result<serde_json::Value, String> {
424        let filter: super::super::hypermedia_store::FacetFilter = if filter_json.trim().is_empty() {
425            Default::default()
426        } else {
427            serde_json::from_str(filter_json).map_err(|e| format!("facet filter json: {e}"))?
428        };
429        let counts = self
430            .library()?
431            .facet_counts(&filter)
432            .map_err(|e| e.to_string())?;
433        Ok(serde_json::to_value(counts).map_err(|e| e.to_string())?)
434    }
435
436    /// Seed the early studio academic QApp inventory into Library → Software.
437    /// Idempotent; returns add/update counts.
438    pub fn seed_studio_qapps_library(&self) -> Result<serde_json::Value, String> {
439        let store = self.library()?;
440        let report = super::super::qapp_catalog::seed_studio_qapps_into_library(&store)
441            .map_err(|e| e.to_string())?;
442        Ok(serde_json::to_value(report).map_err(|e| e.to_string())?)
443    }
444
445    /// Seed perception models + ontology catalogue rows into Library → Software.
446    /// Also ensures seed weight files under `{storage}/models/`.
447    pub fn seed_perception_library(&self) -> Result<serde_json::Value, String> {
448        let store = self.library()?;
449        let root = self.storage_root();
450        let report = super::super::perception_catalog::seed_perception_into_library(&store, root)?;
451        Ok(serde_json::to_value(report).map_err(|e| e.to_string())?)
452    }
453
454    /// Native legislation ingest (structure parse, no Ollama): PDF bytes → Work shelf
455    /// entries for the instrument and every Part/Section/Subsection with full body text.
456    pub fn ingest_legislation_pdf_hex(
457        &self,
458        hex_bytes: &str,
459        register_id: Option<&str>,
460        jurisdiction: Option<&str>,
461        title_hint: Option<&str>,
462    ) -> Result<serde_json::Value, String> {
463        let bytes = decode_hex(hex_bytes)?;
464        let store = self.library()?;
465        let report = super::super::legislation_ingest::ingest_legislation_pdf_bytes(
466            &store,
467            &bytes,
468            register_id,
469            jurisdiction.unwrap_or("AU"),
470            title_hint,
471        )?;
472        Ok(serde_json::to_value(report).map_err(|e| e.to_string())?)
473    }
474
475    /// Native legislation ingest from plain text (already extracted PDF text or HTML).
476    pub fn ingest_legislation_text(
477        &self,
478        text: &str,
479        register_id: Option<&str>,
480        jurisdiction: Option<&str>,
481        title_hint: Option<&str>,
482    ) -> Result<serde_json::Value, String> {
483        let store = self.library()?;
484        let report = super::super::legislation_ingest::ingest_legislation_text(
485            &store,
486            text,
487            register_id,
488            jurisdiction.unwrap_or("AU"),
489            title_hint,
490        )?;
491        Ok(serde_json::to_value(report).map_err(|e| e.to_string())?)
492    }
493
494    /// Build a Rust-native CML context graph for arbitrary text (no Python).
495    /// Returns concepts, signal tags, N3, and deontic/privacy counts — does not persist.
496    pub fn build_cml_context_graph(
497        &self,
498        uri: &str,
499        title: &str,
500        text: &str,
501    ) -> Result<serde_json::Value, String> {
502        let units = super::super::cml_context::units_from_headings(text);
503        let g = super::super::cml_context::build_document_context(uri, title, &units);
504        Ok(serde_json::json!({
505            "document_uri": g.document_uri,
506            "title": g.title,
507            "concepts": g.concepts,
508            "signal_tags": g.signal_tags,
509            "topics": g.topics,
510            "purposes": g.purposes,
511            "deontic_norms": g.deontic_norms,
512            "privacy_hits": g.privacy_hits,
513            "rights_hits": g.rights_hits,
514            "quin_count": g.quins.len(),
515            "n3": g.n3,
516            "curation": "cml:Proposed",
517            "engine": "qualia-client-core::wellfair::cml_context",
518        }))
519    }
520
521    /// Build a **COF HTML+RDFa** package (token-bounded segments) without persisting.
522    /// `max_chars` defaults to 24000 when zero/None.
523    pub fn build_cof_html_package(
524        &self,
525        uri: &str,
526        title: &str,
527        text: &str,
528        max_chars: Option<usize>,
529        dual_surface: bool,
530    ) -> Result<serde_json::Value, String> {
531        let units = super::super::cml_context::units_from_headings(text);
532        let style = if dual_surface {
533            super::super::cml_context::CofStyle::DualSurface
534        } else {
535            super::super::cml_context::CofStyle::AgentLean
536        };
537        let max = max_chars
538            .filter(|n| *n >= 2000)
539            .unwrap_or(super::super::cml_context::DEFAULT_SEGMENT_MAX_CHARS);
540        let pkg = super::super::cml_context::build_cof_package(uri, title, &units, max, style);
541        Ok(serde_json::json!({
542            "document_uri": pkg.document_uri,
543            "title": pkg.title,
544            "profile": pkg.profile,
545            "segment_max_chars": pkg.segment_max_chars,
546            "total_chars": pkg.total_chars,
547            "total_approx_tokens": pkg.total_approx_tokens,
548            "segments": pkg.segments.iter().map(|s| serde_json::json!({
549                "index": s.index,
550                "total": s.total,
551                "id": s.id,
552                "title": s.title,
553                "char_count": s.char_count,
554                "approx_tokens": s.approx_tokens,
555                "unit_frags": s.unit_frags,
556                "is_index": s.is_index,
557                "html": s.html,
558            })).collect::<Vec<_>>(),
559            "how": [
560                "Load segment 0 (index) for a token-cheap map of the instrument.",
561                "Load only the body segment(s) whose unit_frags match the query.",
562                "RDFa attributes carry CML edges; do not strip typeof/property/resource.",
563            ],
564        }))
565    }
566
567    /// Re-run CML context enrichment on an existing library entry's excerpt/text fields.
568    pub fn enrich_library_entry_cml(&self, asset_uri: &str) -> Result<serde_json::Value, String> {
569        let store = self.library()?;
570        let mut entries = store.load().map_err(|e| e.to_string())?;
571        let e = entries
572            .iter_mut()
573            .find(|x| x.asset_uri == asset_uri)
574            .ok_or_else(|| format!("unknown asset '{asset_uri}'"))?;
575        let text = if e.excerpt.len() > 40 {
576            e.excerpt.clone()
577        } else {
578            return Err("entry has no usable text in excerpt to enrich".into());
579        };
580        let units = super::super::cml_context::units_from_headings(&text);
581        let g =
582            super::super::cml_context::build_document_context(&e.asset_uri, &e.asset_uri, &units);
583        for t in &g.topics {
584            if !e.topics.iter().any(|x| x == t) {
585                e.topics.push(t.clone());
586            }
587        }
588        for p in &g.purposes {
589            if !e.purposes.iter().any(|x| x == p) {
590                e.purposes.push(p.clone());
591            }
592        }
593        e.cml_signals = g.signal_tags.clone();
594        e.cml_concept_count = g.concepts.len() as u32;
595        e.cml_n3 = if g.n3.len() > 48_000 {
596            format!("{}…", &g.n3[..48_000])
597        } else {
598            g.n3.clone()
599        };
600        e.quins.extend(g.quins);
601        e.recompute_section();
602        let out = library_summary(e);
603        store.replace_all(&entries).map_err(|e| e.to_string())?;
604        Ok(out)
605    }
606
607    /// List catalogue categories (for Software shelf UI without seeding first).
608    pub fn list_qapp_catalog_categories(&self) -> Result<serde_json::Value, String> {
609        let cats: Vec<serde_json::Value> = super::super::qapp_catalog::catalogue_categories()
610            .into_iter()
611            .map(|slug| {
612                serde_json::json!({
613                    "slug": slug,
614                    "label": super::super::qapp_catalog::category_label(slug),
615                    "count": super::super::qapp_catalog::STUDIO_QAPP_CATALOG
616                        .iter()
617                        .filter(|e| e.category == slug)
618                        .count(),
619                })
620            })
621            .collect();
622        Ok(serde_json::json!({
623            "total": super::super::qapp_catalog::STUDIO_QAPP_CATALOG.len(),
624            "categories": cats,
625        }))
626    }
627
628    /// Aggregate library stats for the UI header (includes section counts).
629    pub fn library_stats(&self) -> Result<serde_json::Value, String> {
630        let store = self.library()?;
631        let s = store.stats().map_err(|e| e.to_string())?;
632        let sections = store.section_counts().map_err(|e| e.to_string())?;
633        Ok(serde_json::json!({
634            "total": s.total,
635            "with_date": s.with_date,
636            "with_place": s.with_place,
637            "flags": s.flags,
638            "quins": s.quins,
639            "topics": s.topics,
640            "projects": s.projects,
641            "sections": sections,
642        }))
643    }
644
645    /// Set commons / peer visibility (refuses Secret).
646    pub fn set_library_commons_visibility(
647        &self,
648        asset_uri: &str,
649        visibility: &str,
650    ) -> Result<serde_json::Value, String> {
651        let vis = super::super::hypermedia_store::CommonsVisibility::parse(visibility);
652        let e = self
653            .library()?
654            .set_commons_visibility(asset_uri, vis)
655            .map_err(|e| e.to_string())?;
656        Ok(library_summary(&e))
657    }
658
659    /// Build a **permissive commons share card** for social networking (no secret payloads).
660    /// Returns metadata peers can list; raw content stays on-device until a fuller mesh transfer.
661    pub fn library_commons_share_card(&self, asset_uri: &str) -> Result<serde_json::Value, String> {
662        let entries = self.library()?.all().map_err(|e| e.to_string())?;
663        let e = entries
664            .iter()
665            .find(|x| x.asset_uri == asset_uri)
666            .ok_or_else(|| format!("unknown asset '{asset_uri}'"))?;
667        if e.is_secret() {
668            return Err("secret items cannot be offered to the commons".into());
669        }
670        if e.commons_visibility == super::super::hypermedia_store::CommonsVisibility::None {
671            return Err("set commons visibility to peers or commons before sharing".into());
672        }
673        Ok(serde_json::json!({
674            "qualia_library_commons": "1",
675            "asset_uri": e.asset_uri,
676            "media_type": e.media_type,
677            "topics": e.topics,
678            "projects": e.projects,
679            "purposes": e.purposes,
680            "excerpt": e.excerpt,
681            "section": e.section,
682            "commons_visibility": e.commons_visibility,
683            "how": [
684                "Host: Keep → Library → Commons → Share to peers.",
685                "Peer: accept via Talk social connection; request content over mesh when available.",
686            ],
687            "note": "Card is metadata only — not the secret body. High-sensitivity items never appear here.",
688        }))
689    }
690
691    /// Remove one library entry by asset URI.
692    pub fn remove_library_entry(&self, asset_uri: &str) -> Result<serde_json::Value, String> {
693        let ok = self
694            .library()?
695            .remove(asset_uri)
696            .map_err(|e| e.to_string())?;
697        Ok(serde_json::json!({ "removed": ok, "asset_uri": asset_uri }))
698    }
699
700    /// Export the full hypermedia graph mass (quin count + optional dump for inject).
701    /// Returns `{ quin_count, entries }` — the live graph inject seam for daemon/MCP.
702    pub fn export_library_graph(&self) -> Result<serde_json::Value, String> {
703        let store = self.library()?;
704        let entries = store.all().map_err(|e| e.to_string())?;
705        let quins = store.all_quins().map_err(|e| e.to_string())?;
706        Ok(serde_json::json!({
707            "quin_count": quins.len(),
708            "entry_count": entries.len(),
709            "message": "Hypermedia edge-graph ready for daemon /query inject. Quins are the searchable semantic form.",
710            "sample_subjects": entries.iter().take(8).map(|e| e.primary_subject).collect::<Vec<_>>(),
711        }))
712    }
713}
714
715// ── Vault-free path helpers (AppState storage_path; no Sanctuary HostApi) ─────
716//
717// The hypermedia shelf is a JSON index under `{storage}/wellfair/`. Reading and
718// seeding catalogue rows must work **before** the person unlocks Sanctuary —
719// otherwise Library looks permanently empty after a perception seed.
720
721use super::super::hypermedia_store::{FacetFilter, HypermediaStore, LibrarySection, LibrarySort};
722use super::library_summary;
723use std::path::Path;
724
725fn open_store(storage_root: &Path) -> Result<HypermediaStore, String> {
726    HypermediaStore::open(storage_root).map_err(|e| e.to_string())
727}
728
729/// List library entries at `storage_root` (newest-first store order). Optional section filter.
730pub fn list_library_section_at(
731    storage_root: &Path,
732    section: Option<&str>,
733) -> Result<Vec<serde_json::Value>, String> {
734    let store = open_store(storage_root)?;
735    let entries = match section {
736        Some(s) if !s.is_empty() && s != "all" => store
737            .by_section(LibrarySection::parse(s))
738            .map_err(|e| e.to_string())?,
739        _ => store.all().map_err(|e| e.to_string())?,
740    };
741    Ok(entries.iter().map(library_summary).collect())
742}
743
744/// Faceted query + facet counts at `storage_root` (same JSON shape as HostApi).
745pub fn query_library_faceted_at(
746    storage_root: &Path,
747    filter_json: &str,
748    sort: &str,
749) -> Result<serde_json::Value, String> {
750    let filter: FacetFilter = if filter_json.trim().is_empty() {
751        Default::default()
752    } else {
753        serde_json::from_str(filter_json).map_err(|e| format!("facet filter json: {e}"))?
754    };
755    let sort = LibrarySort::parse(sort);
756    let store = open_store(storage_root)?;
757    let entries = store
758        .query_faceted(&filter, sort)
759        .map_err(|e| e.to_string())?;
760    let counts = store.facet_counts(&filter).map_err(|e| e.to_string())?;
761    Ok(serde_json::json!({
762        "entries": entries.iter().map(library_summary).collect::<Vec<_>>(),
763        "total": entries.len(),
764        "sort": sort.as_str(),
765        "filter": filter,
766        "facets": counts,
767    }))
768}
769
770/// Aggregate stats at `storage_root` (header chips + section counts).
771pub fn library_stats_at(storage_root: &Path) -> Result<serde_json::Value, String> {
772    let store = open_store(storage_root)?;
773    let s = store.stats().map_err(|e| e.to_string())?;
774    let sections = store.section_counts().map_err(|e| e.to_string())?;
775    Ok(serde_json::json!({
776        "total": s.total,
777        "with_date": s.with_date,
778        "with_place": s.with_place,
779        "flags": s.flags,
780        "quins": s.quins,
781        "topics": s.topics,
782        "projects": s.projects,
783        "sections": sections,
784    }))
785}
786
787/// Facet search (`topic` | `depicts` | `place` | `project` | `purpose`) without vault.
788pub fn search_library_at(
789    storage_root: &Path,
790    facet: &str,
791    value: &str,
792) -> Result<Vec<serde_json::Value>, String> {
793    let store = open_store(storage_root)?;
794    let entries = store.search(facet, value).map_err(|e| e.to_string())?;
795    Ok(entries.iter().map(library_summary).collect())
796}
797
798/// Free-text search without vault.
799pub fn search_library_text_at(
800    storage_root: &Path,
801    query: &str,
802) -> Result<Vec<serde_json::Value>, String> {
803    let store = open_store(storage_root)?;
804    let entries = store.search_text(query).map_err(|e| e.to_string())?;
805    Ok(entries.iter().map(library_summary).collect())
806}
807
808/// Timeline range search without vault.
809pub fn search_library_time_at(
810    storage_root: &Path,
811    start: i64,
812    end: i64,
813) -> Result<Vec<serde_json::Value>, String> {
814    let store = open_store(storage_root)?;
815    let entries = store
816        .search_time_range(start, end)
817        .map_err(|e| e.to_string())?;
818    Ok(entries.iter().map(library_summary).collect())
819}
820
821#[cfg(test)]
822mod vault_free_tests {
823    use super::*;
824    use crate::wellfair::hypermedia_store::{CommonsVisibility, LibraryEntry};
825
826    #[test]
827    fn vault_free_list_and_stats_see_seeded_rows() {
828        let dir = tempfile::tempdir().unwrap();
829        let store = HypermediaStore::open(dir.path()).unwrap();
830        let entry = LibraryEntry {
831            asset_uri: "model://test-vision".into(),
832            primary_subject: 42,
833            media_type: "application/x-webizen-model".into(),
834            quins: vec![],
835            topics: vec!["perception".into(), "computer_vision".into()],
836            projects: vec!["perception:vision".into()],
837            purposes: vec!["model".into()],
838            place: None,
839            occurred_at: None,
840            lat: None,
841            lon: None,
842            flags: vec![],
843            ingested_unix: 1_700_000_000,
844            excerpt: "test model row".into(),
845            sensitivity: "public".into(),
846            section: "software".into(),
847            commons_visibility: CommonsVisibility::None,
848            cml_signals: vec![],
849            cml_concept_count: 0,
850            cml_n3: String::new(),
851            cof_html: String::new(),
852            cof_segment_count: 0,
853            cof_segment_index: 0,
854            cof_profile: String::new(),
855        };
856        store.add(entry).unwrap();
857
858        let listed = list_library_section_at(dir.path(), Some("software")).unwrap();
859        assert_eq!(listed.len(), 1);
860        assert_eq!(listed[0]["asset_uri"], "model://test-vision");
861
862        let stats = library_stats_at(dir.path()).unwrap();
863        assert_eq!(stats["total"], 1);
864        assert_eq!(stats["sections"]["software"], 1);
865
866        let faceted =
867            query_library_faceted_at(dir.path(), r#"{"section":"software"}"#, "newest").unwrap();
868        assert_eq!(faceted["total"], 1);
869        assert_eq!(faceted["entries"].as_array().unwrap().len(), 1);
870    }
871}