Skip to main content

subc_daemon/
registry.rs

1use std::{
2    collections::{BTreeMap, HashMap, HashSet},
3    error::Error,
4    fmt,
5    sync::{Arc, Mutex, MutexGuard},
6};
7
8use subc_protocol::manifest::{CapabilityDeclarations, ModuleManifest, ProviderRole};
9use tokio::sync::watch;
10use tracing::info;
11
12#[cfg(test)]
13#[path = "registry_admission_tests.rs"]
14mod admission_cache_tests;
15
16/// Per-connection identity assigned by [`crate::Router`] while serving a socket.
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
18pub struct ConnectionId(u64);
19
20impl ConnectionId {
21    /// Synthetic connection id used by unit tests. Router-issued connection ids
22    /// start at 1, so this 0 value never collides with a real socket owner.
23    #[cfg(test)]
24    pub const LOCAL: Self = Self(0);
25
26    pub const fn new(raw: u64) -> Self {
27        Self(raw)
28    }
29
30    pub fn get(self) -> u64 {
31        self.0
32    }
33}
34
35/// Lifecycle state for a module's channel allocation.
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
37pub enum ChannelState {
38    Active,
39    Closed,
40}
41
42/// Why a module registration stopped belonging to its connection.
43#[derive(Debug, Clone, Copy, PartialEq, Eq)]
44pub(crate) enum RegistrationEndReason {
45    ConnectionClosed,
46    ExplicitGoodbye,
47    Replaced,
48    SupervisorStop,
49    SupervisorRestart,
50    RegistrationFailed,
51}
52
53impl RegistrationEndReason {
54    fn as_str(self) -> &'static str {
55        match self {
56            Self::ConnectionClosed => "connection_closed",
57            Self::ExplicitGoodbye => "explicit_goodbye",
58            Self::Replaced => "replaced",
59            Self::SupervisorStop => "supervisor_stop",
60            Self::SupervisorRestart => "supervisor_restart",
61            Self::RegistrationFailed => "registration_failed",
62        }
63    }
64}
65
66/// Registry record for one active module registration.
67#[derive(Debug, Clone, PartialEq)]
68pub struct ModuleRegistration {
69    pub manifest: ModuleManifest,
70    pub ready: bool,
71    pub negotiated_ver: u8,
72    pub state: ChannelState,
73    pub connection_id: ConnectionId,
74    pub control_ops: Vec<String>,
75}
76
77/// Only the role identities used by route target selection, not their schemas.
78#[derive(Debug, Clone, PartialEq, Eq)]
79pub(crate) enum AdmissionRole {
80    ToolProvider,
81    ManagementSurface,
82    InternalService(String),
83}
84
85#[derive(Debug, Clone, PartialEq, Eq)]
86pub(crate) struct RouteRegistration {
87    pub(crate) module_id: String,
88    pub(crate) capabilities: Option<CapabilityDeclarations>,
89    pub(crate) roles: Vec<AdmissionRole>,
90    pub(crate) ready: bool,
91    pub(crate) state: ChannelState,
92    pub(crate) connection_id: ConnectionId,
93}
94
95impl From<&ModuleRegistration> for RouteRegistration {
96    fn from(registration: &ModuleRegistration) -> Self {
97        Self {
98            module_id: registration.manifest.module_id.clone(),
99            capabilities: registration.manifest.capabilities.clone(),
100            roles: registration
101                .manifest
102                .provides
103                .iter()
104                .filter_map(|role| match role {
105                    ProviderRole::ToolProvider { .. } => Some(AdmissionRole::ToolProvider),
106                    ProviderRole::ManagementSurface { .. } => {
107                        Some(AdmissionRole::ManagementSurface)
108                    }
109                    ProviderRole::InternalService { service_id, .. } => {
110                        Some(AdmissionRole::InternalService(service_id.clone()))
111                    }
112                    _ => None,
113                })
114                .collect(),
115            ready: registration.ready,
116            state: registration.state,
117            connection_id: registration.connection_id,
118        }
119    }
120}
121
122/// Immutable admission facts from one registry lock. Capability verdicts and
123/// forwarding availability are deliberately checked live, outside this view.
124#[derive(Debug, PartialEq, Eq)]
125pub(crate) struct RouteAdmissionSnapshot {
126    pub(crate) modules: Vec<Arc<RouteRegistration>>,
127    pub(crate) unpublished: HashSet<ConnectionId>,
128    pub(crate) connections: HashMap<ConnectionId, Arc<RouteRegistration>>,
129}
130
131impl std::ops::Deref for RouteAdmissionSnapshot {
132    type Target = [Arc<RouteRegistration>];
133
134    fn deref(&self) -> &Self::Target {
135        &self.modules
136    }
137}
138
139/// Which registration a lookup or a lifecycle wait is about.
140///
141/// A module id alone stops naming one process once a blue/green swap runs two
142/// processes under the same id: the incumbent in the active slot, the
143/// replacement in the candidate slot, and, after cutover, the old incumbent
144/// demoted until its connection goes away. A wait keyed on the bare id would
145/// confuse them (a successful swap never empties the id's active slot, and a
146/// candidate's "has it registered yet" would be answered by the incumbent).
147#[derive(Debug, Clone, Copy, PartialEq, Eq)]
148pub enum RegistrationSlot<'a> {
149    /// The routable registration for this module id. This is what every plain
150    /// start, stop and restart path means by "the module is registered".
151    Active(&'a str),
152    /// A swap candidate registered under this module id and not yet promoted.
153    Candidate(&'a str),
154    /// Whatever registration this module connection holds, in any slot.
155    Connection(ConnectionId),
156}
157
158/// The result of promoting a module's candidate registration to active.
159#[derive(Debug, Clone, PartialEq)]
160pub struct RegistryCutover {
161    /// The registration that is now active (the former candidate).
162    pub promoted: ModuleRegistration,
163    /// The former active registration, now demoted. `None` when the incumbent
164    /// had already gone away before the promotion.
165    pub superseded: Option<ModuleRegistration>,
166}
167
168/// Control-plane registry for module manifests and supervision ownership.
169///
170/// Duplicate active `module_id`s are rejected rather than replaced. Rejection is
171/// the safer v1 behavior because replacing a still-connected module could hijack
172/// in-flight routes. Stale registrations are removed by connection cleanup; a
173/// reconnect after the old connection drops can then register the same id again.
174///
175/// A blue/green swap is the one sanctioned way two processes hold the same id.
176/// The replacement registers into a separate candidate slot, which every by-id
177/// lookup ignores, so it stays unroutable until [`Registry::promote_candidate`]
178/// swaps it in. The old incumbent is then kept as "superseded" until its
179/// connection deregisters. Lookups keyed by connection id search all three
180/// slots, because a connection must be able to update and remove its own
181/// registration whichever slot it currently sits in.
182#[derive(Debug, Default)]
183pub struct Registry {
184    inner: Mutex<RegistryInner>,
185    #[cfg(test)]
186    next_lock_attempt: Mutex<Option<std::sync::mpsc::Sender<bool>>>,
187}
188
189#[derive(Debug, Default)]
190struct RegistryInner {
191    admission_cache: Option<Arc<RouteAdmissionSnapshot>>,
192    /// Only subscribed module ids have a sender. Changes coalesce, and writers
193    /// never wait for a supervisor to receive them.
194    // The value counts accepted active registrations. Keep that evidence even
195    // when register and disconnect coalesce before a supervisor receives them.
196    module_changes: HashMap<String, watch::Sender<u64>>,
197    modules: HashMap<String, ModuleRegistration>,
198    /// Swap candidates by module id: registered, never routable, never listed.
199    candidates: HashMap<String, ModuleRegistration>,
200    /// Former incumbents demoted by a promotion, kept only so their own
201    /// connection can still find and remove them. Never routable, never listed.
202    superseded: Vec<ModuleRegistration>,
203    /// Connections whose HELLO passed the launch-nonce check required for a
204    /// reserved module or swap candidate. Kept outside ModuleRegistration so
205    /// adding this catalog fact does not break callers that construct the public
206    /// registration struct.
207    nonce_verified: HashSet<ConnectionId>,
208    /// The active connection that displaced each superseded registration.
209    superseded_by: HashMap<ConnectionId, ConnectionId>,
210    /// Connections whose registration is reserved but not yet published.
211    ///
212    /// A HELLO registers in the registry before the daemon installs the
213    /// module's forwarding endpoint, and until that endpoint exists a
214    /// `route.open` to the module cannot be relayed. A registration in this set
215    /// already holds its module id (a duplicate HELLO is refused) and is found
216    /// by every lookup except two: [`Registry::list_modules`], which feeds
217    /// `catalog.list`, and [`Registry::published_registration`], which the swap
218    /// supervisor reads to decide that a candidate has registered. Adding a
219    /// registration to this set does not bump the catalog generation;
220    /// [`Registry::publish_registration`] removes it and bumps the generation
221    /// in the same critical section, so a catalog reader sees the module and
222    /// the new generation together.
223    unpublished: HashSet<ConnectionId>,
224    generation: u64,
225    catalog_changes: Option<watch::Sender<u64>>,
226}
227
228impl Registry {
229    /// Capture the current catalog generation and subscribe atomically. Writers
230    /// replace one value; they never wait for discovery clients to receive it.
231    pub(crate) fn subscribe_catalog_changes(&self) -> Result<watch::Receiver<u64>, RegistryError> {
232        let mut inner = self.lock_inner()?;
233        let generation = inner.generation;
234        Ok(inner
235            .catalog_changes
236            .get_or_insert_with(|| watch::channel(generation).0)
237            .subscribe())
238    }
239
240    /// Notify discovery after an approved declaration-set change or a change to
241    /// the spawn's first-party mark (whether it may receive automatic grants).
242    /// The authority owner calls this only after publishing the new state; it
243    /// must not hold a spawn or forwarding lock while taking the registry lock.
244    pub fn catalog_authority_changed(&self) -> Result<(), RegistryError> {
245        self.lock_inner()?.bump_generation();
246        Ok(())
247    }
248
249    /// Subscribe before reading a registration so a change between the read
250    /// and the supervisor's wait remains pending on this receiver.
251    pub(crate) fn subscribe_module_changes(
252        &self,
253        module_id: &str,
254    ) -> Result<watch::Receiver<u64>, RegistryError> {
255        let mut inner = self.lock_inner()?;
256        // Retired supervisors must not leave an ever-growing set of ids.
257        inner
258            .module_changes
259            .retain(|_, sender| sender.receiver_count() > 0);
260        Ok(inner
261            .module_changes
262            .entry(module_id.to_string())
263            .or_insert_with(|| watch::channel(0).0)
264            .subscribe())
265    }
266
267    /// Register a module manifest with the module's effective granted control op set.
268    ///
269    /// The registration is published at once: it is listed by
270    /// [`Self::list_modules`] and bumps the catalog generation. The HELLO path
271    /// uses [`Self::register_unpublished_with_control_ops`] instead, because it
272    /// still has to install the module's forwarding endpoint.
273    pub fn register_with_control_ops(
274        &self,
275        manifest: ModuleManifest,
276        negotiated_ver: u8,
277        connection_id: ConnectionId,
278        control_ops: Vec<String>,
279    ) -> Result<ModuleRegistration, RegistryError> {
280        self.register_active(
281            manifest,
282            negotiated_ver,
283            connection_id,
284            control_ops,
285            true,
286            false,
287        )
288    }
289
290    /// Register a module manifest without listing it yet.
291    ///
292    /// The registration holds its module id and is visible to every lookup
293    /// except [`Self::list_modules`] (and so `catalog.list`) and
294    /// [`Self::published_registration`]. The catalog generation does not move.
295    /// Call [`Self::publish_registration`] once the module can actually be
296    /// routed to; if that never becomes possible, deregistering the connection
297    /// removes the entry without the catalog ever having listed it.
298    pub fn register_unpublished_with_control_ops(
299        &self,
300        manifest: ModuleManifest,
301        negotiated_ver: u8,
302        connection_id: ConnectionId,
303        control_ops: Vec<String>,
304    ) -> Result<ModuleRegistration, RegistryError> {
305        self.register_active(
306            manifest,
307            negotiated_ver,
308            connection_id,
309            control_ops,
310            false,
311            false,
312        )
313    }
314
315    /// Register a module after its HELLO is accepted, without listing it before forwarding is installed.
316    pub(crate) fn register_unpublished_verified_with_control_ops(
317        &self,
318        manifest: ModuleManifest,
319        negotiated_ver: u8,
320        connection_id: ConnectionId,
321        control_ops: Vec<String>,
322        nonce_verified: bool,
323    ) -> Result<ModuleRegistration, RegistryError> {
324        self.register_active(
325            manifest,
326            negotiated_ver,
327            connection_id,
328            control_ops,
329            false,
330            nonce_verified,
331        )
332    }
333
334    fn register_active(
335        &self,
336        manifest: ModuleManifest,
337        negotiated_ver: u8,
338        connection_id: ConnectionId,
339        control_ops: Vec<String>,
340        publish: bool,
341        nonce_verified: bool,
342    ) -> Result<ModuleRegistration, RegistryError> {
343        let module_id = manifest.module_id.clone();
344        if let Err(reason) = module_id_path_hazard(&module_id) {
345            return Err(RegistryError::PathHazardModuleId { module_id, reason });
346        }
347        let mut inner = self.lock_inner()?;
348        if inner.modules.contains_key(&module_id) {
349            return Err(RegistryError::DuplicateModuleId { module_id });
350        }
351
352        let ready = manifest.ready.unwrap_or(true);
353        let registration = ModuleRegistration {
354            manifest,
355            ready,
356            negotiated_ver,
357            state: ChannelState::Active,
358            connection_id,
359            control_ops,
360        };
361
362        inner.modules.insert(module_id, registration.clone());
363        inner.admission_cache = None;
364        if nonce_verified {
365            inner.nonce_verified.insert(connection_id);
366        } else {
367            inner.nonce_verified.remove(&connection_id);
368        }
369        if publish {
370            inner.bump_generation();
371        } else {
372            inner.unpublished.insert(connection_id);
373        }
374        if let Some(sender) = inner.module_changes.get(&registration.manifest.module_id) {
375            sender.send_modify(|accepted| *accepted = accepted.wrapping_add(1));
376        }
377        Ok(registration)
378    }
379
380    /// Register a swap candidate for `manifest.module_id` into the candidate slot.
381    ///
382    /// The candidate is invisible to [`Self::get_module`], [`Self::list_modules`]
383    /// and every other by-id lookup until [`Self::promote_candidate`]. An active
384    /// registration for the id is not required, because the incumbent may die
385    /// while the swap is open; deciding whether a candidate may register at all
386    /// belongs to the caller that admits it. A second candidate for the same id
387    /// is refused.
388    ///
389    /// The candidate is published at once, meaning candidate-slot lookups
390    /// through [`Self::published_registration`] return it immediately. The
391    /// HELLO path uses
392    /// [`Self::register_unpublished_candidate_with_control_ops`] instead.
393    pub fn register_candidate_with_control_ops(
394        &self,
395        manifest: ModuleManifest,
396        negotiated_ver: u8,
397        connection_id: ConnectionId,
398        control_ops: Vec<String>,
399    ) -> Result<ModuleRegistration, RegistryError> {
400        self.register_candidate(
401            manifest,
402            negotiated_ver,
403            connection_id,
404            control_ops,
405            true,
406            false,
407        )
408    }
409
410    /// Register a swap candidate that [`Self::published_registration`] does not
411    /// return until [`Self::publish_registration`] is called for its
412    /// connection. The swap supervisor reads that lookup to decide the
413    /// candidate has registered, and it promotes a ready candidate straight
414    /// away; promoting one whose forwarding endpoint is not installed yet would
415    /// fail the cutover.
416    pub fn register_unpublished_candidate_with_control_ops(
417        &self,
418        manifest: ModuleManifest,
419        negotiated_ver: u8,
420        connection_id: ConnectionId,
421        control_ops: Vec<String>,
422    ) -> Result<ModuleRegistration, RegistryError> {
423        self.register_candidate(
424            manifest,
425            negotiated_ver,
426            connection_id,
427            control_ops,
428            false,
429            false,
430        )
431    }
432
433    /// Register a blue/green swap candidate after its required launch nonce has been verified.
434    pub(crate) fn register_unpublished_verified_candidate_with_control_ops(
435        &self,
436        manifest: ModuleManifest,
437        negotiated_ver: u8,
438        connection_id: ConnectionId,
439        control_ops: Vec<String>,
440    ) -> Result<ModuleRegistration, RegistryError> {
441        self.register_candidate(
442            manifest,
443            negotiated_ver,
444            connection_id,
445            control_ops,
446            false,
447            true,
448        )
449    }
450
451    fn register_candidate(
452        &self,
453        manifest: ModuleManifest,
454        negotiated_ver: u8,
455        connection_id: ConnectionId,
456        control_ops: Vec<String>,
457        publish: bool,
458        nonce_verified: bool,
459    ) -> Result<ModuleRegistration, RegistryError> {
460        let module_id = manifest.module_id.clone();
461        if let Err(reason) = module_id_path_hazard(&module_id) {
462            return Err(RegistryError::PathHazardModuleId { module_id, reason });
463        }
464        let mut inner = self.lock_inner()?;
465        if inner.candidates.contains_key(&module_id) {
466            return Err(RegistryError::DuplicateModuleId { module_id });
467        }
468        let ready = manifest.ready.unwrap_or(true);
469        let registration = ModuleRegistration {
470            manifest,
471            ready,
472            negotiated_ver,
473            state: ChannelState::Active,
474            connection_id,
475            control_ops,
476        };
477        inner.candidates.insert(module_id, registration.clone());
478        if nonce_verified {
479            inner.nonce_verified.insert(connection_id);
480        } else {
481            inner.nonce_verified.remove(&connection_id);
482        }
483        if !publish {
484            inner.unpublished.insert(connection_id);
485        }
486        inner.notify_module_changed(&registration.manifest.module_id);
487        Ok(registration)
488    }
489
490    /// Publish the registration `connection_id` holds, in whichever slot.
491    ///
492    /// For an active registration this is the moment `catalog.list` starts
493    /// listing the module, and the catalog generation advances under the same
494    /// lock, so no reader can see the new generation without the module or the
495    /// module without the new generation. A candidate is not listed either way;
496    /// publishing it only makes it visible to
497    /// [`Self::published_registration`].
498    ///
499    /// Returns `false` when there is nothing to publish: the connection holds
500    /// no registration any more, or it was already published.
501    pub fn publish_registration(&self, connection_id: ConnectionId) -> Result<bool, RegistryError> {
502        let mut inner = self.lock_inner()?;
503        Ok(inner.publish_registration(connection_id))
504    }
505
506    /// Install forwarding and publish without letting a registry reader observe
507    /// the interval after HELLO_ACK is queued but before publication. The install
508    /// callback may take forwarding's lock, but must not re-enter the registry:
509    /// the lock order is Registry -> ForwardingTable::inner.
510    ///
511    /// An install error leaves the registration unpublished. The caller must
512    /// roll it back after this method releases the registry lock. The outer
513    /// result reports registry locking errors; the inner result reports install
514    /// errors or whether the registration was published.
515    pub(crate) fn publish_registration_after<E>(
516        &self,
517        connection_id: ConnectionId,
518        install: impl FnOnce() -> Result<(), E>,
519    ) -> Result<Result<bool, E>, RegistryError> {
520        let mut inner = self.lock_inner()?;
521        if let Err(err) = install() {
522            return Ok(Err(err));
523        }
524        Ok(Ok(inner.publish_registration(connection_id)))
525    }
526
527    #[cfg(test)]
528    pub(crate) fn observe_next_lock_attempt(&self) -> std::sync::mpsc::Receiver<bool> {
529        let (sender, receiver) = std::sync::mpsc::channel();
530        *self.next_lock_attempt.lock().unwrap() = Some(sender);
531        receiver
532    }
533
534    /// Move the candidate for `module_id` into the active slot and demote the
535    /// previous active registration, in one registry critical section.
536    ///
537    /// Returns `Ok(None)` when there is no candidate to promote. Bumps the
538    /// catalog generation, because the listed registration for the id changed.
539    pub fn promote_candidate(
540        &self,
541        module_id: &str,
542    ) -> Result<Option<RegistryCutover>, RegistryError> {
543        let mut inner = self.lock_inner()?;
544        let Some(promoted) = inner.candidates.remove(module_id) else {
545            return Ok(None);
546        };
547        let superseded = inner
548            .modules
549            .insert(module_id.to_string(), promoted.clone());
550        if let Some(superseded) = superseded.clone() {
551            let replaced_connection_id = superseded.connection_id.get();
552            inner
553                .superseded_by
554                .insert(superseded.connection_id, promoted.connection_id);
555            inner.superseded.push(superseded);
556            info!(
557                target: "subc.registry",
558                module_id = %module_id,
559                connection_id = promoted.connection_id.get(),
560                replaced = true,
561                replaced_connection_id,
562                "module registration promoted"
563            );
564        }
565        inner.bump_generation();
566        inner.notify_module_changed(module_id);
567        Ok(Some(RegistryCutover {
568            promoted,
569            superseded,
570        }))
571    }
572
573    /// The ACTIVE registration for `module_id`. Candidates and superseded
574    /// incumbents are never returned: this is the lookup routing decisions use.
575    pub fn get_module(&self, module_id: &str) -> Result<Option<ModuleRegistration>, RegistryError> {
576        Ok(self.lock_inner()?.modules.get(module_id).cloned())
577    }
578
579    pub(crate) fn grants_control_op(
580        &self,
581        module_id: &str,
582        op: &str,
583    ) -> Result<bool, RegistryError> {
584        Ok(self
585            .lock_inner()?
586            .modules
587            .get(module_id)
588            .is_some_and(|registration| {
589                registration.control_ops.iter().any(|granted| granted == op)
590            }))
591    }
592
593    /// Unlike the published-only catalog view, admission sees staged active
594    /// registrations too, exactly as `get_module` does. A target whose
595    /// registration is accepted but not yet published in the catalog must
596    /// answer `target_unavailable`, not `unknown_module`, on an ordinary open.
597    pub(crate) fn route_admission_snapshot(
598        &self,
599    ) -> Result<Arc<RouteAdmissionSnapshot>, RegistryError> {
600        let mut inner = self.lock_inner()?;
601        if let Some(snapshot) = &inner.admission_cache {
602            return Ok(snapshot.clone());
603        }
604        let mut modules = inner
605            .modules
606            .values()
607            .map(|registration| Arc::new(RouteRegistration::from(registration)))
608            .collect::<Vec<_>>();
609        modules.sort_by(|a, b| a.module_id.cmp(&b.module_id));
610        let mut connections: HashMap<_, _> = modules
611            .iter()
612            .map(|registration| (registration.connection_id, registration.clone()))
613            .collect();
614        for registration in inner.candidates.values().chain(inner.superseded.iter()) {
615            connections
616                .entry(registration.connection_id)
617                .or_insert_with(|| Arc::new(RouteRegistration::from(registration)));
618        }
619        let snapshot = Arc::new(RouteAdmissionSnapshot {
620            modules,
621            unpublished: inner.unpublished.clone(),
622            connections,
623        });
624        inner.admission_cache = Some(snapshot.clone());
625        Ok(snapshot)
626    }
627
628    pub(crate) fn route_registration_by_connection(
629        &self,
630        connection: ConnectionId,
631    ) -> Result<Option<Arc<RouteRegistration>>, RegistryError> {
632        Ok(self
633            .route_admission_snapshot()?
634            .connections
635            .get(&connection)
636            .cloned())
637    }
638
639    /// The swap candidate registered for `module_id`, if any.
640    pub fn get_candidate(
641        &self,
642        module_id: &str,
643    ) -> Result<Option<ModuleRegistration>, RegistryError> {
644        Ok(self.lock_inner()?.candidates.get(module_id).cloned())
645    }
646
647    /// The registration held in one specific slot. See [`RegistrationSlot`].
648    pub fn registration(
649        &self,
650        slot: RegistrationSlot<'_>,
651    ) -> Result<Option<ModuleRegistration>, RegistryError> {
652        let inner = self.lock_inner()?;
653        Ok(match slot {
654            RegistrationSlot::Active(module_id) => inner.modules.get(module_id).cloned(),
655            RegistrationSlot::Candidate(module_id) => inner.candidates.get(module_id).cloned(),
656            RegistrationSlot::Connection(connection_id) => inner
657                .find_by_connection(connection_id)
658                .map(|(_, registration)| registration.clone()),
659        })
660    }
661
662    pub fn active_registration_count(&self) -> Result<usize, RegistryError> {
663        Ok(self.lock_inner()?.modules.len())
664    }
665
666    /// The catalog generation and the active registrations `catalog.list`
667    /// shows. Unpublished registrations (see
668    /// [`Self::register_unpublished_with_control_ops`]) are left out.
669    pub fn list_modules(&self) -> Result<(u64, Vec<ModuleRegistration>), RegistryError> {
670        let inner = self.lock_inner()?;
671        let mut modules = inner
672            .modules
673            .values()
674            .filter(|registration| !inner.unpublished.contains(&registration.connection_id))
675            .cloned()
676            .collect::<Vec<_>>();
677        modules.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
678        Ok((inner.generation, modules))
679    }
680
681    /// List published active registrations together with their HELLO nonce-verification status.
682    /// Both values are captured under the registry lock so a concurrent swap or
683    /// disconnect cannot separate a registration from its verification fact.
684    pub fn list_modules_with_nonce_verification(
685        &self,
686    ) -> Result<(u64, Vec<(ModuleRegistration, bool)>), RegistryError> {
687        let inner = self.lock_inner()?;
688        let mut registrations = inner
689            .modules
690            .values()
691            .filter(|registration| !inner.unpublished.contains(&registration.connection_id))
692            .collect::<Vec<_>>();
693        registrations.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
694        let modules = registrations
695            .into_iter()
696            .map(|registration| {
697                (
698                    registration.clone(),
699                    inner.nonce_verified.contains(&registration.connection_id),
700                )
701            })
702            .collect();
703        Ok((inner.generation, modules))
704    }
705
706    /// Every active registration, including unpublished ones.
707    ///
708    /// For the capability evaluator and the capability deny census, which
709    /// count a module as soon as it has registered. Whether `catalog.list`
710    /// shows the module yet does not change their verdicts.
711    pub fn list_registered_modules(&self) -> Result<Vec<ModuleRegistration>, RegistryError> {
712        let inner = self.lock_inner()?;
713        let mut modules = inner.modules.values().cloned().collect::<Vec<_>>();
714        modules.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
715        Ok(modules)
716    }
717
718    /// Like [`Self::registration`], but a registration that is not published
719    /// yet is reported as absent.
720    pub fn published_registration(
721        &self,
722        slot: RegistrationSlot<'_>,
723    ) -> Result<Option<ModuleRegistration>, RegistryError> {
724        let inner = self.lock_inner()?;
725        let registration = match slot {
726            RegistrationSlot::Active(module_id) => inner.modules.get(module_id),
727            RegistrationSlot::Candidate(module_id) => inner.candidates.get(module_id),
728            RegistrationSlot::Connection(connection_id) => inner
729                .find_by_connection(connection_id)
730                .map(|(_, registration)| registration),
731        };
732        Ok(registration
733            .filter(|registration| !inner.unpublished.contains(&registration.connection_id))
734            .cloned())
735    }
736
737    pub fn generation(&self) -> Result<u64, RegistryError> {
738        Ok(self.lock_inner()?.generation)
739    }
740
741    #[cfg(test)]
742    pub(crate) fn set_module_state_for_test(
743        &self,
744        module_id: &str,
745        state: ChannelState,
746    ) -> Result<bool, RegistryError> {
747        let mut inner = self.lock_inner()?;
748        let Some(registration) = inner.modules.get_mut(module_id) else {
749            return Ok(false);
750        };
751        registration.state = state;
752        inner.notify_module_changed(module_id);
753        Ok(true)
754    }
755
756    /// The registration owned by `connection_id`, searching the active,
757    /// candidate and superseded slots in that order.
758    pub fn get_module_by_connection(
759        &self,
760        connection_id: ConnectionId,
761    ) -> Result<Option<ModuleRegistration>, RegistryError> {
762        Ok(self
763            .lock_inner()?
764            .find_by_connection(connection_id)
765            .map(|(_, registration)| registration.clone()))
766    }
767
768    pub(crate) fn module_id_for_connection(
769        &self,
770        connection_id: ConnectionId,
771    ) -> Result<Option<String>, RegistryError> {
772        Ok(self
773            .lock_inner()?
774            .find_by_connection(connection_id)
775            .map(|(_, registration)| registration.manifest.module_id.clone()))
776    }
777
778    /// Replace only the validated role declarations owned by this connection.
779    pub fn replace_role_declarations_for_connection(
780        &self,
781        connection_id: ConnectionId,
782        role_declarations: BTreeMap<String, serde_json::Map<String, serde_json::Value>>,
783    ) -> Result<Option<ModuleRegistration>, RegistryError> {
784        let mut inner = self.lock_inner()?;
785        let Some((slot, _)) = inner.find_by_connection(connection_id) else {
786            return Ok(None);
787        };
788        let registration = inner
789            .registration_mut(slot, connection_id)
790            .expect("registration discovered under the same registry lock must still exist");
791        registration.manifest.role_declarations = role_declarations;
792        let updated = registration.clone();
793        if matches!(slot, SlotKind::Active) && !inner.unpublished.contains(&connection_id) {
794            inner.bump_generation();
795        }
796        inner.notify_module_changed(&updated.manifest.module_id);
797        Ok(Some(updated))
798    }
799
800    /// Replace the provider role list and, when supplied, the attested capability
801    /// declaration for the module owned by `connection_id`.
802    ///
803    /// Searches every slot: a swap candidate declares itself ready through this
804    /// call, and if only the active slot were searched its update would find
805    /// nothing and the candidate would never become ready. Only a change to the
806    /// active slot bumps the catalog generation, because only the active slot is
807    /// listed, and only once that registration is published.
808    pub fn replace_catalog_for_connection(
809        &self,
810        connection_id: ConnectionId,
811        provides: Vec<ProviderRole>,
812        capabilities: Option<CapabilityDeclarations>,
813        ready: Option<bool>,
814    ) -> Result<Option<ModuleRegistration>, RegistryError> {
815        let mut inner = self.lock_inner()?;
816        let Some((slot, _)) = inner.find_by_connection(connection_id) else {
817            return Ok(None);
818        };
819        let registration = inner
820            .registration_mut(slot, connection_id)
821            .expect("registration discovered under the same registry lock must still exist");
822        if let Some(capabilities) = capabilities.as_ref() {
823            let declares_federated = |caps: Option<&CapabilityDeclarations>| {
824                caps.is_some_and(|caps| {
825                    caps.provides
826                        .iter()
827                        .any(|cap| cap == subc_protocol::scope::SCOPE_FEDERATED_CAPABILITY)
828                })
829            };
830            // Pending binds rely on this declaration while the target module's outbound queue is full.
831            if declares_federated(registration.manifest.capabilities.as_ref())
832                != declares_federated(Some(capabilities))
833            {
834                return Err(RegistryError::FederatedCapabilityChanged);
835            }
836            // Pending binds also decide from this declaration whether to
837            // carry `caller`, so routes bound before and after an update
838            // could otherwise attest differently.
839            let declares_caller = |caps: Option<&CapabilityDeclarations>| {
840                caps.is_some_and(|caps| {
841                    caps.provides
842                        .iter()
843                        .any(|cap| cap == subc_protocol::peer::CALLER_ATTESTATION_CAPABILITY)
844                })
845            };
846            if declares_caller(registration.manifest.capabilities.as_ref())
847                != declares_caller(Some(capabilities))
848            {
849                return Err(RegistryError::CallerAttestationCapabilityChanged);
850            }
851        }
852        registration.manifest.provides = provides;
853        if let Some(capabilities) = capabilities {
854            registration.manifest.capabilities = Some(capabilities);
855        }
856        if let Some(ready) = ready {
857            registration.ready = ready;
858            registration.manifest.ready = Some(ready);
859        }
860        let updated = registration.clone();
861        if matches!(slot, SlotKind::Active) && !inner.unpublished.contains(&connection_id) {
862            inner.bump_generation();
863        }
864        inner.notify_module_changed(&updated.manifest.module_id);
865        Ok(Some(updated))
866    }
867
868    /// Deregister every module owned by a dropped connection, in any slot.
869    pub fn deregister_connection(
870        &self,
871        connection_id: ConnectionId,
872    ) -> Result<Vec<ModuleRegistration>, RegistryError> {
873        self.deregister_connection_with_reason(
874            connection_id,
875            RegistrationEndReason::ConnectionClosed,
876        )
877    }
878
879    pub(crate) fn deregister_connection_with_reason(
880        &self,
881        connection_id: ConnectionId,
882        reason: RegistrationEndReason,
883    ) -> Result<Vec<ModuleRegistration>, RegistryError> {
884        let mut inner = self.lock_inner()?;
885        // A registration that was never published was never listed, so
886        // removing it leaves the catalog, and its generation, as they were.
887        let was_published = !inner.unpublished.remove(&connection_id);
888        let module_ids: Vec<String> = inner
889            .modules
890            .iter()
891            .filter(|(_, registration)| registration.connection_id == connection_id)
892            .map(|(module_id, _)| module_id.clone())
893            .collect();
894
895        let mut closed: Vec<ModuleRegistration> = module_ids
896            .into_iter()
897            .filter_map(|module_id| inner.close_module(&module_id, was_published))
898            .collect();
899
900        let candidate_ids: Vec<String> = inner
901            .candidates
902            .iter()
903            .filter(|(_, registration)| registration.connection_id == connection_id)
904            .map(|(module_id, _)| module_id.clone())
905            .collect();
906        for module_id in candidate_ids {
907            if let Some(mut registration) = inner.candidates.remove(&module_id) {
908                registration.state = ChannelState::Closed;
909                closed.push(registration);
910            }
911        }
912
913        let (removed, kept): (Vec<_>, Vec<_>) = std::mem::take(&mut inner.superseded)
914            .into_iter()
915            .partition(|registration| registration.connection_id == connection_id);
916        let superseded_connections: std::collections::HashSet<_> = removed
917            .iter()
918            .map(|registration| registration.connection_id)
919            .collect();
920        inner.superseded = kept;
921        closed.extend(removed.into_iter().map(|mut registration| {
922            registration.state = ChannelState::Closed;
923            registration
924        }));
925        for registration in &closed {
926            inner.nonce_verified.remove(&registration.connection_id);
927            inner.notify_module_changed(&registration.manifest.module_id);
928            let replaced = superseded_connections.contains(&registration.connection_id);
929            let end_reason = if replaced {
930                RegistrationEndReason::Replaced
931            } else {
932                reason
933            };
934            let replaced_by_connection_id = if replaced {
935                inner
936                    .superseded_by
937                    .remove(&registration.connection_id)
938                    .map(ConnectionId::get)
939            } else {
940                None
941            };
942            if let Some(replaced_by_connection_id) = replaced_by_connection_id {
943                info!(
944                    target: "subc.registry",
945                    module_id = %registration.manifest.module_id,
946                    connection_id = registration.connection_id.get(),
947                    reason = %end_reason.as_str(),
948                    replaced_by_connection_id,
949                    "module registration ended"
950                );
951                continue;
952            }
953            info!(
954                target: "subc.registry",
955                module_id = %registration.manifest.module_id,
956                connection_id = registration.connection_id.get(),
957                reason = %end_reason.as_str(),
958                "module registration ended"
959            );
960        }
961        Ok(closed)
962    }
963
964    fn lock_inner(&self) -> Result<MutexGuard<'_, RegistryInner>, RegistryError> {
965        #[cfg(test)]
966        {
967            let observer = self.next_lock_attempt.lock().unwrap().take();
968            if let Some(observer) = observer {
969                // Tell a held-publication test whether its reader acquired the
970                // lock or must wait. This lets it release publication only after
971                // the reader actually attempts the lookup, without a timer.
972                match self.inner.try_lock() {
973                    Ok(inner) => {
974                        observer.send(true).unwrap();
975                        return Ok(inner);
976                    }
977                    Err(std::sync::TryLockError::WouldBlock) => observer.send(false).unwrap(),
978                    Err(std::sync::TryLockError::Poisoned(_)) => {
979                        return Err(RegistryError::Poisoned);
980                    }
981                }
982            }
983        }
984        self.inner.lock().map_err(|_| RegistryError::Poisoned)
985    }
986}
987
988/// Which internal slot a connection-keyed lookup found its registration in.
989#[derive(Debug, Clone, Copy, PartialEq, Eq)]
990enum SlotKind {
991    Active,
992    Candidate,
993    Superseded,
994}
995
996impl RegistryInner {
997    fn publish_registration(&mut self, connection_id: ConnectionId) -> bool {
998        if !self.unpublished.remove(&connection_id) {
999            return false;
1000        }
1001        let Some((slot, registration)) = self.find_by_connection(connection_id) else {
1002            return false;
1003        };
1004        let module_id = registration.manifest.module_id.clone();
1005        if matches!(slot, SlotKind::Active) {
1006            self.bump_generation();
1007        }
1008        self.notify_module_changed(&module_id);
1009        true
1010    }
1011
1012    fn notify_module_changed(&mut self, module_id: &str) {
1013        // Staging, candidate updates and disconnects can change admission facts
1014        // without advancing the published catalog generation.
1015        self.admission_cache = None;
1016        if let Some(sender) = self.module_changes.get(module_id) {
1017            sender.send_modify(|_| {});
1018        }
1019    }
1020
1021    fn find_by_connection(
1022        &self,
1023        connection_id: ConnectionId,
1024    ) -> Option<(SlotKind, &ModuleRegistration)> {
1025        let owned_by =
1026            |registration: &&ModuleRegistration| registration.connection_id == connection_id;
1027        self.modules
1028            .values()
1029            .find(owned_by)
1030            .map(|registration| (SlotKind::Active, registration))
1031            .or_else(|| {
1032                self.candidates
1033                    .values()
1034                    .find(owned_by)
1035                    .map(|registration| (SlotKind::Candidate, registration))
1036            })
1037            .or_else(|| {
1038                self.superseded
1039                    .iter()
1040                    .find(owned_by)
1041                    .map(|registration| (SlotKind::Superseded, registration))
1042            })
1043    }
1044
1045    fn registration_mut(
1046        &mut self,
1047        slot: SlotKind,
1048        connection_id: ConnectionId,
1049    ) -> Option<&mut ModuleRegistration> {
1050        let owned_by =
1051            |registration: &&mut ModuleRegistration| registration.connection_id == connection_id;
1052        match slot {
1053            SlotKind::Active => self.modules.values_mut().find(owned_by),
1054            SlotKind::Candidate => self.candidates.values_mut().find(owned_by),
1055            SlotKind::Superseded => self.superseded.iter_mut().find(owned_by),
1056        }
1057    }
1058
1059    fn close_module(&mut self, module_id: &str, listed: bool) -> Option<ModuleRegistration> {
1060        let mut registration = self.modules.remove(module_id)?;
1061        registration.state = ChannelState::Closed;
1062        if listed {
1063            self.bump_generation();
1064        }
1065        Some(registration)
1066    }
1067
1068    fn bump_generation(&mut self) {
1069        self.admission_cache = None;
1070        self.generation = self.generation.wrapping_add(1);
1071        if let Some(sender) = &self.catalog_changes {
1072            sender.send_replace(self.generation);
1073        }
1074    }
1075}
1076
1077#[derive(Debug, Clone, PartialEq, Eq)]
1078pub enum RegistryError {
1079    FederatedCapabilityChanged,
1080    /// A `catalog.update` tried to add or drop `caller-attestation/v1`, which
1081    /// decides whether binds carry `caller` and so is fixed at HELLO.
1082    CallerAttestationCapabilityChanged,
1083    DuplicateModuleId {
1084        module_id: String,
1085    },
1086    /// The id is unusable as a single path component. Enforced at
1087    /// registration because the daemon MINTS A STORAGE DESCRIPTOR from the
1088    /// self-claimed id verbatim (`<data_home>/cortexkit/<module_id>/store.db`),
1089    /// so an id carrying separators or dot components is a path-traversal or
1090    /// store-collision primitive handed to whoever claims it (issue #32). The
1091    /// derivations deliberately do NOT sanitize instead: sanitizing here would
1092    /// silently re-path every deployed store and desynchronize the Rust and TS
1093    /// derivations, while refusal changes nothing for any id that ever worked.
1094    PathHazardModuleId {
1095        module_id: String,
1096        reason: String,
1097    },
1098    Poisoned,
1099}
1100
1101impl fmt::Display for RegistryError {
1102    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1103        match self {
1104            Self::FederatedCapabilityChanged => write!(
1105                f,
1106                "scope-federated/v1 is fixed at HELLO; restart the module to change it"
1107            ),
1108            Self::CallerAttestationCapabilityChanged => write!(
1109                f,
1110                "caller-attestation/v1 is fixed at HELLO; restart the module to change it"
1111            ),
1112            Self::DuplicateModuleId { module_id } => {
1113                write!(f, "module_id '{module_id}' is already registered")
1114            }
1115            Self::PathHazardModuleId { module_id, reason } => {
1116                write!(
1117                    f,
1118                    "module_id '{}' is not usable as a path component: {reason}",
1119                    module_id.escape_debug()
1120                )
1121            }
1122            Self::Poisoned => write!(f, "registry lock was poisoned"),
1123        }
1124    }
1125}
1126
1127impl Error for RegistryError {}
1128
1129/// Why `module_id` cannot serve as a single path component, or `Ok(())`.
1130///
1131/// This is a REFUSAL predicate, not a sanitizer: every currently-working fleet
1132/// id passes untouched, and anything refused here never worked meaningfully --
1133/// it either escaped `<data_home>/cortexkit/` (separators, dot components) or
1134/// aliased another module's store (`a/b` vs `a//b` collapsing on POSIX).
1135/// Colons are allowed: reserved-namespace children (`mcp:...`) register today
1136/// and a colon cannot traverse. Windows path legality is the store library's
1137/// concern, not an identity rule.
1138pub fn module_id_path_hazard(module_id: &str) -> Result<(), String> {
1139    subc_protocol::module_id::module_id_path_hazard(module_id)
1140}
1141
1142#[cfg(test)]
1143mod change_notification_tests {
1144    use super::*;
1145
1146    fn manifest() -> ModuleManifest {
1147        ModuleManifest::builder("watched", "1.0.0")
1148            .protocol_ver(1)
1149            .build()
1150    }
1151
1152    fn changed(receiver: &mut watch::Receiver<u64>) {
1153        assert!(
1154            receiver.has_changed().unwrap(),
1155            "registry write must notify"
1156        );
1157        receiver.borrow_and_update();
1158    }
1159
1160    #[test]
1161    fn every_registration_write_notifies_only_its_module() {
1162        let registry = Registry::default();
1163        let mut events = registry.subscribe_module_changes("watched").unwrap();
1164        let other = registry.subscribe_module_changes("other").unwrap();
1165        let active = ConnectionId::new(1);
1166        let candidate = ConnectionId::new(2);
1167        registry
1168            .register_with_control_ops(manifest(), 1, active, vec![])
1169            .unwrap();
1170        changed(&mut events);
1171        registry
1172            .set_module_state_for_test("watched", ChannelState::Active)
1173            .unwrap();
1174        changed(&mut events);
1175        registry
1176            .replace_catalog_for_connection(active, vec![], None, Some(true))
1177            .unwrap();
1178        changed(&mut events);
1179        registry
1180            .register_candidate_with_control_ops(manifest(), 1, candidate, vec![])
1181            .unwrap();
1182        changed(&mut events);
1183        registry
1184            .replace_catalog_for_connection(candidate, vec![], None, Some(true))
1185            .unwrap();
1186        changed(&mut events);
1187        registry.promote_candidate("watched").unwrap().unwrap();
1188        changed(&mut events);
1189        // Superseded connections can still update and deregister their slot.
1190        registry
1191            .replace_catalog_for_connection(active, vec![], None, Some(false))
1192            .unwrap();
1193        changed(&mut events);
1194        registry.deregister_connection(active).unwrap();
1195        changed(&mut events);
1196        registry.deregister_connection(candidate).unwrap();
1197        changed(&mut events);
1198        registry
1199            .register_candidate_with_control_ops(manifest(), 1, candidate, vec![])
1200            .unwrap();
1201        changed(&mut events);
1202        registry.deregister_connection(candidate).unwrap();
1203        changed(&mut events);
1204        assert!(
1205            !other.has_changed().unwrap(),
1206            "other module must stay parked"
1207        );
1208    }
1209
1210    #[test]
1211    fn subscription_before_read_keeps_a_change_until_waited_on() {
1212        let registry = Registry::default();
1213        let mut events = registry.subscribe_module_changes("watched").unwrap();
1214        assert!(registry.get_module("watched").unwrap().is_none());
1215        registry
1216            .register_with_control_ops(manifest(), 1, ConnectionId::new(1), vec![])
1217            .unwrap();
1218        // Neither a later lookup nor a coalesced catalog update consumes it.
1219        registry.get_module("watched").unwrap().unwrap();
1220        registry
1221            .replace_catalog_for_connection(ConnectionId::new(1), vec![], None, Some(true))
1222            .unwrap();
1223        changed(&mut events);
1224        assert!(!events.has_changed().unwrap());
1225    }
1226}
1227
1228#[cfg(test)]
1229mod publication_tests {
1230    use super::*;
1231
1232    fn manifest() -> ModuleManifest {
1233        ModuleManifest::builder("m", "1.0.0")
1234            .protocol_ver(1)
1235            .build()
1236    }
1237
1238    /// An unpublished registration holds its id and answers routing lookups,
1239    /// but `list_modules` leaves it out and the generation stays put until
1240    /// it is published; publishing lists it and bumps the generation once.
1241    #[test]
1242    fn unpublished_registration_is_unlisted_until_published() {
1243        let registry = Registry::default();
1244        let connection = ConnectionId::new(1);
1245        registry
1246            .register_unpublished_with_control_ops(manifest(), 1, connection, vec![])
1247            .unwrap();
1248        assert_eq!(registry.list_modules().unwrap(), (0, Vec::new()));
1249        assert!(registry.get_module("m").unwrap().is_some());
1250        assert_eq!(registry.list_registered_modules().unwrap().len(), 1);
1251        assert!(registry
1252            .published_registration(RegistrationSlot::Active("m"))
1253            .unwrap()
1254            .is_none());
1255        assert!(matches!(
1256            registry.register_with_control_ops(manifest(), 1, ConnectionId::new(2), vec![]),
1257            Err(RegistryError::DuplicateModuleId { .. })
1258        ));
1259        // A catalog update before publication does not move the generation.
1260        registry
1261            .replace_catalog_for_connection(connection, vec![], None, Some(true))
1262            .unwrap();
1263        assert_eq!(registry.generation().unwrap(), 0);
1264
1265        assert!(registry.publish_registration(connection).unwrap());
1266        let (generation, listed) = registry.list_modules().unwrap();
1267        assert_eq!(generation, 1);
1268        assert_eq!(listed.len(), 1);
1269        assert!(!registry.publish_registration(connection).unwrap());
1270        assert_eq!(registry.generation().unwrap(), 1);
1271    }
1272
1273    /// Removing a registration that was never published leaves no catalog
1274    /// trace: the generation does not move, and a later publish is a no-op.
1275    #[test]
1276    fn deregistering_an_unpublished_registration_leaves_the_generation() {
1277        let registry = Registry::default();
1278        let connection = ConnectionId::new(1);
1279        registry
1280            .register_unpublished_with_control_ops(manifest(), 1, connection, vec![])
1281            .unwrap();
1282        assert_eq!(registry.deregister_connection(connection).unwrap().len(), 1);
1283        assert_eq!(registry.list_modules().unwrap(), (0, Vec::new()));
1284        assert!(!registry.publish_registration(connection).unwrap());
1285        assert_eq!(registry.generation().unwrap(), 0);
1286    }
1287
1288    /// An unpublished candidate holds the candidate slot but
1289    /// `published_registration` does not return it until it is published.
1290    /// Publishing a candidate does not bump the generation: candidates are
1291    /// never listed.
1292    #[test]
1293    fn unpublished_candidate_is_hidden_from_published_lookups() {
1294        let registry = Registry::default();
1295        let candidate = ConnectionId::new(2);
1296        registry
1297            .register_unpublished_candidate_with_control_ops(manifest(), 1, candidate, vec![])
1298            .unwrap();
1299        assert!(registry
1300            .registration(RegistrationSlot::Candidate("m"))
1301            .unwrap()
1302            .is_some());
1303        assert!(registry
1304            .published_registration(RegistrationSlot::Candidate("m"))
1305            .unwrap()
1306            .is_none());
1307        assert!(registry
1308            .published_registration(RegistrationSlot::Connection(candidate))
1309            .unwrap()
1310            .is_none());
1311        assert!(registry.publish_registration(candidate).unwrap());
1312        assert!(registry
1313            .published_registration(RegistrationSlot::Candidate("m"))
1314            .unwrap()
1315            .is_some());
1316        assert_eq!(registry.generation().unwrap(), 0);
1317    }
1318}
1319
1320#[cfg(test)]
1321mod path_hazard_tests {
1322    use super::*;
1323    use crate::ConnectionId;
1324    use subc_protocol::manifest::ModuleManifest;
1325
1326    fn manifest(module_id: &str) -> ModuleManifest {
1327        ModuleManifest::builder(module_id, "0.1.0")
1328            .protocol_ver(1)
1329            .build()
1330    }
1331
1332    #[test]
1333    fn path_hazard_ids_are_refused_and_nothing_registers() {
1334        let registry = Registry::default();
1335        for (bad, reason_fragment) in [
1336            ("../escape", "path separator"),
1337            ("a/b", "path separator"),
1338            ("a\\b", "path separator"),
1339            ("..", "dot path component"),
1340            (".", "dot path component"),
1341            ("", "empty"),
1342            ("evil\u{0}id", "control character"),
1343        ] {
1344            let err = registry
1345                .register_with_control_ops(manifest(bad), 1, ConnectionId::new(7), Vec::new())
1346                .expect_err("path-hazard id must refuse");
1347            // Reason asserted so a predicate throwing the WRONG refusal fails.
1348            assert!(
1349                err.to_string().contains(reason_fragment),
1350                "id {bad:?}: expected {reason_fragment:?} in {err}"
1351            );
1352        }
1353        // THE EFFECT, not just the verdicts: no refusal left a registration
1354        // behind, and the generation never moved.
1355        assert_eq!(registry.active_registration_count().unwrap(), 0);
1356        assert_eq!(registry.generation().unwrap(), 0);
1357    }
1358
1359    #[test]
1360    fn module_id_path_component_length_matches_shared_refusal_vectors() {
1361        let doc: serde_json::Value = serde_json::from_str(include_str!(
1362            "../tests/golden/module_id_path_component_refusals.json"
1363        ))
1364        .expect("refusal fixture parses");
1365
1366        for case in doc["vectors"].as_array().expect("vectors array") {
1367            let name = case["name"].as_str().expect("name");
1368            let module_id = case["module_id"]["unit"]
1369                .as_str()
1370                .expect("module_id unit")
1371                .repeat(
1372                    case["module_id"]["repeat"]
1373                        .as_u64()
1374                        .expect("module_id repeat") as usize,
1375                );
1376            assert_eq!(
1377                module_id.len(),
1378                case["utf8_bytes"].as_u64().expect("utf8 bytes") as usize
1379            );
1380
1381            let expected = case["expect_reason"].as_str().map(str::to_owned);
1382            assert_eq!(
1383                module_id_path_hazard(&module_id).err(),
1384                expected,
1385                "shared refusal vector {name:?} diverged"
1386            );
1387        }
1388    }
1389
1390    #[test]
1391    fn working_id_shapes_register_including_namespace_colons() {
1392        let registry = Registry::default();
1393        for (i, good) in ["magic-context", "mcp:everything", "v1.2-module"]
1394            .iter()
1395            .enumerate()
1396        {
1397            registry
1398                .register_with_control_ops(
1399                    manifest(good),
1400                    1,
1401                    ConnectionId::new(10 + i as u64),
1402                    Vec::new(),
1403                )
1404                .unwrap_or_else(|err| panic!("id {good:?} must register: {err}"));
1405        }
1406        assert_eq!(registry.active_registration_count().unwrap(), 3);
1407    }
1408}
1409
1410#[cfg(test)]
1411mod swap_slot_tests {
1412    use super::*;
1413
1414    fn manifest(module_id: &str, ready: Option<bool>) -> ModuleManifest {
1415        let mut manifest = ModuleManifest::builder(module_id, "0.1.0").build();
1416        manifest.ready = ready;
1417        manifest
1418    }
1419
1420    const INCUMBENT: ConnectionId = ConnectionId(1);
1421    const CANDIDATE: ConnectionId = ConnectionId(2);
1422
1423    fn registry_with_candidate() -> Registry {
1424        let registry = Registry::default();
1425        registry
1426            .register_with_control_ops(manifest("m", None), 1, INCUMBENT, Vec::new())
1427            .unwrap();
1428        registry
1429            .register_candidate_with_control_ops(
1430                manifest("m", Some(false)),
1431                1,
1432                CANDIDATE,
1433                Vec::new(),
1434            )
1435            .unwrap();
1436        registry
1437    }
1438
1439    #[test]
1440    fn candidate_is_invisible_to_by_id_lookups_and_listing() {
1441        let registry = registry_with_candidate();
1442        let generation = registry.generation().unwrap();
1443        assert_eq!(
1444            registry.get_module("m").unwrap().unwrap().connection_id,
1445            INCUMBENT
1446        );
1447        let (listed_generation, listed) = registry.list_modules().unwrap();
1448        assert_eq!(listed.len(), 1);
1449        assert_eq!(listed[0].connection_id, INCUMBENT);
1450        assert_eq!(listed_generation, generation);
1451        assert_eq!(registry.active_registration_count().unwrap(), 1);
1452        assert_eq!(
1453            registry.get_candidate("m").unwrap().unwrap().connection_id,
1454            CANDIDATE
1455        );
1456        assert_eq!(
1457            registry
1458                .register_candidate_with_control_ops(
1459                    manifest("m", None),
1460                    1,
1461                    ConnectionId(3),
1462                    Vec::new()
1463                )
1464                .unwrap_err(),
1465            RegistryError::DuplicateModuleId {
1466                module_id: "m".to_string()
1467            }
1468        );
1469    }
1470
1471    #[test]
1472    fn promoted_candidate_keeps_its_verified_nonce_fact() {
1473        let registry = Registry::default();
1474        registry
1475            .register_unpublished_verified_candidate_with_control_ops(
1476                manifest("m", Some(true)),
1477                1,
1478                CANDIDATE,
1479                Vec::new(),
1480            )
1481            .unwrap();
1482        assert!(registry.publish_registration(CANDIDATE).unwrap());
1483        assert!(registry
1484            .list_modules_with_nonce_verification()
1485            .unwrap()
1486            .1
1487            .is_empty());
1488
1489        registry.promote_candidate("m").unwrap().unwrap();
1490        let (_, modules) = registry.list_modules_with_nonce_verification().unwrap();
1491        assert_eq!(modules.len(), 1);
1492        assert!(modules[0].1);
1493    }
1494
1495    /// Without the candidate slot in the connection-keyed search, this update
1496    /// returns `Ok(None)` and the candidate never becomes ready.
1497    #[test]
1498    fn candidate_catalog_update_reaches_the_candidate_registration() {
1499        let registry = registry_with_candidate();
1500        assert!(!registry.get_candidate("m").unwrap().unwrap().ready);
1501
1502        let updated = registry
1503            .replace_catalog_for_connection(CANDIDATE, Vec::new(), None, Some(true))
1504            .unwrap()
1505            .expect("the candidate's own connection finds its registration");
1506
1507        assert_eq!(updated.connection_id, CANDIDATE);
1508        assert!(registry.get_candidate("m").unwrap().unwrap().ready);
1509        assert_eq!(
1510            registry.get_module_by_connection(CANDIDATE).unwrap(),
1511            Some(updated)
1512        );
1513        assert_eq!(
1514            registry.get_module("m").unwrap().unwrap().connection_id,
1515            INCUMBENT,
1516            "a candidate's update must not touch the active registration"
1517        );
1518    }
1519
1520    #[test]
1521    fn promotion_swaps_slots_and_each_connection_still_deregisters_its_own() {
1522        let registry = registry_with_candidate();
1523        let before = registry.generation().unwrap();
1524        let cutover = registry.promote_candidate("m").unwrap().unwrap();
1525        assert_eq!(cutover.promoted.connection_id, CANDIDATE);
1526        assert_eq!(cutover.superseded.unwrap().connection_id, INCUMBENT);
1527        assert_ne!(registry.generation().unwrap(), before);
1528        assert_eq!(registry.promote_candidate("m").unwrap(), None);
1529
1530        assert_eq!(
1531            registry
1532                .registration(RegistrationSlot::Active("m"))
1533                .unwrap()
1534                .unwrap()
1535                .connection_id,
1536            CANDIDATE
1537        );
1538        assert!(registry
1539            .registration(RegistrationSlot::Candidate("m"))
1540            .unwrap()
1541            .is_none());
1542        assert!(registry
1543            .registration(RegistrationSlot::Connection(INCUMBENT))
1544            .unwrap()
1545            .is_some());
1546
1547        let closed = registry.deregister_connection(INCUMBENT).unwrap();
1548        assert_eq!(closed.len(), 1);
1549        assert_eq!(closed[0].connection_id, INCUMBENT);
1550        assert_eq!(closed[0].state, ChannelState::Closed);
1551        assert!(registry
1552            .registration(RegistrationSlot::Connection(INCUMBENT))
1553            .unwrap()
1554            .is_none());
1555        assert_eq!(
1556            registry.get_module("m").unwrap().unwrap().connection_id,
1557            CANDIDATE
1558        );
1559    }
1560
1561    #[test]
1562    fn a_dropped_candidate_deregisters_from_the_candidate_slot_only() {
1563        let registry = registry_with_candidate();
1564        let closed = registry.deregister_connection(CANDIDATE).unwrap();
1565        assert_eq!(closed.len(), 1);
1566        assert_eq!(closed[0].connection_id, CANDIDATE);
1567        assert!(registry.get_candidate("m").unwrap().is_none());
1568        assert_eq!(
1569            registry.get_module("m").unwrap().unwrap().connection_id,
1570            INCUMBENT
1571        );
1572    }
1573}