Skip to main content

kernel/graph/
apply.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4use chartulary::stemma::TransitionKind;
5use euclid::default::Point2D;
6use uuid::Uuid;
7
8use super::{
9    Coupling, CouplingId, EdgeAssertion, EdgeKey, Field, FieldId, FrameLayoutHint, Graph,
10    NavigationTrigger, NodeKey, RelationSelector, SemanticSubKind,
11    capture::{
12        CapturedDelta, coupling_from_persisted, field_from_persisted,
13        persisted_coupling_from_coupling, persisted_field_from_field, record_captured_delta,
14    },
15};
16use crate::persistence::{PersistedCoupling, PersistedField};
17use crate::types::{
18    BadgeIcon, ClassificationScheme, ClassificationStatus, GraphScope, ImageRef, ImageRole,
19    ImportRecord, NodeClassification, NodeDerivation, NodeImportProvenance, NodeProperty,
20};
21
22#[derive(Debug, Clone)]
23pub enum GraphDelta {
24    AddNode {
25        id: Option<Uuid>,
26        url: String,
27        position: Point2D<f32>,
28    },
29    AssertRelation {
30        from: NodeKey,
31        to: NodeKey,
32        assertion: EdgeAssertion,
33    },
34    RemoveNode {
35        key: NodeKey,
36    },
37    ReplayAddNodeWithIdIfMissing {
38        id: Uuid,
39        url: String,
40        position: Point2D<f32>,
41    },
42    ReplayAssertRelationByIds {
43        from_id: Uuid,
44        to_id: Uuid,
45        assertion: EdgeAssertion,
46    },
47    ReplayRemoveNodeById {
48        node_id: Uuid,
49    },
50    ReplayRetractRelationsByIds {
51        from_id: Uuid,
52        to_id: Uuid,
53        selector: RelationSelector,
54    },
55    ReplayAppendTraversalByIds {
56        from_id: Uuid,
57        to_id: Uuid,
58        trigger: NavigationTrigger,
59        timestamp_ms: u64,
60    },
61    ReplaySetNodeTitleById {
62        node_id: Uuid,
63        title: String,
64    },
65    ReplaySetNodeUrlById {
66        node_id: Uuid,
67        new_url: String,
68    },
69    ReplaySetNodeImageById {
70        node_id: Uuid,
71        role: ImageRole,
72        image: ImageRef,
73    },
74    ReplaySetNodeMimeHintById {
75        node_id: Uuid,
76        mime_hint: Option<String>,
77    },
78    ReplaySetNodeContentById {
79        node_id: Uuid,
80        content: Option<super::ContentHash>,
81    },
82    ReplaySetNodeNestedById {
83        node_id: Uuid,
84        nested: Option<String>,
85    },
86    ReplaySetNodePinnedById {
87        node_id: Uuid,
88        is_pinned: bool,
89    },
90    ReplaySetNodeFacetById {
91        node_id: Uuid,
92        facet: String,
93        value: serde_json::Value,
94    },
95    ReplayRemoveNodeFacetById {
96        node_id: Uuid,
97        facet: String,
98    },
99    ReplayInsertNodeTagById {
100        node_id: Uuid,
101        tag: String,
102    },
103    ReplayRemoveNodeTagById {
104        node_id: Uuid,
105        tag: String,
106    },
107    ReplaySetNodeBodyById {
108        node_id: Uuid,
109        body: Option<String>,
110    },
111    ReplayNavigateNodeById {
112        node_id: Uuid,
113        url: String,
114        transition: TransitionKind,
115        timestamp_ms: u64,
116        last_session_visited: u64,
117    },
118    ReplayBranchHistoryByIds {
119        child_id: Uuid,
120        parent_id: Uuid,
121    },
122    ReplayNodeHistoryBackById {
123        node_id: Uuid,
124        timestamp_ms: u64,
125    },
126    ReplayNodeHistoryForwardById {
127        node_id: Uuid,
128        timestamp_ms: u64,
129    },
130    ReplayAppendNodePropertyById {
131        node_id: Uuid,
132        property: NodeProperty,
133    },
134    ReplayAddNodeClassificationById {
135        node_id: Uuid,
136        classification: NodeClassification,
137    },
138    ReplayRemoveNodeClassificationById {
139        node_id: Uuid,
140        scheme: ClassificationScheme,
141        value: String,
142    },
143    ReplaySetNodeClassificationStatusById {
144        node_id: Uuid,
145        scheme: ClassificationScheme,
146        value: String,
147        status: ClassificationStatus,
148    },
149    ReplaySetNodePrimaryClassificationById {
150        node_id: Uuid,
151        scheme: ClassificationScheme,
152        value: String,
153    },
154    ReplayRecordNodeDerivationById {
155        node_id: Uuid,
156        derivation: NodeDerivation,
157    },
158    ReplaySetNodeTagIconOverrideById {
159        node_id: Uuid,
160        tag: String,
161        icon: Option<BadgeIcon>,
162    },
163    ReplaySetEdgeSemanticPredicateByIds {
164        from_id: Uuid,
165        to_id: Uuid,
166        predicate: Option<String>,
167    },
168    ReplayAssertSemanticPredicateByIds {
169        from_id: Uuid,
170        to_id: Uuid,
171        predicate: String,
172    },
173    ReplayAppendFrameLayoutHintById {
174        node_id: Uuid,
175        hint: FrameLayoutHint,
176    },
177    ReplayRemoveFrameLayoutHintById {
178        node_id: Uuid,
179        hint_index: usize,
180    },
181    ReplayMoveFrameLayoutHintById {
182        node_id: Uuid,
183        from_index: usize,
184        to_index: usize,
185    },
186    ReplaySetFrameSplitOfferSuppressedById {
187        node_id: Uuid,
188        suppressed: bool,
189    },
190    ReplayUpdateNodeHistoryById {
191        node_id: Uuid,
192        entries: Vec<String>,
193        current_index: usize,
194    },
195    ReplaySetImportRecords {
196        import_records: Vec<ImportRecord>,
197    },
198    ReplayTouchNodeLastVisitedById {
199        node_id: Uuid,
200        timestamp_ms: u64,
201    },
202    RetractRelations {
203        from: NodeKey,
204        to: NodeKey,
205        selector: RelationSelector,
206    },
207    /// Append a traversal event to the `from → to` edge (creating the
208    /// edge if absent). `timestamp_ms = None` stamps now-via-the-kernel;
209    /// `Some(t)` uses the supplied timestamp (importers, replay).
210    AppendTraversal {
211        from: NodeKey,
212        to: NodeKey,
213        trigger: NavigationTrigger,
214        timestamp_ms: Option<u64>,
215    },
216    SetNodeTitle {
217        key: NodeKey,
218        title: String,
219    },
220    SetNodeUrl {
221        key: NodeKey,
222        new_url: String,
223    },
224    /// Attach a stored image reference under a role. The host stores the blob
225    /// first and passes the handle; no pixels travel through the delta spine
226    /// (node-image externalization, phase 3).
227    SetNodeImage {
228        key: NodeKey,
229        role: ImageRole,
230        image: ImageRef,
231    },
232    SetNodeMimeHint {
233        key: NodeKey,
234        mime_hint: Option<String>,
235    },
236    /// Attach a representation already deposited in a muniment blob store.
237    SetNodeContent {
238        key: NodeKey,
239        content: Option<super::ContentHash>,
240    },
241    SetNodeNested {
242        key: NodeKey,
243        nested: Option<codicil::LogId>,
244    },
245    SetNodePinned {
246        key: NodeKey,
247        is_pinned: bool,
248    },
249    /// Set one arbitrary, namespaced facet through the durable delta spine.
250    SetNodeFacet {
251        key: NodeKey,
252        facet: String,
253        value: serde_json::Value,
254    },
255    /// Remove one arbitrary, namespaced facet through the durable delta spine.
256    RemoveNodeFacet {
257        key: NodeKey,
258        facet: String,
259    },
260    AppendFrameLayoutHint {
261        key: NodeKey,
262        hint: FrameLayoutHint,
263    },
264    RemoveFrameLayoutHint {
265        key: NodeKey,
266        hint_index: usize,
267    },
268    MoveFrameLayoutHint {
269        key: NodeKey,
270        from_index: usize,
271        to_index: usize,
272    },
273    SetFrameSplitOfferSuppressed {
274        key: NodeKey,
275        suppressed: bool,
276    },
277    /// Replace a node's persisted navigation history (entries + current
278    /// index). The clamping rule is: `current_index` is treated as `0` when
279    /// `entries` is empty, otherwise it is clamped to `entries.len() - 1`.
280    /// Sole sanctioned write surface for `Node::history`; the underlying
281    /// `Graph` setter is `pub(crate)` so this delta is the only way to
282    /// mutate the field from outside `kernel`.
283    UpdateNodeHistory {
284        key: NodeKey,
285        entries: Vec<String>,
286        current_index: usize,
287    },
288    /// Replace the durable import-record table with a normalized whole-table snapshot.
289    SetImportRecords {
290        import_records: Vec<ImportRecord>,
291    },
292    /// Delete one durable import record by id.
293    DeleteImportRecord {
294        record_id: String,
295    },
296    /// Suppress or unsuppress one node membership within an import record.
297    SetImportRecordMembershipSuppressed {
298        record_id: String,
299        key: NodeKey,
300        suppressed: bool,
301    },
302    /// Replace one node's import provenance; the kernel rebuilds import records from it.
303    SetNodeImportProvenance {
304        key: NodeKey,
305        import_provenance: Vec<NodeImportProvenance>,
306    },
307    /// Stamp one node's last-visited clock from the kernel clock.
308    TouchNodeLastVisited {
309        key: NodeKey,
310    },
311    // --- Write-path migration (2026-07-01): the variants below complete the
312    // Phase 6.5 boundary. Every primitive durable mutation shell/runtime code
313    // performs now has a delta; the raw mutators are `pub(crate)`. ---
314    /// Navigate a node in place: record the visit in its own browse history and
315    /// update its Primary URL. No new node, no edge.
316    NavigateNode {
317        key: NodeKey,
318        url: String,
319    },
320    /// Anchor a freshly-minted `child` node's history under `parent`'s current
321    /// visit (the navigated-from anchor; call before the child's first navigate).
322    BranchHistory {
323        child: NodeKey,
324        parent: NodeKey,
325    },
326    /// Step a node back one visit in its own history (result:
327    /// [`GraphDeltaResult::HistoryStepped`] carries the revealed URL).
328    NodeHistoryBack {
329        key: NodeKey,
330    },
331    /// Step a node forward one visit in its own history.
332    NodeHistoryForward {
333        key: NodeKey,
334    },
335    /// Add a durable semantic tag (also appends to the presentation order).
336    InsertNodeTag {
337        key: NodeKey,
338        tag: String,
339    },
340    /// Remove a durable semantic tag (also drops its presentation entries).
341    RemoveNodeTag {
342        key: NodeKey,
343        tag: String,
344    },
345    /// Set (or clear) a node's inline authored content body (knot note source).
346    SetNodeBody {
347        key: NodeKey,
348        body: Option<String>,
349    },
350    /// Append an open literal property (dedup by exact predicate+value pair).
351    AppendNodeProperty {
352        key: NodeKey,
353        property: NodeProperty,
354    },
355    /// Add a provenance-bearing classification record (dedup by scheme+value).
356    AddNodeClassification {
357        key: NodeKey,
358        classification: NodeClassification,
359    },
360    /// Remove a classification record identified by `(scheme, value)`.
361    RemoveNodeClassification {
362        key: NodeKey,
363        scheme: ClassificationScheme,
364        value: String,
365    },
366    /// Update the status of a classification record identified by `(scheme, value)`.
367    SetNodeClassificationStatus {
368        key: NodeKey,
369        scheme: ClassificationScheme,
370        value: String,
371        status: ClassificationStatus,
372    },
373    /// Promote one classification record to primary within its scheme.
374    SetNodePrimaryClassification {
375        key: NodeKey,
376        scheme: ClassificationScheme,
377        value: String,
378    },
379    /// Record cross-graph / extraction derivation provenance on a node.
380    RecordNodeDerivation {
381        key: NodeKey,
382        derivation: NodeDerivation,
383    },
384    /// Set or clear a tag-icon override for a durable user tag.
385    SetNodeTagIconOverride {
386        key: NodeKey,
387        tag: String,
388        icon: Option<BadgeIcon>,
389    },
390    /// Set (or clear) the canonical semantic-predicate IRI on an existing edge.
391    SetEdgeSemanticPredicate {
392        edge: EdgeKey,
393        predicate: Option<String>,
394    },
395    /// Assert a plain semantic edge carrying a raw predicate IRI (the
396    /// unrecognized-predicate ingest path), creating the edge if absent.
397    AssertSemanticPredicate {
398        from: NodeKey,
399        to: NodeKey,
400        predicate: String,
401    },
402    ReplayAddField {
403        field: PersistedField,
404    },
405    ReplayRetireFieldById {
406        field_id: String,
407    },
408    ReplayAddCoupling {
409        coupling: PersistedCoupling,
410    },
411    ReplaySetFieldCouplingStrengthByFieldId {
412        field_id: String,
413        strength: f32,
414    },
415    ReplayActivateFieldById {
416        field_id: String,
417    },
418    ReplayRetractCouplingById {
419        coupling_id: String,
420    },
421    /// Add (or replace by id) a field — field-layer truth.
422    AddField {
423        field: Field,
424    },
425    /// Retire a field (lifecycle to Retired; couplings stop evaluating).
426    RetireField {
427        id: FieldId,
428    },
429    /// Add (or replace by id) a coupling binding a field to a node selector.
430    AddCoupling {
431        coupling: Coupling,
432    },
433    /// Set the strength of every coupling bound to `field`.
434    SetFieldCouplingStrength {
435        field: FieldId,
436        strength: f32,
437    },
438    /// Reactivate a retired field.
439    ActivateField {
440        id: FieldId,
441    },
442    /// Remove one coupling binding by id.
443    RetractCoupling {
444        id: CouplingId,
445    },
446}
447
448#[derive(Debug, Clone, PartialEq, Eq)]
449pub enum GraphDeltaResult {
450    NodeAdded(NodeKey),
451    NodeMaybeAdded(Option<NodeKey>),
452    EdgeAdded(Option<EdgeKey>),
453    NodeRemoved(bool),
454    EdgesRemoved(usize),
455    TraversalAppended(bool),
456    NodeMetadataUpdated(bool),
457    NodeUrlUpdated(Option<String>),
458    /// A history back/forward step: the revealed URL, or `None` at the
459    /// root/tip (the cursor did not move).
460    HistoryStepped(Option<String>),
461    /// A field-layer mutation: whether anything actually changed.
462    FieldChanged(bool),
463    /// An import-record mutation: whether anything actually changed.
464    ImportRecordsUpdated(bool),
465    /// A mutation with no observable result (e.g. navigate, branch-history).
466    Applied,
467}
468
469fn capture_resolved_import_records(graph: &Graph) {
470    record_captured_delta(&CapturedDelta::ReplaySetImportRecords {
471        import_records: graph.import_records().to_vec(),
472    });
473}
474
475fn set_node_facet(graph: &mut Graph, key: NodeKey, facet: &str, value: serde_json::Value) -> bool {
476    let Some(node_id) = graph.get_node(key).map(|node| node.id) else {
477        return false;
478    };
479    let facet = chartulary::FacetId::new(facet);
480    if graph.facets().get(&node_id, &facet) == Some(&value) {
481        return false;
482    }
483    graph
484        .facets
485        .set(node_id, facet, value, &chartulary::AcceptAll)
486        .expect("AcceptAll cannot reject a graph facet");
487    true
488}
489
490fn remove_node_facet(graph: &mut Graph, key: NodeKey, facet: &str) -> bool {
491    let Some(node_id) = graph.get_node(key).map(|node| node.id) else {
492        return false;
493    };
494    graph
495        .facets
496        .remove(&node_id, &chartulary::FacetId::new(facet))
497        .is_some()
498}
499
500pub fn apply_graph_delta(graph: &mut Graph, delta: GraphDelta) -> GraphDeltaResult {
501    match delta {
502        GraphDelta::AddNode { id, url, position } => {
503            let capture_url = url.clone();
504            let capture_position = [position.x, position.y];
505            let key = match id {
506                Some(id) => graph.add_node_with_id(id, url, position),
507                #[cfg(not(target_arch = "wasm32"))]
508                None => graph.add_node(url, position),
509                #[cfg(target_arch = "wasm32")]
510                None => panic!("AddNode without an explicit id is not supported on WASM"),
511            };
512            if let Some(node) = graph.get_node(key) {
513                record_captured_delta(&CapturedDelta::ReplayAddNodeWithIdIfMissing {
514                    id: node.id.to_string(),
515                    url: capture_url,
516                    position: capture_position,
517                });
518            }
519            GraphDeltaResult::NodeAdded(key)
520        }
521        GraphDelta::AssertRelation {
522            from,
523            to,
524            assertion,
525        } => {
526            let from_id = graph.get_node(from).map(|node| node.id);
527            let to_id = graph.get_node(to).map(|node| node.id);
528            let capture_assertion = assertion.clone();
529            let edge = graph.assert_relation(from, to, assertion);
530            if edge.is_some()
531                && let (Some(from_id), Some(to_id)) = (from_id, to_id)
532            {
533                record_captured_delta(&CapturedDelta::ReplayAssertRelationByIds {
534                    from_id: from_id.to_string(),
535                    to_id: to_id.to_string(),
536                    assertion: capture_assertion,
537                });
538            }
539            GraphDeltaResult::EdgeAdded(edge)
540        }
541        GraphDelta::RemoveNode { key } => {
542            let node_id = graph.get_node(key).map(|node| node.id);
543            let removed = graph.remove_node(key);
544            if removed && let Some(node_id) = node_id {
545                record_captured_delta(&CapturedDelta::ReplayRemoveNodeById {
546                    node_id: node_id.to_string(),
547                });
548            }
549            GraphDeltaResult::NodeRemoved(removed)
550        }
551        GraphDelta::ReplayAddNodeWithIdIfMissing { id, url, position } => {
552            let capture_url = url.clone();
553            let capture_position = [position.x, position.y];
554            let added = graph.replay_add_node_with_id_if_missing(id, url, position);
555            if added.is_some() {
556                record_captured_delta(&CapturedDelta::ReplayAddNodeWithIdIfMissing {
557                    id: id.to_string(),
558                    url: capture_url,
559                    position: capture_position,
560                });
561            }
562            GraphDeltaResult::NodeMaybeAdded(added)
563        }
564        GraphDelta::ReplayAssertRelationByIds {
565            from_id,
566            to_id,
567            assertion,
568        } => {
569            let capture_assertion = assertion.clone();
570            let edge = graph.replay_assert_relation_by_ids(from_id, to_id, assertion);
571            if edge.is_some() {
572                record_captured_delta(&CapturedDelta::ReplayAssertRelationByIds {
573                    from_id: from_id.to_string(),
574                    to_id: to_id.to_string(),
575                    assertion: capture_assertion,
576                });
577            }
578            GraphDeltaResult::EdgeAdded(edge)
579        }
580        GraphDelta::ReplayRemoveNodeById { node_id } => {
581            let removed = graph.replay_remove_node_by_id(node_id);
582            if removed {
583                record_captured_delta(&CapturedDelta::ReplayRemoveNodeById {
584                    node_id: node_id.to_string(),
585                });
586            }
587            GraphDeltaResult::NodeRemoved(removed)
588        }
589        GraphDelta::ReplayRetractRelationsByIds {
590            from_id,
591            to_id,
592            selector,
593        } => {
594            let removed = graph.replay_retract_relations_by_ids(from_id, to_id, selector);
595            if removed > 0 {
596                record_captured_delta(&CapturedDelta::ReplayRetractRelationsByIds {
597                    from_id: from_id.to_string(),
598                    to_id: to_id.to_string(),
599                    selector,
600                });
601            }
602            GraphDeltaResult::EdgesRemoved(removed)
603        }
604        GraphDelta::ReplayAppendTraversalByIds {
605            from_id,
606            to_id,
607            trigger,
608            timestamp_ms,
609        } => {
610            let appended =
611                graph.replay_append_traversal_by_ids(from_id, to_id, trigger, timestamp_ms);
612            if appended {
613                record_captured_delta(&CapturedDelta::ReplayAppendTraversalByIds {
614                    from_id: from_id.to_string(),
615                    to_id: to_id.to_string(),
616                    trigger,
617                    timestamp_ms,
618                });
619            }
620            GraphDeltaResult::TraversalAppended(appended)
621        }
622        GraphDelta::RetractRelations { from, to, selector } => {
623            let from_id = graph.get_node(from).map(|node| node.id);
624            let to_id = graph.get_node(to).map(|node| node.id);
625            let removed = graph.retract_relations(from, to, selector);
626            if removed > 0
627                && let (Some(from_id), Some(to_id)) = (from_id, to_id)
628            {
629                record_captured_delta(&CapturedDelta::ReplayRetractRelationsByIds {
630                    from_id: from_id.to_string(),
631                    to_id: to_id.to_string(),
632                    selector,
633                });
634            }
635            GraphDeltaResult::EdgesRemoved(removed)
636        }
637        GraphDelta::AppendTraversal {
638            from,
639            to,
640            trigger,
641            timestamp_ms,
642        } => {
643            let from_id = graph.get_node(from).map(|node| node.id);
644            let to_id = graph.get_node(to).map(|node| node.id);
645            let appended = graph.append_traversal(from, to, trigger, timestamp_ms);
646            if appended
647                && let (Some(from_id), Some(to_id)) = (from_id, to_id)
648                && let Some(traversal) = graph
649                    .find_edge_key(from, to)
650                    .and_then(|edge| graph.get_edge(edge))
651                    .and_then(|payload| payload.traversals().last())
652                    .copied()
653            {
654                record_captured_delta(&CapturedDelta::ReplayAppendTraversalByIds {
655                    from_id: from_id.to_string(),
656                    to_id: to_id.to_string(),
657                    trigger: traversal.trigger,
658                    timestamp_ms: traversal.timestamp_ms,
659                });
660            }
661            GraphDeltaResult::TraversalAppended(appended)
662        }
663        GraphDelta::ReplaySetNodeTitleById { node_id, title } => {
664            let updated = graph
665                .get_node_key_by_id(node_id)
666                .is_some_and(|key| graph.set_node_title(key, title.clone()));
667            if updated {
668                record_captured_delta(&CapturedDelta::ReplaySetNodeTitleById {
669                    node_id: node_id.to_string(),
670                    title,
671                });
672            }
673            GraphDeltaResult::NodeMetadataUpdated(updated)
674        }
675        GraphDelta::SetNodeTitle { key, title } => {
676            let node_id = graph.get_node(key).map(|node| node.id);
677            let capture_title = title.clone();
678            let updated = graph.set_node_title(key, title);
679            if updated && let Some(node_id) = node_id {
680                record_captured_delta(&CapturedDelta::ReplaySetNodeTitleById {
681                    node_id: node_id.to_string(),
682                    title: capture_title,
683                });
684            }
685            GraphDeltaResult::NodeMetadataUpdated(updated)
686        }
687        GraphDelta::ReplaySetNodeUrlById { node_id, new_url } => {
688            let updated = graph
689                .get_node_key_by_id(node_id)
690                .and_then(|key| graph.update_node_url(key, new_url.clone()));
691            if updated.is_some() {
692                record_captured_delta(&CapturedDelta::ReplaySetNodeUrlById {
693                    node_id: node_id.to_string(),
694                    new_url,
695                });
696            }
697            GraphDeltaResult::NodeUrlUpdated(updated)
698        }
699        GraphDelta::SetNodeUrl { key, new_url } => {
700            let node_id = graph.get_node(key).map(|node| node.id);
701            let capture_url = new_url.clone();
702            let updated = graph.update_node_url(key, new_url);
703            if updated.is_some()
704                && let Some(node_id) = node_id
705            {
706                record_captured_delta(&CapturedDelta::ReplaySetNodeUrlById {
707                    node_id: node_id.to_string(),
708                    new_url: capture_url,
709                });
710            }
711            GraphDeltaResult::NodeUrlUpdated(updated)
712        }
713        GraphDelta::ReplaySetNodeImageById {
714            node_id,
715            role,
716            image,
717        } => {
718            let updated = graph
719                .get_node_key_by_id(node_id)
720                .is_some_and(|key| graph.set_node_image(key, role, image));
721            if updated {
722                record_captured_delta(&CapturedDelta::ReplaySetNodeImageById {
723                    node_id: node_id.to_string(),
724                    role,
725                    image,
726                });
727            }
728            GraphDeltaResult::NodeMetadataUpdated(updated)
729        }
730        GraphDelta::SetNodeImage { key, role, image } => {
731            let node_id = graph.get_node(key).map(|node| node.id);
732            let updated = graph.set_node_image(key, role, image);
733            if updated && let Some(node_id) = node_id {
734                record_captured_delta(&CapturedDelta::ReplaySetNodeImageById {
735                    node_id: node_id.to_string(),
736                    role,
737                    image,
738                });
739            }
740            GraphDeltaResult::NodeMetadataUpdated(updated)
741        }
742        GraphDelta::ReplaySetNodeMimeHintById { node_id, mime_hint } => {
743            let updated = graph
744                .get_node_key_by_id(node_id)
745                .is_some_and(|key| graph.set_node_mime_hint(key, mime_hint.clone()));
746            if updated {
747                record_captured_delta(&CapturedDelta::ReplaySetNodeMimeHintById {
748                    node_id: node_id.to_string(),
749                    mime_hint,
750                });
751            }
752            GraphDeltaResult::NodeMetadataUpdated(updated)
753        }
754        GraphDelta::SetNodeMimeHint { key, mime_hint } => {
755            let node_id = graph.get_node(key).map(|node| node.id);
756            let capture_mime_hint = mime_hint.clone();
757            let updated = graph.set_node_mime_hint(key, mime_hint);
758            if updated && let Some(node_id) = node_id {
759                record_captured_delta(&CapturedDelta::ReplaySetNodeMimeHintById {
760                    node_id: node_id.to_string(),
761                    mime_hint: capture_mime_hint,
762                });
763            }
764            GraphDeltaResult::NodeMetadataUpdated(updated)
765        }
766        GraphDelta::ReplaySetNodeContentById { node_id, content } => {
767            let updated = graph
768                .get_node_key_by_id(node_id)
769                .is_some_and(|key| graph.set_node_content(key, content));
770            if updated {
771                record_captured_delta(&CapturedDelta::ReplaySetNodeContentById {
772                    node_id: node_id.to_string(),
773                    content: content.map(|hash| *hash.as_bytes()),
774                });
775            }
776            GraphDeltaResult::NodeMetadataUpdated(updated)
777        }
778        GraphDelta::SetNodeContent { key, content } => {
779            let node_id = graph.get_node(key).map(|node| node.id);
780            let updated = graph.set_node_content(key, content);
781            if updated && let Some(node_id) = node_id {
782                record_captured_delta(&CapturedDelta::ReplaySetNodeContentById {
783                    node_id: node_id.to_string(),
784                    content: content.map(|hash| *hash.as_bytes()),
785                });
786            }
787            GraphDeltaResult::NodeMetadataUpdated(updated)
788        }
789        GraphDelta::ReplaySetNodeNestedById { node_id, nested } => {
790            let log = nested.clone().map(codicil::LogId::new);
791            let updated = graph
792                .get_node_key_by_id(node_id)
793                .is_some_and(|key| graph.set_node_nested(key, log.clone()));
794            if updated {
795                record_captured_delta(&CapturedDelta::ReplaySetNodeNestedById {
796                    node_id: node_id.to_string(),
797                    nested,
798                });
799            }
800            GraphDeltaResult::NodeMetadataUpdated(updated)
801        }
802        GraphDelta::SetNodeNested { key, nested } => {
803            let node_id = graph.get_node(key).map(|node| node.id);
804            let capture_nested = nested.as_ref().map(|log| log.as_str().to_string());
805            let updated = graph.set_node_nested(key, nested);
806            if updated && let Some(node_id) = node_id {
807                record_captured_delta(&CapturedDelta::ReplaySetNodeNestedById {
808                    node_id: node_id.to_string(),
809                    nested: capture_nested,
810                });
811            }
812            GraphDeltaResult::NodeMetadataUpdated(updated)
813        }
814        GraphDelta::ReplaySetNodePinnedById { node_id, is_pinned } => {
815            let updated = graph
816                .get_node_key_by_id(node_id)
817                .is_some_and(|key| graph.set_node_pinned(key, is_pinned));
818            if updated {
819                record_captured_delta(&CapturedDelta::ReplaySetNodePinnedById {
820                    node_id: node_id.to_string(),
821                    is_pinned,
822                });
823            }
824            GraphDeltaResult::NodeMetadataUpdated(updated)
825        }
826        GraphDelta::SetNodePinned { key, is_pinned } => {
827            let node_id = graph.get_node(key).map(|node| node.id);
828            let updated = graph.set_node_pinned(key, is_pinned);
829            if updated && let Some(node_id) = node_id {
830                record_captured_delta(&CapturedDelta::ReplaySetNodePinnedById {
831                    node_id: node_id.to_string(),
832                    is_pinned,
833                });
834            }
835            GraphDeltaResult::NodeMetadataUpdated(updated)
836        }
837        GraphDelta::ReplaySetNodeFacetById {
838            node_id,
839            facet,
840            value,
841        } => {
842            let updated = graph
843                .get_node_key_by_id(node_id)
844                .is_some_and(|key| set_node_facet(graph, key, &facet, value.clone()));
845            if updated {
846                record_captured_delta(&CapturedDelta::ReplaySetNodeFacetById {
847                    node_id: node_id.to_string(),
848                    facet,
849                    value_json: serde_json::to_string(&value)
850                        .expect("a graph facet value always serializes"),
851                });
852            }
853            GraphDeltaResult::NodeMetadataUpdated(updated)
854        }
855        GraphDelta::SetNodeFacet { key, facet, value } => {
856            let node_id = graph.get_node(key).map(|node| node.id);
857            let capture_value = value.clone();
858            let updated = set_node_facet(graph, key, &facet, value);
859            if updated && let Some(node_id) = node_id {
860                record_captured_delta(&CapturedDelta::ReplaySetNodeFacetById {
861                    node_id: node_id.to_string(),
862                    facet,
863                    value_json: serde_json::to_string(&capture_value)
864                        .expect("a graph facet value always serializes"),
865                });
866            }
867            GraphDeltaResult::NodeMetadataUpdated(updated)
868        }
869        GraphDelta::ReplayRemoveNodeFacetById { node_id, facet } => {
870            let updated = graph
871                .get_node_key_by_id(node_id)
872                .is_some_and(|key| remove_node_facet(graph, key, &facet));
873            if updated {
874                record_captured_delta(&CapturedDelta::ReplayRemoveNodeFacetById {
875                    node_id: node_id.to_string(),
876                    facet,
877                });
878            }
879            GraphDeltaResult::NodeMetadataUpdated(updated)
880        }
881        GraphDelta::RemoveNodeFacet { key, facet } => {
882            let node_id = graph.get_node(key).map(|node| node.id);
883            let updated = remove_node_facet(graph, key, &facet);
884            if updated && let Some(node_id) = node_id {
885                record_captured_delta(&CapturedDelta::ReplayRemoveNodeFacetById {
886                    node_id: node_id.to_string(),
887                    facet,
888                });
889            }
890            GraphDeltaResult::NodeMetadataUpdated(updated)
891        }
892        GraphDelta::ReplayAppendFrameLayoutHintById { node_id, hint } => {
893            let updated = graph
894                .get_node_key_by_id(node_id)
895                .is_some_and(|key| graph.append_frame_layout_hint(key, hint.clone()));
896            if updated {
897                record_captured_delta(&CapturedDelta::ReplayAppendFrameLayoutHintById {
898                    node_id: node_id.to_string(),
899                    hint,
900                });
901            }
902            GraphDeltaResult::NodeMetadataUpdated(updated)
903        }
904        GraphDelta::AppendFrameLayoutHint { key, hint } => {
905            let node_id = graph.get_node(key).map(|node| node.id);
906            let capture_hint = hint.clone();
907            let updated = graph.append_frame_layout_hint(key, hint);
908            if updated && let Some(node_id) = node_id {
909                record_captured_delta(&CapturedDelta::ReplayAppendFrameLayoutHintById {
910                    node_id: node_id.to_string(),
911                    hint: capture_hint,
912                });
913            }
914            GraphDeltaResult::NodeMetadataUpdated(updated)
915        }
916        GraphDelta::ReplayRemoveFrameLayoutHintById {
917            node_id,
918            hint_index,
919        } => {
920            let updated = graph
921                .get_node_key_by_id(node_id)
922                .is_some_and(|key| graph.remove_frame_layout_hint_at(key, hint_index));
923            if updated {
924                record_captured_delta(&CapturedDelta::ReplayRemoveFrameLayoutHintById {
925                    node_id: node_id.to_string(),
926                    hint_index,
927                });
928            }
929            GraphDeltaResult::NodeMetadataUpdated(updated)
930        }
931        GraphDelta::RemoveFrameLayoutHint { key, hint_index } => {
932            let node_id = graph.get_node(key).map(|node| node.id);
933            let updated = graph.remove_frame_layout_hint_at(key, hint_index);
934            if updated && let Some(node_id) = node_id {
935                record_captured_delta(&CapturedDelta::ReplayRemoveFrameLayoutHintById {
936                    node_id: node_id.to_string(),
937                    hint_index,
938                });
939            }
940            GraphDeltaResult::NodeMetadataUpdated(updated)
941        }
942        GraphDelta::ReplayMoveFrameLayoutHintById {
943            node_id,
944            from_index,
945            to_index,
946        } => {
947            let updated = graph
948                .get_node_key_by_id(node_id)
949                .is_some_and(|key| graph.move_frame_layout_hint(key, from_index, to_index));
950            if updated {
951                record_captured_delta(&CapturedDelta::ReplayMoveFrameLayoutHintById {
952                    node_id: node_id.to_string(),
953                    from_index,
954                    to_index,
955                });
956            }
957            GraphDeltaResult::NodeMetadataUpdated(updated)
958        }
959        GraphDelta::MoveFrameLayoutHint {
960            key,
961            from_index,
962            to_index,
963        } => {
964            let node_id = graph.get_node(key).map(|node| node.id);
965            let updated = graph.move_frame_layout_hint(key, from_index, to_index);
966            if updated && let Some(node_id) = node_id {
967                record_captured_delta(&CapturedDelta::ReplayMoveFrameLayoutHintById {
968                    node_id: node_id.to_string(),
969                    from_index,
970                    to_index,
971                });
972            }
973            GraphDeltaResult::NodeMetadataUpdated(updated)
974        }
975        GraphDelta::ReplaySetFrameSplitOfferSuppressedById {
976            node_id,
977            suppressed,
978        } => {
979            let updated = graph
980                .get_node_key_by_id(node_id)
981                .is_some_and(|key| graph.set_frame_split_offer_suppressed(key, suppressed));
982            if updated {
983                record_captured_delta(&CapturedDelta::ReplaySetFrameSplitOfferSuppressedById {
984                    node_id: node_id.to_string(),
985                    suppressed,
986                });
987            }
988            GraphDeltaResult::NodeMetadataUpdated(updated)
989        }
990        GraphDelta::SetFrameSplitOfferSuppressed { key, suppressed } => {
991            let node_id = graph.get_node(key).map(|node| node.id);
992            let updated = graph.set_frame_split_offer_suppressed(key, suppressed);
993            if updated && let Some(node_id) = node_id {
994                record_captured_delta(&CapturedDelta::ReplaySetFrameSplitOfferSuppressedById {
995                    node_id: node_id.to_string(),
996                    suppressed,
997                });
998            }
999            GraphDeltaResult::NodeMetadataUpdated(updated)
1000        }
1001        GraphDelta::ReplayUpdateNodeHistoryById {
1002            node_id,
1003            entries,
1004            current_index,
1005        } => {
1006            let updated = graph.get_node_key_by_id(node_id).is_some_and(|key| {
1007                graph.set_node_history_state(key, entries.clone(), current_index)
1008            });
1009            if updated {
1010                record_captured_delta(&CapturedDelta::ReplayUpdateNodeHistoryById {
1011                    node_id: node_id.to_string(),
1012                    entries,
1013                    current_index,
1014                });
1015            }
1016            GraphDeltaResult::NodeMetadataUpdated(updated)
1017        }
1018        GraphDelta::UpdateNodeHistory {
1019            key,
1020            entries,
1021            current_index,
1022        } => {
1023            let node_id = graph.get_node(key).map(|node| node.id);
1024            let capture_entries = entries.clone();
1025            let updated = graph.set_node_history_state(key, entries, current_index);
1026            if updated && let Some(node_id) = node_id {
1027                record_captured_delta(&CapturedDelta::ReplayUpdateNodeHistoryById {
1028                    node_id: node_id.to_string(),
1029                    entries: capture_entries,
1030                    current_index,
1031                });
1032            }
1033            GraphDeltaResult::NodeMetadataUpdated(updated)
1034        }
1035        GraphDelta::ReplaySetImportRecords { import_records } => {
1036            let changed = graph.set_import_records(import_records);
1037            if changed {
1038                capture_resolved_import_records(graph);
1039            }
1040            GraphDeltaResult::ImportRecordsUpdated(changed)
1041        }
1042        GraphDelta::ReplayTouchNodeLastVisitedById {
1043            node_id,
1044            timestamp_ms,
1045        } => {
1046            let updated = graph
1047                .get_node_key_by_id(node_id)
1048                .is_some_and(|key| graph.set_node_last_visited_at_ms(key, timestamp_ms));
1049            if updated {
1050                record_captured_delta(&CapturedDelta::ReplayTouchNodeLastVisitedById {
1051                    node_id: node_id.to_string(),
1052                    timestamp_ms,
1053                });
1054            }
1055            GraphDeltaResult::NodeMetadataUpdated(updated)
1056        }
1057        GraphDelta::NavigateNode { key, url } => {
1058            let Some(node_id) = graph.get_node(key).map(|node| node.id) else {
1059                return GraphDeltaResult::Applied;
1060            };
1061            let timestamp_ms = Graph::epoch_ms();
1062            graph
1063                .nav
1064                .record_visit(node_id, &url, TransitionKind::UrlTyped, timestamp_ms);
1065            let last_session_visited = graph.current_session;
1066            graph.set_node_last_session_visited(key, last_session_visited);
1067            let _ = graph.update_node_url(key, url.clone());
1068            record_captured_delta(&CapturedDelta::ReplayNavigateNodeById {
1069                node_id: node_id.to_string(),
1070                url,
1071                transition: TransitionKind::UrlTyped,
1072                timestamp_ms,
1073                last_session_visited,
1074            });
1075            GraphDeltaResult::Applied
1076        }
1077        GraphDelta::BranchHistory { child, parent } => {
1078            if let (Some(child_id), Some(parent_id)) = (
1079                graph.get_node(child).map(|node| node.id),
1080                graph.get_node(parent).map(|node| node.id),
1081            ) {
1082                graph.nav.spawn(child_id, parent_id);
1083                record_captured_delta(&CapturedDelta::ReplayBranchHistoryByIds {
1084                    child_id: child_id.to_string(),
1085                    parent_id: parent_id.to_string(),
1086                });
1087            }
1088            GraphDeltaResult::Applied
1089        }
1090        GraphDelta::NodeHistoryBack { key } => {
1091            let Some(node_id) = graph.get_node(key).map(|node| node.id) else {
1092                return GraphDeltaResult::HistoryStepped(None);
1093            };
1094            let timestamp_ms = Graph::epoch_ms();
1095            let stepped = graph.nav.back(node_id, timestamp_ms);
1096            if let Some(url) = stepped.clone() {
1097                let _ = graph.update_node_url(key, url);
1098                record_captured_delta(&CapturedDelta::ReplayNodeHistoryBackById {
1099                    node_id: node_id.to_string(),
1100                    timestamp_ms,
1101                });
1102            }
1103            GraphDeltaResult::HistoryStepped(stepped)
1104        }
1105        GraphDelta::NodeHistoryForward { key } => {
1106            let Some(node_id) = graph.get_node(key).map(|node| node.id) else {
1107                return GraphDeltaResult::HistoryStepped(None);
1108            };
1109            let timestamp_ms = Graph::epoch_ms();
1110            let stepped = graph.nav.forward(node_id, timestamp_ms);
1111            if let Some(url) = stepped.clone() {
1112                let _ = graph.update_node_url(key, url);
1113                record_captured_delta(&CapturedDelta::ReplayNodeHistoryForwardById {
1114                    node_id: node_id.to_string(),
1115                    timestamp_ms,
1116                });
1117            }
1118            GraphDeltaResult::HistoryStepped(stepped)
1119        }
1120        GraphDelta::ReplayInsertNodeTagById { node_id, tag } => {
1121            let updated = graph
1122                .get_node_key_by_id(node_id)
1123                .is_some_and(|key| graph.insert_node_tag(key, tag.clone()));
1124            if updated {
1125                record_captured_delta(&CapturedDelta::ReplayInsertNodeTagById {
1126                    node_id: node_id.to_string(),
1127                    tag,
1128                });
1129            }
1130            GraphDeltaResult::NodeMetadataUpdated(updated)
1131        }
1132        GraphDelta::InsertNodeTag { key, tag } => {
1133            let node_id = graph.get_node(key).map(|node| node.id);
1134            let capture_tag = tag.clone();
1135            let updated = graph.insert_node_tag(key, tag);
1136            if updated && let Some(node_id) = node_id {
1137                record_captured_delta(&CapturedDelta::ReplayInsertNodeTagById {
1138                    node_id: node_id.to_string(),
1139                    tag: capture_tag,
1140                });
1141            }
1142            GraphDeltaResult::NodeMetadataUpdated(updated)
1143        }
1144        GraphDelta::ReplayRemoveNodeTagById { node_id, tag } => {
1145            let updated = graph
1146                .get_node_key_by_id(node_id)
1147                .is_some_and(|key| graph.remove_node_tag(key, &tag));
1148            if updated {
1149                record_captured_delta(&CapturedDelta::ReplayRemoveNodeTagById {
1150                    node_id: node_id.to_string(),
1151                    tag,
1152                });
1153            }
1154            GraphDeltaResult::NodeMetadataUpdated(updated)
1155        }
1156        GraphDelta::RemoveNodeTag { key, tag } => {
1157            let node_id = graph.get_node(key).map(|node| node.id);
1158            let updated = graph.remove_node_tag(key, &tag);
1159            if updated && let Some(node_id) = node_id {
1160                record_captured_delta(&CapturedDelta::ReplayRemoveNodeTagById {
1161                    node_id: node_id.to_string(),
1162                    tag,
1163                });
1164            }
1165            GraphDeltaResult::NodeMetadataUpdated(updated)
1166        }
1167        GraphDelta::ReplaySetNodeBodyById { node_id, body } => {
1168            let updated = graph
1169                .get_node_key_by_id(node_id)
1170                .is_some_and(|key| graph.set_node_body(key, body.clone()));
1171            if updated {
1172                record_captured_delta(&CapturedDelta::ReplaySetNodeBodyById {
1173                    node_id: node_id.to_string(),
1174                    body,
1175                });
1176            }
1177            GraphDeltaResult::NodeMetadataUpdated(updated)
1178        }
1179        GraphDelta::SetNodeBody { key, body } => {
1180            let node_id = graph.get_node(key).map(|node| node.id);
1181            let capture_body = body.clone();
1182            let updated = graph.set_node_body(key, body);
1183            if updated && let Some(node_id) = node_id {
1184                record_captured_delta(&CapturedDelta::ReplaySetNodeBodyById {
1185                    node_id: node_id.to_string(),
1186                    body: capture_body,
1187                });
1188            }
1189            GraphDeltaResult::NodeMetadataUpdated(updated)
1190        }
1191        GraphDelta::ReplayNavigateNodeById {
1192            node_id,
1193            url,
1194            transition,
1195            timestamp_ms,
1196            last_session_visited,
1197        } => {
1198            let applied = graph.get_node_key_by_id(node_id).is_some_and(|key| {
1199                graph
1200                    .nav
1201                    .record_visit(node_id, &url, transition, timestamp_ms);
1202                graph.set_node_last_session_visited(key, last_session_visited);
1203                let _ = graph.update_node_url(key, url.clone());
1204                true
1205            });
1206            if applied {
1207                record_captured_delta(&CapturedDelta::ReplayNavigateNodeById {
1208                    node_id: node_id.to_string(),
1209                    url,
1210                    transition,
1211                    timestamp_ms,
1212                    last_session_visited,
1213                });
1214            }
1215            GraphDeltaResult::Applied
1216        }
1217        GraphDelta::ReplayBranchHistoryByIds {
1218            child_id,
1219            parent_id,
1220        } => {
1221            let applied = match (
1222                graph.get_node_key_by_id(child_id),
1223                graph.get_node_key_by_id(parent_id),
1224            ) {
1225                (Some(_child), Some(_parent)) => {
1226                    graph.nav.spawn(child_id, parent_id);
1227                    true
1228                }
1229                _ => false,
1230            };
1231            if applied {
1232                record_captured_delta(&CapturedDelta::ReplayBranchHistoryByIds {
1233                    child_id: child_id.to_string(),
1234                    parent_id: parent_id.to_string(),
1235                });
1236            }
1237            GraphDeltaResult::Applied
1238        }
1239        GraphDelta::ReplayNodeHistoryBackById {
1240            node_id,
1241            timestamp_ms,
1242        } => {
1243            let stepped = graph.get_node_key_by_id(node_id).and_then(|key| {
1244                let url = graph.nav.back(node_id, timestamp_ms)?;
1245                let _ = graph.update_node_url(key, url.clone());
1246                Some(url)
1247            });
1248            if stepped.is_some() {
1249                record_captured_delta(&CapturedDelta::ReplayNodeHistoryBackById {
1250                    node_id: node_id.to_string(),
1251                    timestamp_ms,
1252                });
1253            }
1254            GraphDeltaResult::HistoryStepped(stepped)
1255        }
1256        GraphDelta::ReplayNodeHistoryForwardById {
1257            node_id,
1258            timestamp_ms,
1259        } => {
1260            let stepped = graph.get_node_key_by_id(node_id).and_then(|key| {
1261                let url = graph.nav.forward(node_id, timestamp_ms)?;
1262                let _ = graph.update_node_url(key, url.clone());
1263                Some(url)
1264            });
1265            if stepped.is_some() {
1266                record_captured_delta(&CapturedDelta::ReplayNodeHistoryForwardById {
1267                    node_id: node_id.to_string(),
1268                    timestamp_ms,
1269                });
1270            }
1271            GraphDeltaResult::HistoryStepped(stepped)
1272        }
1273        GraphDelta::ReplayAppendNodePropertyById { node_id, property } => {
1274            let updated = graph
1275                .get_node_key_by_id(node_id)
1276                .is_some_and(|key| graph.append_node_property(key, property.clone()));
1277            if updated {
1278                record_captured_delta(&CapturedDelta::ReplayAppendNodePropertyById {
1279                    node_id: node_id.to_string(),
1280                    property,
1281                });
1282            }
1283            GraphDeltaResult::NodeMetadataUpdated(updated)
1284        }
1285        GraphDelta::AppendNodeProperty { key, property } => {
1286            let node_id = graph.get_node(key).map(|node| node.id);
1287            let capture_property = property.clone();
1288            let updated = graph.append_node_property(key, property);
1289            if updated && let Some(node_id) = node_id {
1290                record_captured_delta(&CapturedDelta::ReplayAppendNodePropertyById {
1291                    node_id: node_id.to_string(),
1292                    property: capture_property,
1293                });
1294            }
1295            GraphDeltaResult::NodeMetadataUpdated(updated)
1296        }
1297        GraphDelta::ReplayAddNodeClassificationById {
1298            node_id,
1299            classification,
1300        } => {
1301            let updated = graph
1302                .get_node_key_by_id(node_id)
1303                .is_some_and(|key| graph.add_node_classification(key, classification.clone()));
1304            if updated {
1305                record_captured_delta(&CapturedDelta::ReplayAddNodeClassificationById {
1306                    node_id: node_id.to_string(),
1307                    classification,
1308                });
1309            }
1310            GraphDeltaResult::NodeMetadataUpdated(updated)
1311        }
1312        GraphDelta::AddNodeClassification {
1313            key,
1314            classification,
1315        } => {
1316            let node_id = graph.get_node(key).map(|node| node.id);
1317            let capture_classification = classification.clone();
1318            let updated = graph.add_node_classification(key, classification);
1319            if updated && let Some(node_id) = node_id {
1320                record_captured_delta(&CapturedDelta::ReplayAddNodeClassificationById {
1321                    node_id: node_id.to_string(),
1322                    classification: capture_classification,
1323                });
1324            }
1325            GraphDeltaResult::NodeMetadataUpdated(updated)
1326        }
1327        GraphDelta::ReplayRemoveNodeClassificationById {
1328            node_id,
1329            scheme,
1330            value,
1331        } => {
1332            let updated = graph
1333                .get_node_key_by_id(node_id)
1334                .is_some_and(|key| graph.remove_node_classification(key, &scheme, &value));
1335            if updated {
1336                record_captured_delta(&CapturedDelta::ReplayRemoveNodeClassificationById {
1337                    node_id: node_id.to_string(),
1338                    scheme,
1339                    value,
1340                });
1341            }
1342            GraphDeltaResult::NodeMetadataUpdated(updated)
1343        }
1344        GraphDelta::RemoveNodeClassification { key, scheme, value } => {
1345            let node_id = graph.get_node(key).map(|node| node.id);
1346            let capture_scheme = scheme.clone();
1347            let capture_value = value.clone();
1348            let updated = graph.remove_node_classification(key, &scheme, &value);
1349            if updated && let Some(node_id) = node_id {
1350                record_captured_delta(&CapturedDelta::ReplayRemoveNodeClassificationById {
1351                    node_id: node_id.to_string(),
1352                    scheme: capture_scheme,
1353                    value: capture_value,
1354                });
1355            }
1356            GraphDeltaResult::NodeMetadataUpdated(updated)
1357        }
1358        GraphDelta::ReplaySetNodeClassificationStatusById {
1359            node_id,
1360            scheme,
1361            value,
1362            status,
1363        } => {
1364            let updated = graph.get_node_key_by_id(node_id).is_some_and(|key| {
1365                graph.set_node_classification_status(key, &scheme, &value, status.clone())
1366            });
1367            if updated {
1368                record_captured_delta(&CapturedDelta::ReplaySetNodeClassificationStatusById {
1369                    node_id: node_id.to_string(),
1370                    scheme,
1371                    value,
1372                    status,
1373                });
1374            }
1375            GraphDeltaResult::NodeMetadataUpdated(updated)
1376        }
1377        GraphDelta::SetNodeClassificationStatus {
1378            key,
1379            scheme,
1380            value,
1381            status,
1382        } => {
1383            let node_id = graph.get_node(key).map(|node| node.id);
1384            let capture_scheme = scheme.clone();
1385            let capture_value = value.clone();
1386            let capture_status = status.clone();
1387            let updated = graph.set_node_classification_status(key, &scheme, &value, status);
1388            if updated && let Some(node_id) = node_id {
1389                record_captured_delta(&CapturedDelta::ReplaySetNodeClassificationStatusById {
1390                    node_id: node_id.to_string(),
1391                    scheme: capture_scheme,
1392                    value: capture_value,
1393                    status: capture_status,
1394                });
1395            }
1396            GraphDeltaResult::NodeMetadataUpdated(updated)
1397        }
1398        GraphDelta::ReplaySetNodePrimaryClassificationById {
1399            node_id,
1400            scheme,
1401            value,
1402        } => {
1403            let updated = graph
1404                .get_node_key_by_id(node_id)
1405                .is_some_and(|key| graph.set_node_primary_classification(key, &scheme, &value));
1406            if updated {
1407                record_captured_delta(&CapturedDelta::ReplaySetNodePrimaryClassificationById {
1408                    node_id: node_id.to_string(),
1409                    scheme,
1410                    value,
1411                });
1412            }
1413            GraphDeltaResult::NodeMetadataUpdated(updated)
1414        }
1415        GraphDelta::SetNodePrimaryClassification { key, scheme, value } => {
1416            let node_id = graph.get_node(key).map(|node| node.id);
1417            let capture_scheme = scheme.clone();
1418            let capture_value = value.clone();
1419            let updated = graph.set_node_primary_classification(key, &scheme, &value);
1420            if updated && let Some(node_id) = node_id {
1421                record_captured_delta(&CapturedDelta::ReplaySetNodePrimaryClassificationById {
1422                    node_id: node_id.to_string(),
1423                    scheme: capture_scheme,
1424                    value: capture_value,
1425                });
1426            }
1427            GraphDeltaResult::NodeMetadataUpdated(updated)
1428        }
1429        GraphDelta::ReplayRecordNodeDerivationById {
1430            node_id,
1431            derivation,
1432        } => {
1433            let updated = graph
1434                .get_node_key_by_id(node_id)
1435                .is_some_and(|key| graph.record_derivation(key, derivation.clone()));
1436            if updated {
1437                record_captured_delta(&CapturedDelta::ReplayRecordNodeDerivationById {
1438                    node_id: node_id.to_string(),
1439                    derivation,
1440                });
1441            }
1442            GraphDeltaResult::NodeMetadataUpdated(updated)
1443        }
1444        GraphDelta::RecordNodeDerivation { key, derivation } => {
1445            let node_id = graph.get_node(key).map(|node| node.id);
1446            let capture_derivation = derivation.clone();
1447            let updated = graph.record_derivation(key, derivation);
1448            if updated && let Some(node_id) = node_id {
1449                record_captured_delta(&CapturedDelta::ReplayRecordNodeDerivationById {
1450                    node_id: node_id.to_string(),
1451                    derivation: capture_derivation,
1452                });
1453            }
1454            GraphDeltaResult::NodeMetadataUpdated(updated)
1455        }
1456        GraphDelta::ReplaySetNodeTagIconOverrideById { node_id, tag, icon } => {
1457            let updated = graph
1458                .get_node_key_by_id(node_id)
1459                .is_some_and(|key| graph.set_node_tag_icon_override(key, &tag, icon.clone()));
1460            if updated {
1461                record_captured_delta(&CapturedDelta::ReplaySetNodeTagIconOverrideById {
1462                    node_id: node_id.to_string(),
1463                    tag,
1464                    icon,
1465                });
1466            }
1467            GraphDeltaResult::NodeMetadataUpdated(updated)
1468        }
1469        GraphDelta::SetNodeTagIconOverride { key, tag, icon } => {
1470            let node_id = graph.get_node(key).map(|node| node.id);
1471            let capture_tag = tag.clone();
1472            let capture_icon = icon.clone();
1473            let updated = graph.set_node_tag_icon_override(key, &tag, icon);
1474            if updated && let Some(node_id) = node_id {
1475                record_captured_delta(&CapturedDelta::ReplaySetNodeTagIconOverrideById {
1476                    node_id: node_id.to_string(),
1477                    tag: capture_tag,
1478                    icon: capture_icon,
1479                });
1480            }
1481            GraphDeltaResult::NodeMetadataUpdated(updated)
1482        }
1483        GraphDelta::ReplaySetEdgeSemanticPredicateByIds {
1484            from_id,
1485            to_id,
1486            predicate,
1487        } => {
1488            let updated =
1489                graph.replay_set_edge_semantic_predicate_by_ids(from_id, to_id, predicate.clone());
1490            if updated {
1491                record_captured_delta(&CapturedDelta::ReplaySetEdgeSemanticPredicateByIds {
1492                    from_id: from_id.to_string(),
1493                    to_id: to_id.to_string(),
1494                    predicate,
1495                });
1496            }
1497            GraphDeltaResult::NodeMetadataUpdated(updated)
1498        }
1499        GraphDelta::ReplayAssertSemanticPredicateByIds {
1500            from_id,
1501            to_id,
1502            predicate,
1503        } => {
1504            let edge =
1505                graph.replay_assert_semantic_predicate_by_ids(from_id, to_id, predicate.clone());
1506            if edge.is_some() {
1507                record_captured_delta(&CapturedDelta::ReplayAssertSemanticPredicateByIds {
1508                    from_id: from_id.to_string(),
1509                    to_id: to_id.to_string(),
1510                    predicate,
1511                });
1512            }
1513            GraphDeltaResult::EdgeAdded(edge)
1514        }
1515        GraphDelta::SetEdgeSemanticPredicate { edge, predicate } => {
1516            let endpoints = graph
1517                .inner
1518                .inner()
1519                .edge_endpoints(edge)
1520                .and_then(|(from, to)| Some((graph.get_node(from)?.id, graph.get_node(to)?.id)));
1521            let capture_predicate = predicate.clone();
1522            let updated = graph.set_edge_semantic_predicate(edge, predicate);
1523            if updated && let Some((from_id, to_id)) = endpoints {
1524                record_captured_delta(&CapturedDelta::ReplaySetEdgeSemanticPredicateByIds {
1525                    from_id: from_id.to_string(),
1526                    to_id: to_id.to_string(),
1527                    predicate: capture_predicate,
1528                });
1529            }
1530            GraphDeltaResult::NodeMetadataUpdated(updated)
1531        }
1532        GraphDelta::AssertSemanticPredicate {
1533            from,
1534            to,
1535            predicate,
1536        } => {
1537            let from_id = graph.get_node(from).map(|node| node.id);
1538            let to_id = graph.get_node(to).map(|node| node.id);
1539            let capture_predicate = predicate.clone();
1540            let edge = graph.assert_semantic_predicate(from, to, predicate);
1541            if edge.is_some()
1542                && let (Some(from_id), Some(to_id)) = (from_id, to_id)
1543            {
1544                record_captured_delta(&CapturedDelta::ReplayAssertSemanticPredicateByIds {
1545                    from_id: from_id.to_string(),
1546                    to_id: to_id.to_string(),
1547                    predicate: capture_predicate,
1548                });
1549            }
1550            GraphDeltaResult::EdgeAdded(edge)
1551        }
1552        GraphDelta::ReplayAddField { field } => {
1553            let changed = if let Some(field) = field_from_persisted(&field) {
1554                graph.add_field(field);
1555                true
1556            } else {
1557                false
1558            };
1559            if changed {
1560                record_captured_delta(&CapturedDelta::ReplayAddField { field });
1561            }
1562            GraphDeltaResult::FieldChanged(changed)
1563        }
1564        GraphDelta::ReplayRetireFieldById { field_id } => {
1565            let changed = Uuid::parse_str(&field_id)
1566                .ok()
1567                .map(FieldId::from_uuid)
1568                .is_some_and(|id| graph.retire_field(id));
1569            if changed {
1570                record_captured_delta(&CapturedDelta::ReplayRetireFieldById { field_id });
1571            }
1572            GraphDeltaResult::FieldChanged(changed)
1573        }
1574        GraphDelta::ReplayAddCoupling { coupling } => {
1575            let changed = if let Some(coupling_model) = coupling_from_persisted(&coupling) {
1576                graph.add_coupling(coupling_model);
1577                true
1578            } else {
1579                false
1580            };
1581            if changed {
1582                record_captured_delta(&CapturedDelta::ReplayAddCoupling { coupling });
1583            }
1584            GraphDeltaResult::FieldChanged(changed)
1585        }
1586        GraphDelta::ReplaySetFieldCouplingStrengthByFieldId { field_id, strength } => {
1587            let changed = Uuid::parse_str(&field_id)
1588                .ok()
1589                .map(FieldId::from_uuid)
1590                .is_some_and(|field| graph.set_field_coupling_strength(field, strength));
1591            if changed {
1592                record_captured_delta(&CapturedDelta::ReplaySetFieldCouplingStrengthByFieldId {
1593                    field_id,
1594                    strength,
1595                });
1596            }
1597            GraphDeltaResult::FieldChanged(changed)
1598        }
1599        GraphDelta::ReplayActivateFieldById { field_id } => {
1600            let changed = Uuid::parse_str(&field_id)
1601                .ok()
1602                .map(FieldId::from_uuid)
1603                .is_some_and(|id| graph.activate_field(id));
1604            if changed {
1605                record_captured_delta(&CapturedDelta::ReplayActivateFieldById { field_id });
1606            }
1607            GraphDeltaResult::FieldChanged(changed)
1608        }
1609        GraphDelta::ReplayRetractCouplingById { coupling_id } => {
1610            let changed = Uuid::parse_str(&coupling_id)
1611                .ok()
1612                .map(CouplingId::from_uuid)
1613                .is_some_and(|id| graph.retract_coupling(id));
1614            if changed {
1615                record_captured_delta(&CapturedDelta::ReplayRetractCouplingById { coupling_id });
1616            }
1617            GraphDeltaResult::FieldChanged(changed)
1618        }
1619        GraphDelta::AddField { field } => {
1620            let capture_field = persisted_field_from_field(&field);
1621            graph.add_field(field);
1622            record_captured_delta(&CapturedDelta::ReplayAddField {
1623                field: capture_field,
1624            });
1625            GraphDeltaResult::FieldChanged(true)
1626        }
1627        GraphDelta::RetireField { id } => {
1628            let changed = graph.retire_field(id);
1629            if changed {
1630                record_captured_delta(&CapturedDelta::ReplayRetireFieldById {
1631                    field_id: id.as_uuid().to_string(),
1632                });
1633            }
1634            GraphDeltaResult::FieldChanged(changed)
1635        }
1636        GraphDelta::AddCoupling { coupling } => {
1637            let capture_coupling = persisted_coupling_from_coupling(&coupling);
1638            graph.add_coupling(coupling);
1639            record_captured_delta(&CapturedDelta::ReplayAddCoupling {
1640                coupling: capture_coupling,
1641            });
1642            GraphDeltaResult::FieldChanged(true)
1643        }
1644        GraphDelta::SetFieldCouplingStrength { field, strength } => {
1645            let changed = graph.set_field_coupling_strength(field, strength);
1646            if changed {
1647                record_captured_delta(&CapturedDelta::ReplaySetFieldCouplingStrengthByFieldId {
1648                    field_id: field.as_uuid().to_string(),
1649                    strength,
1650                });
1651            }
1652            GraphDeltaResult::FieldChanged(changed)
1653        }
1654        GraphDelta::ActivateField { id } => {
1655            let changed = graph.activate_field(id);
1656            if changed {
1657                record_captured_delta(&CapturedDelta::ReplayActivateFieldById {
1658                    field_id: id.as_uuid().to_string(),
1659                });
1660            }
1661            GraphDeltaResult::FieldChanged(changed)
1662        }
1663        GraphDelta::RetractCoupling { id } => {
1664            let changed = graph.retract_coupling(id);
1665            if changed {
1666                record_captured_delta(&CapturedDelta::ReplayRetractCouplingById {
1667                    coupling_id: id.as_uuid().to_string(),
1668                });
1669            }
1670            GraphDeltaResult::FieldChanged(changed)
1671        }
1672        GraphDelta::SetImportRecords { import_records } => {
1673            let changed = graph.set_import_records(import_records);
1674            if changed {
1675                capture_resolved_import_records(graph);
1676            }
1677            GraphDeltaResult::ImportRecordsUpdated(changed)
1678        }
1679        GraphDelta::DeleteImportRecord { record_id } => {
1680            let changed = graph.delete_import_record(&record_id);
1681            if changed {
1682                capture_resolved_import_records(graph);
1683            }
1684            GraphDeltaResult::ImportRecordsUpdated(changed)
1685        }
1686        GraphDelta::SetImportRecordMembershipSuppressed {
1687            record_id,
1688            key,
1689            suppressed,
1690        } => {
1691            let changed =
1692                graph.set_import_record_membership_suppressed(&record_id, key, suppressed);
1693            if changed {
1694                capture_resolved_import_records(graph);
1695            }
1696            GraphDeltaResult::ImportRecordsUpdated(changed)
1697        }
1698        GraphDelta::SetNodeImportProvenance {
1699            key,
1700            import_provenance,
1701        } => {
1702            let changed = graph.set_node_import_provenance(key, import_provenance);
1703            if changed {
1704                capture_resolved_import_records(graph);
1705            }
1706            GraphDeltaResult::ImportRecordsUpdated(changed)
1707        }
1708        GraphDelta::TouchNodeLastVisited { key } => {
1709            let node_id = graph.get_node(key).map(|node| node.id);
1710            let updated = graph.touch_node_last_visited_now(key);
1711            if updated
1712                && let Some(node_id) = node_id
1713                && let Some(timestamp_ms) = graph
1714                    .node_last_visited(key)
1715                    .and_then(|visited| visited.duration_since(std::time::UNIX_EPOCH).ok())
1716                    .map(|duration| duration.as_millis() as u64)
1717            {
1718                record_captured_delta(&CapturedDelta::ReplayTouchNodeLastVisitedById {
1719                    node_id: node_id.to_string(),
1720                    timestamp_ms,
1721                });
1722            }
1723            GraphDeltaResult::NodeMetadataUpdated(updated)
1724        }
1725    }
1726}
1727
1728// --- Ergonomic wrappers (write-path migration, 2026-07-01) ---
1729//
1730// Thin constructors over [`apply_graph_delta`] for the deltas whose result the
1731// caller almost always unwraps. They keep the funnel — every one routes through
1732// `apply_graph_delta`, so a future recording hook (the event log) instruments
1733// exactly one function — while sparing hot call sites the enum-unwrap noise.
1734
1735/// Add a node (fresh random id when `id` is `None`; not available on wasm
1736/// without an explicit id) and return its key.
1737pub fn add_node(
1738    graph: &mut Graph,
1739    id: Option<Uuid>,
1740    url: String,
1741    position: Point2D<f32>,
1742) -> NodeKey {
1743    match apply_graph_delta(graph, GraphDelta::AddNode { id, url, position }) {
1744        GraphDeltaResult::NodeAdded(key) => key,
1745        other => unreachable!("AddNode returned {other:?}"),
1746    }
1747}
1748
1749/// Assert a relation between two nodes, returning the edge key (or `None` when
1750/// either endpoint is gone).
1751pub fn assert_relation(
1752    graph: &mut Graph,
1753    from: NodeKey,
1754    to: NodeKey,
1755    assertion: EdgeAssertion,
1756) -> Option<EdgeKey> {
1757    match apply_graph_delta(
1758        graph,
1759        GraphDelta::AssertRelation {
1760            from,
1761            to,
1762            assertion,
1763        },
1764    ) {
1765        GraphDeltaResult::EdgeAdded(key) => key,
1766        other => unreachable!("AssertRelation returned {other:?}"),
1767    }
1768}
1769
1770/// Assert a recognized semantic statement in a specific named-graph scope.
1771pub fn assert_semantic_relation_in_scope(
1772    graph: &mut Graph,
1773    from: NodeKey,
1774    to: NodeKey,
1775    sub_kind: SemanticSubKind,
1776    label: Option<String>,
1777    graph_scope: GraphScope,
1778) -> Option<EdgeKey> {
1779    graph.assert_semantic_relation_in_scope(from, to, sub_kind, label, graph_scope)
1780}
1781
1782/// Assert an open-predicate semantic statement in a specific named-graph scope.
1783pub fn assert_semantic_predicate_in_scope(
1784    graph: &mut Graph,
1785    from: NodeKey,
1786    to: NodeKey,
1787    predicate: String,
1788    graph_scope: GraphScope,
1789) -> Option<EdgeKey> {
1790    graph.assert_semantic_predicate_in_scope(from, to, predicate, graph_scope)
1791}
1792
1793/// Step a node back one visit in its own browse history, returning the
1794/// revealed URL (`None` at the root).
1795pub fn node_history_back(graph: &mut Graph, key: NodeKey) -> Option<String> {
1796    match apply_graph_delta(graph, GraphDelta::NodeHistoryBack { key }) {
1797        GraphDeltaResult::HistoryStepped(url) => url,
1798        other => unreachable!("NodeHistoryBack returned {other:?}"),
1799    }
1800}
1801
1802/// Step a node forward one visit in its own browse history, returning the
1803/// revealed URL (`None` at the tip).
1804pub fn node_history_forward(graph: &mut Graph, key: NodeKey) -> Option<String> {
1805    match apply_graph_delta(graph, GraphDelta::NodeHistoryForward { key }) {
1806        GraphDeltaResult::HistoryStepped(url) => url,
1807        other => unreachable!("NodeHistoryForward returned {other:?}"),
1808    }
1809}