Skip to main content

eidetic/browsing/
mod.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Layer 4 — browsing memory, the domain the crate was named for.
5//!
6//! A [`BrowsingTrace`] is a chronological segment of one owner's (persona's)
7//! traversals, stored as a typed payload (design pass §6.2). Traces are the
8//! durable, portable impression of browsing — deliberately coarser than
9//! `node-lineage`'s live per-owner branch detail, which remains the
10//! graph-shaped working memory this module projects *from* (see
11//! [`lineage`], feature `"lineage"`) rather than duplicates.
12//!
13//! [`BrowsingMemory`] composes traces into the user-facing reads: the recent
14//! corridor, time-window slices, and traversal co-occurrence. Everything
15//! saves **LocalOnly** — promotion to a wider audience is always a separate,
16//! explicit act (design pass §8), never a side effect of remembering.
17//!
18//! Quota is a Layer-4 policy: [`BrowsingMemory::apply_quota`] keeps the N
19//! most recent *stored* traces and deletes older manifests (blob bytes await
20//! the explicit GC pass, per the manifest-deletion doctrine).
21
22#[cfg(feature = "lineage")]
23pub mod lineage;
24
25use serde::{Deserialize, Serialize};
26
27use crate::manifest::{NoFetcher, delete_manifest};
28use crate::schema::{
29    Hash, ManifestId, ModerationState, PrivacyClass, ProvenanceOrigin, ProvenanceRecord, SchemaRef,
30    Timestamp, TrustEnvelope, TrustLevel,
31};
32use crate::typed::{TypedPayload, list_typed, load_typed, save_typed};
33use crate::{Result, Store};
34
35/// Canonical bytes of the `BrowsingTrace` schema engram's payload
36/// (mere-native format, like the model-manifest schema). Their BLAKE3 hash
37/// anchors [`BROWSING_TRACE_SCHEMA_REF`].
38const BROWSING_TRACE_SCHEMA_PAYLOAD: &[u8] = br#"{"format":"mere-native","schema_id":"eidetic.BrowsingTrace/v1","body":{"version":1,"description":"A chronological segment of one owner's browsing traversals.","required":["owner","events","started_at_ms","ended_at_ms"],"fields":{"owner":{"type":"string"},"events":{"type":"array"},"started_at_ms":{"type":"integer"},"ended_at_ms":{"type":"integer"}}}}"#;
39
40/// The well-known schema reference for [`BrowsingTrace`] payloads.
41pub static BROWSING_TRACE_SCHEMA_REF: std::sync::LazyLock<SchemaRef> =
42    std::sync::LazyLock::new(|| {
43        SchemaRef::from_id(ManifestId::from_hash(Hash::of(
44            BROWSING_TRACE_SCHEMA_PAYLOAD,
45        )))
46    });
47
48/// Idempotently seed the `BrowsingTrace` schema engram into a Store.
49/// Call once during init for any consumer that records or reads browsing
50/// memory (the [`crate::bootstrap`] pattern).
51pub async fn bootstrap_browsing_schema(store: &mut dyn Store) -> Result<()> {
52    let id = BROWSING_TRACE_SCHEMA_REF.0;
53    if crate::manifest::load_manifest(store, id).await?.is_some() {
54        return Ok(());
55    }
56    // Write the payload bytes verbatim — re-serialization could reorder JSON
57    // keys and break the hash anchor.
58    let local_key = format!("blob:{}", Hash::of(BROWSING_TRACE_SCHEMA_PAYLOAD).to_hex());
59    store.put(&local_key, BROWSING_TRACE_SCHEMA_PAYLOAD).await?;
60    let manifest = crate::manifest::BlobManifest {
61        id,
62        schema: *crate::schema_def::META_SCHEMA_REF,
63        content_hash: Hash::of(BROWSING_TRACE_SCHEMA_PAYLOAD),
64        byte_size: BROWSING_TRACE_SCHEMA_PAYLOAD.len() as u64,
65        created_at: Timestamp::ZERO,
66        last_accessed: None,
67        sources: vec![crate::manifest::BlobSource::Local { key: local_key }],
68        privacy: PrivacyClass::PublicPortable,
69        provenance: ProvenanceRecord {
70            origin: ProvenanceOrigin::Generated,
71            upstream: Vec::new(),
72            tooling: Some(format!("eidetic/{}", env!("CARGO_PKG_VERSION"))),
73            generated_at: Timestamp::ZERO,
74        },
75        trust: TrustEnvelope {
76            level: TrustLevel::CheckpointAccepted,
77            signatures: Vec::new(),
78            moderation_state: ModerationState::Accepted,
79        },
80        schema_metadata: serde_json::Value::Null,
81        manifest_version: crate::manifest::BlobManifest::CURRENT_VERSION,
82    };
83    crate::manifest::save_manifest(store, &manifest).await
84}
85
86/// A visited page: canonical URL plus the title when one was known.
87#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
88pub struct PageRef {
89    pub url: String,
90    pub title: Option<String>,
91}
92
93/// How a traversal happened. Mirrors `node-lineage`'s transition kinds as a
94/// portable wire enum — the schema must not depend on the lineage crate.
95#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
96pub enum TraceTransition {
97    LinkClick,
98    UrlTyped,
99    Back,
100    Forward,
101    Reload,
102    Redirect,
103    TabSpawn,
104    Restore,
105    /// Brought in from another browser's history/bookmarks (the import
106    /// bridge), not traversed live.
107    Imported,
108    Unknown,
109}
110
111/// One traversal: where the user went, from where, how, and when.
112#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
113pub struct TraceEvent {
114    /// The page navigated from; `None` for an origin event (first visit of a
115    /// session, a typed URL into a fresh surface, an import).
116    pub from: Option<PageRef>,
117    pub to: PageRef,
118    pub transition: TraceTransition,
119    pub at_ms: u64,
120    /// Dwell on `to`, when the recorder knows it (live capture may; imports
121    /// rarely do).
122    pub dwell_ms: Option<u64>,
123    /// The other pages this navigation was chosen *against* — the relational
124    /// candidate set (the source page's outbound links, or a materialized
125    /// neighborhood). `to` is the chosen one; the rest are the in-context
126    /// "seen but not followed" negatives (the listwise relevance signal). Empty
127    /// when no relational context was available. (Capture plan C2.)
128    #[serde(default)]
129    pub candidates: Vec<PageRef>,
130}
131
132/// A chronological segment of one owner's traversals — the typed payload
133/// browsing memory accumulates. `owner` is an opaque persona tag carried
134/// from day one (cheap to carry, expensive to retrofit); `""` means
135/// unattributed.
136#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
137pub struct BrowsingTrace {
138    pub owner: String,
139    /// Events in chronological order.
140    pub events: Vec<TraceEvent>,
141    pub started_at_ms: u64,
142    pub ended_at_ms: u64,
143}
144
145impl BrowsingTrace {
146    /// Build a trace from chronologically ordered events. Bounds derive from
147    /// the first and last event; an empty event list is allowed but inert.
148    pub fn from_events(owner: impl Into<String>, events: Vec<TraceEvent>) -> Self {
149        let started_at_ms = events.first().map(|e| e.at_ms).unwrap_or(0);
150        let ended_at_ms = events.last().map(|e| e.at_ms).unwrap_or(0);
151        Self {
152            owner: owner.into(),
153            events,
154            started_at_ms,
155            ended_at_ms,
156        }
157    }
158}
159
160impl TypedPayload for BrowsingTrace {
161    fn schema_ref() -> SchemaRef {
162        *BROWSING_TRACE_SCHEMA_REF
163    }
164}
165
166/// Save one trace as a LocalOnly typed payload (the only privacy a recorder
167/// writes; sharing is a separate explicit act). Returns the manifest id.
168pub async fn save_trace(
169    store: &mut dyn Store,
170    trace: &BrowsingTrace,
171    now_ms: u64,
172) -> Result<ManifestId> {
173    save_typed(
174        store,
175        trace,
176        Vec::new(),
177        PrivacyClass::LocalOnly,
178        ProvenanceRecord {
179            origin: ProvenanceOrigin::Generated,
180            upstream: Vec::new(),
181            tooling: Some(format!("eidetic-browsing/{}", env!("CARGO_PKG_VERSION"))),
182            generated_at: Timestamp(now_ms),
183        },
184        TrustEnvelope {
185            level: TrustLevel::SelfAsserted,
186            signatures: Vec::new(),
187            moderation_state: ModerationState::Unreviewed,
188        },
189        Timestamp(now_ms),
190    )
191    .await
192}
193
194/// The user-facing browsing memory: open (unflushed) segments per owner plus
195/// the loaded trace corpus, with the design-pass reads over both.
196#[derive(Clone)]
197pub struct BrowsingMemory {
198    /// Stored traces (paired with their manifest ids) and adopted unsaved
199    /// traces (`None`), kept sorted by `ended_at_ms`.
200    traces: Vec<(Option<ManifestId>, BrowsingTrace)>,
201    /// Open segment per owner tag, flushed at `segment_size` events.
202    open: std::collections::BTreeMap<String, Vec<TraceEvent>>,
203    /// Events per segment before [`record_traversal`](Self::record_traversal)
204    /// asks for a flush. Configurable; quota and segmenting are policy, not
205    /// constants.
206    segment_size: usize,
207}
208
209impl BrowsingMemory {
210    /// An empty memory with the given segment size (events per flushed
211    /// trace).
212    pub fn new(segment_size: usize) -> Self {
213        Self {
214            traces: Vec::new(),
215            open: std::collections::BTreeMap::new(),
216            segment_size: segment_size.max(1),
217        }
218    }
219
220    /// Load every stored trace from the Store into a memory.
221    pub async fn load(store: &mut dyn Store, segment_size: usize) -> Result<Self> {
222        let mut memory = Self::new(segment_size);
223        let mut fetcher = NoFetcher;
224        for manifest in list_typed::<BrowsingTrace>(store).await? {
225            if let Some(trace) =
226                load_typed::<BrowsingTrace>(store, &mut fetcher, manifest.id).await?
227            {
228                memory.traces.push((Some(manifest.id), trace));
229            }
230        }
231        memory.sort_traces();
232        Ok(memory)
233    }
234
235    fn sort_traces(&mut self) {
236        self.traces.sort_by_key(|(_, t)| t.ended_at_ms);
237    }
238
239    /// Append a traversal to `owner`'s open segment. Returns `true` when the
240    /// segment has reached the configured size and wants a
241    /// [`flush`](Self::flush).
242    pub fn record_traversal(&mut self, owner: &str, event: TraceEvent) -> bool {
243        let segment = self.open.entry(owner.to_string()).or_default();
244        segment.push(event);
245        segment.len() >= self.segment_size
246    }
247
248    /// Flush every non-empty open segment as a stored trace. Returns the new
249    /// manifest ids.
250    pub async fn flush(&mut self, store: &mut dyn Store, now_ms: u64) -> Result<Vec<ManifestId>> {
251        let mut ids = Vec::new();
252        let owners: Vec<String> = self.open.keys().cloned().collect();
253        for owner in owners {
254            let events = self.open.remove(&owner).unwrap_or_default();
255            if events.is_empty() {
256                continue;
257            }
258            let trace = BrowsingTrace::from_events(owner, events);
259            let id = save_trace(store, &trace, now_ms).await?;
260            ids.push(id);
261            self.traces.push((Some(id), trace));
262        }
263        self.sort_traces();
264        Ok(ids)
265    }
266
267    /// Adopt an already-built trace into the in-memory corpus without
268    /// persisting it (projection and import outputs that the caller saves —
269    /// or not — on its own schedule).
270    pub fn adopt(&mut self, trace: BrowsingTrace) {
271        self.traces.push((None, trace));
272        self.sort_traces();
273    }
274
275    /// Every event, oldest first: stored corpus in trace order, then open
276    /// segments.
277    fn all_events(&self) -> impl Iterator<Item = &TraceEvent> {
278        self.traces
279            .iter()
280            .flat_map(|(_, t)| t.events.iter())
281            .chain(self.open.values().flatten())
282    }
283
284    /// The recent corridor: the last `n` traversals, returned in
285    /// chronological order — the path that led here.
286    pub fn recent_corridor(&self, n: usize) -> Vec<TraceEvent> {
287        let all: Vec<&TraceEvent> = self.all_events().collect();
288        let start = all.len().saturating_sub(n);
289        all[start..].iter().map(|e| (*e).clone()).collect()
290    }
291
292    /// Pages visited in `[start_ms, end_ms]`, chronological, deduplicated by
293    /// URL (first-seen title wins).
294    pub fn nodes_visited_in_window(&self, start_ms: u64, end_ms: u64) -> Vec<PageRef> {
295        let mut seen = std::collections::HashSet::new();
296        let mut out = Vec::new();
297        for event in self.all_events() {
298            if event.at_ms < start_ms || event.at_ms > end_ms {
299                continue;
300            }
301            if seen.insert(event.to.url.clone()) {
302                out.push(event.to.clone());
303            }
304        }
305        out
306    }
307
308    /// How often `a` and `b` were traversed together: the count of direct
309    /// traversals between them, in either direction. (Definition kept
310    /// deliberately narrow and edge-shaped so it cannot drift from
311    /// `node-lineage`'s aggregated edge view; broader togetherness measures
312    /// are a consumer's fold.)
313    pub fn co_occurrence(&self, a: &str, b: &str) -> u32 {
314        self.all_events()
315            .filter(|e| {
316                let Some(from) = &e.from else { return false };
317                (from.url == a && e.to.url == b) || (from.url == b && e.to.url == a)
318            })
319            .count() as u32
320    }
321
322    /// The loaded + adopted traces, oldest first.
323    pub fn traces(&self) -> impl Iterator<Item = &BrowsingTrace> {
324        self.traces.iter().map(|(_, t)| t)
325    }
326
327    /// Keep the `keep_n` most recent *stored* traces and delete the
328    /// manifests of older ones (blob bytes await the explicit GC pass).
329    /// Adopted unsaved traces are untouched — there is nothing stored to
330    /// age out. Returns how many manifests were deleted.
331    pub async fn apply_quota(&mut self, store: &mut dyn Store, keep_n: usize) -> Result<usize> {
332        let stored: Vec<ManifestId> = self.traces.iter().filter_map(|(id, _)| *id).collect();
333        if stored.len() <= keep_n {
334            return Ok(0);
335        }
336        // traces is sorted oldest-first, so the overflow is the head.
337        let overflow: Vec<ManifestId> = stored[..stored.len() - keep_n].to_vec();
338        let mut deleted = 0;
339        for id in &overflow {
340            if delete_manifest(store, *id).await? {
341                deleted += 1;
342            }
343        }
344        self.traces
345            .retain(|(id, _)| id.is_none_or(|id| !overflow.contains(&id)));
346        Ok(deleted)
347    }
348
349    /// Forget every trace mentioning `url` (as either end of any event): delete its
350    /// stored manifest and drop it from the loaded corpus and any open segment.
351    /// Returns how many traces were forgotten. The `eidetic-search` index is rebuilt
352    /// from this corpus per query, so a forgotten trace also leaves the index — a
353    /// forget that left the index behind would not be a forget. (Capture plan C4.)
354    pub async fn forget_url(&mut self, store: &mut dyn Store, url: &str) -> Result<usize> {
355        let mentions = |trace: &BrowsingTrace| {
356            trace
357                .events
358                .iter()
359                .any(|e| e.to.url == url || e.from.as_ref().is_some_and(|f| f.url == url))
360        };
361        let mut forgotten = 0;
362        let mut remaining = Vec::with_capacity(self.traces.len());
363        for (id, trace) in std::mem::take(&mut self.traces) {
364            if mentions(&trace) {
365                if let Some(id) = id {
366                    delete_manifest(store, id).await?;
367                }
368                forgotten += 1;
369            } else {
370                remaining.push((id, trace));
371            }
372        }
373        self.traces = remaining;
374        // Drop matching events from any unflushed open segment too.
375        for events in self.open.values_mut() {
376            events.retain(|e| !(e.to.url == url || e.from.as_ref().is_some_and(|f| f.url == url)));
377        }
378        Ok(forgotten)
379    }
380}
381
382#[cfg(test)]
383mod tests;