Skip to main content

qualia_core_db/net/qdnf/harness/multihop/
mod.rs

1//! Native in-process multi-hop for ROUTE-F / NET-05.15.
2//!
3//! Production admission is `plan_routes` over nodes 1→2→3. Forwarding is
4//! published only after planning succeeds. This is not Ethernet, not OS
5//! isolation, not a durable ACK, and not a comparison against other routing.
6
7use crate::net::qdnf::authority::{evaluate_precedence, ContactState, PolicyOutcome};
8use crate::net::qdnf::errors::QdnfError;
9use crate::net::qdnf::harness::faults::FaultPipe;
10use crate::net::qdnf::route::hysteresis::{hop_is_held_down, HopHoldDown, HysteresisPolicy};
11use crate::net::qdnf::route::{CandidatePath, ForwardingGeneration};
12use crate::net::qdnf::session::datagrams::DeliveryStage;
13use crate::net::qdnf::session::paths::PathTable;
14use crate::net::qdnf::session::policy::gate_channel;
15use crate::net::qdnf::session::streams::StreamState;
16use crate::net::qdnf::types::OperationId;
17
18mod forward;
19mod topology;
20
21pub const NODE_COUNT: usize = 3;
22pub const ORIGIN_NODE: u8 = 1;
23pub const MIDDLE_NODE: u8 = 2;
24pub const DEST_NODE: u8 = 3;
25pub(super) const ORIGIN_SLOT: usize = 0;
26pub(super) const MIDDLE_SLOT: usize = 1;
27pub(super) const DEST_SLOT: usize = 2;
28
29#[inline]
30#[rustfmt::skip]
31/// Honest capability probe — transport ACKs are not yet durable (`false`).
32pub fn transport_ack_is_durable() -> bool { false }
33#[inline]
34#[rustfmt::skip]
35/// Honest capability probe — no OS-isolation evidence (`false`).
36pub fn os_isolation_evidence() -> bool { false }
37#[inline]
38#[rustfmt::skip]
39/// Honest capability probe — Ethernet transport not demonstrated (`false`).
40pub fn ethernet_demonstrated() -> bool { false }
41
42#[derive(Clone, Copy, Debug)]
43pub struct AuthState {
44    pub outcome: PolicyOutcome,
45    pub grant_current: bool,
46    pub contact: ContactState,
47    pub revoked: bool,
48}
49
50impl AuthState {
51    pub const OPEN: Self = Self {
52        outcome: PolicyOutcome::Allow,
53        grant_current: true,
54        contact: ContactState::Active,
55        revoked: false,
56    };
57}
58
59fn admit_application(auth: &AuthState) -> Result<(), QdnfError> {
60    evaluate_precedence(
61        auth.revoked,
62        matches!(auth.contact, ContactState::Blocked),
63        !auth.grant_current,
64        auth.outcome.admits_service(),
65    )?;
66    gate_channel(auth.outcome, auth.grant_current, auth.contact)?;
67    match auth.contact {
68        ContactState::Active | ContactState::Consent => Ok(()),
69        _ => Err(QdnfError::Denied),
70    }
71}
72
73/// Bounded 1→2→3 authorized path with middle-hop faults and cell handoff.
74pub struct MultiHop {
75    gens: [ForwardingGeneration; NODE_COUNT],
76    middle: FaultPipe,
77    stream: StreamState,
78    paths: PathTable,
79    active_path: u8,
80    planned_hops: u8,
81    current_path: CandidatePath,
82    last_change_unix: u64,
83    held: HopHoldDown,
84    policy: HysteresisPolicy,
85    pub auth: AuthState,
86    pub operation: OperationId,
87    last_stage: DeliveryStage,
88}
89
90impl MultiHop {
91    /// Creates a 3-generation multihop harness in the unpublished state (empty forwarding gens, fault pipe, fresh path race).
92    pub fn unpublished() -> Self {
93        let mut paths = PathTable::new();
94        let active_path = paths.start_race(1).expect("race");
95        paths.mark_active(active_path).expect("active");
96        Self {
97            gens: [
98                ForwardingGeneration::empty(1),
99                ForwardingGeneration::empty(2),
100                ForwardingGeneration::empty(3),
101            ],
102            middle: FaultPipe::new(),
103            stream: StreamState::new(),
104            paths,
105            active_path,
106            planned_hops: 0,
107            current_path: CandidatePath::EMPTY,
108            last_change_unix: 0,
109            held: HopHoldDown::EMPTY,
110            policy: HysteresisPolicy::STRICT,
111            auth: AuthState::OPEN,
112            operation: OperationId::ZERO,
113            last_stage: DeliveryStage::TransportAck,
114        }
115    }
116
117    /// Creates the harness then publishes the 1→2→3 line topology.
118    pub fn line() -> Self {
119        let mut s = Self::unpublished();
120        s.publish_line().expect("plan");
121        s
122    }
123
124    /// A published line harness whose middle link runs the given `FaultSchedule`.
125    pub fn line_with_schedule(schedule: crate::net::qdnf::harness::faults::FaultSchedule) -> Self {
126        let mut s = Self::line();
127        s.middle = FaultPipe::with_schedule(schedule);
128        s
129    }
130
131    /// Publishes the line topology into the forwarding generations.
132    pub fn publish_line(&mut self) -> Result<(), QdnfError> {
133        topology::publish_line(self)
134    }
135
136    #[rustfmt::skip]
137    /// Looks up the next hop for `DEST_NODE` in the origin generation.
138    pub fn lookup_dest(&self) -> Result<u8, QdnfError> {
139        self.gens[ORIGIN_SLOT].lookup_next(DEST_NODE)
140    }
141    #[rustfmt::skip]
142    /// Messages queued in the middle fault pipe.
143    pub fn queued(&self) -> usize { self.middle.queued() }
144    #[rustfmt::skip]
145    /// Current stream state.
146    pub fn stream(&self) -> StreamState { self.stream }
147    #[rustfmt::skip]
148    /// Shared access to the path table.
149    pub fn paths(&self) -> &PathTable { &self.paths }
150    #[rustfmt::skip]
151    /// Mutable access to the path table.
152    pub fn paths_mut(&mut self) -> &mut PathTable { &mut self.paths }
153    #[rustfmt::skip]
154    /// The last delivery stage reached.
155    pub fn last_stage(&self) -> DeliveryStage { self.last_stage }
156    #[rustfmt::skip]
157    /// Hops the last plan computed.
158    pub fn planned_hop_count(&self) -> u8 { self.planned_hops }
159    #[rustfmt::skip]
160    /// Advances the middle pipe one tick.
161    pub fn tick(&mut self) { self.middle.tick(); }
162
163    /// Withdraw the 1→2 next hop and start the hold-down timer.
164    pub fn partition_next_hop(&mut self, now_unix: u64) -> Result<(), QdnfError> {
165        topology::partition_next_hop(self, now_unix)
166    }
167
168    /// Re-advertise 1→2→3. A hop still in hold-down does not rejoin forwarding.
169    pub fn heal_next_hop(&mut self, now_unix: u64) -> Result<(), QdnfError> {
170        topology::heal_next_hop(self, now_unix)
171    }
172
173    #[inline]
174    /// `true` when the next hop is inside its hold-down window at `now_unix`.
175    pub fn next_hop_held_down(&self, now_unix: u64) -> bool {
176        hop_is_held_down(&self.held, now_unix, &self.policy)
177    }
178
179    /// Races a new path (`active+2`), activates it, and cleans up the previous path; returns the new path id.
180    pub fn handoff(&mut self) -> Result<u8, QdnfError> {
181        let next = self.paths.start_race(self.active_path as u64 + 2)?;
182        self.paths.mark_active(next)?;
183        self.paths.lose_and_cleanup(self.active_path)?;
184        self.active_path = next;
185        Ok(next)
186    }
187}
188
189#[cfg(test)]
190mod tests;