Skip to main content

kernel/graph/
edge_taxonomy.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Edge taxonomy types — families, kinds, and sub-kinds.
5//!
6//! Extracted from `graph/mod.rs` per the 2026-05-11 kernel-mod
7//! decomposition pass. Per-family runtime data structs (Traversal,
8//! EdgeMetrics, *Data types, predicate IRI mapping) live in `edge_data.rs`.
9//! [`EdgePayload`](super::EdgePayload) in `edge_payload.rs` is the primary
10//! consumer; `Graph` methods in `mod.rs` reach for these types via re-exports.
11
12use rkyv::{Archive, Deserialize, Serialize};
13
14#[derive(
15    Debug,
16    Clone,
17    Copy,
18    PartialEq,
19    Eq,
20    Hash,
21    PartialOrd,
22    Ord,
23    Archive,
24    Serialize,
25    Deserialize,
26    serde::Serialize,
27    serde::Deserialize,
28)]
29#[rkyv(compare(PartialEq, PartialOrd), derive(PartialEq, Eq, PartialOrd, Ord))]
30pub enum EdgeFamily {
31    Semantic,
32    Traversal,
33    Containment,
34    Arrangement,
35    Imported,
36    Provenance,
37}
38
39#[derive(
40    Debug,
41    Clone,
42    Copy,
43    PartialEq,
44    Eq,
45    Hash,
46    PartialOrd,
47    Ord,
48    Archive,
49    Serialize,
50    Deserialize,
51    serde::Serialize,
52    serde::Deserialize,
53)]
54#[rkyv(compare(PartialEq, PartialOrd), derive(PartialEq, Eq, PartialOrd, Ord))]
55#[derive(strum::EnumIter, strum::FromRepr)]
56pub enum SemanticSubKind {
57    Hyperlink,
58    UserGrouped,
59    AgentDerived,
60    Cites,
61    Quotes,
62    Summarizes,
63    Elaborates,
64    ExampleOf,
65    Supports,
66    Contradicts,
67    Questions,
68    SameEntityAs,
69    DuplicateOf,
70    CanonicalMirrorOf,
71    DependsOn,
72    Blocks,
73    NextStep,
74}
75
76#[derive(
77    Debug,
78    Clone,
79    Copy,
80    PartialEq,
81    Eq,
82    Hash,
83    PartialOrd,
84    Ord,
85    Archive,
86    Serialize,
87    Deserialize,
88    serde::Serialize,
89    serde::Deserialize,
90)]
91#[rkyv(compare(PartialEq, PartialOrd), derive(PartialEq, Eq, PartialOrd, Ord))]
92#[derive(strum::EnumIter, strum::FromRepr)]
93pub enum ArrangementSubKind {
94    FrameMember,
95    TileGroup,
96    SplitPair,
97}
98
99#[derive(
100    Debug,
101    Clone,
102    Copy,
103    PartialEq,
104    Eq,
105    Hash,
106    PartialOrd,
107    Ord,
108    Archive,
109    Serialize,
110    Deserialize,
111    serde::Serialize,
112    serde::Deserialize,
113)]
114#[rkyv(compare(PartialEq, PartialOrd), derive(PartialEq, Eq, PartialOrd, Ord))]
115#[derive(strum::EnumIter, strum::FromRepr)]
116pub enum ContainmentSubKind {
117    UrlPath,
118    Domain,
119    FileSystem,
120    UserFolder,
121    ClipSource,
122    NotebookSection,
123    CollectionMember,
124}
125
126impl ContainmentSubKind {
127    pub fn as_tag(self) -> &'static str {
128        match self {
129            Self::UrlPath => "url-path",
130            Self::Domain => "domain",
131            Self::FileSystem => "filesystem",
132            Self::UserFolder => "user-folder",
133            Self::ClipSource => "clip-source",
134            Self::NotebookSection => "notebook-section",
135            Self::CollectionMember => "collection-member",
136        }
137    }
138}
139
140#[derive(
141    Debug,
142    Clone,
143    Copy,
144    PartialEq,
145    Eq,
146    Hash,
147    PartialOrd,
148    Ord,
149    Archive,
150    Serialize,
151    Deserialize,
152    serde::Serialize,
153    serde::Deserialize,
154)]
155#[rkyv(compare(PartialEq, PartialOrd), derive(PartialEq, Eq, PartialOrd, Ord))]
156#[derive(strum::EnumIter, strum::FromRepr)]
157pub enum ImportedSubKind {
158    BookmarkFolder,
159    HistoryImport,
160    SessionImport,
161    RssMembership,
162    FileSystemImport,
163    ArchiveMembership,
164    SharedCollection,
165}
166
167#[derive(
168    Debug,
169    Clone,
170    Copy,
171    PartialEq,
172    Eq,
173    Hash,
174    PartialOrd,
175    Ord,
176    Archive,
177    Serialize,
178    Deserialize,
179    serde::Serialize,
180    serde::Deserialize,
181)]
182#[rkyv(compare(PartialEq, PartialOrd), derive(PartialEq, Eq, PartialOrd, Ord))]
183#[derive(strum::EnumIter, strum::FromRepr)]
184pub enum ProvenanceSubKind {
185    ClippedFrom,
186    ExcerptedFrom,
187    SummarizedFrom,
188    TranslatedFrom,
189    RewrittenFrom,
190    GeneratedFrom,
191    ExtractedFrom,
192    ImportedFromSource,
193    /// A verbatim duplicate of the source — the cross-graph copy/tear-out
194    /// "fork" relation (tear-out brief §7.5). Unlike the content-transformation
195    /// sub-kinds above, the copy carries the source's content unchanged; only
196    /// its identity and host graph differ. Appended last so existing ordinals
197    /// (and the positional `tag` encoding) stay stable.
198    CopiedFrom,
199}
200
201#[derive(Debug, Clone, Copy, PartialEq, Eq, Archive, Serialize, Deserialize)]
202pub enum RelationDurability {
203    Durable,
204    Session,
205}
206
207impl RelationDurability {
208    pub fn as_tag(self) -> &'static str {
209        match self {
210            Self::Durable => "durable",
211            Self::Session => "session",
212        }
213    }
214}
215
216impl ArrangementSubKind {
217    pub fn as_tag(self) -> &'static str {
218        match self {
219            Self::FrameMember => "frame-member",
220            Self::TileGroup => "tile-group",
221            Self::SplitPair => "split-pair",
222        }
223    }
224
225    pub fn durability(self) -> RelationDurability {
226        match self {
227            Self::FrameMember => RelationDurability::Durable,
228            Self::TileGroup | Self::SplitPair => RelationDurability::Session,
229        }
230    }
231
232    pub fn provenance(self) -> &'static str {
233        match self {
234            Self::FrameMember => "workbench.frame_snapshot",
235            Self::TileGroup => "workbench.tile_grouping",
236            Self::SplitPair => "workbench.split_pairing",
237        }
238    }
239}
240
241#[derive(
242    Debug, Clone, PartialEq, Archive, Serialize, Deserialize, serde::Serialize, serde::Deserialize,
243)]
244pub enum EdgeAssertion {
245    Semantic {
246        sub_kind: SemanticSubKind,
247        label: Option<String>,
248        decay_progress: Option<f32>,
249    },
250    Containment {
251        sub_kind: ContainmentSubKind,
252    },
253    Arrangement {
254        sub_kind: ArrangementSubKind,
255    },
256    Imported {
257        sub_kind: ImportedSubKind,
258    },
259    Provenance {
260        sub_kind: ProvenanceSubKind,
261    },
262}
263
264#[derive(
265    Debug,
266    Clone,
267    Copy,
268    PartialEq,
269    Eq,
270    Hash,
271    Archive,
272    Serialize,
273    Deserialize,
274    serde::Serialize,
275    serde::Deserialize,
276)]
277pub enum RelationSelector {
278    Family(EdgeFamily),
279    Semantic(SemanticSubKind),
280    Containment(ContainmentSubKind),
281    Arrangement(ArrangementSubKind),
282    Imported(ImportedSubKind),
283    Provenance(ProvenanceSubKind),
284}
285
286/// Trigger classification for a traversal event.
287///
288/// Expanded per the 2026-05-11 relation-taxonomy-and-edge-mutation
289/// plan §2: `Traversal` stays the one family without sub-kinds;
290/// temporal nuance instead lives here in the trigger vocabulary.
291/// Five additions to cover the cases the prior plan called out:
292/// HTTP / meta redirects, session-restore navigations, in-document
293/// fragment jumps, find-in-page-style jumps, and imported-history
294/// hypotheses.
295#[derive(
296    Debug,
297    Clone,
298    Copy,
299    PartialEq,
300    Eq,
301    Archive,
302    Serialize,
303    Deserialize,
304    serde::Serialize,
305    serde::Deserialize,
306)]
307pub enum NavigationTrigger {
308    Unknown,
309    LinkClick,
310    Back,
311    Forward,
312    AddressBarEntry,
313    PanePromotion,
314    Programmatic,
315    /// Server redirect (3xx) or meta-refresh — the user didn't
316    /// directly initiate this hop.
317    Redirect,
318    /// Navigation re-issued by a session restore (window reopen,
319    /// "restore previous tabs," persisted-session rehydration).
320    ReopenSession,
321    /// In-document anchor jump (fragment / `#section`) — same
322    /// document, scroll destination changes.
323    JumpAnchor,
324    /// "Find in page" or analogous within-document search jumps
325    /// that surface as a navigation event.
326    InPageSearchJump,
327    /// Imported from another browser's history database. Distinct
328    /// from `Unknown` so importers can tag confidence-bounded
329    /// traversal hypotheses without conflating them with native
330    /// user navigation.
331    ImportedHistory,
332}
333
334impl NavigationTrigger {
335    #[allow(dead_code)]
336    pub(crate) fn contributes_to_forward_count(self) -> bool {
337        !matches!(self, Self::Back)
338    }
339}
340
341/// Canonical read-side classifier for an edge's relation. Combines
342/// family + sub-kind into one enum that callers reaching for "what
343/// kind of relation is this?" can match on without touching the
344/// write-side `EdgeAssertion` payload.
345///
346/// Per the 2026-05-11 relation-taxonomy plan §3: `RelationKind`
347/// is the discriminant shape (`RelationKind ≈
348/// discriminant(EdgeAssertion)`), used by canvas hit-tests, render
349/// policy, filter UIs, action-target inference, and view-local
350/// hide keys. `EdgeAssertion` remains the write contract — it
351/// carries construction-time payload (labels, decay state, etc.)
352/// that read sites don't need.
353///
354/// `Traversal` is the one variant without a sub-kind: traversal
355/// is event-shaped, with temporal nuance in [`NavigationTrigger`]
356/// rather than a `TraversalSubKind` enum.
357#[derive(
358    Debug,
359    Clone,
360    Copy,
361    PartialEq,
362    Eq,
363    Hash,
364    Archive,
365    Serialize,
366    Deserialize,
367    serde::Serialize,
368    serde::Deserialize,
369)]
370pub enum RelationKind {
371    Semantic(SemanticSubKind),
372    Traversal,
373    Containment(ContainmentSubKind),
374    Arrangement(ArrangementSubKind),
375    Imported(ImportedSubKind),
376    Provenance(ProvenanceSubKind),
377}
378
379impl RelationKind {
380    /// Project to the relation's family. Pure function — no payload
381    /// access required.
382    pub fn family(self) -> EdgeFamily {
383        match self {
384            RelationKind::Semantic(_) => EdgeFamily::Semantic,
385            RelationKind::Traversal => EdgeFamily::Traversal,
386            RelationKind::Containment(_) => EdgeFamily::Containment,
387            RelationKind::Arrangement(_) => EdgeFamily::Arrangement,
388            RelationKind::Imported(_) => EdgeFamily::Imported,
389            RelationKind::Provenance(_) => EdgeFamily::Provenance,
390        }
391    }
392
393    /// Encode this relation as an opaque `u32` tag for transport
394    /// through layers that can't depend on `kernel` (e.g.
395    /// `graph-canvas::CanvasEdge::tag` / `HitProxy::Edge::tag`).
396    /// The top byte is the family ordinal (0..5); the bottom three
397    /// bytes are the sub-kind ordinal within the family.
398    /// [`Self::from_tag`] is the inverse.
399    pub fn tag(self) -> u32 {
400        let (family, sub) = match self {
401            RelationKind::Semantic(sk) => (0u32, sk as u32),
402            RelationKind::Traversal => (1, 0),
403            RelationKind::Containment(sk) => (2, sk as u32),
404            RelationKind::Arrangement(sk) => (3, sk as u32),
405            RelationKind::Imported(sk) => (4, sk as u32),
406            RelationKind::Provenance(sk) => (5, sk as u32),
407        };
408        (family << 24) | (sub & 0x00ff_ffff)
409    }
410
411    /// Decode a `u32` tag produced by [`Self::tag`]. Returns `None`
412    /// for tags that don't correspond to a known relation (unknown
413    /// family byte or sub-kind ordinal out of range).
414    pub fn from_tag(tag: u32) -> Option<Self> {
415        let family = tag >> 24;
416        let sub = tag & 0x00ff_ffff;
417        match family {
418            0 => SemanticSubKind::from_repr(sub as usize).map(RelationKind::Semantic),
419            1 => (sub == 0).then_some(RelationKind::Traversal),
420            2 => ContainmentSubKind::from_repr(sub as usize).map(RelationKind::Containment),
421            3 => ArrangementSubKind::from_repr(sub as usize).map(RelationKind::Arrangement),
422            4 => ImportedSubKind::from_repr(sub as usize).map(RelationKind::Imported),
423            5 => ProvenanceSubKind::from_repr(sub as usize).map(RelationKind::Provenance),
424            _ => None,
425        }
426    }
427}