From ac104da9f123e2844d2b456a8fe536ffd9b4bfc4 Mon Sep 17 00:00:00 2001 From: ac-pplx Date: Mon, 19 Oct 2026 17:16:41 -0400 Subject: [PATCH] docs: drop the duplicated SubstrateKind bullet and correct substrate comments #611 and #602 each added the same row-decision bullet to docs/rust/space-conventions.md, so it appeared twice; keep the copy with the examples. Correct comments #602 added: - `wakes_after_failed_control_connect`: Direct's access path wakes a suspended or restoring sandbox (`DirectSubstrate::access_runtime_client`), not every "dormant" sandbox as the Kubernetes bullet defines it. - `REGISTRY_SUBSTRATE`: every registry write to `nodes`/`node_direct` binds it and `verify` proceeds only for a live node of it; the registry's reads, and the template pull and delete routes, act on nodes of every substrate. - The registry's `substrate_scope` test module header, which said the registry reads only Direct nodes, now describes what it tests: writes and `verify`. --- crates/libs/api/src/routes/admin/node_maintenance.rs | 9 ++++++--- .../admin/node_maintenance/tests/substrate_scope.rs | 3 ++- crates/libs/common/core/src/types/node.rs | 6 +++--- docs/rust/space-conventions.md | 8 -------- 4 files changed, 11 insertions(+), 15 deletions(-) diff --git a/crates/libs/api/src/routes/admin/node_maintenance.rs b/crates/libs/api/src/routes/admin/node_maintenance.rs index 4012c4832f..31f23dc3d5 100644 --- a/crates/libs/api/src/routes/admin/node_maintenance.rs +++ b/crates/libs/api/src/routes/admin/node_maintenance.rs @@ -189,9 +189,12 @@ fn node_response(row: NodeRow) -> NodeResponse { } } -/// The substrate whose nodes this registry owns. Every registry statement -/// scopes to it, and an update's `verify` reads only a node of it, so the -/// registry never touches a node another substrate manages. +/// The substrate whose nodes this registry owns. Every registry write to +/// `nodes`/`node_direct` binds it, and an update's `verify` proceeds only for +/// a live node of it, so registration never changes a node another substrate +/// manages. Its reads (`fetch_node`, `fetch_nodes`) return nodes of every +/// substrate, and the template pull and delete routes (`node_templates.rs`) +/// act on any node `fetch_node` returns. const REGISTRY_SUBSTRATE: SubstrateKind = SubstrateKind::Space; fn require_admin_node_registry( diff --git a/crates/libs/api/src/routes/admin/node_maintenance/tests/substrate_scope.rs b/crates/libs/api/src/routes/admin/node_maintenance/tests/substrate_scope.rs index 7b1b4900df..80ab79c763 100644 --- a/crates/libs/api/src/routes/admin/node_maintenance/tests/substrate_scope.rs +++ b/crates/libs/api/src/routes/admin/node_maintenance/tests/substrate_scope.rs @@ -1,4 +1,5 @@ -//! The Direct node registry reads and writes only Direct (`'space'`) nodes. +//! The Direct node registry writes, and `verify` proceeds for, only Direct +//! (`'space'`) nodes. //! //! Each case pairs a Direct node with an otherwise identical node whose //! `managed_by` is `'k8s'`. Both keep a `node_direct` row, so only the diff --git a/crates/libs/common/core/src/types/node.rs b/crates/libs/common/core/src/types/node.rs index 06fa368f10..4ef10ca82d 100644 --- a/crates/libs/common/core/src/types/node.rs +++ b/crates/libs/common/core/src/types/node.rs @@ -804,9 +804,9 @@ impl SubstrateKind { /// /// - Kubernetes: yes. A dormant sandbox (suspended, or created and never /// started) has no pod until a wake creates one. - /// - Space: no. Direct wakes a dormant sandbox on the access path before - /// connecting (`DirectSubstrate::access_runtime_client` in the api - /// crate), not after a failed control connect. + /// - Space: no. Direct wakes a suspended or restoring sandbox on the + /// access path before connecting (`DirectSubstrate::access_runtime_client` + /// in the api crate), not after a failed control connect. pub const fn wakes_after_failed_control_connect(self) -> bool { match self { Self::Kubernetes => true, diff --git a/docs/rust/space-conventions.md b/docs/rust/space-conventions.md index 6e28a62329..9df9fcac34 100644 --- a/docs/rust/space-conventions.md +++ b/docs/rust/space-conventions.md @@ -201,14 +201,6 @@ sandbox store's public `SandboxRecord.managed_by` and as text (`proves_no_execution` parses the latter). Convert them when touched; they are not a pattern to copy. -- A decision about one row's substrate, its sandbox or node `managed_by`, - calls a `SubstrateKind` method named for the question; add one when no - method asks it. Rust that repeats a statement's fixed scope compares - against the named `SubstrateKind` const the statement binds, and mapping a - variant to a value (wire labels, route identity, construction) may match - it. A fact about the running substrate reads the api crate's - `capabilities()` (`SubstrateCapabilities`). Never compare the label string. - - A decision about one row's substrate, its sandbox or node `managed_by`, calls a `SubstrateKind` method named for the question (for example `proves_execution_absence` or `restores_through_pods`); add one when no