Skip to main content

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