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}