From 849760deb1cf7b07d08501b4e8809df86552b71c Mon Sep 17 00:00:00 2001 From: Keavon Chambers Date: Tue, 28 Jul 2026 02:47:02 -0700 Subject: [PATCH] Document the runtime delta modules where understanding needs it --- document/graph-storage/src/from_runtime.rs | 2 ++ .../network_interface/editor_delta.rs | 17 +++++++++++++++++ node-graph/graph-craft/src/runtime_delta.rs | 5 +++++ 3 files changed, 24 insertions(+) diff --git a/document/graph-storage/src/from_runtime.rs b/document/graph-storage/src/from_runtime.rs index 4bb24deb83..5918777ffd 100644 --- a/document/graph-storage/src/from_runtime.rs +++ b/document/graph-storage/src/from_runtime.rs @@ -423,6 +423,7 @@ fn convert_node( }) } +/// Public form of the node ui-attribute encoding, for staging paths that encode single nodes. pub fn encode_node_ui_attributes( attributes: &mut crate::Attributes, metadata: &M, @@ -433,6 +434,7 @@ pub fn encode_node_ui_attributes( write_ui_attributes(attributes, metadata, metadata_path, runtime_node_id, timestamp) } +/// Public form of the per-input ui-attribute encoding, matching `encode_node_ui_attributes`. pub fn encode_input_ui_attributes( attributes: &mut crate::Attributes, metadata: &M, diff --git a/editor/src/messages/portfolio/document/utility_types/network_interface/editor_delta.rs b/editor/src/messages/portfolio/document/utility_types/network_interface/editor_delta.rs index e688482f14..4920bb0e77 100644 --- a/editor/src/messages/portfolio/document/utility_types/network_interface/editor_delta.rs +++ b/editor/src/messages/portfolio/document/utility_types/network_interface/editor_delta.rs @@ -8,9 +8,14 @@ use graph_craft::document::NodeId; use graph_craft::runtime_delta::RuntimeDelta; use std::collections::HashSet; +/// A [`RuntimeDelta`] extended with the editor-only change kind: a wholesale copy of a node's +/// persistent metadata, which storage diffs against the working registry so minimal attribute ops +/// fall out. The compiler consumes only the `Graph` variant. #[derive(Debug, Clone, PartialEq)] pub enum EditorDelta { Graph(RuntimeDelta), + /// The copy includes the metadata of everything nested under the node, so one delta covers a + /// group and its contents. NodeMetadata { network_path: Vec, node_id: NodeId, @@ -23,6 +28,10 @@ pub struct ConstructedOps { pub declaration_bytes: DeclarationBytes, } +/// Constructs the storage ops for one gesture's deltas, in delta order. Removal closures and +/// resource liveness are computed against the whole batch, since several removals in one gesture +/// can jointly orphan a resource that each alone would not. Op timestamps are placeholders, +/// re-stamped by the staging clock. pub fn construct_batch(deltas: &[EditorDelta], working: &Registry, resources: &ResourceRegistry, peer: document_graph_storage::PeerId) -> Result { let resolver = PathResolver::new(peer); let mut ops = Vec::new(); @@ -117,6 +126,8 @@ impl EditorDelta { } } +/// Converts through the same encoders as a whole-document conversion, with `NoMetadata` as the +/// source: ui attributes arrive via the gesture's paired `NodeMetadata` delta. #[allow(clippy::too_many_arguments)] fn construct_structural_additions( network_path: &[NodeId], @@ -238,6 +249,8 @@ fn construct_metadata_changes( Ok(()) } +/// Minimal ops transforming the `ui::`-prefixed subset of `current` into `encoded`, comparing +/// values only, since timestamps are re-stamped at staging. fn ui_attribute_deltas(current: Option<&Attributes>, encoded: &Attributes) -> Vec { let owned = |key: &str| key.starts_with("ui::"); let mut deltas = Vec::new(); @@ -284,6 +297,8 @@ fn construct_removals(node_id: document_graph_storage::NodeId, working: &Registr } } +/// Emits removals for resources referenced only by the batch's removed nodes, checked after every +/// removal is known. fn construct_resource_removals(batch_removed_nodes: &[document_graph_storage::NodeId], working: &Registry, ops: &mut Vec) { let removed_node_set: HashSet<_> = batch_removed_nodes.iter().copied().collect(); let mut candidates: Vec = batch_removed_nodes @@ -334,6 +349,8 @@ fn collect_removal_closure(node_id: document_graph_storage::NodeId, working: &Re } } +/// Serves a metadata copy as the [`document_graph_storage::NodeMetadataSource`] for its own +/// encoding, resolving requested paths relative to the anchor node the copy was taken from. struct MetadataCopySource<'a> { anchor_path: &'a [NodeId], anchor_id: NodeId, diff --git a/node-graph/graph-craft/src/runtime_delta.rs b/node-graph/graph-craft/src/runtime_delta.rs index 50dff8147e..9188db06bf 100644 --- a/node-graph/graph-craft/src/runtime_delta.rs +++ b/node-graph/graph-craft/src/runtime_delta.rs @@ -1,7 +1,11 @@ use crate::document::{DocumentNode, NodeId, NodeInput}; +/// One mutation's worth of structural graph change, carrying its post-change data as plain runtime +/// types. Constructed by the mutation itself; a compound mutation emits several. Consumed typed and +/// unserialized by the compiler, and paired with `EditorDelta` metadata for storage staging. #[derive(Debug, Clone, PartialEq)] pub enum RuntimeDelta { + /// The node's nested network, if it implements one, rides inside the `DocumentNode`. AddNode { network_path: Vec, node_id: NodeId, @@ -12,6 +16,7 @@ pub enum RuntimeDelta { node_id: NodeId, node: Box, }, + /// Address-only: removal snapshots come from the storage layer's working registry. RemoveNode { network_path: Vec, node_id: NodeId,