Skip to main content

kernel/graph/
identity.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Graph identity types and rkyv archive helpers.
5//!
6//! Extracted from `graph/mod.rs` per the 2026-04-30 renderer plan §6.4
7//! decomposition target (5,459 LOC → split). Contains:
8//!
9//! - Stable handle types (`NodeKey`, `EdgeKey`) — petgraph index aliases.
10//! - Backend type aliases (`GraphDirection`, `GraphIndex`).
11//! - `GraphViewId` — per-graph-view-pane identity (UUID-backed).
12//! - rkyv `with = ...` archive helpers for `Uuid`, `Point2D<f32>`,
13//!   and `Vector2D<f32>` — bridge types between rkyv's primitive
14//!   archive shape and the actual field types used in `Node`/`Edge`/etc.
15//!
16//! WASM-clean: no host-side dependencies beyond what `graph/mod.rs`
17//! already imports.
18
19use petgraph::Directed;
20use petgraph::stable_graph::{EdgeIndex, NodeIndex};
21use rkyv::{
22    Archive, Archived, Deserialize, Place, Resolver, Serialize,
23    rancor::Fallible,
24    with::{ArchiveWith, DeserializeWith, SerializeWith},
25};
26use uuid::Uuid;
27
28/// Stable node handle (petgraph NodeIndex — survives other deletions).
29pub type NodeKey = NodeIndex;
30
31/// Stable edge handle (petgraph EdgeIndex).
32pub type EdgeKey = EdgeIndex;
33
34/// Graph backend direction type exposed for adapter integration.
35pub type GraphDirection = Directed;
36
37/// Graph backend index type exposed for adapter integration.
38pub type GraphIndex = petgraph::graph::DefaultIx;
39
40/// Unique identifier for a graph-view pane (one projection of a graph;
41/// many graph-view panes can exist concurrently, each with its own
42/// camera / selection / filter state).
43///
44/// Pre-M4 slice 10 (2026-04-22) this lived in `app/graph_views.rs`;
45/// moved here alongside the other graph-level identity types so
46/// portable runtime code (`ToolSurfaceReturnTarget`, `FrameViewModel`,
47/// etc.) can reference it without reaching across the app boundary.
48#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
49pub struct GraphViewId(Uuid);
50
51impl GraphViewId {
52    /// Fresh random identity. Gated to non-WASM because
53    /// `Uuid::new_v4()` requires an OS randomness source that is
54    /// unavailable on `wasm32-unknown-unknown`; WASM hosts construct
55    /// via [`GraphViewId::from_uuid`] with a host-supplied UUID.
56    #[cfg(not(target_arch = "wasm32"))]
57    pub fn new() -> Self {
58        Self(Uuid::new_v4())
59    }
60
61    pub fn from_uuid(id: Uuid) -> Self {
62        Self(id)
63    }
64
65    pub fn as_uuid(self) -> Uuid {
66        self.0
67    }
68}
69
70#[cfg(not(target_arch = "wasm32"))]
71impl Default for GraphViewId {
72    fn default() -> Self {
73        Self::new()
74    }
75}
76
77pub(crate) struct UuidAsBytes;
78
79impl ArchiveWith<Uuid> for UuidAsBytes {
80    type Archived = Archived<[u8; 16]>;
81    type Resolver = Resolver<[u8; 16]>;
82
83    fn resolve_with(field: &Uuid, resolver: Self::Resolver, out: Place<Self::Archived>) {
84        let bytes = *field.as_bytes();
85        bytes.resolve(resolver, out);
86    }
87}
88
89impl<S> SerializeWith<Uuid, S> for UuidAsBytes
90where
91    S: Fallible + ?Sized,
92    [u8; 16]: Serialize<S>,
93{
94    fn serialize_with(field: &Uuid, serializer: &mut S) -> Result<Self::Resolver, S::Error> {
95        let bytes = *field.as_bytes();
96        bytes.serialize(serializer)
97    }
98}
99
100impl<D> DeserializeWith<Archived<[u8; 16]>, Uuid, D> for UuidAsBytes
101where
102    D: Fallible + ?Sized,
103    Archived<[u8; 16]>: Deserialize<[u8; 16], D>,
104{
105    fn deserialize_with(
106        field: &Archived<[u8; 16]>,
107        deserializer: &mut D,
108    ) -> Result<Uuid, D::Error> {
109        let bytes = field.deserialize(deserializer)?;
110        Ok(Uuid::from_bytes(bytes))
111    }
112}
113
114// `Point2DAsTuple` (the rkyv with-adapter for `Node.position`) left with the
115// position field (S2): position is no longer graph truth, so the node carries no
116// coordinate to archive. `UuidAsBytes` remains for the node identity.
117//
118// `Vector2DAsTuple` (the rkyv with-adapter for `Node.velocity`) left with the
119// velocity field: seiche owns live velocity, so the graph node no longer carries
120// it. `Point2DAsTuple` remains for the transient projected position.
121
122/// rkyv with-adapter archiving a codicil [`LogId`](codicil::LogId) as its
123/// string form — for `Node.nested` (the borne graph's identity; the one-node
124/// ruling's containment tier). Wrap `Option<LogId>` fields as
125/// `#[rkyv(with = rkyv::with::Map<LogIdAsString>)]`.
126pub(crate) struct LogIdAsString;
127
128impl ArchiveWith<codicil::LogId> for LogIdAsString {
129    type Archived = Archived<String>;
130    type Resolver = Resolver<String>;
131
132    fn resolve_with(field: &codicil::LogId, resolver: Self::Resolver, out: Place<Self::Archived>) {
133        field.as_str().to_string().resolve(resolver, out);
134    }
135}
136
137impl<S> SerializeWith<codicil::LogId, S> for LogIdAsString
138where
139    S: Fallible + ?Sized,
140    String: Serialize<S>,
141{
142    fn serialize_with(
143        field: &codicil::LogId,
144        serializer: &mut S,
145    ) -> Result<Self::Resolver, S::Error> {
146        field.as_str().to_string().serialize(serializer)
147    }
148}
149
150impl<D> DeserializeWith<Archived<String>, codicil::LogId, D> for LogIdAsString
151where
152    D: Fallible + ?Sized,
153    Archived<String>: Deserialize<String, D>,
154{
155    fn deserialize_with(
156        field: &Archived<String>,
157        deserializer: &mut D,
158    ) -> Result<codicil::LogId, D::Error> {
159        let raw: String = field.deserialize(deserializer)?;
160        Ok(codicil::LogId::new(raw))
161    }
162}