Skip to main content

subc_client_rs/
consumer.rs

1use std::{
2    collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque},
3    error::Error,
4    fmt,
5    future::Future,
6    io,
7    path::{Path, PathBuf},
8    pin::Pin,
9    sync::{
10        atomic::{AtomicBool, AtomicU64, Ordering},
11        Arc, Mutex, MutexGuard, OnceLock,
12    },
13    task::{Context, Poll},
14    time::{Duration, SystemTime, UNIX_EPOCH},
15};
16
17use sha2::{Digest, Sha256};
18pub use subc_control::SupervisorEntry;
19use subc_control::{
20    CatalogEntry, ClientControlRequest, ClientControlResponse, ConsumerIdentity, PollKind,
21    RouteOpenReplyExt, RouteOpenRequestExt, ROUTE_CLOSE_REASONS_CAPABILITY,
22};
23/// The spawn snapshot types, re-exported so a caller of
24/// [`SubcConsumer::spawn_snapshot`] needs no direct `subc-control` dependency.
25pub use subc_control::{LiveSpawn, SpawnCursor, SpawnEvent, SpawnEventKind, SpawnSnapshot};
26pub use subc_control::{RouteOpenTarget, RouteOpenTargetKind};
27/// The scope a route is opened under, re-exported so a caller of
28/// [`SubcConsumer::open_route_scoped`] can name the type from this crate.
29pub use subc_protocol::scope::ScopeSelector;
30use subc_protocol::{
31    error_codes, manifest::is_valid_capability_identifier, AdmissionClass, BindIdentity, ErrorBody,
32    Flags, Frame, FrameBuildError, FrameType, Priority, RouteTarget, FLAG_SUBSCRIPTION,
33    SUBC_MODULE_ID_ENV,
34};
35
36use crate::{
37    ActivityCursor, ActivityQueryRequest, ActivityQueryResponse, ActivitySubscribeRequest,
38    ActivitySubscription, RouteHandle,
39};
40use subc_transport::{
41    authenticate_client, connection_file, read_frame, write_frame, AuthError, ConnectionFileError,
42    FrameIoError,
43};
44use tokio::{
45    io::{AsyncRead, AsyncWrite, AsyncWriteExt, BufWriter},
46    net::TcpStream,
47    sync::{mpsc, oneshot, watch, Notify, OwnedSemaphorePermit, Semaphore},
48    task::JoinHandle,
49    time::{sleep, sleep_until, timeout_at, Instant},
50};
51use tokio_util::sync::CancellationToken;
52
53const DEFAULT_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(2);
54// Describe is a daemon-local control read. A daemon that cannot answer within
55// two seconds is overloaded or hung; leave the rest of the route's budget for
56// opening without the optional close-reason declaration.
57const CAPABILITY_PROBE_TIMEOUT: Duration = Duration::from_secs(2);
58pub const DEFAULT_CALL_TIMEOUT: Duration = Duration::from_secs(30);
59// Sized against a real module restart, not a single bind: the daemon drains the
60// module's routes (up to 30s), waits for the old process to stop (up to its stop
61// budget, 25s by default), then boots the new one. A measured prefrontal-core
62// restart kept route.open refused for 62.5s end to end, which a 30s budget gave
63// up on halfway through. 90s covers that window with room for a slow boot. The
64// retries still end at the call's own deadline (`CallOptions::timeout`) when
65// that comes first, so a caller that wants to ride out a restart raises both.
66pub const DEFAULT_ROUTE_RETRY_DEADLINE: Duration = Duration::from_secs(90);
67/// The most route.open requests a consumer keeps outstanding on its connection.
68/// Mirrors the daemon's `MAX_PENDING_ROUTE_OPENS_PER_CONNECTION`
69/// (`crates/subc-daemon/src/server.rs`): the daemon refuses every open beyond
70/// that many with a retryable `target_unavailable`, so sending more at once only
71/// manufactures refusals. Extra opens wait here, first come first served, and the
72/// wait counts against the same deadline as retrying refusals.
73pub const MAX_ROUTE_OPENS_IN_FLIGHT: usize = 8;
74const DEFAULT_RESTORED_DEBOUNCE: Duration = Duration::from_millis(250);
75pub const DEFAULT_LIVENESS_PROBE_WINDOW: Duration = Duration::from_secs(2);
76const EGRESS_BUFFER: usize = 128;
77const DEFAULT_ROUTE_WINDOW: usize = 1024;
78const DEFAULT_SUBSCRIPTION_EVENT_BUFFER: usize = 128;
79const DEFAULT_PUSH_EVENT_BUFFER: usize = 128;
80const REVERSE_REQUEST_UNHANDLED: &str = "reverse_request_unhandled";
81/// The spawn stream's event buffer. A subscription from an old cursor receives the
82/// daemon's whole retained ring at once (4096 events in the current daemon); a smaller
83/// buffer would drop the stream on its own replay. Twice that leaves room for live
84/// events arriving while the replay is being read.
85const SPAWN_EVENT_BUFFER: usize = 8192;
86// Hold the daemon's 1024-entry activity replay plus live entries without ending
87// a healthy subscriber merely because its initial replay arrives in a burst.
88const ACTIVITY_EVENT_BUFFER: usize = 2048;
89
90#[cfg(test)]
91#[path = "activity_consumer_tests.rs"]
92mod activity_consumer_tests;
93
94mod cancellation;
95mod slots;
96use slots::*;
97mod reservation;
98pub use reservation::{CorrelationId, PendingReply, RequestBody, RequestReservation};
99mod catalog;
100mod supervisor_ops;
101use catalog::decode_route_open_response;
102pub use catalog::CatalogSubscription;
103
104#[cfg(test)]
105mod reader_skew_tests;
106
107#[cfg(test)]
108mod connection_ops_tests;
109pub use cancellation::{CancelHandle, CancelOutcome};
110use cancellation::{CancelRegistration, UnaryCancel};
111pub use supervisor_ops::{
112    HealthProbeResponse, ServerDescription, StderrTailResponse, SupervisorAck,
113    SupervisorHealthResponse, SupervisorProvenanceResponse,
114};
115
116/// `supervisor.spawn_subscribe` refused a cursor from another daemon incarnation.
117pub const SPAWN_CURSOR_INCARNATION_MISMATCH: &str = "spawn_cursor_incarnation_mismatch";
118/// `supervisor.spawn_subscribe` refused a cursor older than the daemon's retained ring.
119pub const SPAWN_CURSOR_TOO_OLD: &str = "spawn_cursor_too_old";
120/// The daemon dropped a spawn subscriber that fell too far behind.
121pub const SPAWN_SUBSCRIBER_LAGGED: &str = "spawn_subscriber_lagged";
122
123type ReverseRequestFuture =
124    Pin<Box<dyn Future<Output = Result<Vec<u8>, ReverseRequestError>> + Send + 'static>>;
125type ReverseRequestHandler =
126    Arc<dyn Fn(Vec<u8>, ReverseRequestContext) -> ReverseRequestFuture + Send + Sync + 'static>;
127
128#[derive(Debug, Clone, PartialEq, Eq)]
129pub struct ReverseRequestContext {
130    pub corr: u64,
131    pub method: String,
132}
133
134#[derive(Debug, Clone, PartialEq, Eq)]
135pub struct ReverseRequestError {
136    message: String,
137}
138
139impl ReverseRequestError {
140    pub fn new(message: impl Into<String>) -> Self {
141        Self {
142            message: message.into(),
143        }
144    }
145}
146
147impl fmt::Display for ReverseRequestError {
148    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
149        f.write_str(&self.message)
150    }
151}
152
153impl Error for ReverseRequestError {}
154
155#[derive(Default)]
156struct ReverseRequestRegistryState {
157    handlers: HashMap<String, ReverseRequestHandler>,
158    declared_families: Option<BTreeSet<String>>,
159    consumer_capabilities: BTreeSet<String>,
160}
161
162/// Handler registry prepared before route.open. It carries the reverse-request
163/// method families and any extra capability strings added through route options'
164/// `with_consumer_capability` builder.
165#[derive(Clone, Default)]
166pub struct ReverseRequestRegistry {
167    inner: Arc<Mutex<ReverseRequestRegistryState>>,
168}
169
170impl fmt::Debug for ReverseRequestRegistry {
171    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
172        f.debug_struct("ReverseRequestRegistry")
173            .field("capabilities", &self.capabilities())
174            .field("consumer_capabilities", &self.consumer_capabilities())
175            .finish()
176    }
177}
178
179impl PartialEq for ReverseRequestRegistry {
180    fn eq(&self, other: &Self) -> bool {
181        self.capabilities() == other.capabilities()
182            && self.consumer_capabilities() == other.consumer_capabilities()
183    }
184}
185
186impl Eq for ReverseRequestRegistry {}
187
188impl ReverseRequestRegistry {
189    pub fn new() -> Self {
190        Self::default()
191    }
192
193    pub fn on_request<F, Fut>(
194        &self,
195        method_family: impl Into<String>,
196        handler: F,
197    ) -> Result<(), ReverseRequestRegistrationError>
198    where
199        F: Fn(Vec<u8>, ReverseRequestContext) -> Fut + Send + Sync + 'static,
200        Fut: Future<Output = Vec<u8>> + Send + 'static,
201    {
202        self.on_request_fallible(method_family, move |body, ctx| {
203            let future = handler(body, ctx);
204            async move { Ok(future.await) }
205        })
206    }
207
208    pub fn on_request_fallible<F, Fut>(
209        &self,
210        method_family: impl Into<String>,
211        handler: F,
212    ) -> Result<(), ReverseRequestRegistrationError>
213    where
214        F: Fn(Vec<u8>, ReverseRequestContext) -> Fut + Send + Sync + 'static,
215        Fut: Future<Output = Result<Vec<u8>, ReverseRequestError>> + Send + 'static,
216    {
217        let method_family = method_family.into();
218        if !is_valid_method_family(&method_family) {
219            return Err(ReverseRequestRegistrationError::InvalidFamily(
220                method_family,
221            ));
222        }
223        let mut state = self
224            .inner
225            .lock()
226            .unwrap_or_else(|poisoned| poisoned.into_inner());
227        if state
228            .declared_families
229            .as_ref()
230            .is_some_and(|families| !families.contains(&method_family))
231        {
232            return Err(ReverseRequestRegistrationError::NotDeclared(method_family));
233        }
234        state.handlers.insert(
235            method_family,
236            Arc::new(move |body, ctx| Box::pin(handler(body, ctx))),
237        );
238        Ok(())
239    }
240
241    fn capabilities(&self) -> Vec<String> {
242        let state = self
243            .inner
244            .lock()
245            .unwrap_or_else(|poisoned| poisoned.into_inner());
246        let mut capabilities = state.handlers.keys().cloned().collect::<Vec<_>>();
247        capabilities.sort();
248        capabilities
249    }
250
251    fn declare_consumer_capability(
252        &self,
253        capability: String,
254    ) -> Result<(), ConsumerCapabilityError> {
255        if capability.is_empty()
256            || capability.len() > 64
257            || !capability.bytes().all(|byte| (0x21..=0x7e).contains(&byte))
258        {
259            return Err(ConsumerCapabilityError { capability });
260        }
261
262        self.inner
263            .lock()
264            .unwrap_or_else(|poisoned| poisoned.into_inner())
265            .consumer_capabilities
266            .insert(capability);
267        Ok(())
268    }
269
270    fn consumer_capabilities(&self) -> Vec<String> {
271        self.inner
272            .lock()
273            .unwrap_or_else(|poisoned| poisoned.into_inner())
274            .consumer_capabilities
275            .iter()
276            .cloned()
277            .collect()
278    }
279
280    fn handler(&self, method_family: &str) -> Option<ReverseRequestHandler> {
281        self.inner
282            .lock()
283            .unwrap_or_else(|poisoned| poisoned.into_inner())
284            .handlers
285            .get(method_family)
286            .cloned()
287    }
288
289    pub(crate) fn seal(&self) {
290        let mut state = self
291            .inner
292            .lock()
293            .unwrap_or_else(|poisoned| poisoned.into_inner());
294        if state.declared_families.is_none() {
295            state.declared_families = Some(state.handlers.keys().cloned().collect());
296        }
297    }
298}
299
300#[derive(Debug, Clone, PartialEq, Eq)]
301pub enum ReverseRequestRegistrationError {
302    InvalidFamily(String),
303    NotDeclared(String),
304    NotConsumerRoute,
305}
306
307impl fmt::Display for ReverseRequestRegistrationError {
308    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
309        match self {
310            Self::InvalidFamily(family) => {
311                write!(f, "invalid reverse-request method family {family:?}")
312            }
313            Self::NotDeclared(family) => write!(
314                f,
315                "reverse-request capability {family:?} was not registered before route.open"
316            ),
317            Self::NotConsumerRoute => {
318                f.write_str("route handle does not belong to a consumer route")
319            }
320        }
321    }
322}
323
324impl Error for ReverseRequestRegistrationError {}
325
326fn is_valid_method_family(value: &str) -> bool {
327    let mut segments = value.split(['.', '_', '-']);
328    segments.next().is_some_and(|segment| {
329        segment
330            .as_bytes()
331            .first()
332            .is_some_and(u8::is_ascii_lowercase)
333            && segment
334                .bytes()
335                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
336    }) && segments.all(|segment| {
337        !segment.is_empty()
338            && segment
339                .bytes()
340                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
341    })
342}
343
344/// Reverse-request handlers live in a process-global map keyed by an id the
345/// `RouteHandle` carries, rather than inside the handle itself.
346///
347/// WHY, so nobody "simplifies" this into the handle later: `RouteHandle` is
348/// `Copy`, deliberately and publicly. Every route-scoped call in this SDK takes
349/// it by value, and the fleet's Rust consumers pass it around freely on that
350/// assumption. An `Arc<ReverseRequestRegistry>` field would make it non-`Copy`
351/// and break every one of those call sites across twelve repositories, for a
352/// lane most of them do not use.
353///
354/// The cost is real and bounded: entries are removed on every teardown path
355/// (`remove_route`, `remove_route_by_handle`, `drain_routes`,
356/// `uninstall_route_handle`, `install_ingress_handle`), so a consumer that opens
357/// and closes routes for its lifetime does not grow. A consumer DROPPED without
358/// closing leaks its remaining entries until process exit, which is the one gap
359/// and is acceptable because nothing else about a dropped consumer is reclaimed
360/// either.
361///
362/// If `RouteHandle` ever stops being `Copy` for another reason, move this into
363/// the handle and delete the map — the indirection exists only to preserve that
364/// property.
365static NEXT_REVERSE_REQUEST_REGISTRY_ID: AtomicU64 = AtomicU64::new(1);
366static REVERSE_REQUEST_REGISTRIES: OnceLock<Mutex<HashMap<u64, ReverseRequestRegistry>>> =
367    OnceLock::new();
368
369fn reverse_request_registries() -> &'static Mutex<HashMap<u64, ReverseRequestRegistry>> {
370    REVERSE_REQUEST_REGISTRIES.get_or_init(|| Mutex::new(HashMap::new()))
371}
372
373pub(crate) fn install_reverse_request_registry(registry: ReverseRequestRegistry) -> u64 {
374    let id = crate::checked_increment(&NEXT_REVERSE_REQUEST_REGISTRY_ID)
375        .expect("reverse-request route registry id exhausted");
376    reverse_request_registries()
377        .lock()
378        .unwrap_or_else(|poisoned| poisoned.into_inner())
379        .insert(id, registry);
380    id
381}
382
383pub(crate) fn route_reverse_request_registry(
384    id: u64,
385) -> Result<ReverseRequestRegistry, ReverseRequestRegistrationError> {
386    if id == 0 {
387        return Err(ReverseRequestRegistrationError::NotConsumerRoute);
388    }
389    reverse_request_registries()
390        .lock()
391        .unwrap_or_else(|poisoned| poisoned.into_inner())
392        .get(&id)
393        .cloned()
394        .ok_or(ReverseRequestRegistrationError::NotConsumerRoute)
395}
396
397fn release_reverse_request_registry(handle: RouteHandle) {
398    let id = handle.reverse_request_registry_id();
399    if id != 0 {
400        reverse_request_registries()
401            .lock()
402            .unwrap_or_else(|poisoned| poisoned.into_inner())
403            .remove(&id);
404    }
405}
406
407/// Capped exponential backoff used for reconnects and transient route-open retry.
408/// Each delay is jittered before it is slept: half of it is kept and the other
409/// half is random.
410#[derive(Debug, Clone, Copy, PartialEq, Eq)]
411pub struct RetryBackoff {
412    pub base: Duration,
413    pub cap: Duration,
414    /// Maximum attempts, including the first immediate attempt.
415    pub max_attempts: usize,
416}
417
418impl Default for RetryBackoff {
419    fn default() -> Self {
420        Self {
421            base: Duration::from_millis(100),
422            cap: Duration::from_secs(2),
423            max_attempts: 6,
424        }
425    }
426}
427
428impl RetryBackoff {
429    fn delay_after_attempt(self, attempt: usize) -> Duration {
430        let mut delay = self.base;
431        for _ in 1..attempt {
432            delay = (delay * 2).min(self.cap);
433        }
434        delay
435    }
436}
437
438/// Transport used for the initial connection and every reconnect attempt.
439#[derive(Debug, Clone, Copy, PartialEq, Eq)]
440enum ConsumerTransport {
441    /// Use the connection file's TCP endpoint (the default).
442    Tcp,
443    /// Use only `local_endpoint`, re-read on every connection attempt.
444    Local,
445}
446
447/// Options for [`SubcConsumer::connect`].
448#[derive(Debug, Clone, PartialEq, Eq)]
449pub struct ConsumerOptions {
450    pub handshake_timeout: Duration,
451    /// Deadline for channel-0 calls that do not take per-call options.
452    pub call_timeout: Duration,
453    pub reconnect_backoff: RetryBackoff,
454    pub restored_debounce: Duration,
455    /// Window a post-deadline Ping waits for any inbound frame before the connection is
456    /// treated as half-open. Exposed so callers can use a shorter deterministic test window.
457    pub liveness_probe_window: Duration,
458}
459
460impl Default for ConsumerOptions {
461    fn default() -> Self {
462        Self {
463            handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT,
464            call_timeout: DEFAULT_CALL_TIMEOUT,
465            reconnect_backoff: RetryBackoff::default(),
466            restored_debounce: DEFAULT_RESTORED_DEBOUNCE,
467            liveness_probe_window: DEFAULT_LIVENESS_PROBE_WINDOW,
468        }
469    }
470}
471
472/// A consumer-capability declaration was empty, contained whitespace or
473/// non-printable/non-ASCII bytes, or exceeded 64 bytes.
474#[derive(Debug, Clone, PartialEq, Eq)]
475pub struct ConsumerCapabilityError {
476    capability: String,
477}
478
479impl ConsumerCapabilityError {
480    /// The invalid declaration value.
481    pub fn capability(&self) -> &str {
482        &self.capability
483    }
484}
485
486impl fmt::Display for ConsumerCapabilityError {
487    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
488        write!(
489            f,
490            "invalid consumer capability {:?}: expected 1-64 printable ASCII bytes without whitespace",
491            self.capability
492        )
493    }
494}
495
496impl Error for ConsumerCapabilityError {}
497
498/// Options for [`SubcConsumer::close_route`].
499#[derive(Debug, Clone)]
500pub struct CloseRouteOptions {
501    /// Scope used to open the cached route. Defaults to `None`, which selects
502    /// only the unscoped entry; other scopes and epochs are never closed here.
503    /// [`SubcConsumer::close_handle`] rejects this option because the handle
504    /// already selects exactly one route.
505    pub scope: Option<ScopeSelector>,
506    /// Await in-flight unary requests on the route to settle naturally before tearing
507    /// it down. Defaults to false: close immediately, settling anything in flight as
508    /// at-most-once failures (outcome_unknown if already sent, not_sent otherwise).
509    pub drain: bool,
510    /// Upper bound on the drain wait (ignored when `drain` is false).
511    pub drain_timeout: Duration,
512    /// Override for the consumer identity used to locate the route being closed;
513    /// when absent, the supervised launch identity identifies the route, except
514    /// on connections created by [`SubcConsumer::connect_operator_app`].
515    /// On claim-bound connections, a legacy nonce identity conflicts with the
516    /// binding; `close_route` refuses it by doing nothing.
517    pub consumer_identity: Option<ConsumerIdentity>,
518    /// Reverse-request handlers plus extra capability strings added through
519    /// [`Self::with_consumer_capability`]. Together, they identify the route being closed.
520    pub reverse_requests: ReverseRequestRegistry,
521    /// The role versions the route being closed was opened with (see
522    /// [`CallOptions::role_versions`]); part of the route's identity.
523    pub role_versions: Option<BTreeMap<String, String>>,
524}
525
526impl Default for CloseRouteOptions {
527    fn default() -> Self {
528        Self {
529            scope: None,
530            drain: false,
531            drain_timeout: DEFAULT_CALL_TIMEOUT,
532            consumer_identity: None,
533            reverse_requests: ReverseRequestRegistry::new(),
534            role_versions: None,
535        }
536    }
537}
538
539impl CloseRouteOptions {
540    /// Add a provider-contract capability declaration to the route identity.
541    ///
542    /// Values are merged with the reverse-request families. For example,
543    /// `tool-result/v1` declares the tool-provider content result format; the
544    /// declaration is not verified and grants no privilege.
545    ///
546    /// Like reverse-request handlers, declarations are kept in the options'
547    /// shared reverse-request state, so options cloned before this call share
548    /// the declaration. Add declarations before cloning options for other
549    /// routes.
550    pub fn with_consumer_capability(
551        self,
552        capability: impl Into<String>,
553    ) -> Result<Self, ConsumerCapabilityError> {
554        self.reverse_requests
555            .declare_consumer_capability(capability.into())?;
556        Ok(self)
557    }
558
559    /// The extra capability strings added with `with_consumer_capability`, not
560    /// the reverse-request handler families. For example, `tool-result/v1` declares
561    /// tool-provider content-result support; declarations are unverified and
562    /// grant nothing.
563    pub fn consumer_capabilities(&self) -> Vec<String> {
564        self.reverse_requests.consumer_capabilities()
565    }
566}
567
568/// Per-call options for [`SubcConsumer::call`].
569#[derive(Debug, Clone, PartialEq, Eq)]
570pub struct CallOptions {
571    /// Scope for a managed call's cached route, including reconnect reopens.
572    /// Each owner/ref/epoch has a separate cache entry, apart from unscoped routes.
573    /// Admission, retries and terminal refusals follow [`SubcConsumer::open_route_scoped`].
574    /// A later call after a scope-related close tries a fresh route; the daemon
575    /// refuses it as `scope_ended` for an old epoch or `scope_not_live` if the
576    /// scope ref is gone. No tombstone is cached.
577    /// Defaults to `None`. Methods using an already-open handle reject this option;
578    /// select the scope when opening the route instead.
579    pub scope: Option<ScopeSelector>,
580    /// Deadline for the whole managed call, including route-open retry and the response wait.
581    pub timeout: Duration,
582    pub priority: Priority,
583    /// Admission behavior stamped into the request frame. Defaults to NORMAL.
584    pub admission_class: AdmissionClass,
585    pub route_retry: RetryBackoff,
586    /// Maximum real-time limit for retrying route.open attempts when the target is temporarily absent.
587    /// Bounds the whole route open, including the first attempt: a zero budget
588    /// means no open is attempted. For a single attempt, allow that attempt's time.
589    pub route_retry_deadline: Duration,
590    /// Explicit consumer identity for route.open; when absent, the supervised
591    /// launch identity is used, except on [`SubcConsumer::connect_operator_app`]
592    /// connections, which omit implicit identity.
593    /// A claim-bound connection rejects legacy nonce identity overrides as not
594    /// sent, rather than changing the connection's authority.
595    pub consumer_identity: Option<ConsumerIdentity>,
596    /// Reverse-request handlers plus extra capability strings added with
597    /// [`Self::with_consumer_capability`]. For example, `tool-result/v1` declares
598    /// tool-provider content-result support. These declarations are unverified
599    /// and grant nothing; both sets are merged and omitted when empty.
600    pub reverse_requests: ReverseRequestRegistry,
601    /// The versions of provider roles this consumer speaks on the route, role
602    /// name to version (`{"tool-provider": "v1"}`), sent on `route.open` and
603    /// forwarded by the daemon to the provider's bind. An unverified
604    /// declaration that grants nothing. Routes that differ only here are
605    /// separate routes, so a legacy route and a versioned one to the same
606    /// target are never shared; an empty map is the same as `None`.
607    ///
608    /// A daemon that does not advertise `route-role-versions/v1`
609    /// ([`subc_protocol::scope::CAP_ROUTE_ROLE_VERSIONS_V1`]) drops the field
610    /// without telling the provider, so check the capability before relying
611    /// on it. A malformed map (see
612    /// [`subc_protocol::session::validate_role_versions`]) is refused by the
613    /// daemon as `invalid_request` and the call fails as not sent.
614    pub role_versions: Option<BTreeMap<String, String>>,
615}
616
617impl Default for CallOptions {
618    fn default() -> Self {
619        Self {
620            scope: None,
621            timeout: DEFAULT_CALL_TIMEOUT,
622            priority: Priority::Interactive,
623            admission_class: AdmissionClass::Normal,
624            route_retry: RetryBackoff::default(),
625            route_retry_deadline: DEFAULT_ROUTE_RETRY_DEADLINE,
626            consumer_identity: None,
627            reverse_requests: ReverseRequestRegistry::new(),
628            role_versions: None,
629        }
630    }
631}
632
633impl CallOptions {
634    fn reject_scope(&self) -> Result<(), CallError> {
635        if self.scope.is_some() {
636            return Err(CallError::not_sent(
637                "CallOptions.scope is not supported here; select the scope with open_route_scoped or a managed call",
638            ));
639        }
640        Ok(())
641    }
642
643    /// Add a provider-contract capability declaration to the route.
644    ///
645    /// The list is merged with reverse-request handler families, sorted and
646    /// de-duplicated. For example, `tool-result/v1` declares the tool-provider
647    /// content result format. This remains an unverified declaration and grants
648    /// no privilege. Invalid values are rejected here, before route.open can be
649    /// sent.
650    ///
651    /// Like reverse-request handlers, declarations are kept in the options'
652    /// shared reverse-request state, so options cloned before this call share
653    /// the declaration. Add declarations before cloning options for other
654    /// routes.
655    pub fn with_consumer_capability(
656        self,
657        capability: impl Into<String>,
658    ) -> Result<Self, ConsumerCapabilityError> {
659        self.reverse_requests
660            .declare_consumer_capability(capability.into())?;
661        Ok(self)
662    }
663
664    /// The extra capability strings added with `with_consumer_capability`, not
665    /// the reverse-request handler families. For example, `tool-result/v1` declares
666    /// tool-provider content-result support; declarations are unverified and
667    /// grant nothing.
668    pub fn consumer_capabilities(&self) -> Vec<String> {
669        self.reverse_requests.consumer_capabilities()
670    }
671}
672
673/// Options for [`SubcConsumer::subscribe`].
674#[derive(Debug, Clone, PartialEq, Eq)]
675pub struct SubscribeOptions {
676    /// Scope for the cached route and its reopen attempts. Defaults to `None`.
677    /// Cache separation and daemon refusals follow [`CallOptions::scope`].
678    /// [`SubcConsumer::subscribe_route`] rejects this option because its handle
679    /// already fixes the scope. A scope-related close ends the subscription;
680    /// it is not automatically reopened under this or any other selector.
681    pub scope: Option<ScopeSelector>,
682    pub priority: Priority,
683    /// Admission behavior stamped into the subscription request. Defaults to NORMAL.
684    pub admission_class: AdmissionClass,
685    /// Maximum number of events buffered for the caller before the subscription is dropped.
686    /// The reader task never awaits a slow event consumer; if this bounded channel fills,
687    /// `closed()` resolves with [`CallError::SubscriptionBackpressure`].
688    pub event_buffer: usize,
689    pub route_retry: RetryBackoff,
690    /// Maximum real-time limit for retrying route.open attempts when the target is temporarily absent.
691    pub route_retry_deadline: Duration,
692    /// Deadline for opening the managed route and queuing the held-open request.
693    /// The subscription itself has no response timeout once the request is sent.
694    pub route_open_timeout: Duration,
695    /// Explicit consumer identity for route.open; when absent, the supervised
696    /// launch identity is used, except on [`SubcConsumer::connect_operator_app`]
697    /// connections, which omit implicit identity.
698    /// Claim-bound connections reject legacy nonce identity overrides as not sent.
699    pub consumer_identity: Option<ConsumerIdentity>,
700    /// Reverse-request handlers plus extra capability strings added with
701    /// [`Self::with_consumer_capability`]. For example, `tool-result/v1` declares
702    /// tool-provider content-result support. These declarations are unverified
703    /// and grant nothing; both sets are merged and omitted when empty.
704    pub reverse_requests: ReverseRequestRegistry,
705    /// The role versions declared on the subscription's route; see
706    /// [`CallOptions::role_versions`].
707    pub role_versions: Option<BTreeMap<String, String>>,
708}
709
710impl Default for SubscribeOptions {
711    fn default() -> Self {
712        Self {
713            scope: None,
714            priority: Priority::Interactive,
715            admission_class: AdmissionClass::Normal,
716            event_buffer: DEFAULT_SUBSCRIPTION_EVENT_BUFFER,
717            route_retry: RetryBackoff::default(),
718            route_retry_deadline: DEFAULT_ROUTE_RETRY_DEADLINE,
719            route_open_timeout: DEFAULT_CALL_TIMEOUT,
720            consumer_identity: None,
721            reverse_requests: ReverseRequestRegistry::new(),
722            role_versions: None,
723        }
724    }
725}
726
727impl SubscribeOptions {
728    /// Add a provider-contract capability declaration to the subscription route.
729    ///
730    /// This merges with reverse-request families. For example, `tool-result/v1`
731    /// declares the tool-provider content result format. The declaration is
732    /// unverified and grants no privilege; invalid values are refused before
733    /// route.open is sent.
734    pub fn with_consumer_capability(
735        self,
736        capability: impl Into<String>,
737    ) -> Result<Self, ConsumerCapabilityError> {
738        self.reverse_requests
739            .declare_consumer_capability(capability.into())?;
740        Ok(self)
741    }
742
743    /// The extra capability strings added with `with_consumer_capability`, not
744    /// the reverse-request handler families. For example, `tool-result/v1` declares
745    /// tool-provider content-result support; declarations are unverified and
746    /// grant nothing.
747    pub fn consumer_capabilities(&self) -> Vec<String> {
748        self.reverse_requests.consumer_capabilities()
749    }
750}
751
752/// Minimal connection lifecycle signal. It is useful for logging and route-cache invalidation,
753/// but callers must not use the consumer epoch as proof that a target provider is current.
754#[derive(Debug, Clone, PartialEq, Eq)]
755pub enum ConnectionState {
756    Dropped,
757    Restored { epoch: u64 },
758}
759
760/// Result of a route-scoped status or liveness poll.
761#[derive(Debug, Clone, PartialEq, Eq)]
762pub struct RoutePollResult {
763    pub handle: RouteHandle,
764    pub status: Option<String>,
765    pub live: Option<bool>,
766}
767
768/// Typed response from the daemon's channel-0 `catalog.list` operation.
769///
770/// Each module entry exposes the provider roles and tool definitions advertised by
771/// that module.
772#[derive(Debug, Clone, serde::Deserialize, PartialEq)]
773pub struct CatalogList {
774    pub generation: u64,
775    #[serde(default)]
776    pub modules: Vec<CatalogEntry>,
777    #[serde(default)]
778    pub subc_ops: Vec<String>,
779}
780
781/// Typed response from the daemon's channel-0 `supervisor.list` operation.
782///
783/// Unlike `catalog.list`, this includes configured modules that are stopped or
784/// disabled, along with their current supervisor state.
785#[derive(Debug, Clone, PartialEq)]
786pub struct SupervisorListResponse {
787    pub generation: u64,
788    pub modules: Vec<SupervisorEntry>,
789    pub daemon: Option<subc_control::DaemonResources>,
790    pub agent_commands: Option<Vec<subc_control::AgentCommandResources>>,
791}
792
793/// A provider-originated push delivered on one live route.
794#[derive(Debug, Clone, PartialEq, Eq)]
795pub struct PushEvent {
796    /// The connection-fenced route identity on which the push arrived.
797    pub handle: RouteHandle,
798    /// Opaque payload bytes sent by the provider.
799    pub body: Vec<u8>,
800}
801
802/// Disposition of one provider push at delivery time, so the two drop causes
803/// land on their own counters (issue #40): the remedies differ.
804enum DroppedPush {
805    Delivered,
806    NoReceiver,
807    ReceiverFull,
808}
809
810/// A parsed daemon-originated channel-0 control push.
811#[derive(Debug, Clone)]
812pub struct ControlPush {
813    /// The push discriminator, e.g. `route.closing` / `route.closed`.
814    pub op: String,
815    /// The full parsed body, `op` included, for op-specific fields.
816    pub body: serde_json::Value,
817}
818
819/// A route-close reason accepted from the daemon control-push wire.
820///
821/// The protocol may add reasons before this SDK is upgraded. Preserve that fact
822/// as [`Self::Unknown`] and classify it conservatively rather than refusing to
823/// deliver the enclosing control push.
824#[derive(Debug, Clone, PartialEq, Eq)]
825#[non_exhaustive]
826pub enum RouteCloseReason {
827    Reload,
828    Restart,
829    AuthorityChanged,
830    Disable,
831    Crash,
832    CapabilityDenied,
833    ScopeEnded,
834    ScopeCarrierRemoved,
835    ScopeDelegationChanged,
836    ScopeParentEnded,
837    Unknown(String),
838}
839
840/// Close reasons understood by this SDK, declared only after the daemon
841/// advertises `route-close-reasons/v1` so older daemons see unchanged requests.
842pub const ACCEPTED_CLOSE_REASONS: &[&str] = &[
843    "reload",
844    "restart",
845    "authority_changed",
846    "disable",
847    "crash",
848    "capability_denied",
849    "scope_ended",
850    "scope_carrier_removed",
851    "scope_delegation_changed",
852    "scope_parent_ended",
853];
854
855/// Why a route ended. Even a planned closure can leave a call's outcome unknown.
856#[derive(Debug, Clone, PartialEq, Eq)]
857#[non_exhaustive]
858pub enum RouteEndReason {
859    Daemon(RouteCloseReason),
860    ClosedByCaller,
861    ConnectionLost,
862    Unknown,
863}
864
865#[derive(Debug, Clone)]
866struct RouteEnd {
867    reason: RouteEndReason,
868    terminal: Option<bool>,
869}
870
871impl From<RouteEndReason> for RouteEnd {
872    fn from(reason: RouteEndReason) -> Self {
873        Self {
874            reason,
875            terminal: None,
876        }
877    }
878}
879
880/// Whether a closed route may be reopened automatically from its reason alone.
881#[derive(Debug, Clone, Copy, PartialEq, Eq)]
882pub enum RouteCloseDisposition {
883    MayReopen,
884    MustNotReopen,
885}
886
887impl RouteCloseReason {
888    /// Decode a wire reason without making a new daemon reason fatal to push delivery.
889    pub fn from_wire(reason: &str) -> Self {
890        match reason {
891            "reload" => Self::Reload,
892            "restart" => Self::Restart,
893            "authority_changed" => Self::AuthorityChanged,
894            "disable" => Self::Disable,
895            "crash" => Self::Crash,
896            "capability_denied" => Self::CapabilityDenied,
897            "scope_ended" => Self::ScopeEnded,
898            "scope_carrier_removed" => Self::ScopeCarrierRemoved,
899            "scope_delegation_changed" => Self::ScopeDelegationChanged,
900            "scope_parent_ended" => Self::ScopeParentEnded,
901            other => Self::Unknown(other.to_string()),
902        }
903    }
904
905    /// Unknown reasons take the strictest action: never reopen on their behalf.
906    pub fn disposition(&self) -> RouteCloseDisposition {
907        match self {
908            Self::Reload | Self::Restart | Self::AuthorityChanged => {
909                RouteCloseDisposition::MayReopen
910            }
911            Self::Disable
912            | Self::Crash
913            | Self::CapabilityDenied
914            | Self::ScopeEnded
915            | Self::ScopeCarrierRemoved
916            | Self::ScopeDelegationChanged
917            | Self::ScopeParentEnded
918            | Self::Unknown(_) => RouteCloseDisposition::MustNotReopen,
919        }
920    }
921}
922
923impl ControlPush {
924    /// Decode the close reason from a route lifecycle push, if this is one.
925    pub fn route_close_reason(&self) -> Option<RouteCloseReason> {
926        matches!(self.op.as_str(), "route.closing" | "route.closed")
927            .then(|| {
928                self.body
929                    .get("reason")?
930                    .as_str()
931                    .map(RouteCloseReason::from_wire)
932            })
933            .flatten()
934    }
935}
936
937/// Managed Rust consumer for subc route calls.
938pub struct SubcConsumer {
939    shared: Arc<Shared>,
940}
941
942/// The daemon's view of this connection at the time of the query.
943/// Recognition may change after revalidation or a reconnect.
944#[non_exhaustive]
945#[derive(Debug, Clone, PartialEq, Eq)]
946pub struct ConnectionFacts {
947    local: bool,
948    operator_app: Option<subc_protocol::peer::OperatorApp>,
949}
950
951impl ConnectionFacts {
952    /// Whether this connection arrived on the Unix socket or Windows named pipe.
953    pub fn local(&self) -> bool {
954        self.local
955    }
956
957    /// The operator app currently recognised for this connection. `route.bind`
958    /// sends it only to targets that advertise `operator-app/v1`.
959    pub fn operator_app(&self) -> Option<&subc_protocol::peer::OperatorApp> {
960        self.operator_app.as_ref()
961    }
962}
963
964/// Failure to ask the daemon to open an installed operator app.
965#[non_exhaustive]
966#[derive(Debug)]
967pub enum AppOpenError {
968    /// A daemon error frame. Codes are open strings so future refusals survive.
969    /// The current checks, in order, are `app_open_not_used`,
970    /// `app_open_disabled`, `app_unknown`, `app_not_installed`, and
971    /// `app_verification_failed` (see `subc_control::APP_OPEN_ERROR_CODES`).
972    /// An already-running app succeeds between the unknown and installed checks.
973    Refused { code: String, message: String },
974    /// A transport or protocol failure rather than a daemon refusal.
975    Call(CallError),
976}
977
978impl fmt::Display for AppOpenError {
979    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
980        match self {
981            Self::Refused { code, message } => write!(f, "{code}: {message}"),
982            Self::Call(err) => err.fmt(f),
983        }
984    }
985}
986
987impl Error for AppOpenError {
988    fn source(&self) -> Option<&(dyn Error + 'static)> {
989        match self {
990            Self::Call(err) => Some(err),
991            Self::Refused { .. } => None,
992        }
993    }
994}
995
996impl From<CallError> for AppOpenError {
997    fn from(err: CallError) -> Self {
998        Self::Call(err)
999    }
1000}
1001
1002/// A managed unary reply with the module's raw-body declaration preserved.
1003#[non_exhaustive]
1004#[derive(Debug, Clone, PartialEq, Eq)]
1005pub struct CallReply {
1006    body: Vec<u8>,
1007    binary: bool,
1008}
1009
1010impl CallReply {
1011    /// The body bytes, unchanged from the terminal Response frame.
1012    /// A StreamEnd without a Response has an empty body.
1013    pub fn body(&self) -> &[u8] {
1014        &self.body
1015    }
1016
1017    /// Consume the reply and return its body bytes without copying them.
1018    pub fn into_body(self) -> Vec<u8> {
1019        self.body
1020    }
1021
1022    /// Whether the terminal Response carried `FLAG_BINARY` (raw bytes, not JSON).
1023    /// A StreamEnd without a Response returns `false`.
1024    pub fn is_binary(&self) -> bool {
1025        self.binary
1026    }
1027}
1028
1029/// The first terminal outcome of a subscription.
1030#[derive(Debug, Clone, PartialEq)]
1031#[non_exhaustive]
1032pub enum SubscriptionEnd {
1033    Response(Vec<u8>),
1034    StreamEnd,
1035    Error(ErrorBody),
1036    RouteClosed {
1037        reason: RouteEndReason,
1038    },
1039    ConnectionLost,
1040    Cancelled,
1041    /// The bounded event channel filled before the caller drained it.
1042    Backpressure,
1043}
1044
1045/// A live subscription to a provider event stream.
1046///
1047/// The event receiver yields each `StreamData` payload for the held-open request's
1048/// correlation id. Await [`Subscription::closed`] to learn whether the provider ended
1049/// the stream cleanly (`Response` or `StreamEnd`) or the stream was rejected by an Error frame,
1050/// route GOODBYE, connection drop, or local backpressure. Dropping the subscription
1051/// sends a best-effort Cancel frame, the same as calling [`Subscription::unsubscribe`].
1052pub struct Subscription {
1053    events: mpsc::Receiver<Vec<u8>>,
1054    closed: SubscriptionClosed,
1055    ended: watch::Receiver<Option<SubscriptionEnd>>,
1056    cancel: SubscriptionCancel,
1057}
1058
1059impl Subscription {
1060    /// Receive event payloads emitted as `StreamData` frames for this subscription.
1061    pub fn events(&mut self) -> &mut mpsc::Receiver<Vec<u8>> {
1062        &mut self.events
1063    }
1064
1065    /// Future that resolves when the subscription reaches a terminal state.
1066    ///
1067    /// It resolves with `Ok(())` on `Response`, `StreamEnd` or local unsubscribe, and returns a
1068    /// [`CallError`] for module Error frames, route teardown, connection loss, or
1069    /// event-channel backpressure. Await it after the event receiver returns `None`
1070    /// to distinguish a clean end from an error.
1071    pub fn closed(&mut self) -> &mut SubscriptionClosed {
1072        &mut self.closed
1073    }
1074
1075    /// Wait for the terminal outcome, retaining a Response body or module Error.
1076    ///
1077    /// This is independent of the one-shot [`Self::closed`] future: either can be
1078    /// awaited first, and `ended` can be awaited again after completion. Neither
1079    /// method reads frames; both observe the same pending request's settlement.
1080    pub async fn ended(&mut self) -> SubscriptionEnd {
1081        loop {
1082            if let Some(end) = self.ended.borrow().clone() {
1083                return end;
1084            }
1085            if self.ended.changed().await.is_err() {
1086                return SubscriptionEnd::ConnectionLost;
1087            }
1088        }
1089    }
1090
1091    /// Cancel the held-open request.
1092    ///
1093    /// This sends a best-effort header-only Cancel frame for the subscription's
1094    /// `(channel, corr)` and settles [`Subscription::closed`] promptly with `Ok(())`.
1095    /// The provider may still send a terminal frame later; it is ignored because the
1096    /// local subscription is already closed.
1097    pub fn unsubscribe(&self) -> Result<(), CallError> {
1098        self.cancel.unsubscribe()
1099    }
1100}
1101
1102impl Drop for Subscription {
1103    fn drop(&mut self) {
1104        let _ = self.cancel.unsubscribe();
1105    }
1106}
1107
1108/// A held `supervisor.spawn_subscribe` request: the daemon's spawn events, in cursor
1109/// order, until the stream ends. Dropping it cancels the request.
1110pub struct SpawnSubscription {
1111    inner: Subscription,
1112    finished: bool,
1113}
1114
1115impl SpawnSubscription {
1116    /// The next event. `Ok(None)` is a clean end (the daemon ended the stream, or it was
1117    /// unsubscribed); every later call returns it too.
1118    ///
1119    /// Every event the daemon queued before a terminal error is yielded first, so the
1120    /// last event received is the cursor to resume from. A refused cursor or a dropped
1121    /// subscriber comes back as the matching [`SpawnStreamError`] variant; anything else
1122    /// that ends the stream (connection loss, local backpressure, an event that does not
1123    /// decode) is [`SpawnStreamError::Call`] or [`SpawnStreamError::Decode`].
1124    pub async fn next(&mut self) -> Result<Option<SpawnEvent>, SpawnStreamError> {
1125        if self.finished {
1126            return Ok(None);
1127        }
1128        if let Some(body) = self.inner.events().recv().await {
1129            return serde_json::from_slice::<SpawnEvent>(&body)
1130                .map(Some)
1131                .map_err(|err| {
1132                    self.finished = true;
1133                    let _ = self.inner.unsubscribe();
1134                    SpawnStreamError::Decode(err.to_string())
1135                });
1136        }
1137        // Marked finished only once the terminal has been read: a caller that drops this
1138        // future mid-await (a `select!` arm) still gets the terminal on its next call.
1139        let terminal = self.inner.closed().await;
1140        self.finished = true;
1141        match terminal {
1142            Ok(()) => Ok(None),
1143            Err(err) => Err(SpawnStreamError::from_call_error(err)),
1144        }
1145    }
1146
1147    /// Cancel the held request; the daemon releases the subscriber.
1148    pub fn unsubscribe(&self) -> Result<(), CallError> {
1149        self.inner.unsubscribe()
1150    }
1151}
1152
1153/// Why a spawn stream ended with an error, by the daemon's code where it sent one.
1154#[derive(Debug)]
1155pub enum SpawnStreamError {
1156    /// `spawn_cursor_incarnation_mismatch`: the cursor names another daemon incarnation,
1157    /// so every event since it is unknowable from this daemon.
1158    CursorIncarnationMismatch {
1159        current_daemon_incarnation: String,
1160        body: Box<ErrorBody>,
1161    },
1162    /// `spawn_cursor_too_old`: events after the cursor have left the daemon's ring.
1163    CursorTooOld {
1164        oldest_retained_cursor: SpawnCursor,
1165        body: Box<ErrorBody>,
1166    },
1167    /// `spawn_subscriber_lagged`: the daemon dropped this subscriber for falling behind,
1168    /// after delivering every event it had queued for it.
1169    SubscriberLagged {
1170        first_undelivered_cursor: SpawnCursor,
1171        body: Box<ErrorBody>,
1172    },
1173    /// Any other end: another daemon error (one of the codes above with a detail that
1174    /// does not parse included, so its code is still readable), connection loss, or
1175    /// local backpressure.
1176    Call(CallError),
1177    /// An event body that is not a `SpawnEvent`.
1178    Decode(String),
1179}
1180
1181impl SpawnStreamError {
1182    fn from_call_error(err: CallError) -> Self {
1183        let CallError::Module(body) = err else {
1184            return Self::Call(err);
1185        };
1186        let detail = |key: &str| body.detail.as_ref().and_then(|detail| detail.get(key));
1187        let cursor = |key: &str| {
1188            detail(key).and_then(|value| serde_json::from_value::<SpawnCursor>(value.clone()).ok())
1189        };
1190        match body.code.as_str() {
1191            SPAWN_CURSOR_INCARNATION_MISMATCH => {
1192                match detail("current_daemon_incarnation").and_then(|value| value.as_str()) {
1193                    Some(current) => Self::CursorIncarnationMismatch {
1194                        current_daemon_incarnation: current.to_string(),
1195                        body: Box::new(body),
1196                    },
1197                    None => Self::Call(CallError::Module(body)),
1198                }
1199            }
1200            SPAWN_CURSOR_TOO_OLD => match cursor("oldest_retained_cursor") {
1201                Some(oldest_retained_cursor) => Self::CursorTooOld {
1202                    oldest_retained_cursor,
1203                    body: Box::new(body),
1204                },
1205                None => Self::Call(CallError::Module(body)),
1206            },
1207            SPAWN_SUBSCRIBER_LAGGED => match cursor("first_undelivered_cursor") {
1208                Some(first_undelivered_cursor) => Self::SubscriberLagged {
1209                    first_undelivered_cursor,
1210                    body: Box::new(body),
1211                },
1212                None => Self::Call(CallError::Module(body)),
1213            },
1214            _ => Self::Call(CallError::Module(body)),
1215        }
1216    }
1217
1218    /// The daemon's error code, when the stream ended with one.
1219    pub fn code(&self) -> Option<&str> {
1220        match self {
1221            Self::CursorIncarnationMismatch { .. } => Some(SPAWN_CURSOR_INCARNATION_MISMATCH),
1222            Self::CursorTooOld { .. } => Some(SPAWN_CURSOR_TOO_OLD),
1223            Self::SubscriberLagged { .. } => Some(SPAWN_SUBSCRIBER_LAGGED),
1224            Self::Call(err) => err.code(),
1225            Self::Decode(_) => None,
1226        }
1227    }
1228}
1229
1230impl fmt::Display for SpawnStreamError {
1231    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1232        match self {
1233            Self::CursorIncarnationMismatch {
1234                current_daemon_incarnation,
1235                ..
1236            } => write!(
1237                f,
1238                "{SPAWN_CURSOR_INCARNATION_MISMATCH}: the daemon is incarnation \
1239                 {current_daemon_incarnation}"
1240            ),
1241            Self::CursorTooOld {
1242                oldest_retained_cursor,
1243                ..
1244            } => write!(
1245                f,
1246                "{SPAWN_CURSOR_TOO_OLD}: the oldest retained event is seq {}",
1247                oldest_retained_cursor.seq
1248            ),
1249            Self::SubscriberLagged {
1250                first_undelivered_cursor,
1251                ..
1252            } => write!(
1253                f,
1254                "{SPAWN_SUBSCRIBER_LAGGED}: the first undelivered event is seq {}",
1255                first_undelivered_cursor.seq
1256            ),
1257            Self::Call(err) => write!(f, "spawn stream ended: {err}"),
1258            Self::Decode(message) => write!(f, "spawn event did not decode: {message}"),
1259        }
1260    }
1261}
1262
1263impl Error for SpawnStreamError {}
1264
1265/// Future returned by [`Subscription::closed`].
1266pub struct SubscriptionClosed {
1267    rx: oneshot::Receiver<Result<(), CallError>>,
1268}
1269
1270impl Unpin for SubscriptionClosed {}
1271
1272impl Future for SubscriptionClosed {
1273    type Output = Result<(), CallError>;
1274
1275    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
1276        let this = self.get_mut();
1277        match Pin::new(&mut this.rx).poll(cx) {
1278            Poll::Ready(Ok(result)) => Poll::Ready(result),
1279            Poll::Ready(Err(_)) => Poll::Ready(Err(CallError::outcome_unknown(
1280                "subscription closed result channel dropped",
1281                OutcomeUnknownCause::CompletionFailed,
1282            ))),
1283            Poll::Pending => Poll::Pending,
1284        }
1285    }
1286}
1287
1288struct SubscriptionCancel {
1289    shared: Arc<Shared>,
1290    position: Arc<SubscriptionPosition>,
1291    priority: Priority,
1292    cancelled: AtomicBool,
1293}
1294
1295impl SubscriptionCancel {
1296    fn new(shared: Arc<Shared>, position: Arc<SubscriptionPosition>, priority: Priority) -> Self {
1297        Self {
1298            shared,
1299            position,
1300            priority,
1301            cancelled: AtomicBool::new(false),
1302        }
1303    }
1304
1305    fn unsubscribe(&self) -> Result<(), CallError> {
1306        let key = *self
1307            .position
1308            .key
1309            .lock()
1310            .unwrap_or_else(|err| err.into_inner());
1311        let handle = RouteHandle::new(key.channel, key.epoch, key.generation);
1312        self.shared.validate_current_handle(handle)?;
1313        if self.cancelled.swap(true, Ordering::AcqRel) {
1314            return Ok(());
1315        }
1316        self.shared
1317            .unsubscribe_subscription(&self.position, self.priority)
1318    }
1319}
1320
1321impl SubcConsumer {
1322    /// Connect through an explicit connection-file path. The initial connection
1323    /// generation uses epoch 1; each reconnect advances it.
1324    /// In a supervised process, the module's primary registration connection
1325    /// mints a fresh self claim for
1326    /// every connection, including reconnects. Mint/presentation failure is an
1327    /// error, never a direct connection: dropping the binding would change the
1328    /// caller's authority. Unsupervised processes retain the legacy behavior.
1329    pub async fn connect(
1330        connection_file: &Path,
1331        opts: ConsumerOptions,
1332    ) -> Result<Self, ConsumerError> {
1333        Self::connect_with_transport(connection_file, opts, ConsumerTransport::Tcp, true).await
1334    }
1335
1336    /// Connect only to the connection file's same-user Unix socket or Windows pipe.
1337    ///
1338    /// Each connection attempt, including reconnects, reads the current local
1339    /// endpoint and key from the same owner-checked file. A missing
1340    /// `local_endpoint` returns [`ConsumerError::NoEndpoint`]; a local connect
1341    /// failure retains its endpoint and I/O error. Neither case falls back to TCP.
1342    pub async fn connect_local(
1343        connection_file: &Path,
1344        opts: ConsumerOptions,
1345    ) -> Result<Self, ConsumerError> {
1346        Self::connect_with_transport(connection_file, opts, ConsumerTransport::Local, true).await
1347    }
1348
1349    async fn connect_with_transport(
1350        connection_file: &Path,
1351        opts: ConsumerOptions,
1352        transport: ConsumerTransport,
1353        identity_from_environment: bool,
1354    ) -> Result<Self, ConsumerError> {
1355        let opened =
1356            open_connection(connection_file, opts.handshake_timeout, transport, None).await?;
1357        let mut shared = Shared::with_transport(connection_file.to_path_buf(), opts, transport);
1358        shared.identity_from_environment = identity_from_environment;
1359        let shared = Arc::new(shared);
1360        shared.install_initial(opened)?;
1361        Ok(Self { shared })
1362    }
1363
1364    /// Discover the daemon's connection file, authenticate, and start the I/O loop.
1365    pub async fn connect_default(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1366        let discovered = connection_file::discover(None)
1367            .map_err(|source| ConsumerError::Discovery { source })?;
1368        let opened =
1369            open_connection_with_info(&discovered.path, &discovered.info, opts.handshake_timeout)
1370                .await?;
1371        let shared = Arc::new(Shared::new(discovered.path, opts));
1372        shared.install_initial(opened)?;
1373        Ok(Self { shared })
1374    }
1375
1376    /// Discover the daemon's connection file and connect only to its local endpoint.
1377    ///
1378    /// Uses [`Self::connect_local`], including its per-attempt file reads and
1379    /// refusal to fall back to TCP.
1380    pub async fn connect_default_local(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1381        let discovered = connection_file::discover(None)
1382            .map_err(|source| ConsumerError::Discovery { source })?;
1383        Self::connect_local(&discovered.path, opts).await
1384    }
1385
1386    /// Connect the desktop operator app to the installed daemon without reading
1387    /// environment variables for discovery or consumer identity.
1388    ///
1389    /// Tries [`crate::operator_app_candidates`] in order on every attempt,
1390    /// selecting the first existing owner-checked file. Uses the
1391    /// same per-attempt file reads and local-only transport as
1392    /// [`Self::connect_local`], never falling back to TCP. Requests omit implicit
1393    /// consumer identity, including after reconnect; explicit identities in
1394    /// [`CallOptions`] and [`CloseRouteOptions`] are still honoured.
1395    pub async fn connect_operator_app(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1396        Self::connect_operator_app_resolving(
1397            opts,
1398            ConsumerTransport::Local,
1399            crate::operator_app_candidates,
1400        )
1401        .await
1402    }
1403
1404    /// Open the desktop operator app's plain connection over TCP.
1405    ///
1406    /// Selects and owner-checks the installed daemon's connection file with the
1407    /// same [`crate::operator_app_candidates`] policy as
1408    /// [`Self::connect_operator_app`], then connects to the file's first TCP
1409    /// endpoint instead of its Unix socket or Windows named pipe.
1410    ///
1411    /// The daemon recognises a connection as the operator app only when it
1412    /// arrives over its Unix socket or named pipe, so this connection never
1413    /// carries the `operator_app` stamp and can't skip the daemon's
1414    /// confirmation. Its privileged requests follow the daemon's configured
1415    /// policy like any other client's. The caller decides which actions to send
1416    /// here, for example those made through assistive technology. This API
1417    /// doesn't classify input.
1418    ///
1419    /// When the daemon supports `connection.describe`,
1420    /// [`Self::describe_connection`] reports this connection with
1421    /// `local() == false`. There, `local` means the Unix socket or named pipe,
1422    /// not loopback.
1423    ///
1424    /// Like [`Self::connect_operator_app`], it reads no environment variable for
1425    /// discovery or consumer identity, including after reconnect, and never
1426    /// falls back to the local endpoint.
1427    pub async fn connect_operator_app_plain(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1428        Self::connect_operator_app_resolving(
1429            opts,
1430            ConsumerTransport::Tcp,
1431            crate::operator_app_candidates,
1432        )
1433        .await
1434    }
1435
1436    async fn connect_operator_app_resolving(
1437        opts: ConsumerOptions,
1438        transport: ConsumerTransport,
1439        resolve: impl FnOnce() -> Result<Vec<PathBuf>, crate::OperatorAppPathError>,
1440    ) -> Result<Self, ConsumerError> {
1441        let candidates = resolve().map_err(|source| ConsumerError::ConnectionFile {
1442            path: PathBuf::new(),
1443            source: ConnectionFileError::Io {
1444                op: "resolve installed daemon connection-file path",
1445                path: PathBuf::new(),
1446                source: io::Error::other(source),
1447            },
1448        })?;
1449        let path = candidates[0].clone();
1450        let opened =
1451            open_connection(&path, opts.handshake_timeout, transport, Some(&candidates)).await?;
1452        let mut shared = Shared::with_transport(path, opts, transport);
1453        shared.operator_app_candidates = Some(candidates);
1454        shared.identity_from_environment = false;
1455        let shared = Arc::new(shared);
1456        shared.install_initial(opened)?;
1457        Ok(Self { shared })
1458    }
1459
1460    /// Open or reuse an unscoped managed route and return a handle tied to its
1461    /// current connection (stale after a reconnect).
1462    /// A scope in `opts` is an argument error; use [`Self::open_route_scoped`].
1463    pub async fn open_route(
1464        &self,
1465        target: RouteTarget,
1466        identity: BindIdentity,
1467        opts: CallOptions,
1468    ) -> Result<RouteHandle, CallError> {
1469        opts.reject_scope()?;
1470        let deadline = Instant::now() + opts.timeout;
1471        let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
1472        let consumer_capabilities = route_open_consumer_capabilities(&opts);
1473        let role_versions = route_open_role_versions(opts.role_versions.as_ref());
1474        let key = RouteKey::new(
1475            &target,
1476            &identity,
1477            consumer_identity.as_ref(),
1478            consumer_capabilities.as_deref(),
1479        )
1480        .with_role_versions(role_versions.as_ref());
1481        let params = RouteOpenParams {
1482            target: &target,
1483            identity: &identity,
1484            consumer_identity: &consumer_identity,
1485            consumer_capabilities: &consumer_capabilities,
1486            role_versions: &role_versions,
1487            reverse_requests: &opts.reverse_requests,
1488            scope: None,
1489        };
1490        self.shared
1491            .ensure_route(&key, &params, &opts, deadline)
1492            .await
1493            .map(|route| route.handle)
1494    }
1495
1496    /// Open or reuse a managed route admitted under `scope`, and return a handle
1497    /// tied to its current connection (stale after a reconnect).
1498    ///
1499    /// This is how a carrier opens its onward route for a session. The daemon
1500    /// admits the open only when the opener (the consumer identity in `opts`,
1501    /// or the supervised module's own identity from the environment) is the
1502    /// scope's owner or one of its listed carriers, and it stamps the
1503    /// provider's bind with the scope. `scope.scope_epoch` must be set: the
1504    /// daemon refuses an open without it (`scope_epoch_required`).
1505    ///
1506    /// The route is cached under the whole selector (owner, ref and epoch) as
1507    /// well as the target and identities, so a route opened under one scope or
1508    /// epoch is never returned to a caller asking for another, and a scoped
1509    /// route is never returned by [`Self::open_route`] (nor an unscoped one
1510    /// here). Once the route closes, the next call with the same selector opens
1511    /// a fresh route under that selector. Close it early with
1512    /// [`Self::close_handle`].
1513    ///
1514    /// Refusals: `scope_not_synced` (the owner has not synced since the daemon
1515    /// started) and `scope_changed` (the scope changed while the bind was in
1516    /// flight) are retried within the call's deadline, like a module reload.
1517    /// `scope_ended`, `scope_not_live`, `scope_epoch_required` and
1518    /// `scope_not_carrier` end the call at once as [`CallError::NotSent`], with
1519    /// the daemon's code in [`CallError::route_open_refusal`].
1520    ///
1521    /// When the daemon later closes the route because its scope ended or the
1522    /// opener's authority under it was revoked, [`Self::control_pushes`]
1523    /// delivers `route.closed` with a `scope_*` reason. Its
1524    /// [`RouteCloseReason::disposition`] is
1525    /// [`RouteCloseDisposition::MustNotReopen`]: the session the route served is
1526    /// over, so callers should stop work for that session. The SDK does not
1527    /// cache a tombstone: a later explicit open or managed call with the same
1528    /// selector attempts a fresh open. The daemon refuses it as `scope_ended`
1529    /// if the ref is live at another epoch, or `scope_not_live` if the ref is gone.
1530    /// A selector in `opts.scope` must equal `scope`, or the call fails locally
1531    /// as an argument error before opening a route.
1532    pub async fn open_route_scoped(
1533        &self,
1534        target: RouteTarget,
1535        identity: BindIdentity,
1536        scope: ScopeSelector,
1537        opts: CallOptions,
1538    ) -> Result<RouteHandle, CallError> {
1539        if opts
1540            .scope
1541            .as_ref()
1542            .is_some_and(|selected| selected != &scope)
1543        {
1544            return Err(CallError::not_sent(
1545                "CallOptions.scope differs from open_route_scoped's explicit scope",
1546            ));
1547        }
1548        let deadline = Instant::now() + opts.timeout;
1549        let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
1550        let consumer_capabilities = route_open_consumer_capabilities(&opts);
1551        let role_versions = route_open_role_versions(opts.role_versions.as_ref());
1552        let key = RouteKey::new(
1553            &target,
1554            &identity,
1555            consumer_identity.as_ref(),
1556            consumer_capabilities.as_deref(),
1557        )
1558        .with_role_versions(role_versions.as_ref())
1559        .with_scope(Some(&scope));
1560        let params = RouteOpenParams {
1561            target: &target,
1562            identity: &identity,
1563            consumer_identity: &consumer_identity,
1564            consumer_capabilities: &consumer_capabilities,
1565            role_versions: &role_versions,
1566            reverse_requests: &opts.reverse_requests,
1567            scope: Some(&scope),
1568        };
1569        self.shared
1570            .ensure_route(&key, &params, &opts, deadline)
1571            .await
1572            .map(|route| route.handle)
1573    }
1574
1575    /// Open one admitted route without entering the managed route cache.
1576    ///
1577    /// Admitted routes are never cached or reopened after a connection drop. If
1578    /// this call fails or the route later closes, the caller must perform admission
1579    /// again and call this method with fresh facts.
1580    ///
1581    /// The route declares no reverse-request capabilities, so the provider cannot
1582    /// send it requests. Use [`Self::open_route_with_admission_facts_and_options`]
1583    /// when the provider asks the consumer questions on the route (elicitation).
1584    pub async fn open_route_with_admission_facts(
1585        &self,
1586        target: RouteTarget,
1587        identity: BindIdentity,
1588        facts: serde_json::Value,
1589    ) -> Result<RouteHandle, CallError> {
1590        let deadline = Instant::now() + self.shared.opts.call_timeout;
1591        self.open_admitted_route(
1592            target,
1593            identity,
1594            facts,
1595            &CallOptions::default(),
1596            None,
1597            deadline,
1598        )
1599        .await
1600    }
1601
1602    /// Open one admitted route, with the reverse-request handlers, capability
1603    /// declarations and timeout in `opts`.
1604    ///
1605    /// The route declares the method families of handlers registered on
1606    /// `opts.reverse_requests`, together with any provider-contract declarations
1607    /// in the extra declarations reported by `opts.consumer_capabilities()`. For example, `tool-result/v1` declares the
1608    /// tool-provider content result format. These are unverified declarations,
1609    /// not privilege grants. Requests the provider sends back (elicitation,
1610    /// sampling) reach the registered handlers, exactly as on a managed route.
1611    /// Handlers must be registered before this call: the registry is sealed
1612    /// when the route opens, because the declared method families are what the
1613    /// provider was told.
1614    ///
1615    /// Like [`Self::open_route_with_admission_facts`], the route is never cached
1616    /// or reopened; after a failure or a close the caller performs admission again.
1617    /// A non-`None` `opts.scope` is rejected as an argument error.
1618    pub async fn open_route_with_admission_facts_and_options(
1619        &self,
1620        target: RouteTarget,
1621        identity: BindIdentity,
1622        facts: serde_json::Value,
1623        opts: CallOptions,
1624    ) -> Result<RouteHandle, CallError> {
1625        opts.reject_scope()?;
1626        let deadline = Instant::now() + opts.timeout;
1627        let reverse_requests = opts.reverse_requests.clone();
1628        self.open_admitted_route(
1629            target,
1630            identity,
1631            facts,
1632            &opts,
1633            Some(reverse_requests),
1634            deadline,
1635        )
1636        .await
1637    }
1638
1639    /// One admitted route.open. With `reverse_requests`, the route is opened the
1640    /// way the managed path opens one: the capabilities are declared, the socket
1641    /// reader installs the handle before the open resolves (so a request the
1642    /// provider sends right after binding is not lost), and the handle carries
1643    /// the registry. Without it, the route has no reverse-request handling.
1644    async fn open_admitted_route(
1645        &self,
1646        target: RouteTarget,
1647        identity: BindIdentity,
1648        facts: serde_json::Value,
1649        opts: &CallOptions,
1650        reverse_requests: Option<ReverseRequestRegistry>,
1651        deadline: Instant,
1652    ) -> Result<RouteHandle, CallError> {
1653        let consumer_capabilities = route_open_consumer_capabilities(opts);
1654        let target_label = route_target_label(&target);
1655        let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
1656            busy_refusals: Some(true),
1657            target,
1658            identity,
1659            consumer_identity: self.shared.route_open_consumer_identity(opts)?,
1660            consumer_capabilities,
1661            role_versions: route_open_role_versions(opts.role_versions.as_ref()),
1662            admission_facts: Some(facts),
1663            scope: None,
1664        })
1665        .map_err(|err| CallError::not_sent(format!("failed to encode route.open: {err}")))?;
1666
1667        let terminal = self
1668            .shared
1669            .paced_route_open(body, deadline, reverse_requests.clone())
1670            .await?;
1671        let (generation, body) = match terminal {
1672            TerminalFrame::Response {
1673                generation, body, ..
1674            } => (generation, body),
1675            // The daemon refused the open. Keep its code and detail, as the
1676            // plain route.open does, so a caller can tell "retry shortly"
1677            // (module_warming) from "this configuration will never work"
1678            // (admission_facts_not_permitted).
1679            TerminalFrame::Error { body, .. } => {
1680                return Err(CallError::route_open_refused(target_label, body));
1681            }
1682            _ => {
1683                return Err(CallError::not_sent_with_cause(
1684                    "route.open returned a non-response frame",
1685                    NotSentCause::RouteOpenAbandoned,
1686                ));
1687            }
1688        };
1689        let ClientControlResponse::RouteOpen {
1690            route_channel,
1691            route_epoch,
1692            request_window,
1693            watch_window,
1694            ..
1695        } = decode_route_open_response(&body)
1696            .map_err(|err| {
1697                CallError::not_sent_with_cause(
1698                    format!("failed to decode route.open response: {err}"),
1699                    NotSentCause::RouteOpenAbandoned,
1700                )
1701            })?
1702            .0
1703        else {
1704            return Err(CallError::not_sent_with_cause(
1705                "route.open returned an unexpected control response",
1706                NotSentCause::RouteOpenAbandoned,
1707            ));
1708        };
1709        // Adopt the handle the socket reader installed for this response, which
1710        // carries the registry passed to control_call; build one only if the
1711        // reader did not (the connection moved on before the response landed).
1712        let handle = self
1713            .shared
1714            .ingress_handle(generation, route_channel, route_epoch)
1715            .unwrap_or_else(|| match reverse_requests {
1716                Some(reverse_requests) => RouteHandle::new_consumer(
1717                    route_channel,
1718                    route_epoch,
1719                    generation,
1720                    reverse_requests,
1721                ),
1722                None => RouteHandle::new(route_channel, route_epoch, generation),
1723            });
1724        let route = RouteState::windows(handle, request_window, watch_window);
1725        self.shared.install_one_shot_route(route.clone())?;
1726        Ok(route.handle)
1727    }
1728
1729    /// Describe this connection without prompting or granting any privilege.
1730    /// An older daemon's `unknown_control_op` refusal returns `None`: that daemon
1731    /// doesn't support this query, which says nothing about recognition.
1732    pub async fn describe_connection(&self) -> Result<Option<ConnectionFacts>, CallError> {
1733        let body =
1734            serde_json::to_vec(&subc_control::ConnectionDescribeRequest::new()).map_err(|err| {
1735                CallError::not_sent(format!("failed to encode connection.describe: {err}"))
1736            })?;
1737        let deadline = Instant::now() + self.shared.opts.call_timeout;
1738        match self
1739            .shared
1740            .control_call(body, deadline, false, None)
1741            .await?
1742        {
1743            TerminalFrame::Response { body, .. } => {
1744                let reply: subc_control::ConnectionDescribeReply = serde_json::from_slice(&body)
1745                    .map_err(|err| {
1746                        CallError::invalid_response(format!(
1747                            "failed to decode connection.describe: {err}"
1748                        ))
1749                    })?;
1750                Ok(Some(ConnectionFacts {
1751                    local: reply.local,
1752                    operator_app: reply.operator_app,
1753                }))
1754            }
1755            // The client-control dispatcher uses this exact code for unknown ops.
1756            TerminalFrame::Error { body, .. } if body.code == "unknown_control_op" => Ok(None),
1757            TerminalFrame::Error { body, .. } => Err(CallError::Module(body)),
1758            TerminalFrame::StreamEnd => Err(CallError::invalid_response(
1759                "connection.describe returned StreamEnd",
1760            )),
1761        }
1762    }
1763
1764    /// Ask the daemon to open a known installed app. Starting it grants nothing.
1765    /// Future success statuses and refusal codes are preserved for the caller.
1766    pub async fn app_open(&self, app: &str) -> Result<subc_control::AppOpenReply, AppOpenError> {
1767        let body = serde_json::to_vec(&subc_control::AppOpenRequest::new(app))
1768            .map_err(|err| CallError::not_sent(format!("failed to encode app.open: {err}")))?;
1769        let deadline = Instant::now() + self.shared.opts.call_timeout;
1770        match self
1771            .shared
1772            .control_call(body, deadline, false, None)
1773            .await?
1774        {
1775            TerminalFrame::Response { body, .. } => serde_json::from_slice(&body).map_err(|err| {
1776                CallError::invalid_response(format!("failed to decode app.open: {err}")).into()
1777            }),
1778            TerminalFrame::Error { body, .. } => Err(AppOpenError::Refused {
1779                code: body.code,
1780                message: body.message,
1781            }),
1782            TerminalFrame::StreamEnd => {
1783                Err(CallError::invalid_response("app.open returned StreamEnd").into())
1784            }
1785        }
1786    }
1787
1788    /// Fetch the daemon's module catalog over channel 0.
1789    /// Transport retries use the consumer's reconnect backoff and call deadline.
1790    pub async fn catalog_list(&self) -> Result<CatalogList, CallError> {
1791        let deadline = Instant::now() + self.shared.opts.call_timeout;
1792        let body = serde_json::to_vec(&serde_json::json!({
1793            "op": subc_control::ops::CATALOG_LIST,
1794        }))
1795        .map_err(|err| CallError::not_sent(format!("failed to encode catalog.list: {err}")))?;
1796
1797        let mut attempt = 0usize;
1798        loop {
1799            attempt = attempt.saturating_add(1);
1800            match self
1801                .shared
1802                .control_call(body.clone(), deadline, false, None)
1803                .await
1804            {
1805                Ok(TerminalFrame::Response { body, .. }) => {
1806                    let response =
1807                        serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1808                            CallError::invalid_response(format!(
1809                                "failed to decode catalog.list response: {err}"
1810                            ))
1811                        })?;
1812                    let ClientControlResponse::CatalogList {
1813                        generation,
1814                        modules,
1815                        subc_ops,
1816                    } = response
1817                    else {
1818                        return Err(CallError::invalid_response(
1819                            "catalog.list returned an unexpected control response",
1820                        ));
1821                    };
1822                    return Ok(CatalogList {
1823                        generation,
1824                        modules,
1825                        subc_ops,
1826                    });
1827                }
1828                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1829                Ok(TerminalFrame::StreamEnd) => {
1830                    return Err(CallError::invalid_response(
1831                        "catalog.list returned StreamEnd",
1832                    ));
1833                }
1834                Err(err)
1835                    if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1836                {
1837                    // Connection-file and discovery failures can complete without
1838                    // yielding. Pace the outer retry as well as reconnect itself,
1839                    // so repeated immediate failures cannot monopolize the executor.
1840                    let delay = self.shared.jittered(
1841                        self.shared
1842                            .opts
1843                            .reconnect_backoff
1844                            .delay_after_attempt(attempt),
1845                    );
1846                    self.shared.sleep_until_retry(deadline, delay).await?;
1847                    continue;
1848                }
1849                Err(err) => return Err(err),
1850            }
1851        }
1852    }
1853
1854    /// Fetch the supervisor's configured module list over channel 0.
1855    /// Transport retries use the consumer's reconnect backoff and call deadline.
1856    pub async fn supervisor_list(&self) -> Result<SupervisorListResponse, CallError> {
1857        let deadline = Instant::now() + self.shared.opts.call_timeout;
1858        let body = serde_json::to_vec(&ClientControlRequest::SupervisorList {}).map_err(|err| {
1859            CallError::not_sent(format!("failed to encode supervisor.list: {err}"))
1860        })?;
1861
1862        let mut attempt = 0usize;
1863        loop {
1864            attempt = attempt.saturating_add(1);
1865            match self
1866                .shared
1867                .control_call(body.clone(), deadline, false, None)
1868                .await
1869            {
1870                Ok(TerminalFrame::Response { body, .. }) => {
1871                    let response =
1872                        serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1873                            CallError::invalid_response(format!(
1874                                "failed to decode supervisor.list response: {err}"
1875                            ))
1876                        })?;
1877                    let ClientControlResponse::SupervisorList {
1878                        generation,
1879                        modules,
1880                        daemon,
1881                        agent_commands,
1882                    } = response
1883                    else {
1884                        return Err(CallError::invalid_response(
1885                            "supervisor.list returned an unexpected control response",
1886                        ));
1887                    };
1888                    return Ok(SupervisorListResponse {
1889                        generation,
1890                        modules,
1891                        daemon,
1892                        agent_commands,
1893                    });
1894                }
1895                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1896                Ok(TerminalFrame::StreamEnd) => {
1897                    return Err(CallError::invalid_response(
1898                        "supervisor.list returned StreamEnd",
1899                    ));
1900                }
1901                Err(err)
1902                    if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1903                {
1904                    // Pace immediate discovery failures so retries cannot monopolize the executor.
1905                    let delay = self.shared.jittered(
1906                        self.shared
1907                            .opts
1908                            .reconnect_backoff
1909                            .delay_after_attempt(attempt),
1910                    );
1911                    self.shared.sleep_until_retry(deadline, delay).await?;
1912                    continue;
1913                }
1914                Err(err) => return Err(err),
1915            }
1916        }
1917    }
1918
1919    /// Fetch the supervisor's atomic spawn snapshot (`supervisor.spawn_snapshot`)
1920    /// over channel 0: the live processes with their spawn generations, and the
1921    /// cursor at which they were observed.
1922    ///
1923    /// A daemon refusal comes back as [`CallError::Module`], so its code is readable
1924    /// through [`CallError::code`]. Transport failures are retried until the
1925    /// consumer's call deadline with its reconnect backoff, as for
1926    /// [`SubcConsumer::catalog_list`].
1927    pub async fn spawn_snapshot(&self) -> Result<SpawnSnapshot, CallError> {
1928        let deadline = Instant::now() + self.shared.opts.call_timeout;
1929        let body = serde_json::to_vec(&ClientControlRequest::SupervisorSpawnSnapshot {}).map_err(
1930            |err| CallError::not_sent(format!("failed to encode supervisor.spawn_snapshot: {err}")),
1931        )?;
1932
1933        let mut attempt = 0usize;
1934        loop {
1935            attempt = attempt.saturating_add(1);
1936            match self
1937                .shared
1938                .control_call(body.clone(), deadline, false, None)
1939                .await
1940            {
1941                Ok(TerminalFrame::Response { body, .. }) => {
1942                    let response =
1943                        serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1944                            CallError::invalid_response(format!(
1945                                "failed to decode supervisor.spawn_snapshot response: {err}"
1946                            ))
1947                        })?;
1948                    let ClientControlResponse::SupervisorSpawnSnapshot { snapshot } = response
1949                    else {
1950                        return Err(CallError::invalid_response(
1951                            "supervisor.spawn_snapshot returned an unexpected control response",
1952                        ));
1953                    };
1954                    return Ok(snapshot);
1955                }
1956                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1957                Ok(TerminalFrame::StreamEnd) => {
1958                    return Err(CallError::invalid_response(
1959                        "supervisor.spawn_snapshot returned StreamEnd",
1960                    ));
1961                }
1962                Err(err)
1963                    if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1964                {
1965                    let delay = self.shared.jittered(
1966                        self.shared
1967                            .opts
1968                            .reconnect_backoff
1969                            .delay_after_attempt(attempt),
1970                    );
1971                    self.shared.sleep_until_retry(deadline, delay).await?;
1972                    continue;
1973                }
1974                Err(err) => return Err(err),
1975            }
1976        }
1977    }
1978
1979    /// Query the newest-first activity ledger. The reply preserves entries, the
1980    /// continuation cursor and the head to subscribe from without a query/follow gap.
1981    /// Except for operator-app connections, identity is filled from the supervised
1982    /// launch environment, as for route.open; without one the daemon treats the
1983    /// caller as Direct. Refusals retain their code
1984    /// through [`CallError::code`]. Transport retries are paced to the call deadline.
1985    pub async fn query_activity(
1986        &self,
1987        request: ActivityQueryRequest,
1988    ) -> Result<ActivityQueryResponse, CallError> {
1989        let deadline = Instant::now() + self.shared.opts.call_timeout;
1990        let body = self.shared.activity_read_body(request)?;
1991        let mut attempt = 0usize;
1992        loop {
1993            attempt = attempt.saturating_add(1);
1994            match self
1995                .shared
1996                .control_call(body.clone(), deadline, false, None)
1997                .await
1998            {
1999                Ok(TerminalFrame::Response { body, .. }) => {
2000                    return serde_json::from_slice(&body).map_err(|err| {
2001                        CallError::invalid_response(format!(
2002                            "invalid activity.query response: {err}"
2003                        ))
2004                    });
2005                }
2006                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
2007                Ok(TerminalFrame::StreamEnd) => {
2008                    return Err(CallError::invalid_response(
2009                        "activity.query returned StreamEnd",
2010                    ));
2011                }
2012                Err(err)
2013                    if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
2014                {
2015                    let delay = self.shared.jittered(
2016                        self.shared
2017                            .opts
2018                            .reconnect_backoff
2019                            .delay_after_attempt(attempt),
2020                    );
2021                    self.shared.sleep_until_retry(deadline, delay).await?;
2022                }
2023                Err(err) => return Err(err),
2024            }
2025        }
2026    }
2027
2028    /// Follow durable activity entries after `since`, or from now if absent.
2029    /// The launch identity is filled as for [`Self::query_activity`]. Refused cursors
2030    /// and subscriber lag are terminal stream errors whose daemon code is readable
2031    /// through [`crate::ActivityStreamError::code`]. On reconnect the stream ends;
2032    /// recover with a query and subscribe from its head.
2033    pub async fn subscribe_activity(
2034        &self,
2035        since: Option<ActivityCursor>,
2036    ) -> Result<ActivitySubscription, CallError> {
2037        let deadline = Instant::now() + self.shared.opts.call_timeout;
2038        let body = self
2039            .shared
2040            .activity_read_body(ActivitySubscribeRequest { since })?;
2041        loop {
2042            self.shared.ensure_connected_for_call(deadline).await?;
2043            let permit = Arc::new(Semaphore::new(1))
2044                .acquire_owned()
2045                .await
2046                .map_err(|_| CallError::not_sent("activity subscription permit closed"))?;
2047            match self
2048                .shared
2049                .send_subscription(SubscriptionSend {
2050                    expected_handle: None,
2051                    channel: 0,
2052                    epoch: 0,
2053                    body: body.clone(),
2054                    priority: Priority::Interactive,
2055                    admission_class: AdmissionClass::Normal,
2056                    event_buffer: ACTIVITY_EVENT_BUFFER,
2057                    deadline,
2058                    permit: RoutePermit::legacy(permit),
2059                })
2060                .await
2061            {
2062                Ok(inner) => {
2063                    return Ok(ActivitySubscription {
2064                        inner,
2065                        finished: false,
2066                    })
2067                }
2068                Err(err) if err.is_not_sent() && Instant::now() < deadline => continue,
2069                Err(err) => return Err(err),
2070            }
2071        }
2072    }
2073
2074    /// Follow the supervisor's spawn event stream (`supervisor.spawn_subscribe`) over
2075    /// channel 0, from just after `since` (a cursor copied from a snapshot or an event),
2076    /// or from now when `since` is `None`.
2077    ///
2078    /// The request is held open: the returned [`SpawnSubscription`] yields each event
2079    /// until the stream ends. A cursor the daemon refuses, and the daemon dropping a
2080    /// subscriber that fell behind, arrive as the stream's terminal error (see
2081    /// [`SpawnStreamError`]). A reconnect ends the stream; the caller resubscribes from
2082    /// the last cursor it received. Sending is retried until the consumer's call
2083    /// deadline, as for [`SubcConsumer::spawn_snapshot`].
2084    pub async fn spawn_subscribe(
2085        &self,
2086        since: Option<SpawnCursor>,
2087    ) -> Result<SpawnSubscription, CallError> {
2088        let deadline = Instant::now() + self.shared.opts.call_timeout;
2089        let body = serde_json::to_vec(&ClientControlRequest::SupervisorSpawnSubscribe { since })
2090            .map_err(|err| {
2091                CallError::not_sent(format!(
2092                    "failed to encode supervisor.spawn_subscribe: {err}"
2093                ))
2094            })?;
2095        loop {
2096            self.shared.ensure_connected_for_call(deadline).await?;
2097            // Channel 0 has no route flow-control window; the subscription holds a
2098            // permit of its own so it is shaped like a route subscription.
2099            let permit = Arc::new(Semaphore::new(1))
2100                .acquire_owned()
2101                .await
2102                .map_err(|_| CallError::not_sent("spawn subscription permit closed"))?;
2103            match self
2104                .shared
2105                .send_subscription(SubscriptionSend {
2106                    expected_handle: None,
2107                    channel: 0,
2108                    epoch: 0,
2109                    body: body.clone(),
2110                    priority: Priority::Interactive,
2111                    admission_class: AdmissionClass::Normal,
2112                    event_buffer: SPAWN_EVENT_BUFFER,
2113                    deadline,
2114                    permit: RoutePermit::legacy(permit),
2115                })
2116                .await
2117            {
2118                Ok(inner) => {
2119                    return Ok(SpawnSubscription {
2120                        inner,
2121                        finished: false,
2122                    })
2123                }
2124                Err(err) if err.is_not_sent() && Instant::now() < deadline => continue,
2125                Err(err) => return Err(err),
2126            }
2127        }
2128    }
2129
2130    /// Resolve the sole catalog claimant for a capability.
2131    ///
2132    /// Resolution is deliberately based only on the static capabilities mirror in
2133    /// `catalog.list`; module ids and role names are not fallback claims. Calling
2134    /// this method expresses singular intent, so a plural catalog result is an
2135    /// explicit ambiguity rather than an arbitrary choice.
2136    pub async fn resolve_provider(&self, capability: &str) -> Result<String, CallError> {
2137        let claimants = self.resolve_providers(capability).await?;
2138        match claimants.as_slice() {
2139            [] => Err(CallError::CapabilityUnprovided {
2140                capability: capability.to_string(),
2141            }),
2142            [claimant] => Ok(claimant.clone()),
2143            _ => Err(CallError::CapabilityAmbiguous {
2144                capability: capability.to_string(),
2145                claimants,
2146            }),
2147        }
2148    }
2149
2150    /// Resolve every catalog claimant for a capability in module-id order.
2151    ///
2152    /// The identifier is validated before any channel-0 request is made, so a
2153    /// typo cannot become a network-dependent "unprovided" result.
2154    pub async fn resolve_providers(&self, capability: &str) -> Result<Vec<String>, CallError> {
2155        validate_capability_for_resolution(capability)?;
2156        let catalog = self.catalog_list().await?;
2157        Ok(capability_claimants(&catalog, capability))
2158    }
2159
2160    /// Send one request using an already-opened route handle.
2161    /// `opts.scope` must be `None`: the handle's scope was selected at route open.
2162    pub async fn request(
2163        &self,
2164        handle: &RouteHandle,
2165        body: Vec<u8>,
2166        opts: CallOptions,
2167    ) -> Result<Vec<u8>, CallError> {
2168        self.request_inner(handle, body, opts, None).await
2169    }
2170
2171    /// Like [`Self::request`], with explicit cancellation of the in-flight request.
2172    ///
2173    /// The returned future is lazy and has the same result and deadline as `request`.
2174    /// Calling [`CancelHandle::cancel`] sends at most one header-only Cancel on the
2175    /// request's route; it does not stop waiting for the provider's Response or Error.
2176    /// Dropping the handle sends nothing. Dropping the future only removes its
2177    /// pending registration, **without sending Cancel**.
2178    ///
2179    /// ```no_run
2180    /// # async fn turn(consumer: &subc_client_rs::SubcConsumer,
2181    /// # route: &subc_client_rs::RouteHandle,
2182    /// # turn_stopped: impl std::future::Future<Output = ()>) -> Result<(), subc_client_rs::CallError> {
2183    /// let (cancel, reply) = consumer.request_cancellable(
2184    ///     route, b"work".to_vec(), subc_client_rs::CallOptions::default());
2185    /// tokio::pin!(reply);
2186    /// tokio::select! {
2187    ///     result = &mut reply => { let _body = result?; }
2188    ///     () = turn_stopped => {
2189    ///         cancel.cancel().await;
2190    ///         let _body = reply.await?; // Keep any final Response body.
2191    ///     }
2192    /// }
2193    /// # Ok(())
2194    /// # }
2195    /// ```
2196    pub fn request_cancellable(
2197        &self,
2198        handle: &RouteHandle,
2199        body: Vec<u8>,
2200        opts: CallOptions,
2201    ) -> (
2202        CancelHandle,
2203        impl Future<Output = Result<Vec<u8>, CallError>> + Send + '_,
2204    ) {
2205        let consumer = self;
2206        let handle = *handle;
2207        let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2208        let future = async move {
2209            let guard = registration;
2210            consumer
2211                .request_inner(&handle, body, opts, Some(Arc::clone(&guard.state)))
2212                .await
2213        };
2214        (cancel, future)
2215    }
2216
2217    async fn request_inner(
2218        &self,
2219        handle: &RouteHandle,
2220        body: Vec<u8>,
2221        opts: CallOptions,
2222        cancel: Option<Arc<UnaryCancel>>,
2223    ) -> Result<Vec<u8>, CallError> {
2224        opts.reject_scope()?;
2225        let deadline = Instant::now() + opts.timeout;
2226        let route = self.shared.route_state(*handle)?;
2227        let permit = route.acquire(false, deadline, cancel.as_ref()).await?;
2228        let mut busy_delay = Duration::from_millis(25);
2229        loop {
2230            let result = self
2231                .shared
2232                .send_request_with_slot(
2233                    RequestSend {
2234                        binary: false,
2235                        expected_handle: Some(*handle),
2236                        channel: handle.channel,
2237                        epoch: handle.epoch,
2238                        body: body.clone(),
2239                        priority: opts.priority,
2240                        admission_class: opts.admission_class,
2241                        deadline,
2242                        retain_late_route_open: false,
2243                        route_open_reverse_requests: None,
2244                    },
2245                    cancel.clone(),
2246                    Some(Arc::clone(&permit)),
2247                )
2248                .await;
2249            match result? {
2250                TerminalFrame::Response { body, .. } => return Ok(body),
2251                TerminalFrame::StreamEnd => return Ok(Vec::new()),
2252                TerminalFrame::Error { body, flags }
2253                    if error_codes::is_route_busy_retryable(flags, &body.code, route.opted_in) =>
2254                {
2255                    if !self
2256                        .shared
2257                        .busy_backoff(deadline, busy_delay, cancel.as_ref())
2258                        .await
2259                    {
2260                        return Err(busy_error(&body));
2261                    }
2262                    busy_delay = (busy_delay * 2).min(Duration::from_secs(1));
2263                    self.shared.validate_current_handle(*handle)?;
2264                }
2265                TerminalFrame::Error { body, .. } => return Err(CallError::Module(body)),
2266            }
2267        }
2268    }
2269
2270    /// Start a held-open request using an already-opened route handle.
2271    /// `opts.scope` must be `None`: the handle's scope was selected at route open.
2272    pub async fn subscribe_route(
2273        &self,
2274        handle: &RouteHandle,
2275        body: Vec<u8>,
2276        opts: SubscribeOptions,
2277    ) -> Result<Subscription, CallError> {
2278        if opts.scope.is_some() {
2279            return Err(CallError::not_sent(
2280                "SubscribeOptions.scope is not supported on subscribe_route; select the scope when opening the route",
2281            ));
2282        }
2283        let deadline = Instant::now() + opts.route_open_timeout;
2284        let route = self.shared.route_state(*handle)?;
2285        let permit = route.acquire(true, deadline, None).await?;
2286        self.shared
2287            .send_subscription(SubscriptionSend {
2288                expected_handle: Some(*handle),
2289                channel: handle.channel,
2290                epoch: handle.epoch,
2291                body,
2292                priority: opts.priority,
2293                admission_class: opts.admission_class,
2294                event_buffer: opts.event_buffer,
2295                deadline,
2296                permit,
2297            })
2298            .await
2299    }
2300
2301    /// Poll status or liveness for exactly this route handle.
2302    /// A daemon refusal is returned as [`CallError::Module`] with its original body.
2303    pub async fn poll_route(
2304        &self,
2305        handle: &RouteHandle,
2306        kind: PollKind,
2307        timeout: Duration,
2308    ) -> Result<RoutePollResult, CallError> {
2309        let deadline = Instant::now() + timeout;
2310        let body = serde_json::to_vec(&ClientControlRequest::RoutePoll {
2311            route_channel: handle.channel,
2312            route_epoch: handle.epoch,
2313            kind,
2314        })
2315        .map_err(|err| CallError::not_sent(format!("failed to encode route.poll: {err}")))?;
2316        let terminal = self
2317            .shared
2318            .send_request(RequestSend {
2319                binary: false,
2320                expected_handle: Some(*handle),
2321                channel: 0,
2322                epoch: 0,
2323                body,
2324                priority: Priority::Interactive,
2325                admission_class: AdmissionClass::Normal,
2326                deadline,
2327                retain_late_route_open: false,
2328                route_open_reverse_requests: None,
2329            })
2330            .await?;
2331        let body = match terminal {
2332            TerminalFrame::Response { body, .. } => body,
2333            TerminalFrame::Error { body, .. } => return Err(CallError::Module(body)),
2334            TerminalFrame::StreamEnd => {
2335                return Err(CallError::invalid_response(
2336                    "route.poll returned a non-response frame",
2337                ));
2338            }
2339        };
2340        let ClientControlResponse::RoutePoll {
2341            route_channel,
2342            route_epoch,
2343            status,
2344            live,
2345        } = serde_json::from_slice(&body).map_err(|err| {
2346            CallError::invalid_response(format!("failed to decode route.poll: {err}"))
2347        })?
2348        else {
2349            return Err(CallError::invalid_response(
2350                "route.poll returned an unexpected control response",
2351            ));
2352        };
2353        if route_channel != handle.channel || route_epoch != handle.epoch {
2354            return Err(CallError::invalid_response(
2355                "route.poll response echoed a different route handle",
2356            ));
2357        }
2358        self.shared.validate_current_handle(*handle)?;
2359        Ok(RoutePollResult {
2360            handle: *handle,
2361            status,
2362            live,
2363        })
2364    }
2365
2366    /// Locally observed count of unknown or stale route frames dropped by layer-2 validation.
2367    pub fn dropped_route_frames(&self) -> u64 {
2368        self.shared.lock_inner().dropped_route_frames
2369    }
2370
2371    /// Register a receiver for provider-originated Push frames on exactly one live route.
2372    ///
2373    /// Registering another receiver for the same route replaces and closes the prior receiver.
2374    /// The receiver closes when its route closes or the connection drops. A FULL buffer drops
2375    /// the overflowing push and counts it on `pushes_dropped_receiver_full` while the
2376    /// subscription survives (issue #40; push is a lossy latency optimization and polling
2377    /// remains the correctness backstop). The reader never waits for an application that is
2378    /// not draining pushes.
2379    pub fn push_events(
2380        &self,
2381        handle: &RouteHandle,
2382    ) -> Result<mpsc::Receiver<PushEvent>, CallError> {
2383        self.shared.register_push_events(*handle)
2384    }
2385
2386    /// Number of Push frames dropped because their live route has no active receiver.
2387    ///
2388    /// Push is a one-way latency optimization, not a durable feed: the client does not
2389    /// acknowledge it, and callers retain polling as their correctness backstop. Counting
2390    /// intentional default-path drops makes an application that has not opted in observable.
2391    pub fn pushes_dropped_no_receiver(&self) -> u64 {
2392        self.shared
2393            .pushes_dropped_no_receiver
2394            .load(Ordering::Relaxed)
2395    }
2396
2397    /// Pushes dropped because the registered receiver's bounded buffer was full.
2398    /// The subscription SURVIVES a burst (the receiver stays registered); this
2399    /// counter is the trace the burst leaves. Distinct from
2400    /// `pushes_dropped_no_receiver` because the remedies differ: full means
2401    /// drain faster or register with more capacity, no-receiver means nobody
2402    /// subscribed.
2403    pub fn pushes_dropped_receiver_full(&self) -> u64 {
2404        self.shared
2405            .pushes_dropped_receiver_full
2406            .load(Ordering::Relaxed)
2407    }
2408
2409    /// Register the consumer-level receiver for daemon-originated channel-0
2410    /// control pushes (`route.closing`, `route.closed`, and any op added
2411    /// later). Advisory by contract: GOODBYE remains the load-bearing
2412    /// route-death signal and nothing in the client's own lifecycle consumes
2413    /// these. Unrecognized ops are DELIVERED (the must-ignore choice belongs
2414    /// to the consumer); unparseable bodies are dropped and counted. The
2415    /// receiver survives reconnects. Registering again replaces the prior
2416    /// receiver; a full or closed receiver drops the push and counts it
2417    /// rather than blocking the reader.
2418    pub fn control_pushes(&self, capacity: usize) -> mpsc::Receiver<ControlPush> {
2419        let (sender, receiver) = mpsc::channel(capacity.max(1));
2420        self.shared.lock_inner().control_push_receiver = Some(sender);
2421        receiver
2422    }
2423
2424    /// Always-present count of dropped channel-0 control pushes (no receiver
2425    /// registered, receiver full or closed, or unparseable body). Emitted as a
2426    /// counter rather than silence so an application that has not opted in is
2427    /// observable, mirroring `pushes_dropped_no_receiver`.
2428    pub fn control_pushes_dropped(&self) -> u64 {
2429        self.shared.control_pushes_dropped.load(Ordering::Relaxed)
2430    }
2431
2432    /// Managed unary call. Route-open failures happen before the body is sent and are
2433    /// classified as `NotSent`; module handler Error frames are the only `Module` errors.
2434    ///
2435    /// A daemon refusal that proves the module never received the request
2436    /// (`unknown_channel`, `stale_route_epoch`, or `module_reloading` while the
2437    /// module drains for a restart, reload or disable) evicts the cached route,
2438    /// reopens it and resends the request once, within the call deadline and
2439    /// only if the call has not been cancelled. Reopening during a drain waits
2440    /// out the daemon's `route.open` refusals until the replacement process
2441    /// registers, so the resend reaches the new process. A second such refusal
2442    /// is returned as `CallError::Module`.
2443    pub async fn call(
2444        &self,
2445        target: RouteTarget,
2446        identity: BindIdentity,
2447        body: Vec<u8>,
2448        opts: CallOptions,
2449    ) -> Result<Vec<u8>, CallError> {
2450        self.call_with_reply(target, identity, body, opts)
2451            .await
2452            .map(CallReply::into_body)
2453    }
2454
2455    /// Like [`Self::call`], retaining the terminal Response's binary flag as well
2456    /// as its unchanged body bytes. A StreamEnd yields an empty, non-binary reply.
2457    pub async fn call_with_reply(
2458        &self,
2459        target: RouteTarget,
2460        identity: BindIdentity,
2461        body: Vec<u8>,
2462        opts: CallOptions,
2463    ) -> Result<CallReply, CallError> {
2464        self.call_inner(target, identity, (body, false), opts, None)
2465            .await
2466    }
2467
2468    /// Managed unary call with explicit cancellation, like [`Self::request_cancellable`].
2469    ///
2470    /// Uses the same route opening, options, errors and deadline as [`Self::call`].
2471    /// Once cancellation is requested, a dead-route or `module_reloading` refusal is
2472    /// returned rather than retrying work the caller has asked to stop. Cancellation during route opening
2473    /// is remembered and sent after the Request is queued. Dropping either value
2474    /// sends no Cancel; dropping the future removes its pending registration.
2475    pub fn call_cancellable(
2476        &self,
2477        target: RouteTarget,
2478        identity: BindIdentity,
2479        body: Vec<u8>,
2480        opts: CallOptions,
2481    ) -> (
2482        CancelHandle,
2483        impl Future<Output = Result<Vec<u8>, CallError>> + Send + '_,
2484    ) {
2485        let (cancel, reply) = self.call_cancellable_with_reply(target, identity, body, opts);
2486        (cancel, async move { reply.await.map(CallReply::into_body) })
2487    }
2488
2489    /// Like [`Self::call_cancellable`], retaining the terminal Response's binary
2490    /// flag and unchanged bytes in [`CallReply`]. Cancellation, retries, deadlines
2491    /// and drop behavior are identical. A StreamEnd yields an empty, non-binary reply.
2492    pub fn call_cancellable_with_reply(
2493        &self,
2494        target: RouteTarget,
2495        identity: BindIdentity,
2496        body: Vec<u8>,
2497        opts: CallOptions,
2498    ) -> (
2499        CancelHandle,
2500        impl Future<Output = Result<CallReply, CallError>> + Send + '_,
2501    ) {
2502        let consumer = self;
2503        let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2504        let future = async move {
2505            let guard = registration;
2506            consumer
2507                .call_inner(
2508                    target,
2509                    identity,
2510                    (body, false),
2511                    opts,
2512                    Some(Arc::clone(&guard.state)),
2513                )
2514                .await
2515        };
2516        (cancel, future)
2517    }
2518
2519    /// Sends a framed JSON object head and opaque payload with `FLAG_BINARY`.
2520    /// Only use this for management operations that declare `operation_payload`.
2521    /// The caller enforces the operation's limit; the codec only bounds the head.
2522    pub async fn call_framed_with_reply(
2523        &self,
2524        target: RouteTarget,
2525        identity: BindIdentity,
2526        head: serde_json::Value,
2527        payload: Vec<u8>,
2528        opts: CallOptions,
2529    ) -> Result<CallReply, CallError> {
2530        let body = subc_protocol::framed_body::encode(&head, &payload)
2531            .map_err(|error| CallError::not_sent(format!("invalid framed request: {error}")))?;
2532        self.call_inner(target, identity, (body, true), opts, None)
2533            .await
2534    }
2535
2536    /// Cancellable companion to [`Self::call_framed_with_reply`], with the same
2537    /// lazy send, cancellation, retry and deadline behavior as other managed calls.
2538    pub fn call_framed_cancellable_with_reply(
2539        &self,
2540        target: RouteTarget,
2541        identity: BindIdentity,
2542        head: serde_json::Value,
2543        payload: Vec<u8>,
2544        opts: CallOptions,
2545    ) -> (
2546        CancelHandle,
2547        impl Future<Output = Result<CallReply, CallError>> + Send + '_,
2548    ) {
2549        let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2550        (cancel, async move {
2551            let guard = registration;
2552            let body = subc_protocol::framed_body::encode(&head, &payload)
2553                .map_err(|error| CallError::not_sent(format!("invalid framed request: {error}")))?;
2554            self.call_inner(
2555                target,
2556                identity,
2557                (body, true),
2558                opts,
2559                Some(Arc::clone(&guard.state)),
2560            )
2561            .await
2562        })
2563    }
2564
2565    async fn call_inner(
2566        &self,
2567        target: RouteTarget,
2568        identity: BindIdentity,
2569        body: (Vec<u8>, bool),
2570        opts: CallOptions,
2571        cancel: Option<Arc<UnaryCancel>>,
2572    ) -> Result<CallReply, CallError> {
2573        let mut history = CallAttemptHistory {
2574            never_forwarded: true,
2575            sent: false,
2576        };
2577        self.call_attempts(target, identity, body, opts, cancel, &mut history)
2578            .await
2579            .map_err(|err| {
2580                let err = if history.sent && matches!(err, CallError::StaleRouteHandle(_)) {
2581                    CallError::not_sent(err.to_string())
2582                } else {
2583                    err
2584                };
2585                err.with_never_forwarded(history.never_forwarded)
2586            })
2587    }
2588
2589    async fn call_attempts(
2590        &self,
2591        target: RouteTarget,
2592        identity: BindIdentity,
2593        body: (Vec<u8>, bool),
2594        opts: CallOptions,
2595        cancel: Option<Arc<UnaryCancel>>,
2596        history: &mut CallAttemptHistory,
2597    ) -> Result<CallReply, CallError> {
2598        let (body, binary) = body;
2599        let call_deadline = Instant::now() + opts.timeout;
2600        // Preserve the single resend policy even for older daemons whose
2601        // unmarked refusals cannot prove that the module never saw the request.
2602        let mut resent_after_unsent_refusal = false;
2603        let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
2604        let consumer_capabilities = route_open_consumer_capabilities(&opts);
2605        let role_versions = route_open_role_versions(opts.role_versions.as_ref());
2606        let route_key = RouteKey::new(
2607            &target,
2608            &identity,
2609            consumer_identity.as_ref(),
2610            consumer_capabilities.as_deref(),
2611        )
2612        .with_role_versions(role_versions.as_ref())
2613        .with_scope(opts.scope.as_ref());
2614
2615        let route_open = RouteOpenParams {
2616            target: &target,
2617            identity: &identity,
2618            consumer_identity: &consumer_identity,
2619            consumer_capabilities: &consumer_capabilities,
2620            role_versions: &role_versions,
2621            reverse_requests: &opts.reverse_requests,
2622            scope: opts.scope.as_ref(),
2623        };
2624
2625        let mut busy_permit: Option<Arc<RoutePermit>> = None;
2626        let mut busy_delay = Duration::from_millis(25);
2627        loop {
2628            let route = self
2629                .shared
2630                .ensure_route(&route_key, &route_open, &opts, call_deadline)
2631                .await
2632                .map_err(request_not_sent_after_route_open_failure)?;
2633            if busy_permit
2634                .as_ref()
2635                .is_some_and(|permit| !permit.belongs_to(&route))
2636            {
2637                busy_permit.take();
2638            }
2639            let permit = match busy_permit.take() {
2640                Some(permit) => permit,
2641                None => route
2642                    .acquire(false, call_deadline, cancel.as_ref())
2643                    .await
2644                    .map_err(|err| {
2645                        if matches!(err, CallError::StaleRouteHandle(_)) {
2646                            self.shared.route_not_sent_error(route.handle)
2647                        } else {
2648                            err
2649                        }
2650                    })?,
2651            };
2652
2653            if !self.shared.route_is_current(&route_key, &route) {
2654                drop(permit);
2655                self.shared
2656                    .sleep_until_retry(call_deadline, opts.route_retry.base)
2657                    .await?;
2658                continue;
2659            }
2660
2661            // Snapshot trust for the route's generation before awaiting its reply;
2662            // a reconnect must not lend a newer daemon's guarantees to an old frame.
2663            let daemon_origin_trusted = {
2664                let inner = self.shared.lock_inner();
2665                inner.generation == route.handle.connection_token() && inner.daemon_origin_trusted
2666            };
2667            let response = self
2668                .shared
2669                .send_request_with_slot(
2670                    RequestSend {
2671                        expected_handle: Some(route.handle),
2672                        channel: route.handle.channel,
2673                        epoch: route.handle.epoch,
2674                        body: body.clone(),
2675                        binary,
2676                        priority: opts.priority,
2677                        admission_class: opts.admission_class,
2678                        deadline: call_deadline,
2679                        retain_late_route_open: false,
2680                        route_open_reverse_requests: None,
2681                    },
2682                    cancel.clone(),
2683                    Some(Arc::clone(&permit)),
2684                )
2685                .await;
2686
2687            history.sent |= response.is_ok();
2688            let proven_undelivered = match &response {
2689                Ok(TerminalFrame::Error { body, flags }) => {
2690                    is_refusal_on_route(daemon_origin_trusted, *flags, &body.code, route.opted_in)
2691                }
2692                Err(err) => {
2693                    err.never_forwarded() == Some(true)
2694                        || matches!(err, CallError::StaleRouteHandle(_))
2695                }
2696                _ => false,
2697            };
2698            history.never_forwarded &= proven_undelivered;
2699
2700            match response {
2701                Ok(TerminalFrame::Response { body, flags, .. }) => {
2702                    return Ok(CallReply {
2703                        body,
2704                        binary: flags.is_binary(),
2705                    });
2706                }
2707                Ok(TerminalFrame::StreamEnd) => {
2708                    return Ok(CallReply {
2709                        body: Vec::new(),
2710                        binary: false,
2711                    });
2712                }
2713                Ok(TerminalFrame::Error { body, flags })
2714                    if error_codes::is_route_busy_retryable(flags, &body.code, route.opted_in) =>
2715                {
2716                    if !self
2717                        .shared
2718                        .busy_backoff(call_deadline, busy_delay, cancel.as_ref())
2719                        .await
2720                    {
2721                        return Err(busy_error(&body));
2722                    }
2723                    busy_delay = (busy_delay * 2).min(Duration::from_secs(1));
2724                    busy_permit = Some(permit);
2725                    continue;
2726                }
2727                // Route-dead and drain refusals share one eviction/resend budget.
2728                // Only a trusted daemon-origin flag proves non-delivery; the retry
2729                // policy itself stays compatible with older daemons.
2730                Ok(TerminalFrame::Error { body, flags })
2731                    if (error_codes::is_established_route_dead(flags, &body.code)
2732                        || is_data_plane_drain_refusal(&body.code))
2733                        && !resent_after_unsent_refusal
2734                        && !cancel.as_ref().is_some_and(|cancel| cancel.requested())
2735                        && Instant::now() < call_deadline =>
2736                {
2737                    resent_after_unsent_refusal = true;
2738                    self.shared.invalidate_route(&route_key, Some(route.handle));
2739                    continue;
2740                }
2741                Ok(TerminalFrame::Error { body, flags })
2742                    if is_daemon_refusal_before_forward(
2743                        daemon_origin_trusted,
2744                        flags,
2745                        &body.code,
2746                    ) =>
2747                {
2748                    return Err(CallError::not_sent_with_cause(
2749                        format!(
2750                            "daemon refused before forwarding: {} ({})",
2751                            body.code, body.message
2752                        ),
2753                        NotSentCause::DaemonRefusedBeforeForward { code: body.code },
2754                    ));
2755                }
2756                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
2757                Err(err)
2758                    if err.is_not_sent()
2759                        && Instant::now() < call_deadline
2760                        && !cancel.as_ref().is_some_and(|cancel| cancel.requested()) =>
2761                {
2762                    self.shared.invalidate_route(&route_key, Some(route.handle));
2763                    self.shared.ensure_connected_for_call(call_deadline).await?;
2764                    continue;
2765                }
2766                Err(err)
2767                    if err.outcome_cause() == Some(OutcomeUnknownCause::Deadline)
2768                        && !cancel.as_ref().is_some_and(|cancel| cancel.requested()) =>
2769                {
2770                    self.shared.invalidate_route_with_deadline(
2771                        &route_key,
2772                        Some(route.handle),
2773                        true,
2774                    );
2775                    return Err(err);
2776                }
2777                Err(err) => return Err(err),
2778            }
2779        }
2780    }
2781
2782    /// Open a held-open subscription on a managed route.
2783    ///
2784    /// This opens or reuses the same `(target, identity, consumer_identity, consumer_capabilities, role_versions, scope)` route as
2785    /// [`SubcConsumer::call`], sends one Request that the provider keeps open, and
2786    /// returns a [`Subscription`] whose event receiver yields each matching
2787    /// `StreamData` payload. The request holds one route flow-control permit until
2788    /// `StreamEnd`, an Error frame, route teardown or connection loss. On negotiated
2789    /// routes, local backpressure and unsubscribe keep credit until a wire terminal.
2790    /// Reconnects reject the
2791    /// subscription; callers that need durable replay should resubscribe with their
2792    /// own cursor after observing the failure.
2793    pub async fn subscribe(
2794        &self,
2795        target: RouteTarget,
2796        identity: BindIdentity,
2797        body: Vec<u8>,
2798        opts: SubscribeOptions,
2799    ) -> Result<Subscription, CallError> {
2800        let open_deadline = Instant::now() + opts.route_open_timeout;
2801        let route_opts = CallOptions {
2802            scope: opts.scope.clone(),
2803            timeout: opts.route_open_timeout,
2804            priority: opts.priority,
2805            admission_class: opts.admission_class,
2806            route_retry: opts.route_retry,
2807            route_retry_deadline: opts.route_retry_deadline,
2808            consumer_identity: opts.consumer_identity.clone(),
2809            reverse_requests: opts.reverse_requests.clone(),
2810            role_versions: opts.role_versions.clone(),
2811        };
2812        let consumer_identity = self.shared.route_open_consumer_identity(&route_opts)?;
2813        let consumer_capabilities = route_open_consumer_capabilities(&route_opts);
2814        let role_versions = route_open_role_versions(route_opts.role_versions.as_ref());
2815        let route_key = RouteKey::new(
2816            &target,
2817            &identity,
2818            consumer_identity.as_ref(),
2819            consumer_capabilities.as_deref(),
2820        )
2821        .with_role_versions(role_versions.as_ref())
2822        .with_scope(opts.scope.as_ref());
2823
2824        let route_open = RouteOpenParams {
2825            target: &target,
2826            identity: &identity,
2827            consumer_identity: &consumer_identity,
2828            consumer_capabilities: &consumer_capabilities,
2829            role_versions: &role_versions,
2830            reverse_requests: &opts.reverse_requests,
2831            scope: opts.scope.as_ref(),
2832        };
2833
2834        loop {
2835            let route = self
2836                .shared
2837                .ensure_route(&route_key, &route_open, &route_opts, open_deadline)
2838                .await
2839                .map_err(request_not_sent_after_route_open_failure)?;
2840            let permit = route
2841                .acquire(true, open_deadline, None)
2842                .await
2843                .map_err(|err| {
2844                    if matches!(err, CallError::StaleRouteHandle(_)) {
2845                        self.shared.route_not_sent_error(route.handle)
2846                    } else {
2847                        err
2848                    }
2849                })?;
2850
2851            if !self.shared.route_is_current(&route_key, &route) {
2852                drop(permit);
2853                self.shared
2854                    .sleep_until_retry(open_deadline, opts.route_retry.base)
2855                    .await?;
2856                continue;
2857            }
2858
2859            match self
2860                .shared
2861                .send_subscription(SubscriptionSend {
2862                    expected_handle: Some(route.handle),
2863                    channel: route.handle.channel,
2864                    epoch: route.handle.epoch,
2865                    body: body.clone(),
2866                    priority: opts.priority,
2867                    admission_class: opts.admission_class,
2868                    event_buffer: opts.event_buffer,
2869                    deadline: open_deadline,
2870                    permit,
2871                })
2872                .await
2873            {
2874                Ok(subscription) => return Ok(subscription),
2875                Err(err) if err.is_not_sent() && Instant::now() < open_deadline => {
2876                    self.shared.invalidate_route(&route_key, Some(route.handle));
2877                    self.shared.ensure_connected_for_call(open_deadline).await?;
2878                    continue;
2879                }
2880                Err(err) => return Err(err),
2881            }
2882        }
2883    }
2884
2885    /// Tear down ONE route, keyed by its route-open identity tuple — the parity of the TS
2886    /// client's `closeRoute`. For a long-lived consumer that opens unbounded distinct
2887    /// routes (one per session), this releases a route on session-end without dropping
2888    /// the whole consumer: it drops the cached route, settles in-flight requests on it
2889    /// at-most-once (OutcomeUnknown if already sent, NotSent otherwise), and queues a
2890    /// route GOODBYE so the daemon releases it and notifies the module. When closing
2891    /// a cached route returns, its GOODBYE is queued ahead of any frame sent later on
2892    /// this connection, so the caller may release its per-route budget. If the
2893    /// connection died instead, the daemon releases all its routes on disconnect.
2894    /// `opts.scope` selects only that scope's cache entry; `None` selects only
2895    /// the unscoped entry. Calls and subscriptions use the same route cache.
2896    ///
2897    /// Idempotent: a no-op if the route was never opened or is already closed (callers
2898    /// over-call on session-end). NOT a permanent tombstone — a later `call()` for the
2899    /// same key opens a fresh route. The close-beats-reopen guard ensures a close that
2900    /// races an in-flight route.open WINS (the opened channel is GOODBYE'd, not cached).
2901    ///
2902    /// # Cancel safety
2903    /// Once the cached route is removed, dropping this future abandons any drain
2904    /// wait but still settles pending requests and queues its GOODBYE in the
2905    /// background. The handle stays installed until GOODBYE is queued, unless the
2906    /// connection dies. Cancellation does not queue a second GOODBYE if the close
2907    /// already completed.
2908    pub async fn close_route(
2909        &self,
2910        target: RouteTarget,
2911        identity: BindIdentity,
2912        opts: CloseRouteOptions,
2913    ) {
2914        let Ok(consumer_identity) = self.shared.close_route_consumer_identity(&opts) else {
2915            return;
2916        };
2917        let consumer_capabilities = close_route_consumer_capabilities(&opts);
2918        let key = RouteKey::new(
2919            &target,
2920            &identity,
2921            consumer_identity.as_ref(),
2922            consumer_capabilities.as_deref(),
2923        )
2924        .with_role_versions(route_open_role_versions(opts.role_versions.as_ref()).as_ref())
2925        .with_scope(opts.scope.as_ref());
2926        self.shared.close_route(&key, &opts).await;
2927    }
2928
2929    /// Close exactly this route handle. A stale connection token fails locally and emits no frame.
2930    /// `opts.scope` must be `None`: the handle already selects exactly one route.
2931    ///
2932    /// # Cancel safety
2933    /// After the handle is validated and its route removed, dropping this future
2934    /// abandons any drain wait but still settles pending requests and queues its
2935    /// GOODBYE in the background. The handle is uninstalled after queueing, or when
2936    /// the connection dies; a completed close never queues a second GOODBYE on drop.
2937    pub async fn close_handle(
2938        &self,
2939        handle: &RouteHandle,
2940        opts: CloseRouteOptions,
2941    ) -> Result<(), CallError> {
2942        if opts.scope.is_some() {
2943            return Err(CallError::not_sent(
2944                "CloseRouteOptions.scope is not supported on close_handle; the handle already selects the route",
2945            ));
2946        }
2947        self.shared.close_handle(*handle, &opts).await
2948    }
2949
2950    /// Current transport epoch: 1 on initial connect, then +1 per successful reconnect.
2951    pub fn current_epoch(&self) -> u64 {
2952        self.shared.lock_inner().epoch
2953    }
2954
2955    pub(crate) fn pool_reusable(&self) -> bool {
2956        !self.shared.close_token.is_cancelled()
2957    }
2958
2959    /// Register a connection-state callback. Callbacks are best-effort observability hooks.
2960    pub fn on_connection_state(&self, cb: impl Fn(ConnectionState) + Send + 'static) {
2961        self.shared
2962            .lock_inner()
2963            .callbacks
2964            .push(Arc::new(Mutex::new(Box::new(cb))));
2965    }
2966
2967    /// Close the consumer and settle every pending caller.
2968    pub async fn close(&self) {
2969        self.shared.close_sync("consumer closed");
2970        tokio::task::yield_now().await;
2971    }
2972}
2973
2974impl Drop for SubcConsumer {
2975    fn drop(&mut self) {
2976        self.shared.close_sync("consumer dropped");
2977    }
2978}
2979
2980/// Error returned by [`SubcConsumer`]'s TCP and local connection constructors.
2981#[derive(Debug)]
2982pub enum ConsumerError {
2983    Discovery {
2984        source: connection_file::DiscoveryError,
2985    },
2986    ConnectionFile {
2987        path: PathBuf,
2988        source: ConnectionFileError,
2989    },
2990    /// No endpoint for the requested transport. [`SubcConsumer::connect_local`]
2991    /// returns this when the connection file has no `local_endpoint`.
2992    NoEndpoint {
2993        path: PathBuf,
2994    },
2995    Connect {
2996        path: PathBuf,
2997        endpoint: String,
2998        source: io::Error,
2999    },
3000    Auth {
3001        path: PathBuf,
3002        endpoint: String,
3003        source: AuthError,
3004    },
3005    Closed,
3006}
3007
3008impl ConsumerError {
3009    pub(crate) fn claim(error: crate::ClaimError) -> Self {
3010        Self::Connect {
3011            path: PathBuf::new(),
3012            endpoint: "claim binding".into(),
3013            source: io::Error::other(error),
3014        }
3015    }
3016}
3017
3018impl fmt::Display for ConsumerError {
3019    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3020        match self {
3021            Self::Discovery { source } => source.fmt(f),
3022            Self::ConnectionFile { path, source } => write!(
3023                f,
3024                "failed to read subc connection file '{}': {source}",
3025                path.display()
3026            ),
3027            Self::NoEndpoint { path } => {
3028                write!(
3029                    f,
3030                    "subc connection file '{}' has no endpoint for the requested transport",
3031                    path.display()
3032                )
3033            }
3034            Self::Connect {
3035                path,
3036                endpoint,
3037                source,
3038            } => write!(
3039                f,
3040                "failed to connect to subc endpoint {endpoint} from '{}': {source}",
3041                path.display()
3042            ),
3043            Self::Auth {
3044                path,
3045                endpoint,
3046                source,
3047            } => write!(
3048                f,
3049                "failed to authenticate to subc endpoint {endpoint} from '{}': {source}",
3050                path.display()
3051            ),
3052            Self::Closed => write!(f, "consumer closed"),
3053        }
3054    }
3055}
3056
3057impl Error for ConsumerError {
3058    fn source(&self) -> Option<&(dyn Error + 'static)> {
3059        match self {
3060            Self::Discovery { source } => Some(source),
3061            Self::ConnectionFile { source, .. } => Some(source),
3062            Self::Connect { source, .. } => Some(source),
3063            Self::Auth { source, .. } => Some(source),
3064            Self::NoEndpoint { .. } | Self::Closed => None,
3065        }
3066    }
3067}
3068
3069/// Why a sent request has no observed terminal response.
3070#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3071#[non_exhaustive]
3072pub enum OutcomeUnknownCause {
3073    /// The reply deadline elapsed after the request was sent.
3074    Deadline,
3075    /// The connection's writer closed or failed after send.
3076    WriterClosed,
3077    /// The caller closed the consumer while a request was pending.
3078    ConsumerClosed,
3079    /// The daemon connection failed or dropped.
3080    ConnectionFailed,
3081    /// The route ended; [`CallError::close_reason`] gives its reason.
3082    RouteEnded,
3083    /// An internal completion channel dropped or an unexpected completion arrived.
3084    CompletionFailed,
3085}
3086
3087#[derive(Debug, Clone)]
3088struct OutcomeUnknownSource {
3089    message: String,
3090    cause: OutcomeUnknownCause,
3091    route_reason: Option<RouteEnd>,
3092}
3093
3094impl fmt::Display for OutcomeUnknownSource {
3095    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3096        f.write_str(&self.message)
3097    }
3098}
3099impl Error for OutcomeUnknownSource {}
3100
3101/// Why an attempt was classified as [`CallError::NotSent`]. For resend safety
3102/// across all attempts, also check [`CallError::never_forwarded`].
3103#[derive(Debug, Clone, PartialEq, Eq)]
3104#[non_exhaustive]
3105pub enum NotSentCause {
3106    /// The daemon or module refused route.open before the data request.
3107    RouteOpenRefused { code: String },
3108    /// Route opening ended without a usable answer, including cancellation.
3109    RouteOpenAbandoned,
3110    /// Local validation, connection state or flow control prevented queueing.
3111    BeforeQueue,
3112    /// The deadline elapsed waiting for the writer's cancel-safe queue send.
3113    WriterCapacity,
3114    /// The writer did not accept the request for transmission.
3115    WriterRejected,
3116    /// A control response could not be decoded or had an unexpected shape.
3117    InvalidResponse,
3118    /// No longer produced: since 0.34.2 a dropped completion channel, which
3119    /// can't prove non-delivery, is reported as [`CallError::OutcomeUnknown`]
3120    /// with [`OutcomeUnknownCause::CompletionFailed`]. Kept so existing
3121    /// matches still compile.
3122    CompletionFailed,
3123    /// A daemon-marked data-plane refusal proved this attempt was not forwarded.
3124    DaemonRefusedBeforeForward { code: String },
3125}
3126
3127#[derive(Debug, Clone)]
3128struct NotSentSource {
3129    message: String,
3130    cause: NotSentCause,
3131    never_forwarded: bool,
3132    route_reason: Option<RouteEnd>,
3133    refusal: Option<Box<RouteOpenRefused>>,
3134}
3135
3136impl fmt::Display for NotSentSource {
3137    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3138        f.write_str(&self.message)
3139    }
3140}
3141impl Error for NotSentSource {}
3142
3143/// Managed call or subscription failure.
3144#[derive(Debug)]
3145pub enum CallError {
3146    /// Local compatibility policy refusal: the version retained from the
3147    /// connection file for this connection is not an exact numeric
3148    /// `major.minor.patch` version at least 0.39.0. Unrecognized strings,
3149    /// including prereleases and build suffixes, are refused too. This
3150    /// route-open attempt was refused before being queued for writing.
3151    /// The handshake authenticates the daemon ID, not this version metadata.
3152    DaemonTooOld { daemon_ver: String },
3153    /// A pre-send failure, proven non-delivery, or unusable reply or internal completion.
3154    /// Check [`CallError::never_forwarded`] before treating the whole call as safe to resend.
3155    NotSent(Box<dyn Error + Send + Sync>),
3156    /// The request body was accepted by the writer path, but no terminal response was observed.
3157    OutcomeUnknown(Box<dyn Error + Send + Sync>),
3158    /// The target module handler returned an Error frame. Application-level rejections
3159    /// are returned as ordinary successful response bytes and do not produce this variant.
3160    Module(ErrorBody),
3161    /// A subscription event receiver stopped keeping up with its bounded channel.
3162    ///
3163    /// The reader task must never await a slow consumer while it is dispatching frames
3164    /// for the whole connection, so a full event channel terminates only that subscription.
3165    SubscriptionBackpressure(Box<dyn Error + Send + Sync>),
3166    /// The handle belongs to an earlier connection and no frame was emitted.
3167    StaleRouteHandle(RouteHandle),
3168    /// No registered catalog entry claims the requested capability.
3169    CapabilityUnprovided { capability: String },
3170    /// More than one registered catalog entry claims a singularly requested capability.
3171    CapabilityAmbiguous {
3172        capability: String,
3173        claimants: Vec<String>,
3174    },
3175    /// The resolver rejected a malformed capability identifier before querying the daemon.
3176    InvalidCapabilityIdentifier { capability: String },
3177}
3178
3179impl CallError {
3180    /// A typed terminal scope bind-proof refusal, if the daemon returned one.
3181    pub fn scope_bind_proof_refusal(&self) -> Option<ScopeBindProofRefusal> {
3182        match self.route_open_refusal()?.code.as_str() {
3183            error_codes::SCOPE_BIND_PROOF_REQUIRED => Some(ScopeBindProofRefusal::Required),
3184            error_codes::SCOPE_BIND_PROOF_MISMATCH => Some(ScopeBindProofRefusal::Mismatch),
3185            _ => None,
3186        }
3187    }
3188
3189    /// Why the route ended. The error remains `NotSent` or `OutcomeUnknown`:
3190    /// this reason never makes a sent call safe to resend.
3191    pub fn close_reason(&self) -> Option<&RouteEndReason> {
3192        self.route_end().map(|end| &end.reason)
3193    }
3194
3195    fn route_end(&self) -> Option<&RouteEnd> {
3196        match self {
3197            Self::NotSent(source) => source
3198                .downcast_ref::<NotSentSource>()?
3199                .route_reason
3200                .as_ref(),
3201            Self::OutcomeUnknown(source) => source
3202                .downcast_ref::<OutcomeUnknownSource>()?
3203                .route_reason
3204                .as_ref(),
3205            _ => None,
3206        }
3207    }
3208
3209    /// The daemon's recovery verdict from `route.closed`, if it carried one.
3210    /// `Some(true)` means the daemon will leave the module down until an operator
3211    /// acts. `None` means unknown: older daemons, client-side ends and non-route
3212    /// errors have no verdict. This flag does not change resend safety or the
3213    /// close reason's reopen disposition.
3214    pub fn terminal(&self) -> Option<bool> {
3215        self.route_end()?.terminal
3216    }
3217
3218    /// Why the outcome is unknown, without parsing the error's message.
3219    /// Errors constructed outside this crate with an untyped source return `None`.
3220    pub fn outcome_cause(&self) -> Option<OutcomeUnknownCause> {
3221        match self {
3222            Self::OutcomeUnknown(source) => source
3223                .downcast_ref::<OutcomeUnknownSource>()
3224                .map(|source| source.cause),
3225            _ => None,
3226        }
3227    }
3228
3229    /// Why the final attempt was classified as `NotSent`, without parsing its message.
3230    /// Returns `None` for other variants and externally constructed untyped errors.
3231    pub fn not_sent_cause(&self) -> Option<NotSentCause> {
3232        match self {
3233            Self::NotSent(source) => source
3234                .downcast_ref::<NotSentSource>()
3235                .map(|source| source.cause.clone()),
3236            _ => None,
3237        }
3238    }
3239
3240    /// Whether no attempt of this call may have reached the module.
3241    ///
3242    /// `Some(false)` means this or an earlier attempt may have been forwarded.
3243    /// For data-plane errors, only daemon-marked refusals prove non-delivery;
3244    /// unmarked replies remain conservative on older daemons. Managed calls
3245    /// include every attempt. Returns `None` except for crate-built `NotSent` errors.
3246    pub fn never_forwarded(&self) -> Option<bool> {
3247        match self {
3248            Self::NotSent(source) => source
3249                .downcast_ref::<NotSentSource>()
3250                .map(|source| source.never_forwarded),
3251            _ => None,
3252        }
3253    }
3254
3255    /// Return the stable machine-readable code for typed errors.
3256    pub fn code(&self) -> Option<&str> {
3257        match self {
3258            Self::Module(body) => Some(&body.code),
3259            Self::DaemonTooOld { .. } => Some("daemon_too_old"),
3260            Self::CapabilityUnprovided { .. } => Some("capability_unprovided"),
3261            Self::CapabilityAmbiguous { .. } => Some("capability_ambiguous"),
3262            Self::InvalidCapabilityIdentifier { .. } => Some("invalid_capability_identifier"),
3263            Self::NotSent(source) => match &source.downcast_ref::<NotSentSource>()?.cause {
3264                NotSentCause::DaemonRefusedBeforeForward { code }
3265                    if code == error_codes::ROUTE_BUSY =>
3266                {
3267                    Some(code)
3268                }
3269                _ => None,
3270            },
3271            Self::OutcomeUnknown(_)
3272            | Self::SubscriptionBackpressure(_)
3273            | Self::StaleRouteHandle(_) => None,
3274        }
3275    }
3276
3277    fn not_sent(reason: impl Into<String>) -> Self {
3278        Self::not_sent_with_cause(reason, NotSentCause::BeforeQueue)
3279    }
3280
3281    fn not_sent_with_cause(reason: impl Into<String>, cause: NotSentCause) -> Self {
3282        Self::NotSent(Box::new(NotSentSource {
3283            message: reason.into(),
3284            cause,
3285            never_forwarded: true,
3286            route_reason: None,
3287            refusal: None,
3288        }))
3289    }
3290
3291    fn with_never_forwarded(mut self, never_forwarded: bool) -> Self {
3292        if let Self::NotSent(source) = &mut self {
3293            if let Some(source) = source.downcast_mut::<NotSentSource>() {
3294                source.never_forwarded &= never_forwarded;
3295            }
3296        }
3297        self
3298    }
3299
3300    fn invalid_response(reason: impl Into<String>) -> Self {
3301        Self::not_sent_with_cause(reason, NotSentCause::InvalidResponse).with_never_forwarded(false)
3302    }
3303
3304    fn outcome_unknown(reason: impl Into<String>, cause: OutcomeUnknownCause) -> Self {
3305        Self::outcome_unknown_source(OutcomeUnknownSource {
3306            message: reason.into(),
3307            cause,
3308            route_reason: None,
3309        })
3310    }
3311
3312    fn outcome_unknown_source(source: OutcomeUnknownSource) -> Self {
3313        Self::OutcomeUnknown(Box::new(source))
3314    }
3315
3316    fn is_not_sent(&self) -> bool {
3317        matches!(self, Self::NotSent(_))
3318    }
3319
3320    /// The daemon's refusal body when this failure is a route.open the daemon
3321    /// refused, with its `code`, `message` and machine-readable `detail`
3322    /// intact, for example `module_warming` with
3323    /// `detail.reason = "required_capability_unprovided"`.
3324    ///
3325    /// When retryable refusals ran out the route-retry deadline, this is the
3326    /// most informative refusal seen during the retries, so a caller can tell
3327    /// "the module was reloading" from "the connection failed". Refusals rank:
3328    /// `module_reloading` / `module_warming`, then `delegation_not_registered`,
3329    /// then admission pressure (too many binds in flight), then anything else;
3330    /// at equal rank the later one wins. The failure is still `NotSent`: a
3331    /// refused route.open never delivered the request.
3332    pub fn route_open_refusal(&self) -> Option<&ErrorBody> {
3333        match self {
3334            Self::NotSent(err) => err
3335                .downcast_ref::<NotSentSource>()
3336                .and_then(|source| source.refusal.as_ref())
3337                .map(|refused| &refused.body),
3338            _ => None,
3339        }
3340    }
3341
3342    fn subscription_backpressure(reason: impl Into<String>) -> Self {
3343        Self::SubscriptionBackpressure(Box::new(SimpleError(reason.into())))
3344    }
3345}
3346
3347impl fmt::Display for CallError {
3348    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3349        match self {
3350            Self::DaemonTooOld { daemon_ver } => write!(
3351                f,
3352                "daemon_too_old: route.open requires daemon 0.39.0 or newer (connected version: {daemon_ver})"
3353            ),
3354            Self::NotSent(err) => write!(f, "request not sent: {err}"),
3355            Self::OutcomeUnknown(err) => write!(f, "request outcome unknown: {err}"),
3356            Self::Module(body) => write!(f, "module error {}: {}", body.code, body.message),
3357            Self::SubscriptionBackpressure(err) => {
3358                write!(f, "subscription event channel backpressure: {err}")
3359            }
3360            Self::StaleRouteHandle(handle) => write!(f, "stale route handle: {handle:?}"),
3361            Self::CapabilityUnprovided { capability } => {
3362                write!(
3363                    f,
3364                    "capability_unprovided: no catalog claimant for {capability}"
3365                )
3366            }
3367            Self::CapabilityAmbiguous {
3368                capability,
3369                claimants,
3370            } => write!(
3371                f,
3372                "capability_ambiguous: multiple catalog claimants for {capability}: {claimants:?}"
3373            ),
3374            Self::InvalidCapabilityIdentifier { capability } => write!(
3375                f,
3376                "invalid_capability_identifier: malformed capability identifier {capability:?}"
3377            ),
3378        }
3379    }
3380}
3381
3382impl Error for CallError {
3383    fn source(&self) -> Option<&(dyn Error + 'static)> {
3384        match self {
3385            Self::NotSent(err)
3386            | Self::OutcomeUnknown(err)
3387            | Self::SubscriptionBackpressure(err) => Some(err.as_ref()),
3388            Self::Module(_)
3389            | Self::DaemonTooOld { .. }
3390            | Self::StaleRouteHandle(_)
3391            | Self::CapabilityUnprovided { .. }
3392            | Self::CapabilityAmbiguous { .. }
3393            | Self::InvalidCapabilityIdentifier { .. } => None,
3394        }
3395    }
3396}
3397
3398/// A route.open the daemon refused, kept typed inside [`CallError::NotSent`]
3399/// so the refusal's code and `detail` survive. Read it through
3400/// [`CallError::route_open_refusal`].
3401#[derive(Debug, Clone)]
3402struct RouteOpenRefused {
3403    target: String,
3404    body: ErrorBody,
3405    /// The last refusal of a retry loop, when it is not `body`: kept so the
3406    /// message still says what the daemon answered most recently.
3407    most_recent: Option<ErrorBody>,
3408}
3409
3410/// Terminal refusals requiring the caller to supply the scope's current proof.
3411#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3412#[non_exhaustive]
3413pub enum ScopeBindProofRefusal {
3414    Required,
3415    Mismatch,
3416}
3417
3418impl fmt::Display for RouteOpenRefused {
3419    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3420        write!(
3421            f,
3422            "route.open failed for target {}: {}",
3423            self.target,
3424            DescribeRefusal(&self.body)
3425        )?;
3426        if let Some(most_recent) = &self.most_recent {
3427            write!(
3428                f,
3429                "; the most recent refusal was {}",
3430                DescribeRefusal(most_recent)
3431            )?;
3432        }
3433        Ok(())
3434    }
3435}
3436
3437impl Error for RouteOpenRefused {}
3438
3439/// A refusal as `code (reason r) (message)`, the reason read from
3440/// `detail.reason` and omitted when the daemon sent none.
3441struct DescribeRefusal<'a>(&'a ErrorBody);
3442
3443impl fmt::Display for DescribeRefusal<'_> {
3444    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3445        write!(f, "{}", self.0.code)?;
3446        if let Some(reason) = refusal_reason(self.0) {
3447            write!(f, " (reason {reason})")?;
3448        }
3449        write!(f, " ({})", self.0.message)
3450    }
3451}
3452
3453fn refusal_reason(body: &ErrorBody) -> Option<&str> {
3454    body.detail.as_ref()?.get("reason")?.as_str()
3455}
3456
3457/// The daemon's reasons for refusing a route.open because too many binds are
3458/// already in flight, on the consumer's connection or towards the target module
3459/// (`crates/subc-daemon/src/control.rs`, `route_open_capacity_refusal` and
3460/// `route_open_target_capacity_refusal`). Both are sent as `target_unavailable`.
3461const ADMISSION_PRESSURE_REASONS: [&str; 2] = ["open_admission_full", "target_binds_full"];
3462/// Markers in the messages of those same admission-pressure refusals. The
3463/// daemon currently logs the reason but leaves it out of the refusal's detail,
3464/// so the message is the only way to recognise them.
3465const ADMISSION_PRESSURE_MESSAGES: [&str; 2] =
3466    ["route.open binds in flight", "route.bind relays in flight"];
3467
3468/// How much a route.open refusal says about why the target was unreachable,
3469/// highest first: the module was changing state (reloading or warming); a
3470/// delegation was not registered; admission pressure; anything else.
3471fn route_open_refusal_rank(body: &ErrorBody) -> u8 {
3472    if body.code == error_codes::MODULE_RELOADING || body.code == error_codes::MODULE_WARMING {
3473        return 3;
3474    }
3475    let reason = refusal_reason(body);
3476    if body.code == "delegation_not_registered" || reason == Some("delegation_not_registered") {
3477        return 2;
3478    }
3479    if body.code == error_codes::TARGET_UNAVAILABLE {
3480        let admission_pressure = match reason {
3481            Some(reason) => ADMISSION_PRESSURE_REASONS.contains(&reason),
3482            None => ADMISSION_PRESSURE_MESSAGES
3483                .iter()
3484                .any(|marker| body.message.contains(marker)),
3485        };
3486        if admission_pressure {
3487            return 1;
3488        }
3489    }
3490    0
3491}
3492
3493/// The route.open refusals one retry loop has seen. When the deadline runs out,
3494/// the error is built from the best-ranked one: after a module restart the most
3495/// recent refusal is often admission pressure ("8 binds in flight"), which
3496/// points a reader at the consumer's concurrency when the module was simply down.
3497#[derive(Default)]
3498struct RouteOpenRefusals {
3499    best: Option<ErrorBody>,
3500    /// Set only while the latest refusal ranked below `best`.
3501    most_recent: Option<ErrorBody>,
3502}
3503
3504impl RouteOpenRefusals {
3505    fn record(&mut self, body: ErrorBody) {
3506        // At equal rank the newer refusal wins: it describes the target's latest state.
3507        let outranks = self
3508            .best
3509            .as_ref()
3510            .is_none_or(|best| route_open_refusal_rank(&body) >= route_open_refusal_rank(best));
3511        if outranks {
3512            self.best = Some(body);
3513            self.most_recent = None;
3514        } else {
3515            self.most_recent = Some(body);
3516        }
3517    }
3518
3519    fn into_error(self, target: String) -> Option<CallError> {
3520        let body = self.best?;
3521        Some(CallError::from_route_open_refusal(RouteOpenRefused {
3522            target,
3523            body,
3524            most_recent: self.most_recent,
3525        }))
3526    }
3527}
3528
3529/// The label a route.open refusal names its target by, the same spelling the
3530/// managed route cache uses.
3531fn route_target_label(target: &RouteTarget) -> String {
3532    match target {
3533        RouteTarget::ToolProvider { module_id } => format!("tool_provider:{module_id}"),
3534        RouteTarget::ManagementSurface { module_id } => format!("management_surface:{module_id}"),
3535        RouteTarget::InternalService {
3536            module_id,
3537            service_id,
3538        } => format!("internal_service:{module_id}:{service_id}"),
3539    }
3540}
3541
3542impl CallError {
3543    fn route_open_refused(target: String, body: ErrorBody) -> Self {
3544        Self::from_route_open_refusal(RouteOpenRefused {
3545            target,
3546            body,
3547            most_recent: None,
3548        })
3549    }
3550
3551    fn from_route_open_refusal(refusal: RouteOpenRefused) -> Self {
3552        Self::NotSent(Box::new(NotSentSource {
3553            message: refusal.to_string(),
3554            cause: NotSentCause::RouteOpenRefused {
3555                code: refusal.body.code.clone(),
3556            },
3557            never_forwarded: true,
3558            route_reason: None,
3559            refusal: Some(Box::new(refusal)),
3560        }))
3561    }
3562}
3563
3564#[derive(Debug)]
3565struct SimpleError(String);
3566
3567impl fmt::Display for SimpleError {
3568    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3569        f.write_str(&self.0)
3570    }
3571}
3572
3573impl Error for SimpleError {}
3574
3575type Callback = Arc<Mutex<Box<dyn Fn(ConnectionState) + Send + 'static>>>;
3576
3577type OpeningWaiter = oneshot::Sender<Result<RouteState, SharedCallFailure>>;
3578
3579/// An in-flight route.open for one key: the waiters parked behind the lead opener,
3580/// plus a `closed` flag a concurrent `close_route` flips so the lead opener refuses
3581/// to install its channel (the close-beats-reopen guard). The flag lives here, with
3582/// the in-flight open, so it vanishes when the open finishes — no lingering per-key
3583/// state to leak for a long-lived consumer with unbounded distinct routes.
3584struct Opening {
3585    waiters: Vec<OpeningWaiter>,
3586    closed: bool,
3587}
3588
3589struct Shared {
3590    claim_bound: bool,
3591    connection_file: PathBuf,
3592    operator_app_candidates: Option<Vec<PathBuf>>,
3593    opts: ConsumerOptions,
3594    transport: ConsumerTransport,
3595    identity_from_environment: bool,
3596    inner: Mutex<Inner>,
3597    notify: Notify,
3598    #[cfg(test)]
3599    before_wait: Mutex<Option<Box<dyn FnOnce() + Send>>>,
3600    close_token: CancellationToken,
3601    /// Epoch milliseconds of the last frame dispatched from the current connection.
3602    /// The liveness probe reads this to distinguish a healthy slow request from a
3603    /// socket that has silently stopped delivering inbound traffic.
3604    last_inbound_ms: AtomicU64,
3605    /// Only one deadline-triggered liveness probe may be active across generations.
3606    liveness_probe_running: AtomicBool,
3607    pushes_dropped_no_receiver: AtomicU64,
3608    /// Always-present drop counter for channel-0 control pushes (no receiver,
3609    /// receiver full/closed, or unparseable body). Before this surface existed
3610    /// the drop was SILENT -- not even a counter -- which is how #31's push
3611    /// family shipped unreachable to every Rust consumer (issue #35).
3612    control_pushes_dropped: AtomicU64,
3613    /// Pushes dropped because a registered receiver's bounded buffer was full
3614    /// at delivery time. Distinct from `pushes_dropped_no_receiver` because the
3615    /// operator remedies differ: full means the consumer is too slow (widen the
3616    /// buffer or drain faster), no-receiver means it never subscribed.
3617    pushes_dropped_receiver_full: AtomicU64,
3618    /// Random source in [0, 1) for retry jitter. Tests replace it with a seeded
3619    /// one so jittered delays are reproducible.
3620    random_unit: Box<dyn Fn() -> f64 + Send + Sync>,
3621    /// One permit per route.open the consumer may have outstanding; see
3622    /// [`MAX_ROUTE_OPENS_IN_FLIGHT`]. tokio's semaphore grants permits in
3623    /// request order, which makes the wait first come first served. The consumer
3624    /// holds one connection at a time and a dropped connection fails every open
3625    /// in flight on it, so one semaphore is a per-connection limit.
3626    route_open_slots: Semaphore,
3627    // Serialize the first description lookup, not ordinary opens. The cached
3628    // result belongs to Inner's generation and is reset on reconnect.
3629    route_description: tokio::sync::Mutex<()>,
3630}
3631
3632struct Inner {
3633    generation: u64,
3634    daemon_origin_trusted: bool,
3635    daemon_ver: String,
3636    accepts_close_reasons: Option<bool>,
3637    epoch: u64,
3638    next_corr: Option<u64>,
3639    writer: Option<mpsc::Sender<WriteCommand>>,
3640    pending: HashMap<PendingKey, PendingEntry>,
3641    wire_slots: HashMap<PendingKey, Arc<RoutePermit>>,
3642    routes: HashMap<RouteKey, RouteState>,
3643    route_by_channel: HashMap<u16, RouteKey>,
3644    one_shot_routes: HashMap<u16, RouteState>,
3645    route_epochs: HashMap<u16, RouteHandle>,
3646    route_targets: HashMap<RouteHandle, RouteOpenTarget>,
3647    retired_routes: HashSet<RouteHandle>,
3648    retirement_goodbyes: HashSet<RouteHandle>,
3649    retirement_queue: VecDeque<RouteHandle>,
3650    retirement_notify: Arc<Notify>,
3651    retirement_task: Option<JoinHandle<()>>,
3652    route_modules: HashMap<u16, String>,
3653    route_end_reasons: HashMap<u16, (RouteEnd, bool)>,
3654    legacy_channel_reasons: HashMap<u16, RouteEnd>,
3655    push_event_receivers: HashMap<RouteHandle, mpsc::Sender<PushEvent>>,
3656    /// Consumer-level receiver for daemon-originated channel-0 control pushes
3657    /// (`route.closing`, `route.closed`, future ops). Connection-independent:
3658    /// control pushes are advisory daemon events, so the receiver survives
3659    /// reconnects rather than being keyed by generation.
3660    control_push_receiver: Option<mpsc::Sender<ControlPush>>,
3661    dropped_route_frames: u64,
3662    openings: HashMap<RouteKey, Opening>,
3663    callbacks: Vec<Callback>,
3664    closed: bool,
3665    reconnect: ReconnectState,
3666    restored_token: u64,
3667    reader_task: Option<JoinHandle<()>>,
3668    writer_task: Option<JoinHandle<()>>,
3669}
3670
3671impl Inner {
3672    fn record_route_end(&mut self, push: &ControlPush) {
3673        let Some(reason) = push.route_close_reason() else {
3674            return;
3675        };
3676        let end = RouteEnd {
3677            reason: RouteEndReason::Daemon(reason),
3678            terminal: (push.op == "route.closed")
3679                .then(|| {
3680                    push.body
3681                        .get("terminal")
3682                        .and_then(serde_json::Value::as_bool)
3683                })
3684                .flatten(),
3685        };
3686        if let Some(channels) = push.body.get("channels") {
3687            if let Some(channels) = channels.as_array() {
3688                for channel in channels
3689                    .iter()
3690                    .filter_map(|v| v.as_u64().and_then(|v| u16::try_from(v).ok()))
3691                {
3692                    let final_reason = push.op == "route.closed";
3693                    if final_reason
3694                        || !self
3695                            .route_end_reasons
3696                            .get(&channel)
3697                            .is_some_and(|(_, final_reason)| *final_reason)
3698                    {
3699                        self.route_end_reasons
3700                            .insert(channel, (end.clone(), final_reason));
3701                    }
3702                }
3703            }
3704        } else if let Some(module) = push.body.get("module_id").and_then(|v| v.as_str()) {
3705            for (&channel, target) in &self.route_modules {
3706                if target == module {
3707                    self.legacy_channel_reasons.insert(channel, end.clone());
3708                }
3709            }
3710        }
3711    }
3712
3713    fn route_end(&self, channel: u16) -> RouteEnd {
3714        self.route_end_reasons
3715            .get(&channel)
3716            .map(|(reason, _)| reason.clone())
3717            .or_else(|| self.legacy_channel_reasons.get(&channel).cloned())
3718            .unwrap_or_else(|| RouteEndReason::Unknown.into())
3719    }
3720
3721    #[cfg(test)]
3722    fn route_end_reason(&self, channel: u16) -> RouteEndReason {
3723        self.route_end(channel).reason
3724    }
3725
3726    fn cache_route(&mut self, key: RouteKey, route: RouteState) -> RouteState {
3727        let cached = self.routes.entry(key.clone()).or_insert(route).clone();
3728        let previous = self
3729            .route_by_channel
3730            .insert(cached.handle.channel, key.clone());
3731        debug_assert!(previous.as_ref().is_none_or(|previous| previous == &key));
3732        self.route_epochs
3733            .insert(cached.handle.channel, cached.handle);
3734        cached
3735    }
3736
3737    fn remove_route(&mut self, key: &RouteKey) -> Option<RouteState> {
3738        let route = self.evict_route(key)?;
3739        release_reverse_request_registry(route.handle);
3740        Some(route)
3741    }
3742
3743    fn evict_route(&mut self, key: &RouteKey) -> Option<RouteState> {
3744        let route = self.routes.remove(key)?;
3745        let indexed = self.route_by_channel.remove(&route.handle.channel);
3746        debug_assert_eq!(indexed.as_ref(), Some(key));
3747        Some(route)
3748    }
3749
3750    fn reap_retired_route(&mut self, handle: RouteHandle) {
3751        // A caller may be gone while its written correlation still owns credit.
3752        // Keep ingress for those tombstones as well as live pending callers.
3753        if !self.retired_routes.contains(&handle)
3754            || self
3755                .pending
3756                .keys()
3757                .chain(self.wire_slots.keys())
3758                .any(|key| {
3759                    key.generation == handle.connection_token()
3760                        && key.channel == handle.channel
3761                        && key.epoch == handle.epoch
3762                })
3763        {
3764            return;
3765        }
3766        // Pending keys carry only the wire identity. Use the retained handle
3767        // when releasing its reverse-request registry after retirement.
3768        let handle = *self
3769            .retired_routes
3770            .get(&handle)
3771            .expect("retired route exists");
3772        if self.retirement_goodbyes.contains(&handle) {
3773            if !self.queue_retirement_goodbye(handle) {
3774                // Keep the ingress handle occupied until the flusher queues the
3775                // GOODBYE, so a reopened route cannot take this channel first.
3776                return;
3777            }
3778            self.retirement_goodbyes.remove(&handle);
3779        }
3780        self.retired_routes.remove(&handle);
3781        if self.route_epochs.get(&handle.channel) == Some(&handle) {
3782            self.route_epochs.remove(&handle.channel);
3783            self.route_targets.remove(&handle);
3784            self.push_event_receivers.remove(&handle);
3785        }
3786        release_reverse_request_registry(handle);
3787    }
3788
3789    fn queue_retirement_goodbye(&mut self, handle: RouteHandle) -> bool {
3790        if self.generation != handle.connection_token()
3791            || self.route_epochs.get(&handle.channel) != Some(&handle)
3792            || self.writer.is_none()
3793        {
3794            return true;
3795        }
3796        if self.retirement_queue.is_empty() {
3797            let frame = Frame::build(
3798                FrameType::Goodbye,
3799                Flags::new(false, Priority::Interactive, false),
3800                handle.channel,
3801                handle.epoch,
3802                0,
3803                Vec::new(),
3804            )
3805            .expect("header-only route GOODBYE is valid");
3806            if self
3807                .writer
3808                .as_ref()
3809                .unwrap()
3810                .try_send(WriteCommand {
3811                    frame,
3812                    pending: None,
3813                })
3814                .is_ok()
3815            {
3816                return true;
3817            }
3818        }
3819        // Once one retirement is waiting, later retirements join the same FIFO
3820        // rather than overtaking it through the synchronous fast path.
3821        if !self.retirement_queue.contains(&handle) {
3822            self.retirement_queue.push_back(handle);
3823        }
3824        self.retirement_notify.notify_one();
3825        false
3826    }
3827
3828    fn remove_pending(&mut self, key: &PendingKey) -> Option<PendingEntry> {
3829        let entry = self.pending.remove(key);
3830        if entry.as_ref().is_some_and(|entry| !entry.accepted) {
3831            if let Some(slot) = self.wire_slots.remove(key) {
3832                slot.release();
3833            }
3834        }
3835        self.reap_retired_route(RouteHandle::new(key.channel, key.epoch, key.generation));
3836        entry
3837    }
3838
3839    fn release_wire_slots(&mut self, handle: RouteHandle) {
3840        self.wire_slots.retain(|key, slot| {
3841            let keep = key.generation != handle.connection_token()
3842                || key.channel != handle.channel
3843                || key.epoch != handle.epoch;
3844            if !keep {
3845                slot.release();
3846            }
3847            keep
3848        });
3849    }
3850
3851    fn remove_route_by_handle(&mut self, handle: RouteHandle) -> Option<RouteState> {
3852        if let Some(key) = self.route_by_channel.get(&handle.channel).cloned() {
3853            let matches = self
3854                .routes
3855                .get(&key)
3856                .is_some_and(|route| route.handle == handle);
3857            debug_assert!(matches);
3858            if matches {
3859                return self.remove_route(&key);
3860            }
3861        }
3862        let route = self
3863            .one_shot_routes
3864            .get(&handle.channel)
3865            .is_some_and(|route| route.handle == handle)
3866            .then(|| self.one_shot_routes.remove(&handle.channel))
3867            .flatten();
3868        if let Some(route) = &route {
3869            release_reverse_request_registry(route.handle);
3870        }
3871        route
3872    }
3873
3874    fn drain_routes(&mut self) -> Vec<RouteState> {
3875        self.route_targets.clear();
3876        for (_, slot) in self.wire_slots.drain() {
3877            slot.release();
3878        }
3879        self.retirement_goodbyes.clear();
3880        self.retirement_queue.clear();
3881        if let Some(task) = self.retirement_task.take() {
3882            task.abort();
3883        }
3884        for handle in self.retired_routes.drain() {
3885            release_reverse_request_registry(handle);
3886        }
3887        self.route_by_channel.clear();
3888        let routes = self
3889            .routes
3890            .drain()
3891            .map(|(_, route)| route)
3892            .chain(self.one_shot_routes.drain().map(|(_, route)| route))
3893            .collect::<Vec<_>>();
3894        for route in &routes {
3895            release_reverse_request_registry(route.handle);
3896        }
3897        routes
3898    }
3899
3900    fn close_routes(&mut self) {
3901        self.push_event_receivers.clear();
3902        for route in self.drain_routes() {
3903            route.close();
3904        }
3905    }
3906}
3907
3908impl Shared {
3909    fn new(connection_file: PathBuf, opts: ConsumerOptions) -> Self {
3910        Self::with_transport(connection_file, opts, ConsumerTransport::Tcp)
3911    }
3912
3913    fn with_transport(
3914        connection_file: PathBuf,
3915        opts: ConsumerOptions,
3916        transport: ConsumerTransport,
3917    ) -> Self {
3918        Self {
3919            claim_bound: crate::registration::bound(),
3920            connection_file,
3921            operator_app_candidates: None,
3922            opts,
3923            transport,
3924            identity_from_environment: true,
3925            inner: Mutex::new(Inner {
3926                generation: 1,
3927                daemon_origin_trusted: false,
3928                daemon_ver: String::new(),
3929                accepts_close_reasons: None,
3930                epoch: 1,
3931                next_corr: Some(1),
3932                writer: None,
3933                pending: HashMap::new(),
3934                wire_slots: HashMap::new(),
3935                routes: HashMap::new(),
3936                route_by_channel: HashMap::new(),
3937                one_shot_routes: HashMap::new(),
3938                route_epochs: HashMap::new(),
3939                route_targets: HashMap::new(),
3940                retired_routes: HashSet::new(),
3941                retirement_goodbyes: HashSet::new(),
3942                retirement_queue: VecDeque::new(),
3943                retirement_notify: Arc::new(Notify::new()),
3944                retirement_task: None,
3945                route_modules: HashMap::new(),
3946                route_end_reasons: HashMap::new(),
3947                legacy_channel_reasons: HashMap::new(),
3948                push_event_receivers: HashMap::new(),
3949                control_push_receiver: None,
3950                dropped_route_frames: 0,
3951                openings: HashMap::new(),
3952                callbacks: Vec::new(),
3953                closed: false,
3954                reconnect: ReconnectState::Idle,
3955                restored_token: 0,
3956                reader_task: None,
3957                writer_task: None,
3958            }),
3959            notify: Notify::new(),
3960            #[cfg(test)]
3961            before_wait: Mutex::new(None),
3962            close_token: CancellationToken::new(),
3963            last_inbound_ms: AtomicU64::new(0),
3964            liveness_probe_running: AtomicBool::new(false),
3965            pushes_dropped_no_receiver: AtomicU64::new(0),
3966            control_pushes_dropped: AtomicU64::new(0),
3967            pushes_dropped_receiver_full: AtomicU64::new(0),
3968            random_unit: Box::new(default_random_unit),
3969            route_open_slots: Semaphore::new(MAX_ROUTE_OPENS_IN_FLIGHT),
3970            route_description: tokio::sync::Mutex::new(()),
3971        }
3972    }
3973
3974    /// "Equal jitter": keep half of `delay` and randomize the other half. Every
3975    /// route on a connection is closed together when its module drains, so
3976    /// without jitter they all retry in lock step and reach the daemon as one
3977    /// burst each round; reconnects after a daemon restart herd the same way.
3978    fn jittered(&self, delay: Duration) -> Duration {
3979        let unit = (self.random_unit)();
3980        let unit = if unit.is_finite() {
3981            unit.clamp(0.0, 1.0)
3982        } else {
3983            0.0
3984        };
3985        let half = delay / 2;
3986        half + half.mul_f64(unit)
3987    }
3988
3989    /// One route.open exchange, paced by [`MAX_ROUTE_OPENS_IN_FLIGHT`]. The
3990    /// wait for a free slot ends at `deadline` like the exchange itself.
3991    async fn paced_route_open(
3992        self: &Arc<Self>,
3993        body: Vec<u8>,
3994        deadline: Instant,
3995        reverse_requests: Option<ReverseRequestRegistry>,
3996    ) -> Result<TerminalFrame, CallError> {
3997        let _slot = match timeout_at(deadline, self.route_open_slots.acquire()).await {
3998            Ok(Ok(permit)) => permit,
3999            Ok(Err(_)) => return Err(CallError::not_sent("consumer closed")),
4000            Err(_) => {
4001                return Err(CallError::not_sent(format!(
4002                    "deadline elapsed waiting for one of {MAX_ROUTE_OPENS_IN_FLIGHT} route.open slots"
4003                )));
4004            }
4005        };
4006        self.control_call(body, deadline, true, reverse_requests)
4007            .await
4008    }
4009
4010    fn lock_inner(&self) -> MutexGuard<'_, Inner> {
4011        self.inner
4012            .lock()
4013            .unwrap_or_else(|poisoned| poisoned.into_inner())
4014    }
4015
4016    fn install_initial(self: &Arc<Self>, opened: OpenedConnection) -> Result<(), ConsumerError> {
4017        self.install_connection(opened, InstallKind::Initial)
4018            .map(|_| ())
4019    }
4020
4021    fn install_reconnected(
4022        self: &Arc<Self>,
4023        opened: OpenedConnection,
4024    ) -> Result<(u64, u64), ConsumerError> {
4025        let generation_epoch = self.install_connection(opened, InstallKind::Reconnect)?;
4026        self.notify.notify_waiters();
4027        Ok(generation_epoch)
4028    }
4029
4030    fn install_connection(
4031        self: &Arc<Self>,
4032        opened: OpenedConnection,
4033        kind: InstallKind,
4034    ) -> Result<(u64, u64), ConsumerError> {
4035        if self.close_token.is_cancelled() {
4036            return Err(ConsumerError::Closed);
4037        }
4038
4039        let (reader, writer) = tokio::io::split(opened.stream);
4040        let (tx, rx) = mpsc::channel(EGRESS_BUFFER);
4041        let (generation, epoch, old_reader, old_writer) = {
4042            let mut inner = self.lock_inner();
4043            if inner.closed {
4044                return Err(ConsumerError::Closed);
4045            }
4046            let (generation, epoch) = match kind {
4047                InstallKind::Initial => (inner.generation, inner.epoch),
4048                InstallKind::Reconnect => {
4049                    inner.generation = inner
4050                        .generation
4051                        .checked_add(1)
4052                        .ok_or(ConsumerError::Closed)?;
4053                    inner.epoch = inner.epoch.checked_add(1).ok_or(ConsumerError::Closed)?;
4054                    (inner.generation, inner.epoch)
4055                }
4056            };
4057            inner.close_routes();
4058            inner.route_epochs.clear();
4059            inner.route_targets.clear();
4060            inner.route_modules.clear();
4061            inner.route_end_reasons.clear();
4062            inner.legacy_channel_reasons.clear();
4063            inner.next_corr = Some(1);
4064            inner.writer = Some(tx);
4065            inner.daemon_origin_trusted = opened.daemon_origin_trusted;
4066            inner.daemon_ver = opened.daemon_ver;
4067            inner.accepts_close_reasons = None;
4068            self.last_inbound_ms.store(0, Ordering::Release);
4069            (
4070                generation,
4071                epoch,
4072                inner.reader_task.take(),
4073                inner.writer_task.take(),
4074            )
4075        };
4076
4077        if let Some(handle) = old_reader {
4078            handle.abort();
4079        }
4080        if let Some(handle) = old_writer {
4081            handle.abort();
4082        }
4083
4084        let reader_shared = Arc::clone(self);
4085        let reader_task = tokio::spawn(async move {
4086            reader_loop(reader_shared, reader, generation).await;
4087        });
4088        let writer_shared = Arc::clone(self);
4089        let writer_task = tokio::spawn(async move {
4090            writer_loop(writer_shared, writer, rx, generation).await;
4091        });
4092
4093        {
4094            let mut inner = self.lock_inner();
4095            if inner.closed || inner.generation != generation {
4096                reader_task.abort();
4097                writer_task.abort();
4098                return Err(ConsumerError::Closed);
4099            }
4100            inner.reader_task = Some(reader_task);
4101            inner.writer_task = Some(writer_task);
4102            let retirement_shared = Arc::clone(self);
4103            let retirement_notify = Arc::clone(&inner.retirement_notify);
4104            inner.retirement_task = Some(tokio::spawn(async move {
4105                retirement_goodbye_loop(retirement_shared, generation, retirement_notify).await;
4106            }));
4107        }
4108
4109        Ok((generation, epoch))
4110    }
4111
4112    async fn ensure_connected_for_call(
4113        self: &Arc<Self>,
4114        deadline: Instant,
4115    ) -> Result<(), CallError> {
4116        loop {
4117            if Instant::now() >= deadline {
4118                return Err(CallError::not_sent(
4119                    "call deadline elapsed waiting for reconnection",
4120                ));
4121            }
4122            // Created BEFORE the state is read, and that ordering is the fix.
4123            // Reconnect completion wakes waiters with `notify_waiters()`, which
4124            // reaches only `Notified` futures that already exist and stores no
4125            // permit. A future created after the lock is released misses a
4126            // reconnect that finishes in between, and the caller then sleeps
4127            // until its deadline on a healthy connection. (`enable()` is kept
4128            // for `notify_one` semantics; for `notify_waiters` creation alone
4129            // is what registers the waiter.)
4130            let notified = self.notify.notified();
4131            tokio::pin!(notified);
4132            let action = {
4133                let mut inner = self.lock_inner();
4134                notified.as_mut().enable();
4135                if inner.closed {
4136                    return Err(CallError::not_sent("consumer closed"));
4137                }
4138                if inner.writer.is_some() {
4139                    return Ok(());
4140                }
4141                let generation = inner.generation;
4142                let reconnect_is_live = match &inner.reconnect {
4143                    ReconnectState::Idle => false,
4144                    ReconnectState::Inline { generation: active } => *active == generation,
4145                    ReconnectState::Background {
4146                        generation: active,
4147                        task,
4148                    } => *active == generation && !task.is_finished(),
4149                };
4150                if reconnect_is_live {
4151                    EnsureAction::Wait
4152                } else {
4153                    let stale_task =
4154                        match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4155                            ReconnectState::Background { task, .. } => Some(task),
4156                            ReconnectState::Idle | ReconnectState::Inline { .. } => None,
4157                        };
4158                    inner.reconnect = ReconnectState::Inline { generation };
4159                    EnsureAction::Lead {
4160                        generation,
4161                        stale_task,
4162                    }
4163                }
4164            };
4165
4166            match action {
4167                EnsureAction::Wait => {
4168                    #[cfg(test)]
4169                    {
4170                        let hook = self.before_wait.lock().unwrap().take();
4171                        if let Some(hook) = hook {
4172                            hook();
4173                        }
4174                    }
4175                    timeout_at(deadline, notified).await.map_err(|_| {
4176                        CallError::not_sent("call deadline elapsed waiting for reconnection")
4177                    })?;
4178                }
4179                EnsureAction::Lead {
4180                    generation,
4181                    stale_task,
4182                } => {
4183                    if let Some(handle) = stale_task {
4184                        handle.abort();
4185                    }
4186                    let mut guard = InlineReconnectGuard::new(Arc::clone(self), generation);
4187                    let result = timeout_at(deadline, self.reconnect_with_retry(generation)).await;
4188                    guard.finish();
4189                    return match result {
4190                        Ok(Ok(())) => Ok(()),
4191                        Ok(Err(err)) => Err(CallError::not_sent(err.to_string())),
4192                        Err(_) => Err(CallError::not_sent(
4193                            "call deadline elapsed waiting for reconnection",
4194                        )),
4195                    };
4196                }
4197            }
4198        }
4199    }
4200
4201    fn spawn_reconnect(self: &Arc<Self>, generation: u64) -> bool {
4202        // Reconnect ownership is fenced by the dropped transport generation. A
4203        // newer drop replaces an older attempt instead of letting that attempt
4204        // block recovery for the newer transport.
4205        let stale_task = {
4206            let mut inner = self.lock_inner();
4207            if inner.closed || inner.writer.is_some() || inner.generation != generation {
4208                return false;
4209            }
4210            let should_spawn = match &inner.reconnect {
4211                ReconnectState::Idle => true,
4212                ReconnectState::Inline { generation: active } => *active < generation,
4213                ReconnectState::Background {
4214                    generation: active,
4215                    task,
4216                } => *active < generation || (*active == generation && task.is_finished()),
4217            };
4218            if !should_spawn {
4219                return false;
4220            }
4221
4222            let stale_task = match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4223                ReconnectState::Background { task, .. } => Some(task),
4224                ReconnectState::Idle | ReconnectState::Inline { .. } => None,
4225            };
4226            let shared = Arc::clone(self);
4227            let handle = tokio::spawn(async move {
4228                let _result = shared.reconnect_with_retry(generation).await;
4229                shared.finish_background_reconnect(generation);
4230            });
4231            inner.reconnect = ReconnectState::Background {
4232                generation,
4233                task: handle,
4234            };
4235            stale_task
4236        };
4237        if let Some(handle) = stale_task {
4238            handle.abort();
4239        }
4240        true
4241    }
4242
4243    async fn reconnect_with_retry(
4244        self: &Arc<Self>,
4245        reconnect_generation: u64,
4246    ) -> Result<(), ConsumerError> {
4247        let mut last_error: Option<ConsumerError> = None;
4248        for attempt in 1..=self.opts.reconnect_backoff.max_attempts {
4249            if self.close_token.is_cancelled() {
4250                return Err(ConsumerError::Closed);
4251            }
4252            if !self.reconnect_attempt_is_current(reconnect_generation) {
4253                return Ok(());
4254            }
4255
4256            match open_connection(
4257                &self.connection_file,
4258                self.opts.handshake_timeout,
4259                self.transport,
4260                self.operator_app_candidates.as_deref(),
4261            )
4262            .await
4263            {
4264                Ok(opened) => {
4265                    // A newer drop may have installed its own attempt while this
4266                    // connection was opening. Do not let the stale attempt replace it.
4267                    if !self.reconnect_attempt_is_current(reconnect_generation) {
4268                        return Ok(());
4269                    }
4270                    let (generation, epoch) = self.install_reconnected(opened)?;
4271                    self.schedule_restored(generation, epoch);
4272                    return Ok(());
4273                }
4274                Err(err) => {
4275                    let transient = is_reconnect_transient(&err);
4276                    last_error = Some(err);
4277                    if !transient || attempt >= self.opts.reconnect_backoff.max_attempts {
4278                        break;
4279                    }
4280                    // Jittered like the route.open retries, which share this backoff.
4281                    let delay =
4282                        self.jittered(self.opts.reconnect_backoff.delay_after_attempt(attempt));
4283                    tokio::select! {
4284                        () = self.close_token.cancelled() => return Err(ConsumerError::Closed),
4285                        () = sleep(delay) => {}
4286                    }
4287                }
4288            }
4289        }
4290        Err(last_error.unwrap_or(ConsumerError::Closed))
4291    }
4292
4293    fn reconnect_attempt_is_current(&self, generation: u64) -> bool {
4294        let inner = self.lock_inner();
4295        !inner.closed
4296            && inner.writer.is_none()
4297            && inner.generation == generation
4298            && matches!(
4299                &inner.reconnect,
4300                ReconnectState::Inline { generation: active }
4301                    | ReconnectState::Background {
4302                        generation: active,
4303                        ..
4304                    } if *active == generation
4305            )
4306    }
4307
4308    fn finish_inline_reconnect(&self, generation: u64) {
4309        let finished = {
4310            let mut inner = self.lock_inner();
4311            if matches!(
4312                &inner.reconnect,
4313                ReconnectState::Inline { generation: active } if *active == generation
4314            ) {
4315                inner.reconnect = ReconnectState::Idle;
4316                true
4317            } else {
4318                false
4319            }
4320        };
4321        if finished {
4322            self.notify.notify_waiters();
4323        }
4324    }
4325
4326    fn finish_background_reconnect(&self, generation: u64) {
4327        let completed_task = {
4328            let mut inner = self.lock_inner();
4329            if !matches!(
4330                &inner.reconnect,
4331                ReconnectState::Background { generation: active, .. } if *active == generation
4332            ) {
4333                None
4334            } else {
4335                match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4336                    ReconnectState::Background { task, .. } => Some(task),
4337                    ReconnectState::Idle | ReconnectState::Inline { .. } => unreachable!(),
4338                }
4339            }
4340        };
4341        if completed_task.is_some() {
4342            drop(completed_task);
4343            self.notify.notify_waiters();
4344        }
4345    }
4346
4347    fn schedule_restored(self: &Arc<Self>, generation: u64, epoch: u64) {
4348        let token = {
4349            let mut inner = self.lock_inner();
4350            inner.restored_token = inner.restored_token.saturating_add(1);
4351            inner.restored_token
4352        };
4353        let shared = Arc::clone(self);
4354        tokio::spawn(async move {
4355            tokio::select! {
4356                () = shared.close_token.cancelled() => {}
4357                () = sleep(shared.opts.restored_debounce) => {
4358                    let should_emit = {
4359                        let inner = shared.lock_inner();
4360                        !inner.closed
4361                            && inner.generation == generation
4362                            && inner.epoch == epoch
4363                            && inner.restored_token == token
4364                            && inner.writer.is_some()
4365                    };
4366                    if should_emit {
4367                        shared.emit_connection_state(ConnectionState::Restored { epoch });
4368                    }
4369                }
4370            }
4371        });
4372    }
4373
4374    fn install_one_shot_route(&self, route: RouteState) -> Result<(), CallError> {
4375        let handle = route.handle;
4376        let mut inner = self.lock_inner();
4377        if inner.closed || inner.generation != handle.connection_token() || inner.writer.is_none() {
4378            return Err(CallError::StaleRouteHandle(handle));
4379        }
4380        // The socket reader installs the handle for a route.open response before
4381        // the waiter resolves (so a request the provider sends right after the
4382        // bind is routed), so this route's own channel is normally present
4383        // already, holding exactly this handle. Only a different handle on the
4384        // channel is a collision.
4385        if inner
4386            .route_epochs
4387            .get(&handle.channel)
4388            .is_some_and(|existing| *existing != handle)
4389        {
4390            return Err(CallError::not_sent(
4391                "daemon returned a route channel already in use",
4392            ));
4393        }
4394        inner.one_shot_routes.insert(handle.channel, route);
4395        inner.route_epochs.insert(handle.channel, handle);
4396        Ok(())
4397    }
4398
4399    async fn ensure_route(
4400        self: &Arc<Self>,
4401        key: &RouteKey,
4402        route_open: &RouteOpenParams<'_>,
4403        opts: &CallOptions,
4404        call_deadline: Instant,
4405    ) -> Result<RouteState, CallError> {
4406        loop {
4407            let action = {
4408                let mut inner = self.lock_inner();
4409                if inner.closed {
4410                    return Err(CallError::not_sent("consumer closed"));
4411                }
4412                if let Some(route) = inner.routes.get(key) {
4413                    if route.handle.connection_token() == inner.generation && inner.writer.is_some()
4414                    {
4415                        return Ok(route.clone());
4416                    }
4417                }
4418                if let Some(opening) = inner.openings.get_mut(key) {
4419                    let (tx, rx) = oneshot::channel();
4420                    opening.waiters.push(tx);
4421                    RouteOpenAction::Wait(rx)
4422                } else {
4423                    inner.openings.insert(
4424                        key.clone(),
4425                        Opening {
4426                            waiters: Vec::new(),
4427                            closed: false,
4428                        },
4429                    );
4430                    RouteOpenAction::Lead
4431                }
4432            };
4433
4434            match action {
4435                RouteOpenAction::Wait(rx) => match timeout_at(call_deadline, rx).await {
4436                    Ok(Ok(Ok(route))) => return Ok(route),
4437                    Ok(Ok(Err(err))) => return Err(err.into_call_error()),
4438                    Ok(Err(_)) => continue,
4439                    Err(_) => {
4440                        return Err(CallError::not_sent_with_cause(
4441                            "call deadline elapsed waiting for route.open",
4442                            NotSentCause::RouteOpenAbandoned,
4443                        ));
4444                    }
4445                },
4446                RouteOpenAction::Lead => {
4447                    let mut guard = OpeningGuard::new(Arc::clone(self), key.clone());
4448                    let result = self
4449                        .open_route_with_retry(key, route_open, opts, call_deadline)
4450                        .await
4451                        .map_err(SharedCallFailure::from);
4452                    guard.finish(result.clone());
4453                    return result.map_err(SharedCallFailure::into_call_error);
4454                }
4455            }
4456        }
4457    }
4458
4459    async fn open_route_with_retry(
4460        self: &Arc<Self>,
4461        key: &RouteKey,
4462        route_open: &RouteOpenParams<'_>,
4463        opts: &CallOptions,
4464        call_deadline: Instant,
4465    ) -> Result<RouteState, CallError> {
4466        let route_deadline = (Instant::now() + opts.route_retry_deadline).min(call_deadline);
4467        let mut attempt = 0usize;
4468        // The retryable refusals seen so far. When the deadline ends the retries,
4469        // the caller gets the most informative of them rather than a bare
4470        // "deadline elapsed", so "the module was reloading" stays
4471        // distinguishable from "the connection failed".
4472        let mut refusals = RouteOpenRefusals::default();
4473        // An attempt that ends because the deadline passed hands back the kept
4474        // refusal. That covers an attempt that never left the client (NotSent)
4475        // and one the daemon received but had not answered by the deadline
4476        // (OutcomeUnknown with the Deadline cause): a busy daemon can answer
4477        // the final retry a few milliseconds late, and the refusals before it
4478        // still say why the route never opened. Dropping the unanswered
4479        // attempt's own outcome is safe: route.open requests are sent with
4480        // `retain_late_route_open`, so a late acceptance is closed again with
4481        // a GOODBYE instead of being handed to anyone.
4482        let expired = |err: CallError, refusals: &mut RouteOpenRefusals| {
4483            let ended_by_deadline =
4484                err.is_not_sent() || err.outcome_cause() == Some(OutcomeUnknownCause::Deadline);
4485            if ended_by_deadline && Instant::now() >= route_deadline {
4486                if let Some(refused) = std::mem::take(refusals).into_error(key.target_label()) {
4487                    return refused;
4488                }
4489            }
4490            err
4491        };
4492        loop {
4493            attempt = attempt.saturating_add(1);
4494            let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
4495                busy_refusals: Some(true),
4496                target: route_open.target.clone(),
4497                identity: route_open.identity.clone(),
4498                consumer_identity: route_open.consumer_identity.clone(),
4499                consumer_capabilities: route_open.consumer_capabilities.clone(),
4500                role_versions: route_open.role_versions.clone(),
4501                admission_facts: None,
4502                scope: route_open.scope.cloned(),
4503            })
4504            .map_err(|err| CallError::not_sent(format!("failed to encode route.open: {err}")))?;
4505            match self
4506                .paced_route_open(
4507                    body,
4508                    route_deadline,
4509                    Some(route_open.reverse_requests.clone()),
4510                )
4511                .await
4512            {
4513                Ok(TerminalFrame::Response {
4514                    generation, body, ..
4515                }) => {
4516                    let (response, _) = decode_route_open_response(&body).map_err(|err| {
4517                        CallError::not_sent_with_cause(
4518                            format!("failed to decode route.open response: {err}"),
4519                            NotSentCause::RouteOpenAbandoned,
4520                        )
4521                    })?;
4522                    let ClientControlResponse::RouteOpen {
4523                        route_channel,
4524                        route_epoch,
4525                        request_window,
4526                        watch_window,
4527                        ..
4528                    } = response
4529                    else {
4530                        return Err(CallError::not_sent_with_cause(
4531                            "route.open returned an unexpected control response",
4532                            NotSentCause::RouteOpenAbandoned,
4533                        ));
4534                    };
4535                    let handle = self
4536                        .ingress_handle(generation, route_channel, route_epoch)
4537                        .unwrap_or_else(|| {
4538                            RouteHandle::new_consumer(
4539                                route_channel,
4540                                route_epoch,
4541                                generation,
4542                                route_open.reverse_requests.clone(),
4543                            )
4544                        });
4545                    let route = RouteState::windows(handle, request_window, watch_window);
4546                    let install = {
4547                        let mut inner = self.lock_inner();
4548                        if inner.closed {
4549                            return Err(CallError::not_sent("consumer closed"));
4550                        }
4551                        // Close-beats-reopen guard: a close_route may have flipped this
4552                        // opening's `closed` flag WHILE this route.open was in flight. If
4553                        // so, close wins — do NOT cache the channel; GOODBYE it below and
4554                        // fail as NotSent (the route was closed before the open landed).
4555                        let closed_during_open = inner.openings.get(key).is_some_and(|o| o.closed);
4556                        if closed_during_open
4557                            || inner.generation != generation
4558                            || inner.writer.is_none()
4559                        {
4560                            RouteInstall::Discard {
4561                                closed: closed_during_open,
4562                            }
4563                        } else {
4564                            let cached = inner.cache_route(key.clone(), route.clone());
4565                            RouteInstall::Cached(cached)
4566                        }
4567                    };
4568                    match install {
4569                        RouteInstall::Cached(cached) => return Ok(cached),
4570                        RouteInstall::Discard { closed } => {
4571                            if closed {
4572                                // GOODBYE the channel we opened so the daemon/module don't
4573                                // leak it, then report the close as a NotSent failure.
4574                                self.send_route_goodbye(route.handle, true);
4575                                self.uninstall_route_handle(route.handle);
4576                                return Err(CallError::not_sent_with_cause(
4577                                    "route was closed before route.open completed",
4578                                    NotSentCause::RouteOpenAbandoned,
4579                                ));
4580                            }
4581                            // Stale generation / writer gone: fall through to retry.
4582                        }
4583                    }
4584                    self.sleep_until_retry(route_deadline, self.jittered(opts.route_retry.base))
4585                        .await?;
4586                }
4587                Ok(TerminalFrame::Error { body, .. }) => {
4588                    // The deadline is the ONLY binder for retryable refusals.
4589                    // An attempt cap used to share this condition, and because
4590                    // the capped backoff sums to seconds it strictly dominated
4591                    // the deadline — the advertised reload patience was never
4592                    // delivered, and module restarts whose reload exceeded a
4593                    // few seconds failed every managed caller. A restart
4594                    // legitimately keeps routes refused for about a minute;
4595                    // capped per-attempt backoff bounds pressure.
4596                    if !is_retryable_route_open_code(&body.code) {
4597                        return Err(CallError::route_open_refused(key.target_label(), body));
4598                    }
4599                    refusals.record(body);
4600                    if Instant::now() >= route_deadline {
4601                        // A refusal was just recorded, so the fallback is unreachable.
4602                        return Err(std::mem::take(&mut refusals)
4603                            .into_error(key.target_label())
4604                            .unwrap_or_else(|| {
4605                                CallError::not_sent("route.open retry deadline elapsed")
4606                            }));
4607                    }
4608                    let delay = self.jittered(opts.route_retry.delay_after_attempt(attempt));
4609                    if let Err(err) = self.sleep_until_retry(route_deadline, delay).await {
4610                        return Err(expired(err, &mut refusals));
4611                    }
4612                    continue;
4613                }
4614                Ok(TerminalFrame::StreamEnd) => {
4615                    return Err(CallError::not_sent_with_cause(
4616                        "route.open returned StreamEnd",
4617                        NotSentCause::RouteOpenAbandoned,
4618                    ));
4619                }
4620                Err(err) if err.is_not_sent() && Instant::now() < route_deadline => {
4621                    let delay = self.jittered(opts.route_retry.delay_after_attempt(attempt));
4622                    if let Err(err) = self.sleep_until_retry(route_deadline, delay).await {
4623                        return Err(expired(err, &mut refusals));
4624                    }
4625                }
4626                Err(err) => return Err(expired(err, &mut refusals)),
4627            }
4628        }
4629
4630        #[allow(unreachable_code)]
4631        Err(CallError::not_sent(format!(
4632            "route.open retry deadline elapsed for target {}",
4633            key.target_label()
4634        )))
4635    }
4636
4637    async fn sleep_until_retry(&self, deadline: Instant, delay: Duration) -> Result<(), CallError> {
4638        if Instant::now() >= deadline {
4639            return Err(CallError::not_sent("retry deadline elapsed"));
4640        }
4641        let bounded = delay.min(deadline.saturating_duration_since(Instant::now()));
4642        tokio::select! {
4643            () = self.close_token.cancelled() => Err(CallError::not_sent("consumer closed")),
4644            () = sleep(bounded) => Ok(()),
4645        }
4646    }
4647
4648    async fn control_call(
4649        self: &Arc<Self>,
4650        body: Vec<u8>,
4651        deadline: Instant,
4652        retain_late_route_open: bool,
4653        route_open_reverse_requests: Option<ReverseRequestRegistry>,
4654    ) -> Result<TerminalFrame, CallError> {
4655        self.ensure_connected_for_call(deadline).await?;
4656        if retain_late_route_open {
4657            {
4658                let inner = self.lock_inner();
4659                if !daemon_version_at_least(&inner.daemon_ver, (0, 39, 0)) {
4660                    return Err(CallError::DaemonTooOld {
4661                        daemon_ver: inner.daemon_ver.clone(),
4662                    });
4663                }
4664            }
4665            self.describe_route_close_reasons(deadline).await?;
4666        }
4667        self.send_request(RequestSend {
4668            binary: false,
4669            expected_handle: None,
4670            channel: 0,
4671            epoch: 0,
4672            body,
4673            priority: Priority::Interactive,
4674            admission_class: AdmissionClass::Normal,
4675            deadline,
4676            retain_late_route_open,
4677            route_open_reverse_requests,
4678        })
4679        .await
4680    }
4681
4682    async fn describe_route_close_reasons(
4683        self: &Arc<Self>,
4684        deadline: Instant,
4685    ) -> Result<(), CallError> {
4686        let _lookup = timeout_at(deadline, self.route_description.lock())
4687            .await
4688            .map_err(|_| CallError::not_sent("deadline waiting for server.describe"))?;
4689        loop {
4690            self.ensure_connected_for_call(deadline).await?;
4691            let generation = {
4692                let inner = self.lock_inner();
4693                if inner.accepts_close_reasons.is_some() {
4694                    return Ok(());
4695                }
4696                inner.generation
4697            };
4698            // Description is advisory. A refused, malformed or unanswered lookup
4699            // must not prevent opening routes to a daemon that predates the key.
4700            let reply = self
4701                .send_request(RequestSend {
4702                    binary: false,
4703                    expected_handle: None,
4704                    channel: 0,
4705                    epoch: 0,
4706                    body: br#"{"op":"server.describe"}"#.to_vec(),
4707                    priority: Priority::Interactive,
4708                    admission_class: AdmissionClass::Normal,
4709                    deadline: deadline.min(Instant::now() + CAPABILITY_PROBE_TIMEOUT),
4710                    retain_late_route_open: false,
4711                    route_open_reverse_requests: None,
4712                })
4713                .await;
4714            let supported = match reply {
4715                Ok(TerminalFrame::Response { body, .. }) => {
4716                    matches!(serde_json::from_slice::<ClientControlResponse>(&body),
4717                        Ok(ClientControlResponse::ServerDescribe { capabilities, .. })
4718                        if capabilities.iter().any(|cap| cap == ROUTE_CLOSE_REASONS_CAPABILITY))
4719                }
4720                _ => false,
4721            };
4722            let mut inner = self.lock_inner();
4723            if inner.generation == generation {
4724                inner.accepts_close_reasons = Some(supported);
4725                return Ok(());
4726            }
4727        }
4728    }
4729
4730    async fn send_request(
4731        self: &Arc<Self>,
4732        request: RequestSend,
4733    ) -> Result<TerminalFrame, CallError> {
4734        self.send_request_cancellable(request, None).await
4735    }
4736
4737    fn allocate_request(
4738        self: &Arc<Self>,
4739        expected_handle: Option<RouteHandle>,
4740        channel: u16,
4741        epoch: u32,
4742    ) -> Result<(PendingKey, mpsc::Sender<WriteCommand>), CallError> {
4743        let mut inner = self.lock_inner();
4744        if inner.closed {
4745            return Err(CallError::not_sent("consumer closed"));
4746        }
4747        let generation = inner.generation;
4748        if let Some(expected) = expected_handle {
4749            let route_pair_matches =
4750                channel == 0 || (expected.channel == channel && expected.epoch == epoch);
4751            if expected.connection_token() != generation
4752                || !route_pair_matches
4753                || inner.route_epochs.get(&expected.channel) != Some(&expected)
4754                || inner.retired_routes.contains(&expected)
4755            {
4756                return Err(CallError::StaleRouteHandle(expected));
4757            }
4758        }
4759        let Some(writer) = inner.writer.clone() else {
4760            return Err(CallError::not_sent("subc connection is down before send"));
4761        };
4762        let Some(corr) = inner.next_corr else {
4763            drop(inner);
4764            self.handle_generation_drop(
4765                generation,
4766                "channel-0 correlation allocator exhausted".to_string(),
4767            );
4768            return Err(CallError::not_sent(
4769                "correlation allocator exhausted; connection closed",
4770            ));
4771        };
4772        inner.next_corr = corr.checked_add(1);
4773        Ok((
4774            PendingKey {
4775                generation,
4776                channel,
4777                epoch,
4778                corr,
4779            },
4780            writer,
4781        ))
4782    }
4783
4784    async fn send_request_cancellable(
4785        self: &Arc<Self>,
4786        request: RequestSend,
4787        cancel: Option<Arc<UnaryCancel>>,
4788    ) -> Result<TerminalFrame, CallError> {
4789        self.send_request_with_slot(request, cancel, None).await
4790    }
4791
4792    async fn send_request_with_slot(
4793        self: &Arc<Self>,
4794        request: RequestSend,
4795        cancel: Option<Arc<UnaryCancel>>,
4796        slot: Option<Arc<RoutePermit>>,
4797    ) -> Result<TerminalFrame, CallError> {
4798        let RequestSend {
4799            expected_handle,
4800            channel,
4801            epoch,
4802            body,
4803            binary,
4804            priority,
4805            admission_class,
4806            deadline,
4807            retain_late_route_open,
4808            route_open_reverse_requests,
4809        } = request;
4810        if Instant::now() >= deadline {
4811            return Err(CallError::not_sent(
4812                "call deadline elapsed before request was sent",
4813            ));
4814        }
4815        let slot = match (slot, expected_handle) {
4816            (Some(slot), _) => Some(slot),
4817            (None, Some(handle)) if channel != 0 => match self.route_state(handle) {
4818                Ok(route) if route.opted_in => {
4819                    Some(route.acquire(false, deadline, cancel.as_ref()).await?)
4820                }
4821                _ => None,
4822            },
4823            (None, _) => None,
4824        };
4825        let (key, writer) = self.allocate_request(expected_handle, channel, epoch)?;
4826        let generation = key.generation;
4827
4828        let mut frame = Frame::build(
4829            FrameType::Request,
4830            Flags::new(binary, priority, false).with_admission_class(admission_class),
4831            channel,
4832            epoch,
4833            key.corr,
4834            body,
4835        )
4836        .map_err(|err| CallError::not_sent(format!("failed to build request frame: {err}")))?;
4837        let (tx, rx) = oneshot::channel();
4838        {
4839            let mut inner = self.lock_inner();
4840            if inner.closed || inner.generation != generation || inner.writer.is_none() {
4841                return Err(CallError::not_sent(
4842                    "connection changed before request registration",
4843                ));
4844            }
4845            // Check the version retained for the authenticated connection under
4846            // the same lock as registration, so reconnecting cannot send a
4847            // rootless identity after a check on a different connection.
4848            if retain_late_route_open && !daemon_version_at_least(&inner.daemon_ver, (0, 39, 0)) {
4849                return Err(CallError::DaemonTooOld {
4850                    daemon_ver: inner.daemon_ver.clone(),
4851                });
4852            }
4853            if retain_late_route_open {
4854                let supported = inner.accepts_close_reasons.ok_or_else(|| {
4855                    CallError::not_sent("connection changed before route.open capability discovery")
4856                })?;
4857                let mut body: serde_json::Value = serde_json::from_slice(&frame.body)
4858                    .map_err(|err| CallError::not_sent(format!("invalid route.open: {err}")))?;
4859                RouteOpenRequestExt::new()
4860                    .with_accepts_close_reasons(supported.then(|| {
4861                        ACCEPTED_CLOSE_REASONS
4862                            .iter()
4863                            .map(|reason| (*reason).to_string())
4864                            .collect()
4865                    }))
4866                    .write_to(&mut body)
4867                    .map_err(|err| CallError::not_sent(format!("invalid route.open: {err}")))?;
4868                frame = Frame::build(
4869                    FrameType::Request,
4870                    frame.header.flags,
4871                    channel,
4872                    epoch,
4873                    key.corr,
4874                    serde_json::to_vec(&body)
4875                        .map_err(|err| CallError::not_sent(err.to_string()))?,
4876                )
4877                .map_err(|err| CallError::not_sent(err.to_string()))?;
4878            }
4879            if let Some(expected) = expected_handle {
4880                if inner.route_epochs.get(&expected.channel) != Some(&expected)
4881                    || inner.retired_routes.contains(&expected)
4882                {
4883                    return Err(CallError::StaleRouteHandle(expected));
4884                }
4885            }
4886            let expected_control_handle = (channel == 0 && !retain_late_route_open)
4887                .then_some(expected_handle)
4888                .flatten();
4889            inner.pending.insert(
4890                key,
4891                PendingEntry::unary(
4892                    tx,
4893                    retain_late_route_open,
4894                    expected_control_handle,
4895                    route_open_reverse_requests,
4896                ),
4897            );
4898            if let Some(slot) = slot.filter(|slot| slot.opted_in()) {
4899                inner.wire_slots.insert(key, slot);
4900            }
4901            if retain_late_route_open {
4902                inner.pending.get_mut(&key).unwrap().route_open_module =
4903                    serde_json::from_slice::<serde_json::Value>(&frame.body)
4904                        .ok()
4905                        .and_then(|body| {
4906                            body.get("target")?
4907                                .get("module_id")?
4908                                .as_str()
4909                                .map(str::to_string)
4910                        });
4911            }
4912        }
4913        let mut registration =
4914            PendingRegistration::new(Arc::clone(self), key, retain_late_route_open);
4915        registration.unary_cancel = cancel.clone();
4916
4917        match timeout_at(
4918            deadline,
4919            writer.send(WriteCommand {
4920                frame,
4921                pending: Some(key),
4922            }),
4923        )
4924        .await
4925        {
4926            Ok(Ok(())) => {}
4927            Ok(Err(_)) => {
4928                let accepted = registration.remove_pending().unwrap_or(false);
4929                return Err(classify_failure(
4930                    accepted,
4931                    "writer task closed before accepting request",
4932                    OutcomeUnknownCause::WriterClosed,
4933                ));
4934            }
4935            Err(_) => {
4936                let accepted = registration.remove_pending().unwrap_or(false);
4937                return Err(classify_failure_with_not_sent_cause(
4938                    accepted,
4939                    "call deadline elapsed waiting for writer capacity",
4940                    OutcomeUnknownCause::Deadline,
4941                    NotSentCause::WriterCapacity,
4942                ));
4943            }
4944        }
4945
4946        if let Some(cancel) = cancel {
4947            cancel.activate(key, priority, deadline);
4948            if cancel.requested() {
4949                cancel.cancel().await;
4950            }
4951        }
4952
4953        self.wait_for_reply(registration, rx, deadline).await
4954    }
4955
4956    async fn wait_for_reply(
4957        self: &Arc<Self>,
4958        mut registration: PendingRegistration,
4959        rx: oneshot::Receiver<PendingResult>,
4960        deadline: Instant,
4961    ) -> Result<TerminalFrame, CallError> {
4962        let key = registration.key;
4963        let channel = key.channel;
4964        // After writer handoff, settle_pending, a connection drop or close_sync may already
4965        // have removed the entry and still be settling it. Its absence cannot prove that the
4966        // request was not written, so a missing entry is classified as possibly written.
4967        tokio::select! {
4968            result = timeout_at(deadline, rx) => match result {
4969                Ok(Ok(result)) => {
4970                    registration.disarm();
4971                    result.into_call_result()
4972                }
4973                Ok(Err(_)) => {
4974                    // The entry was settled without a result, so the request may already
4975                    // have been written: report the outcome as unknown, never `NotSent`.
4976                    registration.disarm();
4977                    Err(CallError::outcome_unknown(
4978                        "pending response channel closed",
4979                        OutcomeUnknownCause::CompletionFailed,
4980                    ))
4981                }
4982                Err(_) => {
4983                    let accepted = if registration.retain_on_drop {
4984                        registration.disarm();
4985                        self.pending_accepted(key).unwrap_or(true)
4986                    } else {
4987                        registration.remove_pending().unwrap_or(true)
4988                    };
4989                    if accepted {
4990                        // Removing the pending entry prevents an explicit cancel
4991                        // from queueing afterward. If it won that race, its sent
4992                        // state is already visible and the deadline sends nothing.
4993                        let cancel_sent = registration.unary_cancel.as_ref().is_some_and(|cancel| cancel.sent());
4994                        if !cancel_sent && self.lock_inner().wire_slots.contains_key(&key) {
4995                            self.send_cancel(RouteHandle::new(key.channel, key.epoch, key.generation), key.corr, Priority::Interactive);
4996                        }
4997                        self.spawn_liveness_probe();
4998                    }
4999                    Err(classify_failure(
5000                        accepted,
5001                        format!("request on channel {channel} timed out at its deadline"),
5002                        OutcomeUnknownCause::Deadline,
5003                    ))
5004                }
5005            },
5006            () = self.close_token.cancelled() => {
5007                let accepted = registration.remove_pending().unwrap_or(true);
5008                Err(classify_failure(accepted, "consumer closed while request was pending", OutcomeUnknownCause::ConsumerClosed))
5009            }
5010        }
5011    }
5012
5013    /// Probe a connection retained after an accepted request reaches its reply deadline.
5014    ///
5015    /// Deadline timeouts deliberately keep a connection because scheduler pressure can delay
5016    /// an otherwise healthy reply. A channel-0 Ping plus any later inbound frame separates that
5017    /// case from a half-open socket, which would otherwise pin every subsequent request.
5018    fn spawn_liveness_probe(self: &Arc<Self>) {
5019        if self.liveness_probe_running.swap(true, Ordering::AcqRel) {
5020            return;
5021        }
5022
5023        let allocation = {
5024            let mut inner = self.lock_inner();
5025            // A pending CHANNEL-0 request suspends the probe: the daemon's
5026            // connection loop is FIFO and some channel-0 handlers park it
5027            // inline for seconds (route.open awaits the module bind ack for up
5028            // to route_bind_relay_timeout, ~12s in production), during which
5029            // our Ping sits unread in the daemon's socket buffer. Silence is
5030            // then explained by our own control op, and convicting would tear
5031            // down a healthy connection mid-bind. The gate is local knowledge
5032            // (we always know our own pendings) and re-arms on the next
5033            // deadline settle; the same check runs again before conviction.
5034            let control_pending = inner
5035                .pending
5036                .keys()
5037                .any(|key| key.generation == inner.generation && key.channel == 0);
5038            if inner.closed || control_pending || !matches!(&inner.reconnect, ReconnectState::Idle)
5039            {
5040                None
5041            } else {
5042                match (inner.next_corr, inner.writer.clone()) {
5043                    (Some(corr), Some(writer)) => {
5044                        inner.next_corr = corr.checked_add(1);
5045                        Some((inner.generation, corr, writer))
5046                    }
5047                    (None, _) | (_, None) => None,
5048                }
5049            }
5050        };
5051        let Some((generation, corr, writer)) = allocation else {
5052            self.liveness_probe_running.store(false, Ordering::Release);
5053            return;
5054        };
5055
5056        let t0 = epoch_millis();
5057        let ping = match Frame::build(
5058            FrameType::Ping,
5059            Flags::new(false, Priority::Interactive, false),
5060            0,
5061            0,
5062            corr,
5063            Vec::new(),
5064        ) {
5065            Ok(ping) => ping,
5066            Err(_) => {
5067                self.liveness_probe_running.store(false, Ordering::Release);
5068                return;
5069            }
5070        };
5071        let window = self.opts.liveness_probe_window;
5072        let shared = Arc::clone(self);
5073        tokio::spawn(async move {
5074            let window_end = Instant::now() + window;
5075            // A write failure proves nothing in the healthy direction: it may be the
5076            // first sign of the same broken transport. Let the inbound window decide.
5077            let _ = timeout_at(
5078                window_end,
5079                writer.send(WriteCommand {
5080                    frame: ping,
5081                    pending: None,
5082                }),
5083            )
5084            .await;
5085            sleep_until(window_end).await;
5086
5087            let control_pending_now = {
5088                let inner = shared.lock_inner();
5089                inner
5090                    .pending
5091                    .keys()
5092                    .any(|key| key.generation == generation && key.channel == 0)
5093            };
5094            if !shared.close_token.is_cancelled()
5095                && !control_pending_now // a control op begun during the window explains the silence
5096                && shared.generation_is_current(generation)
5097                && shared.last_inbound_ms.load(Ordering::Acquire) < t0
5098            {
5099                shared.handle_generation_drop(
5100                    generation,
5101                    format!(
5102                        "liveness probe convicted a half-open socket: no inbound frame for {}ms after a channel-0 Ping",
5103                        window.as_millis()
5104                    ),
5105                );
5106            }
5107            shared
5108                .liveness_probe_running
5109                .store(false, Ordering::Release);
5110        });
5111    }
5112
5113    async fn send_subscription(
5114        self: &Arc<Self>,
5115        subscription: SubscriptionSend,
5116    ) -> Result<Subscription, CallError> {
5117        let SubscriptionSend {
5118            expected_handle,
5119            channel,
5120            epoch,
5121            body,
5122            priority,
5123            admission_class,
5124            event_buffer,
5125            deadline,
5126            permit,
5127        } = subscription;
5128        if Instant::now() >= deadline {
5129            return Err(CallError::not_sent(
5130                "subscription deadline elapsed before request was sent",
5131            ));
5132        }
5133        let (generation, corr, writer) = {
5134            let mut inner = self.lock_inner();
5135            if inner.closed {
5136                return Err(CallError::not_sent("consumer closed"));
5137            }
5138            let generation = inner.generation;
5139            if let Some(expected) = expected_handle {
5140                if expected.connection_token() != generation
5141                    || expected.channel != channel
5142                    || expected.epoch != epoch
5143                    || inner.route_epochs.get(&channel) != Some(&expected)
5144                    || inner.retired_routes.contains(&expected)
5145                {
5146                    return Err(CallError::StaleRouteHandle(expected));
5147                }
5148            }
5149            let Some(writer) = inner.writer.clone() else {
5150                return Err(CallError::not_sent("subc connection is down before send"));
5151            };
5152            let Some(corr) = inner.next_corr else {
5153                drop(inner);
5154                self.handle_generation_drop(
5155                    generation,
5156                    "correlation allocator exhausted".to_string(),
5157                );
5158                return Err(CallError::not_sent(
5159                    "correlation allocator exhausted; connection closed",
5160                ));
5161            };
5162            inner.next_corr = corr.checked_add(1);
5163            (generation, corr, writer)
5164        };
5165
5166        // Mark held subscriptions so module drains leave them out of the quiescence wait.
5167        let frame = Frame::build(
5168            FrameType::Request,
5169            Flags(
5170                Flags::new(false, priority, false)
5171                    .with_admission_class(admission_class)
5172                    .0
5173                    | FLAG_SUBSCRIPTION,
5174            ),
5175            channel,
5176            epoch,
5177            corr,
5178            body,
5179        )
5180        .map_err(|err| CallError::not_sent(format!("failed to build request frame: {err}")))?;
5181        let key = PendingKey {
5182            generation,
5183            channel,
5184            epoch,
5185            corr,
5186        };
5187        let position = Arc::new(SubscriptionPosition {
5188            key: Mutex::new(key),
5189            stop: CancellationToken::new(),
5190        });
5191        let retry = permit.opted_in().then(|| SubscriptionRetry {
5192            frame: frame.clone(),
5193            deadline,
5194            delay: Duration::from_millis(25),
5195            position: Arc::clone(&position),
5196        });
5197        let (events_tx, events_rx) = mpsc::channel(event_buffer.max(1));
5198        let (closed_tx, closed_rx) = oneshot::channel();
5199        let (ended_tx, ended_rx) = watch::channel(None);
5200        {
5201            let mut inner = self.lock_inner();
5202            if inner.closed || inner.generation != generation || inner.writer.is_none() {
5203                return Err(CallError::not_sent(
5204                    "connection changed before subscription registration",
5205                ));
5206            }
5207            if let Some(expected) = expected_handle {
5208                if inner.route_epochs.get(&expected.channel) != Some(&expected)
5209                    || inner.retired_routes.contains(&expected)
5210                {
5211                    return Err(CallError::StaleRouteHandle(expected));
5212                }
5213            }
5214            if permit.opted_in() {
5215                inner.wire_slots.insert(key, Arc::clone(&permit));
5216            }
5217            let mut entry =
5218                PendingEntry::subscription(events_tx, closed_tx, ended_tx, permit, priority);
5219            entry.retry = retry;
5220            inner.pending.insert(key, entry);
5221        }
5222        let mut registration = PendingRegistration::new(Arc::clone(self), key, false);
5223
5224        match timeout_at(
5225            deadline,
5226            writer.send(WriteCommand {
5227                frame,
5228                pending: Some(key),
5229            }),
5230        )
5231        .await
5232        {
5233            Ok(Ok(())) => {}
5234            Ok(Err(_)) => {
5235                let accepted = registration.remove_pending().unwrap_or(false);
5236                return Err(classify_failure(
5237                    accepted,
5238                    "writer task closed before accepting subscription request",
5239                    OutcomeUnknownCause::WriterClosed,
5240                ));
5241            }
5242            Err(_) => {
5243                let accepted = registration.remove_pending().unwrap_or(false);
5244                return Err(classify_failure_with_not_sent_cause(
5245                    accepted,
5246                    "subscription deadline elapsed waiting for writer capacity",
5247                    OutcomeUnknownCause::Deadline,
5248                    NotSentCause::WriterCapacity,
5249                ));
5250            }
5251        }
5252
5253        registration.disarm();
5254        Ok(Subscription {
5255            events: events_rx,
5256            closed: SubscriptionClosed { rx: closed_rx },
5257            ended: ended_rx,
5258            cancel: SubscriptionCancel::new(Arc::clone(self), position, priority),
5259        })
5260    }
5261
5262    fn unsubscribe_subscription(
5263        &self,
5264        position: &SubscriptionPosition,
5265        priority: Priority,
5266    ) -> Result<(), CallError> {
5267        let key = *position.key.lock().unwrap_or_else(|err| err.into_inner());
5268        let handle = RouteHandle::new(key.channel, key.epoch, key.generation);
5269        self.validate_current_handle(handle)?;
5270        let (key, entry) = {
5271            let mut inner = self.lock_inner();
5272            let key = *position.key.lock().unwrap_or_else(|err| err.into_inner());
5273            position.stop.cancel();
5274            let entry = inner.pending.remove(&key);
5275            if entry.as_ref().is_some_and(|entry| !entry.accepted) {
5276                if let Some(slot) = inner.wire_slots.remove(&key) {
5277                    slot.release();
5278                }
5279            }
5280            // Keep retired-route ingress until its advisory Cancel is queued.
5281            (key, entry)
5282        };
5283        if let Some(entry) = entry {
5284            let should_cancel = entry.accepted || entry.retry.is_none();
5285            entry.settle_subscription_result(Ok(()));
5286            if should_cancel {
5287                self.send_cancel(handle, key.corr, priority);
5288            }
5289            self.lock_inner().reap_retired_route(handle);
5290        }
5291        Ok(())
5292    }
5293
5294    fn route_stream_data(&self, key: PendingKey, body: Vec<u8>) {
5295        let overflow = {
5296            let mut inner = self.lock_inner();
5297            let Some(entry) = inner.pending.get(&key) else {
5298                return;
5299            };
5300            match entry.try_send_stream_data(body) {
5301                Ok(()) | Err(StreamDataDelivery::NotSubscription) => return,
5302                Err(StreamDataDelivery::Full) => {
5303                    let priority = entry
5304                        .subscription_priority()
5305                        .unwrap_or(Priority::Interactive);
5306                    let entry = inner.pending.remove(&key);
5307                    entry.map(|entry| {
5308                        (
5309                            entry,
5310                            priority,
5311                            "subscription event channel filled; reader dropped the stream instead of blocking",
5312                        )
5313                    })
5314                }
5315                Err(StreamDataDelivery::Closed) => {
5316                    let priority = entry
5317                        .subscription_priority()
5318                        .unwrap_or(Priority::Interactive);
5319                    let entry = inner.pending.remove(&key);
5320                    entry.map(|entry| {
5321                        (
5322                            entry,
5323                            priority,
5324                            "subscription event receiver closed before the stream ended",
5325                        )
5326                    })
5327                }
5328            }
5329        };
5330
5331        if let Some((entry, priority, reason)) = overflow {
5332            entry.settle_call_error(CallError::subscription_backpressure(reason));
5333            self.send_cancel(
5334                RouteHandle::new(key.channel, key.epoch, key.generation),
5335                key.corr,
5336                priority,
5337            );
5338            self.lock_inner().reap_retired_route(RouteHandle::new(
5339                key.channel,
5340                key.epoch,
5341                key.generation,
5342            ));
5343        }
5344    }
5345
5346    fn register_push_events(
5347        &self,
5348        handle: RouteHandle,
5349    ) -> Result<mpsc::Receiver<PushEvent>, CallError> {
5350        let (events_tx, events_rx) = mpsc::channel(DEFAULT_PUSH_EVENT_BUFFER);
5351        let mut inner = self.lock_inner();
5352        if inner.closed
5353            || inner.generation != handle.connection_token()
5354            || inner.writer.is_none()
5355            || inner.route_epochs.get(&handle.channel) != Some(&handle)
5356        {
5357            return Err(CallError::StaleRouteHandle(handle));
5358        }
5359        inner.push_event_receivers.insert(handle, events_tx);
5360        Ok(events_rx)
5361    }
5362
5363    fn route_push(&self, handle: RouteHandle, body: Vec<u8>) {
5364        let should_count_drop = {
5365            let mut inner = self.lock_inner();
5366            if inner.closed
5367                || inner.generation != handle.connection_token()
5368                || inner.route_epochs.get(&handle.channel) != Some(&handle)
5369            {
5370                // Deliberately uncounted: a push against a stale epoch or dead
5371                // generation has no live subscriber by definition, and the
5372                // counters below claim delivery loss on LIVE routes only.
5373                return;
5374            }
5375            match inner.push_event_receivers.get(&handle) {
5376                None => DroppedPush::NoReceiver,
5377                Some(events) => match events.try_send(PushEvent { handle, body }) {
5378                    Ok(()) => DroppedPush::Delivered,
5379                    Err(mpsc::error::TrySendError::Closed(_)) => {
5380                        inner.push_event_receivers.remove(&handle);
5381                        DroppedPush::NoReceiver
5382                    }
5383                    // A burst KEEPS the subscription (issue #40). This used to
5384                    // remove the receiver -- documented as loss-signaling via
5385                    // recv()->None -- but the fleet's real push consumers are
5386                    // idempotent wake nudges, where one missed event costs a
5387                    // poll cycle and a lost subscription costs every later wake
5388                    // until a re-register path that history says is where bugs
5389                    // live. Matches control_push below; the drop is counted on
5390                    // its own counter so a too-slow consumer is diagnosable as
5391                    // such rather than filed under "never subscribed".
5392                    Err(mpsc::error::TrySendError::Full(_)) => DroppedPush::ReceiverFull,
5393                },
5394            }
5395        };
5396        match should_count_drop {
5397            DroppedPush::Delivered => {}
5398            DroppedPush::NoReceiver => {
5399                self.pushes_dropped_no_receiver
5400                    .fetch_add(1, Ordering::Relaxed);
5401            }
5402            DroppedPush::ReceiverFull => {
5403                self.pushes_dropped_receiver_full
5404                    .fetch_add(1, Ordering::Relaxed);
5405            }
5406        }
5407    }
5408
5409    /// Deliver a daemon-originated channel-0 control push to the registered
5410    /// consumer receiver, or count the drop. Never blocks the reader.
5411    fn control_push(&self, body: &[u8]) {
5412        let parsed = serde_json::from_slice::<serde_json::Value>(body)
5413            .ok()
5414            .and_then(|value| {
5415                let op = value.get("op")?.as_str()?.to_string();
5416                Some(ControlPush { op, body: value })
5417            });
5418        let delivered = match parsed {
5419            None => false,
5420            Some(push) => {
5421                let mut inner = self.lock_inner();
5422                inner.record_route_end(&push);
5423                match inner.control_push_receiver.as_ref() {
5424                    None => false,
5425                    Some(sender) => match sender.try_send(push) {
5426                        Ok(()) => true,
5427                        Err(mpsc::error::TrySendError::Closed(_)) => {
5428                            inner.control_push_receiver = None;
5429                            false
5430                        }
5431                        Err(mpsc::error::TrySendError::Full(_)) => false,
5432                    },
5433                }
5434            }
5435        };
5436        if !delivered {
5437            self.control_pushes_dropped.fetch_add(1, Ordering::Relaxed);
5438        }
5439    }
5440
5441    fn send_cancel(&self, handle: RouteHandle, corr: u64, priority: Priority) {
5442        let writer = {
5443            let inner = self.lock_inner();
5444            if inner.closed
5445                || inner.generation != handle.connection_token()
5446                || !route_is_installed(&inner, handle)
5447            {
5448                return;
5449            }
5450            inner.writer.clone()
5451        };
5452        let Some(writer) = writer else {
5453            return;
5454        };
5455        let Ok(frame) = Frame::build(
5456            FrameType::Cancel,
5457            Flags::new(false, priority, false),
5458            handle.channel,
5459            handle.epoch,
5460            corr,
5461            Vec::new(),
5462        ) else {
5463            return;
5464        };
5465        let _ = writer.try_send(WriteCommand {
5466            frame,
5467            pending: None,
5468        });
5469    }
5470
5471    fn mark_pending_accepted(&self, key: PendingKey) -> bool {
5472        let mut inner = self.lock_inner();
5473        if inner.closed || inner.generation != key.generation {
5474            return false;
5475        }
5476        let Some(entry) = inner.pending.get_mut(&key) else {
5477            return false;
5478        };
5479        if entry
5480            .send_deadline
5481            .is_some_and(|deadline| Instant::now() >= deadline)
5482        {
5483            let entry = inner.remove_pending(&key).unwrap();
5484            drop(inner);
5485            entry.settle_call_error(CallError::not_sent_with_cause(
5486                "call deadline elapsed before request was sent",
5487                NotSentCause::WriterRejected,
5488            ));
5489            return false;
5490        }
5491        entry.accepted = true;
5492        true
5493    }
5494
5495    fn settle_pending(self: &Arc<Self>, key: PendingKey, terminal: PendingTerminal) {
5496        let (entry, retry) = {
5497            let mut inner = self.lock_inner();
5498            let entry = inner.remove_pending(&key);
5499            let slot = inner.wire_slots.remove(&key);
5500            let busy = matches!(&terminal, PendingTerminal::Error { body, flags }
5501                if error_codes::is_route_busy_retryable(*flags, &body.code, slot.as_ref().is_some_and(|slot| slot.opted_in())))
5502                && entry
5503                    .as_ref()
5504                    .is_some_and(|entry| !entry.completion_is_closed());
5505            if let Some(slot) = slot {
5506                if !busy {
5507                    slot.release();
5508                }
5509            }
5510            if busy && entry.as_ref().is_some_and(|entry| entry.retry.is_some()) {
5511                let mut entry = entry.unwrap();
5512                entry.accepted = false;
5513                let retry = entry.retry.clone();
5514                inner.pending.insert(key, entry);
5515                (None, retry)
5516            } else {
5517                inner.reap_retired_route(RouteHandle::new(key.channel, key.epoch, key.generation));
5518                (entry, None)
5519            }
5520        };
5521        if let Some(retry) = retry {
5522            let shared = Arc::clone(self);
5523            tokio::spawn(async move {
5524                shared.retry_subscription(key, retry, terminal).await;
5525            });
5526            return;
5527        }
5528        let Some(entry) = entry else {
5529            return;
5530        };
5531        if entry.retain_late_route_open && entry.completion_is_closed() {
5532            if let PendingTerminal::Response {
5533                generation, body, ..
5534            } = &terminal
5535            {
5536                if let Ok(ClientControlResponse::RouteOpen {
5537                    route_channel,
5538                    route_epoch,
5539                    ..
5540                }) = serde_json::from_slice::<ClientControlResponse>(body)
5541                {
5542                    let handle = RouteHandle::new(route_channel, route_epoch, *generation);
5543                    self.send_route_goodbye(handle, true);
5544                    self.uninstall_route_handle(handle);
5545                }
5546            }
5547            return;
5548        }
5549        entry.settle_terminal(terminal);
5550    }
5551
5552    fn pending_accepted(&self, key: PendingKey) -> Option<bool> {
5553        self.lock_inner()
5554            .pending
5555            .get(&key)
5556            .map(|entry| entry.accepted)
5557    }
5558
5559    fn handle_generation_drop(self: &Arc<Self>, generation: u64, reason: String) {
5560        self.handle_generation_drop_with_cause(
5561            generation,
5562            reason,
5563            OutcomeUnknownCause::ConnectionFailed,
5564        );
5565    }
5566
5567    fn handle_generation_drop_with_cause(
5568        self: &Arc<Self>,
5569        generation: u64,
5570        reason: String,
5571        cause: OutcomeUnknownCause,
5572    ) {
5573        let (should_emit, pending, callbacks) = {
5574            let mut inner = self.lock_inner();
5575            if inner.closed || inner.generation != generation || inner.writer.is_none() {
5576                return;
5577            }
5578            inner.writer = None;
5579            inner.restored_token = inner.restored_token.saturating_add(1);
5580            inner.close_routes();
5581            inner.route_epochs.clear();
5582            inner.route_modules.clear();
5583            inner.route_end_reasons.clear();
5584            inner.legacy_channel_reasons.clear();
5585            let pending = drain_pending_generation(&mut inner.pending, generation);
5586            // An opening belongs to its lead caller, not to a socket generation:
5587            // the caller may still be retrying after this transport is replaced.
5588            // Keep its waiters and close flag until its OpeningGuard finishes, so
5589            // a new caller cannot start a competing open for the same key.
5590            let callbacks = inner.callbacks.clone();
5591            (true, pending, callbacks)
5592        };
5593
5594        if should_emit {
5595            settle_route_pending_entries_with_cause(
5596                pending,
5597                reason.clone(),
5598                RouteEndReason::ConnectionLost,
5599                cause,
5600            );
5601            emit_callbacks(callbacks, ConnectionState::Dropped);
5602            self.notify.notify_waiters();
5603            let _ = self.spawn_reconnect(generation);
5604        }
5605    }
5606
5607    fn close_sync(&self, reason: &str) {
5608        let (pending, openings, routes, reader, writer, reconnect) = {
5609            let mut inner = self.lock_inner();
5610            if inner.closed {
5611                return;
5612            }
5613            inner.closed = true;
5614            // Disconnect releases every daemon route, including retirements
5615            // whose GOODBYEs are still waiting for writer capacity. Preserve
5616            // the best-effort shutdown send for retirements not yet reaped.
5617            let retirements = inner
5618                .retirement_goodbyes
5619                .iter()
5620                .copied()
5621                .collect::<Vec<_>>();
5622            for handle in retirements {
5623                inner.queue_retirement_goodbye(handle);
5624            }
5625            inner.writer = None;
5626            inner.route_epochs.clear();
5627            inner.route_modules.clear();
5628            inner.route_end_reasons.clear();
5629            inner.legacy_channel_reasons.clear();
5630            inner.push_event_receivers.clear();
5631            self.close_token.cancel();
5632            let reconnect = match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
5633                ReconnectState::Background { task, .. } => Some(task),
5634                ReconnectState::Idle | ReconnectState::Inline { .. } => None,
5635            };
5636            (
5637                inner
5638                    .pending
5639                    .drain()
5640                    .map(|(_, entry)| entry)
5641                    .collect::<Vec<_>>(),
5642                inner
5643                    .openings
5644                    .drain()
5645                    .map(|(_, opening)| opening.waiters)
5646                    .collect::<Vec<_>>(),
5647                inner.drain_routes(),
5648                inner.reader_task.take(),
5649                inner.writer_task.take(),
5650                reconnect,
5651            )
5652        };
5653        for route in routes {
5654            route.close();
5655        }
5656        if let Some(handle) = reader {
5657            handle.abort();
5658        }
5659        if let Some(mut handle) = writer {
5660            // Let already queued GOODBYEs reach the socket, but never leave
5661            // a writer blocked on an unresponsive peer alive after close.
5662            if let Ok(runtime) = tokio::runtime::Handle::try_current() {
5663                runtime.spawn(async move {
5664                    if tokio::time::timeout(Duration::from_millis(250), &mut handle)
5665                        .await
5666                        .is_err()
5667                    {
5668                        handle.abort();
5669                    }
5670                });
5671            } else {
5672                handle.abort();
5673            }
5674        }
5675        if let Some(handle) = reconnect {
5676            handle.abort();
5677        }
5678        settle_pending_entries(pending, reason.to_string());
5679        fail_openings(openings, SharedCallFailure::not_sent(reason.to_string()));
5680        self.notify.notify_waiters();
5681    }
5682
5683    fn validate_current_handle(&self, handle: RouteHandle) -> Result<(), CallError> {
5684        let inner = self.lock_inner();
5685        if inner.closed
5686            || inner.generation != handle.connection_token()
5687            || inner.writer.is_none()
5688            || !route_is_installed(&inner, handle)
5689        {
5690            Err(CallError::StaleRouteHandle(handle))
5691        } else {
5692            Ok(())
5693        }
5694    }
5695
5696    fn route_state(&self, handle: RouteHandle) -> Result<RouteState, CallError> {
5697        let inner = self.lock_inner();
5698        if inner.closed
5699            || inner.generation != handle.connection_token()
5700            || inner.writer.is_none()
5701            || inner.route_epochs.get(&handle.channel) != Some(&handle)
5702        {
5703            return Err(CallError::StaleRouteHandle(handle));
5704        }
5705
5706        let route = inner
5707            .route_by_channel
5708            .get(&handle.channel)
5709            .and_then(|key| inner.routes.get(key))
5710            .or_else(|| inner.one_shot_routes.get(&handle.channel));
5711        debug_assert!(route.is_none_or(|route| route.handle == handle));
5712        route
5713            .filter(|route| route.handle == handle)
5714            .cloned()
5715            .ok_or(CallError::StaleRouteHandle(handle))
5716    }
5717
5718    fn route_is_current(&self, key: &RouteKey, route: &RouteState) -> bool {
5719        let inner = self.lock_inner();
5720        if inner.closed
5721            || inner.generation != route.handle.connection_token()
5722            || inner.writer.is_none()
5723        {
5724            return false;
5725        }
5726        inner.routes.get(key).is_some_and(|cached| {
5727            cached.handle == route.handle && Arc::ptr_eq(&cached.sem, &route.sem)
5728        })
5729    }
5730
5731    fn invalidate_route(&self, key: &RouteKey, expected_handle: Option<RouteHandle>) {
5732        self.invalidate_route_with_deadline(key, expected_handle, false);
5733    }
5734
5735    /// An accepted call's response deadline cannot prove non-delivery, so it
5736    /// must not trigger a resend. Retiring its route instead lets the next call
5737    /// recover even when the connection-wide Ping still succeeds. A module that
5738    /// is merely slower than the deadline makes the next call open a fresh
5739    /// route. Calls already pending on the retired route still receive their
5740    /// replies until they settle.
5741    fn invalidate_route_with_deadline(
5742        &self,
5743        key: &RouteKey,
5744        expected_handle: Option<RouteHandle>,
5745        response_deadline_expired: bool,
5746    ) {
5747        let removed = {
5748            let mut inner = self.lock_inner();
5749            match inner.routes.get(key) {
5750                Some(route) if expected_handle.is_none_or(|expected| expected == route.handle) => {
5751                    let removed = inner.evict_route(key);
5752                    if let Some(route) = &removed {
5753                        // Eviction stops new calls, but siblings may already be
5754                        // executing or awaiting their own refusal. Keep ingress
5755                        // until those pending entries settle; never resend them
5756                        // merely because another call was refused.
5757                        inner.retired_routes.insert(route.handle);
5758                        if response_deadline_expired {
5759                            inner.retirement_goodbyes.insert(route.handle);
5760                            // Closing this route releases slots retained for outstanding calls.
5761                            // A module that never answers must not block the route's GOODBYE.
5762                            inner.release_wire_slots(route.handle);
5763                            let pending_calls = inner
5764                                .pending
5765                                .keys()
5766                                .filter(|pending| {
5767                                    pending.generation == route.handle.connection_token()
5768                                        && pending.channel == route.handle.channel
5769                                        && pending.epoch == route.handle.epoch
5770                                })
5771                                .count();
5772                            tracing::warn!(
5773                                target_module = %key.target_label(),
5774                                channel = route.handle.channel,
5775                                epoch = route.handle.epoch,
5776                                pending_calls,
5777                                "retiring route after call response deadline"
5778                            );
5779                        }
5780                        inner.reap_retired_route(route.handle);
5781                    }
5782                    removed
5783                }
5784                _ => None,
5785            }
5786        };
5787        if let Some(route) = removed {
5788            route.close();
5789        }
5790    }
5791
5792    fn finish_opening(&self, key: &RouteKey, result: Result<RouteState, SharedCallFailure>) {
5793        let opening = self.lock_inner().openings.remove(key);
5794        for waiter in opening.map(|o| o.waiters).unwrap_or_default() {
5795            let _ = waiter.send(result.clone());
5796        }
5797    }
5798
5799    async fn close_handle(
5800        self: &Arc<Self>,
5801        handle: RouteHandle,
5802        opts: &CloseRouteOptions,
5803    ) -> Result<(), CallError> {
5804        self.validate_current_handle(handle)?;
5805        let route = {
5806            let mut inner = self.lock_inner();
5807            inner.route_end_reasons.insert(
5808                handle.channel,
5809                (RouteEndReason::ClosedByCaller.into(), true),
5810            );
5811            inner.remove_route_by_handle(handle)
5812        };
5813        let mut closing = RouteCloseGuard::new(
5814            Arc::clone(self),
5815            handle,
5816            route,
5817            "route closed by close_handle",
5818        );
5819        if opts.drain {
5820            self.drain_channel(handle, opts.drain_timeout).await;
5821        }
5822        closing.close_pending();
5823        self.queue_route_goodbye(handle).await;
5824        closing.finish();
5825        Ok(())
5826    }
5827
5828    /// Tear down one route by key. See [`SubcConsumer::close_route`].
5829    async fn close_route(self: &Arc<Self>, key: &RouteKey, opts: &CloseRouteOptions) {
5830        // Under the lock: flip the close-beats-reopen flag on any in-flight open for
5831        // this key (so a lead-opener whose channel hasn't been cached yet refuses to
5832        // install it), and remove the cached route if one exists.
5833        let route = {
5834            let mut inner = self.lock_inner();
5835            if let Some(opening) = inner.openings.get_mut(key) {
5836                opening.closed = true;
5837            }
5838            let route = inner.remove_route(key);
5839            if let Some(route) = &route {
5840                inner.route_end_reasons.insert(
5841                    route.handle.channel,
5842                    (RouteEndReason::ClosedByCaller.into(), true),
5843                );
5844            }
5845            route
5846        };
5847
5848        // Nothing cached: either never opened (idempotent no-op) or still opening (the
5849        // racing lead-opener will see the flag and GOODBYE whatever channel it opens).
5850        let Some(route) = route else {
5851            return;
5852        };
5853        let handle = route.handle;
5854        let mut closing = RouteCloseGuard::new(
5855            Arc::clone(self),
5856            handle,
5857            Some(route),
5858            "route closed by close_route",
5859        );
5860
5861        if opts.drain {
5862            // Wait for in-flight UNARY requests on this channel to settle naturally,
5863            // bounded by drain_timeout, before tearing the route down.
5864            self.drain_channel(handle, opts.drain_timeout).await;
5865        }
5866
5867        // Closing the semaphore makes any not-yet-sent acquire() return Err -> the
5868        // caller classifies it NotSent. Already-sent pending requests are settled
5869        // at-most-once (OutcomeUnknown if the writer accepted their bytes).
5870        closing.close_pending();
5871
5872        // Fail pending requests and release their slots before waiting for the
5873        // writer. Keep the ingress handle installed until GOODBYE is queued,
5874        // preventing channel reuse from overtaking the old route's teardown.
5875        self.queue_route_goodbye(handle).await;
5876        closing.finish();
5877    }
5878
5879    fn uninstall_route_handle(&self, handle: RouteHandle) {
5880        let mut inner = self.lock_inner();
5881        inner.release_wire_slots(handle);
5882        inner.retired_routes.remove(&handle);
5883        inner.retirement_goodbyes.remove(&handle);
5884        if inner.route_epochs.get(&handle.channel) == Some(&handle) {
5885            let installed = inner.route_epochs.remove(&handle.channel).unwrap();
5886            inner.route_targets.remove(&handle);
5887            inner.push_event_receivers.remove(&handle);
5888            release_reverse_request_registry(installed);
5889        }
5890    }
5891
5892    fn route_not_sent_error(&self, handle: RouteHandle) -> CallError {
5893        let inner = self.lock_inner();
5894        let reason = if inner.generation != handle.connection_token() || inner.writer.is_none() {
5895            RouteEndReason::ConnectionLost.into()
5896        } else {
5897            inner.route_end(handle.channel)
5898        };
5899        CallError::NotSent(Box::new(NotSentSource {
5900            message: "route flow-control semaphore closed".into(),
5901            cause: NotSentCause::BeforeQueue,
5902            never_forwarded: true,
5903            route_reason: Some(reason),
5904            refusal: None,
5905        }))
5906    }
5907
5908    /// Settle every pending request on this handle as OutcomeUnknown if the writer
5909    /// accepted its bytes, or NotSent otherwise, preserving the route ending cause.
5910    fn fail_channel_pending(
5911        &self,
5912        handle: RouteHandle,
5913        reason: &str,
5914        close_reason: RouteEndReason,
5915    ) {
5916        let entries = {
5917            let mut inner = self.lock_inner();
5918            inner.release_wire_slots(handle);
5919            inner
5920                .route_end_reasons
5921                .insert(handle.channel, (close_reason.clone().into(), true));
5922            drain_pending_handle(&mut inner.pending, handle, true)
5923        };
5924        settle_route_pending_entries(entries, reason.to_string(), close_reason);
5925    }
5926
5927    /// Resolve once every in-flight unary pending on `channel` has settled, or the
5928    /// timeout elapses. Polls the pending map (entries are removed on settle); the
5929    /// volume here is tiny (a route window is small) so a short poll is adequate.
5930    async fn drain_channel(&self, handle: RouteHandle, timeout: Duration) {
5931        let deadline = Instant::now() + timeout;
5932        loop {
5933            let has_inflight = {
5934                let inner = self.lock_inner();
5935                inner.pending.iter().any(|(key, entry)| {
5936                    key.generation == handle.connection_token()
5937                        && key.channel == handle.channel
5938                        && key.epoch == handle.epoch
5939                        && !entry.is_subscription()
5940                })
5941            };
5942            if !has_inflight || Instant::now() >= deadline {
5943                return;
5944            }
5945            sleep(Duration::from_millis(5)).await;
5946        }
5947    }
5948
5949    async fn queue_route_goodbye(self: &Arc<Self>, handle: RouteHandle) {
5950        let frame = Frame::build(
5951            FrameType::Goodbye,
5952            Flags::new(false, Priority::Interactive, false),
5953            handle.channel,
5954            handle.epoch,
5955            0,
5956            Vec::new(),
5957        )
5958        .expect("header-only route GOODBYE is valid");
5959        loop {
5960            let changed = self.notify.notified();
5961            tokio::pin!(changed);
5962            changed.as_mut().enable();
5963            let writer = {
5964                let inner = self.lock_inner();
5965                // A missing writer or changed generation means the connection
5966                // is dead: the daemon releases every route on that connection,
5967                // so no GOODBYE is needed. A removed handle was already closed.
5968                if inner.closed
5969                    || inner.generation != handle.connection_token()
5970                    || inner.route_epochs.get(&handle.channel) != Some(&handle)
5971                {
5972                    return;
5973                }
5974                let Some(writer) = inner.writer.clone() else {
5975                    return;
5976                };
5977                writer
5978            };
5979            // Request deadlines bound other awaited writes, but there is no
5980            // writer-stall timeout: a live connection must admit this teardown
5981            // before its caller can release route budget.
5982            tokio::select! {
5983                result = writer.reserve() => {
5984                    let Ok(permit) = result else {
5985                        self.handle_generation_drop(
5986                            handle.connection_token(),
5987                            "writer closed before route GOODBYE".into(),
5988                        );
5989                        return;
5990                    };
5991                    let inner = self.lock_inner();
5992                    if !inner.closed
5993                        && inner.generation == handle.connection_token()
5994                        && inner.writer.as_ref().is_some_and(|current| current.same_channel(&writer))
5995                        && inner.route_epochs.get(&handle.channel) == Some(&handle)
5996                    {
5997                        permit.send(WriteCommand { frame, pending: None });
5998                    }
5999                    return;
6000                }
6001                _ = &mut changed => {}
6002                _ = self.close_token.cancelled() => return,
6003            }
6004        }
6005    }
6006
6007    /// Queue a header-only route GOODBYE if `handle` is still live on this connection.
6008    /// Late successful route.open cleanup sets `close_on_failure`: orphan prevention then
6009    /// requires closing the connection when the GOODBYE cannot enter the writer queue.
6010    fn send_route_goodbye(self: &Arc<Self>, handle: RouteHandle, close_on_failure: bool) -> bool {
6011        let writer = {
6012            let inner = self.lock_inner();
6013            if inner.closed
6014                || inner.generation != handle.connection_token()
6015                || inner.route_epochs.get(&handle.channel) != Some(&handle)
6016            {
6017                return false;
6018            }
6019            inner.writer.clone()
6020        };
6021        let Some(writer) = writer else {
6022            return false;
6023        };
6024        let Ok(frame) = Frame::build(
6025            FrameType::Goodbye,
6026            Flags::new(false, Priority::Interactive, false),
6027            handle.channel,
6028            handle.epoch,
6029            0,
6030            Vec::new(),
6031        ) else {
6032            return false;
6033        };
6034        if writer
6035            .try_send(WriteCommand {
6036                frame,
6037                pending: None,
6038            })
6039            .is_ok()
6040        {
6041            return true;
6042        }
6043        if close_on_failure {
6044            self.handle_generation_drop(
6045                handle.connection_token(),
6046                "failed to queue late route.open cleanup GOODBYE".to_string(),
6047            );
6048        }
6049        false
6050    }
6051
6052    fn emit_connection_state(&self, state: ConnectionState) {
6053        let callbacks = self.lock_inner().callbacks.clone();
6054        emit_callbacks(callbacks, state);
6055    }
6056}
6057
6058#[derive(Clone, Copy)]
6059enum InstallKind {
6060    Initial,
6061    Reconnect,
6062}
6063
6064enum EnsureAction {
6065    Wait,
6066    Lead {
6067        generation: u64,
6068        stale_task: Option<JoinHandle<()>>,
6069    },
6070}
6071
6072/// The reconnect state is fenced by the generation whose transport failed. A
6073/// newer generation can replace an older attempt, and completion only changes
6074/// the state when its generation still owns the slot.
6075enum ReconnectState {
6076    Idle,
6077    Inline {
6078        generation: u64,
6079    },
6080    Background {
6081        generation: u64,
6082        task: JoinHandle<()>,
6083    },
6084}
6085
6086/// Outcome of the install decision after a route.open response arrives, taken under
6087/// the inner lock so a racing close_route is observed atomically.
6088enum RouteInstall {
6089    /// Install (or reuse) the cached route and return it.
6090    Cached(RouteState),
6091    /// Do not install. `closed` => a close_route won the race (GOODBYE + NotSent);
6092    /// otherwise the generation moved (retry the open).
6093    Discard { closed: bool },
6094}
6095
6096enum RouteOpenAction {
6097    Wait(oneshot::Receiver<Result<RouteState, SharedCallFailure>>),
6098    Lead,
6099}
6100
6101struct RouteOpenParams<'a> {
6102    target: &'a RouteTarget,
6103    identity: &'a BindIdentity,
6104    consumer_identity: &'a Option<ConsumerIdentity>,
6105    consumer_capabilities: &'a Option<Vec<String>>,
6106    /// Already normalized: an empty map is `None` here, as in the route key.
6107    role_versions: &'a Option<BTreeMap<String, String>>,
6108    reverse_requests: &'a ReverseRequestRegistry,
6109    /// The scope every route.open for this key asks to be admitted under, so a
6110    /// reopen after the route drops carries the same selector as the first open.
6111    scope: Option<&'a ScopeSelector>,
6112}
6113
6114struct CallAttemptHistory {
6115    never_forwarded: bool,
6116    sent: bool,
6117}
6118
6119struct RequestSend {
6120    expected_handle: Option<RouteHandle>,
6121    channel: u16,
6122    epoch: u32,
6123    body: Vec<u8>,
6124    binary: bool,
6125    priority: Priority,
6126    admission_class: AdmissionClass,
6127    deadline: Instant,
6128    retain_late_route_open: bool,
6129    route_open_reverse_requests: Option<ReverseRequestRegistry>,
6130}
6131
6132struct SubscriptionSend {
6133    expected_handle: Option<RouteHandle>,
6134    channel: u16,
6135    epoch: u32,
6136    body: Vec<u8>,
6137    priority: Priority,
6138    admission_class: AdmissionClass,
6139    event_buffer: usize,
6140    deadline: Instant,
6141    permit: Arc<RoutePermit>,
6142}
6143
6144struct SubscriptionPosition {
6145    key: Mutex<PendingKey>,
6146    stop: CancellationToken,
6147}
6148
6149#[derive(Clone)]
6150struct SubscriptionRetry {
6151    frame: Frame,
6152    deadline: Instant,
6153    delay: Duration,
6154    position: Arc<SubscriptionPosition>,
6155}
6156
6157struct RouteCloseGuard {
6158    shared: Arc<Shared>,
6159    handle: RouteHandle,
6160    route: Option<RouteState>,
6161    reason: &'static str,
6162    finished: bool,
6163}
6164
6165impl RouteCloseGuard {
6166    fn new(
6167        shared: Arc<Shared>,
6168        handle: RouteHandle,
6169        route: Option<RouteState>,
6170        reason: &'static str,
6171    ) -> Self {
6172        Self {
6173            shared,
6174            handle,
6175            route,
6176            reason,
6177            finished: false,
6178        }
6179    }
6180
6181    fn close_pending(&self) {
6182        if let Some(route) = &self.route {
6183            route.close();
6184        }
6185        self.shared
6186            .fail_channel_pending(self.handle, self.reason, RouteEndReason::ClosedByCaller);
6187    }
6188
6189    fn finish(&mut self) {
6190        self.shared.uninstall_route_handle(self.handle);
6191        self.finished = true;
6192    }
6193}
6194
6195impl Drop for RouteCloseGuard {
6196    fn drop(&mut self) {
6197        if self.finished {
6198            return;
6199        }
6200        // An abandoned drain must not leave requests or their in-flight permits
6201        // waiting on the caller. Retirement owns GOODBYE admission once the close is dropped.
6202        self.close_pending();
6203        let mut inner = self.shared.lock_inner();
6204        if inner.closed
6205            || inner.generation != self.handle.connection_token()
6206            || inner.writer.is_none()
6207            || inner.route_epochs.get(&self.handle.channel) != Some(&self.handle)
6208        {
6209            return;
6210        }
6211        inner.retired_routes.insert(self.handle);
6212        inner.retirement_goodbyes.insert(self.handle);
6213        // Reaping tries synchronous admission first; otherwise the connection's
6214        // FIFO flusher keeps the handle installed until its GOODBYE is queued.
6215        inner.reap_retired_route(self.handle);
6216    }
6217}
6218
6219struct OpeningGuard {
6220    shared: Arc<Shared>,
6221    key: RouteKey,
6222    finished: bool,
6223}
6224
6225impl OpeningGuard {
6226    fn new(shared: Arc<Shared>, key: RouteKey) -> Self {
6227        Self {
6228            shared,
6229            key,
6230            finished: false,
6231        }
6232    }
6233
6234    fn finish(&mut self, result: Result<RouteState, SharedCallFailure>) {
6235        self.shared.finish_opening(&self.key, result);
6236        self.finished = true;
6237    }
6238}
6239
6240impl Drop for OpeningGuard {
6241    fn drop(&mut self) {
6242        if !self.finished {
6243            self.shared.finish_opening(
6244                &self.key,
6245                Err(SharedCallFailure::not_sent(
6246                    "route.open future was cancelled",
6247                )),
6248            );
6249        }
6250    }
6251}
6252
6253struct InlineReconnectGuard {
6254    shared: Arc<Shared>,
6255    generation: u64,
6256    finished: bool,
6257}
6258
6259impl InlineReconnectGuard {
6260    fn new(shared: Arc<Shared>, generation: u64) -> Self {
6261        Self {
6262            shared,
6263            generation,
6264            finished: false,
6265        }
6266    }
6267
6268    fn finish(&mut self) {
6269        self.shared.finish_inline_reconnect(self.generation);
6270        self.finished = true;
6271    }
6272}
6273
6274impl Drop for InlineReconnectGuard {
6275    fn drop(&mut self) {
6276        if !self.finished {
6277            self.shared.finish_inline_reconnect(self.generation);
6278        }
6279    }
6280}
6281
6282#[derive(Clone)]
6283struct RouteState {
6284    handle: RouteHandle,
6285    sem: Arc<Semaphore>,
6286    watch_sem: Option<Arc<Semaphore>>,
6287    opted_in: bool,
6288}
6289
6290#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6291struct RouteKey {
6292    target: RouteTargetKey,
6293    harness: String,
6294    session: String,
6295    consumer_identity: Option<ConsumerIdentityKey>,
6296    consumer_capabilities: Option<ConsumerCapabilitiesKey>,
6297    /// The role versions the route was opened with; `None` for a route that
6298    /// declared none. Part of the key so a legacy route and a versioned one to
6299    /// the same target are never shared: the provider chose its wire shape
6300    /// from these at bind. A `BTreeMap` is already in canonical order.
6301    role_versions: Option<BTreeMap<String, String>>,
6302    /// The scope the route was admitted under; `None` for an unscoped route.
6303    /// Part of the key so a route bound to one session's scope (or one epoch
6304    /// of it) is never reused for another, nor for an unscoped caller.
6305    scope: Option<ScopeKey>,
6306}
6307
6308impl RouteKey {
6309    fn new(
6310        target: &RouteTarget,
6311        identity: &BindIdentity,
6312        consumer_identity: Option<&ConsumerIdentity>,
6313        consumer_capabilities: Option<&[String]>,
6314    ) -> Self {
6315        Self {
6316            target: RouteTargetKey::from(target),
6317            harness: identity.harness.clone(),
6318            session: identity.session.clone(),
6319            consumer_identity: consumer_identity.map(ConsumerIdentityKey::from),
6320            consumer_capabilities: consumer_capabilities.map(ConsumerCapabilitiesKey::from_slice),
6321            role_versions: None,
6322            scope: None,
6323        }
6324    }
6325
6326    fn with_role_versions(mut self, role_versions: Option<&BTreeMap<String, String>>) -> Self {
6327        self.role_versions = role_versions.cloned();
6328        self
6329    }
6330
6331    fn with_scope(mut self, scope: Option<&ScopeSelector>) -> Self {
6332        self.scope = scope.map(ScopeKey::from);
6333        self
6334    }
6335
6336    fn target_label(&self) -> String {
6337        match &self.target {
6338            RouteTargetKey::ToolProvider { module_id } => format!("tool_provider:{module_id}"),
6339            RouteTargetKey::ManagementSurface { module_id } => {
6340                format!("management_surface:{module_id}")
6341            }
6342            RouteTargetKey::InternalService {
6343                module_id,
6344                service_id,
6345            } => format!("internal_service:{module_id}:{service_id}"),
6346        }
6347    }
6348}
6349
6350#[derive(Clone, Hash, PartialEq, Eq)]
6351struct ConsumerIdentityKey {
6352    module_id: String,
6353    launch_nonce: String,
6354}
6355
6356// Hand-written so the launch nonce is never printed. The nonce is the credential
6357// that attributes a connection to a supervised module, and a derived Debug would
6358// write it into any log line or panic message that formats this value. This key sits
6359// inside the route cache key, which is formatted in logs.
6360impl fmt::Debug for ConsumerIdentityKey {
6361    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
6362        f.debug_struct("ConsumerIdentityKey")
6363            .field("module_id", &self.module_id)
6364            .field(
6365                "launch_nonce",
6366                &format_args!("<{} bytes redacted>", self.launch_nonce.len()),
6367            )
6368            .finish()
6369    }
6370}
6371
6372impl From<&ConsumerIdentity> for ConsumerIdentityKey {
6373    fn from(value: &ConsumerIdentity) -> Self {
6374        Self {
6375            module_id: value.module_id.clone(),
6376            launch_nonce: value.launch_nonce.clone(),
6377        }
6378    }
6379}
6380
6381/// Every field of a [`ScopeSelector`], in hashable form.
6382#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6383struct ScopeKey {
6384    /// The owner principal as its JSON encoding. `Principal` is not `Hash`,
6385    /// and matching on its variants here would stop compiling when the
6386    /// protocol crate adds one; the tagged encoding is unique per principal.
6387    owner: String,
6388    scope_ref: String,
6389    scope_epoch: Option<u64>,
6390    bind_proof_digest: Option<[u8; 32]>,
6391}
6392
6393impl From<&ScopeSelector> for ScopeKey {
6394    fn from(value: &ScopeSelector) -> Self {
6395        Self {
6396            owner: serde_json::to_string(&value.owner)
6397                .unwrap_or_else(|_| format!("{:?}", value.owner)),
6398            scope_ref: value.scope_ref.clone(),
6399            scope_epoch: value.scope_epoch,
6400            bind_proof_digest: value
6401                .bind_proof
6402                .as_ref()
6403                .map(|proof| Sha256::digest(proof.as_bytes()).into()),
6404        }
6405    }
6406}
6407
6408#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6409struct ConsumerCapabilitiesKey {
6410    values: Vec<String>,
6411}
6412
6413impl ConsumerCapabilitiesKey {
6414    fn from_slice(values: &[String]) -> Self {
6415        let mut values = values.to_vec();
6416        values.sort();
6417        values.dedup();
6418        Self { values }
6419    }
6420}
6421
6422#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6423enum RouteTargetKey {
6424    ToolProvider {
6425        module_id: String,
6426    },
6427    ManagementSurface {
6428        module_id: String,
6429    },
6430    InternalService {
6431        module_id: String,
6432        service_id: String,
6433    },
6434}
6435
6436impl From<&RouteTarget> for RouteTargetKey {
6437    fn from(value: &RouteTarget) -> Self {
6438        match value {
6439            RouteTarget::ToolProvider { module_id } => Self::ToolProvider {
6440                module_id: module_id.clone(),
6441            },
6442            RouteTarget::ManagementSurface { module_id } => Self::ManagementSurface {
6443                module_id: module_id.clone(),
6444            },
6445            RouteTarget::InternalService {
6446                module_id,
6447                service_id,
6448            } => Self::InternalService {
6449                module_id: module_id.clone(),
6450                service_id: service_id.clone(),
6451            },
6452        }
6453    }
6454}
6455
6456#[derive(Debug, Clone)]
6457struct SharedCallFailure {
6458    kind: FailureKind,
6459}
6460
6461impl SharedCallFailure {
6462    fn not_sent(message: impl Into<String>) -> Self {
6463        CallError::not_sent_with_cause(message, NotSentCause::RouteOpenAbandoned).into()
6464    }
6465
6466    fn into_call_error(self) -> CallError {
6467        match self.kind {
6468            FailureKind::NotSent(source) => CallError::NotSent(Box::new(source)),
6469            FailureKind::OutcomeUnknown(source) => CallError::outcome_unknown_source(source),
6470            FailureKind::DaemonTooOld(daemon_ver) => CallError::DaemonTooOld { daemon_ver },
6471        }
6472    }
6473}
6474
6475impl From<CallError> for SharedCallFailure {
6476    fn from(value: CallError) -> Self {
6477        match value {
6478            CallError::DaemonTooOld { daemon_ver } => Self {
6479                kind: FailureKind::DaemonTooOld(daemon_ver),
6480            },
6481            CallError::NotSent(err) => Self {
6482                kind: FailureKind::NotSent(
6483                    err.downcast_ref::<NotSentSource>()
6484                        .expect("crate-built route.open failure has a typed source")
6485                        .clone(),
6486                ),
6487            },
6488            CallError::OutcomeUnknown(err) => Self {
6489                kind: FailureKind::OutcomeUnknown(
6490                    err.downcast_ref::<OutcomeUnknownSource>()
6491                        .cloned()
6492                        .unwrap_or_else(|| OutcomeUnknownSource {
6493                            message: err.to_string(),
6494                            cause: OutcomeUnknownCause::CompletionFailed,
6495                            route_reason: None,
6496                        }),
6497                ),
6498            },
6499            CallError::Module(body) => Self {
6500                kind: FailureKind::OutcomeUnknown(OutcomeUnknownSource {
6501                    message: format!(
6502                        "unexpected module error during route.open: {} ({})",
6503                        body.code, body.message
6504                    ),
6505                    cause: OutcomeUnknownCause::CompletionFailed,
6506                    route_reason: None,
6507                }),
6508            },
6509            CallError::SubscriptionBackpressure(err) => Self {
6510                kind: FailureKind::OutcomeUnknown(OutcomeUnknownSource {
6511                    message: err.to_string(),
6512                    cause: OutcomeUnknownCause::CompletionFailed,
6513                    route_reason: None,
6514                }),
6515            },
6516            CallError::StaleRouteHandle(handle) => {
6517                CallError::not_sent(format!("stale route handle: {handle:?}")).into()
6518            }
6519            error @ (CallError::CapabilityUnprovided { .. }
6520            | CallError::CapabilityAmbiguous { .. }
6521            | CallError::InvalidCapabilityIdentifier { .. }) => {
6522                CallError::not_sent(error.to_string()).into()
6523            }
6524        }
6525    }
6526}
6527
6528#[derive(Debug, Clone)]
6529enum FailureKind {
6530    NotSent(NotSentSource),
6531    OutcomeUnknown(OutcomeUnknownSource),
6532    DaemonTooOld(String),
6533}
6534
6535#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq)]
6536struct PendingKey {
6537    generation: u64,
6538    channel: u16,
6539    epoch: u32,
6540    corr: u64,
6541}
6542
6543struct PendingEntry {
6544    accepted: bool,
6545    send_deadline: Option<Instant>,
6546    retain_late_route_open: bool,
6547    expected_control_handle: Option<RouteHandle>,
6548    route_open_reverse_requests: Option<ReverseRequestRegistry>,
6549    route_open_module: Option<String>,
6550    retry: Option<SubscriptionRetry>,
6551    completion: PendingCompletion,
6552}
6553
6554enum PendingCompletion {
6555    Unary(oneshot::Sender<PendingResult>),
6556    Subscription {
6557        events: mpsc::Sender<Vec<u8>>,
6558        closed: oneshot::Sender<Result<(), CallError>>,
6559        ended: watch::Sender<Option<SubscriptionEnd>>,
6560        _permit: Arc<RoutePermit>,
6561        priority: Priority,
6562    },
6563}
6564
6565enum StreamDataDelivery {
6566    NotSubscription,
6567    Full,
6568    Closed,
6569}
6570
6571impl PendingEntry {
6572    fn unary(
6573        tx: oneshot::Sender<PendingResult>,
6574        retain_late_route_open: bool,
6575        expected_control_handle: Option<RouteHandle>,
6576        route_open_reverse_requests: Option<ReverseRequestRegistry>,
6577    ) -> Self {
6578        Self {
6579            accepted: false,
6580            send_deadline: None,
6581            retain_late_route_open,
6582            expected_control_handle,
6583            route_open_reverse_requests,
6584            route_open_module: None,
6585            retry: None,
6586            completion: PendingCompletion::Unary(tx),
6587        }
6588    }
6589
6590    fn subscription(
6591        events: mpsc::Sender<Vec<u8>>,
6592        closed: oneshot::Sender<Result<(), CallError>>,
6593        ended: watch::Sender<Option<SubscriptionEnd>>,
6594        permit: Arc<RoutePermit>,
6595        priority: Priority,
6596    ) -> Self {
6597        Self {
6598            accepted: false,
6599            send_deadline: None,
6600            retain_late_route_open: false,
6601            expected_control_handle: None,
6602            route_open_reverse_requests: None,
6603            route_open_module: None,
6604            retry: None,
6605            completion: PendingCompletion::Subscription {
6606                events,
6607                closed,
6608                ended,
6609                _permit: permit,
6610                priority,
6611            },
6612        }
6613    }
6614
6615    fn completion_is_closed(&self) -> bool {
6616        match &self.completion {
6617            PendingCompletion::Unary(tx) => tx.is_closed(),
6618            PendingCompletion::Subscription { closed, .. } => closed.is_closed(),
6619        }
6620    }
6621
6622    fn is_subscription(&self) -> bool {
6623        matches!(&self.completion, PendingCompletion::Subscription { .. })
6624    }
6625
6626    fn subscription_priority(&self) -> Option<Priority> {
6627        match &self.completion {
6628            PendingCompletion::Subscription { priority, .. } => Some(*priority),
6629            PendingCompletion::Unary(_) => None,
6630        }
6631    }
6632
6633    fn try_send_stream_data(&self, body: Vec<u8>) -> Result<(), StreamDataDelivery> {
6634        let PendingCompletion::Subscription { events, .. } = &self.completion else {
6635            return Err(StreamDataDelivery::NotSubscription);
6636        };
6637        events.try_send(body).map_err(|err| match err {
6638            mpsc::error::TrySendError::Full(_) => StreamDataDelivery::Full,
6639            mpsc::error::TrySendError::Closed(_) => StreamDataDelivery::Closed,
6640        })
6641    }
6642
6643    fn settle_terminal(self, terminal: PendingTerminal) {
6644        if let Some(retry) = &self.retry {
6645            retry.position.stop.cancel();
6646        }
6647        match self.completion {
6648            PendingCompletion::Unary(tx) => {
6649                let _ = tx.send(PendingResult::Terminal(terminal));
6650            }
6651            PendingCompletion::Subscription { closed, ended, .. } => {
6652                let (end, result) = match terminal {
6653                    PendingTerminal::Response { body, .. } => {
6654                        (SubscriptionEnd::Response(body), Ok(()))
6655                    }
6656                    PendingTerminal::StreamEnd => (SubscriptionEnd::StreamEnd, Ok(())),
6657                    PendingTerminal::Error { body, flags } => {
6658                        let err = if error_codes::is_route_busy_retryable(
6659                            flags,
6660                            &body.code,
6661                            self.retry.is_some(),
6662                        ) {
6663                            busy_error(&body)
6664                        } else {
6665                            CallError::Module(body.clone())
6666                        };
6667                        (SubscriptionEnd::Error(body.clone()), Err(err))
6668                    }
6669                };
6670                let _ = ended.send(Some(end));
6671                let _ = closed.send(result);
6672            }
6673        }
6674    }
6675
6676    fn settle_failure(self, reason: String) {
6677        if let Some(retry) = &self.retry {
6678            retry.position.stop.cancel();
6679        }
6680        let err = classify_failure(self.accepted, reason, OutcomeUnknownCause::ConsumerClosed);
6681        match self.completion {
6682            PendingCompletion::Unary(tx) => {
6683                let _ = tx.send(PendingResult::CallError(err));
6684            }
6685            PendingCompletion::Subscription { closed, ended, .. } => {
6686                let _ = ended.send(Some(SubscriptionEnd::RouteClosed {
6687                    reason: RouteEndReason::ClosedByCaller,
6688                }));
6689                let _ = closed.send(Err(err));
6690            }
6691        }
6692    }
6693
6694    fn settle_call_error(self, err: CallError) {
6695        if let Some(retry) = &self.retry {
6696            retry.position.stop.cancel();
6697        }
6698        match self.completion {
6699            PendingCompletion::Unary(tx) => {
6700                let _ = tx.send(PendingResult::CallError(err));
6701            }
6702            PendingCompletion::Subscription { closed, ended, .. } => {
6703                let end = if let Some(reason) = err.close_reason() {
6704                    match reason {
6705                        RouteEndReason::ConnectionLost => SubscriptionEnd::ConnectionLost,
6706                        reason => SubscriptionEnd::RouteClosed {
6707                            reason: reason.clone(),
6708                        },
6709                    }
6710                } else if matches!(err, CallError::SubscriptionBackpressure(_)) {
6711                    SubscriptionEnd::Backpressure
6712                } else {
6713                    SubscriptionEnd::ConnectionLost
6714                };
6715                let _ = ended.send(Some(end));
6716                let _ = closed.send(Err(err));
6717            }
6718        }
6719    }
6720
6721    fn settle_subscription_result(self, result: Result<(), CallError>) {
6722        if let Some(retry) = &self.retry {
6723            retry.position.stop.cancel();
6724        }
6725        match self.completion {
6726            PendingCompletion::Subscription { closed, ended, .. } => {
6727                let _ = ended.send(Some(SubscriptionEnd::Cancelled));
6728                let _ = closed.send(result);
6729            }
6730            PendingCompletion::Unary(tx) => {
6731                let _ = tx.send(PendingResult::Failure {
6732                    accepted: self.accepted,
6733                    reason: "subscription cancel matched a unary request".to_string(),
6734                });
6735            }
6736        }
6737    }
6738}
6739
6740struct PendingRegistration {
6741    shared: Arc<Shared>,
6742    key: PendingKey,
6743    active: bool,
6744    retain_on_drop: bool,
6745    unary_cancel: Option<Arc<UnaryCancel>>,
6746}
6747
6748impl PendingRegistration {
6749    fn new(shared: Arc<Shared>, key: PendingKey, retain_on_drop: bool) -> Self {
6750        Self {
6751            shared,
6752            key,
6753            active: true,
6754            retain_on_drop,
6755            unary_cancel: None,
6756        }
6757    }
6758
6759    fn remove_pending(&mut self) -> Option<bool> {
6760        if !self.active {
6761            return None;
6762        }
6763        self.active = false;
6764        self.shared
6765            .lock_inner()
6766            .remove_pending(&self.key)
6767            .map(|entry| entry.accepted)
6768    }
6769
6770    fn disarm(&mut self) {
6771        self.active = false;
6772    }
6773}
6774
6775impl Drop for PendingRegistration {
6776    fn drop(&mut self) {
6777        if self.retain_on_drop {
6778            self.disarm();
6779        } else {
6780            let _ = self.remove_pending();
6781        }
6782    }
6783}
6784
6785enum PendingResult {
6786    Terminal(PendingTerminal),
6787    CallError(CallError),
6788    Failure { accepted: bool, reason: String },
6789}
6790
6791impl PendingResult {
6792    fn into_call_result(self) -> Result<TerminalFrame, CallError> {
6793        match self {
6794            Self::Terminal(terminal) => Ok(terminal.into_terminal_frame()),
6795            Self::CallError(err) => Err(err),
6796            Self::Failure { accepted, reason } => Err(classify_failure(
6797                accepted,
6798                reason,
6799                OutcomeUnknownCause::CompletionFailed,
6800            )),
6801        }
6802    }
6803}
6804
6805enum PendingTerminal {
6806    Response {
6807        generation: u64,
6808        body: Vec<u8>,
6809        flags: Flags,
6810    },
6811    Error {
6812        body: ErrorBody,
6813        flags: Flags,
6814    },
6815    StreamEnd,
6816}
6817
6818impl PendingTerminal {
6819    fn into_terminal_frame(self) -> TerminalFrame {
6820        match self {
6821            Self::Response {
6822                generation,
6823                body,
6824                flags,
6825            } => TerminalFrame::Response {
6826                generation,
6827                body,
6828                flags,
6829            },
6830            Self::Error { body, flags } => TerminalFrame::Error { body, flags },
6831            Self::StreamEnd => TerminalFrame::StreamEnd,
6832        }
6833    }
6834}
6835
6836#[derive(Debug)]
6837enum TerminalFrame {
6838    Response {
6839        generation: u64,
6840        body: Vec<u8>,
6841        flags: Flags,
6842    },
6843    Error {
6844        body: ErrorBody,
6845        flags: Flags,
6846    },
6847    StreamEnd,
6848}
6849
6850struct WriteCommand {
6851    frame: Frame,
6852    pending: Option<PendingKey>,
6853}
6854
6855trait ConsumerStream: AsyncRead + AsyncWrite + Unpin + Send {}
6856impl<T: AsyncRead + AsyncWrite + Unpin + Send> ConsumerStream for T {}
6857
6858struct OpenedConnection {
6859    stream: Box<dyn ConsumerStream>,
6860    daemon_origin_trusted: bool,
6861    daemon_ver: String,
6862}
6863
6864async fn open_connection(
6865    path: &Path,
6866    deadline: Duration,
6867    transport: ConsumerTransport,
6868    operator_candidates: Option<&[PathBuf]>,
6869) -> Result<OpenedConnection, ConsumerError> {
6870    let path = operator_candidates
6871        .map(crate::operator_app::owned_candidate)
6872        .unwrap_or(path);
6873    if transport == ConsumerTransport::Local {
6874        let read =
6875            connection_file::read_for_client_with_local_endpoint(path).map_err(|source| {
6876                ConsumerError::ConnectionFile {
6877                    path: path.to_path_buf(),
6878                    source,
6879                }
6880            })?;
6881        let endpoint = read
6882            .local_endpoint
6883            .ok_or_else(|| ConsumerError::NoEndpoint {
6884                path: path.to_path_buf(),
6885            })?;
6886        let label = match &endpoint {
6887            connection_file::LocalEndpoint::Unix { path } => path.display().to_string(),
6888            connection_file::LocalEndpoint::Pipe { name } => name.clone(),
6889            _ => "unsupported local endpoint".to_owned(),
6890        };
6891        let mut stream =
6892            connect_local(&endpoint)
6893                .await
6894                .map_err(|source| ConsumerError::Connect {
6895                    path: path.to_path_buf(),
6896                    endpoint: label.clone(),
6897                    source,
6898                })?;
6899        authenticate_client(&mut stream, &read.info, deadline)
6900            .await
6901            .map_err(|source| ConsumerError::Auth {
6902                path: path.to_path_buf(),
6903                endpoint: label,
6904                source,
6905            })?;
6906        crate::registration::bind_consumer(&mut stream, deadline)
6907            .await
6908            .map_err(ConsumerError::claim)?;
6909        return Ok(OpenedConnection {
6910            stream,
6911            daemon_origin_trusted: trusts_daemon_origin(&read.info.daemon_ver),
6912            daemon_ver: read.info.daemon_ver,
6913        });
6914    }
6915    let conn =
6916        connection_file::read_for_client(path).map_err(|source| ConsumerError::ConnectionFile {
6917            path: path.to_path_buf(),
6918            source,
6919        })?;
6920    open_connection_with_info(path, &conn, deadline).await
6921}
6922
6923async fn connect_local(
6924    endpoint: &connection_file::LocalEndpoint,
6925) -> io::Result<Box<dyn ConsumerStream>> {
6926    match endpoint {
6927        #[cfg(unix)]
6928        connection_file::LocalEndpoint::Unix { path } => {
6929            Ok(Box::new(tokio::net::UnixStream::connect(path).await?))
6930        }
6931        #[cfg(windows)]
6932        connection_file::LocalEndpoint::Pipe { name } => Ok(Box::new(
6933            tokio::net::windows::named_pipe::ClientOptions::new().open(name)?,
6934        )),
6935        _ => Err(io::Error::new(
6936            io::ErrorKind::Unsupported,
6937            "unsupported local endpoint kind",
6938        )),
6939    }
6940}
6941
6942async fn open_connection_with_info(
6943    path: &Path,
6944    conn: &connection_file::ConnectionInfo,
6945    deadline: Duration,
6946) -> Result<OpenedConnection, ConsumerError> {
6947    let endpoint = conn
6948        .endpoints
6949        .first()
6950        .ok_or_else(|| ConsumerError::NoEndpoint {
6951            path: path.to_path_buf(),
6952        })?;
6953    let endpoint_label = format!("{}:{}", endpoint.host, endpoint.port);
6954    let mut stream = TcpStream::connect(&endpoint_label)
6955        .await
6956        .map_err(|source| ConsumerError::Connect {
6957            path: path.to_path_buf(),
6958            endpoint: endpoint_label.clone(),
6959            source,
6960        })?;
6961    // Consumers send a request and wait for its reply, so there is no following
6962    // write for Nagle to coalesce with -- it can only hold the request back until
6963    // an ACK returns. Both ends of the hop must disable it for either to help.
6964    //
6965    // Dropped rather than logged for the same reason as the module path: no logging
6966    // dependency here, and a socket too broken to take the option fails the
6967    // handshake on the next line with a typed error.
6968    let _ = stream.set_nodelay(true);
6969    authenticate_client(&mut stream, conn, deadline)
6970        .await
6971        .map_err(|source| ConsumerError::Auth {
6972            path: path.to_path_buf(),
6973            endpoint: endpoint_label,
6974            source,
6975        })?;
6976    crate::registration::bind_consumer(&mut stream, deadline)
6977        .await
6978        .map_err(ConsumerError::claim)?;
6979    Ok(OpenedConnection {
6980        stream: Box::new(stream),
6981        daemon_origin_trusted: trusts_daemon_origin(&conn.daemon_ver),
6982        daemon_ver: conn.daemon_ver.clone(),
6983    })
6984}
6985
6986fn dispatch_reverse_request(shared: &Arc<Shared>, frame: Frame, handle: RouteHandle) {
6987    let method = serde_json::from_slice::<serde_json::Value>(&frame.body)
6988        .ok()
6989        .and_then(|body| body.get("method")?.as_str().map(str::to_string));
6990    let method_family = method
6991        .as_deref()
6992        .and_then(|method| method.split('/').next())
6993        .filter(|family| !family.is_empty())
6994        .map(str::to_string);
6995    let handler = method_family.as_deref().and_then(|family| {
6996        route_reverse_request_registry(handle.reverse_request_registry_id())
6997            .ok()?
6998            .handler(family)
6999    });
7000    let generation = handle.connection_token();
7001    let shared = Arc::clone(shared);
7002
7003    tokio::spawn(async move {
7004        let (frame_type, body) = if let (Some(handler), Some(method)) = (handler, method) {
7005            let request_body = frame.body.clone();
7006            let corr = frame.header.corr;
7007            match tokio::spawn(async move {
7008                handler(request_body, ReverseRequestContext { corr, method }).await
7009            })
7010            .await
7011            {
7012                Ok(Ok(body)) => (FrameType::Response, body),
7013                Ok(Err(err)) => (
7014                    FrameType::Error,
7015                    serde_json::to_vec(&ErrorBody::new(REVERSE_REQUEST_UNHANDLED, err.to_string()))
7016                        .unwrap_or_default(),
7017                ),
7018                Err(err) => (
7019                    FrameType::Error,
7020                    serde_json::to_vec(&ErrorBody::new(
7021                        REVERSE_REQUEST_UNHANDLED,
7022                        join_error_message(err),
7023                    ))
7024                    .unwrap_or_default(),
7025                ),
7026            }
7027        } else {
7028            let message = method_family.map_or_else(
7029                || "reverse request has no valid method".to_string(),
7030                |family| format!("no reverse-request handler is registered for {family}"),
7031            );
7032            (
7033                FrameType::Error,
7034                serde_json::to_vec(&ErrorBody::new(REVERSE_REQUEST_UNHANDLED, message))
7035                    .unwrap_or_default(),
7036            )
7037        };
7038
7039        if shared.ingress_handle(generation, handle.channel, handle.epoch) != Some(handle) {
7040            return;
7041        }
7042        let reply = match Frame::build_with_version(
7043            frame.header.ver,
7044            frame_type,
7045            Flags::new(false, Priority::Interactive, false),
7046            handle.channel,
7047            handle.epoch,
7048            frame.header.corr,
7049            body,
7050        ) {
7051            Ok(reply) => reply,
7052            Err(_) => return,
7053        };
7054        let writer = shared.lock_inner().writer.clone();
7055        if let Some(writer) = writer {
7056            let _ = writer
7057                .send(WriteCommand {
7058                    frame: reply,
7059                    pending: None,
7060                })
7061                .await;
7062        }
7063    });
7064}
7065
7066fn join_error_message(error: tokio::task::JoinError) -> String {
7067    if !error.is_panic() {
7068        return error.to_string();
7069    }
7070    let payload = error.into_panic();
7071    if let Some(message) = payload.downcast_ref::<String>() {
7072        return message.clone();
7073    }
7074    if let Some(message) = payload.downcast_ref::<&str>() {
7075        return (*message).to_string();
7076    }
7077    "reverse-request handler panicked".to_string()
7078}
7079
7080async fn reader_loop<R: AsyncRead + Unpin>(shared: Arc<Shared>, mut reader: R, generation: u64) {
7081    loop {
7082        match read_frame(&mut reader).await {
7083            Ok(Some(frame)) => {
7084                if !dispatch_frame(&shared, generation, frame).await {
7085                    return;
7086                }
7087            }
7088            Ok(None) => {
7089                shared.handle_generation_drop(generation, "subc connection closed".to_string());
7090                return;
7091            }
7092            Err(err) => {
7093                shared.handle_generation_drop(generation, err.to_string());
7094                return;
7095            }
7096        }
7097    }
7098}
7099
7100async fn dispatch_frame(shared: &Arc<Shared>, generation: u64, frame: Frame) -> bool {
7101    if !shared.record_inbound_if_current(generation) {
7102        return false;
7103    }
7104    if frame.header.channel != 0
7105        && !shared.validate_ingress_handle(generation, frame.header.channel, frame.header.epoch)
7106    {
7107        return true;
7108    }
7109
7110    if frame.header.ty == FrameType::Request && frame.header.channel != 0 {
7111        if let Some(handle) =
7112            shared.ingress_handle(generation, frame.header.channel, frame.header.epoch)
7113        {
7114            dispatch_reverse_request(shared, frame, handle);
7115        }
7116        return true;
7117    }
7118
7119    let key = PendingKey {
7120        generation,
7121        channel: frame.header.channel,
7122        epoch: frame.header.epoch,
7123        corr: frame.header.corr,
7124    };
7125
7126    if frame.header.channel == 0 && frame.header.ty == FrameType::Response {
7127        if let Some(expected) = shared.pending_expected_control_handle(key) {
7128            let echoes_expected = matches!(
7129                serde_json::from_slice::<ClientControlResponse>(&frame.body),
7130                Ok(ClientControlResponse::RoutePoll {
7131                    route_channel,
7132                    route_epoch,
7133                    ..
7134                }) if route_channel == expected.channel && route_epoch == expected.epoch
7135            );
7136            if !echoes_expected {
7137                shared.count_dropped_route_frame();
7138                return true;
7139            }
7140        }
7141    }
7142
7143    // A route.open handle is published before its waiter is resolved. The socket reader
7144    // cannot consume a following same-route frame until this synchronous install finishes.
7145    if frame.header.channel == 0
7146        && frame.header.ty == FrameType::Response
7147        && shared.pending_expects_route_open(key)
7148    {
7149        if let Ok((
7150            ClientControlResponse::RouteOpen {
7151                route_channel,
7152                route_epoch,
7153                ..
7154            },
7155            authority,
7156        )) = decode_route_open_response(&frame.body)
7157        {
7158            let reverse_requests = shared
7159                .pending_route_open_reverse_requests(key)
7160                .unwrap_or_default();
7161            let module = shared
7162                .lock_inner()
7163                .pending
7164                .get(&key)
7165                .and_then(|entry| entry.route_open_module.clone());
7166            let handle =
7167                RouteHandle::new_consumer(route_channel, route_epoch, generation, reverse_requests);
7168            shared.install_ingress_handle(handle);
7169            if let Some(target) = authority.target {
7170                let mut inner = shared.lock_inner();
7171                if inner.route_epochs.get(&handle.channel) == Some(&handle) {
7172                    inner.route_targets.insert(handle, target);
7173                }
7174            }
7175            if let Some(module) = module {
7176                shared
7177                    .lock_inner()
7178                    .route_modules
7179                    .insert(route_channel, module);
7180            }
7181        }
7182    }
7183
7184    match frame.header.ty {
7185        FrameType::Response => shared.settle_pending(
7186            key,
7187            PendingTerminal::Response {
7188                generation,
7189                body: frame.body,
7190                flags: frame.header.flags,
7191            },
7192        ),
7193        FrameType::Error => {
7194            let body =
7195                serde_json::from_slice::<ErrorBody>(&frame.body).unwrap_or_else(|err| ErrorBody {
7196                    code: "invalid_error_body".to_string(),
7197                    message: err.to_string(),
7198                    detail: None,
7199                });
7200            shared.settle_pending(
7201                key,
7202                PendingTerminal::Error {
7203                    body,
7204                    flags: frame.header.flags,
7205                },
7206            );
7207        }
7208        FrameType::StreamEnd => shared.settle_pending(key, PendingTerminal::StreamEnd),
7209        FrameType::StreamData => shared.route_stream_data(key, frame.body),
7210        FrameType::Push if frame.header.channel == 0 => {
7211            shared.control_push(&frame.body);
7212        }
7213        FrameType::Push => shared.route_push(
7214            RouteHandle::new(frame.header.channel, frame.header.epoch, generation),
7215            frame.body,
7216        ),
7217        FrameType::Goodbye if frame.header.channel == 0 => {
7218            shared.handle_generation_drop(generation, "subc sent GOODBYE".to_string());
7219            return false;
7220        }
7221        FrameType::Goodbye => {
7222            let handle = RouteHandle::new(frame.header.channel, frame.header.epoch, generation);
7223            let close_reason = shared.lock_inner().route_end(handle.channel);
7224            shared.invalidate_routes_for_handle(handle);
7225            let pending = {
7226                let mut inner = shared.lock_inner();
7227                drain_pending_handle(&mut inner.pending, handle, true)
7228            };
7229            settle_route_pending_entries(pending, "route closed by subc".to_string(), close_reason);
7230        }
7231        FrameType::Ping if frame.header.channel == 0 => {
7232            if let Ok(pong) = Frame::build_with_version(
7233                frame.header.ver,
7234                FrameType::Pong,
7235                frame.header.flags,
7236                0,
7237                0,
7238                frame.header.corr,
7239                Vec::new(),
7240            ) {
7241                let writer = shared.lock_inner().writer.clone();
7242                if let Some(writer) = writer {
7243                    let _ = writer
7244                        .send(WriteCommand {
7245                            frame: pong,
7246                            pending: None,
7247                        })
7248                        .await;
7249                }
7250            }
7251        }
7252        _ => {}
7253    }
7254    true
7255}
7256
7257impl Shared {
7258    /// Stamp after holding the same state lock that guards generation changes, so a
7259    /// late frame from an older reader can never vouch for a newly installed socket.
7260    ///
7261    /// PLACEMENT IS LOAD-BEARING: the single caller sits on the frame-read
7262    /// return, the one point every inbound frame passes before demux -- which
7263    /// is why one stamp suffices. A future fast path or drain-and-dispatch
7264    /// refactor that hands frames onward without crossing that point makes the
7265    /// stamp skippable, and the liveness watermark quietly stops meaning "the
7266    /// link delivered bytes": the cheapest correctness property in this file
7267    /// and the easiest to lose in a refactor.
7268    fn record_inbound_if_current(&self, generation: u64) -> bool {
7269        let inner = self.lock_inner();
7270        if inner.closed || inner.generation != generation || inner.writer.is_none() {
7271            return false;
7272        }
7273        self.last_inbound_ms
7274            .store(epoch_millis(), Ordering::Release);
7275        true
7276    }
7277
7278    fn generation_is_current(&self, generation: u64) -> bool {
7279        let inner = self.lock_inner();
7280        !inner.closed && inner.generation == generation && inner.writer.is_some()
7281    }
7282
7283    fn pending_expected_control_handle(&self, key: PendingKey) -> Option<RouteHandle> {
7284        self.lock_inner()
7285            .pending
7286            .get(&key)
7287            .and_then(|entry| entry.expected_control_handle)
7288    }
7289
7290    fn count_dropped_route_frame(&self) {
7291        let mut inner = self.lock_inner();
7292        inner.dropped_route_frames = inner.dropped_route_frames.saturating_add(1);
7293    }
7294
7295    fn pending_expects_route_open(&self, key: PendingKey) -> bool {
7296        self.lock_inner()
7297            .pending
7298            .get(&key)
7299            .is_some_and(|entry| entry.retain_late_route_open)
7300    }
7301
7302    fn pending_route_open_reverse_requests(
7303        &self,
7304        key: PendingKey,
7305    ) -> Option<ReverseRequestRegistry> {
7306        self.lock_inner()
7307            .pending
7308            .get(&key)
7309            .and_then(|entry| entry.route_open_reverse_requests.clone())
7310    }
7311
7312    fn ingress_handle(&self, generation: u64, channel: u16, epoch: u32) -> Option<RouteHandle> {
7313        let inner = self.lock_inner();
7314        let handle = inner.route_epochs.get(&channel).copied()?;
7315        (handle.connection_token() == generation && handle.epoch == epoch).then_some(handle)
7316    }
7317
7318    fn validate_ingress_handle(&self, generation: u64, channel: u16, epoch: u32) -> bool {
7319        let mut inner = self.lock_inner();
7320        let expected = RouteHandle::new(channel, epoch, generation);
7321        if inner.route_epochs.get(&channel) == Some(&expected) {
7322            true
7323        } else {
7324            inner.dropped_route_frames = inner.dropped_route_frames.saturating_add(1);
7325            false
7326        }
7327    }
7328
7329    fn install_ingress_handle(&self, handle: RouteHandle) {
7330        let mut inner = self.lock_inner();
7331        if !inner.closed && inner.generation == handle.connection_token() && inner.writer.is_some()
7332        {
7333            inner.route_end_reasons.remove(&handle.channel);
7334            inner.legacy_channel_reasons.remove(&handle.channel);
7335            inner.route_modules.remove(&handle.channel);
7336            if let Some(previous) = inner.route_epochs.insert(handle.channel, handle) {
7337                inner.route_targets.remove(&previous);
7338                if previous.reverse_request_registry_id() != handle.reverse_request_registry_id() {
7339                    release_reverse_request_registry(previous);
7340                }
7341            }
7342        }
7343    }
7344
7345    fn invalidate_routes_for_handle(&self, handle: RouteHandle) {
7346        let removed = {
7347            let mut inner = self.lock_inner();
7348            if inner.route_epochs.get(&handle.channel) != Some(&handle) {
7349                return;
7350            }
7351            inner.release_wire_slots(handle);
7352            let installed = inner.route_epochs.remove(&handle.channel).unwrap();
7353            inner.route_targets.remove(&handle);
7354            inner.retired_routes.remove(&handle);
7355            inner.retirement_goodbyes.remove(&handle);
7356            inner.push_event_receivers.remove(&handle);
7357            release_reverse_request_registry(installed);
7358            inner
7359                .remove_route_by_handle(handle)
7360                .into_iter()
7361                .collect::<Vec<_>>()
7362        };
7363        for route in removed {
7364            route.close();
7365        }
7366    }
7367}
7368
7369async fn retirement_goodbye_loop(shared: Arc<Shared>, generation: u64, notify: Arc<Notify>) {
7370    loop {
7371        let notified = notify.notified();
7372        let next = {
7373            let inner = shared.lock_inner();
7374            if inner.closed || inner.generation != generation || inner.writer.is_none() {
7375                return;
7376            }
7377            inner
7378                .retirement_queue
7379                .front()
7380                .map(|handle| (*handle, inner.writer.as_ref().unwrap().clone()))
7381        };
7382        let Some((handle, writer)) = next else {
7383            notified.await;
7384            continue;
7385        };
7386        let Ok(permit) = writer.reserve().await else {
7387            shared.handle_generation_drop(
7388                generation,
7389                "writer closed before retirement GOODBYE".into(),
7390            );
7391            return;
7392        };
7393        let mut inner = shared.lock_inner();
7394        if inner.closed || inner.generation != generation || inner.writer.is_none() {
7395            return;
7396        }
7397        if inner.retirement_queue.front() != Some(&handle) {
7398            continue;
7399        }
7400        inner.retirement_queue.pop_front();
7401        inner.retirement_goodbyes.remove(&handle);
7402        if inner.route_epochs.get(&handle.channel) == Some(&handle) {
7403            let frame = Frame::build(
7404                FrameType::Goodbye,
7405                Flags::new(false, Priority::Interactive, false),
7406                handle.channel,
7407                handle.epoch,
7408                0,
7409                Vec::new(),
7410            )
7411            .expect("header-only route GOODBYE is valid");
7412            // Queue admission and uninstallation share the lock. No new route
7413            // can claim this channel between those operations.
7414            permit.send(WriteCommand {
7415                frame,
7416                pending: None,
7417            });
7418        }
7419        inner.reap_retired_route(handle);
7420    }
7421}
7422
7423async fn writer_loop<W>(
7424    shared: Arc<Shared>,
7425    writer: W,
7426    mut rx: mpsc::Receiver<WriteCommand>,
7427    generation: u64,
7428) where
7429    W: AsyncWrite + Unpin,
7430{
7431    let mut writer = BufWriter::new(writer);
7432    while let Some(command) = rx.recv().await {
7433        if let Some(key) = command.pending {
7434            if !shared.mark_pending_accepted(key) {
7435                continue;
7436            }
7437        }
7438        if let Err(err) = write_frame(&mut writer, &command.frame).await {
7439            shared.handle_generation_drop_with_cause(
7440                generation,
7441                err.to_string(),
7442                OutcomeUnknownCause::WriterClosed,
7443            );
7444            return;
7445        }
7446        while let Ok(command) = rx.try_recv() {
7447            if let Some(key) = command.pending {
7448                if !shared.mark_pending_accepted(key) {
7449                    continue;
7450                }
7451            }
7452            if let Err(err) = write_frame(&mut writer, &command.frame).await {
7453                shared.handle_generation_drop_with_cause(
7454                    generation,
7455                    err.to_string(),
7456                    OutcomeUnknownCause::WriterClosed,
7457                );
7458                return;
7459            }
7460        }
7461        if let Err(err) = writer.flush().await.map_err(FrameIoError::Io) {
7462            shared.handle_generation_drop_with_cause(
7463                generation,
7464                err.to_string(),
7465                OutcomeUnknownCause::WriterClosed,
7466            );
7467            return;
7468        }
7469    }
7470}
7471
7472impl Shared {
7473    fn implicit_consumer_identity(&self) -> Option<ConsumerIdentity> {
7474        // Operator-app connections must not even consult the launch environment:
7475        // the nonce accessor can consume an inherited credential descriptor.
7476        if self.identity_from_environment && !self.claim_bound {
7477            consumer_identity_from_env()
7478        } else {
7479            None
7480        }
7481    }
7482
7483    fn activity_read_body(&self, request: impl serde::Serialize) -> Result<Vec<u8>, CallError> {
7484        #[derive(serde::Serialize)]
7485        struct ReadRequest<T> {
7486            #[serde(flatten)]
7487            request: T,
7488            #[serde(skip_serializing_if = "Option::is_none")]
7489            consumer_identity: Option<ConsumerIdentity>,
7490        }
7491        serde_json::to_vec(&ReadRequest {
7492            request,
7493            consumer_identity: self.implicit_consumer_identity(),
7494        })
7495        .map_err(|err| CallError::not_sent(format!("failed to encode activity read: {err}")))
7496    }
7497
7498    fn route_open_consumer_identity(
7499        &self,
7500        opts: &CallOptions,
7501    ) -> Result<Option<ConsumerIdentity>, CallError> {
7502        if self.claim_bound && opts.consumer_identity.is_some() {
7503            // Legacy nonce identities cannot describe a claim-bound connection.
7504            return Err(CallError::not_sent(
7505                "consumer identity conflicts with connection binding",
7506            ));
7507        }
7508        Ok(opts
7509            .consumer_identity
7510            .clone()
7511            .or_else(|| self.implicit_consumer_identity()))
7512    }
7513
7514    fn close_route_consumer_identity(
7515        &self,
7516        opts: &CloseRouteOptions,
7517    ) -> Result<Option<ConsumerIdentity>, CallError> {
7518        if self.claim_bound && opts.consumer_identity.is_some() {
7519            return Err(CallError::not_sent(
7520                "consumer identity conflicts with connection binding",
7521            ));
7522        }
7523        Ok(opts
7524            .consumer_identity
7525            .clone()
7526            .or_else(|| self.implicit_consumer_identity()))
7527    }
7528}
7529
7530fn route_open_consumer_capabilities(opts: &CallOptions) -> Option<Vec<String>> {
7531    opts.reverse_requests.seal();
7532    let mut capabilities = opts.reverse_requests.capabilities();
7533    capabilities.extend(opts.consumer_capabilities());
7534    capabilities.sort();
7535    capabilities.dedup();
7536    (!capabilities.is_empty()).then_some(capabilities)
7537}
7538
7539/// The role versions a route is opened and keyed with. An empty map declares
7540/// nothing, and the daemon forwards it as no field at all, so it is folded
7541/// into `None` here: otherwise `Some({})` and `None` would key two routes the
7542/// provider cannot tell apart.
7543fn route_open_role_versions(
7544    role_versions: Option<&BTreeMap<String, String>>,
7545) -> Option<BTreeMap<String, String>> {
7546    role_versions
7547        .filter(|role_versions| !role_versions.is_empty())
7548        .cloned()
7549}
7550
7551fn close_route_consumer_capabilities(opts: &CloseRouteOptions) -> Option<Vec<String>> {
7552    opts.reverse_requests.seal();
7553    let mut capabilities = opts.reverse_requests.capabilities();
7554    capabilities.extend(opts.consumer_capabilities());
7555    capabilities.sort();
7556    capabilities.dedup();
7557    (!capabilities.is_empty()).then_some(capabilities)
7558}
7559
7560fn consumer_identity_from_env() -> Option<ConsumerIdentity> {
7561    let module_id = std::env::var(SUBC_MODULE_ID_ENV)
7562        .ok()
7563        .filter(|value| !value.is_empty())?;
7564    // Through the process's one cached accessor, never a second read of the
7565    // descriptor. An accessor error (for example a process a module spawned,
7566    // which inherits the descriptor variable but not the pipe) opens the
7567    // route without identity: it never falls back to the environment copy,
7568    // because presenting the module's nonce is exactly what such a process
7569    // must no longer be able to do.
7570    let launch_nonce = crate::launch_nonce()
7571        .ok()
7572        .flatten()
7573        .map(|nonce| nonce.value().to_string())?;
7574    Some(ConsumerIdentity {
7575        module_id,
7576        launch_nonce,
7577    })
7578}
7579
7580fn validate_capability_for_resolution(capability: &str) -> Result<(), CallError> {
7581    if is_valid_capability_identifier(capability) {
7582        Ok(())
7583    } else {
7584        Err(CallError::InvalidCapabilityIdentifier {
7585            capability: capability.to_string(),
7586        })
7587    }
7588}
7589
7590fn capability_claimants(catalog: &CatalogList, capability: &str) -> Vec<String> {
7591    let mut claimants = catalog
7592        .modules
7593        .iter()
7594        .filter(|module| {
7595            module.capabilities.as_ref().is_some_and(|capabilities| {
7596                capabilities
7597                    .provides
7598                    .iter()
7599                    .any(|claim| claim == capability)
7600            })
7601        })
7602        .map(|module| module.module_id.clone())
7603        .collect::<Vec<_>>();
7604    claimants.sort();
7605    claimants
7606}
7607
7608fn epoch_millis() -> u64 {
7609    u64::try_from(
7610        SystemTime::now()
7611            .duration_since(UNIX_EPOCH)
7612            .unwrap_or_default()
7613            .as_millis(),
7614    )
7615    .unwrap_or(u64::MAX)
7616}
7617
7618/// Reclassify a route-open failure seen by a managed `call` or `subscribe`.
7619///
7620/// `ensure_route` reports the route.open control request's own outcome, which
7621/// is `OutcomeUnknown` when that request was written but its reply did not
7622/// arrive before the deadline: the daemon may or may not have opened the
7623/// channel. The caller's request body, however, is only written after a route
7624/// is in hand, so when no route came back the body provably never left the
7625/// client. From the caller's point of view that is `NotSent`, and reporting
7626/// `OutcomeUnknown` would wrongly tell it a non-idempotent operation might
7627/// have run. A route.open reply that arrives after its waiter gave up is still
7628/// cleaned up: `settle_pending` sends that channel a GOODBYE instead of caching
7629/// it, so reporting `NotSent` here leaves no route open behind.
7630/// A uniform value in [0, 1) for retry jitter. Jitter needs spread, not
7631/// unpredictability, so this hashes a counter with std's randomly keyed hasher
7632/// instead of taking a dependency on a random-number crate.
7633fn default_random_unit() -> f64 {
7634    use std::hash::{BuildHasher, RandomState};
7635    static COUNTER: AtomicU64 = AtomicU64::new(0);
7636    let bits = RandomState::new().hash_one(COUNTER.fetch_add(1, Ordering::Relaxed));
7637    // The top 53 bits fill an f64 mantissa exactly.
7638    (bits >> 11) as f64 / (1u64 << 53) as f64
7639}
7640
7641fn request_not_sent_after_route_open_failure(err: CallError) -> CallError {
7642    match err {
7643        CallError::OutcomeUnknown(source) => CallError::not_sent_with_cause(
7644            format!("request not sent: route.open did not complete ({source})"),
7645            NotSentCause::RouteOpenAbandoned,
7646        ),
7647        other => other,
7648    }
7649}
7650
7651fn classify_failure(
7652    accepted: bool,
7653    reason: impl Into<String>,
7654    cause: OutcomeUnknownCause,
7655) -> CallError {
7656    classify_failure_with_not_sent_cause(accepted, reason, cause, NotSentCause::WriterRejected)
7657}
7658
7659fn classify_failure_with_not_sent_cause(
7660    accepted: bool,
7661    reason: impl Into<String>,
7662    cause: OutcomeUnknownCause,
7663    not_sent_cause: NotSentCause,
7664) -> CallError {
7665    if accepted {
7666        CallError::outcome_unknown(reason, cause)
7667    } else {
7668        CallError::not_sent_with_cause(reason, not_sent_cause)
7669    }
7670}
7671
7672fn settle_route_pending_entries(
7673    entries: Vec<PendingEntry>,
7674    message: String,
7675    reason: impl Into<RouteEnd>,
7676) {
7677    let reason = reason.into();
7678    let cause = if reason.reason == RouteEndReason::ConnectionLost {
7679        OutcomeUnknownCause::ConnectionFailed
7680    } else {
7681        OutcomeUnknownCause::RouteEnded
7682    };
7683    settle_route_pending_entries_with_cause(entries, message, reason, cause);
7684}
7685
7686fn settle_route_pending_entries_with_cause(
7687    entries: Vec<PendingEntry>,
7688    message: String,
7689    reason: impl Into<RouteEnd>,
7690    cause: OutcomeUnknownCause,
7691) {
7692    let reason = reason.into();
7693    for entry in entries {
7694        let err = if entry.accepted {
7695            CallError::outcome_unknown_source(OutcomeUnknownSource {
7696                message: message.clone(),
7697                cause,
7698                route_reason: Some(reason.clone()),
7699            })
7700        } else {
7701            CallError::NotSent(Box::new(NotSentSource {
7702                message: message.clone(),
7703                cause: NotSentCause::WriterRejected,
7704                never_forwarded: true,
7705                route_reason: Some(reason.clone()),
7706                refusal: None,
7707            }))
7708        };
7709        entry.settle_call_error(err);
7710    }
7711}
7712
7713fn settle_pending_entries(entries: Vec<PendingEntry>, reason: String) {
7714    for entry in entries {
7715        entry.settle_failure(reason.clone());
7716    }
7717}
7718
7719fn drain_pending_generation(
7720    pending: &mut HashMap<PendingKey, PendingEntry>,
7721    generation: u64,
7722) -> Vec<PendingEntry> {
7723    let keys = pending
7724        .keys()
7725        .copied()
7726        .filter(|key| key.generation == generation)
7727        .collect::<Vec<_>>();
7728    keys.into_iter()
7729        .filter_map(|key| pending.remove(&key))
7730        .collect()
7731}
7732
7733fn drain_pending_handle(
7734    pending: &mut HashMap<PendingKey, PendingEntry>,
7735    handle: RouteHandle,
7736    include_subscriptions: bool,
7737) -> Vec<PendingEntry> {
7738    let keys = pending
7739        .iter()
7740        .filter_map(|(key, entry)| {
7741            (key.generation == handle.connection_token()
7742                && key.channel == handle.channel
7743                && key.epoch == handle.epoch
7744                && (include_subscriptions || !entry.is_subscription()))
7745            .then_some(*key)
7746        })
7747        .collect::<Vec<_>>();
7748    keys.into_iter()
7749        .filter_map(|key| pending.remove(&key))
7750        .collect()
7751}
7752
7753fn fail_openings(openings: Vec<Vec<OpeningWaiter>>, failure: SharedCallFailure) {
7754    for waiters in openings {
7755        for waiter in waiters {
7756            let _ = waiter.send(Err(failure.clone()));
7757        }
7758    }
7759}
7760
7761fn emit_callbacks(callbacks: Vec<Callback>, state: ConnectionState) {
7762    for callback in callbacks {
7763        if let Ok(callback) = callback.lock() {
7764            callback(state.clone());
7765        }
7766    }
7767}
7768
7769/// The route-open retry predicate, defined once in `subc_protocol::error_codes`
7770/// so consumers with their own connection layer share it rather than copy it.
7771pub fn is_retryable_route_open_code(code: &str) -> bool {
7772    error_codes::is_retryable_route_open(code)
7773}
7774
7775/// Whether a data-plane ERROR answering a managed call's request is the
7776/// daemon's drain refusal, `module_reloading`, which the call may resend once
7777/// after reopening the route.
7778///
7779/// On an established route the daemon answers `module_reloading` only when the
7780/// module's endpoint is draining and the request could not take a route
7781/// credit, and it answers BEFORE forwarding (`ForwardBackend::handle_bound` in
7782/// subc-daemon's `router.rs`), so the module never received the request and a
7783/// resend cannot run it twice. The protocol documents that guarantee on
7784/// `error_codes::MODULE_RELOADING`.
7785///
7786/// Kept apart from `error_codes::is_established_route_dead` on purpose. That
7787/// shared predicate decides route DEATH, and other consumers map it to their
7788/// own custody, provider or suspect verdicts; adding a drain code there would
7789/// change those verdicts on a protocol bump. Here the code only earns the same
7790/// remedy (evict, reopen, resend once) inside this client's unary call path.
7791fn is_data_plane_drain_refusal(code: &str) -> bool {
7792    code == error_codes::MODULE_RELOADING
7793}
7794
7795// 0.37.15 is the first daemon that marks its own errors and strips the bit from module frames.
7796const DAEMON_ORIGIN_MIN_VERSION: (u64, u64, u64) = (0, 37, 15);
7797
7798/// Whether a connected daemon strips forged `DAEMON_ORIGIN` flags from module
7799/// frames: only exact numeric `major.minor.patch` versions at least 0.37.15.
7800/// Unknown versions, including pre-release and build suffixes, fail closed.
7801///
7802/// Pass the version from the same `ConnectionInfo` used by a successful
7803/// `authenticate_client` handshake. That handshake checks the daemon id against
7804/// the file, but its HMAC does not cover the version itself. Do not re-read the
7805/// file to classify a connection that is already authenticated.
7806pub fn trusts_daemon_origin(daemon_ver: &str) -> bool {
7807    daemon_version_at_least(daemon_ver, DAEMON_ORIGIN_MIN_VERSION)
7808}
7809
7810fn daemon_version_at_least(daemon_ver: &str, minimum: (u64, u64, u64)) -> bool {
7811    let mut components = daemon_ver.split('.');
7812    let mut next = || {
7813        let component = components.next()?;
7814        if component.is_empty() || !component.bytes().all(|byte| byte.is_ascii_digit()) {
7815            return None;
7816        }
7817        component.parse::<u64>().ok()
7818    };
7819    let version = (next(), next(), next());
7820    match version {
7821        (Some(major), Some(minor), Some(patch)) if components.next().is_none() => {
7822            (major, minor, patch) >= minimum
7823        }
7824        _ => false,
7825    }
7826}
7827
7828/// Whether an Error frame proves that its request was never forwarded.
7829///
7830/// This covers only `module_reloading`, `unknown_channel` and
7831/// `stale_route_epoch` with `DAEMON_ORIGIN`, when `daemon_origin_trusted` came
7832/// from [`trusts_daemon_origin`] for this connection's authenticated daemon
7833/// (0.37.15 or later). It proves only this attempt, not any earlier attempts of
7834/// a call. For managed calls use [`CallError::never_forwarded`] instead.
7835/// Unmarked errors and untrusted daemon versions never prove non-delivery.
7836/// This helper cannot see route negotiation and does not classify `route_busy`;
7837/// SDK-managed requests on opted-in routes handle that refusal internally.
7838pub fn is_daemon_refusal_before_forward(
7839    daemon_origin_trusted: bool,
7840    flags: Flags,
7841    code: &str,
7842) -> bool {
7843    daemon_origin_trusted
7844        && flags.is_daemon_origin()
7845        && matches!(
7846            code,
7847            error_codes::MODULE_RELOADING
7848                | error_codes::UNKNOWN_CHANNEL
7849                | error_codes::STALE_ROUTE_EPOCH
7850        )
7851}
7852
7853/// Whether `handle` names a route installed on the current connection. Channel 0 is the
7854/// connection's own control channel: it is never installed as a route and is current for
7855/// as long as the connection is, so a held channel-0 request (the spawn stream) can be
7856/// cancelled like a route subscription.
7857fn route_is_installed(inner: &Inner, handle: RouteHandle) -> bool {
7858    handle.channel == 0 || inner.route_epochs.get(&handle.channel) == Some(&handle)
7859}
7860
7861fn is_retryable_catalog_transport_error(err: &CallError) -> bool {
7862    matches!(err, CallError::NotSent(_) | CallError::OutcomeUnknown(_))
7863}
7864
7865fn is_reconnect_transient(err: &ConsumerError) -> bool {
7866    if let ConsumerError::Connect { source, .. } = err {
7867        if let Some(claim) = source
7868            .get_ref()
7869            .and_then(|source| source.downcast_ref::<crate::ClaimError>())
7870        {
7871            return matches!(claim, crate::ClaimError::Refused { code } if error_codes::is_retryable_claim(code));
7872        }
7873    }
7874    match err {
7875        ConsumerError::Connect { source, .. } => matches!(
7876            source.kind(),
7877            io::ErrorKind::ConnectionRefused
7878                | io::ErrorKind::ConnectionReset
7879                | io::ErrorKind::ConnectionAborted
7880                | io::ErrorKind::TimedOut
7881                | io::ErrorKind::NotConnected
7882                | io::ErrorKind::AddrNotAvailable
7883        ),
7884        ConsumerError::ConnectionFile { source, .. } => match source {
7885            ConnectionFileError::Io { source, .. } => source.kind() == io::ErrorKind::NotFound,
7886            _ => false,
7887        },
7888        // Auth failure is transient during reconnect: the daemon rotates its key
7889        // on every restart, and with a fixed port a client racing the restart can
7890        // read the pre-rotation connection file yet still connect — the proof
7891        // mismatch then means "stale key mid-rotation", not "impostor". Each
7892        // retry re-reads the connection file (open_connection), so the next
7893        // attempt picks up the rotated key, and server-proves-first protects
7894        // every attempt. First-connect auth failures stay permanent: connect()
7895        // surfaces them directly without entering the reconnect classifier.
7896        ConsumerError::Auth { .. } => true,
7897        ConsumerError::Discovery { .. }
7898        | ConsumerError::NoEndpoint { .. }
7899        | ConsumerError::Closed => false,
7900    }
7901}
7902
7903impl From<FrameBuildError> for CallError {
7904    fn from(err: FrameBuildError) -> Self {
7905        Self::not_sent(err.to_string())
7906    }
7907}
7908
7909#[cfg(test)]
7910mod local_transport_tests;
7911
7912#[cfg(test)]
7913mod tests {
7914    use super::*;
7915
7916    mod busy_refusals_tests;
7917    mod not_sent_tests;
7918    mod route_close_tests;
7919    mod route_deadline_tests;
7920
7921    #[derive(Clone)]
7922    struct InstrumentedWriter {
7923        state: Arc<InstrumentedWriterState>,
7924        fail_flush: bool,
7925    }
7926
7927    #[derive(Default)]
7928    struct InstrumentedWriterState {
7929        bytes: Mutex<Vec<u8>>,
7930        flushes: std::sync::atomic::AtomicUsize,
7931    }
7932
7933    impl InstrumentedWriter {
7934        fn new(fail_flush: bool) -> Self {
7935            Self {
7936                state: Arc::new(InstrumentedWriterState::default()),
7937                fail_flush,
7938            }
7939        }
7940
7941        fn bytes(&self) -> Vec<u8> {
7942            self.state
7943                .bytes
7944                .lock()
7945                .unwrap_or_else(|poisoned| poisoned.into_inner())
7946                .clone()
7947        }
7948
7949        fn flush_count(&self) -> usize {
7950            self.state.flushes.load(Ordering::SeqCst)
7951        }
7952    }
7953
7954    impl AsyncWrite for InstrumentedWriter {
7955        fn poll_write(
7956            self: Pin<&mut Self>,
7957            _cx: &mut Context<'_>,
7958            buf: &[u8],
7959        ) -> Poll<io::Result<usize>> {
7960            self.state
7961                .bytes
7962                .lock()
7963                .unwrap_or_else(|poisoned| poisoned.into_inner())
7964                .extend_from_slice(buf);
7965            Poll::Ready(Ok(buf.len()))
7966        }
7967
7968        fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
7969            self.state.flushes.fetch_add(1, Ordering::SeqCst);
7970            if self.fail_flush {
7971                Poll::Ready(Err(io::Error::new(
7972                    io::ErrorKind::BrokenPipe,
7973                    "instrumented flush failure",
7974                )))
7975            } else {
7976                Poll::Ready(Ok(()))
7977            }
7978        }
7979
7980        fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
7981            Poll::Ready(Ok(()))
7982        }
7983    }
7984
7985    fn writer_test_shared() -> Arc<Shared> {
7986        Arc::new(reader_skew_tests::legacy_shared(
7987            PathBuf::from("/tmp/does-not-exist"),
7988            ConsumerOptions {
7989                reconnect_backoff: RetryBackoff {
7990                    max_attempts: 1,
7991                    ..RetryBackoff::default()
7992                },
7993                ..ConsumerOptions::default()
7994            },
7995        ))
7996    }
7997
7998    fn reverse_test_shared(
7999        reverse_requests: ReverseRequestRegistry,
8000    ) -> (Arc<Shared>, mpsc::Receiver<WriteCommand>, RouteHandle) {
8001        let shared = writer_test_shared();
8002        let (writer, receiver) = mpsc::channel(16);
8003        let handle = RouteHandle::new_consumer(17, 3, 1, reverse_requests);
8004        {
8005            let mut inner = shared.lock_inner();
8006            inner.writer = Some(writer);
8007            inner.daemon_ver = "0.39.0".into();
8008            inner.route_epochs.insert(handle.channel, handle);
8009        }
8010        (shared, receiver, handle)
8011    }
8012
8013    fn reverse_request_frame(handle: RouteHandle, corr: u64, body: Vec<u8>) -> Frame {
8014        Frame::build(
8015            FrameType::Request,
8016            Flags::new(false, Priority::Interactive, false),
8017            handle.channel,
8018            handle.epoch,
8019            corr,
8020            body,
8021        )
8022        .unwrap()
8023    }
8024
8025    #[tokio::test]
8026    async fn binary_reply_request_preserves_flagged_non_utf8_bytes() {
8027        let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8028        let consumer = SubcConsumer {
8029            shared: Arc::clone(&shared),
8030        };
8031        shared
8032            .install_one_shot_route(RouteState {
8033                handle,
8034                sem: Arc::new(Semaphore::new(1)),
8035                watch_sem: None,
8036                opted_in: false,
8037            })
8038            .unwrap();
8039        let request = tokio::spawn(async move {
8040            consumer
8041                .request(&handle, b"bytes".to_vec(), CallOptions::default())
8042                .await
8043        });
8044        let command = receiver.recv().await.unwrap();
8045        let bytes = vec![0, 0xff, 0x80, b'{'];
8046        let frame = Frame::build(
8047            FrameType::Response,
8048            Flags::new(true, Priority::Interactive, false),
8049            handle.channel,
8050            handle.epoch,
8051            command.frame.header.corr,
8052            bytes.clone(),
8053        )
8054        .unwrap();
8055        assert!(dispatch_frame(&shared, 1, frame).await);
8056        assert_eq!(request.await.unwrap().unwrap(), bytes);
8057    }
8058
8059    async fn capture_route_open(
8060        reverse_requests: ReverseRequestRegistry,
8061    ) -> (serde_json::Value, RouteHandle) {
8062        capture_route_open_with_options(CallOptions {
8063            reverse_requests,
8064            ..CallOptions::default()
8065        })
8066        .await
8067    }
8068
8069    async fn capture_route_open_with_options(
8070        opts: CallOptions,
8071    ) -> (serde_json::Value, RouteHandle) {
8072        let shared = writer_test_shared();
8073        let (writer, mut receiver) = mpsc::channel(4);
8074        shared.lock_inner().writer = Some(writer);
8075        shared.lock_inner().daemon_ver = "0.39.0".into();
8076        let consumer = SubcConsumer {
8077            shared: Arc::clone(&shared),
8078        };
8079        let task = tokio::spawn(async move {
8080            consumer
8081                .open_route(
8082                    RouteTarget::ToolProvider {
8083                        module_id: "reverse-provider".to_string(),
8084                    },
8085                    BindIdentity::new("test".to_string(), "reverse".to_string()),
8086                    opts,
8087                )
8088                .await
8089        });
8090        let command = receiver.recv().await.expect("route.open frame");
8091        let request = serde_json::from_slice(&command.frame.body).unwrap();
8092        let response_body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
8093            request_window: None,
8094            watch_window: None,
8095            route_channel: 17,
8096            route_epoch: 3,
8097        })
8098        .unwrap();
8099        assert!(
8100            dispatch_frame(
8101                &shared,
8102                1,
8103                response_frame(0, 0, command.frame.header.corr, response_body),
8104            )
8105            .await
8106        );
8107        let handle = task.await.unwrap().unwrap();
8108        (request, handle)
8109    }
8110
8111    /// Keep held subscriptions marked for drain accounting without marking ordinary requests.
8112    #[tokio::test]
8113    async fn held_subscriptions_set_the_flag_but_ordinary_requests_do_not() {
8114        let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8115        let call_shared = Arc::clone(&shared);
8116        let call = tokio::spawn(async move {
8117            call_shared
8118                .send_request(RequestSend {
8119                    binary: false,
8120                    expected_handle: Some(handle),
8121                    channel: handle.channel,
8122                    epoch: handle.epoch,
8123                    body: b"ordinary".to_vec(),
8124                    priority: Priority::Interactive,
8125                    admission_class: AdmissionClass::Normal,
8126                    deadline: Instant::now() + Duration::from_secs(1),
8127                    retain_late_route_open: false,
8128                    route_open_reverse_requests: None,
8129                })
8130                .await
8131        });
8132        let ordinary = receiver.recv().await.unwrap();
8133        assert_eq!(ordinary.frame.header.encode()[6] & FLAG_SUBSCRIPTION, 0);
8134        assert!(
8135            dispatch_frame(
8136                &shared,
8137                1,
8138                response_frame(
8139                    handle.channel,
8140                    handle.epoch,
8141                    ordinary.frame.header.corr,
8142                    Vec::new()
8143                ),
8144            )
8145            .await
8146        );
8147        assert!(call.await.unwrap().is_ok());
8148
8149        let permit = Arc::new(Semaphore::new(1)).acquire_owned().await.unwrap();
8150        let subscription = Arc::clone(&shared)
8151            .send_subscription(SubscriptionSend {
8152                expected_handle: Some(handle),
8153                channel: handle.channel,
8154                epoch: handle.epoch,
8155                body: b"held".to_vec(),
8156                priority: Priority::Interactive,
8157                admission_class: AdmissionClass::Normal,
8158                event_buffer: 1,
8159                deadline: Instant::now() + Duration::from_secs(1),
8160                permit: RoutePermit::legacy(permit),
8161            })
8162            .await
8163            .unwrap();
8164        let held = receiver.recv().await.unwrap();
8165        assert_ne!(
8166            held.frame.header.encode()[6] & FLAG_SUBSCRIPTION,
8167            0,
8168            "a held-open subscription must be marked for drain accounting"
8169        );
8170        drop(subscription);
8171        release_reverse_request_registry(handle);
8172    }
8173
8174    #[tokio::test]
8175    async fn registered_handlers_derive_route_open_consumer_capabilities() {
8176        let registry = ReverseRequestRegistry::new();
8177        registry
8178            .on_request("elicitation", |_body, _ctx| async { Vec::new() })
8179            .unwrap();
8180        let (request, handle) = capture_route_open(registry).await;
8181        assert_eq!(
8182            request.get("consumer_capabilities"),
8183            Some(&serde_json::json!(["elicitation"]))
8184        );
8185        release_reverse_request_registry(handle);
8186    }
8187
8188    #[tokio::test]
8189    async fn declared_consumer_capabilities_merge_with_handler_families_on_route_open() {
8190        let registry = ReverseRequestRegistry::new();
8191        registry
8192            .on_request("elicitation", |_body, _ctx| async { Vec::new() })
8193            .unwrap();
8194        let opts = CallOptions {
8195            reverse_requests: registry,
8196            ..CallOptions::default()
8197        }
8198        .with_consumer_capability("tool-result/v1")
8199        .unwrap()
8200        .with_consumer_capability("elicitation")
8201        .unwrap()
8202        .with_consumer_capability("tool-result/v1")
8203        .unwrap();
8204
8205        let (request, handle) = capture_route_open_with_options(opts).await;
8206        assert_eq!(
8207            request.get("consumer_capabilities"),
8208            Some(&serde_json::json!(["elicitation", "tool-result/v1"]))
8209        );
8210        release_reverse_request_registry(handle);
8211    }
8212
8213    #[test]
8214    fn invalid_consumer_capability_declarations_are_rejected_before_route_open() {
8215        let (shared, mut receiver) = {
8216            let shared = writer_test_shared();
8217            let (writer, receiver) = mpsc::channel(4);
8218            shared.lock_inner().writer = Some(writer);
8219            shared.lock_inner().daemon_ver = "0.39.0".into();
8220            (shared, receiver)
8221        };
8222        let too_long = "x".repeat(65);
8223        for invalid in [
8224            String::new(),
8225            "content v1".to_string(),
8226            "content\tv1".to_string(),
8227            "content\nv1".to_string(),
8228            "cöntent/v1".to_string(),
8229            "content/\u{7f}v1".to_string(),
8230            too_long,
8231        ] {
8232            let error = CallOptions::default()
8233                .with_consumer_capability(invalid.clone())
8234                .expect_err("invalid declarations must not produce route options");
8235            assert_eq!(error.capability(), invalid);
8236            assert!(
8237                receiver.try_recv().is_err(),
8238                "invalid declaration {invalid:?} must be rejected before any frame is queued"
8239            );
8240        }
8241        let close_error = CloseRouteOptions::default()
8242            .with_consumer_capability("bad value")
8243            .expect_err("close-route declarations use the same validation");
8244        assert_eq!(close_error.capability(), "bad value");
8245        let call_options = CallOptions::default()
8246            .with_consumer_capability("tool-result/v1")
8247            .unwrap();
8248        assert_eq!(
8249            call_options.consumer_capabilities(),
8250            vec!["tool-result/v1".to_string()]
8251        );
8252        let close_options = CloseRouteOptions::default()
8253            .with_consumer_capability("tool-result/v1")
8254            .unwrap();
8255        assert_eq!(
8256            close_options.consumer_capabilities(),
8257            vec!["tool-result/v1".to_string()]
8258        );
8259        shared.close_sync("test complete");
8260    }
8261
8262    #[tokio::test]
8263    async fn no_handlers_omit_consumer_capabilities_from_route_open() {
8264        let (request, handle) = capture_route_open(ReverseRequestRegistry::new()).await;
8265        assert!(!request
8266            .as_object()
8267            .unwrap()
8268            .contains_key("consumer_capabilities"));
8269        release_reverse_request_registry(handle);
8270    }
8271
8272    #[tokio::test]
8273    async fn reverse_request_without_handler_returns_typed_error_instead_of_silence() {
8274        let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8275        let body = serde_json::to_vec(&serde_json::json!({
8276            "jsonrpc": "2.0",
8277            "id": 1,
8278            "method": "elicitation/create",
8279            "params": {}
8280        }))
8281        .unwrap();
8282        assert!(dispatch_frame(&shared, 1, reverse_request_frame(handle, 800, body)).await);
8283        let reply = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8284            .await
8285            .unwrap()
8286            .unwrap()
8287            .frame;
8288        assert_eq!(reply.header.ty, FrameType::Error);
8289        assert_eq!(reply.header.corr, 800);
8290        let error: ErrorBody = serde_json::from_slice(&reply.body).unwrap();
8291        assert_eq!(error.code, REVERSE_REQUEST_UNHANDLED);
8292        release_reverse_request_registry(handle);
8293    }
8294
8295    #[tokio::test]
8296    async fn reverse_request_round_trip_preserves_raw_body_corr_and_response() {
8297        let registry = ReverseRequestRegistry::new();
8298        let seen = Arc::new(Mutex::new(None));
8299        let seen_by_handler = Arc::clone(&seen);
8300        let response = br#"{"jsonrpc":"2.0","id":9,"result":{"accepted":true}}"#.to_vec();
8301        let expected_response = response.clone();
8302        registry
8303            .on_request("elicitation", move |body, ctx| {
8304                *seen_by_handler
8305                    .lock()
8306                    .unwrap_or_else(|poisoned| poisoned.into_inner()) =
8307                    Some((body, ctx.corr, ctx.method));
8308                let response = response.clone();
8309                async move { response }
8310            })
8311            .unwrap();
8312        let (shared, mut receiver, handle) = reverse_test_shared(registry);
8313        let request_body =
8314            br#"{"jsonrpc":"2.0","id":9,"method":"elicitation/create","params":{"z":1,"a":2}}"#
8315                .to_vec();
8316        assert!(
8317            dispatch_frame(
8318                &shared,
8319                1,
8320                reverse_request_frame(handle, 801, request_body.clone()),
8321            )
8322            .await
8323        );
8324        let reply = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8325            .await
8326            .unwrap()
8327            .unwrap()
8328            .frame;
8329        assert_eq!(reply.header.ty, FrameType::Response);
8330        assert_eq!(reply.header.corr, 801);
8331        assert_eq!(reply.body, expected_response);
8332        assert_eq!(
8333            seen.lock()
8334                .unwrap_or_else(|poisoned| poisoned.into_inner())
8335                .clone(),
8336            Some((request_body, 801, "elicitation/create".to_string()))
8337        );
8338        release_reverse_request_registry(handle);
8339    }
8340
8341    #[tokio::test]
8342    async fn panicking_reverse_handler_returns_typed_refusal_and_sibling_request_resolves() {
8343        let registry = ReverseRequestRegistry::new();
8344        registry
8345            .on_request("sampling", |_body, _ctx| async move {
8346                panic!("person prompt exploded");
8347            })
8348            .unwrap();
8349        let (shared, mut receiver, handle) = reverse_test_shared(registry);
8350        let sibling_shared = Arc::clone(&shared);
8351        let sibling = tokio::spawn(async move {
8352            sibling_shared
8353                .send_request(RequestSend {
8354                    binary: false,
8355                    expected_handle: Some(handle),
8356                    channel: handle.channel,
8357                    epoch: handle.epoch,
8358                    body: b"sibling".to_vec(),
8359                    priority: Priority::Interactive,
8360                    admission_class: AdmissionClass::Normal,
8361                    deadline: Instant::now() + Duration::from_secs(1),
8362                    retain_late_route_open: false,
8363                    route_open_reverse_requests: None,
8364                })
8365                .await
8366        });
8367        let sibling_request = receiver.recv().await.unwrap();
8368        let reverse_body = serde_json::to_vec(&serde_json::json!({
8369            "method": "sampling/createMessage",
8370            "params": {}
8371        }))
8372        .unwrap();
8373        assert!(
8374            dispatch_frame(&shared, 1, reverse_request_frame(handle, 802, reverse_body),).await
8375        );
8376        assert!(
8377            dispatch_frame(
8378                &shared,
8379                1,
8380                response_frame(
8381                    handle.channel,
8382                    handle.epoch,
8383                    sibling_request.frame.header.corr,
8384                    b"ok".to_vec(),
8385                ),
8386            )
8387            .await
8388        );
8389        assert!(matches!(
8390            sibling.await.unwrap().unwrap(),
8391            TerminalFrame::Response { body, .. } if body == b"ok"
8392        ));
8393        let refusal = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8394            .await
8395            .unwrap()
8396            .unwrap()
8397            .frame;
8398        assert_eq!(refusal.header.ty, FrameType::Error);
8399        let error: ErrorBody = serde_json::from_slice(&refusal.body).unwrap();
8400        assert_eq!(error.code, REVERSE_REQUEST_UNHANDLED);
8401        assert!(error.message.contains("person prompt exploded"));
8402        assert!(shared.generation_is_current(1));
8403        release_reverse_request_registry(handle);
8404    }
8405
8406    fn reservation_stand_in(
8407        credit: usize,
8408        capacity: usize,
8409    ) -> (
8410        Arc<Shared>,
8411        SubcConsumer,
8412        mpsc::Receiver<WriteCommand>,
8413        RouteHandle,
8414        Arc<Semaphore>,
8415    ) {
8416        let shared = writer_test_shared();
8417        let (writer, rx) = mpsc::channel(capacity);
8418        shared.lock_inner().writer = Some(writer);
8419        shared.lock_inner().daemon_ver = "0.39.0".into();
8420        let handle = RouteHandle::new(5, 3, 1);
8421        let sem = Arc::new(Semaphore::new(credit));
8422        shared
8423            .install_one_shot_route(RouteState {
8424                handle,
8425                sem: Arc::clone(&sem),
8426                watch_sem: None,
8427                opted_in: false,
8428            })
8429            .unwrap();
8430        let consumer = SubcConsumer {
8431            shared: Arc::clone(&shared),
8432        };
8433        (shared, consumer, rx, handle, sem)
8434    }
8435
8436    #[tokio::test]
8437    async fn reservation_send_is_synchronous_and_uses_prevalidated_body() {
8438        let oversized = vec![0; subc_protocol::MAX_FRAME_BODY_LEN as usize + 1];
8439        assert!(matches!(
8440            RequestBody::new(oversized),
8441            Err(CallError::NotSent(_))
8442        ));
8443        let body = RequestBody::new(b"valid".to_vec()).unwrap();
8444        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8445        let reserved = consumer
8446            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8447            .await
8448            .unwrap();
8449        let corr = reserved.correlation_id();
8450        assert_eq!(shared.lock_inner().writer.as_ref().unwrap().capacity(), 0);
8451        assert!(rx.try_recv().is_err());
8452
8453        // A concrete tuple proves send returns without awaiting. Inspect the
8454        // writer queue before running the writer or polling PendingReply.
8455        let (sent_corr, reply): (CorrelationId, PendingReply) =
8456            reserved.send(body, CallOptions::default());
8457        assert_eq!(sent_corr, corr);
8458        let command = rx.try_recv().expect("send must enqueue without yielding");
8459        assert_eq!(command.frame.body, b"valid");
8460        assert_eq!(command.frame.header.corr, corr);
8461        assert_eq!(sem.available_permits(), 0);
8462        assert!(shared.mark_pending_accepted(command.pending.unwrap()));
8463        dispatch_frame(
8464            &shared,
8465            1,
8466            response_frame(handle.channel, handle.epoch, corr, b"reply".to_vec()),
8467        )
8468        .await;
8469        assert_eq!(reply.await.unwrap(), b"reply");
8470        assert_eq!(sem.available_permits(), 1);
8471        consumer.close().await;
8472    }
8473
8474    #[tokio::test]
8475    async fn reservation_drop_releases_route_credit_and_writer_capacity_without_sending() {
8476        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8477        let deadline = Instant::now() + Duration::from_secs(1);
8478        let first = consumer.reserve(&handle, deadline).await.unwrap();
8479        let second = consumer.reserve(&handle, deadline);
8480        tokio::pin!(second);
8481        assert_pending(second.as_mut()).await;
8482        assert_eq!(sem.available_permits(), 0);
8483        drop(first);
8484        let second = timeout_at(deadline, second).await.unwrap().unwrap();
8485        drop(second);
8486        assert_eq!(sem.available_permits(), 1);
8487        assert_eq!(shared.lock_inner().writer.as_ref().unwrap().capacity(), 1);
8488        assert!(shared.lock_inner().pending.is_empty());
8489        assert!(rx.try_recv().is_err());
8490        consumer.close().await;
8491    }
8492
8493    #[tokio::test]
8494    async fn reservation_route_closed_before_send_matches_an_ordinary_unwritten_request() {
8495        let (shared, consumer, mut rx, handle, _) = reservation_stand_in(2, 4);
8496        let reserved = consumer
8497            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8498            .await
8499            .unwrap();
8500        let ordinary = consumer.request(&handle, b"ordinary".to_vec(), CallOptions::default());
8501        tokio::pin!(ordinary);
8502        assert_pending(ordinary.as_mut()).await;
8503        let ordinary_command = rx.try_recv().unwrap();
8504        assert_eq!(ordinary_command.frame.body, b"ordinary");
8505        consumer
8506            .close_handle(&handle, CloseRouteOptions::default())
8507            .await
8508            .unwrap();
8509        let (_, reply) = reserved.send(
8510            RequestBody::new(b"reserved".to_vec()).unwrap(),
8511            CallOptions::default(),
8512        );
8513        let ordinary_error = ordinary.await.unwrap_err();
8514        let reserved_error = reply.await.unwrap_err();
8515        assert!(matches!(reserved_error, CallError::NotSent(_)));
8516        assert_eq!(
8517            reserved_error.close_reason(),
8518            Some(&RouteEndReason::ClosedByCaller)
8519        );
8520        assert_eq!(reserved_error.to_string(), ordinary_error.to_string());
8521        assert_eq!(reserved_error.close_reason(), ordinary_error.close_reason());
8522
8523        rx.close();
8524        let writer = InstrumentedWriter::new(false);
8525        writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8526        let bytes = writer.bytes();
8527        let mut bytes = bytes.as_slice();
8528        let frame = read_frame(&mut bytes).await.unwrap().unwrap();
8529        assert_eq!(frame.header.ty, FrameType::Goodbye);
8530        assert!(
8531            bytes.is_empty(),
8532            "the closed route's reserved request must not be written"
8533        );
8534        consumer.close().await;
8535    }
8536
8537    #[tokio::test]
8538    async fn reservation_connection_loss_after_send_preserves_existing_errors() {
8539        for written in [false, true] {
8540            let (shared, consumer, rx, handle, sem) = reservation_stand_in(1, 1);
8541            let reserved = consumer
8542                .reserve(&handle, Instant::now() + Duration::from_secs(1))
8543                .await
8544                .unwrap();
8545            let (_, reply) = reserved.send(
8546                RequestBody::new(b"request".to_vec()).unwrap(),
8547                CallOptions::default(),
8548            );
8549            let writer = InstrumentedWriter::new(written);
8550            if !written {
8551                shared.handle_generation_drop(1, "connection lost before dequeue".to_string());
8552            }
8553            writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8554            let err = reply.await.unwrap_err();
8555            assert_eq!(err.close_reason(), Some(&RouteEndReason::ConnectionLost));
8556            if written {
8557                // `outcome_cause` answers only for `OutcomeUnknown`, so this also
8558                // checks the variant without adding a spelling the
8559                // outcome_unknown_inventory test would have to count.
8560                assert_eq!(err.outcome_cause(), Some(OutcomeUnknownCause::WriterClosed));
8561                assert!(!writer.bytes().is_empty());
8562            } else {
8563                assert!(matches!(err, CallError::NotSent(_)));
8564                assert!(writer.bytes().is_empty());
8565            }
8566            assert_eq!(sem.available_permits(), 1);
8567            consumer.close().await;
8568        }
8569    }
8570
8571    #[tokio::test]
8572    async fn reservation_correlations_are_unique_and_match_frames_written_out_of_order() {
8573        let (shared, consumer, mut rx, handle, _) = reservation_stand_in(3, 3);
8574        let deadline = Instant::now() + Duration::from_secs(1);
8575        let first = consumer.reserve(&handle, deadline).await.unwrap();
8576        let second = consumer.reserve(&handle, deadline).await.unwrap();
8577        let third = consumer.reserve(&handle, deadline).await.unwrap();
8578        let ids = [
8579            first.correlation_id(),
8580            second.correlation_id(),
8581            third.correlation_id(),
8582        ];
8583        assert_eq!(ids.into_iter().collect::<HashSet<_>>().len(), 3);
8584        let opts = CallOptions {
8585            priority: Priority::Background,
8586            admission_class: AdmissionClass::Expedite,
8587            ..CallOptions::default()
8588        };
8589        let mut replies = Vec::new();
8590        for (reserved, expected_id, body) in [
8591            (third, ids[2], "third"),
8592            (first, ids[0], "first"),
8593            (second, ids[1], "second"),
8594        ] {
8595            let (corr, reply) = reserved.send(
8596                RequestBody::new(body.as_bytes().to_vec()).unwrap(),
8597                opts.clone(),
8598            );
8599            assert_eq!(corr, expected_id);
8600            replies.push((corr, body, reply));
8601        }
8602        rx.close();
8603        let writer = InstrumentedWriter::new(false);
8604        writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8605        let bytes = writer.bytes();
8606        let mut bytes = bytes.as_slice();
8607        for (corr, body, reply) in replies {
8608            let frame = read_frame(&mut bytes).await.unwrap().unwrap();
8609            assert_eq!(frame.header.ty, FrameType::Request);
8610            assert_eq!(frame.header.corr, corr);
8611            assert_eq!(frame.header.channel, handle.channel);
8612            assert_eq!(frame.header.epoch, handle.epoch);
8613            assert_eq!(
8614                frame.header.flags,
8615                Flags::new(false, Priority::Background, false)
8616                    .with_admission_class(AdmissionClass::Expedite)
8617            );
8618            assert_eq!(frame.body, body.as_bytes());
8619            dispatch_frame(
8620                &shared,
8621                1,
8622                response_frame(handle.channel, handle.epoch, corr, body.as_bytes().to_vec()),
8623            )
8624            .await;
8625            assert_eq!(reply.await.unwrap(), body.as_bytes());
8626        }
8627        assert!(bytes.is_empty());
8628        consumer.close().await;
8629    }
8630
8631    #[tokio::test(start_paused = true)]
8632    async fn reservation_deadline_before_send_prevents_writing_without_polling_reply() {
8633        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8634        let reserved = consumer
8635            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8636            .await
8637            .unwrap();
8638        tokio::time::advance(Duration::from_secs(2)).await;
8639        let (_, reply) = reserved.send(
8640            RequestBody::new(b"expired".to_vec()).unwrap(),
8641            CallOptions::default(),
8642        );
8643        rx.close();
8644        let writer = InstrumentedWriter::new(false);
8645        writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8646        assert!(writer.bytes().is_empty());
8647        assert!(matches!(reply.await, Err(CallError::NotSent(_))));
8648        assert_eq!(sem.available_permits(), 1);
8649        consumer.close().await;
8650    }
8651
8652    #[tokio::test(start_paused = true)]
8653    async fn reservation_deadline_bounds_writer_capacity_and_releases_credit() {
8654        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(2, 1);
8655        let first = consumer
8656            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8657            .await
8658            .unwrap();
8659        let second = consumer
8660            .reserve(&handle, Instant::now() + Duration::from_millis(25))
8661            .await;
8662        assert!(matches!(second, Err(CallError::NotSent(_))));
8663        assert_eq!(sem.available_permits(), 1);
8664        drop(first);
8665        assert_eq!(sem.available_permits(), 2);
8666        assert!(shared.lock_inner().pending.is_empty());
8667        assert!(rx.try_recv().is_err());
8668        consumer.close().await;
8669    }
8670
8671    #[tokio::test]
8672    async fn reservation_reconnect_during_writer_capacity_wait_fails_promptly_without_writing() {
8673        let (shared, consumer, mut old_rx, handle, sem) = reservation_stand_in(1, 1);
8674        let old_writer = shared.lock_inner().writer.clone().unwrap();
8675        let held_capacity = old_writer.reserve_owned().await.unwrap();
8676        let reserve = consumer.reserve(&handle, Instant::now() + Duration::from_secs(60));
8677        tokio::pin!(reserve);
8678        assert_pending(reserve.as_mut()).await;
8679        assert_eq!(sem.available_permits(), 0);
8680
8681        let mut replacement_rx = drop_and_replace_test_transport(&shared);
8682        assert_ne!(shared.lock_inner().generation, handle.connection_token());
8683        drop(held_capacity);
8684        let result = std::future::poll_fn(|cx| Poll::Ready(reserve.as_mut().poll(cx))).await;
8685        assert!(matches!(
8686            result,
8687            Poll::Ready(Err(CallError::StaleRouteHandle(stale))) if stale == handle
8688        ));
8689        assert!(shared.lock_inner().pending.is_empty());
8690        assert_eq!(sem.available_permits(), 1);
8691        assert!(old_rx.try_recv().is_err());
8692        assert!(replacement_rx.try_recv().is_err());
8693
8694        old_rx.close();
8695        replacement_rx.close();
8696        let writer = InstrumentedWriter::new(false);
8697        writer_loop(
8698            Arc::clone(&shared),
8699            writer.clone(),
8700            old_rx,
8701            handle.connection_token(),
8702        )
8703        .await;
8704        let generation = shared.lock_inner().generation;
8705        writer_loop(
8706            Arc::clone(&shared),
8707            writer.clone(),
8708            replacement_rx,
8709            generation,
8710        )
8711        .await;
8712        assert!(writer.bytes().is_empty());
8713        consumer.close().await;
8714    }
8715
8716    #[tokio::test]
8717    async fn reservation_reply_drop_cleans_up_without_polling() {
8718        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8719        let reserved = consumer
8720            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8721            .await
8722            .unwrap();
8723        let (_, reply) = reserved.send(
8724            RequestBody::new(b"request".to_vec()).unwrap(),
8725            CallOptions::default(),
8726        );
8727        drop(reply);
8728        assert!(shared.lock_inner().pending.is_empty());
8729        assert_eq!(sem.available_permits(), 1);
8730        rx.close();
8731        let writer = InstrumentedWriter::new(false);
8732        writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8733        assert!(writer.bytes().is_empty());
8734        consumer.close().await;
8735    }
8736
8737    #[tokio::test]
8738    async fn writer_batches_ready_frames_into_one_flush() {
8739        const FRAME_COUNT: usize = 8;
8740
8741        let shared = writer_test_shared();
8742        let (live_writer, _live_rx) = mpsc::channel(1);
8743        let (tx, rx) = mpsc::channel(FRAME_COUNT + 1);
8744        let instrumented = InstrumentedWriter::new(false);
8745        let observer = instrumented.clone();
8746        let mut expected = Vec::with_capacity(FRAME_COUNT);
8747        let mut keys = Vec::with_capacity(FRAME_COUNT);
8748
8749        {
8750            let mut inner = shared.lock_inner();
8751            inner.writer = Some(live_writer);
8752            inner.daemon_ver = "0.39.0".into();
8753            for index in 0..FRAME_COUNT {
8754                let corr = index as u64 + 1;
8755                let frame = response_frame(7, 1, corr, vec![index as u8; index + 1]);
8756                let key = PendingKey {
8757                    generation: 1,
8758                    channel: 7,
8759                    epoch: 1,
8760                    corr,
8761                };
8762                let (pending_tx, _pending_rx) = oneshot::channel();
8763                inner
8764                    .pending
8765                    .insert(key, PendingEntry::unary(pending_tx, false, None, None));
8766                expected.push(frame.clone());
8767                keys.push(key);
8768                tx.try_send(WriteCommand {
8769                    frame,
8770                    pending: Some(key),
8771                })
8772                .expect("the burst should fit in the writer queue");
8773                if index == 0 {
8774                    tx.try_send(WriteCommand {
8775                        frame: response_frame(7, 1, 999, b"skip".to_vec()),
8776                        pending: Some(PendingKey {
8777                            generation: 1,
8778                            channel: 7,
8779                            epoch: 1,
8780                            corr: 999,
8781                        }),
8782                    })
8783                    .expect("the skipped command should fit in the writer queue");
8784                }
8785            }
8786        }
8787        drop(tx);
8788
8789        writer_loop(Arc::clone(&shared), instrumented, rx, 1).await;
8790
8791        {
8792            let inner = shared.lock_inner();
8793            for key in keys {
8794                assert!(
8795                    inner.pending.get(&key).is_some_and(|entry| entry.accepted),
8796                    "every written command must be marked accepted"
8797                );
8798            }
8799        }
8800
8801        let mut wire = std::io::Cursor::new(observer.bytes());
8802        for expected_frame in expected {
8803            let actual = read_frame(&mut wire)
8804                .await
8805                .expect("the emitted frame should decode")
8806                .expect("the emitted frame should be present");
8807            assert_eq!(actual, expected_frame);
8808        }
8809        assert!(
8810            read_frame(&mut wire)
8811                .await
8812                .expect("the end of the emitted burst should be clean")
8813                .is_none(),
8814            "the writer must not emit extra frames"
8815        );
8816
8817        let flush_count = observer.flush_count();
8818        assert_eq!(
8819            flush_count, 1,
8820            "a ready burst must be coalesced into one flush"
8821        );
8822        shared.close_sync("test complete");
8823    }
8824
8825    #[tokio::test]
8826    async fn writer_flush_failure_drops_generation_and_preserves_acceptance_classification() {
8827        let shared = writer_test_shared();
8828        let (live_writer, _live_rx) = mpsc::channel(1);
8829        let accepted_key = PendingKey {
8830            generation: 1,
8831            channel: 3,
8832            epoch: 1,
8833            corr: 1,
8834        };
8835        let not_sent_key = PendingKey {
8836            corr: 2,
8837            ..accepted_key
8838        };
8839        let (accepted_tx, accepted_rx) = oneshot::channel();
8840        let (not_sent_tx, not_sent_rx) = oneshot::channel();
8841        {
8842            let mut inner = shared.lock_inner();
8843            inner.writer = Some(live_writer);
8844            inner.daemon_ver = "0.39.0".into();
8845            inner.pending.insert(
8846                accepted_key,
8847                PendingEntry::unary(accepted_tx, false, None, None),
8848            );
8849            inner.pending.insert(
8850                not_sent_key,
8851                PendingEntry::unary(not_sent_tx, false, None, None),
8852            );
8853        }
8854
8855        let (tx, rx) = mpsc::channel(1);
8856        tx.send(WriteCommand {
8857            frame: response_frame(3, 1, accepted_key.corr, b"accepted".to_vec()),
8858            pending: Some(accepted_key),
8859        })
8860        .await
8861        .unwrap();
8862        drop(tx);
8863
8864        writer_loop(Arc::clone(&shared), InstrumentedWriter::new(true), rx, 1).await;
8865
8866        assert!(
8867            shared.lock_inner().writer.is_none(),
8868            "a flush failure must drop the active generation"
8869        );
8870        let accepted_error = accepted_rx
8871            .await
8872            .expect("the accepted request should be settled")
8873            .into_call_result()
8874            .unwrap_err();
8875        assert!(matches!(accepted_error, CallError::OutcomeUnknown(_)));
8876        assert_eq!(
8877            accepted_error.outcome_cause(),
8878            Some(OutcomeUnknownCause::WriterClosed)
8879        );
8880        let not_sent_error = not_sent_rx
8881            .await
8882            .expect("the unwritten request should be settled")
8883            .into_call_result()
8884            .unwrap_err();
8885        assert!(matches!(not_sent_error, CallError::NotSent(_)));
8886        assert_eq!(not_sent_error.outcome_cause(), None);
8887        shared.close_sync("test complete");
8888    }
8889
8890    #[tokio::test]
8891    async fn consumer_close_attaches_outcome_cause_to_pending_call() {
8892        let shared = writer_test_shared();
8893        let (writer, _writer_rx) = mpsc::channel(1);
8894        shared.lock_inner().writer = Some(writer);
8895        shared.lock_inner().daemon_ver = "0.39.0".into();
8896        let (tx, rx) = oneshot::channel();
8897        let mut entry = PendingEntry::unary(tx, false, None, None);
8898        entry.accepted = true;
8899        shared.lock_inner().pending.insert(
8900            PendingKey {
8901                generation: 1,
8902                channel: 3,
8903                epoch: 1,
8904                corr: 1,
8905            },
8906            entry,
8907        );
8908        let consumer = SubcConsumer { shared };
8909        consumer.close().await;
8910        let err = rx.await.unwrap().into_call_result().unwrap_err();
8911        assert_eq!(
8912            err.outcome_cause(),
8913            Some(OutcomeUnknownCause::ConsumerClosed)
8914        );
8915        assert_eq!(err.to_string(), "request outcome unknown: consumer closed");
8916        assert_eq!(err.close_reason(), None);
8917    }
8918
8919    #[tokio::test]
8920    async fn subscription_completion_drop_attaches_outcome_cause() {
8921        let (tx, rx) = oneshot::channel();
8922        let closed = SubscriptionClosed { rx };
8923        drop(tx);
8924        let err = closed.await.unwrap_err();
8925        assert_eq!(
8926            err.outcome_cause(),
8927            Some(OutcomeUnknownCause::CompletionFailed)
8928        );
8929        assert_eq!(
8930            err.to_string(),
8931            "request outcome unknown: subscription closed result channel dropped"
8932        );
8933    }
8934
8935    #[test]
8936    fn reconnect_classifier_treats_auth_failure_as_transient() {
8937        // Key rotation across a daemon restart on the fixed port: a client racing
8938        // the restart reads the pre-rotation file, connects, and fails the proof.
8939        // That must be retryable — each retry re-reads the file, so the next
8940        // attempt picks up the rotated key. Treating it as a permanent impostor
8941        // verdict would turn every daemon restart into a permanent client wedge.
8942        let auth = ConsumerError::Auth {
8943            path: PathBuf::from("/tmp/subc-connection.json"),
8944            endpoint: "127.0.0.1:8757".to_string(),
8945            source: subc_transport::AuthError::InvalidServerProof,
8946        };
8947        assert!(is_reconnect_transient(&auth), "rotation race must retry");
8948
8949        // Absent file mid-restart stays transient; malformed file stays permanent.
8950        let absent = ConsumerError::ConnectionFile {
8951            path: PathBuf::from("/tmp/subc-connection.json"),
8952            source: ConnectionFileError::Io {
8953                op: "read",
8954                path: PathBuf::from("/tmp/subc-connection.json"),
8955                source: io::Error::new(io::ErrorKind::NotFound, "gone"),
8956            },
8957        };
8958        assert!(is_reconnect_transient(&absent));
8959    }
8960
8961    #[tokio::test]
8962    async fn newer_drop_supersedes_reconnect_and_ignores_stale_completion() {
8963        let shared = Arc::new(reader_skew_tests::legacy_shared(
8964            PathBuf::from("/tmp/does-not-exist"),
8965            ConsumerOptions::default(),
8966        ));
8967        let stale_task = tokio::spawn(std::future::pending::<()>());
8968        {
8969            let mut inner = shared.lock_inner();
8970            inner.generation = 2;
8971            inner.reconnect = ReconnectState::Background {
8972                generation: 1,
8973                task: stale_task,
8974            };
8975        }
8976
8977        assert!(shared.spawn_reconnect(2));
8978        assert!(matches!(
8979            &shared.lock_inner().reconnect,
8980            ReconnectState::Background { generation, .. } if *generation == 2
8981        ));
8982
8983        shared.finish_background_reconnect(1);
8984        assert!(matches!(
8985            &shared.lock_inner().reconnect,
8986            ReconnectState::Background { generation, .. } if *generation == 2
8987        ));
8988        shared.close_sync("test complete");
8989    }
8990
8991    #[test]
8992    fn retryable_route_open_codes_are_code_specific() {
8993        for code in [
8994            "module_reloading",
8995            "module_warming",
8996            "target_unavailable",
8997            "module_timeout",
8998        ] {
8999            assert!(is_retryable_route_open_code(code), "{code} should retry");
9000        }
9001        // "No module of this id is registered or supervised here" is a typo or
9002        // an undeployed peer: the daemon reports a configured-but-late target
9003        // with module_warming/target_unavailable, so retrying unknown_module
9004        // in place only papers over an unsupervised module's HELLO race.
9005        assert!(
9006            !is_retryable_route_open_code(error_codes::UNKNOWN_MODULE),
9007            "unknown_module is terminal"
9008        );
9009        assert!(!is_retryable_route_open_code(error_codes::MODULE_REMOVED));
9010        assert!(!is_retryable_route_open_code("invalid_project_root"));
9011        assert!(!is_retryable_route_open_code("route_rejected"));
9012        assert!(
9013            !is_retryable_route_open_code("capability_forbidden"),
9014            "a capability policy refusal must not enter the route.open retry set"
9015        );
9016    }
9017
9018    #[test]
9019    fn two_routes_record_distinct_reasons_and_reuse_clears_channel() {
9020        let shared = Arc::new(reader_skew_tests::legacy_shared(
9021            PathBuf::new(),
9022            ConsumerOptions::default(),
9023        ));
9024        let (writer, _rx) = mpsc::channel(8);
9025        shared.lock_inner().writer = Some(writer);
9026        shared.lock_inner().daemon_ver = "0.39.0".into();
9027        shared.install_ingress_handle(RouteHandle::new(7, 1, 1));
9028        shared.install_ingress_handle(RouteHandle::new(9, 1, 1));
9029        {
9030            let mut inner = shared.lock_inner();
9031            inner.route_modules.insert(7, "provider".into());
9032            inner.route_modules.insert(9, "provider".into());
9033        }
9034        shared.control_push(br#"{"op":"route.closed","module_id":"provider","channels":[7],"reason":"scope_ended"}"#);
9035        shared.control_push(
9036            br#"{"op":"route.closing","module_id":"provider","channels":[9],"reason":"restart"}"#,
9037        );
9038        shared.control_push(
9039            br#"{"op":"route.closing","module_id":"provider","channels":[7],"reason":"crash"}"#,
9040        );
9041        assert_eq!(
9042            shared.lock_inner().route_end_reason(7),
9043            RouteEndReason::Daemon(RouteCloseReason::ScopeEnded)
9044        );
9045        assert_eq!(
9046            shared.lock_inner().route_end_reason(9),
9047            RouteEndReason::Daemon(RouteCloseReason::Restart)
9048        );
9049        shared.control_push(
9050            br#"{"op":"route.closed","module_id":"provider","channels":[9],"reason":"crash"}"#,
9051        );
9052        assert_eq!(
9053            shared.lock_inner().route_end_reason(9),
9054            RouteEndReason::Daemon(RouteCloseReason::Crash)
9055        );
9056        shared.control_push(br#"{"op":"route.closed","module_id":"provider","reason":"disable"}"#);
9057        shared.install_ingress_handle(RouteHandle::new(7, 2, 1));
9058        assert_eq!(
9059            shared.lock_inner().route_end_reason(7),
9060            RouteEndReason::Unknown
9061        );
9062        assert_eq!(shared.lock_inner().route_end(7).terminal, None);
9063    }
9064
9065    #[test]
9066    fn legacy_route_push_falls_back_only_when_channels_are_absent() {
9067        let shared = reader_skew_tests::legacy_shared(PathBuf::new(), ConsumerOptions::default());
9068        shared
9069            .lock_inner()
9070            .route_modules
9071            .insert(7, "provider".into());
9072        shared.control_push(
9073            br#"{"op":"route.closed","module_id":"provider","channels":[],"reason":"crash"}"#,
9074        );
9075        assert_eq!(
9076            shared.lock_inner().route_end_reason(7),
9077            RouteEndReason::Unknown
9078        );
9079        shared.control_push(br#"{"op":"route.closing","module_id":"provider","reason":"restart"}"#);
9080        assert_eq!(
9081            shared.lock_inner().route_end_reason(7),
9082            RouteEndReason::Daemon(RouteCloseReason::Restart)
9083        );
9084        shared.control_push(br#"{"op":"route.closed","module_id":"provider","reason":"crash"}"#);
9085        assert_eq!(
9086            shared.lock_inner().route_end_reason(7),
9087            RouteEndReason::Daemon(RouteCloseReason::Crash)
9088        );
9089    }
9090
9091    #[tokio::test]
9092    async fn sdk_teardown_paths_attach_caller_and_connection_loss_reasons() {
9093        for local in [true, false] {
9094            let shared = Arc::new(reader_skew_tests::legacy_shared(
9095                PathBuf::new(),
9096                ConsumerOptions::default(),
9097            ));
9098            let (writer, _writer_rx) = mpsc::channel(8);
9099            shared.lock_inner().writer = Some(writer);
9100            shared.lock_inner().daemon_ver = "0.39.0".into();
9101            let handle = RouteHandle::new(7, 1, 1);
9102            shared.install_ingress_handle(handle);
9103            let (tx, rx) = oneshot::channel();
9104            let mut entry = PendingEntry::unary(tx, false, None, None);
9105            entry.accepted = true;
9106            shared.lock_inner().pending.insert(
9107                PendingKey {
9108                    generation: 1,
9109                    channel: 7,
9110                    epoch: 1,
9111                    corr: 1,
9112                },
9113                entry,
9114            );
9115            if local {
9116                shared
9117                    .close_handle(handle, &CloseRouteOptions::default())
9118                    .await
9119                    .unwrap();
9120            } else {
9121                shared.handle_generation_drop(1, "connection gone".into());
9122            }
9123            let err = rx.await.unwrap().into_call_result().err().unwrap();
9124            assert!(matches!(err, CallError::OutcomeUnknown(_)));
9125            assert_eq!(
9126                err.outcome_cause(),
9127                Some(if local {
9128                    OutcomeUnknownCause::RouteEnded
9129                } else {
9130                    OutcomeUnknownCause::ConnectionFailed
9131                })
9132            );
9133            let shared_failure = SharedCallFailure::from(err);
9134            let err = shared_failure.into_call_error();
9135            assert_eq!(
9136                err.close_reason(),
9137                Some(&if local {
9138                    RouteEndReason::ClosedByCaller
9139                } else {
9140                    RouteEndReason::ConnectionLost
9141                })
9142            );
9143            shared.close_sync("test complete");
9144        }
9145    }
9146
9147    #[tokio::test]
9148    async fn route_end_reasons_preserve_pending_retry_classes() {
9149        for reason in [
9150            RouteEndReason::ClosedByCaller,
9151            RouteEndReason::ConnectionLost,
9152            RouteEndReason::Daemon(RouteCloseReason::ScopeEnded),
9153            RouteEndReason::Unknown,
9154        ] {
9155            for accepted in [false, true] {
9156                let (tx, rx) = oneshot::channel();
9157                let mut entry = PendingEntry::unary(tx, false, None, None);
9158                entry.accepted = accepted;
9159                settle_route_pending_entries(vec![entry], "route ended".into(), reason.clone());
9160                let err = rx.await.unwrap().into_call_result().err().unwrap();
9161                assert_eq!(err.close_reason(), Some(&reason));
9162                assert_eq!(err.terminal(), None);
9163                assert_eq!(matches!(err, CallError::OutcomeUnknown(_)), accepted);
9164                assert_eq!(matches!(err, CallError::NotSent(_)), !accepted);
9165            }
9166        }
9167    }
9168
9169    #[test]
9170    fn route_closing_does_not_supply_or_overwrite_a_terminal_verdict() {
9171        let shared = Shared::new(PathBuf::new(), ConsumerOptions::default());
9172        shared.control_push(
9173            br#"{"op":"route.closing","channels":[7],"reason":"restart","terminal":true}"#,
9174        );
9175        assert_eq!(shared.lock_inner().route_end(7).terminal, None);
9176        shared.control_push(
9177            br#"{"op":"route.closed","channels":[7],"reason":"restart","terminal":false}"#,
9178        );
9179        shared.control_push(
9180            br#"{"op":"route.closing","channels":[7],"reason":"restart","terminal":true}"#,
9181        );
9182        assert_eq!(shared.lock_inner().route_end(7).terminal, Some(false));
9183        assert_eq!(CallError::not_sent("not a route end").terminal(), None);
9184    }
9185
9186    #[test]
9187    fn route_close_reason_classifier_accepts_capability_denied_and_fails_closed_for_unknown() {
9188        assert_eq!(
9189            RouteCloseReason::from_wire("capability_denied"),
9190            RouteCloseReason::CapabilityDenied
9191        );
9192        assert_eq!(
9193            RouteCloseReason::from_wire("capability_denied").disposition(),
9194            RouteCloseDisposition::MustNotReopen
9195        );
9196        assert_eq!(
9197            RouteCloseReason::from_wire("future_policy_reason").disposition(),
9198            RouteCloseDisposition::MustNotReopen,
9199            "an unknown close reason must receive the strictest handling"
9200        );
9201        assert_eq!(
9202            RouteCloseReason::from_wire("reload").disposition(),
9203            RouteCloseDisposition::MayReopen,
9204            "control proves the classifier can distinguish a conservative default"
9205        );
9206    }
9207
9208    #[tokio::test]
9209    async fn module_removed_fails_fast_while_module_reloading_retries_at_the_same_route_open_call_site(
9210    ) {
9211        // Serves rejections with `code` until the caller settles, returning
9212        // (attempts_served, result). The retryable arm must keep retrying past
9213        // any attempt count until the DEADLINE binds — the attempt cap in the
9214        // options below is deliberately tiny so a regression that re-couples
9215        // attempts into the retry condition (the 3.1s-effective-budget defect)
9216        // stops the loop at 2 and fails the `> 2` assertion by name.
9217        async fn reject_route_open_attempts(code: &str, deadline: Duration) -> (usize, CallError) {
9218            let shared = Arc::new(reader_skew_tests::legacy_shared(
9219                PathBuf::from("/tmp/does-not-exist"),
9220                ConsumerOptions::default(),
9221            ));
9222            let (writer, mut receiver) = mpsc::channel(4);
9223            {
9224                let mut inner = shared.lock_inner();
9225                inner.writer = Some(writer);
9226                inner.daemon_ver = "0.39.0".into();
9227            }
9228            let consumer = SubcConsumer {
9229                shared: Arc::clone(&shared),
9230            };
9231            let target = RouteTarget::ToolProvider {
9232                module_id: "retry-polarity".to_string(),
9233            };
9234            let identity = BindIdentity::new("test".to_string(), code.to_string());
9235            let options = CallOptions {
9236                timeout: Duration::from_secs(2),
9237                route_retry: RetryBackoff {
9238                    base: Duration::ZERO,
9239                    cap: Duration::ZERO,
9240                    max_attempts: 2,
9241                },
9242                route_retry_deadline: deadline,
9243                ..CallOptions::default()
9244            };
9245            let mut task =
9246                tokio::spawn(async move { consumer.open_route(target, identity, options).await });
9247
9248            let mut attempts = 0usize;
9249            let result = loop {
9250                tokio::select! {
9251                    command = receiver.recv() => {
9252                        // The consumer tears the writer down when the open
9253                        // settles, so a closed channel here means the task is
9254                        // finishing — join it rather than treating the race as
9255                        // a broken harness.
9256                        let Some(command) = command else {
9257                            break task.await.unwrap().expect_err("route.open must reject");
9258                        };
9259                        attempts += 1;
9260                        let body =
9261                            serde_json::to_vec(&ErrorBody::new(code, "test rejection")).unwrap();
9262                        assert!(
9263                            dispatch_frame(
9264                                &shared,
9265                                1,
9266                                Frame::build(
9267                                    FrameType::Error,
9268                                    Flags::new(false, Priority::Interactive, false),
9269                                    0,
9270                                    0,
9271                                    command.frame.header.corr,
9272                                    body,
9273                                )
9274                                .unwrap(),
9275                            )
9276                            .await
9277                        );
9278                    }
9279                    joined = &mut task => {
9280                        break joined.unwrap().expect_err("route.open must reject");
9281                    }
9282                }
9283            };
9284            assert!(
9285                receiver.try_recv().is_err(),
9286                "a settled route.open must not queue another attempt"
9287            );
9288            (attempts, result)
9289        }
9290
9291        let (reloading_attempts, reloading) =
9292            reject_route_open_attempts(error_codes::MODULE_RELOADING, Duration::from_millis(150))
9293                .await;
9294        assert!(matches!(reloading, CallError::NotSent(_)));
9295        assert!(
9296            reloading_attempts > 2,
9297            "reloading retries must run until the deadline, not an attempt cap \
9298             (served {reloading_attempts} attempts against max_attempts=2)"
9299        );
9300
9301        let (removed_attempts, removed) =
9302            reject_route_open_attempts(error_codes::MODULE_REMOVED, Duration::from_millis(150))
9303                .await;
9304        assert!(matches!(removed, CallError::NotSent(_)));
9305        assert_eq!(
9306            removed_attempts, 1,
9307            "terminal codes settle on the first answer"
9308        );
9309    }
9310
9311    /// splitmix64 over a counter: a seeded stand-in for the consumer's random
9312    /// source, so jittered delays are reproducible.
9313    fn seeded_random(seed: u64) -> Box<dyn Fn() -> f64 + Send + Sync> {
9314        let state = AtomicU64::new(seed);
9315        Box::new(move || {
9316            let mut z = state
9317                .fetch_add(0x9E37_79B9_7F4A_7C15, Ordering::Relaxed)
9318                .wrapping_add(0x9E37_79B9_7F4A_7C15);
9319            z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
9320            z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
9321            z ^= z >> 31;
9322            (z >> 11) as f64 / (1u64 << 53) as f64
9323        })
9324    }
9325
9326    /// A consumer wired to an in-memory writer, standing in for a daemon that
9327    /// the test answers by hand.
9328    fn route_open_stand_in(
9329        random_unit: Box<dyn Fn() -> f64 + Send + Sync>,
9330    ) -> (Arc<Shared>, Arc<SubcConsumer>, mpsc::Receiver<WriteCommand>) {
9331        let mut shared = reader_skew_tests::legacy_shared(
9332            PathBuf::from("/tmp/does-not-exist"),
9333            ConsumerOptions::default(),
9334        );
9335        shared.random_unit = random_unit;
9336        let shared = Arc::new(shared);
9337        let (writer, receiver) = mpsc::channel(64);
9338        shared.lock_inner().writer = Some(writer);
9339        shared.lock_inner().daemon_ver = "0.39.0".into();
9340        let consumer = Arc::new(SubcConsumer {
9341            shared: Arc::clone(&shared),
9342        });
9343        (shared, consumer, receiver)
9344    }
9345
9346    fn restart_target(module_id: &str) -> RouteTarget {
9347        RouteTarget::ToolProvider {
9348            module_id: module_id.to_string(),
9349        }
9350    }
9351
9352    fn restart_identity() -> BindIdentity {
9353        BindIdentity::new("test".to_string(), "restart".to_string())
9354    }
9355
9356    /// The daemon's answer to one route.open: accept it on `channel`, or refuse
9357    /// it with `refusal`.
9358    fn route_open_answer(corr: u64, channel: u16, refusal: Option<ErrorBody>) -> Frame {
9359        match refusal {
9360            None => response_frame(
9361                0,
9362                0,
9363                corr,
9364                serde_json::to_vec(&ClientControlResponse::RouteOpen {
9365                    request_window: None,
9366                    watch_window: None,
9367                    route_channel: channel,
9368                    route_epoch: 1,
9369                })
9370                .unwrap(),
9371            ),
9372            Some(body) => Frame::build(
9373                FrameType::Error,
9374                Flags::new(false, Priority::Interactive, false),
9375                0,
9376                0,
9377                corr,
9378                serde_json::to_vec(&body).unwrap(),
9379            )
9380            .unwrap(),
9381        }
9382    }
9383
9384    /// Answer every route.open the consumer writes, as `answer` decides from the
9385    /// open's target module, until `task` finishes.
9386    async fn answer_route_opens<T>(
9387        shared: &Arc<Shared>,
9388        receiver: &mut mpsc::Receiver<WriteCommand>,
9389        task: &mut JoinHandle<T>,
9390        mut answer: impl FnMut(&str) -> Option<ErrorBody>,
9391    ) -> T {
9392        let mut next_channel = 40u16;
9393        loop {
9394            tokio::select! {
9395                command = receiver.recv() => {
9396                    let Some(command) = command else {
9397                        return (&mut *task).await.unwrap();
9398                    };
9399                    let request: serde_json::Value =
9400                        serde_json::from_slice(&command.frame.body).unwrap();
9401                    let module_id = request["target"]["module_id"].as_str().unwrap().to_string();
9402                    next_channel += 1;
9403                    let frame = route_open_answer(
9404                        command.frame.header.corr,
9405                        next_channel,
9406                        answer(&module_id),
9407                    );
9408                    assert!(dispatch_frame(shared, 1, frame).await);
9409                }
9410                joined = &mut *task => return joined.unwrap(),
9411            }
9412        }
9413    }
9414
9415    fn reloading() -> ErrorBody {
9416        ErrorBody::new(error_codes::MODULE_RELOADING, "module is reloading")
9417    }
9418
9419    fn drain_call<'a>(
9420        consumer: &'a SubcConsumer,
9421        body: &'static [u8],
9422    ) -> impl Future<Output = Result<Vec<u8>, CallError>> + 'a {
9423        consumer.call(
9424            restart_target("plexus"),
9425            restart_identity(),
9426            body.to_vec(),
9427            CallOptions {
9428                timeout: Duration::from_secs(5),
9429                ..CallOptions::default()
9430            },
9431        )
9432    }
9433
9434    async fn refuse_during_drain(shared: &Arc<Shared>, request: &Frame) {
9435        let frame = Frame::build(
9436            FrameType::Error,
9437            request.header.flags,
9438            request.header.channel,
9439            request.header.epoch,
9440            request.header.corr,
9441            serde_json::to_vec(&reloading()).unwrap(),
9442        )
9443        .unwrap();
9444        assert!(dispatch_frame(shared, 1, frame).await);
9445    }
9446
9447    async fn reply_to_drain_call(shared: &Arc<Shared>, request: Frame) {
9448        assert_eq!(request.header.ty, FrameType::Request);
9449        assert!(
9450            dispatch_frame(
9451                shared,
9452                1,
9453                response_frame(
9454                    request.header.channel,
9455                    request.header.epoch,
9456                    request.header.corr,
9457                    request.body,
9458                ),
9459            )
9460            .await
9461        );
9462    }
9463
9464    #[tokio::test(start_paused = true)]
9465    async fn shared_route_drain_delivers_both_refusals_and_resends_both_calls() {
9466        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9467        let (_, old) = open_answered(
9468            &shared,
9469            &consumer,
9470            &mut receiver,
9471            None,
9472            41,
9473            "initial shared route",
9474        )
9475        .await;
9476        let mut seed = Box::pin(drain_call(&consumer, b"seed"));
9477        assert_pending(seed.as_mut()).await;
9478        reply_to_drain_call(&shared, receiver.recv().await.unwrap().frame).await;
9479        assert_eq!(seed.await.unwrap(), b"seed");
9480        shared.control_push(
9481            &serde_json::to_vec(&serde_json::json!({
9482                "op": "route.closing", "module_id": "plexus",
9483                "channels": [old.channel], "terminal": false
9484            }))
9485            .unwrap(),
9486        );
9487        let mut first = Box::pin(drain_call(&consumer, b"first"));
9488        let mut second = Box::pin(drain_call(&consumer, b"second"));
9489        assert_pending(first.as_mut()).await;
9490        assert_pending(second.as_mut()).await;
9491        let first_command = receiver.recv().await.unwrap();
9492        let second_command = receiver.recv().await.unwrap();
9493        // Observing a frame at the daemon means the real writer accepted it.
9494        assert!(shared.mark_pending_accepted(first_command.pending.unwrap()));
9495        assert!(shared.mark_pending_accepted(second_command.pending.unwrap()));
9496        let first_request = first_command.frame;
9497        let second_request = second_command.frame;
9498        assert_eq!(first_request.header.channel, old.channel);
9499        assert_eq!(second_request.header.channel, old.channel);
9500
9501        refuse_during_drain(&shared, &first_request).await;
9502        assert_pending(first.as_mut()).await;
9503        // Holding route.open unanswered is the barrier: the first call has
9504        // invalidated the old route before its sibling's refusal arrives.
9505        let (open_corr, _) = next_route_open(&mut receiver, "replacement route barrier").await;
9506        refuse_during_drain(&shared, &second_request).await;
9507        for (ty, channel, epoch, corr) in [
9508            (FrameType::Goodbye, old.channel, old.epoch, 0),
9509            (FrameType::Ping, 0, 0, 991),
9510        ] {
9511            let frame = Frame::build(
9512                ty,
9513                Flags::new(false, Priority::Interactive, false),
9514                channel,
9515                epoch,
9516                corr,
9517                Vec::new(),
9518            )
9519            .unwrap();
9520            assert!(dispatch_frame(&shared, 1, frame).await);
9521        }
9522        // The same dispatcher used by the socket reader emits Pong only after
9523        // processing the second refusal and the old-route GOODBYE.
9524        let pong = receiver.recv().await.unwrap().frame;
9525        assert_eq!(pong.header.ty, FrameType::Pong);
9526        assert_eq!(pong.header.corr, 991);
9527        assert_pending(second.as_mut()).await;
9528        assert!(dispatch_frame(&shared, 1, route_open_answer(open_corr, 42, None)).await);
9529        assert_pending(first.as_mut()).await;
9530        assert_pending(second.as_mut()).await;
9531        while let Ok(command) = receiver.try_recv() {
9532            assert_eq!(command.frame.header.channel, 42);
9533            reply_to_drain_call(&shared, command.frame).await;
9534        }
9535        assert_eq!(first.await.expect("first call resends"), b"first");
9536        assert_eq!(
9537            second.await.expect("second refusal must not time out"),
9538            b"second"
9539        );
9540        assert!(shared.lock_inner().pending.is_empty());
9541    }
9542
9543    #[tokio::test(start_paused = true)]
9544    async fn shared_route_drain_preserves_unrefused_reply_without_resending() {
9545        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9546        let (_, old) = open_answered(
9547            &shared,
9548            &consumer,
9549            &mut receiver,
9550            None,
9551            41,
9552            "initial shared route",
9553        )
9554        .await;
9555        let mut first = Box::pin(drain_call(&consumer, b"refused"));
9556        let mut second = Box::pin(drain_call(&consumer, b"executing"));
9557        assert_pending(first.as_mut()).await;
9558        assert_pending(second.as_mut()).await;
9559        let first_request = receiver.recv().await.unwrap().frame;
9560        let second_request = receiver.recv().await.unwrap().frame;
9561        let executing_corr = second_request.header.corr;
9562        assert_eq!(second_request.header.channel, old.channel);
9563        let mut executing_requests = 1;
9564
9565        refuse_during_drain(&shared, &first_request).await;
9566        assert_pending(first.as_mut()).await;
9567        let (open_corr, _) = next_route_open(&mut receiver, "replacement route barrier").await;
9568        assert_pending(second.as_mut()).await;
9569        assert!(dispatch_frame(&shared, 1, route_open_answer(open_corr, 42, None)).await);
9570        assert_pending(first.as_mut()).await;
9571        assert_pending(second.as_mut()).await;
9572        while let Ok(command) = receiver.try_recv() {
9573            assert_eq!(command.frame.header.ty, FrameType::Request);
9574            // Managed resends allocate a new corr; count the logical request's
9575            // body as well so an unsafe resend cannot hide behind a new corr.
9576            if command.frame.header.corr == executing_corr || command.frame.body == b"executing" {
9577                executing_requests += 1;
9578            }
9579            reply_to_drain_call(&shared, command.frame).await;
9580        }
9581        reply_to_drain_call(&shared, second_request).await;
9582        assert_eq!(first.await.expect("refused call resends"), b"refused");
9583        assert_eq!(
9584            second.await.expect("real old-route reply arrives"),
9585            b"executing"
9586        );
9587        assert_eq!(executing_requests, 1, "unrefused call must never resend");
9588    }
9589
9590    #[tokio::test(start_paused = true)]
9591    async fn invalidated_route_ingress_is_uninstalled_after_last_pending_settles() {
9592        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9593        let (_, old) = open_answered(
9594            &shared,
9595            &consumer,
9596            &mut receiver,
9597            None,
9598            41,
9599            "initial shared route",
9600        )
9601        .await;
9602        let mut first = Box::pin(drain_call(&consumer, b"first"));
9603        let mut second = Box::pin(drain_call(&consumer, b"second"));
9604        assert_pending(first.as_mut()).await;
9605        assert_pending(second.as_mut()).await;
9606        let first_request = receiver.recv().await.unwrap().frame;
9607        let second_request = receiver.recv().await.unwrap().frame;
9608        refuse_during_drain(&shared, &first_request).await;
9609        assert_pending(first.as_mut()).await;
9610        let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9611        assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), Some(old));
9612        assert!(route_reverse_request_registry(old.reverse_request_registry_id()).is_ok());
9613        reply_to_drain_call(&shared, second_request).await;
9614        assert_eq!(second.await.unwrap(), b"second");
9615        assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), None);
9616        assert!(shared.lock_inner().retired_routes.is_empty());
9617        assert!(route_reverse_request_registry(old.reverse_request_registry_id()).is_err());
9618        drop(first);
9619    }
9620
9621    #[tokio::test(start_paused = true)]
9622    async fn invalidated_route_ingress_cleans_up_on_drop_deadline_goodbye_and_disconnect() {
9623        for ending in ["drop", "deadline", "goodbye", "disconnect"] {
9624            let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9625            let (_, old) = open_answered(
9626                &shared,
9627                &consumer,
9628                &mut receiver,
9629                None,
9630                41,
9631                "initial shared route",
9632            )
9633            .await;
9634            let mut first = Box::pin(drain_call(&consumer, b"refused"));
9635            let mut second = Box::pin(drain_call(&consumer, b"executing"));
9636            assert_pending(first.as_mut()).await;
9637            assert_pending(second.as_mut()).await;
9638            let first_request = receiver.recv().await.unwrap().frame;
9639            let second_command = receiver.recv().await.unwrap();
9640            assert!(shared.mark_pending_accepted(second_command.pending.unwrap()));
9641            refuse_during_drain(&shared, &first_request).await;
9642            assert_pending(first.as_mut()).await;
9643            let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9644            match ending {
9645                "drop" => drop(second),
9646                "deadline" => {
9647                    assert_eq!(
9648                        second.await.unwrap_err().outcome_cause(),
9649                        Some(OutcomeUnknownCause::Deadline)
9650                    );
9651                }
9652                "goodbye" => {
9653                    let frame = Frame::build(
9654                        FrameType::Goodbye,
9655                        Flags::new(false, Priority::Interactive, false),
9656                        old.channel,
9657                        old.epoch,
9658                        0,
9659                        Vec::new(),
9660                    )
9661                    .unwrap();
9662                    assert!(dispatch_frame(&shared, 1, frame).await);
9663                    assert_eq!(
9664                        second.await.unwrap_err().outcome_cause(),
9665                        Some(OutcomeUnknownCause::RouteEnded)
9666                    );
9667                }
9668                "disconnect" => {
9669                    shared.handle_generation_drop(1, "test disconnect".into());
9670                    assert_eq!(
9671                        second.await.unwrap_err().outcome_cause(),
9672                        Some(OutcomeUnknownCause::ConnectionFailed)
9673                    );
9674                }
9675                _ => unreachable!(),
9676            }
9677            assert_eq!(
9678                shared.ingress_handle(1, old.channel, old.epoch),
9679                None,
9680                "{ending}"
9681            );
9682            assert!(shared.lock_inner().retired_routes.is_empty(), "{ending}");
9683            assert!(
9684                route_reverse_request_registry(old.reverse_request_registry_id()).is_err(),
9685                "{ending}"
9686            );
9687            drop(first);
9688        }
9689    }
9690
9691    #[tokio::test(start_paused = true)]
9692    async fn invalidated_route_subscription_cancel_and_overflow_uninstall_ingress() {
9693        for overflow in [false, true] {
9694            let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9695            let (_, old) = open_answered(
9696                &shared,
9697                &consumer,
9698                &mut receiver,
9699                None,
9700                41,
9701                "initial shared route",
9702            )
9703            .await;
9704            let mut subscription = consumer
9705                .subscribe_route(&old, b"watch".to_vec(), SubscribeOptions::default())
9706                .await
9707                .unwrap();
9708            let request = receiver.recv().await.unwrap().frame;
9709            let mut call = Box::pin(drain_call(&consumer, b"refused"));
9710            assert_pending(call.as_mut()).await;
9711            let refused = receiver.recv().await.unwrap().frame;
9712            refuse_during_drain(&shared, &refused).await;
9713            assert_pending(call.as_mut()).await;
9714            let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9715            assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), Some(old));
9716            assert!(matches!(
9717                consumer
9718                    .request(&old, b"new".to_vec(), CallOptions::default())
9719                    .await,
9720                Err(CallError::StaleRouteHandle(_))
9721            ));
9722            if overflow {
9723                for _ in 0..=DEFAULT_SUBSCRIPTION_EVENT_BUFFER {
9724                    assert!(
9725                        dispatch_frame(
9726                            &shared,
9727                            1,
9728                            watch_terminal(&request, FrameType::StreamData, vec![1])
9729                        )
9730                        .await
9731                    );
9732                }
9733                assert_eq!(subscription.ended().await, SubscriptionEnd::Backpressure);
9734            } else {
9735                subscription.unsubscribe().unwrap();
9736                assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
9737            }
9738            assert_eq!(
9739                receiver.recv().await.unwrap().frame.header.ty,
9740                FrameType::Cancel
9741            );
9742            assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), None);
9743            assert!(shared.lock_inner().retired_routes.is_empty());
9744            drop(call);
9745        }
9746    }
9747
9748    #[tokio::test(start_paused = true)]
9749    async fn the_default_retry_deadline_outlasts_a_60s_restart_and_the_open_succeeds() {
9750        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9751        let started = Instant::now();
9752        // A call deadline past the retry deadline, so the retry deadline is
9753        // the one under test.
9754        let options = CallOptions {
9755            timeout: Duration::from_secs(120),
9756            ..CallOptions::default()
9757        };
9758        let mut task = tokio::spawn(async move {
9759            consumer
9760                .open_route(restart_target("restarting"), restart_identity(), options)
9761                .await
9762        });
9763        let opened = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9764            (started.elapsed() < Duration::from_secs(60)).then(reloading)
9765        })
9766        .await;
9767        let handle =
9768            opened.unwrap_or_else(|err| panic!("the open must survive the restart: {err}"));
9769        assert!(handle.channel > 40);
9770        assert!(started.elapsed() >= Duration::from_secs(60));
9771    }
9772
9773    #[tokio::test(start_paused = true)]
9774    async fn a_call_timeout_shorter_than_the_retry_deadline_ends_the_retries_at_the_call_timeout() {
9775        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(2));
9776        let started = Instant::now();
9777        let options = CallOptions {
9778            timeout: Duration::from_secs(10),
9779            ..CallOptions::default()
9780        };
9781        let mut task = tokio::spawn(async move {
9782            consumer
9783                .open_route(restart_target("restarting"), restart_identity(), options)
9784                .await
9785        });
9786        let err = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9787            (started.elapsed() < Duration::from_secs(60)).then(reloading)
9788        })
9789        .await
9790        .expect_err("the call timeout must end the retries before the module is back");
9791        let elapsed = started.elapsed();
9792        assert!(matches!(err, CallError::NotSent(_)), "got {err:?}");
9793        assert!(
9794            elapsed >= Duration::from_secs(9) && elapsed <= Duration::from_secs(10),
9795            "the retries must stop at the 10s call timeout, stopped after {elapsed:?}"
9796        );
9797    }
9798
9799    #[tokio::test(start_paused = true)]
9800    async fn two_routes_refused_together_retry_at_different_jittered_times() {
9801        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(42));
9802        let started = Instant::now();
9803        let mut task = tokio::spawn(async move {
9804            let alpha = consumer.open_route(
9805                restart_target("alpha"),
9806                restart_identity(),
9807                CallOptions::default(),
9808            );
9809            let beta = consumer.open_route(
9810                restart_target("beta"),
9811                restart_identity(),
9812                CallOptions::default(),
9813            );
9814            let (alpha, beta) = tokio::join!(alpha, beta);
9815            (alpha.is_ok(), beta.is_ok())
9816        });
9817        let mut first_open = HashMap::<String, Duration>::new();
9818        let mut retried_at = HashMap::<String, Duration>::new();
9819        let opened = answer_route_opens(&shared, &mut receiver, &mut task, |module_id| {
9820            let at = started.elapsed();
9821            if first_open.contains_key(module_id) {
9822                retried_at.insert(module_id.to_string(), at);
9823                None
9824            } else {
9825                first_open.insert(module_id.to_string(), at);
9826                Some(reloading())
9827            }
9828        })
9829        .await;
9830        assert_eq!(opened, (true, true));
9831        assert_eq!(first_open["alpha"], first_open["beta"], "refused together");
9832        // Equal jitter keeps half of the 100ms base delay and randomizes the rest.
9833        for at in retried_at.values() {
9834            assert!(
9835                *at >= Duration::from_millis(50) && *at <= Duration::from_millis(100),
9836                "retry at {at:?} is outside the jitter window"
9837            );
9838        }
9839        assert_ne!(
9840            retried_at["alpha"], retried_at["beta"],
9841            "routes refused together must not retry in lock step"
9842        );
9843    }
9844
9845    #[tokio::test(start_paused = true)]
9846    async fn twenty_concurrent_opens_never_have_more_than_eight_outstanding_at_the_daemon() {
9847        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(3));
9848        let mut task = tokio::spawn(async move {
9849            let mut opens = tokio::task::JoinSet::new();
9850            for i in 0..20 {
9851                let consumer = Arc::clone(&consumer);
9852                opens.spawn(async move {
9853                    consumer
9854                        .open_route(
9855                            restart_target(&format!("module-{i}")),
9856                            restart_identity(),
9857                            CallOptions::default(),
9858                        )
9859                        .await
9860                });
9861            }
9862            let mut opened = 0usize;
9863            while let Some(result) = opens.join_next().await {
9864                result.unwrap().unwrap();
9865                opened += 1;
9866            }
9867            opened
9868        });
9869        // Hold every open until the consumer has gone quiet, so everything it
9870        // is willing to send at once is outstanding together; then answer them.
9871        let mut held = Vec::new();
9872        let mut max_outstanding = 0usize;
9873        let mut next_channel = 40u16;
9874        let opened = loop {
9875            tokio::select! {
9876                command = receiver.recv() => {
9877                    // The writer closes when the last consumer handle drops,
9878                    // which means every open has settled.
9879                    let Some(command) = command else {
9880                        break (&mut task).await.unwrap();
9881                    };
9882                    held.push(command.frame.header.corr);
9883                    max_outstanding = max_outstanding.max(held.len());
9884                }
9885                () = sleep(Duration::from_millis(25)), if !held.is_empty() => {
9886                    for corr in held.drain(..) {
9887                        next_channel += 1;
9888                        assert!(dispatch_frame(&shared, 1, route_open_answer(corr, next_channel, None)).await);
9889                    }
9890                }
9891                joined = &mut task => break joined.unwrap(),
9892            }
9893        };
9894        assert_eq!(opened, 20);
9895        assert_eq!(max_outstanding, MAX_ROUTE_OPENS_IN_FLIGHT);
9896    }
9897
9898    #[tokio::test(start_paused = true)]
9899    async fn an_exhausted_deadline_names_module_reloading_not_the_later_admission_pressure() {
9900        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(4));
9901        let options = CallOptions {
9902            route_retry_deadline: Duration::from_secs(5),
9903            ..CallOptions::default()
9904        };
9905        let mut task = tokio::spawn(async move {
9906            consumer
9907                .open_route(restart_target("restarting"), restart_identity(), options)
9908                .await
9909        });
9910        let mut opens = 0usize;
9911        let err = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9912            opens += 1;
9913            Some(if opens <= 2 {
9914                reloading().with_detail(serde_json::json!({ "reason": "restart" }))
9915            } else {
9916                ErrorBody::new(
9917                    error_codes::TARGET_UNAVAILABLE,
9918                    "connection already has 8 route.open binds in flight (limit 8); retry after one settles",
9919                )
9920            })
9921        })
9922        .await
9923        .expect_err("the module never comes back");
9924        assert!(opens > 2);
9925        assert!(matches!(err, CallError::NotSent(_)), "got {err:?}");
9926        assert_eq!(
9927            err.route_open_refusal().map(|body| body.code.as_str()),
9928            Some(error_codes::MODULE_RELOADING)
9929        );
9930        let message = err.to_string();
9931        assert!(
9932            message.starts_with(
9933                "request not sent: route.open failed for target tool_provider:restarting: \
9934                 module_reloading (reason restart) (module is reloading); \
9935                 the most recent refusal was target_unavailable"
9936            ),
9937            "got {message}"
9938        );
9939    }
9940
9941    #[tokio::test]
9942    async fn close_route_flips_inflight_opening_so_a_racing_open_discards() {
9943        // The load-bearing close-beats-reopen guard, in isolation: a close that lands
9944        // while a route.open is in flight (channel not yet cached) must flip the
9945        // opening's `closed` flag, so the lead opener re-checks it before installing and
9946        // GOODBYEs the channel it opened instead of caching it.
9947        let shared = Arc::new(reader_skew_tests::legacy_shared(
9948            PathBuf::from("/tmp/does-not-exist"),
9949            ConsumerOptions::default(),
9950        ));
9951        let key = RouteKey::new(
9952            &RouteTarget::ToolProvider {
9953                module_id: "m".into(),
9954            },
9955            &BindIdentity::new("h", "s"),
9956            None,
9957            None,
9958        );
9959        // Simulate an in-flight lead open: an openings entry exists, not yet closed,
9960        // with no cached route (channel hasn't been installed yet).
9961        shared.lock_inner().openings.insert(
9962            key.clone(),
9963            Opening {
9964                waiters: Vec::new(),
9965                closed: false,
9966            },
9967        );
9968
9969        // close_route with no cached route is an idempotent no-op on routes, but MUST
9970        // flip the in-flight opening's flag so the racing open discards.
9971        shared
9972            .close_route(&key, &CloseRouteOptions::default())
9973            .await;
9974        assert!(
9975            shared
9976                .lock_inner()
9977                .openings
9978                .get(&key)
9979                .is_some_and(|o| o.closed),
9980            "close_route must flip the in-flight opening's closed flag (close-beats-reopen)"
9981        );
9982
9983        // And closing a key with neither a route nor an in-flight open is a no-op.
9984        let absent = RouteKey::new(
9985            &RouteTarget::ToolProvider {
9986                module_id: "absent".into(),
9987            },
9988            &BindIdentity::new("h", "s"),
9989            None,
9990            None,
9991        );
9992        shared
9993            .close_route(&absent, &CloseRouteOptions::default())
9994            .await;
9995    }
9996
9997    #[test]
9998    fn route_key_is_structured() {
9999        let target = RouteTarget::InternalService {
10000            module_id: "a\0b".into(),
10001            service_id: "svc".into(),
10002        };
10003        let identity = BindIdentity::new("h", "s");
10004        let key = RouteKey::new(&target, &identity, None, None);
10005        assert!(matches!(key.target, RouteTargetKey::InternalService { .. }));
10006    }
10007
10008    async fn assert_pending(mut future: Pin<&mut (impl Future + ?Sized)>) {
10009        assert!(
10010            std::future::poll_fn(|cx| Poll::Ready(future.as_mut().poll(cx).is_pending())).await
10011        );
10012    }
10013
10014    /// Replace only the transport, leaving the actual generation-drop cleanup in use.
10015    fn drop_and_replace_test_transport(shared: &Arc<Shared>) -> mpsc::Receiver<WriteCommand> {
10016        let generation = shared.lock_inner().generation;
10017        // Keep the background supervisor from touching a real connection file.
10018        shared.lock_inner().reconnect = ReconnectState::Inline { generation };
10019        shared.handle_generation_drop(generation, "test connection drop".into());
10020        let (writer, receiver) = mpsc::channel(64);
10021        let mut inner = shared.lock_inner();
10022        inner.generation += 1;
10023        inner.epoch += 1;
10024        inner.next_corr = Some(1);
10025        inner.writer = Some(writer);
10026        inner.daemon_ver = "0.39.0".into();
10027        inner.reconnect = ReconnectState::Idle;
10028        receiver
10029    }
10030
10031    #[tokio::test(start_paused = true)]
10032    async fn route_open_single_flight_survives_generation_drop_during_backoff() {
10033        let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
10034        let opts = CallOptions::default();
10035        let opener = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10036        tokio::pin!(opener);
10037        assert_pending(opener.as_mut()).await;
10038        let first = receiver.try_recv().unwrap();
10039        assert!(
10040            dispatch_frame(
10041                &shared,
10042                1,
10043                route_open_answer(first.frame.header.corr, 0, Some(reloading())),
10044            )
10045            .await
10046        );
10047        assert_pending(opener.as_mut()).await;
10048
10049        // A caller already waiting and one arriving after the drop must both stay
10050        // behind the same lead opener, including its unfinished retry backoff.
10051        let waiting = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10052        tokio::pin!(waiting);
10053        assert_pending(waiting.as_mut()).await;
10054        let mut receiver = drop_and_replace_test_transport(&shared);
10055        assert_pending(waiting.as_mut()).await;
10056        let arriving = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10057        tokio::pin!(arriving);
10058        assert_pending(arriving.as_mut()).await;
10059        assert!(
10060            receiver.try_recv().is_err(),
10061            "a second opener bypassed the backoff"
10062        );
10063
10064        tokio::time::advance(opts.route_retry.base).await;
10065        assert_pending(opener.as_mut()).await;
10066        let retry = receiver.try_recv().unwrap();
10067        assert!(
10068            dispatch_frame(
10069                &shared,
10070                2,
10071                route_open_answer(retry.frame.header.corr, 42, None),
10072            )
10073            .await
10074        );
10075        let handle = opener.await.unwrap();
10076        assert_eq!(waiting.await.unwrap(), handle);
10077        assert_eq!(arriving.await.unwrap(), handle);
10078        assert!(
10079            receiver.try_recv().is_err(),
10080            "more than one retry was emitted"
10081        );
10082        let inner = shared.lock_inner();
10083        assert!(inner.openings.is_empty());
10084        assert_eq!(inner.routes.len(), 1);
10085        assert_eq!(inner.route_epochs.len(), 1);
10086    }
10087
10088    #[tokio::test(start_paused = true)]
10089    async fn close_route_during_backoff_survives_generation_drop() {
10090        let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
10091        let opts = CallOptions::default();
10092        let opener = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10093        tokio::pin!(opener);
10094        assert_pending(opener.as_mut()).await;
10095        let first = receiver.try_recv().unwrap();
10096        assert!(
10097            dispatch_frame(
10098                &shared,
10099                1,
10100                route_open_answer(first.frame.header.corr, 0, Some(reloading())),
10101            )
10102            .await
10103        );
10104        assert_pending(opener.as_mut()).await;
10105        consumer
10106            .close_route(
10107                restart_target("m"),
10108                restart_identity(),
10109                CloseRouteOptions::default(),
10110            )
10111            .await;
10112        let mut receiver = drop_and_replace_test_transport(&shared);
10113        tokio::time::advance(opts.route_retry.base).await;
10114        assert_pending(opener.as_mut()).await;
10115        let retry = receiver.try_recv().unwrap();
10116        assert!(
10117            dispatch_frame(
10118                &shared,
10119                2,
10120                route_open_answer(retry.frame.header.corr, 42, None),
10121            )
10122            .await
10123        );
10124        let err = opener.await.expect_err("close must win over the retry");
10125        assert!(matches!(err, CallError::NotSent(_)));
10126        let goodbye = receiver
10127            .try_recv()
10128            .expect("discarded route must get GOODBYE");
10129        assert_eq!(goodbye.frame.header.ty, FrameType::Goodbye);
10130        assert_eq!(goodbye.frame.header.channel, 42);
10131        assert!(receiver.try_recv().is_err());
10132        let inner = shared.lock_inner();
10133        assert!(inner.routes.is_empty());
10134        assert!(inner.route_epochs.is_empty());
10135        assert!(inner.openings.is_empty());
10136    }
10137
10138    fn route_teardown_stand_in() -> (
10139        Arc<Shared>,
10140        SubcConsumer,
10141        mpsc::Receiver<WriteCommand>,
10142        tokio::io::DuplexStream,
10143        RouteKey,
10144        RouteState,
10145    ) {
10146        let shared = writer_test_shared();
10147        let (stream, peer) = tokio::io::duplex(1024);
10148        shared
10149            .install_initial(OpenedConnection {
10150                stream: Box::new(stream),
10151                daemon_origin_trusted: true,
10152                daemon_ver: "0.39.0".into(),
10153            })
10154            .unwrap();
10155        let (writer, rx) = mpsc::channel(1);
10156        writer
10157            .try_send(WriteCommand {
10158                frame: response_frame(0, 0, 99, b"filler".to_vec()),
10159                pending: None,
10160            })
10161            .unwrap();
10162        let key = RouteKey::new(&restart_target("teardown"), &restart_identity(), None, None);
10163        let route = RouteState {
10164            handle: RouteHandle::new(17, 23, 1),
10165            sem: Arc::new(Semaphore::new(1)),
10166            watch_sem: None,
10167            opted_in: false,
10168        };
10169        {
10170            let mut inner = shared.lock_inner();
10171            inner.writer = Some(writer);
10172            inner.cache_route(key.clone(), route.clone());
10173        }
10174        let consumer = SubcConsumer {
10175            shared: Arc::clone(&shared),
10176        };
10177        (shared, consumer, rx, peer, key, route)
10178    }
10179
10180    async fn assert_reopened_request_after_goodbye(
10181        shared: &Arc<Shared>,
10182        consumer: &SubcConsumer,
10183        rx: &mut mpsc::Receiver<WriteCommand>,
10184        old: RouteHandle,
10185    ) {
10186        let reopened = RouteHandle::new(old.channel, old.epoch + 1, old.connection_token());
10187        shared
10188            .install_one_shot_route(RouteState {
10189                handle: reopened,
10190                sem: Arc::new(Semaphore::new(1)),
10191                watch_sem: None,
10192                opted_in: false,
10193            })
10194            .unwrap();
10195        let request = consumer.request(&reopened, b"reopened".to_vec(), CallOptions::default());
10196        tokio::pin!(request);
10197        assert_pending(request.as_mut()).await;
10198        let command = rx.recv().await.unwrap();
10199        assert_eq!(command.frame.header.ty, FrameType::Goodbye);
10200        assert_eq!(
10201            (command.frame.header.channel, command.frame.header.epoch),
10202            (old.channel, old.epoch)
10203        );
10204        assert_pending(request.as_mut()).await;
10205        let command = rx.recv().await.unwrap();
10206        assert_eq!(command.frame.header.ty, FrameType::Request);
10207        assert_eq!(command.frame.header.channel, reopened.channel);
10208        assert_eq!(command.frame.header.epoch, reopened.epoch);
10209        dispatch_frame(
10210            shared,
10211            reopened.connection_token(),
10212            response_frame(
10213                reopened.channel,
10214                reopened.epoch,
10215                command.frame.header.corr,
10216                Vec::new(),
10217            ),
10218        )
10219        .await;
10220        request.await.unwrap();
10221    }
10222
10223    #[tokio::test]
10224    async fn route_teardown_close_waits_for_goodbye_before_channel_reuse() {
10225        for by_handle in [false, true] {
10226            let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10227            let close = async {
10228                if by_handle {
10229                    consumer
10230                        .close_handle(&route.handle, CloseRouteOptions::default())
10231                        .await
10232                        .unwrap();
10233                } else {
10234                    consumer
10235                        .close_route(
10236                            restart_target("teardown"),
10237                            restart_identity(),
10238                            CloseRouteOptions::default(),
10239                        )
10240                        .await;
10241                }
10242            };
10243            tokio::pin!(close);
10244            assert_pending(close.as_mut()).await;
10245            assert!(route.sem.is_closed());
10246            assert!(!shared.lock_inner().routes.contains_key(&key));
10247            assert_eq!(
10248                shared.lock_inner().route_epochs.get(&route.handle.channel),
10249                Some(&route.handle)
10250            );
10251            let mut reopened = route.clone();
10252            reopened.handle = RouteHandle::new(route.handle.channel, route.handle.epoch + 1, 1);
10253            assert!(shared.install_one_shot_route(reopened).is_err());
10254            assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10255            close.await;
10256            assert_reopened_request_after_goodbye(&shared, &consumer, &mut rx, route.handle).await;
10257            consumer.close().await;
10258        }
10259    }
10260
10261    #[tokio::test]
10262    async fn route_teardown_retirement_waits_for_goodbye_before_channel_reuse() {
10263        let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10264        shared.invalidate_route_with_deadline(&key, Some(route.handle), true);
10265        assert!(route.sem.is_closed());
10266        assert_eq!(
10267            shared.lock_inner().route_epochs.get(&route.handle.channel),
10268            Some(&route.handle)
10269        );
10270        let mut reopened = route.clone();
10271        reopened.handle = RouteHandle::new(route.handle.channel, route.handle.epoch + 1, 1);
10272        assert!(shared.install_one_shot_route(reopened).is_err());
10273        assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10274        tokio::time::timeout(Duration::from_secs(1), async {
10275            while shared
10276                .lock_inner()
10277                .route_epochs
10278                .contains_key(&route.handle.channel)
10279            {
10280                tokio::task::yield_now().await;
10281            }
10282        })
10283        .await
10284        .expect("retirement must queue its GOODBYE after writer capacity frees");
10285        assert_reopened_request_after_goodbye(&shared, &consumer, &mut rx, route.handle).await;
10286        consumer.close().await;
10287    }
10288
10289    #[tokio::test]
10290    async fn route_teardown_retirements_flush_in_order() {
10291        let (shared, consumer, mut rx, _peer, first_key, first) = route_teardown_stand_in();
10292        let second_key = RouteKey::new(&restart_target("second"), &restart_identity(), None, None);
10293        let mut second = first.clone();
10294        second.handle = RouteHandle::new(first.handle.channel + 1, 31, 1);
10295        shared
10296            .lock_inner()
10297            .cache_route(second_key.clone(), second.clone());
10298        shared.invalidate_route_with_deadline(&first_key, Some(first.handle), true);
10299        shared.invalidate_route_with_deadline(&second_key, Some(second.handle), true);
10300        assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10301        for handle in [first.handle, second.handle] {
10302            let command = tokio::time::timeout(Duration::from_secs(1), rx.recv())
10303                .await
10304                .unwrap()
10305                .unwrap();
10306            assert_eq!(command.frame.header.ty, FrameType::Goodbye);
10307            assert_eq!(
10308                (command.frame.header.channel, command.frame.header.epoch),
10309                (handle.channel, handle.epoch)
10310            );
10311            assert!(!shared
10312                .lock_inner()
10313                .route_epochs
10314                .contains_key(&handle.channel));
10315        }
10316        assert!(shared.lock_inner().retirement_queue.is_empty());
10317        assert!(shared.lock_inner().retirement_goodbyes.is_empty());
10318        assert!(rx.try_recv().is_err());
10319        consumer.close().await;
10320    }
10321
10322    #[tokio::test]
10323    async fn route_teardown_dead_connection_ends_writer_wait_and_discards_retirements() {
10324        for death in 0..3 {
10325            let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10326            let opts = CloseRouteOptions::default();
10327            let close = shared.close_route(&key, &opts);
10328            tokio::pin!(close);
10329            assert_pending(close.as_mut()).await;
10330            match death {
10331                0 => rx.close(),
10332                1 => shared.handle_generation_drop(1, "test connection lost".into()),
10333                _ => shared.close_sync("test connection closed"),
10334            }
10335            tokio::time::timeout(Duration::from_secs(1), close)
10336                .await
10337                .unwrap();
10338            assert!(!shared
10339                .lock_inner()
10340                .route_epochs
10341                .contains_key(&route.handle.channel));
10342            assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10343            assert!(rx.try_recv().is_err());
10344            consumer.close().await;
10345
10346            let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10347            shared.invalidate_route_with_deadline(&key, Some(route.handle), true);
10348            if death == 1 {
10349                shared.handle_generation_drop(1, "test connection lost".into());
10350            } else {
10351                consumer.close().await;
10352            }
10353            assert!(shared.lock_inner().retirement_queue.is_empty());
10354            assert!(shared.lock_inner().retirement_goodbyes.is_empty());
10355            assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10356            assert!(rx.try_recv().is_err());
10357            consumer.close().await;
10358        }
10359    }
10360
10361    #[tokio::test]
10362    async fn route_channel_index_tracks_lookup_close_and_generation_drop() {
10363        let shared = writer_test_shared();
10364        let (writer, _rx) = mpsc::channel(32);
10365        let mut expected = Vec::new();
10366        {
10367            let mut inner = shared.lock_inner();
10368            inner.writer = Some(writer);
10369            inner.daemon_ver = "0.39.0".into();
10370            for channel in 1..=8 {
10371                let key = RouteKey::new(
10372                    &RouteTarget::ToolProvider {
10373                        module_id: format!("module-{channel}"),
10374                    },
10375                    &BindIdentity::new("test", format!("session-{channel}")),
10376                    None,
10377                    None,
10378                );
10379                let route = RouteState {
10380                    handle: RouteHandle::new(channel, channel.into(), 1),
10381                    sem: Arc::new(Semaphore::new(DEFAULT_ROUTE_WINDOW)),
10382                    watch_sem: None,
10383                    opted_in: false,
10384                };
10385                inner.cache_route(key.clone(), route.clone());
10386                expected.push((key, route));
10387            }
10388        }
10389
10390        for (key, expected_route) in &expected {
10391            let resolved = shared
10392                .route_state(expected_route.handle)
10393                .expect("an indexed route handle should resolve");
10394            assert_eq!(resolved.handle, expected_route.handle);
10395            assert!(Arc::ptr_eq(&resolved.sem, &expected_route.sem));
10396
10397            let inner = shared.lock_inner();
10398            assert_eq!(
10399                inner.route_by_channel.get(&expected_route.handle.channel),
10400                Some(key)
10401            );
10402            assert_eq!(
10403                inner.route_epochs.get(&expected_route.handle.channel),
10404                Some(&expected_route.handle)
10405            );
10406            assert!(inner
10407                .routes
10408                .get(key)
10409                .is_some_and(|route| route.handle == expected_route.handle));
10410        }
10411
10412        let (closed_key, closed_route) = &expected[3];
10413        shared
10414            .close_route(closed_key, &CloseRouteOptions::default())
10415            .await;
10416        {
10417            let inner = shared.lock_inner();
10418            assert!(!inner.routes.contains_key(closed_key));
10419            assert!(!inner
10420                .route_by_channel
10421                .contains_key(&closed_route.handle.channel));
10422            assert!(!inner
10423                .route_epochs
10424                .contains_key(&closed_route.handle.channel));
10425        }
10426        assert!(matches!(
10427            shared.route_state(closed_route.handle),
10428            Err(CallError::StaleRouteHandle(handle)) if handle == closed_route.handle
10429        ));
10430
10431        shared.handle_generation_drop(1, "test generation dropped".into());
10432        {
10433            let inner = shared.lock_inner();
10434            assert!(inner.routes.is_empty());
10435            assert!(inner.route_by_channel.is_empty());
10436            assert!(inner.route_epochs.is_empty());
10437        }
10438        shared.close_sync("test complete");
10439    }
10440
10441    #[tokio::test]
10442    async fn stale_push_is_not_delivered_after_connection_generation_changes() {
10443        let shared = writer_test_shared();
10444        let old_handle = RouteHandle::new(7, 1, 1);
10445        let (writer, _writer_rx) = mpsc::channel(1);
10446        {
10447            let mut inner = shared.lock_inner();
10448            inner.writer = Some(writer);
10449            inner.daemon_ver = "0.39.0".into();
10450            inner.route_epochs.insert(old_handle.channel, old_handle);
10451        }
10452        let mut pushes = shared
10453            .register_push_events(old_handle)
10454            .expect("the old live route should accept a receiver");
10455
10456        {
10457            let mut inner = shared.lock_inner();
10458            inner.generation = 2;
10459            inner.close_routes();
10460            inner.route_epochs.clear();
10461            inner.route_modules.clear();
10462            inner.route_end_reasons.clear();
10463            inner.legacy_channel_reasons.clear();
10464        }
10465        shared.route_push(old_handle, b"stale".to_vec());
10466
10467        assert!(
10468            pushes.recv().await.is_none(),
10469            "connection teardown must end the old receiver before a stale Push can arrive"
10470        );
10471        shared.close_sync("test complete");
10472    }
10473
10474    #[test]
10475    fn route_key_canonicalizes_consumer_capabilities() {
10476        let target = RouteTarget::ToolProvider {
10477            module_id: "aft".into(),
10478        };
10479        let identity = BindIdentity::new("h", "s");
10480        let left = RouteKey::new(
10481            &target,
10482            &identity,
10483            None,
10484            Some(&["sampling".to_string(), "elicitation".to_string()]),
10485        );
10486        let right = RouteKey::new(
10487            &target,
10488            &identity,
10489            None,
10490            Some(&[
10491                "elicitation".to_string(),
10492                "sampling".to_string(),
10493                "sampling".to_string(),
10494            ]),
10495        );
10496        assert_eq!(left, right);
10497    }
10498
10499    #[tokio::test]
10500    async fn routes_with_and_without_declared_consumer_capabilities_are_kept_apart() {
10501        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(10));
10502        let (undeclared_request, undeclared) = open_answered_with(
10503            &shared,
10504            &consumer,
10505            &mut receiver,
10506            CallOptions::default(),
10507            74,
10508            "the undeclared route opens first",
10509        )
10510        .await;
10511        assert!(undeclared_request.get("consumer_capabilities").is_none());
10512
10513        let declared_opts = CallOptions::default()
10514            .with_consumer_capability("tool-result/v1")
10515            .unwrap();
10516        let (declared_request, declared) = open_answered_with(
10517            &shared,
10518            &consumer,
10519            &mut receiver,
10520            declared_opts.clone(),
10521            75,
10522            "a declared open must not reuse the undeclared route",
10523        )
10524        .await;
10525        assert_eq!(
10526            declared_request["consumer_capabilities"],
10527            serde_json::json!(["tool-result/v1"])
10528        );
10529        assert_ne!(undeclared, declared);
10530
10531        assert_eq!(
10532            consumer
10533                .open_route(restart_target("plexus"), restart_identity(), declared_opts)
10534                .await
10535                .unwrap(),
10536            declared,
10537            "the same declaration must reuse its cached route"
10538        );
10539        assert_eq!(
10540            consumer
10541                .open_route(
10542                    restart_target("plexus"),
10543                    restart_identity(),
10544                    CallOptions::default(),
10545                )
10546                .await
10547                .unwrap(),
10548            undeclared,
10549            "an undeclared open must continue to reuse only its own route"
10550        );
10551        assert!(
10552            receiver.try_recv().is_err(),
10553            "both subsequent opens are cache hits"
10554        );
10555        shared.close_sync("test complete");
10556    }
10557
10558    fn scope_selector(owner: &str, scope_ref: &str, scope_epoch: u64) -> ScopeSelector {
10559        ScopeSelector::new(
10560            subc_protocol::Principal::Reserved {
10561                module_id: owner.to_string(),
10562            },
10563            scope_ref.to_string(),
10564            Some(scope_epoch),
10565        )
10566    }
10567
10568    #[test]
10569    fn route_key_separates_scopes_by_owner_ref_and_epoch_and_from_unscoped() {
10570        let target = RouteTarget::ToolProvider {
10571            module_id: "plexus".into(),
10572        };
10573        let identity = BindIdentity::new("h", "s");
10574        let key = |scope: Option<ScopeSelector>| {
10575            RouteKey::new(&target, &identity, None, None).with_scope(scope.as_ref())
10576        };
10577        let base = key(Some(scope_selector("owner", "session-a", 1)));
10578        assert_eq!(base, key(Some(scope_selector("owner", "session-a", 1))));
10579        for (label, other) in [
10580            ("epoch", key(Some(scope_selector("owner", "session-a", 2)))),
10581            ("ref", key(Some(scope_selector("owner", "session-b", 1)))),
10582            ("owner", key(Some(scope_selector("other", "session-a", 1)))),
10583            ("unscoped", key(None)),
10584        ] {
10585            assert_ne!(base, other, "a different {label} must be a different route");
10586        }
10587        let mut no_epoch = scope_selector("owner", "session-a", 1);
10588        no_epoch.scope_epoch = None;
10589        assert_ne!(base, key(Some(no_epoch)));
10590    }
10591
10592    /// The next route.open the consumer writes, skipping any other frame
10593    /// (a GOODBYE, a cancel). Fails the test by name if none arrives, which is
10594    /// what a cache hit that should have been a miss looks like.
10595    async fn next_route_open(
10596        receiver: &mut mpsc::Receiver<WriteCommand>,
10597        why: &str,
10598    ) -> (u64, serde_json::Value) {
10599        loop {
10600            let command = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
10601                .await
10602                .unwrap_or_else(|_| panic!("no route.open was sent: {why}"))
10603                .expect("writer channel open");
10604            if command.frame.header.channel != 0 || command.frame.header.ty != FrameType::Request {
10605                continue;
10606            }
10607            let request: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
10608            if request["op"] == "route.open" {
10609                return (command.frame.header.corr, request);
10610            }
10611        }
10612    }
10613
10614    /// Open a route (scoped when `scope` is set) through the stand-in daemon,
10615    /// accept its route.open on `channel`, and return the open's body and handle.
10616    async fn open_answered(
10617        shared: &Arc<Shared>,
10618        consumer: &Arc<SubcConsumer>,
10619        receiver: &mut mpsc::Receiver<WriteCommand>,
10620        scope: Option<ScopeSelector>,
10621        channel: u16,
10622        why: &str,
10623    ) -> (serde_json::Value, RouteHandle) {
10624        let consumer = Arc::clone(consumer);
10625        let task = tokio::spawn(async move {
10626            match scope {
10627                Some(scope) => {
10628                    consumer
10629                        .open_route_scoped(
10630                            restart_target("plexus"),
10631                            restart_identity(),
10632                            scope,
10633                            CallOptions::default(),
10634                        )
10635                        .await
10636                }
10637                None => {
10638                    consumer
10639                        .open_route(
10640                            restart_target("plexus"),
10641                            restart_identity(),
10642                            CallOptions::default(),
10643                        )
10644                        .await
10645                }
10646            }
10647        });
10648        let (corr, request) = next_route_open(receiver, why).await;
10649        assert!(dispatch_frame(shared, 1, route_open_answer(corr, channel, None)).await);
10650        let handle = task.await.unwrap().expect("the stand-in accepted the open");
10651        (request, handle)
10652    }
10653
10654    /// Open an unscoped `plexus` route with `opts` through the stand-in
10655    /// daemon, accept its route.open on `channel`, and return the open's body
10656    /// and handle.
10657    async fn open_answered_with(
10658        shared: &Arc<Shared>,
10659        consumer: &Arc<SubcConsumer>,
10660        receiver: &mut mpsc::Receiver<WriteCommand>,
10661        opts: CallOptions,
10662        channel: u16,
10663        why: &str,
10664    ) -> (serde_json::Value, RouteHandle) {
10665        let consumer = Arc::clone(consumer);
10666        let task = tokio::spawn(async move {
10667            consumer
10668                .open_route(restart_target("plexus"), restart_identity(), opts)
10669                .await
10670        });
10671        let (corr, request) = next_route_open(receiver, why).await;
10672        assert!(dispatch_frame(shared, 1, route_open_answer(corr, channel, None)).await);
10673        let handle = task.await.unwrap().expect("the stand-in accepted the open");
10674        (request, handle)
10675    }
10676
10677    fn with_role_versions(entries: &[(&str, &str)]) -> CallOptions {
10678        CallOptions {
10679            role_versions: Some(
10680                entries
10681                    .iter()
10682                    .map(|(role, version)| (role.to_string(), version.to_string()))
10683                    .collect(),
10684            ),
10685            ..CallOptions::default()
10686        }
10687    }
10688
10689    /// A provider picks its wire shape from the role versions at bind, so a
10690    /// legacy route and a versioned one to the same target must never be
10691    /// shared, while the same declaration again (and an empty map, which
10692    /// declares nothing) reuses the route it matches.
10693    #[tokio::test]
10694    async fn routes_differing_only_in_role_versions_are_kept_apart() {
10695        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(9));
10696        let (legacy_request, legacy) = open_answered_with(
10697            &shared,
10698            &consumer,
10699            &mut receiver,
10700            CallOptions::default(),
10701            71,
10702            "first, legacy open",
10703        )
10704        .await;
10705        assert!(
10706            legacy_request.get("role_versions").is_none(),
10707            "{legacy_request}"
10708        );
10709
10710        let (v1_request, v1) = open_answered_with(
10711            &shared,
10712            &consumer,
10713            &mut receiver,
10714            with_role_versions(&[("tool-provider", "v1")]),
10715            72,
10716            "a v1 open must not reuse the legacy route",
10717        )
10718        .await;
10719        assert_eq!(
10720            v1_request["role_versions"],
10721            serde_json::json!({ "tool-provider": "v1" })
10722        );
10723        assert_ne!(legacy, v1);
10724
10725        let (v2_request, v2) = open_answered_with(
10726            &shared,
10727            &consumer,
10728            &mut receiver,
10729            with_role_versions(&[("tool-provider", "v2")]),
10730            73,
10731            "a v2 open must not reuse the v1 route",
10732        )
10733        .await;
10734        assert_eq!(
10735            v2_request["role_versions"],
10736            serde_json::json!({ "tool-provider": "v2" })
10737        );
10738        assert!(![legacy, v1].contains(&v2));
10739
10740        let open = |opts: CallOptions| {
10741            let consumer = Arc::clone(&consumer);
10742            async move {
10743                consumer
10744                    .open_route(restart_target("plexus"), restart_identity(), opts)
10745                    .await
10746                    .unwrap()
10747            }
10748        };
10749        assert_eq!(
10750            open(with_role_versions(&[("tool-provider", "v1")])).await,
10751            v1
10752        );
10753        assert_eq!(open(CallOptions::default()).await, legacy);
10754        assert_eq!(
10755            open(CallOptions {
10756                role_versions: Some(BTreeMap::new()),
10757                ..CallOptions::default()
10758            })
10759            .await,
10760            legacy,
10761            "an empty map declares nothing and reuses the legacy route"
10762        );
10763        assert!(
10764            receiver.try_recv().is_err(),
10765            "a cache hit must not send a route.open"
10766        );
10767        shared.close_sync("test complete");
10768    }
10769
10770    #[tokio::test]
10771    async fn scoped_routes_are_cached_per_owner_ref_and_epoch_and_apart_from_unscoped() {
10772        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(8));
10773        let selector = scope_selector("owner", "session-a", 1);
10774        let (request, first) = open_answered(
10775            &shared,
10776            &consumer,
10777            &mut receiver,
10778            Some(selector.clone()),
10779            61,
10780            "first scoped open",
10781        )
10782        .await;
10783        assert_eq!(request["scope"], serde_json::to_value(&selector).unwrap());
10784
10785        // The same selector again is a cache hit: no route.open, same handle.
10786        let again = consumer
10787            .open_route_scoped(
10788                restart_target("plexus"),
10789                restart_identity(),
10790                selector,
10791                CallOptions::default(),
10792            )
10793            .await
10794            .unwrap();
10795        assert_eq!(again, first);
10796        assert!(
10797            receiver.try_recv().is_err(),
10798            "a cache hit must not send a route.open"
10799        );
10800
10801        let mut handles = vec![first];
10802        for (channel, scope, why) in [
10803            (
10804                62,
10805                Some(scope_selector("owner", "session-a", 2)),
10806                "another epoch of the same scope must open its own route",
10807            ),
10808            (
10809                63,
10810                Some(scope_selector("owner", "session-b", 1)),
10811                "another scope ref must open its own route",
10812            ),
10813            (
10814                64,
10815                Some(scope_selector("other-owner", "session-a", 1)),
10816                "another owner's scope must open its own route",
10817            ),
10818            (65, None, "an unscoped open must not reuse a scoped route"),
10819        ] {
10820            let expected_scope = scope
10821                .as_ref()
10822                .map(|scope| serde_json::to_value(scope).unwrap());
10823            let (request, handle) =
10824                open_answered(&shared, &consumer, &mut receiver, scope, channel, why).await;
10825            assert_eq!(
10826                request.get("scope").cloned(),
10827                expected_scope,
10828                "the route.open must carry exactly the requested scope: {why}"
10829            );
10830            assert!(!handles.contains(&handle), "{why}");
10831            handles.push(handle);
10832        }
10833        shared.close_sync("test complete");
10834    }
10835
10836    #[tokio::test]
10837    async fn a_dropped_scoped_route_reopens_with_the_same_selector() {
10838        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(7));
10839        let selector = scope_selector("owner", "session-a", 3);
10840        let (first_request, first) = open_answered(
10841            &shared,
10842            &consumer,
10843            &mut receiver,
10844            Some(selector.clone()),
10845            51,
10846            "first scoped open",
10847        )
10848        .await;
10849
10850        // The daemon ends the route, as it does when the provider restarts.
10851        let goodbye = Frame::build(
10852            FrameType::Goodbye,
10853            Flags::new(false, Priority::Interactive, false),
10854            first.channel,
10855            first.epoch,
10856            0,
10857            Vec::new(),
10858        )
10859        .unwrap();
10860        assert!(dispatch_frame(&shared, 1, goodbye).await);
10861        assert!(matches!(
10862            shared.route_state(first),
10863            Err(CallError::StaleRouteHandle(_))
10864        ));
10865
10866        let (second_request, second) = open_answered(
10867            &shared,
10868            &consumer,
10869            &mut receiver,
10870            Some(selector.clone()),
10871            52,
10872            "the reopen after the route dropped",
10873        )
10874        .await;
10875        assert_eq!(
10876            first_request["scope"],
10877            serde_json::to_value(&selector).unwrap()
10878        );
10879        assert_eq!(second_request["scope"], first_request["scope"]);
10880        assert_ne!(second, first);
10881        shared.close_sync("test complete");
10882    }
10883
10884    /// Refuse every scoped route.open with `code` until the open settles, and
10885    /// return how many attempts were served and the error the caller got.
10886    async fn refuse_scoped_opens(code: &str) -> (usize, CallError) {
10887        refuse_scoped_operation(code, "open").await
10888    }
10889
10890    async fn refuse_scoped_operation(code: &str, operation: &str) -> (usize, CallError) {
10891        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(9));
10892        let selector = scope_selector("owner", "session-a", 1);
10893        let options = CallOptions {
10894            scope: Some(selector.clone()),
10895            timeout: Duration::from_secs(2),
10896            route_retry: RetryBackoff {
10897                base: Duration::ZERO,
10898                cap: Duration::ZERO,
10899                max_attempts: 2,
10900            },
10901            route_retry_deadline: Duration::from_millis(150),
10902            ..CallOptions::default()
10903        };
10904        let operation = operation.to_string();
10905        let mut task = tokio::spawn(async move {
10906            match operation.as_str() {
10907                "call" => consumer
10908                    .call(
10909                        restart_target("plexus"),
10910                        restart_identity(),
10911                        b"{}".to_vec(),
10912                        options,
10913                    )
10914                    .await
10915                    .map(|_| ()),
10916                "subscribe" => consumer
10917                    .subscribe(
10918                        restart_target("plexus"),
10919                        restart_identity(),
10920                        b"{}".to_vec(),
10921                        SubscribeOptions {
10922                            scope: options.scope,
10923                            route_open_timeout: options.timeout,
10924                            route_retry: options.route_retry,
10925                            route_retry_deadline: options.route_retry_deadline,
10926                            ..SubscribeOptions::default()
10927                        },
10928                    )
10929                    .await
10930                    .map(|_| ()),
10931                "open" => consumer
10932                    .open_route_scoped(
10933                        restart_target("plexus"),
10934                        restart_identity(),
10935                        scope_selector("owner", "session-a", 1),
10936                        options,
10937                    )
10938                    .await
10939                    .map(|_| ()),
10940                _ => unreachable!(),
10941            }
10942        });
10943        let mut attempts = 0usize;
10944        let err = loop {
10945            tokio::select! {
10946                command = receiver.recv() => {
10947                    let Some(command) = command else {
10948                        break task.await.unwrap().expect_err("route.open must be refused");
10949                    };
10950                    let open: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
10951                    assert_eq!(open["scope"], serde_json::to_value(&selector).unwrap());
10952                    attempts += 1;
10953                    let frame = route_open_answer(
10954                        command.frame.header.corr,
10955                        0,
10956                        Some(ErrorBody::new(code, "test refusal")),
10957                    );
10958                    assert!(dispatch_frame(&shared, 1, frame).await);
10959                }
10960                joined = &mut task => {
10961                    break joined.unwrap().expect_err("route.open must be refused");
10962                }
10963            }
10964        };
10965        shared.close_sync("test complete");
10966        (attempts, err)
10967    }
10968
10969    #[tokio::test]
10970    async fn scoped_managed_operations_retry_only_transient_scope_refusals() {
10971        for operation in ["call", "subscribe"] {
10972            for (code, retryable) in [
10973                (error_codes::SCOPE_NOT_SYNCED, true),
10974                (error_codes::SCOPE_CHANGED, true),
10975                (error_codes::SCOPE_ENDED, false),
10976                (error_codes::SCOPE_NOT_LIVE, false),
10977                (error_codes::SCOPE_EPOCH_REQUIRED, false),
10978                (error_codes::SCOPE_NOT_CARRIER, false),
10979            ] {
10980                let (attempts, err) = refuse_scoped_operation(code, operation).await;
10981                if retryable {
10982                    assert!(attempts > 1, "{operation}: {code} must be retried");
10983                } else {
10984                    assert_eq!(attempts, 1, "{operation}: {code} must be terminal");
10985                }
10986                assert!(matches!(err, CallError::NotSent(_)), "{operation}: {err}");
10987                assert_eq!(err.never_forwarded(), Some(true));
10988                assert_eq!(err.route_open_refusal().unwrap().code, code);
10989            }
10990        }
10991    }
10992
10993    #[tokio::test]
10994    async fn scoped_open_retries_not_synced_and_changed_and_ends_on_the_terminal_scope_codes() {
10995        for code in [error_codes::SCOPE_NOT_SYNCED, error_codes::SCOPE_CHANGED] {
10996            let (attempts, err) = refuse_scoped_opens(code).await;
10997            assert!(attempts > 1, "{code} must be retried, served {attempts}");
10998            assert_eq!(
10999                err.route_open_refusal().map(|body| body.code.as_str()),
11000                Some(code)
11001            );
11002        }
11003        for code in [
11004            error_codes::SCOPE_ENDED,
11005            error_codes::SCOPE_NOT_LIVE,
11006            error_codes::SCOPE_EPOCH_REQUIRED,
11007            error_codes::SCOPE_NOT_CARRIER,
11008        ] {
11009            let (attempts, err) = refuse_scoped_opens(code).await;
11010            assert_eq!(attempts, 1, "{code} is terminal and must not be retried");
11011            assert!(matches!(err, CallError::NotSent(_)));
11012            assert_eq!(
11013                err.route_open_refusal().map(|body| body.code.as_str()),
11014                Some(code)
11015            );
11016        }
11017    }
11018
11019    /// The daemon refuses the first route.open with `module_warming`, then the
11020    /// retry is written and accepted but never answered, so the retry deadline
11021    /// expires while that attempt is still waiting. The caller must still get
11022    /// the refusal it already received, as `NotSent`, rather than the bare
11023    /// "timed out at its deadline" of the unanswered attempt. A busy daemon
11024    /// that answers the final retry a few milliseconds late hits this path.
11025    #[tokio::test]
11026    async fn refusal_survives_a_retry_still_in_flight_at_the_deadline() {
11027        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(11));
11028        let options = CallOptions {
11029            timeout: Duration::from_secs(5),
11030            route_retry: RetryBackoff {
11031                base: Duration::ZERO,
11032                cap: Duration::ZERO,
11033                max_attempts: 2,
11034            },
11035            route_retry_deadline: Duration::from_millis(300),
11036            ..CallOptions::default()
11037        };
11038        let mut task = tokio::spawn(async move {
11039            consumer
11040                .open_route(restart_target("warming"), restart_identity(), options)
11041                .await
11042        });
11043        let generation = shared.lock_inner().generation;
11044        let refusal = ErrorBody {
11045            code: error_codes::MODULE_WARMING.to_string(),
11046            message: "warming is not ready".to_string(),
11047            detail: Some(serde_json::json!({"reason": "required_capability_unprovided"})),
11048        };
11049        let mut attempts = 0usize;
11050        let mut held = false;
11051        let err = loop {
11052            tokio::select! {
11053                command = receiver.recv() => {
11054                    let Some(command) = command else {
11055                        break task.await.unwrap().expect_err("route.open must fail");
11056                    };
11057                    if command.frame.header.ty != FrameType::Request {
11058                        continue;
11059                    }
11060                    attempts += 1;
11061                    if attempts == 1 {
11062                        let frame = route_open_answer(
11063                            command.frame.header.corr,
11064                            0,
11065                            Some(refusal.clone()),
11066                        );
11067                        assert!(dispatch_frame(&shared, generation, frame).await);
11068                    } else {
11069                        // What the writer task does once the frame is on the
11070                        // socket: from here a timeout is OutcomeUnknown.
11071                        held = shared.mark_pending_accepted(
11072                            command.pending.expect("a route.open is a pending request"),
11073                        );
11074                    }
11075                }
11076                joined = &mut task => {
11077                    break joined.unwrap().expect_err("route.open must fail");
11078                }
11079            }
11080        };
11081        shared.close_sync("test complete");
11082        assert_eq!(
11083            attempts, 2,
11084            "one refused attempt, then one held past the deadline"
11085        );
11086        assert!(
11087            held,
11088            "the second attempt must be accepted and left unanswered"
11089        );
11090        assert!(
11091            err.is_not_sent(),
11092            "a refused route never delivered the request: {err}"
11093        );
11094        let body = err
11095            .route_open_refusal()
11096            .unwrap_or_else(|| panic!("the refusal must survive the deadline: {err}"));
11097        assert_eq!(body.code, error_codes::MODULE_WARMING);
11098        assert_eq!(body.detail, refusal.detail);
11099    }
11100
11101    #[test]
11102    fn every_scope_close_reason_must_not_reopen() {
11103        for reason in [
11104            subc_protocol::RouteCloseReason::ScopeEnded,
11105            subc_protocol::RouteCloseReason::ScopeCarrierRemoved,
11106            subc_protocol::RouteCloseReason::ScopeDelegationChanged,
11107            subc_protocol::RouteCloseReason::ScopeParentEnded,
11108        ] {
11109            let wire = serde_json::to_value(reason).unwrap();
11110            let wire = wire.as_str().expect("a close reason is a string");
11111            assert!(wire.starts_with("scope_"), "{wire}");
11112            assert_eq!(
11113                RouteCloseReason::from_wire(wire).disposition(),
11114                RouteCloseDisposition::MustNotReopen,
11115                "a route closed for {wire} must not be reopened"
11116            );
11117        }
11118    }
11119
11120    // The fake module receives the queued Request and injects frames through the
11121    // same dispatcher as the socket reader, without a daemon process.
11122    async fn watch_subscribed() -> (
11123        SubcConsumer,
11124        mpsc::Receiver<WriteCommand>,
11125        Subscription,
11126        Frame,
11127    ) {
11128        let (shared, mut rx, handle) = reverse_test_shared(ReverseRequestRegistry::new());
11129        shared.lock_inner().one_shot_routes.insert(
11130            handle.channel,
11131            RouteState {
11132                handle,
11133                sem: Arc::new(Semaphore::new(1)),
11134                watch_sem: None,
11135                opted_in: false,
11136            },
11137        );
11138        let consumer = SubcConsumer { shared };
11139        let subscription = consumer
11140            .subscribe_route(&handle, b"watch".to_vec(), SubscribeOptions::default())
11141            .await
11142            .unwrap();
11143        let request = rx.recv().await.unwrap().frame;
11144        (consumer, rx, subscription, request)
11145    }
11146
11147    fn watch_terminal(request: &Frame, ty: FrameType, body: Vec<u8>) -> Frame {
11148        Frame::build(
11149            ty,
11150            Flags::new(false, Priority::Interactive, false),
11151            request.header.channel,
11152            request.header.epoch,
11153            request.header.corr,
11154            body,
11155        )
11156        .unwrap()
11157    }
11158
11159    #[tokio::test]
11160    async fn subscription_ended_preserves_response_body_and_closed_stays_ok() {
11161        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11162        let body = vec![0, 255, 128, 1, 10];
11163        assert!(
11164            dispatch_frame(
11165                &consumer.shared,
11166                1,
11167                watch_terminal(&request, FrameType::Response, body.clone())
11168            )
11169            .await
11170        );
11171        subscription.closed().await.unwrap();
11172        assert_eq!(
11173            subscription.ended().await,
11174            SubscriptionEnd::Response(body.clone())
11175        );
11176        subscription.unsubscribe().unwrap();
11177        assert_eq!(subscription.ended().await, SubscriptionEnd::Response(body));
11178        assert_eq!(subscription.events().recv().await, None);
11179    }
11180
11181    #[tokio::test]
11182    async fn subscription_ended_distinguishes_empty_response_from_stream_end() {
11183        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11184        assert!(
11185            dispatch_frame(
11186                &consumer.shared,
11187                1,
11188                watch_terminal(&request, FrameType::Response, Vec::new())
11189            )
11190            .await
11191        );
11192        assert_eq!(
11193            subscription.ended().await,
11194            SubscriptionEnd::Response(Vec::new())
11195        );
11196        subscription.closed().await.unwrap();
11197    }
11198
11199    #[tokio::test]
11200    async fn subscription_ended_reports_stream_end_and_closed_stays_ok() {
11201        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11202        assert!(
11203            dispatch_frame(
11204                &consumer.shared,
11205                1,
11206                watch_terminal(&request, FrameType::StreamEnd, Vec::new())
11207            )
11208            .await
11209        );
11210        assert_eq!(subscription.ended().await, SubscriptionEnd::StreamEnd);
11211        subscription.closed().await.unwrap();
11212    }
11213
11214    #[tokio::test]
11215    async fn subscription_ended_reports_module_error_code_and_detail() {
11216        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11217        let error = ErrorBody {
11218            code: "no_grant".to_string(),
11219            message: "not accepted: no grant".to_string(),
11220            detail: Some(serde_json::json!({"capability": "watch"})),
11221        };
11222        assert!(
11223            dispatch_frame(
11224                &consumer.shared,
11225                1,
11226                watch_terminal(
11227                    &request,
11228                    FrameType::Error,
11229                    serde_json::to_vec(&error).unwrap()
11230                )
11231            )
11232            .await
11233        );
11234        assert_eq!(
11235            subscription.ended().await,
11236            SubscriptionEnd::Error(error.clone())
11237        );
11238        let CallError::Module(closed_error) = subscription.closed().await.unwrap_err() else {
11239            panic!("closed must still return the module error");
11240        };
11241        assert_eq!(closed_error, error);
11242        subscription.unsubscribe().unwrap();
11243        assert_eq!(subscription.ended().await, SubscriptionEnd::Error(error));
11244    }
11245
11246    #[tokio::test]
11247    async fn subscription_ended_reports_unsubscribe_as_cancelled_and_ignores_late_terminal() {
11248        let (consumer, mut rx, mut subscription, request) = watch_subscribed().await;
11249        subscription.unsubscribe().unwrap();
11250        subscription.unsubscribe().unwrap();
11251        subscription.closed().await.unwrap();
11252        assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
11253        let cancel = rx.recv().await.unwrap().frame;
11254        assert_eq!(cancel.header.ty, FrameType::Cancel);
11255        assert_eq!(cancel.header.corr, request.header.corr);
11256        assert!(rx.try_recv().is_err());
11257        assert!(
11258            dispatch_frame(
11259                &consumer.shared,
11260                1,
11261                watch_terminal(&request, FrameType::Response, b"late".to_vec())
11262            )
11263            .await
11264        );
11265        assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
11266    }
11267
11268    #[tokio::test]
11269    async fn subscription_ended_retains_route_close_reason() {
11270        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11271        let push = Frame::build(FrameType::Push, Flags::new(false, Priority::Interactive, false), 0, 0, 0,
11272            serde_json::to_vec(&serde_json::json!({"op": "route.closed", "module_id": "watch", "reason": "capability_denied", "channels": [request.header.channel]})).unwrap()).unwrap();
11273        assert!(dispatch_frame(&consumer.shared, 1, push).await);
11274        assert!(
11275            dispatch_frame(
11276                &consumer.shared,
11277                1,
11278                watch_terminal(&request, FrameType::Goodbye, Vec::new())
11279            )
11280            .await
11281        );
11282        let reason = RouteEndReason::Daemon(RouteCloseReason::CapabilityDenied);
11283        assert_eq!(
11284            subscription.ended().await,
11285            SubscriptionEnd::RouteClosed {
11286                reason: reason.clone()
11287            }
11288        );
11289        assert_eq!(
11290            subscription.closed().await.unwrap_err().close_reason(),
11291            Some(&reason)
11292        );
11293    }
11294
11295    #[tokio::test]
11296    async fn subscription_ended_reports_connection_loss() {
11297        let (consumer, _rx, mut subscription, _request) = watch_subscribed().await;
11298        consumer
11299            .shared
11300            .handle_generation_drop(1, "fake connection lost".to_string());
11301        assert_eq!(subscription.ended().await, SubscriptionEnd::ConnectionLost);
11302        assert!(subscription.closed().await.is_err());
11303    }
11304
11305    #[tokio::test]
11306    async fn subscription_ended_waiter_wakes_on_stream_end() {
11307        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11308        let (end, dispatched) = tokio::join!(subscription.ended(), async {
11309            tokio::task::yield_now().await;
11310            dispatch_frame(
11311                &consumer.shared,
11312                1,
11313                watch_terminal(&request, FrameType::StreamEnd, Vec::new()),
11314            )
11315            .await
11316        });
11317        assert!(dispatched);
11318        assert_eq!(end, SubscriptionEnd::StreamEnd);
11319        subscription.closed().await.unwrap();
11320    }
11321
11322    #[tokio::test]
11323    async fn subscription_ended_reports_backpressure_without_hiding_closed_error() {
11324        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11325        for _ in 0..=DEFAULT_SUBSCRIPTION_EVENT_BUFFER {
11326            assert!(
11327                dispatch_frame(
11328                    &consumer.shared,
11329                    1,
11330                    watch_terminal(&request, FrameType::StreamData, vec![1])
11331                )
11332                .await
11333            );
11334        }
11335        assert_eq!(subscription.ended().await, SubscriptionEnd::Backpressure);
11336        assert!(matches!(
11337            subscription.closed().await,
11338            Err(CallError::SubscriptionBackpressure(_))
11339        ));
11340    }
11341
11342    #[tokio::test]
11343    async fn subscription_ended_reports_client_close_as_route_closed_by_caller() {
11344        let (consumer, _rx, mut subscription, _request) = watch_subscribed().await;
11345        consumer.close().await;
11346        assert_eq!(
11347            subscription.ended().await,
11348            SubscriptionEnd::RouteClosed {
11349                reason: RouteEndReason::ClosedByCaller
11350            }
11351        );
11352        assert!(subscription.closed().await.is_err());
11353    }
11354
11355    #[test]
11356    fn drain_pending_channel_can_skip_subscriptions() {
11357        let mut pending = HashMap::new();
11358        let generation = 7;
11359        let channel = 11;
11360        let handle = RouteHandle::new(channel, 3, generation);
11361        let unary_key = PendingKey {
11362            generation,
11363            channel,
11364            epoch: handle.epoch,
11365            corr: 1,
11366        };
11367        let subscription_key = PendingKey {
11368            generation,
11369            channel,
11370            epoch: handle.epoch,
11371            corr: 2,
11372        };
11373        let (unary_tx, _unary_rx) = oneshot::channel();
11374        pending.insert(unary_key, PendingEntry::unary(unary_tx, false, None, None));
11375
11376        let (events_tx, _events_rx) = mpsc::channel(1);
11377        let (closed_tx, _closed_rx) = oneshot::channel();
11378        let (ended_tx, _ended_rx) = watch::channel(None);
11379        let permit = Arc::new(Semaphore::new(1))
11380            .try_acquire_owned()
11381            .expect("test semaphore permit should be available");
11382        pending.insert(
11383            subscription_key,
11384            PendingEntry::subscription(
11385                events_tx,
11386                closed_tx,
11387                ended_tx,
11388                RoutePermit::legacy(permit),
11389                Priority::Interactive,
11390            ),
11391        );
11392
11393        let drained = drain_pending_handle(&mut pending, handle, false);
11394        assert_eq!(drained.len(), 1);
11395        assert!(pending.contains_key(&subscription_key));
11396
11397        let drained = drain_pending_handle(&mut pending, handle, true);
11398        assert_eq!(drained.len(), 1);
11399        assert!(pending.is_empty());
11400    }
11401
11402    fn response_frame(channel: u16, epoch: u32, corr: u64, body: Vec<u8>) -> Frame {
11403        Frame::build(
11404            FrameType::Response,
11405            Flags::new(false, Priority::Interactive, false),
11406            channel,
11407            epoch,
11408            corr,
11409            body,
11410        )
11411        .unwrap()
11412    }
11413
11414    #[tokio::test]
11415    async fn stale_epoch_ingress_drops_without_settling_matching_corr() {
11416        let shared = Arc::new(reader_skew_tests::legacy_shared(
11417            PathBuf::from("/tmp/does-not-exist"),
11418            ConsumerOptions::default(),
11419        ));
11420        let (writer, _rx) = mpsc::channel(4);
11421        let current = RouteHandle::new(9, 2, 1);
11422        let stale_key = PendingKey {
11423            generation: 1,
11424            channel: 9,
11425            epoch: 1,
11426            corr: 77,
11427        };
11428        let key = PendingKey {
11429            generation: 1,
11430            channel: 9,
11431            epoch: 2,
11432            corr: 77,
11433        };
11434        let (stale_tx, mut stale_response) = oneshot::channel();
11435        let (tx, mut response) = oneshot::channel();
11436        {
11437            let mut inner = shared.lock_inner();
11438            inner.writer = Some(writer);
11439            inner.daemon_ver = "0.39.0".into();
11440            inner.route_epochs.insert(9, current);
11441            inner
11442                .pending
11443                .insert(stale_key, PendingEntry::unary(stale_tx, false, None, None));
11444            inner
11445                .pending
11446                .insert(key, PendingEntry::unary(tx, false, None, None));
11447        }
11448
11449        assert!(dispatch_frame(&shared, 1, response_frame(9, 1, 77, b"stale".to_vec())).await);
11450        assert!(matches!(
11451            response.try_recv(),
11452            Err(oneshot::error::TryRecvError::Empty)
11453        ));
11454        assert!(matches!(
11455            stale_response.try_recv(),
11456            Err(oneshot::error::TryRecvError::Empty)
11457        ));
11458        assert!(shared.lock_inner().pending.contains_key(&stale_key));
11459        assert!(shared.lock_inner().pending.contains_key(&key));
11460        assert_eq!(shared.lock_inner().dropped_route_frames, 1);
11461
11462        assert!(dispatch_frame(&shared, 1, response_frame(9, 2, 77, b"current".to_vec())).await);
11463        let PendingResult::Terminal(PendingTerminal::Response { body, .. }) =
11464            response.await.unwrap()
11465        else {
11466            panic!("current epoch must settle its own pending request");
11467        };
11468        assert_eq!(body, b"current");
11469        assert!(shared.lock_inner().pending.contains_key(&stale_key));
11470    }
11471
11472    #[tokio::test]
11473    async fn route_poll_response_must_echo_expected_handle_before_settling() {
11474        let shared = Arc::new(reader_skew_tests::legacy_shared(
11475            PathBuf::from("/tmp/does-not-exist"),
11476            ConsumerOptions::default(),
11477        ));
11478        let (writer, _rx) = mpsc::channel(4);
11479        let handle = RouteHandle::new(3, 9, 1);
11480        let key = PendingKey {
11481            generation: 1,
11482            channel: 0,
11483            epoch: 0,
11484            corr: 88,
11485        };
11486        let (tx, mut response) = oneshot::channel();
11487        {
11488            let mut inner = shared.lock_inner();
11489            inner.writer = Some(writer);
11490            inner.daemon_ver = "0.39.0".into();
11491            inner.route_epochs.insert(handle.channel, handle);
11492            inner
11493                .pending
11494                .insert(key, PendingEntry::unary(tx, false, Some(handle), None));
11495        }
11496        let wrong = serde_json::to_vec(&ClientControlResponse::RoutePoll {
11497            route_channel: handle.channel,
11498            route_epoch: handle.epoch + 1,
11499            status: Some("wrong".to_string()),
11500            live: Some(true),
11501        })
11502        .unwrap();
11503        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, key.corr, wrong)).await);
11504        assert!(matches!(
11505            response.try_recv(),
11506            Err(oneshot::error::TryRecvError::Empty)
11507        ));
11508        assert!(shared.lock_inner().pending.contains_key(&key));
11509
11510        let correct = serde_json::to_vec(&ClientControlResponse::RoutePoll {
11511            route_channel: handle.channel,
11512            route_epoch: handle.epoch,
11513            status: Some("ready".to_string()),
11514            live: Some(true),
11515        })
11516        .unwrap();
11517        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, key.corr, correct)).await);
11518        assert!(matches!(
11519            response.await.unwrap(),
11520            PendingResult::Terminal(PendingTerminal::Response { .. })
11521        ));
11522    }
11523
11524    #[tokio::test]
11525    async fn stale_connection_handle_emits_no_request_cancel_or_goodbye() {
11526        let shared = Arc::new(reader_skew_tests::legacy_shared(
11527            PathBuf::from("/tmp/does-not-exist"),
11528            ConsumerOptions::default(),
11529        ));
11530        let (writer, mut rx) = mpsc::channel(4);
11531        let stale = RouteHandle::new(4, 1, 1);
11532        let current = RouteHandle::new(4, 1, 2);
11533        {
11534            let mut inner = shared.lock_inner();
11535            inner.generation = 2;
11536            inner.writer = Some(writer);
11537            inner.daemon_ver = "0.39.0".into();
11538            inner.route_epochs.insert(4, current);
11539        }
11540
11541        let err = shared
11542            .send_request(RequestSend {
11543                binary: false,
11544                expected_handle: Some(stale),
11545                channel: stale.channel,
11546                epoch: stale.epoch,
11547                body: b"request".to_vec(),
11548                priority: Priority::Interactive,
11549                admission_class: AdmissionClass::Normal,
11550                deadline: Instant::now() + Duration::from_millis(10),
11551                retain_late_route_open: false,
11552                route_open_reverse_requests: None,
11553            })
11554            .await
11555            .unwrap_err();
11556        assert!(matches!(err, CallError::StaleRouteHandle(handle) if handle == stale));
11557        shared.send_cancel(stale, 8, Priority::Interactive);
11558        assert!(!shared.send_route_goodbye(stale, false));
11559        assert!(
11560            rx.try_recv().is_err(),
11561            "stale operations must not queue frames"
11562        );
11563    }
11564
11565    #[tokio::test]
11566    async fn route_poll_refusal_preserves_daemon_code_message_and_detail() {
11567        let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
11568        let handle = RouteHandle::new(3, 9, 1);
11569        shared
11570            .lock_inner()
11571            .route_epochs
11572            .insert(handle.channel, handle);
11573        let poll = consumer.poll_route(&handle, PollKind::Liveness, Duration::from_secs(1));
11574        tokio::pin!(poll);
11575        assert_pending(poll.as_mut()).await;
11576        let request = receiver.try_recv().unwrap();
11577        let refusal = ErrorBody {
11578            code: "unknown_route".into(),
11579            message: "the route is no longer present".into(),
11580            detail: Some(serde_json::json!({ "route_channel": 3, "route_epoch": 9 })),
11581        };
11582        assert!(
11583            dispatch_frame(
11584                &shared,
11585                1,
11586                channel_zero_frame(
11587                    FrameType::Error,
11588                    request.frame.header.corr,
11589                    serde_json::to_vec(&refusal).unwrap(),
11590                ),
11591            )
11592            .await
11593        );
11594        let err = poll.await.unwrap_err();
11595        assert_eq!(err.code(), Some("unknown_route"));
11596        let CallError::Module(body) = err else {
11597            panic!("a delivered refusal must not be classified as a send failure");
11598        };
11599        assert_eq!(body.code, refusal.code);
11600        assert_eq!(body.message, refusal.message);
11601        assert_eq!(body.detail, refusal.detail);
11602    }
11603
11604    #[tokio::test]
11605    async fn late_route_open_queues_goodbye_and_full_queue_closes_connection() {
11606        let shared = Arc::new(reader_skew_tests::legacy_shared(
11607            PathBuf::from("/tmp/does-not-exist"),
11608            ConsumerOptions::default(),
11609        ));
11610        let (writer, mut rx) = mpsc::channel(2);
11611        let key = PendingKey {
11612            generation: 1,
11613            channel: 0,
11614            epoch: 0,
11615            corr: 41,
11616        };
11617        let (tx, response) = oneshot::channel();
11618        drop(response);
11619        {
11620            let mut inner = shared.lock_inner();
11621            inner.writer = Some(writer);
11622            inner.daemon_ver = "0.39.0".into();
11623            inner
11624                .pending
11625                .insert(key, PendingEntry::unary(tx, true, None, None));
11626        }
11627        let body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11628            request_window: None,
11629            watch_window: None,
11630            route_channel: 12,
11631            route_epoch: 7,
11632        })
11633        .unwrap();
11634        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, 41, body)).await);
11635        let cleanup = rx.recv().await.unwrap().frame;
11636        assert_eq!(cleanup.header.ty, FrameType::Goodbye);
11637        assert_eq!((cleanup.header.channel, cleanup.header.epoch), (12, 7));
11638
11639        let shared = Arc::new(reader_skew_tests::legacy_shared(
11640            PathBuf::from("/tmp/does-not-exist"),
11641            ConsumerOptions {
11642                reconnect_backoff: RetryBackoff {
11643                    max_attempts: 1,
11644                    ..RetryBackoff::default()
11645                },
11646                ..ConsumerOptions::default()
11647            },
11648        ));
11649        let (writer, _rx) = mpsc::channel(1);
11650        let filler = response_frame(0, 0, 1, Vec::new());
11651        writer
11652            .try_send(WriteCommand {
11653                frame: filler,
11654                pending: None,
11655            })
11656            .unwrap();
11657        let key = PendingKey {
11658            generation: 1,
11659            channel: 0,
11660            epoch: 0,
11661            corr: 42,
11662        };
11663        let (tx, response) = oneshot::channel();
11664        drop(response);
11665        {
11666            let mut inner = shared.lock_inner();
11667            inner.writer = Some(writer);
11668            inner.daemon_ver = "0.39.0".into();
11669            inner
11670                .pending
11671                .insert(key, PendingEntry::unary(tx, true, None, None));
11672        }
11673        let body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11674            request_window: None,
11675            watch_window: None,
11676            route_channel: 13,
11677            route_epoch: 8,
11678        })
11679        .unwrap();
11680        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, 42, body)).await);
11681        assert!(shared.lock_inner().writer.is_none());
11682    }
11683
11684    #[tokio::test]
11685    async fn correlation_allocator_emits_max_once_then_closes_without_reuse() {
11686        let shared = Arc::new(reader_skew_tests::legacy_shared(
11687            PathBuf::from("/tmp/does-not-exist"),
11688            ConsumerOptions {
11689                reconnect_backoff: RetryBackoff {
11690                    max_attempts: 1,
11691                    ..RetryBackoff::default()
11692                },
11693                ..ConsumerOptions::default()
11694            },
11695        ));
11696        let (writer, mut rx) = mpsc::channel(4);
11697        {
11698            let mut inner = shared.lock_inner();
11699            inner.writer = Some(writer);
11700            inner.daemon_ver = "0.39.0".into();
11701            inner.next_corr = Some(u64::MAX);
11702        }
11703        let request_shared = Arc::clone(&shared);
11704        let request = tokio::spawn(async move {
11705            request_shared
11706                .send_request(RequestSend {
11707                    binary: false,
11708                    expected_handle: None,
11709                    channel: 0,
11710                    epoch: 0,
11711                    body: Vec::new(),
11712                    priority: Priority::Interactive,
11713                    admission_class: AdmissionClass::Normal,
11714                    deadline: Instant::now() + Duration::from_secs(1),
11715                    retain_late_route_open: false,
11716                    route_open_reverse_requests: None,
11717                })
11718                .await
11719        });
11720        let command = rx.recv().await.unwrap();
11721        assert_eq!(command.frame.header.corr, u64::MAX);
11722        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, u64::MAX, Vec::new()),).await);
11723        assert!(request.await.unwrap().is_ok());
11724
11725        let exhausted = shared
11726            .send_request(RequestSend {
11727                binary: false,
11728                expected_handle: None,
11729                channel: 0,
11730                epoch: 0,
11731                body: Vec::new(),
11732                priority: Priority::Interactive,
11733                admission_class: AdmissionClass::Normal,
11734                deadline: Instant::now() + Duration::from_millis(10),
11735                retain_late_route_open: false,
11736                route_open_reverse_requests: None,
11737            })
11738            .await
11739            .unwrap_err();
11740        assert!(matches!(exhausted, CallError::NotSent(_)));
11741        assert!(rx.try_recv().is_err());
11742        assert!(shared.lock_inner().writer.is_none());
11743    }
11744
11745    #[tokio::test]
11746    async fn managed_call_deadline_bounds_flow_control_wait() {
11747        let shared = Arc::new(reader_skew_tests::legacy_shared(
11748            PathBuf::from("/tmp/does-not-exist"),
11749            ConsumerOptions::default(),
11750        ));
11751        let (writer, mut rx) = mpsc::channel(4);
11752        let target = RouteTarget::ToolProvider {
11753            module_id: "flow-controlled".to_string(),
11754        };
11755        let identity = BindIdentity::new("test".to_string(), "deadline".to_string());
11756        let consumer_identity = Some(ConsumerIdentity {
11757            module_id: "caller".to_string(),
11758            launch_nonce: "nonce".to_string(),
11759        });
11760        let first_opts = CallOptions {
11761            timeout: Duration::from_secs(1),
11762            consumer_identity: consumer_identity.clone(),
11763            ..CallOptions::default()
11764        };
11765        let second_opts = CallOptions {
11766            timeout: Duration::from_millis(25),
11767            consumer_identity,
11768            ..CallOptions::default()
11769        };
11770        let key = RouteKey::new(
11771            &target,
11772            &identity,
11773            first_opts.consumer_identity.as_ref(),
11774            None,
11775        );
11776        let handle = RouteHandle::new(5, 3, 1);
11777        {
11778            let mut inner = shared.lock_inner();
11779            inner.writer = Some(writer);
11780            inner.daemon_ver = "0.39.0".into();
11781            inner.cache_route(
11782                key,
11783                RouteState {
11784                    handle,
11785                    sem: Arc::new(Semaphore::new(1)),
11786                    watch_sem: None,
11787                    opted_in: false,
11788                },
11789            );
11790        }
11791
11792        let first = tokio::spawn({
11793            let consumer = SubcConsumer {
11794                shared: Arc::clone(&shared),
11795            };
11796            let target = target.clone();
11797            let identity = identity.clone();
11798            async move {
11799                consumer
11800                    .call(target, identity, b"first".to_vec(), first_opts)
11801                    .await
11802            }
11803        });
11804        let first_frame = rx
11805            .recv()
11806            .await
11807            .expect("the first request should enter the fake daemon queue");
11808        assert_eq!(first_frame.frame.header.ty, FrameType::Request);
11809        assert_eq!(first_frame.frame.body, b"first");
11810        assert!(shared.mark_pending_accepted(
11811            first_frame
11812                .pending
11813                .expect("request commands retain their pending key"),
11814        ));
11815
11816        let consumer = SubcConsumer {
11817            shared: Arc::clone(&shared),
11818        };
11819        let result = tokio::time::timeout(
11820            Duration::from_millis(250),
11821            consumer.call(target, identity, b"second".to_vec(), second_opts),
11822        )
11823        .await
11824        .expect("a flow-controlled call must finish at its own deadline")
11825        .unwrap_err();
11826        assert!(matches!(result, CallError::NotSent(_)));
11827        assert!(
11828            rx.try_recv().is_err(),
11829            "the timed-out second request must not reach the fake daemon"
11830        );
11831
11832        first.abort();
11833        let _ = first.await;
11834    }
11835
11836    #[tokio::test]
11837    async fn admitted_route_open_emits_one_frame_without_retrying_daemon_errors() {
11838        let shared = Arc::new(reader_skew_tests::legacy_shared(
11839            PathBuf::from("/tmp/does-not-exist"),
11840            ConsumerOptions {
11841                call_timeout: Duration::from_secs(1),
11842                ..ConsumerOptions::default()
11843            },
11844        ));
11845        let (writer, mut rx) = mpsc::channel(4);
11846        {
11847            let mut inner = shared.lock_inner();
11848            inner.writer = Some(writer);
11849            inner.daemon_ver = "0.39.0".into();
11850        }
11851
11852        let consumer = SubcConsumer {
11853            shared: Arc::clone(&shared),
11854        };
11855        let target = RouteTarget::ToolProvider {
11856            module_id: "admitted-target".to_string(),
11857        };
11858        let identity = BindIdentity::new("test".to_string(), "admitted".to_string());
11859        let task = tokio::spawn(async move {
11860            consumer
11861                .open_route_with_admission_facts(
11862                    target,
11863                    identity,
11864                    serde_json::json!({"schema": 1, "verified_class": "member"}),
11865                )
11866                .await
11867        });
11868
11869        let command = rx.recv().await.expect("one route.open must be queued");
11870        let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
11871        let ClientControlRequest::RouteOpen {
11872            admission_facts, ..
11873        } = request
11874        else {
11875            panic!("expected route.open")
11876        };
11877        assert_eq!(
11878            admission_facts,
11879            Some(serde_json::json!({"schema": 1, "verified_class": "member"}))
11880        );
11881
11882        let error_body = serde_json::to_vec(&ErrorBody {
11883            code: "admission_facts_not_permitted".to_string(),
11884            message: "not permitted".to_string(),
11885            detail: None,
11886        })
11887        .unwrap();
11888        assert!(
11889            dispatch_frame(
11890                &shared,
11891                1,
11892                Frame::build(
11893                    FrameType::Error,
11894                    Flags::new(false, Priority::Interactive, false),
11895                    0,
11896                    0,
11897                    command.frame.header.corr,
11898                    error_body,
11899                )
11900                .unwrap(),
11901            )
11902            .await
11903        );
11904        let result = task.await.unwrap();
11905        assert!(matches!(result, Err(CallError::NotSent(_))));
11906        assert!(rx.try_recv().is_err(), "one-shot route.open must not retry");
11907    }
11908
11909    /// Drive one admitted route.open to success on a test writer and return the
11910    /// route.open request that was sent, the resolved handle, and the writer.
11911    async fn open_admitted_route_for_test(
11912        opts: Option<CallOptions>,
11913    ) -> (
11914        Arc<Shared>,
11915        SubcConsumer,
11916        ClientControlRequest,
11917        Result<RouteHandle, CallError>,
11918        mpsc::Receiver<WriteCommand>,
11919    ) {
11920        let shared = writer_test_shared();
11921        let (writer, mut rx) = mpsc::channel(8);
11922        let generation = {
11923            let mut inner = shared.lock_inner();
11924            inner.writer = Some(writer);
11925            inner.daemon_ver = "0.39.0".into();
11926            inner.generation
11927        };
11928        let consumer = SubcConsumer {
11929            shared: Arc::clone(&shared),
11930        };
11931        let target = RouteTarget::ToolProvider {
11932            module_id: "cerebellum".to_string(),
11933        };
11934        let identity = BindIdentity::new("test".to_string(), "admitted".to_string());
11935        let facts = serde_json::json!({"schema": 1, "verified_class": "member"});
11936        // The consumer is returned from the task and kept alive by the caller:
11937        // dropping it closes the connection, after which no frame is dispatched.
11938        let task = tokio::spawn(async move {
11939            let result = match opts {
11940                Some(opts) => {
11941                    consumer
11942                        .open_route_with_admission_facts_and_options(target, identity, facts, opts)
11943                        .await
11944                }
11945                None => {
11946                    consumer
11947                        .open_route_with_admission_facts(target, identity, facts)
11948                        .await
11949                }
11950            };
11951            (consumer, result)
11952        });
11953        let command = rx.recv().await.expect("one route.open must be queued");
11954        let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
11955        let response = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11956            request_window: None,
11957            watch_window: None,
11958            route_channel: 21,
11959            route_epoch: 4,
11960        })
11961        .unwrap();
11962        assert!(
11963            dispatch_frame(
11964                &shared,
11965                generation,
11966                Frame::build(
11967                    FrameType::Response,
11968                    Flags::new(false, Priority::Interactive, false),
11969                    0,
11970                    0,
11971                    command.frame.header.corr,
11972                    response,
11973                )
11974                .unwrap(),
11975            )
11976            .await
11977        );
11978        let (consumer, result) = tokio::time::timeout(Duration::from_secs(1), task)
11979            .await
11980            .expect("admitted route.open resolves")
11981            .unwrap();
11982        (shared, consumer, request, result, rx)
11983    }
11984
11985    #[tokio::test]
11986    async fn admitted_route_open_refusal_keeps_the_daemon_code_and_detail() {
11987        let shared = writer_test_shared();
11988        let (writer, mut rx) = mpsc::channel(8);
11989        let generation = {
11990            let mut inner = shared.lock_inner();
11991            inner.writer = Some(writer);
11992            inner.daemon_ver = "0.39.0".into();
11993            inner.generation
11994        };
11995        let consumer = SubcConsumer {
11996            shared: Arc::clone(&shared),
11997        };
11998        let task = tokio::spawn(async move {
11999            let result = consumer
12000                .open_route_with_admission_facts(
12001                    RouteTarget::ToolProvider {
12002                        module_id: "cerebellum".to_string(),
12003                    },
12004                    BindIdentity::new("test".to_string(), "admitted".to_string()),
12005                    serde_json::json!({"schema": 1, "verified_class": "member"}),
12006                )
12007                .await;
12008            (consumer, result)
12009        });
12010        let command = rx.recv().await.expect("one route.open must be queued");
12011        let refusal = ErrorBody {
12012            code: "module_warming".to_string(),
12013            message: "cerebellum is not ready".to_string(),
12014            detail: Some(serde_json::json!({"reason": "declared_not_ready"})),
12015        };
12016        assert!(
12017            dispatch_frame(
12018                &shared,
12019                generation,
12020                Frame::build(
12021                    FrameType::Error,
12022                    Flags::new(false, Priority::Interactive, false),
12023                    0,
12024                    0,
12025                    command.frame.header.corr,
12026                    serde_json::to_vec(&refusal).unwrap(),
12027                )
12028                .unwrap(),
12029            )
12030            .await
12031        );
12032        let (_consumer, result) = tokio::time::timeout(Duration::from_secs(1), task)
12033            .await
12034            .expect("admitted route.open resolves")
12035            .unwrap();
12036        let error = result.expect_err("a refused open is an error");
12037        assert!(
12038            error.is_not_sent(),
12039            "a refused open never reached the module: {error}"
12040        );
12041        let body = error
12042            .route_open_refusal()
12043            .unwrap_or_else(|| panic!("the refusal's code must survive: {error}"));
12044        assert_eq!(body.code, "module_warming");
12045        assert_eq!(
12046            body.detail,
12047            Some(serde_json::json!({"reason": "declared_not_ready"}))
12048        );
12049        assert!(
12050            error.to_string().contains("tool_provider:cerebellum"),
12051            "the error names its target: {error}"
12052        );
12053    }
12054
12055    #[tokio::test]
12056    async fn admitted_route_without_options_opens_and_declares_no_reverse_capabilities() {
12057        let (_shared, _consumer, request, result, _rx) = open_admitted_route_for_test(None).await;
12058        let ClientControlRequest::RouteOpen {
12059            consumer_capabilities,
12060            admission_facts,
12061            ..
12062        } = request
12063        else {
12064            panic!("expected route.open")
12065        };
12066        assert_eq!(consumer_capabilities, None);
12067        assert!(admission_facts.is_some());
12068        let handle = result.expect("admitted route opens");
12069        assert_eq!((handle.channel, handle.epoch), (21, 4));
12070    }
12071
12072    // An admitted route opened with handlers declares their capabilities and
12073    // delivers the provider's reverse requests to them, replying under the
12074    // provider's own correlation id: the browser plane's consent prompts arrive
12075    // as elicitation on exactly this kind of route.
12076    #[tokio::test]
12077    async fn admitted_route_with_options_delivers_elicitation_to_its_handler() {
12078        let opts = CallOptions::default();
12079        let seen = Arc::new(Mutex::new(None));
12080        let seen_by_handler = Arc::clone(&seen);
12081        let reply_body = br#"{"jsonrpc":"2.0","id":3,"result":{"action":"accept"}}"#.to_vec();
12082        let expected_reply = reply_body.clone();
12083        opts.reverse_requests
12084            .on_request("elicitation", move |body, ctx| {
12085                *seen_by_handler
12086                    .lock()
12087                    .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some((body, ctx.corr));
12088                let reply_body = reply_body.clone();
12089                async move { reply_body }
12090            })
12091            .unwrap();
12092
12093        let (shared, _consumer, request, result, mut rx) =
12094            open_admitted_route_for_test(Some(opts)).await;
12095        let ClientControlRequest::RouteOpen {
12096            consumer_capabilities,
12097            admission_facts,
12098            ..
12099        } = request
12100        else {
12101            panic!("expected route.open")
12102        };
12103        assert_eq!(consumer_capabilities, Some(vec!["elicitation".to_string()]));
12104        assert_eq!(
12105            admission_facts,
12106            Some(serde_json::json!({"schema": 1, "verified_class": "member"}))
12107        );
12108        let handle = result.expect("admitted route opens");
12109
12110        let request_body =
12111            br#"{"jsonrpc":"2.0","id":3,"method":"elicitation/create","params":{}}"#.to_vec();
12112        assert!(
12113            dispatch_frame(
12114                &shared,
12115                handle.connection_token(),
12116                reverse_request_frame(handle, 900, request_body.clone()),
12117            )
12118            .await
12119        );
12120        let reply = tokio::time::timeout(Duration::from_secs(1), rx.recv())
12121            .await
12122            .expect("the handler replies")
12123            .unwrap()
12124            .frame;
12125        assert_eq!(reply.header.ty, FrameType::Response);
12126        assert_eq!(reply.header.corr, 900);
12127        assert_eq!(reply.header.channel, 21);
12128        assert_eq!(reply.body, expected_reply);
12129        assert_eq!(
12130            seen.lock()
12131                .unwrap_or_else(|poisoned| poisoned.into_inner())
12132                .clone(),
12133            Some((request_body, 900))
12134        );
12135    }
12136
12137    #[tokio::test]
12138    async fn route_open_waiter_deadline_is_not_sent_without_writing() {
12139        let shared = Arc::new(reader_skew_tests::legacy_shared(
12140            PathBuf::from("/tmp/does-not-exist"),
12141            ConsumerOptions::default(),
12142        ));
12143        let (writer, mut rx) = mpsc::channel(4);
12144        let target = RouteTarget::ToolProvider {
12145            module_id: "single-flight".to_string(),
12146        };
12147        let identity = BindIdentity::new("test".to_string(), "route-open".to_string());
12148        let opts = CallOptions {
12149            timeout: Duration::from_millis(25),
12150            consumer_identity: Some(ConsumerIdentity {
12151                module_id: "caller".to_string(),
12152                launch_nonce: "nonce".to_string(),
12153            }),
12154            ..CallOptions::default()
12155        };
12156        let key = RouteKey::new(&target, &identity, opts.consumer_identity.as_ref(), None);
12157        {
12158            let mut inner = shared.lock_inner();
12159            inner.writer = Some(writer);
12160            inner.daemon_ver = "0.39.0".into();
12161            inner.openings.insert(
12162                key,
12163                Opening {
12164                    waiters: Vec::new(),
12165                    closed: false,
12166                },
12167            );
12168        }
12169
12170        let consumer = SubcConsumer { shared };
12171        let result = tokio::time::timeout(
12172            Duration::from_millis(250),
12173            consumer.open_route(target, identity, opts),
12174        )
12175        .await
12176        .expect("a route.open waiter must finish at its own deadline")
12177        .unwrap_err();
12178        assert!(matches!(result, CallError::NotSent(_)));
12179        assert!(
12180            rx.try_recv().is_err(),
12181            "a timed-out route.open waiter must not write a control frame"
12182        );
12183    }
12184
12185    // A route.open whose control reply never arrives before the deadline has an
12186    // unknown outcome of its own (the daemon may have opened the channel), but
12187    // the managed call's request body was never written. The call and the
12188    // subscription must therefore report NotSent, not OutcomeUnknown: callers
12189    // use that distinction to decide whether a non-idempotent retry is safe.
12190    async fn managed_op_with_unanswered_route_open(subscribe: bool) -> CallError {
12191        let shared = Arc::new(reader_skew_tests::legacy_shared(
12192            PathBuf::from("/tmp/does-not-exist"),
12193            ConsumerOptions::default(),
12194        ));
12195        let (writer, mut rx) = mpsc::channel(4);
12196        {
12197            let mut inner = shared.lock_inner();
12198            inner.writer = Some(writer);
12199            inner.daemon_ver = "0.39.0".into();
12200        }
12201        let consumer = SubcConsumer {
12202            shared: Arc::clone(&shared),
12203        };
12204        let target = RouteTarget::ToolProvider {
12205            module_id: "slow-route-open".to_string(),
12206        };
12207        let identity = BindIdentity::new("test".to_string(), "slow-route-open".to_string());
12208        let task = tokio::spawn(async move {
12209            if subscribe {
12210                consumer
12211                    .subscribe(
12212                        target,
12213                        identity,
12214                        b"{}".to_vec(),
12215                        SubscribeOptions {
12216                            route_open_timeout: Duration::from_millis(200),
12217                            route_retry_deadline: Duration::from_millis(100),
12218                            ..SubscribeOptions::default()
12219                        },
12220                    )
12221                    .await
12222                    .map(|_| ())
12223            } else {
12224                consumer
12225                    .call(
12226                        target,
12227                        identity,
12228                        b"{}".to_vec(),
12229                        CallOptions {
12230                            timeout: Duration::from_millis(200),
12231                            route_retry_deadline: Duration::from_millis(100),
12232                            ..CallOptions::default()
12233                        },
12234                    )
12235                    .await
12236                    .map(|_| ())
12237            }
12238        });
12239
12240        // Play the writer task: accept the route.open onto the wire (so the
12241        // consumer knows the control frame left) and then never answer it,
12242        // which is what a daemon under load looks like from the client.
12243        let command = rx.recv().await.expect("route.open must be queued");
12244        assert_eq!(command.frame.header.channel, 0);
12245        let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
12246        assert!(matches!(request, ClientControlRequest::RouteOpen { .. }));
12247        assert!(shared.mark_pending_accepted(command.pending.expect("route.open is tracked")));
12248
12249        let err = tokio::time::timeout(Duration::from_secs(2), task)
12250            .await
12251            .expect("the managed op must settle at its own deadline")
12252            .unwrap()
12253            .expect_err("an unanswered route.open cannot yield a route");
12254        while let Ok(command) = rx.try_recv() {
12255            assert_eq!(
12256                command.frame.header.channel, 0,
12257                "no data-plane frame may be written without an open route"
12258            );
12259        }
12260        err
12261    }
12262
12263    #[tokio::test]
12264    async fn call_whose_route_open_times_out_after_send_is_not_sent() {
12265        let err = managed_op_with_unanswered_route_open(false).await;
12266        assert!(
12267            matches!(err, CallError::NotSent(_)),
12268            "call body never left the client, got {err:?}"
12269        );
12270    }
12271
12272    #[tokio::test]
12273    async fn subscribe_whose_route_open_times_out_after_send_is_not_sent() {
12274        let err = managed_op_with_unanswered_route_open(true).await;
12275        assert!(
12276            matches!(err, CallError::NotSent(_)),
12277            "subscription request never left the client, got {err:?}"
12278        );
12279    }
12280
12281    #[tokio::test]
12282    async fn route_poll_deadline_bounds_writer_capacity() {
12283        let shared = Arc::new(reader_skew_tests::legacy_shared(
12284            PathBuf::from("/tmp/does-not-exist"),
12285            ConsumerOptions::default(),
12286        ));
12287        let (writer, mut rx) = mpsc::channel(1);
12288        let handle = RouteHandle::new(8, 4, 1);
12289        writer
12290            .try_send(WriteCommand {
12291                frame: response_frame(0, 0, 99, Vec::new()),
12292                pending: None,
12293            })
12294            .expect("the fake daemon queue should accept its filler frame");
12295        {
12296            let mut inner = shared.lock_inner();
12297            inner.writer = Some(writer);
12298            inner.daemon_ver = "0.39.0".into();
12299            inner.route_epochs.insert(handle.channel, handle);
12300        }
12301
12302        let consumer = SubcConsumer { shared };
12303        let result = tokio::time::timeout(
12304            Duration::from_millis(250),
12305            consumer.poll_route(&handle, PollKind::Liveness, Duration::from_millis(25)),
12306        )
12307        .await
12308        .expect("a control request must finish at its own deadline")
12309        .unwrap_err();
12310        assert!(matches!(result, CallError::NotSent(_)));
12311        assert_eq!(
12312            rx.recv()
12313                .await
12314                .expect("the filler must still be the only queued frame")
12315                .frame
12316                .header
12317                .corr,
12318            99
12319        );
12320        assert!(
12321            rx.try_recv().is_err(),
12322            "the timed-out control request must not reach the fake daemon"
12323        );
12324    }
12325
12326    #[tokio::test]
12327    async fn subscription_deadline_bounds_writer_capacity() {
12328        let shared = Arc::new(reader_skew_tests::legacy_shared(
12329            PathBuf::from("/tmp/does-not-exist"),
12330            ConsumerOptions::default(),
12331        ));
12332        let (writer, mut rx) = mpsc::channel(1);
12333        let handle = RouteHandle::new(9, 2, 1);
12334        let route_sem = Arc::new(Semaphore::new(1));
12335        writer
12336            .try_send(WriteCommand {
12337                frame: response_frame(0, 0, 100, Vec::new()),
12338                pending: None,
12339            })
12340            .expect("the fake daemon queue should accept its filler frame");
12341        {
12342            let mut inner = shared.lock_inner();
12343            inner.writer = Some(writer);
12344            inner.daemon_ver = "0.39.0".into();
12345            inner.cache_route(
12346                RouteKey::new(
12347                    &RouteTarget::ToolProvider {
12348                        module_id: "subscriptions".to_string(),
12349                    },
12350                    &BindIdentity::new("test".to_string(), "subscription".to_string()),
12351                    None,
12352                    None,
12353                ),
12354                RouteState {
12355                    handle,
12356                    sem: Arc::clone(&route_sem),
12357                    watch_sem: None,
12358                    opted_in: false,
12359                },
12360            );
12361        }
12362
12363        let consumer = SubcConsumer { shared };
12364        let result = tokio::time::timeout(
12365            Duration::from_millis(250),
12366            consumer.subscribe_route(
12367                &handle,
12368                b"subscribe".to_vec(),
12369                SubscribeOptions {
12370                    route_open_timeout: Duration::from_millis(25),
12371                    ..SubscribeOptions::default()
12372                },
12373            ),
12374        )
12375        .await
12376        .expect("a subscription must finish at its route-open deadline");
12377        let result = match result {
12378            Ok(_) => panic!("a subscription blocked before writing must time out"),
12379            Err(err) => err,
12380        };
12381        assert!(matches!(result, CallError::NotSent(_)));
12382        assert_eq!(
12383            rx.recv()
12384                .await
12385                .expect("the filler must still be the only queued frame")
12386                .frame
12387                .header
12388                .corr,
12389            100
12390        );
12391        assert!(
12392            rx.try_recv().is_err(),
12393            "the timed-out subscription must not reach the fake daemon"
12394        );
12395        assert!(
12396            route_sem.try_acquire().is_ok(),
12397            "a pre-write subscription timeout must release its route credit"
12398        );
12399    }
12400
12401    #[test]
12402    fn catalog_list_deserializes_golden_reply_and_ignores_unknown_fields() {
12403        let mut reply: serde_json::Value = serde_json::from_str(include_str!(
12404            "../../subc-control/tests/golden/client_control_response_catalog_list.json"
12405        ))
12406        .expect("the catalog.list golden reply must be valid JSON");
12407        reply["future_top_level"] = serde_json::json!(true);
12408        reply["modules"][0]["future_module_field"] = serde_json::json!("ignored");
12409
12410        let catalog: CatalogList =
12411            serde_json::from_value(reply).expect("catalog.list should tolerate additive fields");
12412        assert_eq!(catalog.generation, 7);
12413        assert_eq!(catalog.modules.len(), 1);
12414        assert!(catalog.subc_ops.iter().any(|op| op == "catalog.list"));
12415
12416        let tools = catalog.modules[0]
12417            .roles
12418            .iter()
12419            .find_map(|role| match role {
12420                subc_protocol::manifest::ProviderRole::ToolProvider { tools, .. } => Some(tools),
12421                _ => None,
12422            })
12423            .expect("the golden module must advertise a tool_provider role");
12424        let tool = tools
12425            .first()
12426            .expect("the golden tool_provider role must advertise a tool");
12427        assert!(!tool.name.is_empty());
12428        assert_eq!(
12429            tool.schema.get("type").and_then(serde_json::Value::as_str),
12430            Some("object")
12431        );
12432        assert!(matches!(
12433            tool.execution_mode,
12434            subc_protocol::manifest::ExecutionMode::Pure
12435        ));
12436    }
12437
12438    #[tokio::test]
12439    async fn catalog_list_sends_an_unfiltered_channel_zero_request() {
12440        let shared = Arc::new(reader_skew_tests::legacy_shared(
12441            PathBuf::from("/tmp/does-not-exist"),
12442            ConsumerOptions::default(),
12443        ));
12444        let (writer, mut rx) = mpsc::channel(1);
12445        shared.lock_inner().writer = Some(writer);
12446        shared.lock_inner().daemon_ver = "0.39.0".into();
12447
12448        let consumer = SubcConsumer {
12449            shared: Arc::clone(&shared),
12450        };
12451        let request = tokio::spawn(async move { consumer.catalog_list().await });
12452        let command = rx
12453            .recv()
12454            .await
12455            .expect("catalog.list must queue a channel-0 request");
12456        assert_eq!(command.frame.header.channel, 0);
12457        let body: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
12458        assert_eq!(body["op"], "catalog.list");
12459        assert!(
12460            body.get("module_id").is_none(),
12461            "catalog.list must request the complete catalog without a module filter"
12462        );
12463
12464        let response = serde_json::to_vec(&ClientControlResponse::CatalogList {
12465            generation: 9,
12466            modules: Vec::new(),
12467            subc_ops: vec!["catalog.list".to_string()],
12468        })
12469        .unwrap();
12470        assert!(
12471            dispatch_frame(
12472                &shared,
12473                1,
12474                response_frame(0, 0, command.frame.header.corr, response),
12475            )
12476            .await
12477        );
12478        let catalog = request.await.unwrap().unwrap();
12479        assert_eq!(catalog.generation, 9);
12480        assert!(catalog.modules.is_empty());
12481    }
12482
12483    #[tokio::test]
12484    async fn spawn_snapshot_sends_a_channel_zero_request_and_returns_the_snapshot() {
12485        let shared = Arc::new(reader_skew_tests::legacy_shared(
12486            PathBuf::from("/tmp/does-not-exist"),
12487            ConsumerOptions::default(),
12488        ));
12489        let (writer, mut rx) = mpsc::channel(1);
12490        shared.lock_inner().writer = Some(writer);
12491        shared.lock_inner().daemon_ver = "0.39.0".into();
12492
12493        let consumer = SubcConsumer {
12494            shared: Arc::clone(&shared),
12495        };
12496        let request = tokio::spawn(async move { consumer.spawn_snapshot().await });
12497        let command = rx
12498            .recv()
12499            .await
12500            .expect("supervisor.spawn_snapshot must queue a channel-0 request");
12501        assert_eq!(command.frame.header.channel, 0);
12502        let body: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
12503        assert_eq!(body["op"], "supervisor.spawn_snapshot");
12504
12505        let snapshot = SpawnSnapshot {
12506            cursor: SpawnCursor {
12507                daemon_incarnation: "incarnation-a".to_string(),
12508                seq: 41,
12509            },
12510            ring_bound: 256,
12511            live: vec![LiveSpawn {
12512                module_id: "participant".to_string(),
12513                spawn_generation: 3,
12514                pid: 4242,
12515                spawned_at_ms: 1_700_000_000_000,
12516            }],
12517        };
12518        let response = serde_json::to_vec(&ClientControlResponse::SupervisorSpawnSnapshot {
12519            snapshot: snapshot.clone(),
12520        })
12521        .unwrap();
12522        assert!(
12523            dispatch_frame(
12524                &shared,
12525                1,
12526                response_frame(0, 0, command.frame.header.corr, response),
12527            )
12528            .await
12529        );
12530        assert_eq!(request.await.unwrap().unwrap(), snapshot);
12531    }
12532
12533    #[tokio::test]
12534    async fn spawn_snapshot_refusal_keeps_the_daemon_code() {
12535        let shared = Arc::new(reader_skew_tests::legacy_shared(
12536            PathBuf::from("/tmp/does-not-exist"),
12537            ConsumerOptions::default(),
12538        ));
12539        let (writer, mut rx) = mpsc::channel(1);
12540        shared.lock_inner().writer = Some(writer);
12541        shared.lock_inner().daemon_ver = "0.39.0".into();
12542
12543        let consumer = SubcConsumer {
12544            shared: Arc::clone(&shared),
12545        };
12546        let request = tokio::spawn(async move { consumer.spawn_snapshot().await });
12547        let command = rx
12548            .recv()
12549            .await
12550            .expect("supervisor.spawn_snapshot must queue a channel-0 request");
12551        let refusal = serde_json::to_vec(&ErrorBody {
12552            code: "op_not_permitted".to_string(),
12553            message: "refused by the test".to_string(),
12554            detail: None,
12555        })
12556        .unwrap();
12557        let frame = Frame::build(
12558            FrameType::Error,
12559            Flags::new(false, Priority::Interactive, false),
12560            0,
12561            0,
12562            command.frame.header.corr,
12563            refusal,
12564        )
12565        .unwrap();
12566        assert!(dispatch_frame(&shared, 1, frame).await);
12567        let error = request.await.unwrap().unwrap_err();
12568        assert_eq!(error.code(), Some("op_not_permitted"));
12569    }
12570
12571    fn spawn_cursor(seq: u64) -> SpawnCursor {
12572        SpawnCursor {
12573            daemon_incarnation: "incarnation-a".to_string(),
12574            seq,
12575        }
12576    }
12577
12578    fn spawn_event(seq: u64, kind: SpawnEventKind, generation: u64) -> SpawnEvent {
12579        SpawnEvent {
12580            cursor: spawn_cursor(seq),
12581            kind,
12582            module_id: "participant".to_string(),
12583            spawn_generation: generation,
12584            pid: 4242,
12585            exit_code: (kind == SpawnEventKind::Exited).then_some(0),
12586            exit_signal: None,
12587        }
12588    }
12589
12590    fn channel_zero_frame(ty: FrameType, corr: u64, body: Vec<u8>) -> Frame {
12591        Frame::build(
12592            ty,
12593            Flags::new(false, Priority::Interactive, false),
12594            0,
12595            0,
12596            corr,
12597            body,
12598        )
12599        .unwrap()
12600    }
12601
12602    fn spawn_error_frame(corr: u64, code: &str, detail: serde_json::Value) -> Frame {
12603        channel_zero_frame(
12604            FrameType::Error,
12605            corr,
12606            serde_json::to_vec(&ErrorBody {
12607                code: code.to_string(),
12608                message: "sent by the test".to_string(),
12609                detail: Some(detail),
12610            })
12611            .unwrap(),
12612        )
12613    }
12614
12615    /// A consumer over the writer-test harness, subscribed from `since`, with the
12616    /// request frame it queued.
12617    async fn spawn_subscribed(
12618        since: Option<SpawnCursor>,
12619    ) -> (
12620        Arc<Shared>,
12621        mpsc::Receiver<WriteCommand>,
12622        SpawnSubscription,
12623        Frame,
12624    ) {
12625        let shared = writer_test_shared();
12626        let (writer, mut rx) = mpsc::channel(8);
12627        shared.lock_inner().writer = Some(writer);
12628        shared.lock_inner().daemon_ver = "0.39.0".into();
12629        let consumer = SubcConsumer {
12630            shared: Arc::clone(&shared),
12631        };
12632        let subscription = consumer
12633            .spawn_subscribe(since)
12634            .await
12635            .expect("supervisor.spawn_subscribe must be sent");
12636        std::mem::forget(consumer);
12637        let command = rx
12638            .recv()
12639            .await
12640            .expect("supervisor.spawn_subscribe must queue a channel-0 request");
12641        (shared, rx, subscription, command.frame)
12642    }
12643
12644    #[tokio::test]
12645    async fn spawn_subscribe_sends_its_cursor_on_channel_zero_and_yields_events_until_stream_end() {
12646        let (shared, _rx, mut subscription, request) =
12647            spawn_subscribed(Some(spawn_cursor(7))).await;
12648        assert_eq!(request.header.channel, 0);
12649        assert_eq!(request.header.ty, FrameType::Request);
12650        let body: serde_json::Value = serde_json::from_slice(&request.body).unwrap();
12651        assert_eq!(
12652            body,
12653            serde_json::json!({
12654                "op": "supervisor.spawn_subscribe",
12655                "since": {"daemon_incarnation": "incarnation-a", "seq": 7},
12656            })
12657        );
12658
12659        let corr = request.header.corr;
12660        let events = [
12661            spawn_event(8, SpawnEventKind::Exited, 3),
12662            spawn_event(9, SpawnEventKind::Spawned, 4),
12663        ];
12664        for event in &events {
12665            let body = serde_json::to_vec(event).unwrap();
12666            assert!(
12667                dispatch_frame(
12668                    &shared,
12669                    1,
12670                    channel_zero_frame(FrameType::StreamData, corr, body)
12671                )
12672                .await
12673            );
12674        }
12675        assert!(
12676            dispatch_frame(
12677                &shared,
12678                1,
12679                channel_zero_frame(FrameType::StreamEnd, corr, Vec::new())
12680            )
12681            .await
12682        );
12683        assert_eq!(subscription.next().await.unwrap(), Some(events[0].clone()));
12684        assert_eq!(subscription.next().await.unwrap(), Some(events[1].clone()));
12685        assert_eq!(subscription.next().await.unwrap(), None);
12686        assert_eq!(
12687            subscription.next().await.unwrap(),
12688            None,
12689            "a finished stream stays finished"
12690        );
12691    }
12692
12693    #[tokio::test]
12694    async fn spawn_subscribe_without_a_cursor_omits_since() {
12695        let (_shared, _rx, _subscription, request) = spawn_subscribed(None).await;
12696        let body: serde_json::Value = serde_json::from_slice(&request.body).unwrap();
12697        assert_eq!(
12698            body,
12699            serde_json::json!({"op": "supervisor.spawn_subscribe"})
12700        );
12701    }
12702
12703    #[tokio::test]
12704    async fn spawn_cursor_refusals_surface_as_coded_errors_with_their_detail() {
12705        let (shared, _rx, mut subscription, request) =
12706            spawn_subscribed(Some(spawn_cursor(7))).await;
12707        let frame = spawn_error_frame(
12708            request.header.corr,
12709            "spawn_cursor_incarnation_mismatch",
12710            serde_json::json!({"current_daemon_incarnation": "incarnation-b"}),
12711        );
12712        assert!(dispatch_frame(&shared, 1, frame).await);
12713        let error = subscription.next().await.unwrap_err();
12714        assert_eq!(error.code(), Some("spawn_cursor_incarnation_mismatch"));
12715        let SpawnStreamError::CursorIncarnationMismatch {
12716            current_daemon_incarnation,
12717            body,
12718        } = &error
12719        else {
12720            panic!("expected the incarnation refusal, got {error:?}");
12721        };
12722        assert_eq!(current_daemon_incarnation, "incarnation-b");
12723        assert_eq!(body.code, "spawn_cursor_incarnation_mismatch");
12724        assert_eq!(subscription.next().await.unwrap(), None);
12725
12726        let (shared, _rx, mut subscription, request) =
12727            spawn_subscribed(Some(spawn_cursor(1))).await;
12728        let frame = spawn_error_frame(
12729            request.header.corr,
12730            "spawn_cursor_too_old",
12731            serde_json::json!({"oldest_retained_cursor": spawn_cursor(90)}),
12732        );
12733        assert!(dispatch_frame(&shared, 1, frame).await);
12734        let error = subscription.next().await.unwrap_err();
12735        assert_eq!(error.code(), Some("spawn_cursor_too_old"));
12736        let SpawnStreamError::CursorTooOld {
12737            oldest_retained_cursor,
12738            ..
12739        } = &error
12740        else {
12741            panic!("expected the too-old refusal, got {error:?}");
12742        };
12743        assert_eq!(oldest_retained_cursor, &spawn_cursor(90));
12744    }
12745
12746    #[tokio::test]
12747    async fn a_lagged_spawn_stream_yields_its_queued_events_then_the_lag_error() {
12748        let (shared, _rx, mut subscription, request) =
12749            spawn_subscribed(Some(spawn_cursor(7))).await;
12750        let corr = request.header.corr;
12751        let queued = spawn_event(8, SpawnEventKind::Exited, 3);
12752        assert!(
12753            dispatch_frame(
12754                &shared,
12755                1,
12756                channel_zero_frame(
12757                    FrameType::StreamData,
12758                    corr,
12759                    serde_json::to_vec(&queued).unwrap()
12760                ),
12761            )
12762            .await
12763        );
12764        let frame = spawn_error_frame(
12765            corr,
12766            "spawn_subscriber_lagged",
12767            serde_json::json!({"first_undelivered_cursor": spawn_cursor(9)}),
12768        );
12769        assert!(dispatch_frame(&shared, 1, frame).await);
12770        assert_eq!(subscription.next().await.unwrap(), Some(queued));
12771        let error = subscription.next().await.unwrap_err();
12772        assert_eq!(error.code(), Some("spawn_subscriber_lagged"));
12773        let SpawnStreamError::SubscriberLagged {
12774            first_undelivered_cursor,
12775            ..
12776        } = &error
12777        else {
12778            panic!("expected the lag error, got {error:?}");
12779        };
12780        assert_eq!(first_undelivered_cursor, &spawn_cursor(9));
12781    }
12782
12783    #[tokio::test]
12784    async fn dropping_a_spawn_subscription_sends_a_channel_zero_cancel_for_its_corr() {
12785        let (_shared, mut rx, subscription, request) =
12786            spawn_subscribed(Some(spawn_cursor(7))).await;
12787        drop(subscription);
12788        let cancel = tokio::time::timeout(Duration::from_secs(1), rx.recv())
12789            .await
12790            .expect("dropping the subscription must queue a Cancel")
12791            .expect("the writer stays open");
12792        assert_eq!(cancel.frame.header.ty, FrameType::Cancel);
12793        assert_eq!(cancel.frame.header.channel, 0);
12794        assert_eq!(cancel.frame.header.corr, request.header.corr);
12795    }
12796
12797    #[tokio::test]
12798    async fn reconnect_completion_between_wait_decision_and_registration_wakes_caller() {
12799        let shared = Arc::new(reader_skew_tests::legacy_shared(
12800            PathBuf::from("/tmp/subc-client-rs-reconnect-wakeup"),
12801            ConsumerOptions::default(),
12802        ));
12803        let (sender, _receiver) = mpsc::channel(EGRESS_BUFFER);
12804        {
12805            let mut inner = shared.lock_inner();
12806            inner.reconnect = ReconnectState::Inline {
12807                generation: inner.generation,
12808            };
12809        }
12810        let completing = Arc::clone(&shared);
12811        *shared.before_wait.lock().unwrap() = Some(Box::new(move || {
12812            completing.lock_inner().writer = Some(sender);
12813            completing.lock_inner().daemon_ver = "0.39.0".into();
12814            completing.notify.notify_waiters();
12815        }));
12816
12817        let result = shared
12818            .ensure_connected_for_call(Instant::now() + Duration::from_millis(30))
12819            .await;
12820        assert!(
12821            result.is_ok(),
12822            "connected caller should not time out: {result:?}"
12823        );
12824        assert!(shared.before_wait.lock().unwrap().is_none());
12825    }
12826
12827    #[tokio::test]
12828    async fn catalog_list_deadline_is_not_sent_when_reconnection_stays_down() {
12829        let shared = Arc::new(reader_skew_tests::legacy_shared(
12830            PathBuf::from("/tmp/subc-client-rs-catalog-list-unavailable"),
12831            ConsumerOptions {
12832                call_timeout: Duration::from_millis(25),
12833                reconnect_backoff: RetryBackoff {
12834                    base: Duration::from_millis(1),
12835                    cap: Duration::from_millis(1),
12836                    max_attempts: 100,
12837                },
12838                ..ConsumerOptions::default()
12839            },
12840        ));
12841        let consumer = SubcConsumer { shared };
12842        let result = tokio::time::timeout(Duration::from_millis(250), consumer.catalog_list())
12843            .await
12844            .expect("catalog.list must finish at its configured deadline")
12845            .unwrap_err();
12846        assert!(matches!(result, CallError::NotSent(_)));
12847    }
12848
12849    fn consumer_with_malformed_connection_file(
12850    ) -> (cortexkit_test_support::ScratchDir, SubcConsumer) {
12851        let temp = cortexkit_test_support::ScratchDir::new("consumer-malformed-connection");
12852        let path = temp.path().join("connection.json");
12853        std::fs::write(&path, b"not JSON").unwrap();
12854        #[cfg(unix)]
12855        {
12856            use std::os::unix::fs::PermissionsExt;
12857            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap();
12858        }
12859        let shared = Arc::new(reader_skew_tests::legacy_shared(
12860            path,
12861            ConsumerOptions {
12862                call_timeout: Duration::from_millis(100),
12863                reconnect_backoff: RetryBackoff {
12864                    base: Duration::from_millis(20),
12865                    cap: Duration::from_millis(40),
12866                    max_attempts: 6,
12867                },
12868                ..ConsumerOptions::default()
12869            },
12870        ));
12871        (temp, SubcConsumer { shared })
12872    }
12873
12874    // A malformed file fails synchronously. Keep the clock running so an unpaced
12875    // retry loop reaches its deadline instead of hanging a paused-time runtime.
12876    #[tokio::test]
12877    async fn catalog_list_backs_off_after_malformed_connection_file_and_close_cancels_it() {
12878        let (_temp, consumer) = consumer_with_malformed_connection_file();
12879        let call = consumer.catalog_list();
12880        tokio::pin!(call);
12881        assert_pending(call.as_mut()).await;
12882        consumer.close().await;
12883        let err = call.await.unwrap_err();
12884        assert!(matches!(err, CallError::NotSent(_)));
12885        assert!(err.to_string().contains("consumer closed"));
12886    }
12887
12888    #[tokio::test]
12889    async fn spawn_snapshot_backs_off_after_malformed_connection_file_and_close_cancels_it() {
12890        let (_temp, consumer) = consumer_with_malformed_connection_file();
12891        let call = consumer.spawn_snapshot();
12892        tokio::pin!(call);
12893        assert_pending(call.as_mut()).await;
12894        consumer.close().await;
12895        let err = call.await.unwrap_err();
12896        assert!(matches!(err, CallError::NotSent(_)));
12897        assert!(err.to_string().contains("consumer closed"));
12898    }
12899}
12900
12901#[cfg(test)]
12902mod launch_nonce_redaction_tests {
12903    use super::*;
12904
12905    const NONCE: &str = "nonce-f00dfeed1234abcd";
12906
12907    #[test]
12908    fn option_types_and_route_keys_never_print_the_nonce() {
12909        let identity = ConsumerIdentity {
12910            module_id: "wernicke".to_string(),
12911            launch_nonce: NONCE.to_string(),
12912        };
12913        let call = CallOptions {
12914            consumer_identity: Some(identity.clone()),
12915            ..CallOptions::default()
12916        };
12917        let key = ConsumerIdentityKey::from(&identity);
12918        for printed in [format!("{call:?}"), format!("{key:?}")] {
12919            assert!(!printed.contains(NONCE), "launch nonce printed: {printed}");
12920        }
12921    }
12922}