Skip to main content

kernel/
persistence.rs

1// Copyright 2026 Mark Alan Boykin
2// This Source Code Form is subject to the terms of the Mozilla Public
3// License, v. 2.0. If a copy of the MPL was not distributed with this
4// file, You can obtain one at https://mozilla.org/MPL/2.0/.
5// SPDX-License-Identifier: MPL-2.0
6
7//! Serializable types for graph persistence.
8//!
9//! These types define the portable snapshot and edge schema shared by all hosts.
10//! Storage adapters (fjall, IndexedDB, etc.) live in the host, not here.
11
12use std::collections::BTreeMap;
13
14use rkyv::{Archive, Deserialize, Serialize};
15
16use crate::types::{ImageRef, ImageRole};
17
18// Field-layer DTOs live in their own file (per-file ceiling) but belong to this
19// module's vocabulary; re-export so `crate::persistence::PersistedField` resolves.
20pub use crate::persistence_fields::{
21    PersistedCoupling, PersistedCouplingResponse, PersistedField, PersistedFieldExtent,
22    PersistedFieldLifecycle, PersistedNodeSelector,
23};
24
25// Edge persistence types live in their own file (per-file ceiling); re-exported
26// here so `crate::persistence::PersistedEdge` etc. continue to resolve.
27pub use crate::persistence_edge::{
28    PersistedArrangementEdgeData, PersistedArrangementSubKind, PersistedContainmentEdgeData,
29    PersistedContainmentSubKind, PersistedEdge, PersistedEdgeAssertion, PersistedEdgeFamily,
30    PersistedImportedEdgeData, PersistedImportedSubKind, PersistedNavigationTrigger,
31    PersistedProvenanceEdgeData, PersistedProvenanceSubKind, PersistedRelationSelector,
32    PersistedSemanticEdgeData, PersistedSemanticStatement, PersistedSemanticSubKind,
33    PersistedTraversalEdgeData, PersistedTraversalMetrics, PersistedTraversalRecord,
34};
35
36use crate::graph::SharedNavigationMemory;
37use crate::types::{
38    FrameLayoutHint, ImportRecord, NodeClassification, NodeDerivation, NodeImportProvenance,
39    NodeProperty, NodeTagPresentationState,
40};
41
42// ---------------------------------------------------------------------------
43// Address persistence types
44// ---------------------------------------------------------------------------
45
46/// Address type hint for persistence (mirrors `AddressKind` in the graph model).
47///
48/// Deprecated: superseded by [`PersistedAddress`]. Kept for rkyv backward compatibility
49/// with old snapshots. No new values are written.
50#[derive(
51    Archive,
52    Serialize,
53    Deserialize,
54    Clone,
55    Copy,
56    Debug,
57    PartialEq,
58    Default,
59    serde::Serialize,
60    serde::Deserialize,
61)]
62#[rkyv(derive(Debug, PartialEq))]
63pub enum PersistedAddressKind {
64    #[default]
65    Http,
66    File,
67    Data,
68    GraphshellClip,
69    Directory,
70    Unknown,
71}
72
73/// Typed address for persistence — carries both the URL scheme classification
74/// and the raw URL string.
75///
76/// All variants store the full URL string so that [`PersistedAddress::as_url_str`]
77/// is always a round-trip identity.
78#[derive(
79    Archive, Serialize, Deserialize, Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize,
80)]
81#[rkyv(derive(Debug, PartialEq))]
82pub enum PersistedAddress {
83    Http(String),
84    File(String),
85    Data(String),
86    /// Clip route (`verso://clip/<id>` or `graphshell://clip/<id>`). Stores the full URL.
87    Clip(String),
88    Directory(String),
89    Custom(String),
90}
91
92impl Default for PersistedAddress {
93    /// Fallback used when deserializing old snapshots that lack the `address` field.
94    /// The load path detects the empty URL and uses the legacy `url` field instead.
95    fn default() -> Self {
96        PersistedAddress::Custom(String::new())
97    }
98}
99
100impl PersistedAddress {
101    /// Return the raw URL string for this address.
102    pub fn as_url_str(&self) -> &str {
103        match self {
104            PersistedAddress::Http(s)
105            | PersistedAddress::File(s)
106            | PersistedAddress::Data(s)
107            | PersistedAddress::Clip(s)
108            | PersistedAddress::Directory(s)
109            | PersistedAddress::Custom(s) => s.as_str(),
110        }
111    }
112}
113
114impl ArchivedPersistedAddress {
115    /// Return the raw URL string from the archived address.
116    pub fn as_url_str(&self) -> &str {
117        match self {
118            ArchivedPersistedAddress::Http(s)
119            | ArchivedPersistedAddress::File(s)
120            | ArchivedPersistedAddress::Data(s)
121            | ArchivedPersistedAddress::Clip(s)
122            | ArchivedPersistedAddress::Directory(s)
123            | ArchivedPersistedAddress::Custom(s) => s.as_str(),
124        }
125    }
126}
127
128// ---------------------------------------------------------------------------
129// Node persistence types
130// ---------------------------------------------------------------------------
131
132/// Persisted per-node session fidelity state.
133#[derive(Archive, Serialize, Deserialize, Clone, Debug, serde::Serialize, serde::Deserialize)]
134pub struct PersistedNodeSessionState {
135    pub scroll_x: Option<f32>,
136    pub scroll_y: Option<f32>,
137    pub form_draft: Option<String>,
138    #[serde(default)]
139    pub last_visited_ms: Option<u64>,
140}
141
142/// Persisted node.
143#[derive(Archive, Serialize, Deserialize, Clone, Debug, serde::Serialize, serde::Deserialize)]
144pub struct PersistedNode {
145    /// Stable node identity.
146    pub node_id: String,
147
148    /// Typed address — canonical source of the node URL since Stage C.2.
149    #[serde(default)]
150    pub address: PersistedAddress,
151
152    /// Legacy URL field — written alongside `address` for backward compatibility.
153    #[serde(default)]
154    pub url: String,
155
156    #[serde(default)]
157    pub cached_host: Option<String>,
158    pub title: String,
159    #[serde(default)]
160    pub tags: Vec<String>,
161    #[serde(default)]
162    pub tag_presentation: NodeTagPresentationState,
163    #[serde(default)]
164    pub import_provenance: Vec<NodeImportProvenance>,
165    pub is_pinned: bool,
166    /// Content-addressed preview imagery by role. Snapshots carry handles,
167    /// never pixels (node-image externalization, phase 2).
168    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
169    pub images: BTreeMap<ImageRole, ImageRef>,
170
171    // --- Legacy inline imagery: deserialize-only migration shadows ---------
172    //
173    // Snapshots written before phase 2 carry raw PNG/RGBA bytes here. They
174    // load, get externalized into the blob store, and are never written back:
175    // `skip_serializing` means a re-saved snapshot emits references only. Once
176    // no snapshot in the wild carries them these can go.
177    #[serde(default, skip_serializing, rename = "thumbnail_png")]
178    pub legacy_thumbnail_png: Option<Vec<u8>>,
179    #[serde(default, skip_serializing, rename = "thumbnail_width")]
180    pub legacy_thumbnail_width: u32,
181    #[serde(default, skip_serializing, rename = "thumbnail_height")]
182    pub legacy_thumbnail_height: u32,
183    #[serde(default, skip_serializing, rename = "favicon_rgba")]
184    pub legacy_favicon_rgba: Option<Vec<u8>>,
185    #[serde(default, skip_serializing, rename = "favicon_width")]
186    pub legacy_favicon_width: u32,
187    #[serde(default, skip_serializing, rename = "favicon_height")]
188    pub legacy_favicon_height: u32,
189    pub session_state: Option<PersistedNodeSessionState>,
190    /// Optional MIME type hint; drives renderer selection.
191    pub mime_hint: Option<String>,
192    /// Durable provenance-bearing classification records (Stage A enrichment).
193    #[serde(default)]
194    pub classifications: Vec<NodeClassification>,
195    /// Durable split arrangement annotations for frame-anchor nodes.
196    #[serde(default)]
197    pub frame_layout_hints: Vec<FrameLayoutHint>,
198    /// Durable split-offer suppression for frame-anchor nodes.
199    #[serde(default)]
200    pub frame_split_offer_suppressed: bool,
201    /// Open literal properties (non-curated literals preserved on ingest).
202    #[serde(default)]
203    pub properties: Vec<NodeProperty>,
204    /// Cross-graph derivation provenance (copied/forked from another graph).
205    #[serde(default)]
206    pub derivations: Vec<NodeDerivation>,
207    /// Inline authored content body — a knot note's djot source. `#[serde(default)]`
208    /// so snapshots written before the inline body load with `None`. (Djot editor
209    /// reframe, slice 3.)
210    #[serde(default)]
211    pub body: Option<String>,
212    /// The app-launch session number this node was last navigated in. `0` (the
213    /// `#[serde(default)]` for snapshots written before this field existed) means
214    /// "never stamped" — by-sessions eviction treats that as undated, never evicted.
215    /// (Alembic B5.)
216    #[serde(default)]
217    pub last_session_visited: u64,
218    /// The nested graph this node bears, as a log-id string (`Node.nested`;
219    /// the one-node containment ruling). `#[serde(default)]` so snapshots
220    /// written before containment load with `None`.
221    #[serde(default)]
222    pub nested: Option<String>,
223    /// Content-addressed out-of-line representation. Hex keeps graph.json
224    /// inspectable and lets snapshots written before this field load as None.
225    #[serde(default, skip_serializing_if = "Option::is_none")]
226    pub content_hash: Option<String>,
227}
228
229/// Ordinary metadata on a resource, encoded without a JSON codec assumption.
230#[derive(
231    Archive,
232    Serialize,
233    Deserialize,
234    Clone,
235    Debug,
236    PartialEq,
237    Eq,
238    serde::Serialize,
239    serde::Deserialize,
240)]
241pub struct PersistedResourceFacet {
242    pub facet: String,
243    pub value_json: String,
244}
245
246/// One resource's identity and metadata; its edges are stored separately.
247#[derive(
248    Archive,
249    Serialize,
250    Deserialize,
251    Clone,
252    Debug,
253    PartialEq,
254    Eq,
255    serde::Serialize,
256    serde::Deserialize,
257)]
258pub struct PersistedResourceRecord {
259    pub canonical_iri: String,
260    pub facets: Vec<PersistedResourceFacet>,
261}
262
263/// A surface's current resource association, with explicit strata.
264#[derive(
265    Archive,
266    Serialize,
267    Deserialize,
268    Clone,
269    Debug,
270    PartialEq,
271    Eq,
272    serde::Serialize,
273    serde::Deserialize,
274)]
275pub struct PersistedShownResource {
276    pub surface_id: String,
277    pub resource_id: String,
278}
279
280/// Full graph snapshot for periodic saves.
281///
282/// Carries both `rkyv` derives (for compact binary persistence —
283/// the original intent) and `serde` derives (added 2026-05-11 so
284/// `host-runtime::session_graph_store` can persist sessions
285/// as hand-inspectable JSON). All sub-types (`PersistedNode`,
286/// `PersistedEdge`, `ImportRecord`) already carry both.
287#[derive(Archive, Serialize, Deserialize, Clone, Debug, serde::Serialize, serde::Deserialize)]
288pub struct GraphSnapshot {
289    pub nodes: Vec<PersistedNode>,
290    pub edges: Vec<PersistedEdge>,
291    pub import_records: Vec<ImportRecord>,
292    pub timestamp_secs: u64,
293    /// Field-layer truth (field-system Phase 2). `#[serde(default)]` so snapshots
294    /// written before the field layer load with an empty one.
295    #[serde(default)]
296    pub fields: Vec<PersistedField>,
297    #[serde(default)]
298    pub couplings: Vec<PersistedCoupling>,
299    /// The graph's shared navigation history (one visit space, owner per node —
300    /// the (b) anchor design). `#[serde(default)]` so snapshots written before the
301    /// shared-history migration (per-node `navigation_memory`, now ignored) load
302    /// with an empty history rather than failing.
303    #[serde(default)]
304    pub navigation: SharedNavigationMemory,
305    #[serde(default)]
306    pub resources: Vec<PersistedResourceRecord>,
307    #[serde(default)]
308    pub resource_edges: Vec<PersistedEdge>,
309    #[serde(default)]
310    pub shown_resources: Vec<PersistedShownResource>,
311    /// Assertion-column format: `0` is the legacy sidecar layout and `1` is
312    /// the canonical all-family assertion-record layout.
313    #[serde(default, skip_serializing_if = "is_zero_u32")]
314    pub assertion_schema: u32,
315}
316
317fn is_zero_u32(value: &u32) -> bool {
318    *value == 0
319}
320
321impl GraphSnapshot {
322    /// How many nodes still carry pre-phase-2 inline image bytes.
323    ///
324    /// Conversion into a `Graph` keeps references only, so a non-zero count
325    /// here means the host has not run its externalization pass yet and those
326    /// pixels are about to be dropped. Assert it is zero after migrating; a
327    /// silent loss is the failure mode this exists to make loud.
328    pub fn legacy_image_count(&self) -> usize {
329        self.nodes
330            .iter()
331            .filter(|n| n.legacy_thumbnail_png.is_some() || n.legacy_favicon_rgba.is_some())
332            .count()
333    }
334
335    /// How many nodes still carry optional metadata in the pre-facet columns.
336    ///
337    /// A non-zero count asks the host to persist the imported facet store and
338    /// re-save the graph immediately. Canonical snapshots keep these columns
339    /// empty; the values survive only in `facets.json`.
340    pub fn legacy_node_facet_count(&self) -> usize {
341        self.nodes
342            .iter()
343            .filter(|node| {
344                node.is_pinned
345                    || !node.frame_layout_hints.is_empty()
346                    || node.frame_split_offer_suppressed
347                    || node.tag_presentation != NodeTagPresentationState::default()
348                    || !node.import_provenance.is_empty()
349                    || !node.classifications.is_empty()
350                    || !node.properties.is_empty()
351                    || !node.derivations.is_empty()
352                    || node.last_session_visited != 0
353                    || node
354                        .session_state
355                        .as_ref()
356                        .is_some_and(|state| state.last_visited_ms.is_some())
357            })
358            .count()
359    }
360}
361
362// ---------------------------------------------------------------------------
363// Node audit event taxonomy (Slice 63 — promoted from
364// `services/persistence/types.rs`)
365// ---------------------------------------------------------------------------
366
367/// The kind of node metadata or lifecycle event recorded in an audit log entry.
368///
369/// Each variant carries only the new value (not the old one). The sequence of
370/// audit events in the WAL provides the full history; diffing adjacent entries
371/// to recover the "from" value is a query-time operation.
372///
373/// Promoted to kernel in Slice 63 so it can travel with the rest
374/// of the persistence type taxonomy and be referenced by the (eventually
375/// portable) `GraphMutation` / `GraphIntent` enums without needing the
376/// shell-side `services/persistence` module in scope.
377#[derive(
378    Archive,
379    Serialize,
380    Deserialize,
381    Clone,
382    Debug,
383    PartialEq,
384    Eq,
385    serde::Serialize,
386    serde::Deserialize,
387)]
388#[rkyv(derive(Debug))]
389pub enum NodeAuditEventKind {
390    /// Node title was changed. Records the new title.
391    TitleChanged { new_title: String },
392    /// A tag was added to the node.
393    Tagged { tag: String },
394    /// A tag was removed from the node.
395    Untagged { tag: String },
396    /// Node was pinned.
397    Pinned,
398    /// Node was unpinned.
399    Unpinned,
400    /// Node URL was changed out-of-band (not via NavigateNode navigation).
401    /// Used when a node's URL is set directly rather than through navigation.
402    UrlChanged { new_url: String },
403    /// A viewer or workflow recorded a notable node-scoped action.
404    ActionRecorded { action: String, detail: String },
405    /// Node was tombstoned (soft-deleted).
406    Tombstoned,
407    /// Node was restored from tombstone state.
408    Restored,
409}