minerva 0.2.0

Causal ordering for distributed systems
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

use super::super::super::Dotted;
use super::super::super::metathesis::Metatheses;
#[cfg(feature = "timing")]
use super::super::placement::Dot;

/// Wall-time attribution for one accepted movement testimony.
///
/// Enabled by the `timing` feature. Validation precedes the measured windows.
/// The topology total includes observer overhead; phase boundaries exclude
/// between-phase bookkeeping, while suffix replay necessarily includes its
/// per-play counter updates. The structured [`Self::topology`] field replaces
/// the provisional flat duration; [`Self::topology_placement`] remains a
/// deprecated read-only compatibility alias.
#[cfg(feature = "timing")]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct MovementBatchMoveProfile {
    /// Effective-topology suffix maintenance.
    pub topology: MovementTopologyProfile,
    /// Compatibility alias for [`Self::topology`]'s total duration.
    #[deprecated(since = "0.1.0", note = "use `topology.total`")]
    pub topology_placement: core::time::Duration,
    /// Causal-record supersession and delta composition.
    pub record_composition: core::time::Duration,
}

/// Attribution inside one effective-topology testimony application.
#[cfg(feature = "timing")]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct MovementTopologyProfile {
    /// End-to-end topology application, including observer overhead.
    pub total: core::time::Duration,
    /// Disjoint internal phase durations.
    pub phases: MovementTopologyPhases,
    /// Exact structural work performed.
    pub work: MovementTopologyWork,
    /// Cycle validation nested inside suffix replay.
    pub cycle_validation: MovementCycleValidationProfile,
}

/// Attribution for cycle validation nested inside topology suffix replay.
#[cfg(feature = "timing")]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct MovementCycleValidationProfile {
    /// Sum of cycle-check durations across replayed plays.
    pub total: core::time::Duration,
    /// Exact guard, bounded-walk, and terminal work.
    pub work: MovementCycleValidationWork,
}

/// Exact structural work performed by cycle validation.
///
/// The allocation-free walk removes the provisional
/// `repeated_node_terminals`, `visited_sets_created`,
/// `visited_set_insert_attempts`, and `visited_set_insertions` fields.
/// [`Self::anchor_cycle_terminals`] retains the repeated-node terminal's
/// semantics without exposing the discarded set implementation.
/// [`Self::invariant_refusals`] counts only exhaustion of the larger defensive
/// bound after allocation-free cycle detection has had enough steps to finish.
#[cfg(feature = "timing")]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct MovementCycleValidationWork {
    /// Replayed plays proven acyclic without an anchor-chain walk.
    pub guards_skipped: usize,
    /// Walks required because the proposed anchor is the target itself.
    pub self_guard_entries: usize,
    /// Monotone-guard entries backed by a current effective child.
    pub live_guard_entries: usize,
    /// Monotone-guard entries with no current effective child.
    pub stale_guard_entries: usize,
    /// Exact ancestry-coordinate queries.
    pub coordinate_queries: usize,
    /// Anchor-chain nodes examined by entered walks.
    pub chain_nodes_visited: usize,
    /// Coordinate queries that proved the destination outside the target.
    pub not_descendant_terminals: usize,
    /// Entered walks that reached the origin.
    pub origin_terminals: usize,
    /// Entered walks that reached an unborn link.
    pub unborn_terminals: usize,
    /// Entered walks that terminated in a non-target anchor cycle.
    pub anchor_cycle_terminals: usize,
    /// Entered walks that exhausted the defensive finite-skeleton bound.
    ///
    /// This is unreachable for a lookup over the stated skeleton. The
    /// corresponding play is refused rather than applied to uncertain state.
    pub invariant_refusals: usize,
    /// Entered walks that reached the target and refused the play.
    pub refusals: usize,
}

/// Disjoint wall-time attribution inside topology application.
#[cfg(feature = "timing")]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct MovementTopologyPhases {
    /// Locate the first existing play for the target.
    pub play_search: core::time::Duration,
    /// Restore the affected suffix in reverse order.
    pub suffix_unwind: core::time::Duration,
    /// Split, supersede, and finalize the replay queue.
    pub suffix_edit: core::time::Duration,
    /// Revalidate and reapply the edited suffix.
    pub suffix_replay: core::time::Duration,
}

/// Exact structural work inside one topology application.
///
/// Cycle work moved to [`MovementTopologyProfile::cycle_validation`] when the
/// guard states became exclusive. The intentional pre-release migration is:
///
/// * `cycle_guards_skipped` to
///   [`MovementCycleValidationWork::guards_skipped`];
/// * `cycle_guards_entered` to the sum of
///   [`MovementCycleValidationWork::self_guard_entries`],
///   [`MovementCycleValidationWork::live_guard_entries`], and
///   [`MovementCycleValidationWork::stale_guard_entries`];
/// * `cycle_chain_nodes_visited` to
///   [`MovementCycleValidationWork::chain_nodes_visited`];
/// * `cycle_refusals` to [`MovementCycleValidationWork::refusals`].
#[cfg(feature = "timing")]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct MovementTopologyWork {
    /// Play-log entries examined while locating the affected suffix.
    pub play_search_visits: usize,
    /// Zero-based affected position, or the old log length on a miss.
    pub suffix_start: usize,
    /// Plays in the affected suffix before editing.
    pub raw_suffix_len: usize,
    /// Applied plays restored during unwind.
    pub applied_plays_unwound: usize,
    /// Refused plays crossed without mutation during unwind.
    pub refused_plays_skipped_unwind: usize,
    /// Same-target plays removed from the affected suffix.
    pub superseded_plays_removed: usize,
    /// Edited suffix length, including the new play.
    pub replay_len: usize,
    /// Accepted replay plays that replaced one effective locus.
    pub locus_replacements: usize,
}

/// Receipt and attribution for one accepted profiled movement.
#[cfg(feature = "timing")]
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ProfiledMovement {
    /// Fresh testimony identity.
    pub witness: Dot,
    /// Causal delta carrying the testimony and supersession context.
    pub delta: Dotted<Metatheses>,
    /// Disjoint wall-time attribution for the movement implementation.
    pub profile: MovementBatchMoveProfile,
}