Skip to main content

qualia_client_core/wellfair/
hypermedia_store.rs

1//! **Persistent hypermedia asset library** — ingest documents/assets, and find them by *meaning* (topic /
2//! depiction / time / place / project / purpose), never by folder.
3//!
4//! # Sections (product lanes)
5//! The library is one store, many **sections** — purpose-shaped views, not folders:
6//! - **Secret** — sanctuary / restricted / classified / Wellfair-private health
7//! - **Wellfair** — health & welfare purposes (can also force secret when sensitivity is high)
8//! - **Personal** — private life, default home shelf
9//! - **Work** — project-scoped labour
10//! - **Tools** — logs, telemetry, technical artefacts, agent/tool output
11//! - **Software** — QApps, websites, packages, installable/runnable software artefacts
12//! - **Commons** — permissive share surface (peers / micro-commons via social networking)
13//!
14//! Sensitivity (`public` | `restricted` | `classified` | `sanctuary`) is orthogonal: high sensitivity
15//! always routes into **Secret** even if the purpose is Wellfair or Work.
16
17use std::collections::{BTreeMap, HashSet};
18use std::fs;
19use std::path::{Path, PathBuf};
20
21use qualia_core_db::hypermedia;
22use qualia_core_db::NQuin;
23use serde::{Deserialize, Serialize};
24
25pub const LIBRARY_FILE: &str = "wellfair/hypermedia_library.json";
26
27/// Product section id for the Library chrome.
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
29#[serde(rename_all = "snake_case")]
30pub enum LibrarySection {
31    /// All items (except those filtered by UI for secret gate).
32    All,
33    /// High-sensitivity / sanctuary / private health — the secret shelf.
34    Secret,
35    /// Health, welfare, care (Wellfair).
36    Wellfair,
37    /// Default personal shelf.
38    Personal,
39    /// Project / cooperative work.
40    Work,
41    /// Logs, telemetry, agent/tool output, technical diagnostics.
42    Tools,
43    /// QApps, websites, packages, installable or runnable software artefacts.
44    Software,
45    /// Permissive commons — shareable with peers / social networking layers.
46    Commons,
47}
48
49impl LibrarySection {
50    /// `str` form.
51    pub fn as_str(self) -> &'static str {
52        match self {
53            Self::All => "all",
54            Self::Secret => "secret",
55            Self::Wellfair => "wellfair",
56            Self::Personal => "personal",
57            Self::Work => "work",
58            Self::Tools => "tools",
59            Self::Software => "software",
60            Self::Commons => "commons",
61        }
62    }
63
64    /// Parses.
65    pub fn parse(s: &str) -> Self {
66        match s.trim().to_ascii_lowercase().as_str() {
67            "secret" | "sanctuary" | "private" => Self::Secret,
68            "wellfair" | "health" | "welfare" => Self::Wellfair,
69            "personal" | "home" => Self::Personal,
70            "work" | "project" | "coop" => Self::Work,
71            "tools" | "tool" | "logs" | "log" | "tech" | "technical" | "ops" | "debug"
72            | "telemetry" | "agent" => Self::Tools,
73            "software" | "qapp" | "qapps" | "app" | "apps" | "website" | "websites" | "web"
74            | "site" | "package" | "packages" | "install" | "pwa" | "extension" => Self::Software,
75            "commons" | "public" | "share" | "permissive" => Self::Commons,
76            _ => Self::All,
77        }
78    }
79
80    /// Label.
81    pub fn label(self) -> &'static str {
82        match self {
83            Self::All => "All",
84            Self::Secret => "Secret",
85            Self::Wellfair => "Wellfair",
86            Self::Personal => "Personal",
87            Self::Work => "Work",
88            Self::Tools => "Tools",
89            Self::Software => "Software",
90            Self::Commons => "Commons",
91        }
92    }
93
94    /// Blurb.
95    pub fn blurb(self) -> &'static str {
96        match self {
97            Self::All => "Everything on this device you have rights to see.",
98            Self::Secret => "Sanctuary & high-sensitivity — Wellfair-private health and other secrets. Not for commons.",
99            Self::Wellfair => "Health, care, and welfare records — may also live under Secret when classified.",
100            Self::Personal => "Your private shelf — notes, life admin, unshared research.",
101            Self::Work => "Project-scoped material for cooperative labour.",
102            Self::Tools => "Logs, telemetry, agent/tool output, technical diagnostics — the machine's paper trail.",
103            Self::Software => "QApps, websites, packages, and other installable or runnable software artefacts.",
104            Self::Commons => "Permissive share surface — peers and micro-commons via Talk social networking.",
105        }
106    }
107}
108
109/// How far an item may travel on social / commons layers.
110#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
111#[serde(rename_all = "snake_case")]
112pub enum CommonsVisibility {
113    /// Device-local only (default for secret).
114    #[default]
115    None,
116    /// Visible to accepted social peers (bilateral / mesh).
117    Peers,
118    /// Permissive commons — intended for broader micro-commons replication.
119    Commons,
120}
121
122impl CommonsVisibility {
123    /// Parses.
124    pub fn parse(s: &str) -> Self {
125        match s.trim().to_ascii_lowercase().as_str() {
126            "peers" | "peer" | "bilateral" => Self::Peers,
127            "commons" | "public" | "permissive" => Self::Commons,
128            _ => Self::None,
129        }
130    }
131
132    /// `str` form.
133    pub fn as_str(self) -> &'static str {
134        match self {
135            Self::None => "none",
136            Self::Peers => "peers",
137            Self::Commons => "commons",
138        }
139    }
140}
141
142/// Normalize sensitivity tokens used at ingest / UI.
143pub fn normalize_sensitivity(s: &str) -> String {
144    match s.trim().to_ascii_lowercase().as_str() {
145        "restricted" => "restricted".into(),
146        "classified" | "sanctuary" => "classified".into(),
147        "secret" => "classified".into(),
148        _ => "public".into(),
149    }
150}
151
152/// Resolve the product section for an entry (secret always wins on high sensitivity).
153pub fn resolve_section(
154    sensitivity: &str,
155    purposes: &[String],
156    projects: &[String],
157    commons: CommonsVisibility,
158    section_hint: Option<&str>,
159) -> LibrarySection {
160    let sens = normalize_sensitivity(sensitivity);
161    if sens == "restricted" || sens == "classified" {
162        return LibrarySection::Secret;
163    }
164    if commons == CommonsVisibility::Commons || commons == CommonsVisibility::Peers {
165        // Explicit share lane — still never secret.
166        if let Some(h) = section_hint {
167            let p = LibrarySection::parse(h);
168            if p != LibrarySection::Secret {
169                return if commons == CommonsVisibility::Commons {
170                    LibrarySection::Commons
171                } else {
172                    p
173                };
174            }
175        }
176        return LibrarySection::Commons;
177    }
178    if let Some(h) = section_hint {
179        let p = LibrarySection::parse(h);
180        if p != LibrarySection::All {
181            return p;
182        }
183    }
184    let purpose_blob = purposes
185        .iter()
186        .chain(projects.iter())
187        .map(|s| s.to_ascii_lowercase())
188        .collect::<Vec<_>>()
189        .join(" ");
190    if purpose_blob.contains("health")
191        || purpose_blob.contains("wellfair")
192        || purpose_blob.contains("welfare")
193        || purpose_blob.contains("medical")
194        || purpose_blob.contains("care")
195    {
196        return LibrarySection::Wellfair;
197    }
198    if purpose_blob.contains("legislation")
199        || purpose_blob.contains("statute")
200        || purpose_blob.contains("legal")
201        || purpose_blob.contains("regulation")
202        || purpose_blob.contains("bill")
203    {
204        // Statutes and regulations sit on the Work shelf (research / labour), not Software.
205        return LibrarySection::Work;
206    }
207    if purpose_blob.contains("qapp")
208        || purpose_blob.contains("website")
209        || purpose_blob.contains("web-app")
210        || purpose_blob.contains("webapp")
211        || purpose_blob.contains("software")
212        || purpose_blob.contains("package")
213        || purpose_blob.contains("pwa")
214        || purpose_blob.contains("extension")
215        || purpose_blob.contains("installable")
216        || purpose_blob.contains("application")
217    {
218        return LibrarySection::Software;
219    }
220    if purpose_blob.contains("log")
221        || purpose_blob.contains("telemetry")
222        || purpose_blob.contains("debug")
223        || purpose_blob.contains("trace")
224        || purpose_blob.contains("tool")
225        || purpose_blob.contains("agent")
226        || purpose_blob.contains("ops")
227        || purpose_blob.contains("technical")
228        || purpose_blob.contains("diagnostic")
229        || purpose_blob.contains("build")
230        || purpose_blob.contains("ci")
231    {
232        return LibrarySection::Tools;
233    }
234    if !projects.is_empty()
235        || purpose_blob.contains("work")
236        || purpose_blob.contains("project")
237        || purpose_blob.contains("coop")
238    {
239        return LibrarySection::Work;
240    }
241    LibrarySection::Personal
242}
243
244/// A summarised flag on an ingested asset (for display / the guardian path).
245#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
246pub struct LibraryFlag {
247    pub kind: String,
248    pub severity_level: u64,
249    pub detail: String,
250}
251
252/// One ingested asset in the person's library — its identity + the container's semantic edge-graph.
253#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
254pub struct LibraryEntry {
255    pub asset_uri: String,
256    /// The container primary's subject (`= fnv60(asset_uri)`) — the join key for search results.
257    pub primary_subject: u64,
258    pub media_type: String,
259    /// The container's edge-graph (container + descriptor + flag quins) — the searchable semantic form.
260    pub quins: Vec<NQuin>,
261    /// Display facets (the string forms of the descriptors; search itself runs over the quins above).
262    #[serde(default)]
263    pub topics: Vec<String>,
264    #[serde(default)]
265    pub projects: Vec<String>,
266    /// Purpose tags (tax, health, research, …) — power purpose-shaped sections.
267    #[serde(default)]
268    pub purposes: Vec<String>,
269    #[serde(default)]
270    pub place: Option<String>,
271    /// Event instant (unix seconds) if the asset carries one — the timeline anchor
272    /// (e.g. a photo's EXIF capture time). `None` = no dated event.
273    #[serde(default)]
274    pub occurred_at: Option<i64>,
275    /// Geographic coordinates if the asset carries them (e.g. a photo's GPS) — the
276    /// map pin. Both present together or both `None`.
277    #[serde(default)]
278    pub lat: Option<f32>,
279    #[serde(default)]
280    pub lon: Option<f32>,
281    #[serde(default)]
282    pub flags: Vec<LibraryFlag>,
283    pub ingested_unix: u64,
284    /// A short excerpt for display in results (never the whole asset).
285    #[serde(default)]
286    pub excerpt: String,
287    /// `public` | `restricted` | `classified` — high sensitivity forces Secret section.
288    #[serde(default = "default_sensitivity_public")]
289    pub sensitivity: String,
290    /// Product section lane (secret / wellfair / personal / work / commons).
291    #[serde(default = "default_section_personal")]
292    pub section: String,
293    /// How far this may travel on social / commons layers.
294    #[serde(default)]
295    pub commons_visibility: CommonsVisibility,
296    /// CML context-graph signal tags (`privacy:consent`, `deontic:obligation`, …).
297    #[serde(default)]
298    pub cml_signals: Vec<String>,
299    /// Number of proposed CML concepts on this entry.
300    #[serde(default)]
301    pub cml_concept_count: u32,
302    /// Compact proposed CML N3 for this unit (TEXT→CONCEPT→LOGIC; cml:Proposed only).
303    /// Truncated for large instruments; full graph also lives in `quins`.
304    #[serde(default)]
305    pub cml_n3: String,
306    /// COF HTML+RDFa segment (profile html-rdfa-1). Empty if not emitted.
307    /// Large instruments store the **index** on the root and body segments as child entries.
308    #[serde(default)]
309    pub cof_html: String,
310    /// Number of COF segments in the package this entry belongs to (0 = none).
311    #[serde(default)]
312    pub cof_segment_count: u32,
313    /// This entry's segment index (0 = index/TOC).
314    #[serde(default)]
315    pub cof_segment_index: u32,
316    /// COF profile IRI when `cof_html` is set.
317    #[serde(default)]
318    pub cof_profile: String,
319}
320
321fn default_sensitivity_public() -> String {
322    "public".into()
323}
324fn default_section_personal() -> String {
325    LibrarySection::Personal.as_str().into()
326}
327
328impl LibraryEntry {
329    /// Recompute section from sensitivity / purposes / commons (call after mutate).
330    pub fn recompute_section(&mut self) {
331        self.section = resolve_section(
332            &self.sensitivity,
333            &self.purposes,
334            &self.projects,
335            self.commons_visibility,
336            Some(&self.section),
337        )
338        .as_str()
339        .into();
340        // Secret can never be commons-visible.
341        if self.section == LibrarySection::Secret.as_str() {
342            self.commons_visibility = CommonsVisibility::None;
343        }
344    }
345
346    /// `true` when secret.
347    pub fn is_secret(&self) -> bool {
348        self.section == LibrarySection::Secret.as_str()
349            || matches!(
350                normalize_sensitivity(&self.sensitivity).as_str(),
351                "restricted" | "classified"
352            )
353    }
354}
355
356/// On-disk library store (whole-file JSON, write-temp-then-rename), matching the sibling-store convention.
357pub struct HypermediaStore {
358    path: PathBuf,
359}
360
361impl HypermediaStore {
362    /// Opens.
363    pub fn open(storage_root: impl AsRef<Path>) -> std::io::Result<Self> {
364        let path = storage_root.as_ref().join(LIBRARY_FILE);
365        if let Some(parent) = path.parent() {
366            fs::create_dir_all(parent)?;
367        }
368        Ok(Self { path })
369    }
370
371    /// Loads.
372    pub fn load(&self) -> std::io::Result<Vec<LibraryEntry>> {
373        match fs::read(&self.path) {
374            Ok(bytes) => {
375                serde_json::from_slice(&bytes).map_err(|e| std::io::Error::other(e.to_string()))
376            }
377            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Vec::new()),
378            Err(e) => Err(e),
379        }
380    }
381
382    fn save(&self, entries: &[LibraryEntry]) -> std::io::Result<()> {
383        let bytes =
384            serde_json::to_vec_pretty(entries).map_err(|e| std::io::Error::other(e.to_string()))?;
385        let tmp = self.path.with_extension("json.tmp");
386        fs::write(&tmp, &bytes)?;
387        fs::rename(&tmp, &self.path)?;
388        Ok(())
389    }
390
391    /// Add (or replace by `asset_uri`) an entry.
392    pub fn add(&self, entry: LibraryEntry) -> std::io::Result<()> {
393        let mut entries = self.load()?;
394        entries.retain(|e| e.asset_uri != entry.asset_uri);
395        entries.push(entry);
396        self.save(&entries)
397    }
398
399    /// Replace the entire library (used by bulk seed paths — one write).
400    pub fn replace_all(&self, entries: &[LibraryEntry]) -> std::io::Result<()> {
401        self.save(entries)
402    }
403
404    /// Everything in the library (newest first).
405    pub fn all(&self) -> std::io::Result<Vec<LibraryEntry>> {
406        let mut entries = self.load()?;
407        // Backfill section/sensitivity on old entries.
408        for e in &mut entries {
409            if e.section.is_empty() || e.sensitivity.is_empty() {
410                e.sensitivity = normalize_sensitivity(&e.sensitivity);
411                e.recompute_section();
412            }
413        }
414        entries.sort_by(|a, b| b.ingested_unix.cmp(&a.ingested_unix));
415        Ok(entries)
416    }
417
418    /// Entries in one product section (`all` = everything).
419    pub fn by_section(&self, section: LibrarySection) -> std::io::Result<Vec<LibraryEntry>> {
420        let mut entries = self.all()?;
421        if section != LibrarySection::All {
422            let want = section.as_str();
423            entries.retain(|e| e.section == want);
424        }
425        Ok(entries)
426    }
427
428    /// Counts per section for the section rail UI.
429    pub fn section_counts(&self) -> std::io::Result<BTreeMap<String, usize>> {
430        let entries = self.all()?;
431        let mut m = BTreeMap::new();
432        m.insert(LibrarySection::All.as_str().into(), entries.len());
433        for sec in [
434            LibrarySection::Secret,
435            LibrarySection::Wellfair,
436            LibrarySection::Personal,
437            LibrarySection::Work,
438            LibrarySection::Tools,
439            LibrarySection::Software,
440            LibrarySection::Commons,
441        ] {
442            m.insert(
443                sec.as_str().into(),
444                entries.iter().filter(|e| e.section == sec.as_str()).count(),
445            );
446        }
447        Ok(m)
448    }
449
450    /// Publish (or revoke) commons visibility — never allowed for Secret / high sensitivity.
451    pub fn set_commons_visibility(
452        &self,
453        asset_uri: &str,
454        visibility: CommonsVisibility,
455    ) -> std::io::Result<LibraryEntry> {
456        let mut entries = self.load()?;
457        let e = entries
458            .iter_mut()
459            .find(|e| e.asset_uri == asset_uri)
460            .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "unknown asset"))?;
461        if e.is_secret() && visibility != CommonsVisibility::None {
462            return Err(std::io::Error::other(
463                "secret / high-sensitivity items cannot join the commons or peer share lane",
464            ));
465        }
466        e.commons_visibility = visibility;
467        if visibility == CommonsVisibility::Commons {
468            e.section = LibrarySection::Commons.as_str().into();
469        } else if visibility == CommonsVisibility::None
470            && e.section == LibrarySection::Commons.as_str()
471        {
472            e.recompute_section();
473        }
474        let out = e.clone();
475        self.save(&entries)?;
476        Ok(out)
477    }
478
479    /// Return the entries whose primary subject is in `subjects` (the join back from a graph query).
480    fn entries_for(&self, subjects: &HashSet<u64>) -> std::io::Result<Vec<LibraryEntry>> {
481        Ok(self
482            .load()?
483            .into_iter()
484            .filter(|e| subjects.contains(&e.primary_subject))
485            .collect())
486    }
487
488    /// Run a graph query over the union of all entries' quins, returning matching entries. `facet` is one of
489    /// `topic` | `depicts` | `place` | `project` | `purpose`.
490    pub fn search(&self, facet: &str, value: &str) -> std::io::Result<Vec<LibraryEntry>> {
491        let entries = self.load()?;
492        let all: Vec<NQuin> = entries
493            .iter()
494            .flat_map(|e| e.quins.iter().cloned())
495            .collect();
496        let subjects: HashSet<u64> = match facet {
497            "topic" => hypermedia::by_topic(&all, value),
498            "depicts" => hypermedia::by_depiction(&all, value),
499            "place" => hypermedia::by_place(&all, value),
500            "project" => hypermedia::in_project(&all, value),
501            "purpose" => hypermedia::for_purpose(&all, value),
502            "target" => hypermedia::analytics_for(&all, hypermedia::fnv60(value.as_bytes())),
503            _ => Vec::new(),
504        }
505        .into_iter()
506        .collect();
507        self.entries_for(&subjects)
508    }
509
510    /// The **timeline** query — entries whose event instant is within `[start, end]` (unix seconds).
511    pub fn search_time_range(&self, start: i64, end: i64) -> std::io::Result<Vec<LibraryEntry>> {
512        let entries = self.load()?;
513        let all: Vec<NQuin> = entries
514            .iter()
515            .flat_map(|e| e.quins.iter().cloned())
516            .collect();
517        let subjects: HashSet<u64> = hypermedia::in_time_range(&all, start, end)
518            .into_iter()
519            .collect();
520        self.entries_for(&subjects)
521    }
522
523    /// Free-text filter over uri, excerpt, topics, projects, purposes, place (case-insensitive).
524    pub fn search_text(&self, query: &str) -> std::io::Result<Vec<LibraryEntry>> {
525        let q = query.trim().to_lowercase();
526        if q.is_empty() {
527            return self.all();
528        }
529        let mut entries = self.load()?;
530        entries.retain(|e| entry_matches_text(e, &q));
531        entries.sort_by(|a, b| b.ingested_unix.cmp(&a.ingested_unix));
532        Ok(entries)
533    }
534
535    /// Multi-facet filter + sort. Facets are **AND** across dimensions; within each
536    /// non-empty list, match is **OR** (any of the selected values).
537    ///
538    /// Categories match `topics` containing the slug or `projects` of form `category:{slug}`.
539    pub fn query_faceted(
540        &self,
541        filter: &FacetFilter,
542        sort: LibrarySort,
543    ) -> std::io::Result<Vec<LibraryEntry>> {
544        let mut entries = self.all()?;
545        entries.retain(|e| filter.matches(e));
546        sort_entries(&mut entries, sort);
547        Ok(entries)
548    }
549
550    /// Facet value counts over entries matching `filter` (for chip UI). Counts are
551    /// computed **after** the filter so selecting a category narrows other facet tallies.
552    pub fn facet_counts(&self, filter: &FacetFilter) -> std::io::Result<FacetCounts> {
553        let entries = self.query_faceted(filter, LibrarySort::Newest)?;
554        let mut topics = BTreeMap::new();
555        let mut purposes = BTreeMap::new();
556        let mut projects = BTreeMap::new();
557        let mut media_types = BTreeMap::new();
558        let mut categories = BTreeMap::new();
559        let mut sections = BTreeMap::new();
560        for e in &entries {
561            *sections.entry(e.section.clone()).or_default() += 1;
562            *media_types.entry(e.media_type.clone()).or_default() += 1;
563            for t in &e.topics {
564                *topics.entry(t.clone()).or_default() += 1;
565            }
566            for p in &e.purposes {
567                *purposes.entry(p.clone()).or_default() += 1;
568            }
569            for p in &e.projects {
570                *projects.entry(p.clone()).or_default() += 1;
571                if let Some(cat) = p.strip_prefix("category:") {
572                    *categories.entry(cat.to_string()).or_default() += 1;
573                }
574            }
575            // Also treat topic slugs that look like domain categories.
576            for t in &e.topics {
577                if t.contains('-') && t != "qapp" && t != "academic" && !t.contains(':') {
578                    // Prefer explicit category: project tags; fill gaps from topics.
579                    categories.entry(t.clone()).or_insert(0);
580                }
581            }
582        }
583        // Re-count categories from project tags primarily (authoritative for QApps).
584        categories.clear();
585        for e in &entries {
586            for p in &e.projects {
587                if let Some(cat) = p.strip_prefix("category:") {
588                    *categories.entry(cat.to_string()).or_default() += 1;
589                }
590            }
591            // Fallback: topic that matches a known category project tag pattern on peers.
592            if e.projects.iter().all(|p| !p.starts_with("category:")) {
593                for t in &e.topics {
594                    if matches_category_slug(t) {
595                        *categories.entry(t.clone()).or_default() += 1;
596                    }
597                }
598            }
599        }
600        Ok(FacetCounts {
601            total: entries.len(),
602            topics,
603            purposes,
604            projects,
605            media_types,
606            categories,
607            sections,
608        })
609    }
610
611    /// Remove an entry by asset_uri.
612    pub fn remove(&self, asset_uri: &str) -> std::io::Result<bool> {
613        let mut entries = self.load()?;
614        let before = entries.len();
615        entries.retain(|e| e.asset_uri != asset_uri);
616        if entries.len() == before {
617            return Ok(false);
618        }
619        self.save(&entries)?;
620        Ok(true)
621    }
622
623    /// Library stats for the UI chrome.
624    pub fn stats(&self) -> std::io::Result<LibraryStats> {
625        let entries = self.load()?;
626        let mut topics: std::collections::BTreeMap<String, usize> =
627            std::collections::BTreeMap::new();
628        let mut projects: std::collections::BTreeMap<String, usize> =
629            std::collections::BTreeMap::new();
630        let mut with_date = 0usize;
631        let mut with_place = 0usize;
632        let mut flags = 0usize;
633        let mut quins = 0usize;
634        for e in &entries {
635            for t in &e.topics {
636                *topics.entry(t.clone()).or_default() += 1;
637            }
638            for p in &e.projects {
639                *projects.entry(p.clone()).or_default() += 1;
640            }
641            if e.occurred_at.is_some() {
642                with_date += 1;
643            }
644            if e.lat.is_some() && e.lon.is_some() {
645                with_place += 1;
646            }
647            flags += e.flags.len();
648            quins += e.quins.len();
649        }
650        Ok(LibraryStats {
651            total: entries.len(),
652            with_date,
653            with_place,
654            flags,
655            quins,
656            topics,
657            projects,
658        })
659    }
660
661    /// Flatten all library quins for graph export / daemon inject (caller owns the slice).
662    pub fn all_quins(&self) -> std::io::Result<Vec<NQuin>> {
663        Ok(self.load()?.into_iter().flat_map(|e| e.quins).collect())
664    }
665}
666
667/// Aggregate counts for the Library UI header.
668#[derive(Debug, Clone, Default, Serialize, Deserialize)]
669pub struct LibraryStats {
670    pub total: usize,
671    pub with_date: usize,
672    pub with_place: usize,
673    pub flags: usize,
674    /// Total NQuins across all containers — the semantic graph mass.
675    pub quins: usize,
676    pub topics: std::collections::BTreeMap<String, usize>,
677    pub projects: std::collections::BTreeMap<String, usize>,
678}
679
680/// Multi-facet filter for library browse / Software QApp shelf.
681///
682/// Empty lists mean "no constraint" on that dimension. Within a non-empty list,
683/// matching is OR; across dimensions, matching is AND.
684#[derive(Debug, Clone, Default, Serialize, Deserialize)]
685pub struct FacetFilter {
686    /// Product section id (`software`, `tools`, …). `all` / empty = no section filter.
687    #[serde(default)]
688    pub section: Option<String>,
689    /// Free-text over uri / excerpt / topics / purposes / projects / place / media.
690    #[serde(default)]
691    pub text: Option<String>,
692    #[serde(default)]
693    pub topics: Vec<String>,
694    #[serde(default)]
695    pub purposes: Vec<String>,
696    #[serde(default)]
697    pub projects: Vec<String>,
698    #[serde(default)]
699    pub media_types: Vec<String>,
700    /// Domain categories (e.g. `natural-sciences`) — matches `category:{slug}` projects or topic slug.
701    #[serde(default)]
702    pub categories: Vec<String>,
703}
704
705impl FacetFilter {
706    /// `true` when it matches.
707    pub fn matches(&self, e: &LibraryEntry) -> bool {
708        if let Some(sec) = self.section.as_deref() {
709            let sec = sec.trim();
710            if !sec.is_empty() && sec != "all" && e.section != sec {
711                return false;
712            }
713        }
714        if let Some(q) = self.text.as_deref() {
715            let q = q.trim().to_lowercase();
716            if !q.is_empty() && !entry_matches_text(e, &q) {
717                return false;
718            }
719        }
720        if !self.topics.is_empty()
721            && !self.topics.iter().any(|t| {
722                let t = t.to_ascii_lowercase();
723                e.topics.iter().any(|et| et.to_ascii_lowercase() == t)
724            })
725        {
726            return false;
727        }
728        if !self.purposes.is_empty()
729            && !self.purposes.iter().any(|p| {
730                let p = p.to_ascii_lowercase();
731                e.purposes.iter().any(|ep| ep.to_ascii_lowercase() == p)
732            })
733        {
734            return false;
735        }
736        if !self.projects.is_empty()
737            && !self.projects.iter().any(|p| {
738                let p = p.to_ascii_lowercase();
739                e.projects.iter().any(|ep| ep.to_ascii_lowercase() == p)
740            })
741        {
742            return false;
743        }
744        if !self.media_types.is_empty()
745            && !self
746                .media_types
747                .iter()
748                .any(|m| e.media_type.eq_ignore_ascii_case(m.trim()))
749        {
750            return false;
751        }
752        if !self.categories.is_empty() && !self.categories.iter().any(|c| entry_has_category(e, c))
753        {
754            return false;
755        }
756        true
757    }
758}
759
760/// Sort keys for faceted library browse.
761#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
762#[serde(rename_all = "snake_case")]
763pub enum LibrarySort {
764    #[default]
765    Newest,
766    Oldest,
767    TitleAsc,
768    TitleDesc,
769    MediaType,
770    Category,
771}
772
773impl LibrarySort {
774    /// Parses.
775    pub fn parse(s: &str) -> Self {
776        match s.trim().to_ascii_lowercase().as_str() {
777            "oldest" | "old" => Self::Oldest,
778            "title" | "title_asc" | "name" | "name_asc" | "a-z" | "az" => Self::TitleAsc,
779            "title_desc" | "name_desc" | "z-a" | "za" => Self::TitleDesc,
780            "media" | "media_type" | "type" => Self::MediaType,
781            "category" | "cat" => Self::Category,
782            _ => Self::Newest,
783        }
784    }
785
786    /// `str` form.
787    pub fn as_str(self) -> &'static str {
788        match self {
789            Self::Newest => "newest",
790            Self::Oldest => "oldest",
791            Self::TitleAsc => "title_asc",
792            Self::TitleDesc => "title_desc",
793            Self::MediaType => "media_type",
794            Self::Category => "category",
795        }
796    }
797}
798
799/// Per-value counts for facet chips after a filter is applied.
800#[derive(Debug, Clone, Default, Serialize, Deserialize)]
801pub struct FacetCounts {
802    pub total: usize,
803    pub topics: BTreeMap<String, usize>,
804    pub purposes: BTreeMap<String, usize>,
805    pub projects: BTreeMap<String, usize>,
806    pub media_types: BTreeMap<String, usize>,
807    pub categories: BTreeMap<String, usize>,
808    pub sections: BTreeMap<String, usize>,
809}
810
811fn entry_matches_text(e: &LibraryEntry, q: &str) -> bool {
812    e.asset_uri.to_lowercase().contains(q)
813        || e.excerpt.to_lowercase().contains(q)
814        || e.media_type.to_lowercase().contains(q)
815        || e.section.to_lowercase().contains(q)
816        || e.topics.iter().any(|t| t.to_lowercase().contains(q))
817        || e.projects.iter().any(|t| t.to_lowercase().contains(q))
818        || e.purposes.iter().any(|t| t.to_lowercase().contains(q))
819        || e.cml_signals.iter().any(|t| t.to_lowercase().contains(q))
820        || e.cml_n3.to_lowercase().contains(q)
821        || e.place
822            .as_ref()
823            .map(|p| p.to_lowercase().contains(q))
824            .unwrap_or(false)
825}
826
827fn entry_has_category(e: &LibraryEntry, cat: &str) -> bool {
828    let cat = cat.trim().to_ascii_lowercase();
829    if cat.is_empty() {
830        return true;
831    }
832    let tag = format!("category:{cat}");
833    e.projects
834        .iter()
835        .any(|p| p.eq_ignore_ascii_case(&tag) || p.to_ascii_lowercase() == cat)
836        || e.topics.iter().any(|t| t.eq_ignore_ascii_case(&cat))
837}
838
839fn matches_category_slug(s: &str) -> bool {
840    // Domain categories are kebab-case multi-word slugs (contain a hyphen).
841    let s = s.trim();
842    s.contains('-')
843        && s.chars()
844            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
845        && s != "qapp"
846}
847
848fn entry_title_key(e: &LibraryEntry) -> String {
849    // Prefer last path segment of URI for title-ish sort.
850    let uri = e.asset_uri.as_str();
851    let t = uri
852        .rsplit(['/', ':'])
853        .next()
854        .unwrap_or(uri)
855        .to_ascii_lowercase();
856    if t.is_empty() {
857        uri.to_ascii_lowercase()
858    } else {
859        t
860    }
861}
862
863fn entry_category_key(e: &LibraryEntry) -> String {
864    for p in &e.projects {
865        if let Some(c) = p.strip_prefix("category:") {
866            return c.to_ascii_lowercase();
867        }
868    }
869    e.topics
870        .iter()
871        .find(|t| matches_category_slug(t))
872        .cloned()
873        .unwrap_or_default()
874}
875
876fn sort_entries(entries: &mut [LibraryEntry], sort: LibrarySort) {
877    match sort {
878        LibrarySort::Newest => entries.sort_by(|a, b| b.ingested_unix.cmp(&a.ingested_unix)),
879        LibrarySort::Oldest => entries.sort_by(|a, b| a.ingested_unix.cmp(&b.ingested_unix)),
880        LibrarySort::TitleAsc => {
881            entries.sort_by(|a, b| entry_title_key(a).cmp(&entry_title_key(b)))
882        }
883        LibrarySort::TitleDesc => {
884            entries.sort_by(|a, b| entry_title_key(b).cmp(&entry_title_key(a)))
885        }
886        LibrarySort::MediaType => entries.sort_by(|a, b| {
887            a.media_type
888                .cmp(&b.media_type)
889                .then_with(|| entry_title_key(a).cmp(&entry_title_key(b)))
890        }),
891        LibrarySort::Category => entries.sort_by(|a, b| {
892            entry_category_key(a)
893                .cmp(&entry_category_key(b))
894                .then_with(|| entry_title_key(a).cmp(&entry_title_key(b)))
895        }),
896    }
897}
898
899#[cfg(test)]
900mod tests {
901    use super::*;
902    use qualia_core_db::hypermedia::{ingest_with, TextProcessor};
903
904    fn ingest(store: &HypermediaStore, uri: &str, text: &str, now: u64) {
905        let proc = TextProcessor::default();
906        let r = ingest_with(&proc, uri, "text/markdown", 1, text.as_bytes());
907        let mut entry = LibraryEntry {
908            asset_uri: uri.to_string(),
909            primary_subject: r.container.primary.subject(),
910            media_type: "text/markdown".to_string(),
911            quins: r.quins,
912            topics: Vec::new(),
913            projects: Vec::new(),
914            purposes: Vec::new(),
915            place: None,
916            occurred_at: None,
917            lat: None,
918            lon: None,
919            flags: Vec::new(),
920            ingested_unix: now,
921            excerpt: text.chars().take(40).collect(),
922            sensitivity: "public".into(),
923            section: "personal".into(),
924            commons_visibility: CommonsVisibility::None,
925            cml_signals: Vec::new(),
926            cml_concept_count: 0,
927            cml_n3: String::new(),
928            cof_html: String::new(),
929            cof_segment_count: 0,
930            cof_segment_index: 0,
931            cof_profile: String::new(),
932        };
933        entry.recompute_section();
934        store.add(entry).unwrap();
935    }
936
937    #[test]
938    fn ingested_documents_are_findable_by_topic_across_the_library() {
939        let dir = tempfile::tempdir().unwrap();
940        let store = HypermediaStore::open(dir.path()).unwrap();
941        ingest(
942            &store,
943            "urn:doc:liver",
944            "The liver is an organ; hepatocytes secrete bile.",
945            1_000,
946        );
947        ingest(
948            &store,
949            "urn:doc:contract",
950            "This contract is governed by statute and jurisdiction.",
951            1_100,
952        );
953        ingest(
954            &store,
955            "urn:doc:receipt",
956            "Invoice for a tax-deductible expense; keep this receipt.",
957            1_200,
958        );
959
960        // Search the WHOLE library by meaning — biology finds the liver, law finds the contract, finance the receipt.
961        let bio = store.search("topic", "biology").unwrap();
962        assert_eq!(bio.len(), 1);
963        assert_eq!(bio[0].asset_uri, "urn:doc:liver");
964        let law = store.search("topic", "law").unwrap();
965        assert_eq!(law.len(), 1);
966        assert_eq!(law[0].asset_uri, "urn:doc:contract");
967        // The tax/expenses use case: finance topic finds the receipt.
968        let fin = store.search("topic", "finance").unwrap();
969        assert_eq!(fin.len(), 1);
970        assert_eq!(fin[0].asset_uri, "urn:doc:receipt");
971        // A topic no doc has returns nothing; the whole library lists all three.
972        assert!(store.search("topic", "astronomy").unwrap().is_empty());
973        assert_eq!(store.all().unwrap().len(), 3);
974    }
975
976    #[test]
977    fn secret_section_forced_by_classified_sensitivity() {
978        assert_eq!(
979            resolve_section(
980                "classified",
981                &["health".into()],
982                &[],
983                CommonsVisibility::Commons,
984                Some("commons")
985            ),
986            LibrarySection::Secret
987        );
988    }
989
990    #[test]
991    fn wellfair_purpose_routes_to_wellfair_when_public() {
992        assert_eq!(
993            resolve_section(
994                "public",
995                &["health-record".into()],
996                &[],
997                CommonsVisibility::None,
998                None
999            ),
1000            LibrarySection::Wellfair
1001        );
1002    }
1003
1004    #[test]
1005    fn commons_visibility_routes_to_commons() {
1006        assert_eq!(
1007            resolve_section("public", &[], &[], CommonsVisibility::Commons, None),
1008            LibrarySection::Commons
1009        );
1010    }
1011
1012    #[test]
1013    fn tools_purpose_routes_to_tools() {
1014        assert_eq!(
1015            resolve_section(
1016                "public",
1017                &["agent-log".into(), "telemetry".into()],
1018                &[],
1019                CommonsVisibility::None,
1020                None
1021            ),
1022            LibrarySection::Tools
1023        );
1024        assert_eq!(
1025            resolve_section("public", &[], &[], CommonsVisibility::None, Some("tools")),
1026            LibrarySection::Tools
1027        );
1028    }
1029
1030    #[test]
1031    fn software_purpose_routes_to_software() {
1032        assert_eq!(
1033            resolve_section(
1034                "public",
1035                &["qapp".into()],
1036                &[],
1037                CommonsVisibility::None,
1038                None
1039            ),
1040            LibrarySection::Software
1041        );
1042        assert_eq!(
1043            resolve_section(
1044                "public",
1045                &["website".into()],
1046                &[],
1047                CommonsVisibility::None,
1048                None
1049            ),
1050            LibrarySection::Software
1051        );
1052        assert_eq!(
1053            resolve_section(
1054                "public",
1055                &[],
1056                &[],
1057                CommonsVisibility::None,
1058                Some("software")
1059            ),
1060            LibrarySection::Software
1061        );
1062    }
1063
1064    #[test]
1065    fn faceted_filter_and_sort() {
1066        let dir = tempfile::tempdir().unwrap();
1067        let store = HypermediaStore::open(dir.path()).unwrap();
1068        for (uri, topics, purposes, projects, media, section, when) in [
1069            (
1070                "qapp://studio/biology",
1071                vec!["qapp", "natural-sciences", "biology"],
1072                vec!["qapp", "software"],
1073                vec!["category:natural-sciences"],
1074                "application/x-webizen-qapp",
1075                "software",
1076                100u64,
1077            ),
1078            (
1079                "qapp://studio/philosophy",
1080                vec!["qapp", "humanities", "philosophy"],
1081                vec!["qapp", "software"],
1082                vec!["category:humanities"],
1083                "application/x-webizen-qapp",
1084                "software",
1085                200,
1086            ),
1087            (
1088                "urn:doc:note",
1089                vec!["personal"],
1090                vec!["note"],
1091                vec![],
1092                "text/markdown",
1093                "personal",
1094                300,
1095            ),
1096        ] {
1097            let mut e = LibraryEntry {
1098                asset_uri: uri.into(),
1099                primary_subject: when,
1100                media_type: media.into(),
1101                quins: Vec::new(),
1102                topics: topics.into_iter().map(str::to_string).collect(),
1103                projects: projects.into_iter().map(str::to_string).collect(),
1104                purposes: purposes.into_iter().map(str::to_string).collect(),
1105                place: None,
1106                occurred_at: None,
1107                lat: None,
1108                lon: None,
1109                flags: Vec::new(),
1110                ingested_unix: when,
1111                excerpt: uri.into(),
1112                sensitivity: "public".into(),
1113                section: section.into(),
1114                commons_visibility: CommonsVisibility::None,
1115                cml_signals: Vec::new(),
1116                cml_concept_count: 0,
1117                cml_n3: String::new(),
1118                cof_html: String::new(),
1119                cof_segment_count: 0,
1120                cof_segment_index: 0,
1121                cof_profile: String::new(),
1122            };
1123            e.recompute_section();
1124            store.add(e).unwrap();
1125        }
1126
1127        let soft = store
1128            .query_faceted(
1129                &FacetFilter {
1130                    section: Some("software".into()),
1131                    ..Default::default()
1132                },
1133                LibrarySort::TitleAsc,
1134            )
1135            .unwrap();
1136        assert_eq!(soft.len(), 2);
1137        assert!(soft[0].asset_uri.contains("biology"));
1138        assert!(soft[1].asset_uri.contains("philosophy"));
1139
1140        let nat = store
1141            .query_faceted(
1142                &FacetFilter {
1143                    section: Some("software".into()),
1144                    categories: vec!["natural-sciences".into()],
1145                    ..Default::default()
1146                },
1147                LibrarySort::Newest,
1148            )
1149            .unwrap();
1150        assert_eq!(nat.len(), 1);
1151        assert!(nat[0].asset_uri.contains("biology"));
1152
1153        let text = store
1154            .query_faceted(
1155                &FacetFilter {
1156                    text: Some("philo".into()),
1157                    ..Default::default()
1158                },
1159                LibrarySort::Newest,
1160            )
1161            .unwrap();
1162        assert_eq!(text.len(), 1);
1163
1164        let counts = store
1165            .facet_counts(&FacetFilter {
1166                section: Some("software".into()),
1167                ..Default::default()
1168            })
1169            .unwrap();
1170        assert_eq!(counts.total, 2);
1171        assert_eq!(counts.categories.get("natural-sciences"), Some(&1));
1172        assert_eq!(counts.categories.get("humanities"), Some(&1));
1173    }
1174}