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 as _, 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 config_ops;
101mod supervisor_ops;
102use catalog::decode_route_open_response;
103pub use catalog::CatalogSubscription;
104pub use config_ops::{
105    ConfigApplyResponse, ConfigEdit, ConfigEditAction, ConfigFileError, ConfigModule,
106    ConfigModulesResponse, ConfigPlanRefusal, ConfigPlanView, ConfigSchemaResponse,
107    ConfigSettingsLayer, ConfigShowResponse, ConfigSubscription, ConfigThrough, ConfigWatchEvent,
108    Digest,
109};
110
111#[cfg(test)]
112mod reader_skew_tests;
113
114#[cfg(test)]
115mod connection_ops_tests;
116pub use cancellation::{CancelHandle, CancelOutcome};
117use cancellation::{CancelRegistration, UnaryCancel};
118pub use supervisor_ops::{
119    HealthProbeResponse, ServerDescription, StderrTailResponse, SupervisorAck,
120    SupervisorHealthResponse, SupervisorProvenanceResponse,
121};
122
123/// `supervisor.spawn_subscribe` refused a cursor from another daemon incarnation.
124pub const SPAWN_CURSOR_INCARNATION_MISMATCH: &str = "spawn_cursor_incarnation_mismatch";
125/// `supervisor.spawn_subscribe` refused a cursor older than the daemon's retained ring.
126pub const SPAWN_CURSOR_TOO_OLD: &str = "spawn_cursor_too_old";
127/// The daemon dropped a spawn subscriber that fell too far behind.
128pub const SPAWN_SUBSCRIBER_LAGGED: &str = "spawn_subscriber_lagged";
129
130type ReverseRequestFuture =
131    Pin<Box<dyn Future<Output = Result<Vec<u8>, ReverseRequestError>> + Send + 'static>>;
132type ReverseRequestHandler =
133    Arc<dyn Fn(Vec<u8>, ReverseRequestContext) -> ReverseRequestFuture + Send + Sync + 'static>;
134
135#[derive(Debug, Clone, PartialEq, Eq)]
136pub struct ReverseRequestContext {
137    pub corr: u64,
138    pub method: String,
139}
140
141#[derive(Debug, Clone, PartialEq, Eq)]
142pub struct ReverseRequestError {
143    message: String,
144}
145
146impl ReverseRequestError {
147    pub fn new(message: impl Into<String>) -> Self {
148        Self {
149            message: message.into(),
150        }
151    }
152}
153
154impl fmt::Display for ReverseRequestError {
155    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
156        f.write_str(&self.message)
157    }
158}
159
160impl Error for ReverseRequestError {}
161
162#[derive(Default)]
163struct ReverseRequestRegistryState {
164    handlers: HashMap<String, ReverseRequestHandler>,
165    declared_families: Option<BTreeSet<String>>,
166    consumer_capabilities: BTreeSet<String>,
167}
168
169/// Handler registry prepared before route.open. It carries the reverse-request
170/// method families and any extra capability strings added through route options'
171/// `with_consumer_capability` builder.
172#[derive(Clone, Default)]
173pub struct ReverseRequestRegistry {
174    inner: Arc<Mutex<ReverseRequestRegistryState>>,
175}
176
177impl fmt::Debug for ReverseRequestRegistry {
178    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
179        f.debug_struct("ReverseRequestRegistry")
180            .field("capabilities", &self.capabilities())
181            .field("consumer_capabilities", &self.consumer_capabilities())
182            .finish()
183    }
184}
185
186impl PartialEq for ReverseRequestRegistry {
187    fn eq(&self, other: &Self) -> bool {
188        self.capabilities() == other.capabilities()
189            && self.consumer_capabilities() == other.consumer_capabilities()
190    }
191}
192
193impl Eq for ReverseRequestRegistry {}
194
195impl ReverseRequestRegistry {
196    pub fn new() -> Self {
197        Self::default()
198    }
199
200    pub fn on_request<F, Fut>(
201        &self,
202        method_family: impl Into<String>,
203        handler: F,
204    ) -> Result<(), ReverseRequestRegistrationError>
205    where
206        F: Fn(Vec<u8>, ReverseRequestContext) -> Fut + Send + Sync + 'static,
207        Fut: Future<Output = Vec<u8>> + Send + 'static,
208    {
209        self.on_request_fallible(method_family, move |body, ctx| {
210            let future = handler(body, ctx);
211            async move { Ok(future.await) }
212        })
213    }
214
215    pub fn on_request_fallible<F, Fut>(
216        &self,
217        method_family: impl Into<String>,
218        handler: F,
219    ) -> Result<(), ReverseRequestRegistrationError>
220    where
221        F: Fn(Vec<u8>, ReverseRequestContext) -> Fut + Send + Sync + 'static,
222        Fut: Future<Output = Result<Vec<u8>, ReverseRequestError>> + Send + 'static,
223    {
224        let method_family = method_family.into();
225        if !is_valid_method_family(&method_family) {
226            return Err(ReverseRequestRegistrationError::InvalidFamily(
227                method_family,
228            ));
229        }
230        let mut state = self
231            .inner
232            .lock()
233            .unwrap_or_else(|poisoned| poisoned.into_inner());
234        if state
235            .declared_families
236            .as_ref()
237            .is_some_and(|families| !families.contains(&method_family))
238        {
239            return Err(ReverseRequestRegistrationError::NotDeclared(method_family));
240        }
241        state.handlers.insert(
242            method_family,
243            Arc::new(move |body, ctx| Box::pin(handler(body, ctx))),
244        );
245        Ok(())
246    }
247
248    fn capabilities(&self) -> Vec<String> {
249        let state = self
250            .inner
251            .lock()
252            .unwrap_or_else(|poisoned| poisoned.into_inner());
253        let mut capabilities = state.handlers.keys().cloned().collect::<Vec<_>>();
254        capabilities.sort();
255        capabilities
256    }
257
258    fn declare_consumer_capability(
259        &self,
260        capability: String,
261    ) -> Result<(), ConsumerCapabilityError> {
262        if capability.is_empty()
263            || capability.len() > 64
264            || !capability.bytes().all(|byte| (0x21..=0x7e).contains(&byte))
265        {
266            return Err(ConsumerCapabilityError { capability });
267        }
268
269        self.inner
270            .lock()
271            .unwrap_or_else(|poisoned| poisoned.into_inner())
272            .consumer_capabilities
273            .insert(capability);
274        Ok(())
275    }
276
277    fn consumer_capabilities(&self) -> Vec<String> {
278        self.inner
279            .lock()
280            .unwrap_or_else(|poisoned| poisoned.into_inner())
281            .consumer_capabilities
282            .iter()
283            .cloned()
284            .collect()
285    }
286
287    fn handler(&self, method_family: &str) -> Option<ReverseRequestHandler> {
288        self.inner
289            .lock()
290            .unwrap_or_else(|poisoned| poisoned.into_inner())
291            .handlers
292            .get(method_family)
293            .cloned()
294    }
295
296    pub(crate) fn seal(&self) {
297        let mut state = self
298            .inner
299            .lock()
300            .unwrap_or_else(|poisoned| poisoned.into_inner());
301        if state.declared_families.is_none() {
302            state.declared_families = Some(state.handlers.keys().cloned().collect());
303        }
304    }
305}
306
307#[derive(Debug, Clone, PartialEq, Eq)]
308pub enum ReverseRequestRegistrationError {
309    InvalidFamily(String),
310    NotDeclared(String),
311    NotConsumerRoute,
312}
313
314impl fmt::Display for ReverseRequestRegistrationError {
315    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
316        match self {
317            Self::InvalidFamily(family) => {
318                write!(f, "invalid reverse-request method family {family:?}")
319            }
320            Self::NotDeclared(family) => write!(
321                f,
322                "reverse-request capability {family:?} was not registered before route.open"
323            ),
324            Self::NotConsumerRoute => {
325                f.write_str("route handle does not belong to a consumer route")
326            }
327        }
328    }
329}
330
331impl Error for ReverseRequestRegistrationError {}
332
333fn is_valid_method_family(value: &str) -> bool {
334    let mut segments = value.split(['.', '_', '-']);
335    segments.next().is_some_and(|segment| {
336        segment
337            .as_bytes()
338            .first()
339            .is_some_and(u8::is_ascii_lowercase)
340            && segment
341                .bytes()
342                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
343    }) && segments.all(|segment| {
344        !segment.is_empty()
345            && segment
346                .bytes()
347                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
348    })
349}
350
351/// Reverse-request handlers live in a process-global map keyed by an id the
352/// `RouteHandle` carries, rather than inside the handle itself.
353///
354/// WHY, so nobody "simplifies" this into the handle later: `RouteHandle` is
355/// `Copy`, deliberately and publicly. Every route-scoped call in this SDK takes
356/// it by value, and the fleet's Rust consumers pass it around freely on that
357/// assumption. An `Arc<ReverseRequestRegistry>` field would make it non-`Copy`
358/// and break every one of those call sites across twelve repositories, for a
359/// lane most of them do not use.
360///
361/// The cost is real and bounded: entries are removed on every teardown path
362/// (`remove_route`, `remove_route_by_handle`, `drain_routes`,
363/// `uninstall_route_handle`, `install_ingress_handle`), so a consumer that opens
364/// and closes routes for its lifetime does not grow. A consumer DROPPED without
365/// closing leaks its remaining entries until process exit, which is the one gap
366/// and is acceptable because nothing else about a dropped consumer is reclaimed
367/// either.
368///
369/// If `RouteHandle` ever stops being `Copy` for another reason, move this into
370/// the handle and delete the map — the indirection exists only to preserve that
371/// property.
372static NEXT_REVERSE_REQUEST_REGISTRY_ID: AtomicU64 = AtomicU64::new(1);
373static REVERSE_REQUEST_REGISTRIES: OnceLock<Mutex<HashMap<u64, ReverseRequestRegistry>>> =
374    OnceLock::new();
375
376fn reverse_request_registries() -> &'static Mutex<HashMap<u64, ReverseRequestRegistry>> {
377    REVERSE_REQUEST_REGISTRIES.get_or_init(|| Mutex::new(HashMap::new()))
378}
379
380pub(crate) fn install_reverse_request_registry(registry: ReverseRequestRegistry) -> u64 {
381    let id = crate::checked_increment(&NEXT_REVERSE_REQUEST_REGISTRY_ID)
382        .expect("reverse-request route registry id exhausted");
383    reverse_request_registries()
384        .lock()
385        .unwrap_or_else(|poisoned| poisoned.into_inner())
386        .insert(id, registry);
387    id
388}
389
390pub(crate) fn route_reverse_request_registry(
391    id: u64,
392) -> Result<ReverseRequestRegistry, ReverseRequestRegistrationError> {
393    if id == 0 {
394        return Err(ReverseRequestRegistrationError::NotConsumerRoute);
395    }
396    reverse_request_registries()
397        .lock()
398        .unwrap_or_else(|poisoned| poisoned.into_inner())
399        .get(&id)
400        .cloned()
401        .ok_or(ReverseRequestRegistrationError::NotConsumerRoute)
402}
403
404fn release_reverse_request_registry(handle: RouteHandle) {
405    let id = handle.reverse_request_registry_id();
406    if id != 0 {
407        reverse_request_registries()
408            .lock()
409            .unwrap_or_else(|poisoned| poisoned.into_inner())
410            .remove(&id);
411    }
412}
413
414/// Capped exponential backoff used for reconnects and transient route-open retry.
415/// Each delay is jittered before it is slept: half of it is kept and the other
416/// half is random.
417#[derive(Debug, Clone, Copy, PartialEq, Eq)]
418pub struct RetryBackoff {
419    pub base: Duration,
420    pub cap: Duration,
421    /// Maximum attempts, including the first immediate attempt.
422    pub max_attempts: usize,
423}
424
425impl Default for RetryBackoff {
426    fn default() -> Self {
427        Self {
428            base: Duration::from_millis(100),
429            cap: Duration::from_secs(2),
430            max_attempts: 6,
431        }
432    }
433}
434
435impl RetryBackoff {
436    fn delay_after_attempt(self, attempt: usize) -> Duration {
437        let mut delay = self.base;
438        for _ in 1..attempt {
439            delay = (delay * 2).min(self.cap);
440        }
441        delay
442    }
443}
444
445/// Transport used for the initial connection and every reconnect attempt.
446#[derive(Debug, Clone, Copy, PartialEq, Eq)]
447enum ConsumerTransport {
448    /// Use the connection file's TCP endpoint (the default).
449    Tcp,
450    /// Use only `local_endpoint`, re-read on every connection attempt.
451    Local,
452}
453
454/// Options for [`SubcConsumer::connect`].
455#[derive(Debug, Clone, PartialEq, Eq)]
456pub struct ConsumerOptions {
457    pub handshake_timeout: Duration,
458    /// Deadline for channel-0 calls that do not take per-call options.
459    pub call_timeout: Duration,
460    pub reconnect_backoff: RetryBackoff,
461    pub restored_debounce: Duration,
462    /// Window a post-deadline Ping waits for any inbound frame before the connection is
463    /// treated as half-open. Exposed so callers can use a shorter deterministic test window.
464    pub liveness_probe_window: Duration,
465}
466
467impl Default for ConsumerOptions {
468    fn default() -> Self {
469        Self {
470            handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT,
471            call_timeout: DEFAULT_CALL_TIMEOUT,
472            reconnect_backoff: RetryBackoff::default(),
473            restored_debounce: DEFAULT_RESTORED_DEBOUNCE,
474            liveness_probe_window: DEFAULT_LIVENESS_PROBE_WINDOW,
475        }
476    }
477}
478
479/// A consumer-capability declaration was empty, contained whitespace or
480/// non-printable/non-ASCII bytes, or exceeded 64 bytes.
481#[derive(Debug, Clone, PartialEq, Eq)]
482pub struct ConsumerCapabilityError {
483    capability: String,
484}
485
486impl ConsumerCapabilityError {
487    /// The invalid declaration value.
488    pub fn capability(&self) -> &str {
489        &self.capability
490    }
491}
492
493impl fmt::Display for ConsumerCapabilityError {
494    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
495        write!(
496            f,
497            "invalid consumer capability {:?}: expected 1-64 printable ASCII bytes without whitespace",
498            self.capability
499        )
500    }
501}
502
503impl Error for ConsumerCapabilityError {}
504
505/// Options for [`SubcConsumer::close_route`].
506#[derive(Debug, Clone)]
507pub struct CloseRouteOptions {
508    /// Scope used to open the cached route. Defaults to `None`, which selects
509    /// only the unscoped entry; other scopes and epochs are never closed here.
510    /// [`SubcConsumer::close_handle`] rejects this option because the handle
511    /// already selects exactly one route.
512    pub scope: Option<ScopeSelector>,
513    /// Await in-flight unary requests on the route to settle naturally before tearing
514    /// it down. Defaults to false: close immediately, settling anything in flight as
515    /// at-most-once failures (outcome_unknown if already sent, not_sent otherwise).
516    pub drain: bool,
517    /// Upper bound on the drain wait (ignored when `drain` is false).
518    pub drain_timeout: Duration,
519    /// Override for the consumer identity used to locate the route being closed;
520    /// when absent, the supervised launch identity identifies the route, except
521    /// on connections created by [`SubcConsumer::connect_operator_app`].
522    /// On claim-bound connections, a legacy nonce identity conflicts with the
523    /// binding; `close_route` refuses it by doing nothing.
524    pub consumer_identity: Option<ConsumerIdentity>,
525    /// Reverse-request handlers plus extra capability strings added through
526    /// [`Self::with_consumer_capability`]. Together, they identify the route being closed.
527    pub reverse_requests: ReverseRequestRegistry,
528    /// The role versions the route being closed was opened with (see
529    /// [`CallOptions::role_versions`]); part of the route's identity.
530    pub role_versions: Option<BTreeMap<String, String>>,
531}
532
533impl Default for CloseRouteOptions {
534    fn default() -> Self {
535        Self {
536            scope: None,
537            drain: false,
538            drain_timeout: DEFAULT_CALL_TIMEOUT,
539            consumer_identity: None,
540            reverse_requests: ReverseRequestRegistry::new(),
541            role_versions: None,
542        }
543    }
544}
545
546impl CloseRouteOptions {
547    /// Add a provider-contract capability declaration to the route identity.
548    ///
549    /// Values are merged with the reverse-request families. For example,
550    /// `tool-result/v1` declares the tool-provider content result format; the
551    /// declaration is not verified and grants no privilege.
552    ///
553    /// Like reverse-request handlers, declarations are kept in the options'
554    /// shared reverse-request state, so options cloned before this call share
555    /// the declaration. Add declarations before cloning options for other
556    /// routes.
557    pub fn with_consumer_capability(
558        self,
559        capability: impl Into<String>,
560    ) -> Result<Self, ConsumerCapabilityError> {
561        self.reverse_requests
562            .declare_consumer_capability(capability.into())?;
563        Ok(self)
564    }
565
566    /// The extra capability strings added with `with_consumer_capability`, not
567    /// the reverse-request handler families. For example, `tool-result/v1` declares
568    /// tool-provider content-result support; declarations are unverified and
569    /// grant nothing.
570    pub fn consumer_capabilities(&self) -> Vec<String> {
571        self.reverse_requests.consumer_capabilities()
572    }
573}
574
575/// Per-call options for [`SubcConsumer::call`].
576#[derive(Debug, Clone, PartialEq, Eq)]
577pub struct CallOptions {
578    /// Scope for a managed call's cached route, including reconnect reopens.
579    /// Each owner/ref/epoch has a separate cache entry, apart from unscoped routes.
580    /// Admission, retries and terminal refusals follow [`SubcConsumer::open_route_scoped`].
581    /// A later call after a scope-related close tries a fresh route; the daemon
582    /// refuses it as `scope_ended` for an old epoch or `scope_not_live` if the
583    /// scope ref is gone. No tombstone is cached.
584    /// Defaults to `None`. Methods using an already-open handle reject this option;
585    /// select the scope when opening the route instead.
586    pub scope: Option<ScopeSelector>,
587    /// Deadline for the whole managed call, including route-open retry and the response wait.
588    pub timeout: Duration,
589    pub priority: Priority,
590    /// Admission behavior stamped into the request frame. Defaults to NORMAL.
591    pub admission_class: AdmissionClass,
592    pub route_retry: RetryBackoff,
593    /// Maximum real-time limit for retrying route.open attempts when the target is temporarily absent.
594    /// Bounds the whole route open, including the first attempt: a zero budget
595    /// means no open is attempted. For a single attempt, allow that attempt's time.
596    pub route_retry_deadline: Duration,
597    /// Explicit consumer identity for route.open; when absent, the supervised
598    /// launch identity is used, except on [`SubcConsumer::connect_operator_app`]
599    /// connections, which omit implicit identity.
600    /// A claim-bound connection rejects legacy nonce identity overrides as not
601    /// sent, rather than changing the connection's authority.
602    pub consumer_identity: Option<ConsumerIdentity>,
603    /// Reverse-request handlers plus extra capability strings added with
604    /// [`Self::with_consumer_capability`]. For example, `tool-result/v1` declares
605    /// tool-provider content-result support. These declarations are unverified
606    /// and grant nothing; both sets are merged and omitted when empty.
607    pub reverse_requests: ReverseRequestRegistry,
608    /// The versions of provider roles this consumer speaks on the route, role
609    /// name to version (`{"tool-provider": "v1"}`), sent on `route.open` and
610    /// forwarded by the daemon to the provider's bind. An unverified
611    /// declaration that grants nothing. Routes that differ only here are
612    /// separate routes, so a legacy route and a versioned one to the same
613    /// target are never shared; an empty map is the same as `None`.
614    ///
615    /// A daemon that does not advertise `route-role-versions/v1`
616    /// ([`subc_protocol::scope::CAP_ROUTE_ROLE_VERSIONS_V1`]) drops the field
617    /// without telling the provider, so check the capability before relying
618    /// on it. A malformed map (see
619    /// [`subc_protocol::session::validate_role_versions`]) is refused by the
620    /// daemon as `invalid_request` and the call fails as not sent.
621    pub role_versions: Option<BTreeMap<String, String>>,
622}
623
624impl Default for CallOptions {
625    fn default() -> Self {
626        Self {
627            scope: None,
628            timeout: DEFAULT_CALL_TIMEOUT,
629            priority: Priority::Interactive,
630            admission_class: AdmissionClass::Normal,
631            route_retry: RetryBackoff::default(),
632            route_retry_deadline: DEFAULT_ROUTE_RETRY_DEADLINE,
633            consumer_identity: None,
634            reverse_requests: ReverseRequestRegistry::new(),
635            role_versions: None,
636        }
637    }
638}
639
640impl CallOptions {
641    fn reject_scope(&self) -> Result<(), CallError> {
642        if self.scope.is_some() {
643            return Err(CallError::not_sent(
644                "CallOptions.scope is not supported here; select the scope with open_route_scoped or a managed call",
645            ));
646        }
647        Ok(())
648    }
649
650    /// Add a provider-contract capability declaration to the route.
651    ///
652    /// The list is merged with reverse-request handler families, sorted and
653    /// de-duplicated. For example, `tool-result/v1` declares the tool-provider
654    /// content result format. This remains an unverified declaration and grants
655    /// no privilege. Invalid values are rejected here, before route.open can be
656    /// sent.
657    ///
658    /// Like reverse-request handlers, declarations are kept in the options'
659    /// shared reverse-request state, so options cloned before this call share
660    /// the declaration. Add declarations before cloning options for other
661    /// routes.
662    pub fn with_consumer_capability(
663        self,
664        capability: impl Into<String>,
665    ) -> Result<Self, ConsumerCapabilityError> {
666        self.reverse_requests
667            .declare_consumer_capability(capability.into())?;
668        Ok(self)
669    }
670
671    /// The extra capability strings added with `with_consumer_capability`, not
672    /// the reverse-request handler families. For example, `tool-result/v1` declares
673    /// tool-provider content-result support; declarations are unverified and
674    /// grant nothing.
675    pub fn consumer_capabilities(&self) -> Vec<String> {
676        self.reverse_requests.consumer_capabilities()
677    }
678}
679
680/// Options for [`SubcConsumer::subscribe`].
681#[derive(Debug, Clone, PartialEq, Eq)]
682pub struct SubscribeOptions {
683    /// Scope for the cached route and its reopen attempts. Defaults to `None`.
684    /// Cache separation and daemon refusals follow [`CallOptions::scope`].
685    /// [`SubcConsumer::subscribe_route`] rejects this option because its handle
686    /// already fixes the scope. A scope-related close ends the subscription;
687    /// it is not automatically reopened under this or any other selector.
688    pub scope: Option<ScopeSelector>,
689    pub priority: Priority,
690    /// Admission behavior stamped into the subscription request. Defaults to NORMAL.
691    pub admission_class: AdmissionClass,
692    /// Maximum number of events buffered for the caller before the subscription is dropped.
693    /// The reader task never awaits a slow event consumer; if this bounded channel fills,
694    /// `closed()` resolves with [`CallError::SubscriptionBackpressure`].
695    pub event_buffer: usize,
696    pub route_retry: RetryBackoff,
697    /// Maximum real-time limit for retrying route.open attempts when the target is temporarily absent.
698    pub route_retry_deadline: Duration,
699    /// Deadline for opening the managed route and queuing the held-open request.
700    /// The subscription itself has no response timeout once the request is sent.
701    pub route_open_timeout: Duration,
702    /// Explicit consumer identity for route.open; when absent, the supervised
703    /// launch identity is used, except on [`SubcConsumer::connect_operator_app`]
704    /// connections, which omit implicit identity.
705    /// Claim-bound connections reject legacy nonce identity overrides as not sent.
706    pub consumer_identity: Option<ConsumerIdentity>,
707    /// Reverse-request handlers plus extra capability strings added with
708    /// [`Self::with_consumer_capability`]. For example, `tool-result/v1` declares
709    /// tool-provider content-result support. These declarations are unverified
710    /// and grant nothing; both sets are merged and omitted when empty.
711    pub reverse_requests: ReverseRequestRegistry,
712    /// The role versions declared on the subscription's route; see
713    /// [`CallOptions::role_versions`].
714    pub role_versions: Option<BTreeMap<String, String>>,
715}
716
717impl Default for SubscribeOptions {
718    fn default() -> Self {
719        Self {
720            scope: None,
721            priority: Priority::Interactive,
722            admission_class: AdmissionClass::Normal,
723            event_buffer: DEFAULT_SUBSCRIPTION_EVENT_BUFFER,
724            route_retry: RetryBackoff::default(),
725            route_retry_deadline: DEFAULT_ROUTE_RETRY_DEADLINE,
726            route_open_timeout: DEFAULT_CALL_TIMEOUT,
727            consumer_identity: None,
728            reverse_requests: ReverseRequestRegistry::new(),
729            role_versions: None,
730        }
731    }
732}
733
734impl SubscribeOptions {
735    /// Add a provider-contract capability declaration to the subscription route.
736    ///
737    /// This merges with reverse-request families. For example, `tool-result/v1`
738    /// declares the tool-provider content result format. The declaration is
739    /// unverified and grants no privilege; invalid values are refused before
740    /// route.open is sent.
741    pub fn with_consumer_capability(
742        self,
743        capability: impl Into<String>,
744    ) -> Result<Self, ConsumerCapabilityError> {
745        self.reverse_requests
746            .declare_consumer_capability(capability.into())?;
747        Ok(self)
748    }
749
750    /// The extra capability strings added with `with_consumer_capability`, not
751    /// the reverse-request handler families. For example, `tool-result/v1` declares
752    /// tool-provider content-result support; declarations are unverified and
753    /// grant nothing.
754    pub fn consumer_capabilities(&self) -> Vec<String> {
755        self.reverse_requests.consumer_capabilities()
756    }
757}
758
759/// Minimal connection lifecycle signal. It is useful for logging and route-cache invalidation,
760/// but callers must not use the consumer epoch as proof that a target provider is current.
761#[derive(Debug, Clone, PartialEq, Eq)]
762pub enum ConnectionState {
763    Dropped,
764    Restored { epoch: u64 },
765}
766
767/// Result of a route-scoped status or liveness poll.
768#[derive(Debug, Clone, PartialEq, Eq)]
769pub struct RoutePollResult {
770    pub handle: RouteHandle,
771    pub status: Option<String>,
772    pub live: Option<bool>,
773}
774
775/// Typed response from the daemon's channel-0 `catalog.list` operation.
776///
777/// Each module entry exposes the provider roles and tool definitions advertised by
778/// that module.
779#[derive(Debug, Clone, serde::Deserialize, PartialEq)]
780pub struct CatalogList {
781    pub generation: u64,
782    #[serde(default)]
783    pub modules: Vec<CatalogEntry>,
784    #[serde(default)]
785    pub subc_ops: Vec<String>,
786}
787
788/// Typed response from the daemon's channel-0 `supervisor.list` operation.
789///
790/// Unlike `catalog.list`, this includes configured modules that are stopped or
791/// disabled, along with their current supervisor state.
792#[derive(Debug, Clone, PartialEq)]
793pub struct SupervisorListResponse {
794    pub generation: u64,
795    pub modules: Vec<SupervisorEntry>,
796    pub daemon: Option<subc_control::DaemonResources>,
797    pub agent_commands: Option<Vec<subc_control::AgentCommandResources>>,
798}
799
800/// A provider-originated push delivered on one live route.
801#[derive(Debug, Clone, PartialEq, Eq)]
802pub struct PushEvent {
803    /// The connection-fenced route identity on which the push arrived.
804    pub handle: RouteHandle,
805    /// Opaque payload bytes sent by the provider.
806    pub body: Vec<u8>,
807}
808
809/// Disposition of one provider push at delivery time, so the two drop causes
810/// land on their own counters (issue #40): the remedies differ.
811enum DroppedPush {
812    Delivered,
813    NoReceiver,
814    ReceiverFull,
815}
816
817/// A parsed daemon-originated channel-0 control push.
818#[derive(Debug, Clone)]
819pub struct ControlPush {
820    /// The push discriminator, e.g. `route.closing` / `route.closed`.
821    pub op: String,
822    /// The full parsed body, `op` included, for op-specific fields.
823    pub body: serde_json::Value,
824}
825
826/// A route-close reason accepted from the daemon control-push wire.
827///
828/// The protocol may add reasons before this SDK is upgraded. Preserve that fact
829/// as [`Self::Unknown`] and classify it conservatively rather than refusing to
830/// deliver the enclosing control push.
831#[derive(Debug, Clone, PartialEq, Eq)]
832#[non_exhaustive]
833pub enum RouteCloseReason {
834    Reload,
835    Restart,
836    AuthorityChanged,
837    Disable,
838    Crash,
839    CapabilityDenied,
840    ScopeEnded,
841    ScopeCarrierRemoved,
842    ScopeDelegationChanged,
843    ScopeParentEnded,
844    Unknown(String),
845}
846
847/// Close reasons understood by this SDK, declared only after the daemon
848/// advertises `route-close-reasons/v1` so older daemons see unchanged requests.
849pub const ACCEPTED_CLOSE_REASONS: &[&str] = &[
850    "reload",
851    "restart",
852    "authority_changed",
853    "disable",
854    "crash",
855    "capability_denied",
856    "scope_ended",
857    "scope_carrier_removed",
858    "scope_delegation_changed",
859    "scope_parent_ended",
860];
861
862/// Why a route ended. Even a planned closure can leave a call's outcome unknown.
863#[derive(Debug, Clone, PartialEq, Eq)]
864#[non_exhaustive]
865pub enum RouteEndReason {
866    Daemon(RouteCloseReason),
867    ClosedByCaller,
868    ConnectionLost,
869    Unknown,
870}
871
872#[derive(Debug, Clone)]
873struct RouteEnd {
874    reason: RouteEndReason,
875    terminal: Option<bool>,
876}
877
878impl From<RouteEndReason> for RouteEnd {
879    fn from(reason: RouteEndReason) -> Self {
880        Self {
881            reason,
882            terminal: None,
883        }
884    }
885}
886
887/// Whether a closed route may be reopened automatically from its reason alone.
888#[derive(Debug, Clone, Copy, PartialEq, Eq)]
889pub enum RouteCloseDisposition {
890    MayReopen,
891    MustNotReopen,
892}
893
894impl RouteCloseReason {
895    /// Decode a wire reason without making a new daemon reason fatal to push delivery.
896    pub fn from_wire(reason: &str) -> Self {
897        match reason {
898            "reload" => Self::Reload,
899            "restart" => Self::Restart,
900            "authority_changed" => Self::AuthorityChanged,
901            "disable" => Self::Disable,
902            "crash" => Self::Crash,
903            "capability_denied" => Self::CapabilityDenied,
904            "scope_ended" => Self::ScopeEnded,
905            "scope_carrier_removed" => Self::ScopeCarrierRemoved,
906            "scope_delegation_changed" => Self::ScopeDelegationChanged,
907            "scope_parent_ended" => Self::ScopeParentEnded,
908            other => Self::Unknown(other.to_string()),
909        }
910    }
911
912    /// Unknown reasons take the strictest action: never reopen on their behalf.
913    pub fn disposition(&self) -> RouteCloseDisposition {
914        match self {
915            Self::Reload | Self::Restart | Self::AuthorityChanged => {
916                RouteCloseDisposition::MayReopen
917            }
918            Self::Disable
919            | Self::Crash
920            | Self::CapabilityDenied
921            | Self::ScopeEnded
922            | Self::ScopeCarrierRemoved
923            | Self::ScopeDelegationChanged
924            | Self::ScopeParentEnded
925            | Self::Unknown(_) => RouteCloseDisposition::MustNotReopen,
926        }
927    }
928}
929
930impl ControlPush {
931    /// Decode the close reason from a route lifecycle push, if this is one.
932    pub fn route_close_reason(&self) -> Option<RouteCloseReason> {
933        matches!(self.op.as_str(), "route.closing" | "route.closed")
934            .then(|| {
935                self.body
936                    .get("reason")?
937                    .as_str()
938                    .map(RouteCloseReason::from_wire)
939            })
940            .flatten()
941    }
942}
943
944/// Managed Rust consumer for subc route calls.
945pub struct SubcConsumer {
946    shared: Arc<Shared>,
947}
948
949/// The daemon's view of this connection at the time of the query.
950/// Recognition may change after revalidation or a reconnect.
951#[non_exhaustive]
952#[derive(Debug, Clone, PartialEq, Eq)]
953pub struct ConnectionFacts {
954    local: bool,
955    operator_app: Option<subc_protocol::peer::OperatorApp>,
956}
957
958impl ConnectionFacts {
959    /// Whether this connection arrived on the Unix socket or Windows named pipe.
960    pub fn local(&self) -> bool {
961        self.local
962    }
963
964    /// The operator app currently recognised for this connection. `route.bind`
965    /// sends it only to targets that advertise `operator-app/v1`.
966    pub fn operator_app(&self) -> Option<&subc_protocol::peer::OperatorApp> {
967        self.operator_app.as_ref()
968    }
969}
970
971/// Failure to ask the daemon to open an installed operator app.
972#[non_exhaustive]
973#[derive(Debug)]
974pub enum AppOpenError {
975    /// A daemon error frame. Codes are open strings so future refusals survive.
976    /// The current checks, in order, are `app_open_not_used`,
977    /// `app_open_disabled`, `app_unknown`, `app_not_installed`, and
978    /// `app_verification_failed` (see `subc_control::APP_OPEN_ERROR_CODES`).
979    /// An already-running app succeeds between the unknown and installed checks.
980    Refused { code: String, message: String },
981    /// A transport or protocol failure rather than a daemon refusal.
982    Call(CallError),
983}
984
985impl fmt::Display for AppOpenError {
986    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
987        match self {
988            Self::Refused { code, message } => write!(f, "{code}: {message}"),
989            Self::Call(err) => err.fmt(f),
990        }
991    }
992}
993
994impl Error for AppOpenError {
995    fn source(&self) -> Option<&(dyn Error + 'static)> {
996        match self {
997            Self::Call(err) => Some(err),
998            Self::Refused { .. } => None,
999        }
1000    }
1001}
1002
1003impl From<CallError> for AppOpenError {
1004    fn from(err: CallError) -> Self {
1005        Self::Call(err)
1006    }
1007}
1008
1009/// A managed unary reply with the module's raw-body declaration preserved.
1010#[non_exhaustive]
1011#[derive(Debug, Clone, PartialEq, Eq)]
1012pub struct CallReply {
1013    body: Vec<u8>,
1014    binary: bool,
1015}
1016
1017impl CallReply {
1018    /// The body bytes, unchanged from the terminal Response frame.
1019    /// A StreamEnd without a Response has an empty body.
1020    pub fn body(&self) -> &[u8] {
1021        &self.body
1022    }
1023
1024    /// Consume the reply and return its body bytes without copying them.
1025    pub fn into_body(self) -> Vec<u8> {
1026        self.body
1027    }
1028
1029    /// Whether the terminal Response carried `FLAG_BINARY` (raw bytes, not JSON).
1030    /// A StreamEnd without a Response returns `false`.
1031    pub fn is_binary(&self) -> bool {
1032        self.binary
1033    }
1034}
1035
1036/// The first terminal outcome of a subscription.
1037#[derive(Debug, Clone, PartialEq)]
1038#[non_exhaustive]
1039pub enum SubscriptionEnd {
1040    Response(Vec<u8>),
1041    StreamEnd,
1042    Error(ErrorBody),
1043    RouteClosed {
1044        reason: RouteEndReason,
1045    },
1046    ConnectionLost,
1047    Cancelled,
1048    /// The bounded event channel filled before the caller drained it.
1049    Backpressure,
1050}
1051
1052/// A live subscription to a provider event stream.
1053///
1054/// The event receiver yields each `StreamData` payload for the held-open request's
1055/// correlation id. Await [`Subscription::closed`] to learn whether the provider ended
1056/// the stream cleanly (`Response` or `StreamEnd`) or the stream was rejected by an Error frame,
1057/// route GOODBYE, connection drop, or local backpressure. Dropping the subscription
1058/// sends a best-effort Cancel frame, the same as calling [`Subscription::unsubscribe`].
1059pub struct Subscription {
1060    events: mpsc::Receiver<Vec<u8>>,
1061    closed: SubscriptionClosed,
1062    ended: watch::Receiver<Option<SubscriptionEnd>>,
1063    cancel: SubscriptionCancel,
1064}
1065
1066impl Subscription {
1067    /// Receive event payloads emitted as `StreamData` frames for this subscription.
1068    pub fn events(&mut self) -> &mut mpsc::Receiver<Vec<u8>> {
1069        &mut self.events
1070    }
1071
1072    /// Future that resolves when the subscription reaches a terminal state.
1073    ///
1074    /// It resolves with `Ok(())` on `Response`, `StreamEnd` or local unsubscribe, and returns a
1075    /// [`CallError`] for module Error frames, route teardown, connection loss, or
1076    /// event-channel backpressure. Await it after the event receiver returns `None`
1077    /// to distinguish a clean end from an error.
1078    pub fn closed(&mut self) -> &mut SubscriptionClosed {
1079        &mut self.closed
1080    }
1081
1082    /// Wait for the terminal outcome, retaining a Response body or module Error.
1083    ///
1084    /// This is independent of the one-shot [`Self::closed`] future: either can be
1085    /// awaited first, and `ended` can be awaited again after completion. Neither
1086    /// method reads frames; both observe the same pending request's settlement.
1087    pub async fn ended(&mut self) -> SubscriptionEnd {
1088        loop {
1089            if let Some(end) = self.ended.borrow().clone() {
1090                return end;
1091            }
1092            if self.ended.changed().await.is_err() {
1093                return SubscriptionEnd::ConnectionLost;
1094            }
1095        }
1096    }
1097
1098    /// Cancel the held-open request.
1099    ///
1100    /// This sends a best-effort header-only Cancel frame for the subscription's
1101    /// `(channel, corr)` and settles [`Subscription::closed`] promptly with `Ok(())`.
1102    /// The provider may still send a terminal frame later; it is ignored because the
1103    /// local subscription is already closed.
1104    pub fn unsubscribe(&self) -> Result<(), CallError> {
1105        self.cancel.unsubscribe()
1106    }
1107}
1108
1109impl Drop for Subscription {
1110    fn drop(&mut self) {
1111        let _ = self.cancel.unsubscribe();
1112    }
1113}
1114
1115/// A held `supervisor.spawn_subscribe` request: the daemon's spawn events, in cursor
1116/// order, until the stream ends. Dropping it cancels the request.
1117pub struct SpawnSubscription {
1118    inner: Subscription,
1119    finished: bool,
1120}
1121
1122impl SpawnSubscription {
1123    /// The next event. `Ok(None)` is a clean end (the daemon ended the stream, or it was
1124    /// unsubscribed); every later call returns it too.
1125    ///
1126    /// Every event the daemon queued before a terminal error is yielded first, so the
1127    /// last event received is the cursor to resume from. A refused cursor or a dropped
1128    /// subscriber comes back as the matching [`SpawnStreamError`] variant; anything else
1129    /// that ends the stream (connection loss, local backpressure, an event that does not
1130    /// decode) is [`SpawnStreamError::Call`] or [`SpawnStreamError::Decode`].
1131    pub async fn next(&mut self) -> Result<Option<SpawnEvent>, SpawnStreamError> {
1132        if self.finished {
1133            return Ok(None);
1134        }
1135        if let Some(body) = self.inner.events().recv().await {
1136            return serde_json::from_slice::<SpawnEvent>(&body)
1137                .map(Some)
1138                .map_err(|err| {
1139                    self.finished = true;
1140                    let _ = self.inner.unsubscribe();
1141                    SpawnStreamError::Decode(err.to_string())
1142                });
1143        }
1144        // Marked finished only once the terminal has been read: a caller that drops this
1145        // future mid-await (a `select!` arm) still gets the terminal on its next call.
1146        let terminal = self.inner.closed().await;
1147        self.finished = true;
1148        match terminal {
1149            Ok(()) => Ok(None),
1150            Err(err) => Err(SpawnStreamError::from_call_error(err)),
1151        }
1152    }
1153
1154    /// Cancel the held request; the daemon releases the subscriber.
1155    pub fn unsubscribe(&self) -> Result<(), CallError> {
1156        self.inner.unsubscribe()
1157    }
1158}
1159
1160/// Why a spawn stream ended with an error, by the daemon's code where it sent one.
1161#[derive(Debug)]
1162pub enum SpawnStreamError {
1163    /// `spawn_cursor_incarnation_mismatch`: the cursor names another daemon incarnation,
1164    /// so every event since it is unknowable from this daemon.
1165    CursorIncarnationMismatch {
1166        current_daemon_incarnation: String,
1167        body: Box<ErrorBody>,
1168    },
1169    /// `spawn_cursor_too_old`: events after the cursor have left the daemon's ring.
1170    CursorTooOld {
1171        oldest_retained_cursor: SpawnCursor,
1172        body: Box<ErrorBody>,
1173    },
1174    /// `spawn_subscriber_lagged`: the daemon dropped this subscriber for falling behind,
1175    /// after delivering every event it had queued for it.
1176    SubscriberLagged {
1177        first_undelivered_cursor: SpawnCursor,
1178        body: Box<ErrorBody>,
1179    },
1180    /// Any other end: another daemon error (one of the codes above with a detail that
1181    /// does not parse included, so its code is still readable), connection loss, or
1182    /// local backpressure.
1183    Call(CallError),
1184    /// An event body that is not a `SpawnEvent`.
1185    Decode(String),
1186}
1187
1188impl SpawnStreamError {
1189    fn from_call_error(err: CallError) -> Self {
1190        let CallError::Module(body) = err else {
1191            return Self::Call(err);
1192        };
1193        let detail = |key: &str| body.detail.as_ref().and_then(|detail| detail.get(key));
1194        let cursor = |key: &str| {
1195            detail(key).and_then(|value| serde_json::from_value::<SpawnCursor>(value.clone()).ok())
1196        };
1197        match body.code.as_str() {
1198            SPAWN_CURSOR_INCARNATION_MISMATCH => {
1199                match detail("current_daemon_incarnation").and_then(|value| value.as_str()) {
1200                    Some(current) => Self::CursorIncarnationMismatch {
1201                        current_daemon_incarnation: current.to_string(),
1202                        body: Box::new(body),
1203                    },
1204                    None => Self::Call(CallError::Module(body)),
1205                }
1206            }
1207            SPAWN_CURSOR_TOO_OLD => match cursor("oldest_retained_cursor") {
1208                Some(oldest_retained_cursor) => Self::CursorTooOld {
1209                    oldest_retained_cursor,
1210                    body: Box::new(body),
1211                },
1212                None => Self::Call(CallError::Module(body)),
1213            },
1214            SPAWN_SUBSCRIBER_LAGGED => match cursor("first_undelivered_cursor") {
1215                Some(first_undelivered_cursor) => Self::SubscriberLagged {
1216                    first_undelivered_cursor,
1217                    body: Box::new(body),
1218                },
1219                None => Self::Call(CallError::Module(body)),
1220            },
1221            _ => Self::Call(CallError::Module(body)),
1222        }
1223    }
1224
1225    /// The daemon's error code, when the stream ended with one.
1226    pub fn code(&self) -> Option<&str> {
1227        match self {
1228            Self::CursorIncarnationMismatch { .. } => Some(SPAWN_CURSOR_INCARNATION_MISMATCH),
1229            Self::CursorTooOld { .. } => Some(SPAWN_CURSOR_TOO_OLD),
1230            Self::SubscriberLagged { .. } => Some(SPAWN_SUBSCRIBER_LAGGED),
1231            Self::Call(err) => err.code(),
1232            Self::Decode(_) => None,
1233        }
1234    }
1235}
1236
1237impl fmt::Display for SpawnStreamError {
1238    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1239        match self {
1240            Self::CursorIncarnationMismatch {
1241                current_daemon_incarnation,
1242                ..
1243            } => write!(
1244                f,
1245                "{SPAWN_CURSOR_INCARNATION_MISMATCH}: the daemon is incarnation \
1246                 {current_daemon_incarnation}"
1247            ),
1248            Self::CursorTooOld {
1249                oldest_retained_cursor,
1250                ..
1251            } => write!(
1252                f,
1253                "{SPAWN_CURSOR_TOO_OLD}: the oldest retained event is seq {}",
1254                oldest_retained_cursor.seq
1255            ),
1256            Self::SubscriberLagged {
1257                first_undelivered_cursor,
1258                ..
1259            } => write!(
1260                f,
1261                "{SPAWN_SUBSCRIBER_LAGGED}: the first undelivered event is seq {}",
1262                first_undelivered_cursor.seq
1263            ),
1264            Self::Call(err) => write!(f, "spawn stream ended: {err}"),
1265            Self::Decode(message) => write!(f, "spawn event did not decode: {message}"),
1266        }
1267    }
1268}
1269
1270impl Error for SpawnStreamError {}
1271
1272/// Future returned by [`Subscription::closed`].
1273pub struct SubscriptionClosed {
1274    rx: oneshot::Receiver<Result<(), CallError>>,
1275}
1276
1277impl Unpin for SubscriptionClosed {}
1278
1279impl Future for SubscriptionClosed {
1280    type Output = Result<(), CallError>;
1281
1282    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
1283        let this = self.get_mut();
1284        match Pin::new(&mut this.rx).poll(cx) {
1285            Poll::Ready(Ok(result)) => Poll::Ready(result),
1286            Poll::Ready(Err(_)) => Poll::Ready(Err(CallError::outcome_unknown(
1287                "subscription closed result channel dropped",
1288                OutcomeUnknownCause::CompletionFailed,
1289            ))),
1290            Poll::Pending => Poll::Pending,
1291        }
1292    }
1293}
1294
1295struct SubscriptionCancel {
1296    shared: Arc<Shared>,
1297    position: Arc<SubscriptionPosition>,
1298    priority: Priority,
1299    cancelled: AtomicBool,
1300}
1301
1302impl SubscriptionCancel {
1303    fn new(shared: Arc<Shared>, position: Arc<SubscriptionPosition>, priority: Priority) -> Self {
1304        Self {
1305            shared,
1306            position,
1307            priority,
1308            cancelled: AtomicBool::new(false),
1309        }
1310    }
1311
1312    fn unsubscribe(&self) -> Result<(), CallError> {
1313        let key = *self
1314            .position
1315            .key
1316            .lock()
1317            .unwrap_or_else(|err| err.into_inner());
1318        let handle = RouteHandle::new(key.channel, key.epoch, key.generation);
1319        self.shared.validate_current_handle(handle)?;
1320        if self.cancelled.swap(true, Ordering::AcqRel) {
1321            return Ok(());
1322        }
1323        self.shared
1324            .unsubscribe_subscription(&self.position, self.priority)
1325    }
1326}
1327
1328impl SubcConsumer {
1329    /// Connect through an explicit connection-file path. The initial connection
1330    /// generation uses epoch 1; each reconnect advances it.
1331    /// In a supervised process, the module's primary registration connection
1332    /// mints a fresh self claim for
1333    /// every connection, including reconnects. Mint/presentation failure is an
1334    /// error, never a direct connection: dropping the binding would change the
1335    /// caller's authority. Unsupervised processes retain the legacy behavior.
1336    pub async fn connect(
1337        connection_file: &Path,
1338        opts: ConsumerOptions,
1339    ) -> Result<Self, ConsumerError> {
1340        Self::connect_with_transport(connection_file, opts, ConsumerTransport::Tcp, true).await
1341    }
1342
1343    /// Connect only to the connection file's same-user Unix socket or Windows pipe.
1344    ///
1345    /// Each connection attempt, including reconnects, reads the current local
1346    /// endpoint and key from the same owner-checked file. A missing
1347    /// `local_endpoint` returns [`ConsumerError::NoEndpoint`]; a local connect
1348    /// failure retains its endpoint and I/O error. Neither case falls back to TCP.
1349    pub async fn connect_local(
1350        connection_file: &Path,
1351        opts: ConsumerOptions,
1352    ) -> Result<Self, ConsumerError> {
1353        Self::connect_with_transport(connection_file, opts, ConsumerTransport::Local, true).await
1354    }
1355
1356    async fn connect_with_transport(
1357        connection_file: &Path,
1358        opts: ConsumerOptions,
1359        transport: ConsumerTransport,
1360        identity_from_environment: bool,
1361    ) -> Result<Self, ConsumerError> {
1362        let opened =
1363            open_connection(connection_file, opts.handshake_timeout, transport, None).await?;
1364        let mut shared = Shared::with_transport(connection_file.to_path_buf(), opts, transport);
1365        shared.identity_from_environment = identity_from_environment;
1366        let shared = Arc::new(shared);
1367        shared.install_initial(opened)?;
1368        Ok(Self { shared })
1369    }
1370
1371    /// Discover the daemon's connection file, authenticate, and start the I/O loop.
1372    pub async fn connect_default(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1373        let discovered = connection_file::discover(None)
1374            .map_err(|source| ConsumerError::Discovery { source })?;
1375        let opened =
1376            open_connection_with_info(&discovered.path, &discovered.info, opts.handshake_timeout)
1377                .await?;
1378        let shared = Arc::new(Shared::new(discovered.path, opts));
1379        shared.install_initial(opened)?;
1380        Ok(Self { shared })
1381    }
1382
1383    /// Discover the daemon's connection file and connect only to its local endpoint.
1384    ///
1385    /// Uses [`Self::connect_local`], including its per-attempt file reads and
1386    /// refusal to fall back to TCP.
1387    pub async fn connect_default_local(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1388        let discovered = connection_file::discover(None)
1389            .map_err(|source| ConsumerError::Discovery { source })?;
1390        Self::connect_local(&discovered.path, opts).await
1391    }
1392
1393    /// Connect the desktop operator app to the installed daemon without reading
1394    /// environment variables for discovery or consumer identity.
1395    ///
1396    /// Tries [`crate::operator_app_candidates`] in order on every attempt,
1397    /// selecting the first existing owner-checked file. Uses the
1398    /// same per-attempt file reads and local-only transport as
1399    /// [`Self::connect_local`], never falling back to TCP. Requests omit implicit
1400    /// consumer identity, including after reconnect; explicit identities in
1401    /// [`CallOptions`] and [`CloseRouteOptions`] are still honoured.
1402    pub async fn connect_operator_app(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1403        Self::connect_operator_app_resolving(
1404            opts,
1405            ConsumerTransport::Local,
1406            crate::operator_app_candidates,
1407        )
1408        .await
1409    }
1410
1411    /// Open the desktop operator app's plain connection over TCP.
1412    ///
1413    /// Selects and owner-checks the installed daemon's connection file with the
1414    /// same [`crate::operator_app_candidates`] policy as
1415    /// [`Self::connect_operator_app`], then connects to the file's first TCP
1416    /// endpoint instead of its Unix socket or Windows named pipe.
1417    ///
1418    /// The daemon recognises a connection as the operator app only when it
1419    /// arrives over its Unix socket or named pipe, so this connection never
1420    /// carries the `operator_app` stamp and can't skip the daemon's
1421    /// confirmation. Its privileged requests follow the daemon's configured
1422    /// policy like any other client's. The caller decides which actions to send
1423    /// here, for example those made through assistive technology. This API
1424    /// doesn't classify input.
1425    ///
1426    /// When the daemon supports `connection.describe`,
1427    /// [`Self::describe_connection`] reports this connection with
1428    /// `local() == false`. There, `local` means the Unix socket or named pipe,
1429    /// not loopback.
1430    ///
1431    /// Like [`Self::connect_operator_app`], it reads no environment variable for
1432    /// discovery or consumer identity, including after reconnect, and never
1433    /// falls back to the local endpoint.
1434    pub async fn connect_operator_app_plain(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1435        Self::connect_operator_app_resolving(
1436            opts,
1437            ConsumerTransport::Tcp,
1438            crate::operator_app_candidates,
1439        )
1440        .await
1441    }
1442
1443    async fn connect_operator_app_resolving(
1444        opts: ConsumerOptions,
1445        transport: ConsumerTransport,
1446        resolve: impl FnOnce() -> Result<Vec<PathBuf>, crate::OperatorAppPathError>,
1447    ) -> Result<Self, ConsumerError> {
1448        let candidates = resolve().map_err(|source| ConsumerError::ConnectionFile {
1449            path: PathBuf::new(),
1450            source: ConnectionFileError::Io {
1451                op: "resolve installed daemon connection-file path",
1452                path: PathBuf::new(),
1453                source: io::Error::other(source),
1454            },
1455        })?;
1456        let path = candidates[0].clone();
1457        let opened =
1458            open_connection(&path, opts.handshake_timeout, transport, Some(&candidates)).await?;
1459        let mut shared = Shared::with_transport(path, opts, transport);
1460        shared.operator_app_candidates = Some(candidates);
1461        shared.identity_from_environment = false;
1462        let shared = Arc::new(shared);
1463        shared.install_initial(opened)?;
1464        Ok(Self { shared })
1465    }
1466
1467    /// Open or reuse an unscoped managed route and return a handle tied to its
1468    /// current connection (stale after a reconnect).
1469    /// A scope in `opts` is an argument error; use [`Self::open_route_scoped`].
1470    pub async fn open_route(
1471        &self,
1472        target: RouteTarget,
1473        identity: BindIdentity,
1474        opts: CallOptions,
1475    ) -> Result<RouteHandle, CallError> {
1476        opts.reject_scope()?;
1477        let deadline = Instant::now() + opts.timeout;
1478        let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
1479        let consumer_capabilities = route_open_consumer_capabilities(&opts);
1480        let role_versions = route_open_role_versions(opts.role_versions.as_ref());
1481        let key = RouteKey::new(
1482            &target,
1483            &identity,
1484            consumer_identity.as_ref(),
1485            consumer_capabilities.as_deref(),
1486        )
1487        .with_role_versions(role_versions.as_ref());
1488        let params = RouteOpenParams {
1489            target: &target,
1490            identity: &identity,
1491            consumer_identity: &consumer_identity,
1492            consumer_capabilities: &consumer_capabilities,
1493            role_versions: &role_versions,
1494            reverse_requests: &opts.reverse_requests,
1495            scope: None,
1496        };
1497        self.shared
1498            .ensure_route(&key, &params, &opts, deadline)
1499            .await
1500            .map(|route| route.handle)
1501    }
1502
1503    /// Open or reuse a managed route admitted under `scope`, and return a handle
1504    /// tied to its current connection (stale after a reconnect).
1505    ///
1506    /// This is how a carrier opens its onward route for a session. The daemon
1507    /// admits the open only when the opener (the consumer identity in `opts`,
1508    /// or the supervised module's own identity from the environment) is the
1509    /// scope's owner or one of its listed carriers, and it stamps the
1510    /// provider's bind with the scope. `scope.scope_epoch` must be set: the
1511    /// daemon refuses an open without it (`scope_epoch_required`).
1512    ///
1513    /// The route is cached under the whole selector (owner, ref and epoch) as
1514    /// well as the target and identities, so a route opened under one scope or
1515    /// epoch is never returned to a caller asking for another, and a scoped
1516    /// route is never returned by [`Self::open_route`] (nor an unscoped one
1517    /// here). Once the route closes, the next call with the same selector opens
1518    /// a fresh route under that selector. Close it early with
1519    /// [`Self::close_handle`].
1520    ///
1521    /// Refusals: `scope_not_synced` (the owner has not synced since the daemon
1522    /// started) and `scope_changed` (the scope changed while the bind was in
1523    /// flight) are retried within the call's deadline, like a module reload.
1524    /// `scope_ended`, `scope_not_live`, `scope_epoch_required` and
1525    /// `scope_not_carrier` end the call at once as [`CallError::NotSent`], with
1526    /// the daemon's code in [`CallError::route_open_refusal`].
1527    ///
1528    /// When the daemon later closes the route because its scope ended or the
1529    /// opener's authority under it was revoked, [`Self::control_pushes`]
1530    /// delivers `route.closed` with a `scope_*` reason. Its
1531    /// [`RouteCloseReason::disposition`] is
1532    /// [`RouteCloseDisposition::MustNotReopen`]: the session the route served is
1533    /// over, so callers should stop work for that session. The SDK does not
1534    /// cache a tombstone: a later explicit open or managed call with the same
1535    /// selector attempts a fresh open. The daemon refuses it as `scope_ended`
1536    /// if the ref is live at another epoch, or `scope_not_live` if the ref is gone.
1537    /// A selector in `opts.scope` must equal `scope`, or the call fails locally
1538    /// as an argument error before opening a route.
1539    pub async fn open_route_scoped(
1540        &self,
1541        target: RouteTarget,
1542        identity: BindIdentity,
1543        scope: ScopeSelector,
1544        opts: CallOptions,
1545    ) -> Result<RouteHandle, CallError> {
1546        if opts
1547            .scope
1548            .as_ref()
1549            .is_some_and(|selected| selected != &scope)
1550        {
1551            return Err(CallError::not_sent(
1552                "CallOptions.scope differs from open_route_scoped's explicit scope",
1553            ));
1554        }
1555        let deadline = Instant::now() + opts.timeout;
1556        let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
1557        let consumer_capabilities = route_open_consumer_capabilities(&opts);
1558        let role_versions = route_open_role_versions(opts.role_versions.as_ref());
1559        let key = RouteKey::new(
1560            &target,
1561            &identity,
1562            consumer_identity.as_ref(),
1563            consumer_capabilities.as_deref(),
1564        )
1565        .with_role_versions(role_versions.as_ref())
1566        .with_scope(Some(&scope));
1567        let params = RouteOpenParams {
1568            target: &target,
1569            identity: &identity,
1570            consumer_identity: &consumer_identity,
1571            consumer_capabilities: &consumer_capabilities,
1572            role_versions: &role_versions,
1573            reverse_requests: &opts.reverse_requests,
1574            scope: Some(&scope),
1575        };
1576        self.shared
1577            .ensure_route(&key, &params, &opts, deadline)
1578            .await
1579            .map(|route| route.handle)
1580    }
1581
1582    /// Open one admitted route without entering the managed route cache.
1583    ///
1584    /// Admitted routes are never cached or reopened after a connection drop. If
1585    /// this call fails or the route later closes, the caller must perform admission
1586    /// again and call this method with fresh facts.
1587    ///
1588    /// The route declares no reverse-request capabilities, so the provider cannot
1589    /// send it requests. Use [`Self::open_route_with_admission_facts_and_options`]
1590    /// when the provider asks the consumer questions on the route (elicitation).
1591    pub async fn open_route_with_admission_facts(
1592        &self,
1593        target: RouteTarget,
1594        identity: BindIdentity,
1595        facts: serde_json::Value,
1596    ) -> Result<RouteHandle, CallError> {
1597        let deadline = Instant::now() + self.shared.opts.call_timeout;
1598        self.open_admitted_route(
1599            target,
1600            identity,
1601            facts,
1602            &CallOptions::default(),
1603            None,
1604            deadline,
1605        )
1606        .await
1607    }
1608
1609    /// Open one admitted route, with the reverse-request handlers, capability
1610    /// declarations and timeout in `opts`.
1611    ///
1612    /// The route declares the method families of handlers registered on
1613    /// `opts.reverse_requests`, together with any provider-contract declarations
1614    /// in the extra declarations reported by `opts.consumer_capabilities()`. For example, `tool-result/v1` declares the
1615    /// tool-provider content result format. These are unverified declarations,
1616    /// not privilege grants. Requests the provider sends back (elicitation,
1617    /// sampling) reach the registered handlers, exactly as on a managed route.
1618    /// Handlers must be registered before this call: the registry is sealed
1619    /// when the route opens, because the declared method families are what the
1620    /// provider was told.
1621    ///
1622    /// Like [`Self::open_route_with_admission_facts`], the route is never cached
1623    /// or reopened; after a failure or a close the caller performs admission again.
1624    /// A non-`None` `opts.scope` is rejected as an argument error.
1625    pub async fn open_route_with_admission_facts_and_options(
1626        &self,
1627        target: RouteTarget,
1628        identity: BindIdentity,
1629        facts: serde_json::Value,
1630        opts: CallOptions,
1631    ) -> Result<RouteHandle, CallError> {
1632        opts.reject_scope()?;
1633        let deadline = Instant::now() + opts.timeout;
1634        let reverse_requests = opts.reverse_requests.clone();
1635        self.open_admitted_route(
1636            target,
1637            identity,
1638            facts,
1639            &opts,
1640            Some(reverse_requests),
1641            deadline,
1642        )
1643        .await
1644    }
1645
1646    /// One admitted route.open. With `reverse_requests`, the route is opened the
1647    /// way the managed path opens one: the capabilities are declared, the socket
1648    /// reader installs the handle before the open resolves (so a request the
1649    /// provider sends right after binding is not lost), and the handle carries
1650    /// the registry. Without it, the route has no reverse-request handling.
1651    async fn open_admitted_route(
1652        &self,
1653        target: RouteTarget,
1654        identity: BindIdentity,
1655        facts: serde_json::Value,
1656        opts: &CallOptions,
1657        reverse_requests: Option<ReverseRequestRegistry>,
1658        deadline: Instant,
1659    ) -> Result<RouteHandle, CallError> {
1660        let consumer_capabilities = route_open_consumer_capabilities(opts);
1661        let target_label = route_target_label(&target);
1662        let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
1663            busy_refusals: Some(true),
1664            target,
1665            identity,
1666            consumer_identity: self.shared.route_open_consumer_identity(opts)?,
1667            consumer_capabilities,
1668            role_versions: route_open_role_versions(opts.role_versions.as_ref()),
1669            admission_facts: Some(facts),
1670            scope: None,
1671        })
1672        .map_err(|err| CallError::not_sent(format!("failed to encode route.open: {err}")))?;
1673
1674        let terminal = self
1675            .shared
1676            .paced_route_open(body, deadline, reverse_requests.clone())
1677            .await?;
1678        let (generation, body) = match terminal {
1679            TerminalFrame::Response {
1680                generation, body, ..
1681            } => (generation, body),
1682            // The daemon refused the open. Keep its code and detail, as the
1683            // plain route.open does, so a caller can tell "retry shortly"
1684            // (module_warming) from "this configuration will never work"
1685            // (admission_facts_not_permitted).
1686            TerminalFrame::Error { body, .. } => {
1687                return Err(CallError::route_open_refused(target_label, body));
1688            }
1689            _ => {
1690                return Err(CallError::not_sent_with_cause(
1691                    "route.open returned a non-response frame",
1692                    NotSentCause::RouteOpenAbandoned,
1693                ));
1694            }
1695        };
1696        let ClientControlResponse::RouteOpen {
1697            route_channel,
1698            route_epoch,
1699            request_window,
1700            watch_window,
1701            ..
1702        } = decode_route_open_response(&body)
1703            .map_err(|err| {
1704                CallError::not_sent_with_cause(
1705                    format!("failed to decode route.open response: {err}"),
1706                    NotSentCause::RouteOpenAbandoned,
1707                )
1708            })?
1709            .0
1710        else {
1711            return Err(CallError::not_sent_with_cause(
1712                "route.open returned an unexpected control response",
1713                NotSentCause::RouteOpenAbandoned,
1714            ));
1715        };
1716        // Adopt the handle the socket reader installed for this response, which
1717        // carries the registry passed to control_call; build one only if the
1718        // reader did not (the connection moved on before the response landed).
1719        let handle = self
1720            .shared
1721            .ingress_handle(generation, route_channel, route_epoch)
1722            .unwrap_or_else(|| match reverse_requests {
1723                Some(reverse_requests) => RouteHandle::new_consumer(
1724                    route_channel,
1725                    route_epoch,
1726                    generation,
1727                    reverse_requests,
1728                ),
1729                None => RouteHandle::new(route_channel, route_epoch, generation),
1730            });
1731        let route = RouteState::windows(handle, request_window, watch_window);
1732        self.shared.install_one_shot_route(route.clone())?;
1733        Ok(route.handle)
1734    }
1735
1736    /// Describe this connection without prompting or granting any privilege.
1737    /// An older daemon's `unknown_control_op` refusal returns `None`: that daemon
1738    /// doesn't support this query, which says nothing about recognition.
1739    pub async fn describe_connection(&self) -> Result<Option<ConnectionFacts>, CallError> {
1740        let body =
1741            serde_json::to_vec(&subc_control::ConnectionDescribeRequest::new()).map_err(|err| {
1742                CallError::not_sent(format!("failed to encode connection.describe: {err}"))
1743            })?;
1744        let deadline = Instant::now() + self.shared.opts.call_timeout;
1745        match self
1746            .shared
1747            .control_call(body, deadline, false, None)
1748            .await?
1749        {
1750            TerminalFrame::Response { body, .. } => {
1751                let reply: subc_control::ConnectionDescribeReply = serde_json::from_slice(&body)
1752                    .map_err(|err| {
1753                        CallError::invalid_response(format!(
1754                            "failed to decode connection.describe: {err}"
1755                        ))
1756                    })?;
1757                Ok(Some(ConnectionFacts {
1758                    local: reply.local,
1759                    operator_app: reply.operator_app,
1760                }))
1761            }
1762            // The client-control dispatcher uses this exact code for unknown ops.
1763            TerminalFrame::Error { body, .. } if body.code == "unknown_control_op" => Ok(None),
1764            TerminalFrame::Error { body, .. } => Err(CallError::Module(body)),
1765            TerminalFrame::StreamEnd => Err(CallError::invalid_response(
1766                "connection.describe returned StreamEnd",
1767            )),
1768        }
1769    }
1770
1771    /// Ask the daemon to open a known installed app. Starting it grants nothing.
1772    /// Future success statuses and refusal codes are preserved for the caller.
1773    pub async fn app_open(&self, app: &str) -> Result<subc_control::AppOpenReply, AppOpenError> {
1774        let body = serde_json::to_vec(&subc_control::AppOpenRequest::new(app))
1775            .map_err(|err| CallError::not_sent(format!("failed to encode app.open: {err}")))?;
1776        let deadline = Instant::now() + self.shared.opts.call_timeout;
1777        match self
1778            .shared
1779            .control_call(body, deadline, false, None)
1780            .await?
1781        {
1782            TerminalFrame::Response { body, .. } => serde_json::from_slice(&body).map_err(|err| {
1783                CallError::invalid_response(format!("failed to decode app.open: {err}")).into()
1784            }),
1785            TerminalFrame::Error { body, .. } => Err(AppOpenError::Refused {
1786                code: body.code,
1787                message: body.message,
1788            }),
1789            TerminalFrame::StreamEnd => {
1790                Err(CallError::invalid_response("app.open returned StreamEnd").into())
1791            }
1792        }
1793    }
1794
1795    /// Fetch the daemon's module catalog over channel 0.
1796    /// Transport retries use the consumer's reconnect backoff and call deadline.
1797    pub async fn catalog_list(&self) -> Result<CatalogList, CallError> {
1798        let deadline = Instant::now() + self.shared.opts.call_timeout;
1799        let body = serde_json::to_vec(&serde_json::json!({
1800            "op": subc_control::ops::CATALOG_LIST,
1801        }))
1802        .map_err(|err| CallError::not_sent(format!("failed to encode catalog.list: {err}")))?;
1803
1804        let mut attempt = 0usize;
1805        loop {
1806            attempt = attempt.saturating_add(1);
1807            match self
1808                .shared
1809                .control_call(body.clone(), deadline, false, None)
1810                .await
1811            {
1812                Ok(TerminalFrame::Response { body, .. }) => {
1813                    let response =
1814                        serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1815                            CallError::invalid_response(format!(
1816                                "failed to decode catalog.list response: {err}"
1817                            ))
1818                        })?;
1819                    let ClientControlResponse::CatalogList {
1820                        generation,
1821                        modules,
1822                        subc_ops,
1823                    } = response
1824                    else {
1825                        return Err(CallError::invalid_response(
1826                            "catalog.list returned an unexpected control response",
1827                        ));
1828                    };
1829                    return Ok(CatalogList {
1830                        generation,
1831                        modules,
1832                        subc_ops,
1833                    });
1834                }
1835                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1836                Ok(TerminalFrame::StreamEnd) => {
1837                    return Err(CallError::invalid_response(
1838                        "catalog.list returned StreamEnd",
1839                    ));
1840                }
1841                Err(err)
1842                    if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1843                {
1844                    // Connection-file and discovery failures can complete without
1845                    // yielding. Pace the outer retry as well as reconnect itself,
1846                    // so repeated immediate failures cannot monopolize the executor.
1847                    let delay = self.shared.jittered(
1848                        self.shared
1849                            .opts
1850                            .reconnect_backoff
1851                            .delay_after_attempt(attempt),
1852                    );
1853                    self.shared.sleep_until_retry(deadline, delay).await?;
1854                    continue;
1855                }
1856                Err(err) => return Err(err),
1857            }
1858        }
1859    }
1860
1861    /// Fetch the supervisor's configured module list over channel 0.
1862    /// Transport retries use the consumer's reconnect backoff and call deadline.
1863    pub async fn supervisor_list(&self) -> Result<SupervisorListResponse, CallError> {
1864        let deadline = Instant::now() + self.shared.opts.call_timeout;
1865        let body = serde_json::to_vec(&ClientControlRequest::SupervisorList {}).map_err(|err| {
1866            CallError::not_sent(format!("failed to encode supervisor.list: {err}"))
1867        })?;
1868
1869        let mut attempt = 0usize;
1870        loop {
1871            attempt = attempt.saturating_add(1);
1872            match self
1873                .shared
1874                .control_call(body.clone(), deadline, false, None)
1875                .await
1876            {
1877                Ok(TerminalFrame::Response { body, .. }) => {
1878                    let response =
1879                        serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1880                            CallError::invalid_response(format!(
1881                                "failed to decode supervisor.list response: {err}"
1882                            ))
1883                        })?;
1884                    let ClientControlResponse::SupervisorList {
1885                        generation,
1886                        modules,
1887                        daemon,
1888                        agent_commands,
1889                    } = response
1890                    else {
1891                        return Err(CallError::invalid_response(
1892                            "supervisor.list returned an unexpected control response",
1893                        ));
1894                    };
1895                    return Ok(SupervisorListResponse {
1896                        generation,
1897                        modules,
1898                        daemon,
1899                        agent_commands,
1900                    });
1901                }
1902                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1903                Ok(TerminalFrame::StreamEnd) => {
1904                    return Err(CallError::invalid_response(
1905                        "supervisor.list returned StreamEnd",
1906                    ));
1907                }
1908                Err(err)
1909                    if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1910                {
1911                    // Pace immediate discovery failures so retries cannot monopolize the executor.
1912                    let delay = self.shared.jittered(
1913                        self.shared
1914                            .opts
1915                            .reconnect_backoff
1916                            .delay_after_attempt(attempt),
1917                    );
1918                    self.shared.sleep_until_retry(deadline, delay).await?;
1919                    continue;
1920                }
1921                Err(err) => return Err(err),
1922            }
1923        }
1924    }
1925
1926    /// Fetch the supervisor's atomic spawn snapshot (`supervisor.spawn_snapshot`)
1927    /// over channel 0: the live processes with their spawn generations, and the
1928    /// cursor at which they were observed.
1929    ///
1930    /// A daemon refusal comes back as [`CallError::Module`], so its code is readable
1931    /// through [`CallError::code`]. Transport failures are retried until the
1932    /// consumer's call deadline with its reconnect backoff, as for
1933    /// [`SubcConsumer::catalog_list`].
1934    pub async fn spawn_snapshot(&self) -> Result<SpawnSnapshot, CallError> {
1935        let deadline = Instant::now() + self.shared.opts.call_timeout;
1936        let body = serde_json::to_vec(&ClientControlRequest::SupervisorSpawnSnapshot {}).map_err(
1937            |err| CallError::not_sent(format!("failed to encode supervisor.spawn_snapshot: {err}")),
1938        )?;
1939
1940        let mut attempt = 0usize;
1941        loop {
1942            attempt = attempt.saturating_add(1);
1943            match self
1944                .shared
1945                .control_call(body.clone(), deadline, false, None)
1946                .await
1947            {
1948                Ok(TerminalFrame::Response { body, .. }) => {
1949                    let response =
1950                        serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1951                            CallError::invalid_response(format!(
1952                                "failed to decode supervisor.spawn_snapshot response: {err}"
1953                            ))
1954                        })?;
1955                    let ClientControlResponse::SupervisorSpawnSnapshot { snapshot } = response
1956                    else {
1957                        return Err(CallError::invalid_response(
1958                            "supervisor.spawn_snapshot returned an unexpected control response",
1959                        ));
1960                    };
1961                    return Ok(snapshot);
1962                }
1963                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1964                Ok(TerminalFrame::StreamEnd) => {
1965                    return Err(CallError::invalid_response(
1966                        "supervisor.spawn_snapshot returned StreamEnd",
1967                    ));
1968                }
1969                Err(err)
1970                    if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1971                {
1972                    let delay = self.shared.jittered(
1973                        self.shared
1974                            .opts
1975                            .reconnect_backoff
1976                            .delay_after_attempt(attempt),
1977                    );
1978                    self.shared.sleep_until_retry(deadline, delay).await?;
1979                    continue;
1980                }
1981                Err(err) => return Err(err),
1982            }
1983        }
1984    }
1985
1986    /// Query the newest-first activity ledger. The reply preserves entries, the
1987    /// continuation cursor and the head to subscribe from without a query/follow gap.
1988    /// Except for operator-app connections, identity is filled from the supervised
1989    /// launch environment, as for route.open; without one the daemon treats the
1990    /// caller as Direct. Refusals retain their code
1991    /// through [`CallError::code`]. Transport retries are paced to the call deadline.
1992    pub async fn query_activity(
1993        &self,
1994        request: ActivityQueryRequest,
1995    ) -> Result<ActivityQueryResponse, CallError> {
1996        let deadline = Instant::now() + self.shared.opts.call_timeout;
1997        let body = self.shared.activity_read_body(request)?;
1998        let mut attempt = 0usize;
1999        loop {
2000            attempt = attempt.saturating_add(1);
2001            match self
2002                .shared
2003                .control_call(body.clone(), deadline, false, None)
2004                .await
2005            {
2006                Ok(TerminalFrame::Response { body, .. }) => {
2007                    return serde_json::from_slice(&body).map_err(|err| {
2008                        CallError::invalid_response(format!(
2009                            "invalid activity.query response: {err}"
2010                        ))
2011                    });
2012                }
2013                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
2014                Ok(TerminalFrame::StreamEnd) => {
2015                    return Err(CallError::invalid_response(
2016                        "activity.query returned StreamEnd",
2017                    ));
2018                }
2019                Err(err)
2020                    if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
2021                {
2022                    let delay = self.shared.jittered(
2023                        self.shared
2024                            .opts
2025                            .reconnect_backoff
2026                            .delay_after_attempt(attempt),
2027                    );
2028                    self.shared.sleep_until_retry(deadline, delay).await?;
2029                }
2030                Err(err) => return Err(err),
2031            }
2032        }
2033    }
2034
2035    /// Follow durable activity entries after `since`, or from now if absent.
2036    /// The launch identity is filled as for [`Self::query_activity`]. Refused cursors
2037    /// and subscriber lag are terminal stream errors whose daemon code is readable
2038    /// through [`crate::ActivityStreamError::code`]. On reconnect the stream ends;
2039    /// recover with a query and subscribe from its head.
2040    pub async fn subscribe_activity(
2041        &self,
2042        since: Option<ActivityCursor>,
2043    ) -> Result<ActivitySubscription, CallError> {
2044        let deadline = Instant::now() + self.shared.opts.call_timeout;
2045        let body = self
2046            .shared
2047            .activity_read_body(ActivitySubscribeRequest { since })?;
2048        loop {
2049            self.shared.ensure_connected_for_call(deadline).await?;
2050            let permit = Arc::new(Semaphore::new(1))
2051                .acquire_owned()
2052                .await
2053                .map_err(|_| CallError::not_sent("activity subscription permit closed"))?;
2054            match self
2055                .shared
2056                .send_subscription(SubscriptionSend {
2057                    expected_handle: None,
2058                    channel: 0,
2059                    epoch: 0,
2060                    body: body.clone(),
2061                    priority: Priority::Interactive,
2062                    admission_class: AdmissionClass::Normal,
2063                    event_buffer: ACTIVITY_EVENT_BUFFER,
2064                    deadline,
2065                    permit: RoutePermit::legacy(permit),
2066                })
2067                .await
2068            {
2069                Ok(inner) => {
2070                    return Ok(ActivitySubscription {
2071                        inner,
2072                        finished: false,
2073                    })
2074                }
2075                Err(err) if err.is_not_sent() && Instant::now() < deadline => continue,
2076                Err(err) => return Err(err),
2077            }
2078        }
2079    }
2080
2081    /// Follow the supervisor's spawn event stream (`supervisor.spawn_subscribe`) over
2082    /// channel 0, from just after `since` (a cursor copied from a snapshot or an event),
2083    /// or from now when `since` is `None`.
2084    ///
2085    /// The request is held open: the returned [`SpawnSubscription`] yields each event
2086    /// until the stream ends. A cursor the daemon refuses, and the daemon dropping a
2087    /// subscriber that fell behind, arrive as the stream's terminal error (see
2088    /// [`SpawnStreamError`]). A reconnect ends the stream; the caller resubscribes from
2089    /// the last cursor it received. Sending is retried until the consumer's call
2090    /// deadline, as for [`SubcConsumer::spawn_snapshot`].
2091    pub async fn spawn_subscribe(
2092        &self,
2093        since: Option<SpawnCursor>,
2094    ) -> Result<SpawnSubscription, CallError> {
2095        let deadline = Instant::now() + self.shared.opts.call_timeout;
2096        let body = serde_json::to_vec(&ClientControlRequest::SupervisorSpawnSubscribe { since })
2097            .map_err(|err| {
2098                CallError::not_sent(format!(
2099                    "failed to encode supervisor.spawn_subscribe: {err}"
2100                ))
2101            })?;
2102        loop {
2103            self.shared.ensure_connected_for_call(deadline).await?;
2104            // Channel 0 has no route flow-control window; the subscription holds a
2105            // permit of its own so it is shaped like a route subscription.
2106            let permit = Arc::new(Semaphore::new(1))
2107                .acquire_owned()
2108                .await
2109                .map_err(|_| CallError::not_sent("spawn subscription permit closed"))?;
2110            match self
2111                .shared
2112                .send_subscription(SubscriptionSend {
2113                    expected_handle: None,
2114                    channel: 0,
2115                    epoch: 0,
2116                    body: body.clone(),
2117                    priority: Priority::Interactive,
2118                    admission_class: AdmissionClass::Normal,
2119                    event_buffer: SPAWN_EVENT_BUFFER,
2120                    deadline,
2121                    permit: RoutePermit::legacy(permit),
2122                })
2123                .await
2124            {
2125                Ok(inner) => {
2126                    return Ok(SpawnSubscription {
2127                        inner,
2128                        finished: false,
2129                    })
2130                }
2131                Err(err) if err.is_not_sent() && Instant::now() < deadline => continue,
2132                Err(err) => return Err(err),
2133            }
2134        }
2135    }
2136
2137    /// Resolve the sole catalog claimant for a capability.
2138    ///
2139    /// Resolution is deliberately based only on the static capabilities mirror in
2140    /// `catalog.list`; module ids and role names are not fallback claims. Calling
2141    /// this method expresses singular intent, so a plural catalog result is an
2142    /// explicit ambiguity rather than an arbitrary choice.
2143    pub async fn resolve_provider(&self, capability: &str) -> Result<String, CallError> {
2144        let claimants = self.resolve_providers(capability).await?;
2145        match claimants.as_slice() {
2146            [] => Err(CallError::CapabilityUnprovided {
2147                capability: capability.to_string(),
2148            }),
2149            [claimant] => Ok(claimant.clone()),
2150            _ => Err(CallError::CapabilityAmbiguous {
2151                capability: capability.to_string(),
2152                claimants,
2153            }),
2154        }
2155    }
2156
2157    /// Resolve every catalog claimant for a capability in module-id order.
2158    ///
2159    /// The identifier is validated before any channel-0 request is made, so a
2160    /// typo cannot become a network-dependent "unprovided" result.
2161    pub async fn resolve_providers(&self, capability: &str) -> Result<Vec<String>, CallError> {
2162        validate_capability_for_resolution(capability)?;
2163        let catalog = self.catalog_list().await?;
2164        Ok(capability_claimants(&catalog, capability))
2165    }
2166
2167    /// Send one request using an already-opened route handle.
2168    /// `opts.scope` must be `None`: the handle's scope was selected at route open.
2169    pub async fn request(
2170        &self,
2171        handle: &RouteHandle,
2172        body: Vec<u8>,
2173        opts: CallOptions,
2174    ) -> Result<Vec<u8>, CallError> {
2175        self.request_inner(handle, body, opts, None).await
2176    }
2177
2178    /// Like [`Self::request`], with explicit cancellation of the in-flight request.
2179    ///
2180    /// The returned future is lazy and has the same result and deadline as `request`.
2181    /// Calling [`CancelHandle::cancel`] sends at most one header-only Cancel on the
2182    /// request's route; it does not stop waiting for the provider's Response or Error.
2183    /// Dropping the handle sends nothing. Dropping the future only removes its
2184    /// pending registration, **without sending Cancel**.
2185    ///
2186    /// ```no_run
2187    /// # async fn turn(consumer: &subc_client_rs::SubcConsumer,
2188    /// # route: &subc_client_rs::RouteHandle,
2189    /// # turn_stopped: impl std::future::Future<Output = ()>) -> Result<(), subc_client_rs::CallError> {
2190    /// let (cancel, reply) = consumer.request_cancellable(
2191    ///     route, b"work".to_vec(), subc_client_rs::CallOptions::default());
2192    /// tokio::pin!(reply);
2193    /// tokio::select! {
2194    ///     result = &mut reply => { let _body = result?; }
2195    ///     () = turn_stopped => {
2196    ///         cancel.cancel().await;
2197    ///         let _body = reply.await?; // Keep any final Response body.
2198    ///     }
2199    /// }
2200    /// # Ok(())
2201    /// # }
2202    /// ```
2203    pub fn request_cancellable(
2204        &self,
2205        handle: &RouteHandle,
2206        body: Vec<u8>,
2207        opts: CallOptions,
2208    ) -> (
2209        CancelHandle,
2210        impl Future<Output = Result<Vec<u8>, CallError>> + Send + '_,
2211    ) {
2212        let consumer = self;
2213        let handle = *handle;
2214        let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2215        let future = async move {
2216            let guard = registration;
2217            consumer
2218                .request_inner(&handle, body, opts, Some(Arc::clone(&guard.state)))
2219                .await
2220        };
2221        (cancel, future)
2222    }
2223
2224    async fn request_inner(
2225        &self,
2226        handle: &RouteHandle,
2227        body: Vec<u8>,
2228        opts: CallOptions,
2229        cancel: Option<Arc<UnaryCancel>>,
2230    ) -> Result<Vec<u8>, CallError> {
2231        opts.reject_scope()?;
2232        let deadline = Instant::now() + opts.timeout;
2233        let route = self.shared.route_state(*handle)?;
2234        let permit = route.acquire(false, deadline, cancel.as_ref()).await?;
2235        let mut busy_delay = Duration::from_millis(25);
2236        loop {
2237            let result = self
2238                .shared
2239                .send_request_with_slot(
2240                    RequestSend {
2241                        binary: false,
2242                        expected_handle: Some(*handle),
2243                        channel: handle.channel,
2244                        epoch: handle.epoch,
2245                        body: body.clone(),
2246                        priority: opts.priority,
2247                        admission_class: opts.admission_class,
2248                        deadline,
2249                        retain_late_route_open: false,
2250                        route_open_reverse_requests: None,
2251                    },
2252                    cancel.clone(),
2253                    Some(Arc::clone(&permit)),
2254                )
2255                .await;
2256            match result? {
2257                TerminalFrame::Response { body, .. } => return Ok(body),
2258                TerminalFrame::StreamEnd => return Ok(Vec::new()),
2259                TerminalFrame::Error { body, flags }
2260                    if error_codes::is_route_busy_retryable(flags, &body.code, route.opted_in) =>
2261                {
2262                    if !self
2263                        .shared
2264                        .busy_backoff(deadline, busy_delay, cancel.as_ref())
2265                        .await
2266                    {
2267                        return Err(busy_error(&body));
2268                    }
2269                    busy_delay = (busy_delay * 2).min(Duration::from_secs(1));
2270                    self.shared.validate_current_handle(*handle)?;
2271                }
2272                TerminalFrame::Error { body, .. } => return Err(CallError::Module(body)),
2273            }
2274        }
2275    }
2276
2277    /// Start a held-open request using an already-opened route handle.
2278    /// `opts.scope` must be `None`: the handle's scope was selected at route open.
2279    pub async fn subscribe_route(
2280        &self,
2281        handle: &RouteHandle,
2282        body: Vec<u8>,
2283        opts: SubscribeOptions,
2284    ) -> Result<Subscription, CallError> {
2285        if opts.scope.is_some() {
2286            return Err(CallError::not_sent(
2287                "SubscribeOptions.scope is not supported on subscribe_route; select the scope when opening the route",
2288            ));
2289        }
2290        let deadline = Instant::now() + opts.route_open_timeout;
2291        let route = self.shared.route_state(*handle)?;
2292        let permit = route.acquire(true, deadline, None).await?;
2293        self.shared
2294            .send_subscription(SubscriptionSend {
2295                expected_handle: Some(*handle),
2296                channel: handle.channel,
2297                epoch: handle.epoch,
2298                body,
2299                priority: opts.priority,
2300                admission_class: opts.admission_class,
2301                event_buffer: opts.event_buffer,
2302                deadline,
2303                permit,
2304            })
2305            .await
2306    }
2307
2308    /// Poll status or liveness for exactly this route handle.
2309    /// A daemon refusal is returned as [`CallError::Module`] with its original body.
2310    pub async fn poll_route(
2311        &self,
2312        handle: &RouteHandle,
2313        kind: PollKind,
2314        timeout: Duration,
2315    ) -> Result<RoutePollResult, CallError> {
2316        let deadline = Instant::now() + timeout;
2317        let body = serde_json::to_vec(&ClientControlRequest::RoutePoll {
2318            route_channel: handle.channel,
2319            route_epoch: handle.epoch,
2320            kind,
2321        })
2322        .map_err(|err| CallError::not_sent(format!("failed to encode route.poll: {err}")))?;
2323        let terminal = self
2324            .shared
2325            .send_request(RequestSend {
2326                binary: false,
2327                expected_handle: Some(*handle),
2328                channel: 0,
2329                epoch: 0,
2330                body,
2331                priority: Priority::Interactive,
2332                admission_class: AdmissionClass::Normal,
2333                deadline,
2334                retain_late_route_open: false,
2335                route_open_reverse_requests: None,
2336            })
2337            .await?;
2338        let body = match terminal {
2339            TerminalFrame::Response { body, .. } => body,
2340            TerminalFrame::Error { body, .. } => return Err(CallError::Module(body)),
2341            TerminalFrame::StreamEnd => {
2342                return Err(CallError::invalid_response(
2343                    "route.poll returned a non-response frame",
2344                ));
2345            }
2346        };
2347        let ClientControlResponse::RoutePoll {
2348            route_channel,
2349            route_epoch,
2350            status,
2351            live,
2352        } = serde_json::from_slice(&body).map_err(|err| {
2353            CallError::invalid_response(format!("failed to decode route.poll: {err}"))
2354        })?
2355        else {
2356            return Err(CallError::invalid_response(
2357                "route.poll returned an unexpected control response",
2358            ));
2359        };
2360        if route_channel != handle.channel || route_epoch != handle.epoch {
2361            return Err(CallError::invalid_response(
2362                "route.poll response echoed a different route handle",
2363            ));
2364        }
2365        self.shared.validate_current_handle(*handle)?;
2366        Ok(RoutePollResult {
2367            handle: *handle,
2368            status,
2369            live,
2370        })
2371    }
2372
2373    /// Locally observed count of unknown or stale route frames dropped by layer-2 validation.
2374    pub fn dropped_route_frames(&self) -> u64 {
2375        self.shared.lock_inner().dropped_route_frames
2376    }
2377
2378    /// Register a receiver for provider-originated Push frames on exactly one live route.
2379    ///
2380    /// Registering another receiver for the same route replaces and closes the prior receiver.
2381    /// The receiver closes when its route closes or the connection drops. A FULL buffer drops
2382    /// the overflowing push and counts it on `pushes_dropped_receiver_full` while the
2383    /// subscription survives (issue #40; push is a lossy latency optimization and polling
2384    /// remains the correctness backstop). The reader never waits for an application that is
2385    /// not draining pushes.
2386    pub fn push_events(
2387        &self,
2388        handle: &RouteHandle,
2389    ) -> Result<mpsc::Receiver<PushEvent>, CallError> {
2390        self.shared.register_push_events(*handle)
2391    }
2392
2393    /// Number of Push frames dropped because their live route has no active receiver.
2394    ///
2395    /// Push is a one-way latency optimization, not a durable feed: the client does not
2396    /// acknowledge it, and callers retain polling as their correctness backstop. Counting
2397    /// intentional default-path drops makes an application that has not opted in observable.
2398    pub fn pushes_dropped_no_receiver(&self) -> u64 {
2399        self.shared
2400            .pushes_dropped_no_receiver
2401            .load(Ordering::Relaxed)
2402    }
2403
2404    /// Pushes dropped because the registered receiver's bounded buffer was full.
2405    /// The subscription SURVIVES a burst (the receiver stays registered); this
2406    /// counter is the trace the burst leaves. Distinct from
2407    /// `pushes_dropped_no_receiver` because the remedies differ: full means
2408    /// drain faster or register with more capacity, no-receiver means nobody
2409    /// subscribed.
2410    pub fn pushes_dropped_receiver_full(&self) -> u64 {
2411        self.shared
2412            .pushes_dropped_receiver_full
2413            .load(Ordering::Relaxed)
2414    }
2415
2416    /// Register the consumer-level receiver for daemon-originated channel-0
2417    /// control pushes (`route.closing`, `route.closed`, and any op added
2418    /// later). Advisory by contract: GOODBYE remains the load-bearing
2419    /// route-death signal and nothing in the client's own lifecycle consumes
2420    /// these. Unrecognized ops are DELIVERED (the must-ignore choice belongs
2421    /// to the consumer); unparseable bodies are dropped and counted. The
2422    /// receiver survives reconnects. Registering again replaces the prior
2423    /// receiver; a full or closed receiver drops the push and counts it
2424    /// rather than blocking the reader.
2425    pub fn control_pushes(&self, capacity: usize) -> mpsc::Receiver<ControlPush> {
2426        let (sender, receiver) = mpsc::channel(capacity.max(1));
2427        self.shared.lock_inner().control_push_receiver = Some(sender);
2428        receiver
2429    }
2430
2431    /// Always-present count of dropped channel-0 control pushes (no receiver
2432    /// registered, receiver full or closed, or unparseable body). Emitted as a
2433    /// counter rather than silence so an application that has not opted in is
2434    /// observable, mirroring `pushes_dropped_no_receiver`.
2435    pub fn control_pushes_dropped(&self) -> u64 {
2436        self.shared.control_pushes_dropped.load(Ordering::Relaxed)
2437    }
2438
2439    /// Managed unary call. Route-open failures happen before the body is sent and are
2440    /// classified as `NotSent`; module handler Error frames are the only `Module` errors.
2441    ///
2442    /// A daemon refusal that proves the module never received the request
2443    /// (`unknown_channel`, `stale_route_epoch`, or `module_reloading` while the
2444    /// module drains for a restart, reload or disable) evicts the cached route,
2445    /// reopens it and resends the request once, within the call deadline and
2446    /// only if the call has not been cancelled. Reopening during a drain waits
2447    /// out the daemon's `route.open` refusals until the replacement process
2448    /// registers, so the resend reaches the new process. A second such refusal
2449    /// is returned as `CallError::Module`.
2450    pub async fn call(
2451        &self,
2452        target: RouteTarget,
2453        identity: BindIdentity,
2454        body: Vec<u8>,
2455        opts: CallOptions,
2456    ) -> Result<Vec<u8>, CallError> {
2457        self.call_with_reply(target, identity, body, opts)
2458            .await
2459            .map(CallReply::into_body)
2460    }
2461
2462    /// Like [`Self::call`], retaining the terminal Response's binary flag as well
2463    /// as its unchanged body bytes. A StreamEnd yields an empty, non-binary reply.
2464    pub async fn call_with_reply(
2465        &self,
2466        target: RouteTarget,
2467        identity: BindIdentity,
2468        body: Vec<u8>,
2469        opts: CallOptions,
2470    ) -> Result<CallReply, CallError> {
2471        self.call_inner(target, identity, (body, false), opts, None)
2472            .await
2473    }
2474
2475    /// Managed unary call with explicit cancellation, like [`Self::request_cancellable`].
2476    ///
2477    /// Uses the same route opening, options, errors and deadline as [`Self::call`].
2478    /// Once cancellation is requested, a dead-route or `module_reloading` refusal is
2479    /// returned rather than retrying work the caller has asked to stop. Cancellation during route opening
2480    /// is remembered and sent after the Request is queued. Dropping either value
2481    /// sends no Cancel; dropping the future removes its pending registration.
2482    pub fn call_cancellable(
2483        &self,
2484        target: RouteTarget,
2485        identity: BindIdentity,
2486        body: Vec<u8>,
2487        opts: CallOptions,
2488    ) -> (
2489        CancelHandle,
2490        impl Future<Output = Result<Vec<u8>, CallError>> + Send + '_,
2491    ) {
2492        let (cancel, reply) = self.call_cancellable_with_reply(target, identity, body, opts);
2493        (cancel, async move { reply.await.map(CallReply::into_body) })
2494    }
2495
2496    /// Like [`Self::call_cancellable`], retaining the terminal Response's binary
2497    /// flag and unchanged bytes in [`CallReply`]. Cancellation, retries, deadlines
2498    /// and drop behavior are identical. A StreamEnd yields an empty, non-binary reply.
2499    pub fn call_cancellable_with_reply(
2500        &self,
2501        target: RouteTarget,
2502        identity: BindIdentity,
2503        body: Vec<u8>,
2504        opts: CallOptions,
2505    ) -> (
2506        CancelHandle,
2507        impl Future<Output = Result<CallReply, CallError>> + Send + '_,
2508    ) {
2509        let consumer = self;
2510        let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2511        let future = async move {
2512            let guard = registration;
2513            consumer
2514                .call_inner(
2515                    target,
2516                    identity,
2517                    (body, false),
2518                    opts,
2519                    Some(Arc::clone(&guard.state)),
2520                )
2521                .await
2522        };
2523        (cancel, future)
2524    }
2525
2526    /// Sends a framed JSON object head and opaque payload with `FLAG_BINARY`.
2527    /// Only use this for management operations that declare `operation_payload`.
2528    /// The caller enforces the operation's limit; the codec only bounds the head.
2529    pub async fn call_framed_with_reply(
2530        &self,
2531        target: RouteTarget,
2532        identity: BindIdentity,
2533        head: serde_json::Value,
2534        payload: Vec<u8>,
2535        opts: CallOptions,
2536    ) -> Result<CallReply, CallError> {
2537        let body = subc_protocol::framed_body::encode(&head, &payload)
2538            .map_err(|error| CallError::not_sent(format!("invalid framed request: {error}")))?;
2539        self.call_inner(target, identity, (body, true), opts, None)
2540            .await
2541    }
2542
2543    /// Cancellable companion to [`Self::call_framed_with_reply`], with the same
2544    /// lazy send, cancellation, retry and deadline behavior as other managed calls.
2545    pub fn call_framed_cancellable_with_reply(
2546        &self,
2547        target: RouteTarget,
2548        identity: BindIdentity,
2549        head: serde_json::Value,
2550        payload: Vec<u8>,
2551        opts: CallOptions,
2552    ) -> (
2553        CancelHandle,
2554        impl Future<Output = Result<CallReply, CallError>> + Send + '_,
2555    ) {
2556        let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2557        (cancel, async move {
2558            let guard = registration;
2559            let body = subc_protocol::framed_body::encode(&head, &payload)
2560                .map_err(|error| CallError::not_sent(format!("invalid framed request: {error}")))?;
2561            self.call_inner(
2562                target,
2563                identity,
2564                (body, true),
2565                opts,
2566                Some(Arc::clone(&guard.state)),
2567            )
2568            .await
2569        })
2570    }
2571
2572    async fn call_inner(
2573        &self,
2574        target: RouteTarget,
2575        identity: BindIdentity,
2576        body: (Vec<u8>, bool),
2577        opts: CallOptions,
2578        cancel: Option<Arc<UnaryCancel>>,
2579    ) -> Result<CallReply, CallError> {
2580        let mut history = CallAttemptHistory {
2581            never_forwarded: true,
2582            sent: false,
2583        };
2584        self.call_attempts(target, identity, body, opts, cancel, &mut history)
2585            .await
2586            .map_err(|err| {
2587                let err = if history.sent && matches!(err, CallError::StaleRouteHandle(_)) {
2588                    CallError::not_sent(err.to_string())
2589                } else {
2590                    err
2591                };
2592                err.with_never_forwarded(history.never_forwarded)
2593            })
2594    }
2595
2596    async fn call_attempts(
2597        &self,
2598        target: RouteTarget,
2599        identity: BindIdentity,
2600        body: (Vec<u8>, bool),
2601        opts: CallOptions,
2602        cancel: Option<Arc<UnaryCancel>>,
2603        history: &mut CallAttemptHistory,
2604    ) -> Result<CallReply, CallError> {
2605        let (body, binary) = body;
2606        let call_deadline = Instant::now() + opts.timeout;
2607        // Preserve the single resend policy even for older daemons whose
2608        // unmarked refusals cannot prove that the module never saw the request.
2609        let mut resent_after_unsent_refusal = false;
2610        let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
2611        let consumer_capabilities = route_open_consumer_capabilities(&opts);
2612        let role_versions = route_open_role_versions(opts.role_versions.as_ref());
2613        let route_key = RouteKey::new(
2614            &target,
2615            &identity,
2616            consumer_identity.as_ref(),
2617            consumer_capabilities.as_deref(),
2618        )
2619        .with_role_versions(role_versions.as_ref())
2620        .with_scope(opts.scope.as_ref());
2621
2622        let route_open = RouteOpenParams {
2623            target: &target,
2624            identity: &identity,
2625            consumer_identity: &consumer_identity,
2626            consumer_capabilities: &consumer_capabilities,
2627            role_versions: &role_versions,
2628            reverse_requests: &opts.reverse_requests,
2629            scope: opts.scope.as_ref(),
2630        };
2631
2632        let mut busy_permit: Option<Arc<RoutePermit>> = None;
2633        let mut busy_delay = Duration::from_millis(25);
2634        loop {
2635            let route = self
2636                .shared
2637                .ensure_route(&route_key, &route_open, &opts, call_deadline)
2638                .await
2639                .map_err(request_not_sent_after_route_open_failure)?;
2640            if busy_permit
2641                .as_ref()
2642                .is_some_and(|permit| !permit.belongs_to(&route))
2643            {
2644                busy_permit.take();
2645            }
2646            let permit = match busy_permit.take() {
2647                Some(permit) => permit,
2648                None => route
2649                    .acquire(false, call_deadline, cancel.as_ref())
2650                    .await
2651                    .map_err(|err| {
2652                        if matches!(err, CallError::StaleRouteHandle(_)) {
2653                            self.shared.route_not_sent_error(route.handle)
2654                        } else {
2655                            err
2656                        }
2657                    })?,
2658            };
2659
2660            if !self.shared.route_is_current(&route_key, &route) {
2661                drop(permit);
2662                self.shared
2663                    .sleep_until_retry(call_deadline, opts.route_retry.base)
2664                    .await?;
2665                continue;
2666            }
2667
2668            // Snapshot trust for the route's generation before awaiting its reply;
2669            // a reconnect must not lend a newer daemon's guarantees to an old frame.
2670            let daemon_origin_trusted = {
2671                let inner = self.shared.lock_inner();
2672                inner.generation == route.handle.connection_token() && inner.daemon_origin_trusted
2673            };
2674            let response = self
2675                .shared
2676                .send_request_with_slot(
2677                    RequestSend {
2678                        expected_handle: Some(route.handle),
2679                        channel: route.handle.channel,
2680                        epoch: route.handle.epoch,
2681                        body: body.clone(),
2682                        binary,
2683                        priority: opts.priority,
2684                        admission_class: opts.admission_class,
2685                        deadline: call_deadline,
2686                        retain_late_route_open: false,
2687                        route_open_reverse_requests: None,
2688                    },
2689                    cancel.clone(),
2690                    Some(Arc::clone(&permit)),
2691                )
2692                .await;
2693
2694            history.sent |= response.is_ok();
2695            let proven_undelivered = match &response {
2696                Ok(TerminalFrame::Error { body, flags }) => {
2697                    is_refusal_on_route(daemon_origin_trusted, *flags, &body.code, route.opted_in)
2698                }
2699                Err(err) => {
2700                    err.never_forwarded() == Some(true)
2701                        || matches!(err, CallError::StaleRouteHandle(_))
2702                }
2703                _ => false,
2704            };
2705            history.never_forwarded &= proven_undelivered;
2706
2707            match response {
2708                Ok(TerminalFrame::Response { body, flags, .. }) => {
2709                    return Ok(CallReply {
2710                        body,
2711                        binary: flags.is_binary(),
2712                    });
2713                }
2714                Ok(TerminalFrame::StreamEnd) => {
2715                    return Ok(CallReply {
2716                        body: Vec::new(),
2717                        binary: false,
2718                    });
2719                }
2720                Ok(TerminalFrame::Error { body, flags })
2721                    if error_codes::is_route_busy_retryable(flags, &body.code, route.opted_in) =>
2722                {
2723                    if !self
2724                        .shared
2725                        .busy_backoff(call_deadline, busy_delay, cancel.as_ref())
2726                        .await
2727                    {
2728                        return Err(busy_error(&body));
2729                    }
2730                    busy_delay = (busy_delay * 2).min(Duration::from_secs(1));
2731                    busy_permit = Some(permit);
2732                    continue;
2733                }
2734                // Route-dead and drain refusals share one eviction/resend budget.
2735                // Only a trusted daemon-origin flag proves non-delivery; the retry
2736                // policy itself stays compatible with older daemons.
2737                Ok(TerminalFrame::Error { body, flags })
2738                    if (error_codes::is_established_route_dead(flags, &body.code)
2739                        || is_data_plane_drain_refusal(&body.code))
2740                        && !resent_after_unsent_refusal
2741                        && !cancel.as_ref().is_some_and(|cancel| cancel.requested())
2742                        && Instant::now() < call_deadline =>
2743                {
2744                    resent_after_unsent_refusal = true;
2745                    self.shared.invalidate_route(&route_key, Some(route.handle));
2746                    continue;
2747                }
2748                Ok(TerminalFrame::Error { body, flags })
2749                    if is_daemon_refusal_before_forward(
2750                        daemon_origin_trusted,
2751                        flags,
2752                        &body.code,
2753                    ) =>
2754                {
2755                    return Err(CallError::not_sent_with_cause(
2756                        format!(
2757                            "daemon refused before forwarding: {} ({})",
2758                            body.code, body.message
2759                        ),
2760                        NotSentCause::DaemonRefusedBeforeForward { code: body.code },
2761                    ));
2762                }
2763                Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
2764                Err(err)
2765                    if err.is_not_sent()
2766                        && Instant::now() < call_deadline
2767                        && !cancel.as_ref().is_some_and(|cancel| cancel.requested()) =>
2768                {
2769                    self.shared.invalidate_route(&route_key, Some(route.handle));
2770                    self.shared.ensure_connected_for_call(call_deadline).await?;
2771                    continue;
2772                }
2773                Err(err)
2774                    if err.outcome_cause() == Some(OutcomeUnknownCause::Deadline)
2775                        && !cancel.as_ref().is_some_and(|cancel| cancel.requested()) =>
2776                {
2777                    self.shared.invalidate_route_with_deadline(
2778                        &route_key,
2779                        Some(route.handle),
2780                        true,
2781                    );
2782                    return Err(err);
2783                }
2784                Err(err) => return Err(err),
2785            }
2786        }
2787    }
2788
2789    /// Open a held-open subscription on a managed route.
2790    ///
2791    /// This opens or reuses the same `(target, identity, consumer_identity, consumer_capabilities, role_versions, scope)` route as
2792    /// [`SubcConsumer::call`], sends one Request that the provider keeps open, and
2793    /// returns a [`Subscription`] whose event receiver yields each matching
2794    /// `StreamData` payload. The request holds one route flow-control permit until
2795    /// `StreamEnd`, an Error frame, route teardown or connection loss. On negotiated
2796    /// routes, local backpressure and unsubscribe keep credit until a wire terminal.
2797    /// Reconnects reject the
2798    /// subscription; callers that need durable replay should resubscribe with their
2799    /// own cursor after observing the failure.
2800    pub async fn subscribe(
2801        &self,
2802        target: RouteTarget,
2803        identity: BindIdentity,
2804        body: Vec<u8>,
2805        opts: SubscribeOptions,
2806    ) -> Result<Subscription, CallError> {
2807        let open_deadline = Instant::now() + opts.route_open_timeout;
2808        let route_opts = CallOptions {
2809            scope: opts.scope.clone(),
2810            timeout: opts.route_open_timeout,
2811            priority: opts.priority,
2812            admission_class: opts.admission_class,
2813            route_retry: opts.route_retry,
2814            route_retry_deadline: opts.route_retry_deadline,
2815            consumer_identity: opts.consumer_identity.clone(),
2816            reverse_requests: opts.reverse_requests.clone(),
2817            role_versions: opts.role_versions.clone(),
2818        };
2819        let consumer_identity = self.shared.route_open_consumer_identity(&route_opts)?;
2820        let consumer_capabilities = route_open_consumer_capabilities(&route_opts);
2821        let role_versions = route_open_role_versions(route_opts.role_versions.as_ref());
2822        let route_key = RouteKey::new(
2823            &target,
2824            &identity,
2825            consumer_identity.as_ref(),
2826            consumer_capabilities.as_deref(),
2827        )
2828        .with_role_versions(role_versions.as_ref())
2829        .with_scope(opts.scope.as_ref());
2830
2831        let route_open = RouteOpenParams {
2832            target: &target,
2833            identity: &identity,
2834            consumer_identity: &consumer_identity,
2835            consumer_capabilities: &consumer_capabilities,
2836            role_versions: &role_versions,
2837            reverse_requests: &opts.reverse_requests,
2838            scope: opts.scope.as_ref(),
2839        };
2840
2841        loop {
2842            let route = self
2843                .shared
2844                .ensure_route(&route_key, &route_open, &route_opts, open_deadline)
2845                .await
2846                .map_err(request_not_sent_after_route_open_failure)?;
2847            let permit = route
2848                .acquire(true, open_deadline, None)
2849                .await
2850                .map_err(|err| {
2851                    if matches!(err, CallError::StaleRouteHandle(_)) {
2852                        self.shared.route_not_sent_error(route.handle)
2853                    } else {
2854                        err
2855                    }
2856                })?;
2857
2858            if !self.shared.route_is_current(&route_key, &route) {
2859                drop(permit);
2860                self.shared
2861                    .sleep_until_retry(open_deadline, opts.route_retry.base)
2862                    .await?;
2863                continue;
2864            }
2865
2866            match self
2867                .shared
2868                .send_subscription(SubscriptionSend {
2869                    expected_handle: Some(route.handle),
2870                    channel: route.handle.channel,
2871                    epoch: route.handle.epoch,
2872                    body: body.clone(),
2873                    priority: opts.priority,
2874                    admission_class: opts.admission_class,
2875                    event_buffer: opts.event_buffer,
2876                    deadline: open_deadline,
2877                    permit,
2878                })
2879                .await
2880            {
2881                Ok(subscription) => return Ok(subscription),
2882                Err(err) if err.is_not_sent() && Instant::now() < open_deadline => {
2883                    self.shared.invalidate_route(&route_key, Some(route.handle));
2884                    self.shared.ensure_connected_for_call(open_deadline).await?;
2885                    continue;
2886                }
2887                Err(err) => return Err(err),
2888            }
2889        }
2890    }
2891
2892    /// Tear down ONE route, keyed by its route-open identity tuple — the parity of the TS
2893    /// client's `closeRoute`. For a long-lived consumer that opens unbounded distinct
2894    /// routes (one per session), this releases a route on session-end without dropping
2895    /// the whole consumer: it drops the cached route, settles in-flight requests on it
2896    /// at-most-once (OutcomeUnknown if already sent, NotSent otherwise), and queues a
2897    /// route GOODBYE so the daemon releases it and notifies the module. When closing
2898    /// a cached route returns, its GOODBYE is queued ahead of any frame sent later on
2899    /// this connection, so the caller may release its per-route budget. If the
2900    /// connection died instead, the daemon releases all its routes on disconnect.
2901    /// `opts.scope` selects only that scope's cache entry; `None` selects only
2902    /// the unscoped entry. Calls and subscriptions use the same route cache.
2903    ///
2904    /// Idempotent: a no-op if the route was never opened or is already closed (callers
2905    /// over-call on session-end). NOT a permanent tombstone — a later `call()` for the
2906    /// same key opens a fresh route. The close-beats-reopen guard ensures a close that
2907    /// races an in-flight route.open WINS (the opened channel is GOODBYE'd, not cached).
2908    ///
2909    /// # Cancel safety
2910    /// Once the cached route is removed, dropping this future abandons any drain
2911    /// wait but still settles pending requests and queues its GOODBYE in the
2912    /// background. The handle stays installed until GOODBYE is queued, unless the
2913    /// connection dies. Cancellation does not queue a second GOODBYE if the close
2914    /// already completed.
2915    pub async fn close_route(
2916        &self,
2917        target: RouteTarget,
2918        identity: BindIdentity,
2919        opts: CloseRouteOptions,
2920    ) {
2921        let Ok(consumer_identity) = self.shared.close_route_consumer_identity(&opts) else {
2922            return;
2923        };
2924        let consumer_capabilities = close_route_consumer_capabilities(&opts);
2925        let key = RouteKey::new(
2926            &target,
2927            &identity,
2928            consumer_identity.as_ref(),
2929            consumer_capabilities.as_deref(),
2930        )
2931        .with_role_versions(route_open_role_versions(opts.role_versions.as_ref()).as_ref())
2932        .with_scope(opts.scope.as_ref());
2933        self.shared.close_route(&key, &opts).await;
2934    }
2935
2936    /// Close exactly this route handle. A stale connection token fails locally and emits no frame.
2937    /// `opts.scope` must be `None`: the handle already selects exactly one route.
2938    ///
2939    /// # Cancel safety
2940    /// After the handle is validated and its route removed, dropping this future
2941    /// abandons any drain wait but still settles pending requests and queues its
2942    /// GOODBYE in the background. The handle is uninstalled after queueing, or when
2943    /// the connection dies; a completed close never queues a second GOODBYE on drop.
2944    pub async fn close_handle(
2945        &self,
2946        handle: &RouteHandle,
2947        opts: CloseRouteOptions,
2948    ) -> Result<(), CallError> {
2949        if opts.scope.is_some() {
2950            return Err(CallError::not_sent(
2951                "CloseRouteOptions.scope is not supported on close_handle; the handle already selects the route",
2952            ));
2953        }
2954        self.shared.close_handle(*handle, &opts).await
2955    }
2956
2957    /// Current transport epoch: 1 on initial connect, then +1 per successful reconnect.
2958    pub fn current_epoch(&self) -> u64 {
2959        self.shared.lock_inner().epoch
2960    }
2961
2962    pub(crate) fn pool_reusable(&self) -> bool {
2963        !self.shared.close_token.is_cancelled()
2964    }
2965
2966    /// Register a connection-state callback. Callbacks are best-effort observability hooks.
2967    pub fn on_connection_state(&self, cb: impl Fn(ConnectionState) + Send + 'static) {
2968        self.shared
2969            .lock_inner()
2970            .callbacks
2971            .push(Arc::new(Mutex::new(Box::new(cb))));
2972    }
2973
2974    /// Close the consumer and settle every pending caller.
2975    pub async fn close(&self) {
2976        self.shared.close_sync("consumer closed");
2977        tokio::task::yield_now().await;
2978    }
2979}
2980
2981impl Drop for SubcConsumer {
2982    fn drop(&mut self) {
2983        self.shared.close_sync("consumer dropped");
2984    }
2985}
2986
2987/// Error returned by [`SubcConsumer`]'s TCP and local connection constructors.
2988#[derive(Debug)]
2989pub enum ConsumerError {
2990    Discovery {
2991        source: connection_file::DiscoveryError,
2992    },
2993    ConnectionFile {
2994        path: PathBuf,
2995        source: ConnectionFileError,
2996    },
2997    /// No endpoint for the requested transport. [`SubcConsumer::connect_local`]
2998    /// returns this when the connection file has no `local_endpoint`.
2999    NoEndpoint {
3000        path: PathBuf,
3001    },
3002    Connect {
3003        path: PathBuf,
3004        endpoint: String,
3005        source: io::Error,
3006    },
3007    Auth {
3008        path: PathBuf,
3009        endpoint: String,
3010        source: AuthError,
3011    },
3012    Closed,
3013}
3014
3015impl ConsumerError {
3016    pub(crate) fn claim(error: crate::ClaimError) -> Self {
3017        Self::Connect {
3018            path: PathBuf::new(),
3019            endpoint: "claim binding".into(),
3020            source: io::Error::other(error),
3021        }
3022    }
3023}
3024
3025impl fmt::Display for ConsumerError {
3026    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3027        match self {
3028            Self::Discovery { source } => source.fmt(f),
3029            Self::ConnectionFile { path, source } => write!(
3030                f,
3031                "failed to read subc connection file '{}': {source}",
3032                path.display()
3033            ),
3034            Self::NoEndpoint { path } => {
3035                write!(
3036                    f,
3037                    "subc connection file '{}' has no endpoint for the requested transport",
3038                    path.display()
3039                )
3040            }
3041            Self::Connect {
3042                path,
3043                endpoint,
3044                source,
3045            } => write!(
3046                f,
3047                "failed to connect to subc endpoint {endpoint} from '{}': {source}",
3048                path.display()
3049            ),
3050            Self::Auth {
3051                path,
3052                endpoint,
3053                source,
3054            } => write!(
3055                f,
3056                "failed to authenticate to subc endpoint {endpoint} from '{}': {source}",
3057                path.display()
3058            ),
3059            Self::Closed => write!(f, "consumer closed"),
3060        }
3061    }
3062}
3063
3064impl Error for ConsumerError {
3065    fn source(&self) -> Option<&(dyn Error + 'static)> {
3066        match self {
3067            Self::Discovery { source } => Some(source),
3068            Self::ConnectionFile { source, .. } => Some(source),
3069            Self::Connect { source, .. } => Some(source),
3070            Self::Auth { source, .. } => Some(source),
3071            Self::NoEndpoint { .. } | Self::Closed => None,
3072        }
3073    }
3074}
3075
3076/// Why a sent request has no observed terminal response.
3077#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3078#[non_exhaustive]
3079pub enum OutcomeUnknownCause {
3080    /// The reply deadline elapsed after the request was sent.
3081    Deadline,
3082    /// The connection's writer closed or failed after send.
3083    WriterClosed,
3084    /// The caller closed the consumer while a request was pending.
3085    ConsumerClosed,
3086    /// The daemon connection failed or dropped.
3087    ConnectionFailed,
3088    /// The route ended; [`CallError::close_reason`] gives its reason.
3089    RouteEnded,
3090    /// An internal completion channel dropped or an unexpected completion arrived.
3091    CompletionFailed,
3092}
3093
3094#[derive(Debug, Clone)]
3095struct OutcomeUnknownSource {
3096    message: String,
3097    cause: OutcomeUnknownCause,
3098    route_reason: Option<RouteEnd>,
3099}
3100
3101impl fmt::Display for OutcomeUnknownSource {
3102    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3103        f.write_str(&self.message)
3104    }
3105}
3106impl Error for OutcomeUnknownSource {}
3107
3108/// Why an attempt was classified as [`CallError::NotSent`]. For resend safety
3109/// across all attempts, also check [`CallError::never_forwarded`].
3110#[derive(Debug, Clone, PartialEq, Eq)]
3111#[non_exhaustive]
3112pub enum NotSentCause {
3113    /// The daemon or module refused route.open before the data request.
3114    RouteOpenRefused { code: String },
3115    /// Route opening ended without a usable answer, including cancellation.
3116    RouteOpenAbandoned,
3117    /// Local validation, connection state or flow control prevented queueing.
3118    BeforeQueue,
3119    /// The deadline elapsed waiting for the writer's cancel-safe queue send.
3120    WriterCapacity,
3121    /// The writer did not accept the request for transmission.
3122    WriterRejected,
3123    /// A control response could not be decoded or had an unexpected shape.
3124    InvalidResponse,
3125    /// No longer produced: since 0.34.2 a dropped completion channel, which
3126    /// can't prove non-delivery, is reported as [`CallError::OutcomeUnknown`]
3127    /// with [`OutcomeUnknownCause::CompletionFailed`]. Kept so existing
3128    /// matches still compile.
3129    CompletionFailed,
3130    /// A daemon-marked data-plane refusal proved this attempt was not forwarded.
3131    DaemonRefusedBeforeForward { code: String },
3132}
3133
3134#[derive(Debug, Clone)]
3135struct NotSentSource {
3136    message: String,
3137    cause: NotSentCause,
3138    never_forwarded: bool,
3139    route_reason: Option<RouteEnd>,
3140    refusal: Option<Box<RouteOpenRefused>>,
3141}
3142
3143impl fmt::Display for NotSentSource {
3144    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3145        f.write_str(&self.message)
3146    }
3147}
3148impl Error for NotSentSource {}
3149
3150/// Managed call or subscription failure.
3151#[derive(Debug)]
3152pub enum CallError {
3153    /// Local compatibility policy refusal: the version retained from the
3154    /// connection file for this connection is not an exact numeric
3155    /// `major.minor.patch` version at least 0.39.0. Unrecognized strings,
3156    /// including prereleases and build suffixes, are refused too. This
3157    /// route-open attempt was refused before being queued for writing.
3158    /// The handshake authenticates the daemon ID, not this version metadata.
3159    DaemonTooOld { daemon_ver: String },
3160    /// A pre-send failure, proven non-delivery, or unusable reply or internal completion.
3161    /// Check [`CallError::never_forwarded`] before treating the whole call as safe to resend.
3162    NotSent(Box<dyn Error + Send + Sync>),
3163    /// The request body was accepted by the writer path, but no terminal response was observed.
3164    OutcomeUnknown(Box<dyn Error + Send + Sync>),
3165    /// The target module handler returned an Error frame. Application-level rejections
3166    /// are returned as ordinary successful response bytes and do not produce this variant.
3167    Module(ErrorBody),
3168    /// A subscription event receiver stopped keeping up with its bounded channel.
3169    ///
3170    /// The reader task must never await a slow consumer while it is dispatching frames
3171    /// for the whole connection, so a full event channel terminates only that subscription.
3172    SubscriptionBackpressure(Box<dyn Error + Send + Sync>),
3173    /// The handle belongs to an earlier connection and no frame was emitted.
3174    StaleRouteHandle(RouteHandle),
3175    /// No registered catalog entry claims the requested capability.
3176    CapabilityUnprovided { capability: String },
3177    /// More than one registered catalog entry claims a singularly requested capability.
3178    CapabilityAmbiguous {
3179        capability: String,
3180        claimants: Vec<String>,
3181    },
3182    /// The resolver rejected a malformed capability identifier before querying the daemon.
3183    InvalidCapabilityIdentifier { capability: String },
3184}
3185
3186impl CallError {
3187    /// A typed terminal scope bind-proof refusal, if the daemon returned one.
3188    pub fn scope_bind_proof_refusal(&self) -> Option<ScopeBindProofRefusal> {
3189        match self.route_open_refusal()?.code.as_str() {
3190            error_codes::SCOPE_BIND_PROOF_REQUIRED => Some(ScopeBindProofRefusal::Required),
3191            error_codes::SCOPE_BIND_PROOF_MISMATCH => Some(ScopeBindProofRefusal::Mismatch),
3192            _ => None,
3193        }
3194    }
3195
3196    /// Why the route ended. The error remains `NotSent` or `OutcomeUnknown`:
3197    /// this reason never makes a sent call safe to resend.
3198    pub fn close_reason(&self) -> Option<&RouteEndReason> {
3199        self.route_end().map(|end| &end.reason)
3200    }
3201
3202    fn route_end(&self) -> Option<&RouteEnd> {
3203        match self {
3204            Self::NotSent(source) => source
3205                .downcast_ref::<NotSentSource>()?
3206                .route_reason
3207                .as_ref(),
3208            Self::OutcomeUnknown(source) => source
3209                .downcast_ref::<OutcomeUnknownSource>()?
3210                .route_reason
3211                .as_ref(),
3212            _ => None,
3213        }
3214    }
3215
3216    /// The daemon's recovery verdict from `route.closed`, if it carried one.
3217    /// `Some(true)` means the daemon will leave the module down until an operator
3218    /// acts. `None` means unknown: older daemons, client-side ends and non-route
3219    /// errors have no verdict. This flag does not change resend safety or the
3220    /// close reason's reopen disposition.
3221    pub fn terminal(&self) -> Option<bool> {
3222        self.route_end()?.terminal
3223    }
3224
3225    /// Why the outcome is unknown, without parsing the error's message.
3226    /// Errors constructed outside this crate with an untyped source return `None`.
3227    pub fn outcome_cause(&self) -> Option<OutcomeUnknownCause> {
3228        match self {
3229            Self::OutcomeUnknown(source) => source
3230                .downcast_ref::<OutcomeUnknownSource>()
3231                .map(|source| source.cause),
3232            _ => None,
3233        }
3234    }
3235
3236    /// Why the final attempt was classified as `NotSent`, without parsing its message.
3237    /// Returns `None` for other variants and externally constructed untyped errors.
3238    pub fn not_sent_cause(&self) -> Option<NotSentCause> {
3239        match self {
3240            Self::NotSent(source) => source
3241                .downcast_ref::<NotSentSource>()
3242                .map(|source| source.cause.clone()),
3243            _ => None,
3244        }
3245    }
3246
3247    /// Whether no attempt of this call may have reached the module.
3248    ///
3249    /// `Some(false)` means this or an earlier attempt may have been forwarded.
3250    /// For data-plane errors, only daemon-marked refusals prove non-delivery;
3251    /// unmarked replies remain conservative on older daemons. Managed calls
3252    /// include every attempt. Returns `None` except for crate-built `NotSent` errors.
3253    pub fn never_forwarded(&self) -> Option<bool> {
3254        match self {
3255            Self::NotSent(source) => source
3256                .downcast_ref::<NotSentSource>()
3257                .map(|source| source.never_forwarded),
3258            _ => None,
3259        }
3260    }
3261
3262    /// Return the stable machine-readable code for typed errors.
3263    pub fn code(&self) -> Option<&str> {
3264        match self {
3265            Self::Module(body) => Some(&body.code),
3266            Self::DaemonTooOld { .. } => Some("daemon_too_old"),
3267            Self::CapabilityUnprovided { .. } => Some("capability_unprovided"),
3268            Self::CapabilityAmbiguous { .. } => Some("capability_ambiguous"),
3269            Self::InvalidCapabilityIdentifier { .. } => Some("invalid_capability_identifier"),
3270            Self::NotSent(source) => match &source.downcast_ref::<NotSentSource>()?.cause {
3271                NotSentCause::DaemonRefusedBeforeForward { code }
3272                    if code == error_codes::ROUTE_BUSY =>
3273                {
3274                    Some(code)
3275                }
3276                _ => None,
3277            },
3278            Self::OutcomeUnknown(_)
3279            | Self::SubscriptionBackpressure(_)
3280            | Self::StaleRouteHandle(_) => None,
3281        }
3282    }
3283
3284    fn not_sent(reason: impl Into<String>) -> Self {
3285        Self::not_sent_with_cause(reason, NotSentCause::BeforeQueue)
3286    }
3287
3288    fn not_sent_with_cause(reason: impl Into<String>, cause: NotSentCause) -> Self {
3289        Self::NotSent(Box::new(NotSentSource {
3290            message: reason.into(),
3291            cause,
3292            never_forwarded: true,
3293            route_reason: None,
3294            refusal: None,
3295        }))
3296    }
3297
3298    fn with_never_forwarded(mut self, never_forwarded: bool) -> Self {
3299        if let Self::NotSent(source) = &mut self {
3300            if let Some(source) = source.downcast_mut::<NotSentSource>() {
3301                source.never_forwarded &= never_forwarded;
3302            }
3303        }
3304        self
3305    }
3306
3307    fn invalid_response(reason: impl Into<String>) -> Self {
3308        Self::not_sent_with_cause(reason, NotSentCause::InvalidResponse).with_never_forwarded(false)
3309    }
3310
3311    fn outcome_unknown(reason: impl Into<String>, cause: OutcomeUnknownCause) -> Self {
3312        Self::outcome_unknown_source(OutcomeUnknownSource {
3313            message: reason.into(),
3314            cause,
3315            route_reason: None,
3316        })
3317    }
3318
3319    fn outcome_unknown_source(source: OutcomeUnknownSource) -> Self {
3320        Self::OutcomeUnknown(Box::new(source))
3321    }
3322
3323    fn is_not_sent(&self) -> bool {
3324        matches!(self, Self::NotSent(_))
3325    }
3326
3327    /// The daemon's refusal body when this failure is a route.open the daemon
3328    /// refused, with its `code`, `message` and machine-readable `detail`
3329    /// intact, for example `module_warming` with
3330    /// `detail.reason = "required_capability_unprovided"`.
3331    ///
3332    /// When retryable refusals ran out the route-retry deadline, this is the
3333    /// most informative refusal seen during the retries, so a caller can tell
3334    /// "the module was reloading" from "the connection failed". Refusals rank:
3335    /// `module_reloading` / `module_warming`, then `delegation_not_registered`,
3336    /// then admission pressure (too many binds in flight), then anything else;
3337    /// at equal rank the later one wins. The failure is still `NotSent`: a
3338    /// refused route.open never delivered the request.
3339    pub fn route_open_refusal(&self) -> Option<&ErrorBody> {
3340        match self {
3341            Self::NotSent(err) => err
3342                .downcast_ref::<NotSentSource>()
3343                .and_then(|source| source.refusal.as_ref())
3344                .map(|refused| &refused.body),
3345            _ => None,
3346        }
3347    }
3348
3349    fn subscription_backpressure(reason: impl Into<String>) -> Self {
3350        Self::SubscriptionBackpressure(Box::new(SimpleError(reason.into())))
3351    }
3352}
3353
3354impl fmt::Display for CallError {
3355    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3356        match self {
3357            Self::DaemonTooOld { daemon_ver } => write!(
3358                f,
3359                "daemon_too_old: route.open requires daemon 0.39.0 or newer (connected version: {daemon_ver})"
3360            ),
3361            Self::NotSent(err) => write!(f, "request not sent: {err}"),
3362            Self::OutcomeUnknown(err) => write!(f, "request outcome unknown: {err}"),
3363            Self::Module(body) => write!(f, "module error {}: {}", body.code, body.message),
3364            Self::SubscriptionBackpressure(err) => {
3365                write!(f, "subscription event channel backpressure: {err}")
3366            }
3367            Self::StaleRouteHandle(handle) => write!(f, "stale route handle: {handle:?}"),
3368            Self::CapabilityUnprovided { capability } => {
3369                write!(
3370                    f,
3371                    "capability_unprovided: no catalog claimant for {capability}"
3372                )
3373            }
3374            Self::CapabilityAmbiguous {
3375                capability,
3376                claimants,
3377            } => write!(
3378                f,
3379                "capability_ambiguous: multiple catalog claimants for {capability}: {claimants:?}"
3380            ),
3381            Self::InvalidCapabilityIdentifier { capability } => write!(
3382                f,
3383                "invalid_capability_identifier: malformed capability identifier {capability:?}"
3384            ),
3385        }
3386    }
3387}
3388
3389impl Error for CallError {
3390    fn source(&self) -> Option<&(dyn Error + 'static)> {
3391        match self {
3392            Self::NotSent(err)
3393            | Self::OutcomeUnknown(err)
3394            | Self::SubscriptionBackpressure(err) => Some(err.as_ref()),
3395            Self::Module(_)
3396            | Self::DaemonTooOld { .. }
3397            | Self::StaleRouteHandle(_)
3398            | Self::CapabilityUnprovided { .. }
3399            | Self::CapabilityAmbiguous { .. }
3400            | Self::InvalidCapabilityIdentifier { .. } => None,
3401        }
3402    }
3403}
3404
3405/// A route.open the daemon refused, kept typed inside [`CallError::NotSent`]
3406/// so the refusal's code and `detail` survive. Read it through
3407/// [`CallError::route_open_refusal`].
3408#[derive(Debug, Clone)]
3409struct RouteOpenRefused {
3410    target: String,
3411    body: ErrorBody,
3412    /// The last refusal of a retry loop, when it is not `body`: kept so the
3413    /// message still says what the daemon answered most recently.
3414    most_recent: Option<ErrorBody>,
3415}
3416
3417/// Terminal refusals requiring the caller to supply the scope's current proof.
3418#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3419#[non_exhaustive]
3420pub enum ScopeBindProofRefusal {
3421    Required,
3422    Mismatch,
3423}
3424
3425impl fmt::Display for RouteOpenRefused {
3426    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3427        write!(
3428            f,
3429            "route.open failed for target {}: {}",
3430            self.target,
3431            DescribeRefusal(&self.body)
3432        )?;
3433        if let Some(most_recent) = &self.most_recent {
3434            write!(
3435                f,
3436                "; the most recent refusal was {}",
3437                DescribeRefusal(most_recent)
3438            )?;
3439        }
3440        Ok(())
3441    }
3442}
3443
3444impl Error for RouteOpenRefused {}
3445
3446/// A refusal as `code (reason r) (message)`, the reason read from
3447/// `detail.reason` and omitted when the daemon sent none.
3448struct DescribeRefusal<'a>(&'a ErrorBody);
3449
3450impl fmt::Display for DescribeRefusal<'_> {
3451    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3452        write!(f, "{}", self.0.code)?;
3453        if let Some(reason) = refusal_reason(self.0) {
3454            write!(f, " (reason {reason})")?;
3455        }
3456        write!(f, " ({})", self.0.message)
3457    }
3458}
3459
3460fn refusal_reason(body: &ErrorBody) -> Option<&str> {
3461    body.detail.as_ref()?.get("reason")?.as_str()
3462}
3463
3464/// The daemon's reasons for refusing a route.open because too many binds are
3465/// already in flight, on the consumer's connection or towards the target module
3466/// (`crates/subc-daemon/src/control.rs`, `route_open_capacity_refusal` and
3467/// `route_open_target_capacity_refusal`). Both are sent as `target_unavailable`.
3468const ADMISSION_PRESSURE_REASONS: [&str; 2] = ["open_admission_full", "target_binds_full"];
3469/// Markers in the messages of those same admission-pressure refusals. The
3470/// daemon currently logs the reason but leaves it out of the refusal's detail,
3471/// so the message is the only way to recognise them.
3472const ADMISSION_PRESSURE_MESSAGES: [&str; 2] =
3473    ["route.open binds in flight", "route.bind relays in flight"];
3474
3475/// How much a route.open refusal says about why the target was unreachable,
3476/// highest first: the module was changing state (reloading or warming); a
3477/// delegation was not registered; admission pressure; anything else.
3478fn route_open_refusal_rank(body: &ErrorBody) -> u8 {
3479    if body.code == error_codes::MODULE_RELOADING || body.code == error_codes::MODULE_WARMING {
3480        return 3;
3481    }
3482    let reason = refusal_reason(body);
3483    if body.code == "delegation_not_registered" || reason == Some("delegation_not_registered") {
3484        return 2;
3485    }
3486    if body.code == error_codes::TARGET_UNAVAILABLE {
3487        let admission_pressure = match reason {
3488            Some(reason) => ADMISSION_PRESSURE_REASONS.contains(&reason),
3489            None => ADMISSION_PRESSURE_MESSAGES
3490                .iter()
3491                .any(|marker| body.message.contains(marker)),
3492        };
3493        if admission_pressure {
3494            return 1;
3495        }
3496    }
3497    0
3498}
3499
3500/// The route.open refusals one retry loop has seen. When the deadline runs out,
3501/// the error is built from the best-ranked one: after a module restart the most
3502/// recent refusal is often admission pressure ("8 binds in flight"), which
3503/// points a reader at the consumer's concurrency when the module was simply down.
3504#[derive(Default)]
3505struct RouteOpenRefusals {
3506    best: Option<ErrorBody>,
3507    /// Set only while the latest refusal ranked below `best`.
3508    most_recent: Option<ErrorBody>,
3509}
3510
3511impl RouteOpenRefusals {
3512    fn record(&mut self, body: ErrorBody) {
3513        // At equal rank the newer refusal wins: it describes the target's latest state.
3514        let outranks = self
3515            .best
3516            .as_ref()
3517            .is_none_or(|best| route_open_refusal_rank(&body) >= route_open_refusal_rank(best));
3518        if outranks {
3519            self.best = Some(body);
3520            self.most_recent = None;
3521        } else {
3522            self.most_recent = Some(body);
3523        }
3524    }
3525
3526    fn into_error(self, target: String) -> Option<CallError> {
3527        let body = self.best?;
3528        Some(CallError::from_route_open_refusal(RouteOpenRefused {
3529            target,
3530            body,
3531            most_recent: self.most_recent,
3532        }))
3533    }
3534}
3535
3536/// The label a route.open refusal names its target by, the same spelling the
3537/// managed route cache uses.
3538fn route_target_label(target: &RouteTarget) -> String {
3539    match target {
3540        RouteTarget::ToolProvider { module_id } => format!("tool_provider:{module_id}"),
3541        RouteTarget::ManagementSurface { module_id } => format!("management_surface:{module_id}"),
3542        RouteTarget::InternalService {
3543            module_id,
3544            service_id,
3545        } => format!("internal_service:{module_id}:{service_id}"),
3546    }
3547}
3548
3549impl CallError {
3550    fn route_open_refused(target: String, body: ErrorBody) -> Self {
3551        Self::from_route_open_refusal(RouteOpenRefused {
3552            target,
3553            body,
3554            most_recent: None,
3555        })
3556    }
3557
3558    fn from_route_open_refusal(refusal: RouteOpenRefused) -> Self {
3559        Self::NotSent(Box::new(NotSentSource {
3560            message: refusal.to_string(),
3561            cause: NotSentCause::RouteOpenRefused {
3562                code: refusal.body.code.clone(),
3563            },
3564            never_forwarded: true,
3565            route_reason: None,
3566            refusal: Some(Box::new(refusal)),
3567        }))
3568    }
3569}
3570
3571#[derive(Debug)]
3572struct SimpleError(String);
3573
3574impl fmt::Display for SimpleError {
3575    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3576        f.write_str(&self.0)
3577    }
3578}
3579
3580impl Error for SimpleError {}
3581
3582type Callback = Arc<Mutex<Box<dyn Fn(ConnectionState) + Send + 'static>>>;
3583
3584type OpeningWaiter = oneshot::Sender<Result<RouteState, SharedCallFailure>>;
3585
3586/// An in-flight route.open for one key: the waiters parked behind the lead opener,
3587/// plus a `closed` flag a concurrent `close_route` flips so the lead opener refuses
3588/// to install its channel (the close-beats-reopen guard). The flag lives here, with
3589/// the in-flight open, so it vanishes when the open finishes — no lingering per-key
3590/// state to leak for a long-lived consumer with unbounded distinct routes.
3591struct Opening {
3592    waiters: Vec<OpeningWaiter>,
3593    closed: bool,
3594}
3595
3596struct Shared {
3597    claim_bound: bool,
3598    connection_file: PathBuf,
3599    operator_app_candidates: Option<Vec<PathBuf>>,
3600    opts: ConsumerOptions,
3601    transport: ConsumerTransport,
3602    identity_from_environment: bool,
3603    inner: Mutex<Inner>,
3604    notify: Notify,
3605    #[cfg(test)]
3606    before_wait: Mutex<Option<Box<dyn FnOnce() + Send>>>,
3607    close_token: CancellationToken,
3608    /// Epoch milliseconds of the last frame dispatched from the current connection.
3609    /// The liveness probe reads this to distinguish a healthy slow request from a
3610    /// socket that has silently stopped delivering inbound traffic.
3611    last_inbound_ms: AtomicU64,
3612    /// Only one deadline-triggered liveness probe may be active across generations.
3613    liveness_probe_running: AtomicBool,
3614    pushes_dropped_no_receiver: AtomicU64,
3615    /// Always-present drop counter for channel-0 control pushes (no receiver,
3616    /// receiver full/closed, or unparseable body). Before this surface existed
3617    /// the drop was SILENT -- not even a counter -- which is how #31's push
3618    /// family shipped unreachable to every Rust consumer (issue #35).
3619    control_pushes_dropped: AtomicU64,
3620    /// Pushes dropped because a registered receiver's bounded buffer was full
3621    /// at delivery time. Distinct from `pushes_dropped_no_receiver` because the
3622    /// operator remedies differ: full means the consumer is too slow (widen the
3623    /// buffer or drain faster), no-receiver means it never subscribed.
3624    pushes_dropped_receiver_full: AtomicU64,
3625    /// Random source in [0, 1) for retry jitter. Tests replace it with a seeded
3626    /// one so jittered delays are reproducible.
3627    random_unit: Box<dyn Fn() -> f64 + Send + Sync>,
3628    /// One permit per route.open the consumer may have outstanding; see
3629    /// [`MAX_ROUTE_OPENS_IN_FLIGHT`]. tokio's semaphore grants permits in
3630    /// request order, which makes the wait first come first served. The consumer
3631    /// holds one connection at a time and a dropped connection fails every open
3632    /// in flight on it, so one semaphore is a per-connection limit.
3633    route_open_slots: Semaphore,
3634    // Serialize the first description lookup, not ordinary opens. The cached
3635    // result belongs to Inner's generation and is reset on reconnect.
3636    route_description: tokio::sync::Mutex<()>,
3637}
3638
3639struct Inner {
3640    generation: u64,
3641    daemon_origin_trusted: bool,
3642    daemon_ver: String,
3643    accepts_close_reasons: Option<bool>,
3644    epoch: u64,
3645    next_corr: Option<u64>,
3646    writer: Option<mpsc::Sender<WriteCommand>>,
3647    pending: HashMap<PendingKey, PendingEntry>,
3648    wire_slots: HashMap<PendingKey, Arc<RoutePermit>>,
3649    routes: HashMap<RouteKey, RouteState>,
3650    route_by_channel: HashMap<u16, RouteKey>,
3651    one_shot_routes: HashMap<u16, RouteState>,
3652    route_epochs: HashMap<u16, RouteHandle>,
3653    route_targets: HashMap<RouteHandle, RouteOpenTarget>,
3654    retired_routes: HashSet<RouteHandle>,
3655    retirement_goodbyes: HashSet<RouteHandle>,
3656    retirement_queue: VecDeque<RouteHandle>,
3657    retirement_notify: Arc<Notify>,
3658    retirement_task: Option<JoinHandle<()>>,
3659    route_modules: HashMap<u16, String>,
3660    route_end_reasons: HashMap<u16, (RouteEnd, bool)>,
3661    legacy_channel_reasons: HashMap<u16, RouteEnd>,
3662    push_event_receivers: HashMap<RouteHandle, mpsc::Sender<PushEvent>>,
3663    /// Consumer-level receiver for daemon-originated channel-0 control pushes
3664    /// (`route.closing`, `route.closed`, future ops). Connection-independent:
3665    /// control pushes are advisory daemon events, so the receiver survives
3666    /// reconnects rather than being keyed by generation.
3667    control_push_receiver: Option<mpsc::Sender<ControlPush>>,
3668    dropped_route_frames: u64,
3669    openings: HashMap<RouteKey, Opening>,
3670    callbacks: Vec<Callback>,
3671    closed: bool,
3672    reconnect: ReconnectState,
3673    restored_token: u64,
3674    reader_task: Option<JoinHandle<()>>,
3675    writer_task: Option<JoinHandle<()>>,
3676}
3677
3678impl Inner {
3679    fn record_route_end(&mut self, push: &ControlPush) {
3680        let Some(reason) = push.route_close_reason() else {
3681            return;
3682        };
3683        let end = RouteEnd {
3684            reason: RouteEndReason::Daemon(reason),
3685            terminal: (push.op == "route.closed")
3686                .then(|| {
3687                    push.body
3688                        .get("terminal")
3689                        .and_then(serde_json::Value::as_bool)
3690                })
3691                .flatten(),
3692        };
3693        if let Some(channels) = push.body.get("channels") {
3694            if let Some(channels) = channels.as_array() {
3695                for channel in channels
3696                    .iter()
3697                    .filter_map(|v| v.as_u64().and_then(|v| u16::try_from(v).ok()))
3698                {
3699                    let final_reason = push.op == "route.closed";
3700                    if final_reason
3701                        || !self
3702                            .route_end_reasons
3703                            .get(&channel)
3704                            .is_some_and(|(_, final_reason)| *final_reason)
3705                    {
3706                        self.route_end_reasons
3707                            .insert(channel, (end.clone(), final_reason));
3708                    }
3709                }
3710            }
3711        } else if let Some(module) = push.body.get("module_id").and_then(|v| v.as_str()) {
3712            for (&channel, target) in &self.route_modules {
3713                if target == module {
3714                    self.legacy_channel_reasons.insert(channel, end.clone());
3715                }
3716            }
3717        }
3718    }
3719
3720    fn route_end(&self, channel: u16) -> RouteEnd {
3721        self.route_end_reasons
3722            .get(&channel)
3723            .map(|(reason, _)| reason.clone())
3724            .or_else(|| self.legacy_channel_reasons.get(&channel).cloned())
3725            .unwrap_or_else(|| RouteEndReason::Unknown.into())
3726    }
3727
3728    #[cfg(test)]
3729    fn route_end_reason(&self, channel: u16) -> RouteEndReason {
3730        self.route_end(channel).reason
3731    }
3732
3733    fn cache_route(&mut self, key: RouteKey, route: RouteState) -> RouteState {
3734        let cached = self.routes.entry(key.clone()).or_insert(route).clone();
3735        let previous = self
3736            .route_by_channel
3737            .insert(cached.handle.channel, key.clone());
3738        debug_assert!(previous.as_ref().is_none_or(|previous| previous == &key));
3739        self.route_epochs
3740            .insert(cached.handle.channel, cached.handle);
3741        cached
3742    }
3743
3744    fn remove_route(&mut self, key: &RouteKey) -> Option<RouteState> {
3745        let route = self.evict_route(key)?;
3746        release_reverse_request_registry(route.handle);
3747        Some(route)
3748    }
3749
3750    fn evict_route(&mut self, key: &RouteKey) -> Option<RouteState> {
3751        let route = self.routes.remove(key)?;
3752        let indexed = self.route_by_channel.remove(&route.handle.channel);
3753        debug_assert_eq!(indexed.as_ref(), Some(key));
3754        Some(route)
3755    }
3756
3757    fn reap_retired_route(&mut self, handle: RouteHandle) {
3758        // A caller may be gone while its written correlation still owns credit.
3759        // Keep ingress for those tombstones as well as live pending callers.
3760        if !self.retired_routes.contains(&handle)
3761            || self
3762                .pending
3763                .keys()
3764                .chain(self.wire_slots.keys())
3765                .any(|key| {
3766                    key.generation == handle.connection_token()
3767                        && key.channel == handle.channel
3768                        && key.epoch == handle.epoch
3769                })
3770        {
3771            return;
3772        }
3773        // Pending keys carry only the wire identity. Use the retained handle
3774        // when releasing its reverse-request registry after retirement.
3775        let handle = *self
3776            .retired_routes
3777            .get(&handle)
3778            .expect("retired route exists");
3779        if self.retirement_goodbyes.contains(&handle) {
3780            if !self.queue_retirement_goodbye(handle) {
3781                // Keep the ingress handle occupied until the flusher queues the
3782                // GOODBYE, so a reopened route cannot take this channel first.
3783                return;
3784            }
3785            self.retirement_goodbyes.remove(&handle);
3786        }
3787        self.retired_routes.remove(&handle);
3788        if self.route_epochs.get(&handle.channel) == Some(&handle) {
3789            self.route_epochs.remove(&handle.channel);
3790            self.route_targets.remove(&handle);
3791            self.push_event_receivers.remove(&handle);
3792        }
3793        release_reverse_request_registry(handle);
3794    }
3795
3796    fn queue_retirement_goodbye(&mut self, handle: RouteHandle) -> bool {
3797        if self.generation != handle.connection_token()
3798            || self.route_epochs.get(&handle.channel) != Some(&handle)
3799            || self.writer.is_none()
3800        {
3801            return true;
3802        }
3803        if self.retirement_queue.is_empty() {
3804            let frame = Frame::build(
3805                FrameType::Goodbye,
3806                Flags::new(false, Priority::Interactive, false),
3807                handle.channel,
3808                handle.epoch,
3809                0,
3810                Vec::new(),
3811            )
3812            .expect("header-only route GOODBYE is valid");
3813            if self
3814                .writer
3815                .as_ref()
3816                .unwrap()
3817                .try_send(WriteCommand {
3818                    frame,
3819                    pending: None,
3820                })
3821                .is_ok()
3822            {
3823                return true;
3824            }
3825        }
3826        // Once one retirement is waiting, later retirements join the same FIFO
3827        // rather than overtaking it through the synchronous fast path.
3828        if !self.retirement_queue.contains(&handle) {
3829            self.retirement_queue.push_back(handle);
3830        }
3831        self.retirement_notify.notify_one();
3832        false
3833    }
3834
3835    fn remove_pending(&mut self, key: &PendingKey) -> Option<PendingEntry> {
3836        let entry = self.pending.remove(key);
3837        if entry.as_ref().is_some_and(|entry| !entry.accepted) {
3838            if let Some(slot) = self.wire_slots.remove(key) {
3839                slot.release();
3840            }
3841        }
3842        self.reap_retired_route(RouteHandle::new(key.channel, key.epoch, key.generation));
3843        entry
3844    }
3845
3846    fn release_wire_slots(&mut self, handle: RouteHandle) {
3847        self.wire_slots.retain(|key, slot| {
3848            let keep = key.generation != handle.connection_token()
3849                || key.channel != handle.channel
3850                || key.epoch != handle.epoch;
3851            if !keep {
3852                slot.release();
3853            }
3854            keep
3855        });
3856    }
3857
3858    fn remove_route_by_handle(&mut self, handle: RouteHandle) -> Option<RouteState> {
3859        if let Some(key) = self.route_by_channel.get(&handle.channel).cloned() {
3860            let matches = self
3861                .routes
3862                .get(&key)
3863                .is_some_and(|route| route.handle == handle);
3864            debug_assert!(matches);
3865            if matches {
3866                return self.remove_route(&key);
3867            }
3868        }
3869        let route = self
3870            .one_shot_routes
3871            .get(&handle.channel)
3872            .is_some_and(|route| route.handle == handle)
3873            .then(|| self.one_shot_routes.remove(&handle.channel))
3874            .flatten();
3875        if let Some(route) = &route {
3876            release_reverse_request_registry(route.handle);
3877        }
3878        route
3879    }
3880
3881    fn drain_routes(&mut self) -> Vec<RouteState> {
3882        self.route_targets.clear();
3883        for (_, slot) in self.wire_slots.drain() {
3884            slot.release();
3885        }
3886        self.retirement_goodbyes.clear();
3887        self.retirement_queue.clear();
3888        if let Some(task) = self.retirement_task.take() {
3889            task.abort();
3890        }
3891        for handle in self.retired_routes.drain() {
3892            release_reverse_request_registry(handle);
3893        }
3894        self.route_by_channel.clear();
3895        let routes = self
3896            .routes
3897            .drain()
3898            .map(|(_, route)| route)
3899            .chain(self.one_shot_routes.drain().map(|(_, route)| route))
3900            .collect::<Vec<_>>();
3901        for route in &routes {
3902            release_reverse_request_registry(route.handle);
3903        }
3904        routes
3905    }
3906
3907    fn close_routes(&mut self) {
3908        self.push_event_receivers.clear();
3909        for route in self.drain_routes() {
3910            route.close();
3911        }
3912    }
3913}
3914
3915impl Shared {
3916    fn new(connection_file: PathBuf, opts: ConsumerOptions) -> Self {
3917        Self::with_transport(connection_file, opts, ConsumerTransport::Tcp)
3918    }
3919
3920    fn with_transport(
3921        connection_file: PathBuf,
3922        opts: ConsumerOptions,
3923        transport: ConsumerTransport,
3924    ) -> Self {
3925        Self {
3926            claim_bound: crate::registration::bound(),
3927            connection_file,
3928            operator_app_candidates: None,
3929            opts,
3930            transport,
3931            identity_from_environment: true,
3932            inner: Mutex::new(Inner {
3933                generation: 1,
3934                daemon_origin_trusted: false,
3935                daemon_ver: String::new(),
3936                accepts_close_reasons: None,
3937                epoch: 1,
3938                next_corr: Some(1),
3939                writer: None,
3940                pending: HashMap::new(),
3941                wire_slots: HashMap::new(),
3942                routes: HashMap::new(),
3943                route_by_channel: HashMap::new(),
3944                one_shot_routes: HashMap::new(),
3945                route_epochs: HashMap::new(),
3946                route_targets: HashMap::new(),
3947                retired_routes: HashSet::new(),
3948                retirement_goodbyes: HashSet::new(),
3949                retirement_queue: VecDeque::new(),
3950                retirement_notify: Arc::new(Notify::new()),
3951                retirement_task: None,
3952                route_modules: HashMap::new(),
3953                route_end_reasons: HashMap::new(),
3954                legacy_channel_reasons: HashMap::new(),
3955                push_event_receivers: HashMap::new(),
3956                control_push_receiver: None,
3957                dropped_route_frames: 0,
3958                openings: HashMap::new(),
3959                callbacks: Vec::new(),
3960                closed: false,
3961                reconnect: ReconnectState::Idle,
3962                restored_token: 0,
3963                reader_task: None,
3964                writer_task: None,
3965            }),
3966            notify: Notify::new(),
3967            #[cfg(test)]
3968            before_wait: Mutex::new(None),
3969            close_token: CancellationToken::new(),
3970            last_inbound_ms: AtomicU64::new(0),
3971            liveness_probe_running: AtomicBool::new(false),
3972            pushes_dropped_no_receiver: AtomicU64::new(0),
3973            control_pushes_dropped: AtomicU64::new(0),
3974            pushes_dropped_receiver_full: AtomicU64::new(0),
3975            random_unit: Box::new(default_random_unit),
3976            route_open_slots: Semaphore::new(MAX_ROUTE_OPENS_IN_FLIGHT),
3977            route_description: tokio::sync::Mutex::new(()),
3978        }
3979    }
3980
3981    /// "Equal jitter": keep half of `delay` and randomize the other half. Every
3982    /// route on a connection is closed together when its module drains, so
3983    /// without jitter they all retry in lock step and reach the daemon as one
3984    /// burst each round; reconnects after a daemon restart herd the same way.
3985    fn jittered(&self, delay: Duration) -> Duration {
3986        let unit = (self.random_unit)();
3987        let unit = if unit.is_finite() {
3988            unit.clamp(0.0, 1.0)
3989        } else {
3990            0.0
3991        };
3992        let half = delay / 2;
3993        half + half.mul_f64(unit)
3994    }
3995
3996    /// One route.open exchange, paced by [`MAX_ROUTE_OPENS_IN_FLIGHT`]. The
3997    /// wait for a free slot ends at `deadline` like the exchange itself.
3998    async fn paced_route_open(
3999        self: &Arc<Self>,
4000        body: Vec<u8>,
4001        deadline: Instant,
4002        reverse_requests: Option<ReverseRequestRegistry>,
4003    ) -> Result<TerminalFrame, CallError> {
4004        let _slot = match timeout_at(deadline, self.route_open_slots.acquire()).await {
4005            Ok(Ok(permit)) => permit,
4006            Ok(Err(_)) => return Err(CallError::not_sent("consumer closed")),
4007            Err(_) => {
4008                return Err(CallError::not_sent(format!(
4009                    "deadline elapsed waiting for one of {MAX_ROUTE_OPENS_IN_FLIGHT} route.open slots"
4010                )));
4011            }
4012        };
4013        self.control_call(body, deadline, true, reverse_requests)
4014            .await
4015    }
4016
4017    fn lock_inner(&self) -> MutexGuard<'_, Inner> {
4018        self.inner
4019            .lock()
4020            .unwrap_or_else(|poisoned| poisoned.into_inner())
4021    }
4022
4023    fn install_initial(self: &Arc<Self>, opened: OpenedConnection) -> Result<(), ConsumerError> {
4024        self.install_connection(opened, InstallKind::Initial)
4025            .map(|_| ())
4026    }
4027
4028    fn install_reconnected(
4029        self: &Arc<Self>,
4030        opened: OpenedConnection,
4031    ) -> Result<(u64, u64), ConsumerError> {
4032        let generation_epoch = self.install_connection(opened, InstallKind::Reconnect)?;
4033        self.notify.notify_waiters();
4034        Ok(generation_epoch)
4035    }
4036
4037    fn install_connection(
4038        self: &Arc<Self>,
4039        opened: OpenedConnection,
4040        kind: InstallKind,
4041    ) -> Result<(u64, u64), ConsumerError> {
4042        if self.close_token.is_cancelled() {
4043            return Err(ConsumerError::Closed);
4044        }
4045
4046        let (reader, writer) = tokio::io::split(opened.stream);
4047        let (tx, rx) = mpsc::channel(EGRESS_BUFFER);
4048        let (generation, epoch, old_reader, old_writer) = {
4049            let mut inner = self.lock_inner();
4050            if inner.closed {
4051                return Err(ConsumerError::Closed);
4052            }
4053            let (generation, epoch) = match kind {
4054                InstallKind::Initial => (inner.generation, inner.epoch),
4055                InstallKind::Reconnect => {
4056                    inner.generation = inner
4057                        .generation
4058                        .checked_add(1)
4059                        .ok_or(ConsumerError::Closed)?;
4060                    inner.epoch = inner.epoch.checked_add(1).ok_or(ConsumerError::Closed)?;
4061                    (inner.generation, inner.epoch)
4062                }
4063            };
4064            inner.close_routes();
4065            inner.route_epochs.clear();
4066            inner.route_targets.clear();
4067            inner.route_modules.clear();
4068            inner.route_end_reasons.clear();
4069            inner.legacy_channel_reasons.clear();
4070            inner.next_corr = Some(1);
4071            inner.writer = Some(tx);
4072            inner.daemon_origin_trusted = opened.daemon_origin_trusted;
4073            inner.daemon_ver = opened.daemon_ver;
4074            inner.accepts_close_reasons = None;
4075            self.last_inbound_ms.store(0, Ordering::Release);
4076            (
4077                generation,
4078                epoch,
4079                inner.reader_task.take(),
4080                inner.writer_task.take(),
4081            )
4082        };
4083
4084        if let Some(handle) = old_reader {
4085            handle.abort();
4086        }
4087        if let Some(handle) = old_writer {
4088            handle.abort();
4089        }
4090
4091        let reader_shared = Arc::clone(self);
4092        let reader_task = tokio::spawn(async move {
4093            reader_loop(reader_shared, reader, generation).await;
4094        });
4095        let writer_shared = Arc::clone(self);
4096        let writer_task = tokio::spawn(async move {
4097            writer_loop(writer_shared, writer, rx, generation).await;
4098        });
4099
4100        {
4101            let mut inner = self.lock_inner();
4102            if inner.closed || inner.generation != generation {
4103                reader_task.abort();
4104                writer_task.abort();
4105                return Err(ConsumerError::Closed);
4106            }
4107            inner.reader_task = Some(reader_task);
4108            inner.writer_task = Some(writer_task);
4109            let retirement_shared = Arc::clone(self);
4110            let retirement_notify = Arc::clone(&inner.retirement_notify);
4111            inner.retirement_task = Some(tokio::spawn(async move {
4112                retirement_goodbye_loop(retirement_shared, generation, retirement_notify).await;
4113            }));
4114        }
4115
4116        Ok((generation, epoch))
4117    }
4118
4119    async fn ensure_connected_for_call(
4120        self: &Arc<Self>,
4121        deadline: Instant,
4122    ) -> Result<(), CallError> {
4123        loop {
4124            if Instant::now() >= deadline {
4125                return Err(CallError::not_sent(
4126                    "call deadline elapsed waiting for reconnection",
4127                ));
4128            }
4129            // Created BEFORE the state is read, and that ordering is the fix.
4130            // Reconnect completion wakes waiters with `notify_waiters()`, which
4131            // reaches only `Notified` futures that already exist and stores no
4132            // permit. A future created after the lock is released misses a
4133            // reconnect that finishes in between, and the caller then sleeps
4134            // until its deadline on a healthy connection. (`enable()` is kept
4135            // for `notify_one` semantics; for `notify_waiters` creation alone
4136            // is what registers the waiter.)
4137            let notified = self.notify.notified();
4138            tokio::pin!(notified);
4139            let action = {
4140                let mut inner = self.lock_inner();
4141                notified.as_mut().enable();
4142                if inner.closed {
4143                    return Err(CallError::not_sent("consumer closed"));
4144                }
4145                if inner.writer.is_some() {
4146                    return Ok(());
4147                }
4148                let generation = inner.generation;
4149                let reconnect_is_live = match &inner.reconnect {
4150                    ReconnectState::Idle => false,
4151                    ReconnectState::Inline { generation: active } => *active == generation,
4152                    ReconnectState::Background {
4153                        generation: active,
4154                        task,
4155                    } => *active == generation && !task.is_finished(),
4156                };
4157                if reconnect_is_live {
4158                    EnsureAction::Wait
4159                } else {
4160                    let stale_task =
4161                        match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4162                            ReconnectState::Background { task, .. } => Some(task),
4163                            ReconnectState::Idle | ReconnectState::Inline { .. } => None,
4164                        };
4165                    inner.reconnect = ReconnectState::Inline { generation };
4166                    EnsureAction::Lead {
4167                        generation,
4168                        stale_task,
4169                    }
4170                }
4171            };
4172
4173            match action {
4174                EnsureAction::Wait => {
4175                    #[cfg(test)]
4176                    {
4177                        let hook = self.before_wait.lock().unwrap().take();
4178                        if let Some(hook) = hook {
4179                            hook();
4180                        }
4181                    }
4182                    timeout_at(deadline, notified).await.map_err(|_| {
4183                        CallError::not_sent("call deadline elapsed waiting for reconnection")
4184                    })?;
4185                }
4186                EnsureAction::Lead {
4187                    generation,
4188                    stale_task,
4189                } => {
4190                    if let Some(handle) = stale_task {
4191                        handle.abort();
4192                    }
4193                    let mut guard = InlineReconnectGuard::new(Arc::clone(self), generation);
4194                    let result = timeout_at(deadline, self.reconnect_with_retry(generation)).await;
4195                    guard.finish();
4196                    return match result {
4197                        Ok(Ok(())) => Ok(()),
4198                        Ok(Err(err)) => Err(CallError::not_sent(err.to_string())),
4199                        Err(_) => Err(CallError::not_sent(
4200                            "call deadline elapsed waiting for reconnection",
4201                        )),
4202                    };
4203                }
4204            }
4205        }
4206    }
4207
4208    fn spawn_reconnect(self: &Arc<Self>, generation: u64) -> bool {
4209        // Reconnect ownership is fenced by the dropped transport generation. A
4210        // newer drop replaces an older attempt instead of letting that attempt
4211        // block recovery for the newer transport.
4212        let stale_task = {
4213            let mut inner = self.lock_inner();
4214            if inner.closed || inner.writer.is_some() || inner.generation != generation {
4215                return false;
4216            }
4217            let should_spawn = match &inner.reconnect {
4218                ReconnectState::Idle => true,
4219                ReconnectState::Inline { generation: active } => *active < generation,
4220                ReconnectState::Background {
4221                    generation: active,
4222                    task,
4223                } => *active < generation || (*active == generation && task.is_finished()),
4224            };
4225            if !should_spawn {
4226                return false;
4227            }
4228
4229            let stale_task = match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4230                ReconnectState::Background { task, .. } => Some(task),
4231                ReconnectState::Idle | ReconnectState::Inline { .. } => None,
4232            };
4233            let shared = Arc::clone(self);
4234            let handle = tokio::spawn(async move {
4235                let _result = shared.reconnect_with_retry(generation).await;
4236                shared.finish_background_reconnect(generation);
4237            });
4238            inner.reconnect = ReconnectState::Background {
4239                generation,
4240                task: handle,
4241            };
4242            stale_task
4243        };
4244        if let Some(handle) = stale_task {
4245            handle.abort();
4246        }
4247        true
4248    }
4249
4250    async fn reconnect_with_retry(
4251        self: &Arc<Self>,
4252        reconnect_generation: u64,
4253    ) -> Result<(), ConsumerError> {
4254        let mut last_error: Option<ConsumerError> = None;
4255        for attempt in 1..=self.opts.reconnect_backoff.max_attempts {
4256            if self.close_token.is_cancelled() {
4257                return Err(ConsumerError::Closed);
4258            }
4259            if !self.reconnect_attempt_is_current(reconnect_generation) {
4260                return Ok(());
4261            }
4262
4263            match open_connection(
4264                &self.connection_file,
4265                self.opts.handshake_timeout,
4266                self.transport,
4267                self.operator_app_candidates.as_deref(),
4268            )
4269            .await
4270            {
4271                Ok(opened) => {
4272                    // A newer drop may have installed its own attempt while this
4273                    // connection was opening. Do not let the stale attempt replace it.
4274                    if !self.reconnect_attempt_is_current(reconnect_generation) {
4275                        return Ok(());
4276                    }
4277                    let (generation, epoch) = self.install_reconnected(opened)?;
4278                    self.schedule_restored(generation, epoch);
4279                    return Ok(());
4280                }
4281                Err(err) => {
4282                    let transient = is_reconnect_transient(&err);
4283                    last_error = Some(err);
4284                    if !transient || attempt >= self.opts.reconnect_backoff.max_attempts {
4285                        break;
4286                    }
4287                    // Jittered like the route.open retries, which share this backoff.
4288                    let delay =
4289                        self.jittered(self.opts.reconnect_backoff.delay_after_attempt(attempt));
4290                    tokio::select! {
4291                        () = self.close_token.cancelled() => return Err(ConsumerError::Closed),
4292                        () = sleep(delay) => {}
4293                    }
4294                }
4295            }
4296        }
4297        Err(last_error.unwrap_or(ConsumerError::Closed))
4298    }
4299
4300    fn reconnect_attempt_is_current(&self, generation: u64) -> bool {
4301        let inner = self.lock_inner();
4302        !inner.closed
4303            && inner.writer.is_none()
4304            && inner.generation == generation
4305            && matches!(
4306                &inner.reconnect,
4307                ReconnectState::Inline { generation: active }
4308                    | ReconnectState::Background {
4309                        generation: active,
4310                        ..
4311                    } if *active == generation
4312            )
4313    }
4314
4315    fn finish_inline_reconnect(&self, generation: u64) {
4316        let finished = {
4317            let mut inner = self.lock_inner();
4318            if matches!(
4319                &inner.reconnect,
4320                ReconnectState::Inline { generation: active } if *active == generation
4321            ) {
4322                inner.reconnect = ReconnectState::Idle;
4323                true
4324            } else {
4325                false
4326            }
4327        };
4328        if finished {
4329            self.notify.notify_waiters();
4330        }
4331    }
4332
4333    fn finish_background_reconnect(&self, generation: u64) {
4334        let completed_task = {
4335            let mut inner = self.lock_inner();
4336            if !matches!(
4337                &inner.reconnect,
4338                ReconnectState::Background { generation: active, .. } if *active == generation
4339            ) {
4340                None
4341            } else {
4342                match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4343                    ReconnectState::Background { task, .. } => Some(task),
4344                    ReconnectState::Idle | ReconnectState::Inline { .. } => unreachable!(),
4345                }
4346            }
4347        };
4348        if completed_task.is_some() {
4349            drop(completed_task);
4350            self.notify.notify_waiters();
4351        }
4352    }
4353
4354    fn schedule_restored(self: &Arc<Self>, generation: u64, epoch: u64) {
4355        let token = {
4356            let mut inner = self.lock_inner();
4357            inner.restored_token = inner.restored_token.saturating_add(1);
4358            inner.restored_token
4359        };
4360        let shared = Arc::clone(self);
4361        tokio::spawn(async move {
4362            tokio::select! {
4363                () = shared.close_token.cancelled() => {}
4364                () = sleep(shared.opts.restored_debounce) => {
4365                    let should_emit = {
4366                        let inner = shared.lock_inner();
4367                        !inner.closed
4368                            && inner.generation == generation
4369                            && inner.epoch == epoch
4370                            && inner.restored_token == token
4371                            && inner.writer.is_some()
4372                    };
4373                    if should_emit {
4374                        shared.emit_connection_state(ConnectionState::Restored { epoch });
4375                    }
4376                }
4377            }
4378        });
4379    }
4380
4381    fn install_one_shot_route(&self, route: RouteState) -> Result<(), CallError> {
4382        let handle = route.handle;
4383        let mut inner = self.lock_inner();
4384        if inner.closed || inner.generation != handle.connection_token() || inner.writer.is_none() {
4385            return Err(CallError::StaleRouteHandle(handle));
4386        }
4387        // The socket reader installs the handle for a route.open response before
4388        // the waiter resolves (so a request the provider sends right after the
4389        // bind is routed), so this route's own channel is normally present
4390        // already, holding exactly this handle. Only a different handle on the
4391        // channel is a collision.
4392        if inner
4393            .route_epochs
4394            .get(&handle.channel)
4395            .is_some_and(|existing| *existing != handle)
4396        {
4397            return Err(CallError::not_sent(
4398                "daemon returned a route channel already in use",
4399            ));
4400        }
4401        inner.one_shot_routes.insert(handle.channel, route);
4402        inner.route_epochs.insert(handle.channel, handle);
4403        Ok(())
4404    }
4405
4406    async fn ensure_route(
4407        self: &Arc<Self>,
4408        key: &RouteKey,
4409        route_open: &RouteOpenParams<'_>,
4410        opts: &CallOptions,
4411        call_deadline: Instant,
4412    ) -> Result<RouteState, CallError> {
4413        loop {
4414            let action = {
4415                let mut inner = self.lock_inner();
4416                if inner.closed {
4417                    return Err(CallError::not_sent("consumer closed"));
4418                }
4419                if let Some(route) = inner.routes.get(key) {
4420                    if route.handle.connection_token() == inner.generation && inner.writer.is_some()
4421                    {
4422                        return Ok(route.clone());
4423                    }
4424                }
4425                if let Some(opening) = inner.openings.get_mut(key) {
4426                    let (tx, rx) = oneshot::channel();
4427                    opening.waiters.push(tx);
4428                    RouteOpenAction::Wait(rx)
4429                } else {
4430                    inner.openings.insert(
4431                        key.clone(),
4432                        Opening {
4433                            waiters: Vec::new(),
4434                            closed: false,
4435                        },
4436                    );
4437                    RouteOpenAction::Lead
4438                }
4439            };
4440
4441            match action {
4442                RouteOpenAction::Wait(rx) => match timeout_at(call_deadline, rx).await {
4443                    Ok(Ok(Ok(route))) => return Ok(route),
4444                    Ok(Ok(Err(err))) => return Err(err.into_call_error()),
4445                    Ok(Err(_)) => continue,
4446                    Err(_) => {
4447                        return Err(CallError::not_sent_with_cause(
4448                            "call deadline elapsed waiting for route.open",
4449                            NotSentCause::RouteOpenAbandoned,
4450                        ));
4451                    }
4452                },
4453                RouteOpenAction::Lead => {
4454                    let mut guard = OpeningGuard::new(Arc::clone(self), key.clone());
4455                    let result = self
4456                        .open_route_with_retry(key, route_open, opts, call_deadline)
4457                        .await
4458                        .map_err(SharedCallFailure::from);
4459                    guard.finish(result.clone());
4460                    return result.map_err(SharedCallFailure::into_call_error);
4461                }
4462            }
4463        }
4464    }
4465
4466    async fn open_route_with_retry(
4467        self: &Arc<Self>,
4468        key: &RouteKey,
4469        route_open: &RouteOpenParams<'_>,
4470        opts: &CallOptions,
4471        call_deadline: Instant,
4472    ) -> Result<RouteState, CallError> {
4473        let route_deadline = (Instant::now() + opts.route_retry_deadline).min(call_deadline);
4474        let mut attempt = 0usize;
4475        // The retryable refusals seen so far. When the deadline ends the retries,
4476        // the caller gets the most informative of them rather than a bare
4477        // "deadline elapsed", so "the module was reloading" stays
4478        // distinguishable from "the connection failed".
4479        let mut refusals = RouteOpenRefusals::default();
4480        // An attempt that ends because the deadline passed hands back the kept
4481        // refusal. That covers an attempt that never left the client (NotSent)
4482        // and one the daemon received but had not answered by the deadline
4483        // (OutcomeUnknown with the Deadline cause): a busy daemon can answer
4484        // the final retry a few milliseconds late, and the refusals before it
4485        // still say why the route never opened. Dropping the unanswered
4486        // attempt's own outcome is safe: route.open requests are sent with
4487        // `retain_late_route_open`, so a late acceptance is closed again with
4488        // a GOODBYE instead of being handed to anyone.
4489        let expired = |err: CallError, refusals: &mut RouteOpenRefusals| {
4490            let ended_by_deadline =
4491                err.is_not_sent() || err.outcome_cause() == Some(OutcomeUnknownCause::Deadline);
4492            if ended_by_deadline && Instant::now() >= route_deadline {
4493                if let Some(refused) = std::mem::take(refusals).into_error(key.target_label()) {
4494                    return refused;
4495                }
4496            }
4497            err
4498        };
4499        loop {
4500            attempt = attempt.saturating_add(1);
4501            let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
4502                busy_refusals: Some(true),
4503                target: route_open.target.clone(),
4504                identity: route_open.identity.clone(),
4505                consumer_identity: route_open.consumer_identity.clone(),
4506                consumer_capabilities: route_open.consumer_capabilities.clone(),
4507                role_versions: route_open.role_versions.clone(),
4508                admission_facts: None,
4509                scope: route_open.scope.cloned(),
4510            })
4511            .map_err(|err| CallError::not_sent(format!("failed to encode route.open: {err}")))?;
4512            match self
4513                .paced_route_open(
4514                    body,
4515                    route_deadline,
4516                    Some(route_open.reverse_requests.clone()),
4517                )
4518                .await
4519            {
4520                Ok(TerminalFrame::Response {
4521                    generation, body, ..
4522                }) => {
4523                    let (response, _) = decode_route_open_response(&body).map_err(|err| {
4524                        CallError::not_sent_with_cause(
4525                            format!("failed to decode route.open response: {err}"),
4526                            NotSentCause::RouteOpenAbandoned,
4527                        )
4528                    })?;
4529                    let ClientControlResponse::RouteOpen {
4530                        route_channel,
4531                        route_epoch,
4532                        request_window,
4533                        watch_window,
4534                        ..
4535                    } = response
4536                    else {
4537                        return Err(CallError::not_sent_with_cause(
4538                            "route.open returned an unexpected control response",
4539                            NotSentCause::RouteOpenAbandoned,
4540                        ));
4541                    };
4542                    let handle = self
4543                        .ingress_handle(generation, route_channel, route_epoch)
4544                        .unwrap_or_else(|| {
4545                            RouteHandle::new_consumer(
4546                                route_channel,
4547                                route_epoch,
4548                                generation,
4549                                route_open.reverse_requests.clone(),
4550                            )
4551                        });
4552                    let route = RouteState::windows(handle, request_window, watch_window);
4553                    let install = {
4554                        let mut inner = self.lock_inner();
4555                        if inner.closed {
4556                            return Err(CallError::not_sent("consumer closed"));
4557                        }
4558                        // Close-beats-reopen guard: a close_route may have flipped this
4559                        // opening's `closed` flag WHILE this route.open was in flight. If
4560                        // so, close wins — do NOT cache the channel; GOODBYE it below and
4561                        // fail as NotSent (the route was closed before the open landed).
4562                        let closed_during_open = inner.openings.get(key).is_some_and(|o| o.closed);
4563                        if closed_during_open
4564                            || inner.generation != generation
4565                            || inner.writer.is_none()
4566                        {
4567                            RouteInstall::Discard {
4568                                closed: closed_during_open,
4569                            }
4570                        } else {
4571                            let cached = inner.cache_route(key.clone(), route.clone());
4572                            RouteInstall::Cached(cached)
4573                        }
4574                    };
4575                    match install {
4576                        RouteInstall::Cached(cached) => return Ok(cached),
4577                        RouteInstall::Discard { closed } => {
4578                            if closed {
4579                                // GOODBYE the channel we opened so the daemon/module don't
4580                                // leak it, then report the close as a NotSent failure.
4581                                self.send_route_goodbye(route.handle, true);
4582                                self.uninstall_route_handle(route.handle);
4583                                return Err(CallError::not_sent_with_cause(
4584                                    "route was closed before route.open completed",
4585                                    NotSentCause::RouteOpenAbandoned,
4586                                ));
4587                            }
4588                            // Stale generation / writer gone: fall through to retry.
4589                        }
4590                    }
4591                    self.sleep_until_retry(route_deadline, self.jittered(opts.route_retry.base))
4592                        .await?;
4593                }
4594                Ok(TerminalFrame::Error { body, .. }) => {
4595                    // The deadline is the ONLY binder for retryable refusals.
4596                    // An attempt cap used to share this condition, and because
4597                    // the capped backoff sums to seconds it strictly dominated
4598                    // the deadline — the advertised reload patience was never
4599                    // delivered, and module restarts whose reload exceeded a
4600                    // few seconds failed every managed caller. A restart
4601                    // legitimately keeps routes refused for about a minute;
4602                    // capped per-attempt backoff bounds pressure.
4603                    if !is_retryable_route_open_code(&body.code) {
4604                        return Err(CallError::route_open_refused(key.target_label(), body));
4605                    }
4606                    refusals.record(body);
4607                    if Instant::now() >= route_deadline {
4608                        // A refusal was just recorded, so the fallback is unreachable.
4609                        return Err(std::mem::take(&mut refusals)
4610                            .into_error(key.target_label())
4611                            .unwrap_or_else(|| {
4612                                CallError::not_sent("route.open retry deadline elapsed")
4613                            }));
4614                    }
4615                    let delay = self.jittered(opts.route_retry.delay_after_attempt(attempt));
4616                    if let Err(err) = self.sleep_until_retry(route_deadline, delay).await {
4617                        return Err(expired(err, &mut refusals));
4618                    }
4619                    continue;
4620                }
4621                Ok(TerminalFrame::StreamEnd) => {
4622                    return Err(CallError::not_sent_with_cause(
4623                        "route.open returned StreamEnd",
4624                        NotSentCause::RouteOpenAbandoned,
4625                    ));
4626                }
4627                Err(err) if err.is_not_sent() && Instant::now() < route_deadline => {
4628                    let delay = self.jittered(opts.route_retry.delay_after_attempt(attempt));
4629                    if let Err(err) = self.sleep_until_retry(route_deadline, delay).await {
4630                        return Err(expired(err, &mut refusals));
4631                    }
4632                }
4633                Err(err) => return Err(expired(err, &mut refusals)),
4634            }
4635        }
4636
4637        #[allow(unreachable_code)]
4638        Err(CallError::not_sent(format!(
4639            "route.open retry deadline elapsed for target {}",
4640            key.target_label()
4641        )))
4642    }
4643
4644    async fn sleep_until_retry(&self, deadline: Instant, delay: Duration) -> Result<(), CallError> {
4645        if Instant::now() >= deadline {
4646            return Err(CallError::not_sent("retry deadline elapsed"));
4647        }
4648        let bounded = delay.min(deadline.saturating_duration_since(Instant::now()));
4649        tokio::select! {
4650            () = self.close_token.cancelled() => Err(CallError::not_sent("consumer closed")),
4651            () = sleep(bounded) => Ok(()),
4652        }
4653    }
4654
4655    async fn control_call(
4656        self: &Arc<Self>,
4657        body: Vec<u8>,
4658        deadline: Instant,
4659        retain_late_route_open: bool,
4660        route_open_reverse_requests: Option<ReverseRequestRegistry>,
4661    ) -> Result<TerminalFrame, CallError> {
4662        self.ensure_connected_for_call(deadline).await?;
4663        if retain_late_route_open {
4664            {
4665                let inner = self.lock_inner();
4666                if !daemon_version_at_least(&inner.daemon_ver, (0, 39, 0)) {
4667                    return Err(CallError::DaemonTooOld {
4668                        daemon_ver: inner.daemon_ver.clone(),
4669                    });
4670                }
4671            }
4672            self.describe_route_close_reasons(deadline).await?;
4673        }
4674        self.send_request(RequestSend {
4675            binary: false,
4676            expected_handle: None,
4677            channel: 0,
4678            epoch: 0,
4679            body,
4680            priority: Priority::Interactive,
4681            admission_class: AdmissionClass::Normal,
4682            deadline,
4683            retain_late_route_open,
4684            route_open_reverse_requests,
4685        })
4686        .await
4687    }
4688
4689    async fn describe_route_close_reasons(
4690        self: &Arc<Self>,
4691        deadline: Instant,
4692    ) -> Result<(), CallError> {
4693        let _lookup = timeout_at(deadline, self.route_description.lock())
4694            .await
4695            .map_err(|_| CallError::not_sent("deadline waiting for server.describe"))?;
4696        loop {
4697            self.ensure_connected_for_call(deadline).await?;
4698            let generation = {
4699                let inner = self.lock_inner();
4700                if inner.accepts_close_reasons.is_some() {
4701                    return Ok(());
4702                }
4703                inner.generation
4704            };
4705            // Description is advisory. A refused, malformed or unanswered lookup
4706            // must not prevent opening routes to a daemon that predates the key.
4707            let reply = self
4708                .send_request(RequestSend {
4709                    binary: false,
4710                    expected_handle: None,
4711                    channel: 0,
4712                    epoch: 0,
4713                    body: br#"{"op":"server.describe"}"#.to_vec(),
4714                    priority: Priority::Interactive,
4715                    admission_class: AdmissionClass::Normal,
4716                    deadline: deadline.min(Instant::now() + CAPABILITY_PROBE_TIMEOUT),
4717                    retain_late_route_open: false,
4718                    route_open_reverse_requests: None,
4719                })
4720                .await;
4721            let supported = match reply {
4722                Ok(TerminalFrame::Response { body, .. }) => {
4723                    matches!(serde_json::from_slice::<ClientControlResponse>(&body),
4724                        Ok(ClientControlResponse::ServerDescribe { capabilities, .. })
4725                        if capabilities.iter().any(|cap| cap == ROUTE_CLOSE_REASONS_CAPABILITY))
4726                }
4727                _ => false,
4728            };
4729            let mut inner = self.lock_inner();
4730            if inner.generation == generation {
4731                inner.accepts_close_reasons = Some(supported);
4732                return Ok(());
4733            }
4734        }
4735    }
4736
4737    async fn send_request(
4738        self: &Arc<Self>,
4739        request: RequestSend,
4740    ) -> Result<TerminalFrame, CallError> {
4741        self.send_request_cancellable(request, None).await
4742    }
4743
4744    fn allocate_request(
4745        self: &Arc<Self>,
4746        expected_handle: Option<RouteHandle>,
4747        channel: u16,
4748        epoch: u32,
4749    ) -> Result<(PendingKey, mpsc::Sender<WriteCommand>), CallError> {
4750        let mut inner = self.lock_inner();
4751        if inner.closed {
4752            return Err(CallError::not_sent("consumer closed"));
4753        }
4754        let generation = inner.generation;
4755        if let Some(expected) = expected_handle {
4756            let route_pair_matches =
4757                channel == 0 || (expected.channel == channel && expected.epoch == epoch);
4758            if expected.connection_token() != generation
4759                || !route_pair_matches
4760                || inner.route_epochs.get(&expected.channel) != Some(&expected)
4761                || inner.retired_routes.contains(&expected)
4762            {
4763                return Err(CallError::StaleRouteHandle(expected));
4764            }
4765        }
4766        let Some(writer) = inner.writer.clone() else {
4767            return Err(CallError::not_sent("subc connection is down before send"));
4768        };
4769        let Some(corr) = inner.next_corr else {
4770            drop(inner);
4771            self.handle_generation_drop(
4772                generation,
4773                "channel-0 correlation allocator exhausted".to_string(),
4774            );
4775            return Err(CallError::not_sent(
4776                "correlation allocator exhausted; connection closed",
4777            ));
4778        };
4779        inner.next_corr = corr.checked_add(1);
4780        Ok((
4781            PendingKey {
4782                generation,
4783                channel,
4784                epoch,
4785                corr,
4786            },
4787            writer,
4788        ))
4789    }
4790
4791    async fn send_request_cancellable(
4792        self: &Arc<Self>,
4793        request: RequestSend,
4794        cancel: Option<Arc<UnaryCancel>>,
4795    ) -> Result<TerminalFrame, CallError> {
4796        self.send_request_with_slot(request, cancel, None).await
4797    }
4798
4799    async fn send_request_with_slot(
4800        self: &Arc<Self>,
4801        request: RequestSend,
4802        cancel: Option<Arc<UnaryCancel>>,
4803        slot: Option<Arc<RoutePermit>>,
4804    ) -> Result<TerminalFrame, CallError> {
4805        let RequestSend {
4806            expected_handle,
4807            channel,
4808            epoch,
4809            body,
4810            binary,
4811            priority,
4812            admission_class,
4813            deadline,
4814            retain_late_route_open,
4815            route_open_reverse_requests,
4816        } = request;
4817        if Instant::now() >= deadline {
4818            return Err(CallError::not_sent(
4819                "call deadline elapsed before request was sent",
4820            ));
4821        }
4822        let slot = match (slot, expected_handle) {
4823            (Some(slot), _) => Some(slot),
4824            (None, Some(handle)) if channel != 0 => match self.route_state(handle) {
4825                Ok(route) if route.opted_in => {
4826                    Some(route.acquire(false, deadline, cancel.as_ref()).await?)
4827                }
4828                _ => None,
4829            },
4830            (None, _) => None,
4831        };
4832        let (key, writer) = self.allocate_request(expected_handle, channel, epoch)?;
4833        let generation = key.generation;
4834
4835        let mut frame = Frame::build(
4836            FrameType::Request,
4837            Flags::new(binary, priority, false).with_admission_class(admission_class),
4838            channel,
4839            epoch,
4840            key.corr,
4841            body,
4842        )
4843        .map_err(|err| CallError::not_sent(format!("failed to build request frame: {err}")))?;
4844        let (tx, rx) = oneshot::channel();
4845        {
4846            let mut inner = self.lock_inner();
4847            if inner.closed || inner.generation != generation || inner.writer.is_none() {
4848                return Err(CallError::not_sent(
4849                    "connection changed before request registration",
4850                ));
4851            }
4852            // Check the version retained for the authenticated connection under
4853            // the same lock as registration, so reconnecting cannot send a
4854            // rootless identity after a check on a different connection.
4855            if retain_late_route_open && !daemon_version_at_least(&inner.daemon_ver, (0, 39, 0)) {
4856                return Err(CallError::DaemonTooOld {
4857                    daemon_ver: inner.daemon_ver.clone(),
4858                });
4859            }
4860            if retain_late_route_open {
4861                let supported = inner.accepts_close_reasons.ok_or_else(|| {
4862                    CallError::not_sent("connection changed before route.open capability discovery")
4863                })?;
4864                let mut body: serde_json::Value = serde_json::from_slice(&frame.body)
4865                    .map_err(|err| CallError::not_sent(format!("invalid route.open: {err}")))?;
4866                RouteOpenRequestExt::new()
4867                    .with_accepts_close_reasons(supported.then(|| {
4868                        ACCEPTED_CLOSE_REASONS
4869                            .iter()
4870                            .map(|reason| (*reason).to_string())
4871                            .collect()
4872                    }))
4873                    .write_to(&mut body)
4874                    .map_err(|err| CallError::not_sent(format!("invalid route.open: {err}")))?;
4875                frame = Frame::build(
4876                    FrameType::Request,
4877                    frame.header.flags,
4878                    channel,
4879                    epoch,
4880                    key.corr,
4881                    serde_json::to_vec(&body)
4882                        .map_err(|err| CallError::not_sent(err.to_string()))?,
4883                )
4884                .map_err(|err| CallError::not_sent(err.to_string()))?;
4885            }
4886            if let Some(expected) = expected_handle {
4887                if inner.route_epochs.get(&expected.channel) != Some(&expected)
4888                    || inner.retired_routes.contains(&expected)
4889                {
4890                    return Err(CallError::StaleRouteHandle(expected));
4891                }
4892            }
4893            let expected_control_handle = (channel == 0 && !retain_late_route_open)
4894                .then_some(expected_handle)
4895                .flatten();
4896            inner.pending.insert(
4897                key,
4898                PendingEntry::unary(
4899                    tx,
4900                    retain_late_route_open,
4901                    expected_control_handle,
4902                    route_open_reverse_requests,
4903                ),
4904            );
4905            if let Some(slot) = slot.filter(|slot| slot.opted_in()) {
4906                inner.wire_slots.insert(key, slot);
4907            }
4908            if retain_late_route_open {
4909                inner.pending.get_mut(&key).unwrap().route_open_module =
4910                    serde_json::from_slice::<serde_json::Value>(&frame.body)
4911                        .ok()
4912                        .and_then(|body| {
4913                            body.get("target")?
4914                                .get("module_id")?
4915                                .as_str()
4916                                .map(str::to_string)
4917                        });
4918            }
4919        }
4920        let mut registration =
4921            PendingRegistration::new(Arc::clone(self), key, retain_late_route_open);
4922        registration.unary_cancel = cancel.clone();
4923
4924        match timeout_at(
4925            deadline,
4926            writer.send(WriteCommand {
4927                frame,
4928                pending: Some(key),
4929            }),
4930        )
4931        .await
4932        {
4933            Ok(Ok(())) => {}
4934            Ok(Err(_)) => {
4935                let accepted = registration.remove_pending().unwrap_or(false);
4936                return Err(classify_failure(
4937                    accepted,
4938                    "writer task closed before accepting request",
4939                    OutcomeUnknownCause::WriterClosed,
4940                ));
4941            }
4942            Err(_) => {
4943                let accepted = registration.remove_pending().unwrap_or(false);
4944                return Err(classify_failure_with_not_sent_cause(
4945                    accepted,
4946                    "call deadline elapsed waiting for writer capacity",
4947                    OutcomeUnknownCause::Deadline,
4948                    NotSentCause::WriterCapacity,
4949                ));
4950            }
4951        }
4952
4953        if let Some(cancel) = cancel {
4954            cancel.activate(key, priority, deadline);
4955            if cancel.requested() {
4956                cancel.cancel().await;
4957            }
4958        }
4959
4960        self.wait_for_reply(registration, rx, deadline).await
4961    }
4962
4963    async fn wait_for_reply(
4964        self: &Arc<Self>,
4965        mut registration: PendingRegistration,
4966        rx: oneshot::Receiver<PendingResult>,
4967        deadline: Instant,
4968    ) -> Result<TerminalFrame, CallError> {
4969        let key = registration.key;
4970        let channel = key.channel;
4971        // After writer handoff, settle_pending, a connection drop or close_sync may already
4972        // have removed the entry and still be settling it. Its absence cannot prove that the
4973        // request was not written, so a missing entry is classified as possibly written.
4974        tokio::select! {
4975            result = timeout_at(deadline, rx) => match result {
4976                Ok(Ok(result)) => {
4977                    registration.disarm();
4978                    result.into_call_result()
4979                }
4980                Ok(Err(_)) => {
4981                    // The entry was settled without a result, so the request may already
4982                    // have been written: report the outcome as unknown, never `NotSent`.
4983                    registration.disarm();
4984                    Err(CallError::outcome_unknown(
4985                        "pending response channel closed",
4986                        OutcomeUnknownCause::CompletionFailed,
4987                    ))
4988                }
4989                Err(_) => {
4990                    let accepted = if registration.retain_on_drop {
4991                        registration.disarm();
4992                        self.pending_accepted(key).unwrap_or(true)
4993                    } else {
4994                        registration.remove_pending().unwrap_or(true)
4995                    };
4996                    if accepted {
4997                        // Removing the pending entry prevents an explicit cancel
4998                        // from queueing afterward. If it won that race, its sent
4999                        // state is already visible and the deadline sends nothing.
5000                        let cancel_sent = registration.unary_cancel.as_ref().is_some_and(|cancel| cancel.sent());
5001                        if !cancel_sent && self.lock_inner().wire_slots.contains_key(&key) {
5002                            self.send_cancel(RouteHandle::new(key.channel, key.epoch, key.generation), key.corr, Priority::Interactive);
5003                        }
5004                        self.spawn_liveness_probe();
5005                    }
5006                    Err(classify_failure(
5007                        accepted,
5008                        format!("request on channel {channel} timed out at its deadline"),
5009                        OutcomeUnknownCause::Deadline,
5010                    ))
5011                }
5012            },
5013            () = self.close_token.cancelled() => {
5014                let accepted = registration.remove_pending().unwrap_or(true);
5015                Err(classify_failure(accepted, "consumer closed while request was pending", OutcomeUnknownCause::ConsumerClosed))
5016            }
5017        }
5018    }
5019
5020    /// Probe a connection retained after an accepted request reaches its reply deadline.
5021    ///
5022    /// Deadline timeouts deliberately keep a connection because scheduler pressure can delay
5023    /// an otherwise healthy reply. A channel-0 Ping plus any later inbound frame separates that
5024    /// case from a half-open socket, which would otherwise pin every subsequent request.
5025    fn spawn_liveness_probe(self: &Arc<Self>) {
5026        if self.liveness_probe_running.swap(true, Ordering::AcqRel) {
5027            return;
5028        }
5029
5030        let allocation = {
5031            let mut inner = self.lock_inner();
5032            // A pending CHANNEL-0 request suspends the probe: the daemon's
5033            // connection loop is FIFO and some channel-0 handlers park it
5034            // inline for seconds (route.open awaits the module bind ack for up
5035            // to route_bind_relay_timeout, ~12s in production), during which
5036            // our Ping sits unread in the daemon's socket buffer. Silence is
5037            // then explained by our own control op, and convicting would tear
5038            // down a healthy connection mid-bind. The gate is local knowledge
5039            // (we always know our own pendings) and re-arms on the next
5040            // deadline settle; the same check runs again before conviction.
5041            let control_pending = inner
5042                .pending
5043                .keys()
5044                .any(|key| key.generation == inner.generation && key.channel == 0);
5045            if inner.closed || control_pending || !matches!(&inner.reconnect, ReconnectState::Idle)
5046            {
5047                None
5048            } else {
5049                match (inner.next_corr, inner.writer.clone()) {
5050                    (Some(corr), Some(writer)) => {
5051                        inner.next_corr = corr.checked_add(1);
5052                        Some((inner.generation, corr, writer))
5053                    }
5054                    (None, _) | (_, None) => None,
5055                }
5056            }
5057        };
5058        let Some((generation, corr, writer)) = allocation else {
5059            self.liveness_probe_running.store(false, Ordering::Release);
5060            return;
5061        };
5062
5063        let t0 = epoch_millis();
5064        let ping = match Frame::build(
5065            FrameType::Ping,
5066            Flags::new(false, Priority::Interactive, false),
5067            0,
5068            0,
5069            corr,
5070            Vec::new(),
5071        ) {
5072            Ok(ping) => ping,
5073            Err(_) => {
5074                self.liveness_probe_running.store(false, Ordering::Release);
5075                return;
5076            }
5077        };
5078        let window = self.opts.liveness_probe_window;
5079        let shared = Arc::clone(self);
5080        tokio::spawn(async move {
5081            let window_end = Instant::now() + window;
5082            // A write failure proves nothing in the healthy direction: it may be the
5083            // first sign of the same broken transport. Let the inbound window decide.
5084            let _ = timeout_at(
5085                window_end,
5086                writer.send(WriteCommand {
5087                    frame: ping,
5088                    pending: None,
5089                }),
5090            )
5091            .await;
5092            sleep_until(window_end).await;
5093
5094            let control_pending_now = {
5095                let inner = shared.lock_inner();
5096                inner
5097                    .pending
5098                    .keys()
5099                    .any(|key| key.generation == generation && key.channel == 0)
5100            };
5101            if !shared.close_token.is_cancelled()
5102                && !control_pending_now // a control op begun during the window explains the silence
5103                && shared.generation_is_current(generation)
5104                && shared.last_inbound_ms.load(Ordering::Acquire) < t0
5105            {
5106                shared.handle_generation_drop(
5107                    generation,
5108                    format!(
5109                        "liveness probe convicted a half-open socket: no inbound frame for {}ms after a channel-0 Ping",
5110                        window.as_millis()
5111                    ),
5112                );
5113            }
5114            shared
5115                .liveness_probe_running
5116                .store(false, Ordering::Release);
5117        });
5118    }
5119
5120    async fn send_subscription(
5121        self: &Arc<Self>,
5122        subscription: SubscriptionSend,
5123    ) -> Result<Subscription, CallError> {
5124        let SubscriptionSend {
5125            expected_handle,
5126            channel,
5127            epoch,
5128            body,
5129            priority,
5130            admission_class,
5131            event_buffer,
5132            deadline,
5133            permit,
5134        } = subscription;
5135        if Instant::now() >= deadline {
5136            return Err(CallError::not_sent(
5137                "subscription deadline elapsed before request was sent",
5138            ));
5139        }
5140        let (generation, corr, writer) = {
5141            let mut inner = self.lock_inner();
5142            if inner.closed {
5143                return Err(CallError::not_sent("consumer closed"));
5144            }
5145            let generation = inner.generation;
5146            if let Some(expected) = expected_handle {
5147                if expected.connection_token() != generation
5148                    || expected.channel != channel
5149                    || expected.epoch != epoch
5150                    || inner.route_epochs.get(&channel) != Some(&expected)
5151                    || inner.retired_routes.contains(&expected)
5152                {
5153                    return Err(CallError::StaleRouteHandle(expected));
5154                }
5155            }
5156            let Some(writer) = inner.writer.clone() else {
5157                return Err(CallError::not_sent("subc connection is down before send"));
5158            };
5159            let Some(corr) = inner.next_corr else {
5160                drop(inner);
5161                self.handle_generation_drop(
5162                    generation,
5163                    "correlation allocator exhausted".to_string(),
5164                );
5165                return Err(CallError::not_sent(
5166                    "correlation allocator exhausted; connection closed",
5167                ));
5168            };
5169            inner.next_corr = corr.checked_add(1);
5170            (generation, corr, writer)
5171        };
5172
5173        // Mark held subscriptions so module drains leave them out of the quiescence wait.
5174        let frame = Frame::build(
5175            FrameType::Request,
5176            Flags(
5177                Flags::new(false, priority, false)
5178                    .with_admission_class(admission_class)
5179                    .0
5180                    | FLAG_SUBSCRIPTION,
5181            ),
5182            channel,
5183            epoch,
5184            corr,
5185            body,
5186        )
5187        .map_err(|err| CallError::not_sent(format!("failed to build request frame: {err}")))?;
5188        let key = PendingKey {
5189            generation,
5190            channel,
5191            epoch,
5192            corr,
5193        };
5194        let position = Arc::new(SubscriptionPosition {
5195            key: Mutex::new(key),
5196            stop: CancellationToken::new(),
5197        });
5198        let retry = permit.opted_in().then(|| SubscriptionRetry {
5199            frame: frame.clone(),
5200            deadline,
5201            delay: Duration::from_millis(25),
5202            position: Arc::clone(&position),
5203        });
5204        let (events_tx, events_rx) = mpsc::channel(event_buffer.max(1));
5205        let (closed_tx, closed_rx) = oneshot::channel();
5206        let (ended_tx, ended_rx) = watch::channel(None);
5207        {
5208            let mut inner = self.lock_inner();
5209            if inner.closed || inner.generation != generation || inner.writer.is_none() {
5210                return Err(CallError::not_sent(
5211                    "connection changed before subscription registration",
5212                ));
5213            }
5214            if let Some(expected) = expected_handle {
5215                if inner.route_epochs.get(&expected.channel) != Some(&expected)
5216                    || inner.retired_routes.contains(&expected)
5217                {
5218                    return Err(CallError::StaleRouteHandle(expected));
5219                }
5220            }
5221            if permit.opted_in() {
5222                inner.wire_slots.insert(key, Arc::clone(&permit));
5223            }
5224            let mut entry =
5225                PendingEntry::subscription(events_tx, closed_tx, ended_tx, permit, priority);
5226            entry.retry = retry;
5227            inner.pending.insert(key, entry);
5228        }
5229        let mut registration = PendingRegistration::new(Arc::clone(self), key, false);
5230
5231        match timeout_at(
5232            deadline,
5233            writer.send(WriteCommand {
5234                frame,
5235                pending: Some(key),
5236            }),
5237        )
5238        .await
5239        {
5240            Ok(Ok(())) => {}
5241            Ok(Err(_)) => {
5242                let accepted = registration.remove_pending().unwrap_or(false);
5243                return Err(classify_failure(
5244                    accepted,
5245                    "writer task closed before accepting subscription request",
5246                    OutcomeUnknownCause::WriterClosed,
5247                ));
5248            }
5249            Err(_) => {
5250                let accepted = registration.remove_pending().unwrap_or(false);
5251                return Err(classify_failure_with_not_sent_cause(
5252                    accepted,
5253                    "subscription deadline elapsed waiting for writer capacity",
5254                    OutcomeUnknownCause::Deadline,
5255                    NotSentCause::WriterCapacity,
5256                ));
5257            }
5258        }
5259
5260        registration.disarm();
5261        Ok(Subscription {
5262            events: events_rx,
5263            closed: SubscriptionClosed { rx: closed_rx },
5264            ended: ended_rx,
5265            cancel: SubscriptionCancel::new(Arc::clone(self), position, priority),
5266        })
5267    }
5268
5269    fn unsubscribe_subscription(
5270        &self,
5271        position: &SubscriptionPosition,
5272        priority: Priority,
5273    ) -> Result<(), CallError> {
5274        let key = *position.key.lock().unwrap_or_else(|err| err.into_inner());
5275        let handle = RouteHandle::new(key.channel, key.epoch, key.generation);
5276        self.validate_current_handle(handle)?;
5277        let (key, entry) = {
5278            let mut inner = self.lock_inner();
5279            let key = *position.key.lock().unwrap_or_else(|err| err.into_inner());
5280            position.stop.cancel();
5281            let entry = inner.pending.remove(&key);
5282            if entry.as_ref().is_some_and(|entry| !entry.accepted) {
5283                if let Some(slot) = inner.wire_slots.remove(&key) {
5284                    slot.release();
5285                }
5286            }
5287            // Keep retired-route ingress until its advisory Cancel is queued.
5288            (key, entry)
5289        };
5290        if let Some(entry) = entry {
5291            let should_cancel = entry.accepted || entry.retry.is_none();
5292            entry.settle_subscription_result(Ok(()));
5293            if should_cancel {
5294                self.send_cancel(handle, key.corr, priority);
5295            }
5296            self.lock_inner().reap_retired_route(handle);
5297        }
5298        Ok(())
5299    }
5300
5301    fn route_stream_data(&self, key: PendingKey, body: Vec<u8>) {
5302        let overflow = {
5303            let mut inner = self.lock_inner();
5304            let Some(entry) = inner.pending.get(&key) else {
5305                return;
5306            };
5307            match entry.try_send_stream_data(body) {
5308                Ok(()) | Err(StreamDataDelivery::NotSubscription) => return,
5309                Err(StreamDataDelivery::Full) => {
5310                    let priority = entry
5311                        .subscription_priority()
5312                        .unwrap_or(Priority::Interactive);
5313                    let entry = inner.pending.remove(&key);
5314                    entry.map(|entry| {
5315                        (
5316                            entry,
5317                            priority,
5318                            "subscription event channel filled; reader dropped the stream instead of blocking",
5319                        )
5320                    })
5321                }
5322                Err(StreamDataDelivery::Closed) => {
5323                    let priority = entry
5324                        .subscription_priority()
5325                        .unwrap_or(Priority::Interactive);
5326                    let entry = inner.pending.remove(&key);
5327                    entry.map(|entry| {
5328                        (
5329                            entry,
5330                            priority,
5331                            "subscription event receiver closed before the stream ended",
5332                        )
5333                    })
5334                }
5335            }
5336        };
5337
5338        if let Some((entry, priority, reason)) = overflow {
5339            entry.settle_call_error(CallError::subscription_backpressure(reason));
5340            self.send_cancel(
5341                RouteHandle::new(key.channel, key.epoch, key.generation),
5342                key.corr,
5343                priority,
5344            );
5345            self.lock_inner().reap_retired_route(RouteHandle::new(
5346                key.channel,
5347                key.epoch,
5348                key.generation,
5349            ));
5350        }
5351    }
5352
5353    fn register_push_events(
5354        &self,
5355        handle: RouteHandle,
5356    ) -> Result<mpsc::Receiver<PushEvent>, CallError> {
5357        let (events_tx, events_rx) = mpsc::channel(DEFAULT_PUSH_EVENT_BUFFER);
5358        let mut inner = self.lock_inner();
5359        if inner.closed
5360            || inner.generation != handle.connection_token()
5361            || inner.writer.is_none()
5362            || inner.route_epochs.get(&handle.channel) != Some(&handle)
5363        {
5364            return Err(CallError::StaleRouteHandle(handle));
5365        }
5366        inner.push_event_receivers.insert(handle, events_tx);
5367        Ok(events_rx)
5368    }
5369
5370    fn route_push(&self, handle: RouteHandle, body: Vec<u8>) {
5371        let should_count_drop = {
5372            let mut inner = self.lock_inner();
5373            if inner.closed
5374                || inner.generation != handle.connection_token()
5375                || inner.route_epochs.get(&handle.channel) != Some(&handle)
5376            {
5377                // Deliberately uncounted: a push against a stale epoch or dead
5378                // generation has no live subscriber by definition, and the
5379                // counters below claim delivery loss on LIVE routes only.
5380                return;
5381            }
5382            match inner.push_event_receivers.get(&handle) {
5383                None => DroppedPush::NoReceiver,
5384                Some(events) => match events.try_send(PushEvent { handle, body }) {
5385                    Ok(()) => DroppedPush::Delivered,
5386                    Err(mpsc::error::TrySendError::Closed(_)) => {
5387                        inner.push_event_receivers.remove(&handle);
5388                        DroppedPush::NoReceiver
5389                    }
5390                    // A burst KEEPS the subscription (issue #40). This used to
5391                    // remove the receiver -- documented as loss-signaling via
5392                    // recv()->None -- but the fleet's real push consumers are
5393                    // idempotent wake nudges, where one missed event costs a
5394                    // poll cycle and a lost subscription costs every later wake
5395                    // until a re-register path that history says is where bugs
5396                    // live. Matches control_push below; the drop is counted on
5397                    // its own counter so a too-slow consumer is diagnosable as
5398                    // such rather than filed under "never subscribed".
5399                    Err(mpsc::error::TrySendError::Full(_)) => DroppedPush::ReceiverFull,
5400                },
5401            }
5402        };
5403        match should_count_drop {
5404            DroppedPush::Delivered => {}
5405            DroppedPush::NoReceiver => {
5406                self.pushes_dropped_no_receiver
5407                    .fetch_add(1, Ordering::Relaxed);
5408            }
5409            DroppedPush::ReceiverFull => {
5410                self.pushes_dropped_receiver_full
5411                    .fetch_add(1, Ordering::Relaxed);
5412            }
5413        }
5414    }
5415
5416    /// Deliver a daemon-originated channel-0 control push to the registered
5417    /// consumer receiver, or count the drop. Never blocks the reader.
5418    fn control_push(&self, body: &[u8]) {
5419        let parsed = serde_json::from_slice::<serde_json::Value>(body)
5420            .ok()
5421            .and_then(|value| {
5422                let op = value.get("op")?.as_str()?.to_string();
5423                Some(ControlPush { op, body: value })
5424            });
5425        let delivered = match parsed {
5426            None => false,
5427            Some(push) => {
5428                let mut inner = self.lock_inner();
5429                inner.record_route_end(&push);
5430                match inner.control_push_receiver.as_ref() {
5431                    None => false,
5432                    Some(sender) => match sender.try_send(push) {
5433                        Ok(()) => true,
5434                        Err(mpsc::error::TrySendError::Closed(_)) => {
5435                            inner.control_push_receiver = None;
5436                            false
5437                        }
5438                        Err(mpsc::error::TrySendError::Full(_)) => false,
5439                    },
5440                }
5441            }
5442        };
5443        if !delivered {
5444            self.control_pushes_dropped.fetch_add(1, Ordering::Relaxed);
5445        }
5446    }
5447
5448    fn send_cancel(&self, handle: RouteHandle, corr: u64, priority: Priority) {
5449        let writer = {
5450            let inner = self.lock_inner();
5451            if inner.closed
5452                || inner.generation != handle.connection_token()
5453                || !route_is_installed(&inner, handle)
5454            {
5455                return;
5456            }
5457            inner.writer.clone()
5458        };
5459        let Some(writer) = writer else {
5460            return;
5461        };
5462        let Ok(frame) = Frame::build(
5463            FrameType::Cancel,
5464            Flags::new(false, priority, false),
5465            handle.channel,
5466            handle.epoch,
5467            corr,
5468            Vec::new(),
5469        ) else {
5470            return;
5471        };
5472        let _ = writer.try_send(WriteCommand {
5473            frame,
5474            pending: None,
5475        });
5476    }
5477
5478    fn mark_pending_accepted(&self, key: PendingKey) -> bool {
5479        let mut inner = self.lock_inner();
5480        if inner.closed || inner.generation != key.generation {
5481            return false;
5482        }
5483        let Some(entry) = inner.pending.get_mut(&key) else {
5484            return false;
5485        };
5486        if entry
5487            .send_deadline
5488            .is_some_and(|deadline| Instant::now() >= deadline)
5489        {
5490            let entry = inner.remove_pending(&key).unwrap();
5491            drop(inner);
5492            entry.settle_call_error(CallError::not_sent_with_cause(
5493                "call deadline elapsed before request was sent",
5494                NotSentCause::WriterRejected,
5495            ));
5496            return false;
5497        }
5498        entry.accepted = true;
5499        true
5500    }
5501
5502    fn settle_pending(self: &Arc<Self>, key: PendingKey, terminal: PendingTerminal) {
5503        let (entry, retry) = {
5504            let mut inner = self.lock_inner();
5505            let entry = inner.remove_pending(&key);
5506            let slot = inner.wire_slots.remove(&key);
5507            let busy = matches!(&terminal, PendingTerminal::Error { body, flags }
5508                if error_codes::is_route_busy_retryable(*flags, &body.code, slot.as_ref().is_some_and(|slot| slot.opted_in())))
5509                && entry
5510                    .as_ref()
5511                    .is_some_and(|entry| !entry.completion_is_closed());
5512            if let Some(slot) = slot {
5513                if !busy {
5514                    slot.release();
5515                }
5516            }
5517            if busy && entry.as_ref().is_some_and(|entry| entry.retry.is_some()) {
5518                let mut entry = entry.unwrap();
5519                entry.accepted = false;
5520                let retry = entry.retry.clone();
5521                inner.pending.insert(key, entry);
5522                (None, retry)
5523            } else {
5524                inner.reap_retired_route(RouteHandle::new(key.channel, key.epoch, key.generation));
5525                (entry, None)
5526            }
5527        };
5528        if let Some(retry) = retry {
5529            let shared = Arc::clone(self);
5530            tokio::spawn(async move {
5531                shared.retry_subscription(key, retry, terminal).await;
5532            });
5533            return;
5534        }
5535        let Some(entry) = entry else {
5536            return;
5537        };
5538        if entry.retain_late_route_open && entry.completion_is_closed() {
5539            if let PendingTerminal::Response {
5540                generation, body, ..
5541            } = &terminal
5542            {
5543                if let Ok(ClientControlResponse::RouteOpen {
5544                    route_channel,
5545                    route_epoch,
5546                    ..
5547                }) = serde_json::from_slice::<ClientControlResponse>(body)
5548                {
5549                    let handle = RouteHandle::new(route_channel, route_epoch, *generation);
5550                    self.send_route_goodbye(handle, true);
5551                    self.uninstall_route_handle(handle);
5552                }
5553            }
5554            return;
5555        }
5556        entry.settle_terminal(terminal);
5557    }
5558
5559    fn pending_accepted(&self, key: PendingKey) -> Option<bool> {
5560        self.lock_inner()
5561            .pending
5562            .get(&key)
5563            .map(|entry| entry.accepted)
5564    }
5565
5566    fn handle_generation_drop(self: &Arc<Self>, generation: u64, reason: String) {
5567        self.handle_generation_drop_with_cause(
5568            generation,
5569            reason,
5570            OutcomeUnknownCause::ConnectionFailed,
5571        );
5572    }
5573
5574    fn handle_generation_drop_with_cause(
5575        self: &Arc<Self>,
5576        generation: u64,
5577        reason: String,
5578        cause: OutcomeUnknownCause,
5579    ) {
5580        let (should_emit, pending, callbacks) = {
5581            let mut inner = self.lock_inner();
5582            if inner.closed || inner.generation != generation || inner.writer.is_none() {
5583                return;
5584            }
5585            inner.writer = None;
5586            inner.restored_token = inner.restored_token.saturating_add(1);
5587            inner.close_routes();
5588            inner.route_epochs.clear();
5589            inner.route_modules.clear();
5590            inner.route_end_reasons.clear();
5591            inner.legacy_channel_reasons.clear();
5592            let pending = drain_pending_generation(&mut inner.pending, generation);
5593            // An opening belongs to its lead caller, not to a socket generation:
5594            // the caller may still be retrying after this transport is replaced.
5595            // Keep its waiters and close flag until its OpeningGuard finishes, so
5596            // a new caller cannot start a competing open for the same key.
5597            let callbacks = inner.callbacks.clone();
5598            (true, pending, callbacks)
5599        };
5600
5601        if should_emit {
5602            settle_route_pending_entries_with_cause(
5603                pending,
5604                reason.clone(),
5605                RouteEndReason::ConnectionLost,
5606                cause,
5607            );
5608            emit_callbacks(callbacks, ConnectionState::Dropped);
5609            self.notify.notify_waiters();
5610            let _ = self.spawn_reconnect(generation);
5611        }
5612    }
5613
5614    fn close_sync(&self, reason: &str) {
5615        let (pending, openings, routes, reader, writer, reconnect) = {
5616            let mut inner = self.lock_inner();
5617            if inner.closed {
5618                return;
5619            }
5620            inner.closed = true;
5621            // Disconnect releases every daemon route, including retirements
5622            // whose GOODBYEs are still waiting for writer capacity. Preserve
5623            // the best-effort shutdown send for retirements not yet reaped.
5624            let retirements = inner
5625                .retirement_goodbyes
5626                .iter()
5627                .copied()
5628                .collect::<Vec<_>>();
5629            for handle in retirements {
5630                inner.queue_retirement_goodbye(handle);
5631            }
5632            inner.writer = None;
5633            inner.route_epochs.clear();
5634            inner.route_modules.clear();
5635            inner.route_end_reasons.clear();
5636            inner.legacy_channel_reasons.clear();
5637            inner.push_event_receivers.clear();
5638            self.close_token.cancel();
5639            let reconnect = match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
5640                ReconnectState::Background { task, .. } => Some(task),
5641                ReconnectState::Idle | ReconnectState::Inline { .. } => None,
5642            };
5643            (
5644                inner
5645                    .pending
5646                    .drain()
5647                    .map(|(_, entry)| entry)
5648                    .collect::<Vec<_>>(),
5649                inner
5650                    .openings
5651                    .drain()
5652                    .map(|(_, opening)| opening.waiters)
5653                    .collect::<Vec<_>>(),
5654                inner.drain_routes(),
5655                inner.reader_task.take(),
5656                inner.writer_task.take(),
5657                reconnect,
5658            )
5659        };
5660        for route in routes {
5661            route.close();
5662        }
5663        if let Some(handle) = reader {
5664            handle.abort();
5665        }
5666        if let Some(mut handle) = writer {
5667            // Let already queued GOODBYEs reach the socket, but never leave
5668            // a writer blocked on an unresponsive peer alive after close.
5669            if let Ok(runtime) = tokio::runtime::Handle::try_current() {
5670                runtime.spawn(async move {
5671                    if tokio::time::timeout(Duration::from_millis(250), &mut handle)
5672                        .await
5673                        .is_err()
5674                    {
5675                        handle.abort();
5676                    }
5677                });
5678            } else {
5679                handle.abort();
5680            }
5681        }
5682        if let Some(handle) = reconnect {
5683            handle.abort();
5684        }
5685        settle_pending_entries(pending, reason.to_string());
5686        fail_openings(openings, SharedCallFailure::not_sent(reason.to_string()));
5687        self.notify.notify_waiters();
5688    }
5689
5690    fn validate_current_handle(&self, handle: RouteHandle) -> Result<(), CallError> {
5691        let inner = self.lock_inner();
5692        if inner.closed
5693            || inner.generation != handle.connection_token()
5694            || inner.writer.is_none()
5695            || !route_is_installed(&inner, handle)
5696        {
5697            Err(CallError::StaleRouteHandle(handle))
5698        } else {
5699            Ok(())
5700        }
5701    }
5702
5703    fn route_state(&self, handle: RouteHandle) -> Result<RouteState, CallError> {
5704        let inner = self.lock_inner();
5705        if inner.closed
5706            || inner.generation != handle.connection_token()
5707            || inner.writer.is_none()
5708            || inner.route_epochs.get(&handle.channel) != Some(&handle)
5709        {
5710            return Err(CallError::StaleRouteHandle(handle));
5711        }
5712
5713        let route = inner
5714            .route_by_channel
5715            .get(&handle.channel)
5716            .and_then(|key| inner.routes.get(key))
5717            .or_else(|| inner.one_shot_routes.get(&handle.channel));
5718        debug_assert!(route.is_none_or(|route| route.handle == handle));
5719        route
5720            .filter(|route| route.handle == handle)
5721            .cloned()
5722            .ok_or(CallError::StaleRouteHandle(handle))
5723    }
5724
5725    fn route_is_current(&self, key: &RouteKey, route: &RouteState) -> bool {
5726        let inner = self.lock_inner();
5727        if inner.closed
5728            || inner.generation != route.handle.connection_token()
5729            || inner.writer.is_none()
5730        {
5731            return false;
5732        }
5733        inner.routes.get(key).is_some_and(|cached| {
5734            cached.handle == route.handle && Arc::ptr_eq(&cached.sem, &route.sem)
5735        })
5736    }
5737
5738    fn invalidate_route(&self, key: &RouteKey, expected_handle: Option<RouteHandle>) {
5739        self.invalidate_route_with_deadline(key, expected_handle, false);
5740    }
5741
5742    /// An accepted call's response deadline cannot prove non-delivery, so it
5743    /// must not trigger a resend. Retiring its route instead lets the next call
5744    /// recover even when the connection-wide Ping still succeeds. A module that
5745    /// is merely slower than the deadline makes the next call open a fresh
5746    /// route. Calls already pending on the retired route still receive their
5747    /// replies until they settle.
5748    fn invalidate_route_with_deadline(
5749        &self,
5750        key: &RouteKey,
5751        expected_handle: Option<RouteHandle>,
5752        response_deadline_expired: bool,
5753    ) {
5754        let removed = {
5755            let mut inner = self.lock_inner();
5756            match inner.routes.get(key) {
5757                Some(route) if expected_handle.is_none_or(|expected| expected == route.handle) => {
5758                    let removed = inner.evict_route(key);
5759                    if let Some(route) = &removed {
5760                        // Eviction stops new calls, but siblings may already be
5761                        // executing or awaiting their own refusal. Keep ingress
5762                        // until those pending entries settle; never resend them
5763                        // merely because another call was refused.
5764                        inner.retired_routes.insert(route.handle);
5765                        if response_deadline_expired {
5766                            inner.retirement_goodbyes.insert(route.handle);
5767                            // Closing this route releases slots retained for outstanding calls.
5768                            // A module that never answers must not block the route's GOODBYE.
5769                            inner.release_wire_slots(route.handle);
5770                            let pending_calls = inner
5771                                .pending
5772                                .keys()
5773                                .filter(|pending| {
5774                                    pending.generation == route.handle.connection_token()
5775                                        && pending.channel == route.handle.channel
5776                                        && pending.epoch == route.handle.epoch
5777                                })
5778                                .count();
5779                            tracing::warn!(
5780                                target_module = %key.target_label(),
5781                                channel = route.handle.channel,
5782                                epoch = route.handle.epoch,
5783                                pending_calls,
5784                                "retiring route after call response deadline"
5785                            );
5786                        }
5787                        inner.reap_retired_route(route.handle);
5788                    }
5789                    removed
5790                }
5791                _ => None,
5792            }
5793        };
5794        if let Some(route) = removed {
5795            route.close();
5796        }
5797    }
5798
5799    fn finish_opening(&self, key: &RouteKey, result: Result<RouteState, SharedCallFailure>) {
5800        let opening = self.lock_inner().openings.remove(key);
5801        for waiter in opening.map(|o| o.waiters).unwrap_or_default() {
5802            let _ = waiter.send(result.clone());
5803        }
5804    }
5805
5806    async fn close_handle(
5807        self: &Arc<Self>,
5808        handle: RouteHandle,
5809        opts: &CloseRouteOptions,
5810    ) -> Result<(), CallError> {
5811        self.validate_current_handle(handle)?;
5812        let route = {
5813            let mut inner = self.lock_inner();
5814            inner.route_end_reasons.insert(
5815                handle.channel,
5816                (RouteEndReason::ClosedByCaller.into(), true),
5817            );
5818            inner.remove_route_by_handle(handle)
5819        };
5820        let mut closing = RouteCloseGuard::new(
5821            Arc::clone(self),
5822            handle,
5823            route,
5824            "route closed by close_handle",
5825        );
5826        if opts.drain {
5827            self.drain_channel(handle, opts.drain_timeout).await;
5828        }
5829        closing.close_pending();
5830        self.queue_route_goodbye(handle).await;
5831        closing.finish();
5832        Ok(())
5833    }
5834
5835    /// Tear down one route by key. See [`SubcConsumer::close_route`].
5836    async fn close_route(self: &Arc<Self>, key: &RouteKey, opts: &CloseRouteOptions) {
5837        // Under the lock: flip the close-beats-reopen flag on any in-flight open for
5838        // this key (so a lead-opener whose channel hasn't been cached yet refuses to
5839        // install it), and remove the cached route if one exists.
5840        let route = {
5841            let mut inner = self.lock_inner();
5842            if let Some(opening) = inner.openings.get_mut(key) {
5843                opening.closed = true;
5844            }
5845            let route = inner.remove_route(key);
5846            if let Some(route) = &route {
5847                inner.route_end_reasons.insert(
5848                    route.handle.channel,
5849                    (RouteEndReason::ClosedByCaller.into(), true),
5850                );
5851            }
5852            route
5853        };
5854
5855        // Nothing cached: either never opened (idempotent no-op) or still opening (the
5856        // racing lead-opener will see the flag and GOODBYE whatever channel it opens).
5857        let Some(route) = route else {
5858            return;
5859        };
5860        let handle = route.handle;
5861        let mut closing = RouteCloseGuard::new(
5862            Arc::clone(self),
5863            handle,
5864            Some(route),
5865            "route closed by close_route",
5866        );
5867
5868        if opts.drain {
5869            // Wait for in-flight UNARY requests on this channel to settle naturally,
5870            // bounded by drain_timeout, before tearing the route down.
5871            self.drain_channel(handle, opts.drain_timeout).await;
5872        }
5873
5874        // Closing the semaphore makes any not-yet-sent acquire() return Err -> the
5875        // caller classifies it NotSent. Already-sent pending requests are settled
5876        // at-most-once (OutcomeUnknown if the writer accepted their bytes).
5877        closing.close_pending();
5878
5879        // Fail pending requests and release their slots before waiting for the
5880        // writer. Keep the ingress handle installed until GOODBYE is queued,
5881        // preventing channel reuse from overtaking the old route's teardown.
5882        self.queue_route_goodbye(handle).await;
5883        closing.finish();
5884    }
5885
5886    fn uninstall_route_handle(&self, handle: RouteHandle) {
5887        let mut inner = self.lock_inner();
5888        inner.release_wire_slots(handle);
5889        inner.retired_routes.remove(&handle);
5890        inner.retirement_goodbyes.remove(&handle);
5891        if inner.route_epochs.get(&handle.channel) == Some(&handle) {
5892            let installed = inner.route_epochs.remove(&handle.channel).unwrap();
5893            inner.route_targets.remove(&handle);
5894            inner.push_event_receivers.remove(&handle);
5895            release_reverse_request_registry(installed);
5896        }
5897    }
5898
5899    fn route_not_sent_error(&self, handle: RouteHandle) -> CallError {
5900        let inner = self.lock_inner();
5901        let reason = if inner.generation != handle.connection_token() || inner.writer.is_none() {
5902            RouteEndReason::ConnectionLost.into()
5903        } else {
5904            inner.route_end(handle.channel)
5905        };
5906        CallError::NotSent(Box::new(NotSentSource {
5907            message: "route flow-control semaphore closed".into(),
5908            cause: NotSentCause::BeforeQueue,
5909            never_forwarded: true,
5910            route_reason: Some(reason),
5911            refusal: None,
5912        }))
5913    }
5914
5915    /// Settle every pending request on this handle as OutcomeUnknown if the writer
5916    /// accepted its bytes, or NotSent otherwise, preserving the route ending cause.
5917    fn fail_channel_pending(
5918        &self,
5919        handle: RouteHandle,
5920        reason: &str,
5921        close_reason: RouteEndReason,
5922    ) {
5923        let entries = {
5924            let mut inner = self.lock_inner();
5925            inner.release_wire_slots(handle);
5926            inner
5927                .route_end_reasons
5928                .insert(handle.channel, (close_reason.clone().into(), true));
5929            drain_pending_handle(&mut inner.pending, handle, true)
5930        };
5931        settle_route_pending_entries(entries, reason.to_string(), close_reason);
5932    }
5933
5934    /// Resolve once every in-flight unary pending on `channel` has settled, or the
5935    /// timeout elapses. Polls the pending map (entries are removed on settle); the
5936    /// volume here is tiny (a route window is small) so a short poll is adequate.
5937    async fn drain_channel(&self, handle: RouteHandle, timeout: Duration) {
5938        let deadline = Instant::now() + timeout;
5939        loop {
5940            let has_inflight = {
5941                let inner = self.lock_inner();
5942                inner.pending.iter().any(|(key, entry)| {
5943                    key.generation == handle.connection_token()
5944                        && key.channel == handle.channel
5945                        && key.epoch == handle.epoch
5946                        && !entry.is_subscription()
5947                })
5948            };
5949            if !has_inflight || Instant::now() >= deadline {
5950                return;
5951            }
5952            sleep(Duration::from_millis(5)).await;
5953        }
5954    }
5955
5956    async fn queue_route_goodbye(self: &Arc<Self>, handle: RouteHandle) {
5957        let frame = Frame::build(
5958            FrameType::Goodbye,
5959            Flags::new(false, Priority::Interactive, false),
5960            handle.channel,
5961            handle.epoch,
5962            0,
5963            Vec::new(),
5964        )
5965        .expect("header-only route GOODBYE is valid");
5966        loop {
5967            let changed = self.notify.notified();
5968            tokio::pin!(changed);
5969            changed.as_mut().enable();
5970            let writer = {
5971                let inner = self.lock_inner();
5972                // A missing writer or changed generation means the connection
5973                // is dead: the daemon releases every route on that connection,
5974                // so no GOODBYE is needed. A removed handle was already closed.
5975                if inner.closed
5976                    || inner.generation != handle.connection_token()
5977                    || inner.route_epochs.get(&handle.channel) != Some(&handle)
5978                {
5979                    return;
5980                }
5981                let Some(writer) = inner.writer.clone() else {
5982                    return;
5983                };
5984                writer
5985            };
5986            // Request deadlines bound other awaited writes, but there is no
5987            // writer-stall timeout: a live connection must admit this teardown
5988            // before its caller can release route budget.
5989            tokio::select! {
5990                result = writer.reserve() => {
5991                    let Ok(permit) = result else {
5992                        self.handle_generation_drop(
5993                            handle.connection_token(),
5994                            "writer closed before route GOODBYE".into(),
5995                        );
5996                        return;
5997                    };
5998                    let inner = self.lock_inner();
5999                    if !inner.closed
6000                        && inner.generation == handle.connection_token()
6001                        && inner.writer.as_ref().is_some_and(|current| current.same_channel(&writer))
6002                        && inner.route_epochs.get(&handle.channel) == Some(&handle)
6003                    {
6004                        permit.send(WriteCommand { frame, pending: None });
6005                    }
6006                    return;
6007                }
6008                _ = &mut changed => {}
6009                _ = self.close_token.cancelled() => return,
6010            }
6011        }
6012    }
6013
6014    /// Queue a header-only route GOODBYE if `handle` is still live on this connection.
6015    /// Late successful route.open cleanup sets `close_on_failure`: orphan prevention then
6016    /// requires closing the connection when the GOODBYE cannot enter the writer queue.
6017    fn send_route_goodbye(self: &Arc<Self>, handle: RouteHandle, close_on_failure: bool) -> bool {
6018        let writer = {
6019            let inner = self.lock_inner();
6020            if inner.closed
6021                || inner.generation != handle.connection_token()
6022                || inner.route_epochs.get(&handle.channel) != Some(&handle)
6023            {
6024                return false;
6025            }
6026            inner.writer.clone()
6027        };
6028        let Some(writer) = writer else {
6029            return false;
6030        };
6031        let Ok(frame) = Frame::build(
6032            FrameType::Goodbye,
6033            Flags::new(false, Priority::Interactive, false),
6034            handle.channel,
6035            handle.epoch,
6036            0,
6037            Vec::new(),
6038        ) else {
6039            return false;
6040        };
6041        if writer
6042            .try_send(WriteCommand {
6043                frame,
6044                pending: None,
6045            })
6046            .is_ok()
6047        {
6048            return true;
6049        }
6050        if close_on_failure {
6051            self.handle_generation_drop(
6052                handle.connection_token(),
6053                "failed to queue late route.open cleanup GOODBYE".to_string(),
6054            );
6055        }
6056        false
6057    }
6058
6059    fn emit_connection_state(&self, state: ConnectionState) {
6060        let callbacks = self.lock_inner().callbacks.clone();
6061        emit_callbacks(callbacks, state);
6062    }
6063}
6064
6065#[derive(Clone, Copy)]
6066enum InstallKind {
6067    Initial,
6068    Reconnect,
6069}
6070
6071enum EnsureAction {
6072    Wait,
6073    Lead {
6074        generation: u64,
6075        stale_task: Option<JoinHandle<()>>,
6076    },
6077}
6078
6079/// The reconnect state is fenced by the generation whose transport failed. A
6080/// newer generation can replace an older attempt, and completion only changes
6081/// the state when its generation still owns the slot.
6082enum ReconnectState {
6083    Idle,
6084    Inline {
6085        generation: u64,
6086    },
6087    Background {
6088        generation: u64,
6089        task: JoinHandle<()>,
6090    },
6091}
6092
6093/// Outcome of the install decision after a route.open response arrives, taken under
6094/// the inner lock so a racing close_route is observed atomically.
6095enum RouteInstall {
6096    /// Install (or reuse) the cached route and return it.
6097    Cached(RouteState),
6098    /// Do not install. `closed` => a close_route won the race (GOODBYE + NotSent);
6099    /// otherwise the generation moved (retry the open).
6100    Discard { closed: bool },
6101}
6102
6103enum RouteOpenAction {
6104    Wait(oneshot::Receiver<Result<RouteState, SharedCallFailure>>),
6105    Lead,
6106}
6107
6108struct RouteOpenParams<'a> {
6109    target: &'a RouteTarget,
6110    identity: &'a BindIdentity,
6111    consumer_identity: &'a Option<ConsumerIdentity>,
6112    consumer_capabilities: &'a Option<Vec<String>>,
6113    /// Already normalized: an empty map is `None` here, as in the route key.
6114    role_versions: &'a Option<BTreeMap<String, String>>,
6115    reverse_requests: &'a ReverseRequestRegistry,
6116    /// The scope every route.open for this key asks to be admitted under, so a
6117    /// reopen after the route drops carries the same selector as the first open.
6118    scope: Option<&'a ScopeSelector>,
6119}
6120
6121struct CallAttemptHistory {
6122    never_forwarded: bool,
6123    sent: bool,
6124}
6125
6126struct RequestSend {
6127    expected_handle: Option<RouteHandle>,
6128    channel: u16,
6129    epoch: u32,
6130    body: Vec<u8>,
6131    binary: bool,
6132    priority: Priority,
6133    admission_class: AdmissionClass,
6134    deadline: Instant,
6135    retain_late_route_open: bool,
6136    route_open_reverse_requests: Option<ReverseRequestRegistry>,
6137}
6138
6139struct SubscriptionSend {
6140    expected_handle: Option<RouteHandle>,
6141    channel: u16,
6142    epoch: u32,
6143    body: Vec<u8>,
6144    priority: Priority,
6145    admission_class: AdmissionClass,
6146    event_buffer: usize,
6147    deadline: Instant,
6148    permit: Arc<RoutePermit>,
6149}
6150
6151struct SubscriptionPosition {
6152    key: Mutex<PendingKey>,
6153    stop: CancellationToken,
6154}
6155
6156#[derive(Clone)]
6157struct SubscriptionRetry {
6158    frame: Frame,
6159    deadline: Instant,
6160    delay: Duration,
6161    position: Arc<SubscriptionPosition>,
6162}
6163
6164struct RouteCloseGuard {
6165    shared: Arc<Shared>,
6166    handle: RouteHandle,
6167    route: Option<RouteState>,
6168    reason: &'static str,
6169    finished: bool,
6170}
6171
6172impl RouteCloseGuard {
6173    fn new(
6174        shared: Arc<Shared>,
6175        handle: RouteHandle,
6176        route: Option<RouteState>,
6177        reason: &'static str,
6178    ) -> Self {
6179        Self {
6180            shared,
6181            handle,
6182            route,
6183            reason,
6184            finished: false,
6185        }
6186    }
6187
6188    fn close_pending(&self) {
6189        if let Some(route) = &self.route {
6190            route.close();
6191        }
6192        self.shared
6193            .fail_channel_pending(self.handle, self.reason, RouteEndReason::ClosedByCaller);
6194    }
6195
6196    fn finish(&mut self) {
6197        self.shared.uninstall_route_handle(self.handle);
6198        self.finished = true;
6199    }
6200}
6201
6202impl Drop for RouteCloseGuard {
6203    fn drop(&mut self) {
6204        if self.finished {
6205            return;
6206        }
6207        // An abandoned drain must not leave requests or their in-flight permits
6208        // waiting on the caller. Retirement owns GOODBYE admission once the close is dropped.
6209        self.close_pending();
6210        let mut inner = self.shared.lock_inner();
6211        if inner.closed
6212            || inner.generation != self.handle.connection_token()
6213            || inner.writer.is_none()
6214            || inner.route_epochs.get(&self.handle.channel) != Some(&self.handle)
6215        {
6216            return;
6217        }
6218        inner.retired_routes.insert(self.handle);
6219        inner.retirement_goodbyes.insert(self.handle);
6220        // Reaping tries synchronous admission first; otherwise the connection's
6221        // FIFO flusher keeps the handle installed until its GOODBYE is queued.
6222        inner.reap_retired_route(self.handle);
6223    }
6224}
6225
6226struct OpeningGuard {
6227    shared: Arc<Shared>,
6228    key: RouteKey,
6229    finished: bool,
6230}
6231
6232impl OpeningGuard {
6233    fn new(shared: Arc<Shared>, key: RouteKey) -> Self {
6234        Self {
6235            shared,
6236            key,
6237            finished: false,
6238        }
6239    }
6240
6241    fn finish(&mut self, result: Result<RouteState, SharedCallFailure>) {
6242        self.shared.finish_opening(&self.key, result);
6243        self.finished = true;
6244    }
6245}
6246
6247impl Drop for OpeningGuard {
6248    fn drop(&mut self) {
6249        if !self.finished {
6250            self.shared.finish_opening(
6251                &self.key,
6252                Err(SharedCallFailure::not_sent(
6253                    "route.open future was cancelled",
6254                )),
6255            );
6256        }
6257    }
6258}
6259
6260struct InlineReconnectGuard {
6261    shared: Arc<Shared>,
6262    generation: u64,
6263    finished: bool,
6264}
6265
6266impl InlineReconnectGuard {
6267    fn new(shared: Arc<Shared>, generation: u64) -> Self {
6268        Self {
6269            shared,
6270            generation,
6271            finished: false,
6272        }
6273    }
6274
6275    fn finish(&mut self) {
6276        self.shared.finish_inline_reconnect(self.generation);
6277        self.finished = true;
6278    }
6279}
6280
6281impl Drop for InlineReconnectGuard {
6282    fn drop(&mut self) {
6283        if !self.finished {
6284            self.shared.finish_inline_reconnect(self.generation);
6285        }
6286    }
6287}
6288
6289#[derive(Clone)]
6290struct RouteState {
6291    handle: RouteHandle,
6292    sem: Arc<Semaphore>,
6293    watch_sem: Option<Arc<Semaphore>>,
6294    opted_in: bool,
6295}
6296
6297#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6298struct RouteKey {
6299    target: RouteTargetKey,
6300    harness: String,
6301    session: String,
6302    consumer_identity: Option<ConsumerIdentityKey>,
6303    consumer_capabilities: Option<ConsumerCapabilitiesKey>,
6304    /// The role versions the route was opened with; `None` for a route that
6305    /// declared none. Part of the key so a legacy route and a versioned one to
6306    /// the same target are never shared: the provider chose its wire shape
6307    /// from these at bind. A `BTreeMap` is already in canonical order.
6308    role_versions: Option<BTreeMap<String, String>>,
6309    /// The scope the route was admitted under; `None` for an unscoped route.
6310    /// Part of the key so a route bound to one session's scope (or one epoch
6311    /// of it) is never reused for another, nor for an unscoped caller.
6312    scope: Option<ScopeKey>,
6313}
6314
6315impl RouteKey {
6316    fn new(
6317        target: &RouteTarget,
6318        identity: &BindIdentity,
6319        consumer_identity: Option<&ConsumerIdentity>,
6320        consumer_capabilities: Option<&[String]>,
6321    ) -> Self {
6322        Self {
6323            target: RouteTargetKey::from(target),
6324            harness: identity.harness.clone(),
6325            session: identity.session.clone(),
6326            consumer_identity: consumer_identity.map(ConsumerIdentityKey::from),
6327            consumer_capabilities: consumer_capabilities.map(ConsumerCapabilitiesKey::from_slice),
6328            role_versions: None,
6329            scope: None,
6330        }
6331    }
6332
6333    fn with_role_versions(mut self, role_versions: Option<&BTreeMap<String, String>>) -> Self {
6334        self.role_versions = role_versions.cloned();
6335        self
6336    }
6337
6338    fn with_scope(mut self, scope: Option<&ScopeSelector>) -> Self {
6339        self.scope = scope.map(ScopeKey::from);
6340        self
6341    }
6342
6343    fn target_label(&self) -> String {
6344        match &self.target {
6345            RouteTargetKey::ToolProvider { module_id } => format!("tool_provider:{module_id}"),
6346            RouteTargetKey::ManagementSurface { module_id } => {
6347                format!("management_surface:{module_id}")
6348            }
6349            RouteTargetKey::InternalService {
6350                module_id,
6351                service_id,
6352            } => format!("internal_service:{module_id}:{service_id}"),
6353        }
6354    }
6355}
6356
6357#[derive(Clone, Hash, PartialEq, Eq)]
6358struct ConsumerIdentityKey {
6359    module_id: String,
6360    launch_nonce: String,
6361}
6362
6363// Hand-written so the launch nonce is never printed. The nonce is the credential
6364// that attributes a connection to a supervised module, and a derived Debug would
6365// write it into any log line or panic message that formats this value. This key sits
6366// inside the route cache key, which is formatted in logs.
6367impl fmt::Debug for ConsumerIdentityKey {
6368    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
6369        f.debug_struct("ConsumerIdentityKey")
6370            .field("module_id", &self.module_id)
6371            .field(
6372                "launch_nonce",
6373                &format_args!("<{} bytes redacted>", self.launch_nonce.len()),
6374            )
6375            .finish()
6376    }
6377}
6378
6379impl From<&ConsumerIdentity> for ConsumerIdentityKey {
6380    fn from(value: &ConsumerIdentity) -> Self {
6381        Self {
6382            module_id: value.module_id.clone(),
6383            launch_nonce: value.launch_nonce.clone(),
6384        }
6385    }
6386}
6387
6388/// Every field of a [`ScopeSelector`], in hashable form.
6389#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6390struct ScopeKey {
6391    /// The owner principal as its JSON encoding. `Principal` is not `Hash`,
6392    /// and matching on its variants here would stop compiling when the
6393    /// protocol crate adds one; the tagged encoding is unique per principal.
6394    owner: String,
6395    scope_ref: String,
6396    scope_epoch: Option<u64>,
6397    bind_proof_digest: Option<[u8; 32]>,
6398}
6399
6400impl From<&ScopeSelector> for ScopeKey {
6401    fn from(value: &ScopeSelector) -> Self {
6402        Self {
6403            owner: serde_json::to_string(&value.owner)
6404                .unwrap_or_else(|_| format!("{:?}", value.owner)),
6405            scope_ref: value.scope_ref.clone(),
6406            scope_epoch: value.scope_epoch,
6407            bind_proof_digest: value
6408                .bind_proof
6409                .as_ref()
6410                .map(|proof| Sha256::digest(proof.as_bytes()).into()),
6411        }
6412    }
6413}
6414
6415#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6416struct ConsumerCapabilitiesKey {
6417    values: Vec<String>,
6418}
6419
6420impl ConsumerCapabilitiesKey {
6421    fn from_slice(values: &[String]) -> Self {
6422        let mut values = values.to_vec();
6423        values.sort();
6424        values.dedup();
6425        Self { values }
6426    }
6427}
6428
6429#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6430enum RouteTargetKey {
6431    ToolProvider {
6432        module_id: String,
6433    },
6434    ManagementSurface {
6435        module_id: String,
6436    },
6437    InternalService {
6438        module_id: String,
6439        service_id: String,
6440    },
6441}
6442
6443impl From<&RouteTarget> for RouteTargetKey {
6444    fn from(value: &RouteTarget) -> Self {
6445        match value {
6446            RouteTarget::ToolProvider { module_id } => Self::ToolProvider {
6447                module_id: module_id.clone(),
6448            },
6449            RouteTarget::ManagementSurface { module_id } => Self::ManagementSurface {
6450                module_id: module_id.clone(),
6451            },
6452            RouteTarget::InternalService {
6453                module_id,
6454                service_id,
6455            } => Self::InternalService {
6456                module_id: module_id.clone(),
6457                service_id: service_id.clone(),
6458            },
6459        }
6460    }
6461}
6462
6463#[derive(Debug, Clone)]
6464struct SharedCallFailure {
6465    kind: FailureKind,
6466}
6467
6468impl SharedCallFailure {
6469    fn not_sent(message: impl Into<String>) -> Self {
6470        CallError::not_sent_with_cause(message, NotSentCause::RouteOpenAbandoned).into()
6471    }
6472
6473    fn into_call_error(self) -> CallError {
6474        match self.kind {
6475            FailureKind::NotSent(source) => CallError::NotSent(Box::new(source)),
6476            FailureKind::OutcomeUnknown(source) => CallError::outcome_unknown_source(source),
6477            FailureKind::DaemonTooOld(daemon_ver) => CallError::DaemonTooOld { daemon_ver },
6478        }
6479    }
6480}
6481
6482impl From<CallError> for SharedCallFailure {
6483    fn from(value: CallError) -> Self {
6484        match value {
6485            CallError::DaemonTooOld { daemon_ver } => Self {
6486                kind: FailureKind::DaemonTooOld(daemon_ver),
6487            },
6488            CallError::NotSent(err) => Self {
6489                kind: FailureKind::NotSent(
6490                    err.downcast_ref::<NotSentSource>()
6491                        .expect("crate-built route.open failure has a typed source")
6492                        .clone(),
6493                ),
6494            },
6495            CallError::OutcomeUnknown(err) => Self {
6496                kind: FailureKind::OutcomeUnknown(
6497                    err.downcast_ref::<OutcomeUnknownSource>()
6498                        .cloned()
6499                        .unwrap_or_else(|| OutcomeUnknownSource {
6500                            message: err.to_string(),
6501                            cause: OutcomeUnknownCause::CompletionFailed,
6502                            route_reason: None,
6503                        }),
6504                ),
6505            },
6506            CallError::Module(body) => Self {
6507                kind: FailureKind::OutcomeUnknown(OutcomeUnknownSource {
6508                    message: format!(
6509                        "unexpected module error during route.open: {} ({})",
6510                        body.code, body.message
6511                    ),
6512                    cause: OutcomeUnknownCause::CompletionFailed,
6513                    route_reason: None,
6514                }),
6515            },
6516            CallError::SubscriptionBackpressure(err) => Self {
6517                kind: FailureKind::OutcomeUnknown(OutcomeUnknownSource {
6518                    message: err.to_string(),
6519                    cause: OutcomeUnknownCause::CompletionFailed,
6520                    route_reason: None,
6521                }),
6522            },
6523            CallError::StaleRouteHandle(handle) => {
6524                CallError::not_sent(format!("stale route handle: {handle:?}")).into()
6525            }
6526            error @ (CallError::CapabilityUnprovided { .. }
6527            | CallError::CapabilityAmbiguous { .. }
6528            | CallError::InvalidCapabilityIdentifier { .. }) => {
6529                CallError::not_sent(error.to_string()).into()
6530            }
6531        }
6532    }
6533}
6534
6535#[derive(Debug, Clone)]
6536enum FailureKind {
6537    NotSent(NotSentSource),
6538    OutcomeUnknown(OutcomeUnknownSource),
6539    DaemonTooOld(String),
6540}
6541
6542#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq)]
6543struct PendingKey {
6544    generation: u64,
6545    channel: u16,
6546    epoch: u32,
6547    corr: u64,
6548}
6549
6550struct PendingEntry {
6551    accepted: bool,
6552    send_deadline: Option<Instant>,
6553    retain_late_route_open: bool,
6554    expected_control_handle: Option<RouteHandle>,
6555    route_open_reverse_requests: Option<ReverseRequestRegistry>,
6556    route_open_module: Option<String>,
6557    retry: Option<SubscriptionRetry>,
6558    completion: PendingCompletion,
6559}
6560
6561enum PendingCompletion {
6562    Unary(oneshot::Sender<PendingResult>),
6563    Subscription {
6564        events: mpsc::Sender<Vec<u8>>,
6565        closed: oneshot::Sender<Result<(), CallError>>,
6566        ended: watch::Sender<Option<SubscriptionEnd>>,
6567        _permit: Arc<RoutePermit>,
6568        priority: Priority,
6569    },
6570}
6571
6572enum StreamDataDelivery {
6573    NotSubscription,
6574    Full,
6575    Closed,
6576}
6577
6578impl PendingEntry {
6579    fn unary(
6580        tx: oneshot::Sender<PendingResult>,
6581        retain_late_route_open: bool,
6582        expected_control_handle: Option<RouteHandle>,
6583        route_open_reverse_requests: Option<ReverseRequestRegistry>,
6584    ) -> Self {
6585        Self {
6586            accepted: false,
6587            send_deadline: None,
6588            retain_late_route_open,
6589            expected_control_handle,
6590            route_open_reverse_requests,
6591            route_open_module: None,
6592            retry: None,
6593            completion: PendingCompletion::Unary(tx),
6594        }
6595    }
6596
6597    fn subscription(
6598        events: mpsc::Sender<Vec<u8>>,
6599        closed: oneshot::Sender<Result<(), CallError>>,
6600        ended: watch::Sender<Option<SubscriptionEnd>>,
6601        permit: Arc<RoutePermit>,
6602        priority: Priority,
6603    ) -> Self {
6604        Self {
6605            accepted: false,
6606            send_deadline: None,
6607            retain_late_route_open: false,
6608            expected_control_handle: None,
6609            route_open_reverse_requests: None,
6610            route_open_module: None,
6611            retry: None,
6612            completion: PendingCompletion::Subscription {
6613                events,
6614                closed,
6615                ended,
6616                _permit: permit,
6617                priority,
6618            },
6619        }
6620    }
6621
6622    fn completion_is_closed(&self) -> bool {
6623        match &self.completion {
6624            PendingCompletion::Unary(tx) => tx.is_closed(),
6625            PendingCompletion::Subscription { closed, .. } => closed.is_closed(),
6626        }
6627    }
6628
6629    fn is_subscription(&self) -> bool {
6630        matches!(&self.completion, PendingCompletion::Subscription { .. })
6631    }
6632
6633    fn subscription_priority(&self) -> Option<Priority> {
6634        match &self.completion {
6635            PendingCompletion::Subscription { priority, .. } => Some(*priority),
6636            PendingCompletion::Unary(_) => None,
6637        }
6638    }
6639
6640    fn try_send_stream_data(&self, body: Vec<u8>) -> Result<(), StreamDataDelivery> {
6641        let PendingCompletion::Subscription { events, .. } = &self.completion else {
6642            return Err(StreamDataDelivery::NotSubscription);
6643        };
6644        events.try_send(body).map_err(|err| match err {
6645            mpsc::error::TrySendError::Full(_) => StreamDataDelivery::Full,
6646            mpsc::error::TrySendError::Closed(_) => StreamDataDelivery::Closed,
6647        })
6648    }
6649
6650    fn settle_terminal(self, terminal: PendingTerminal) {
6651        if let Some(retry) = &self.retry {
6652            retry.position.stop.cancel();
6653        }
6654        match self.completion {
6655            PendingCompletion::Unary(tx) => {
6656                let _ = tx.send(PendingResult::Terminal(terminal));
6657            }
6658            PendingCompletion::Subscription { closed, ended, .. } => {
6659                let (end, result) = match terminal {
6660                    PendingTerminal::Response { body, .. } => {
6661                        (SubscriptionEnd::Response(body), Ok(()))
6662                    }
6663                    PendingTerminal::StreamEnd => (SubscriptionEnd::StreamEnd, Ok(())),
6664                    PendingTerminal::Error { body, flags } => {
6665                        let err = if error_codes::is_route_busy_retryable(
6666                            flags,
6667                            &body.code,
6668                            self.retry.is_some(),
6669                        ) {
6670                            busy_error(&body)
6671                        } else {
6672                            CallError::Module(body.clone())
6673                        };
6674                        (SubscriptionEnd::Error(body.clone()), Err(err))
6675                    }
6676                };
6677                let _ = ended.send(Some(end));
6678                let _ = closed.send(result);
6679            }
6680        }
6681    }
6682
6683    fn settle_failure(self, reason: String) {
6684        if let Some(retry) = &self.retry {
6685            retry.position.stop.cancel();
6686        }
6687        let err = classify_failure(self.accepted, reason, OutcomeUnknownCause::ConsumerClosed);
6688        match self.completion {
6689            PendingCompletion::Unary(tx) => {
6690                let _ = tx.send(PendingResult::CallError(err));
6691            }
6692            PendingCompletion::Subscription { closed, ended, .. } => {
6693                let _ = ended.send(Some(SubscriptionEnd::RouteClosed {
6694                    reason: RouteEndReason::ClosedByCaller,
6695                }));
6696                let _ = closed.send(Err(err));
6697            }
6698        }
6699    }
6700
6701    fn settle_call_error(self, err: CallError) {
6702        if let Some(retry) = &self.retry {
6703            retry.position.stop.cancel();
6704        }
6705        match self.completion {
6706            PendingCompletion::Unary(tx) => {
6707                let _ = tx.send(PendingResult::CallError(err));
6708            }
6709            PendingCompletion::Subscription { closed, ended, .. } => {
6710                let end = if let Some(reason) = err.close_reason() {
6711                    match reason {
6712                        RouteEndReason::ConnectionLost => SubscriptionEnd::ConnectionLost,
6713                        reason => SubscriptionEnd::RouteClosed {
6714                            reason: reason.clone(),
6715                        },
6716                    }
6717                } else if matches!(err, CallError::SubscriptionBackpressure(_)) {
6718                    SubscriptionEnd::Backpressure
6719                } else {
6720                    SubscriptionEnd::ConnectionLost
6721                };
6722                let _ = ended.send(Some(end));
6723                let _ = closed.send(Err(err));
6724            }
6725        }
6726    }
6727
6728    fn settle_subscription_result(self, result: Result<(), CallError>) {
6729        if let Some(retry) = &self.retry {
6730            retry.position.stop.cancel();
6731        }
6732        match self.completion {
6733            PendingCompletion::Subscription { closed, ended, .. } => {
6734                let _ = ended.send(Some(SubscriptionEnd::Cancelled));
6735                let _ = closed.send(result);
6736            }
6737            PendingCompletion::Unary(tx) => {
6738                let _ = tx.send(PendingResult::Failure {
6739                    accepted: self.accepted,
6740                    reason: "subscription cancel matched a unary request".to_string(),
6741                });
6742            }
6743        }
6744    }
6745}
6746
6747struct PendingRegistration {
6748    shared: Arc<Shared>,
6749    key: PendingKey,
6750    active: bool,
6751    retain_on_drop: bool,
6752    unary_cancel: Option<Arc<UnaryCancel>>,
6753}
6754
6755impl PendingRegistration {
6756    fn new(shared: Arc<Shared>, key: PendingKey, retain_on_drop: bool) -> Self {
6757        Self {
6758            shared,
6759            key,
6760            active: true,
6761            retain_on_drop,
6762            unary_cancel: None,
6763        }
6764    }
6765
6766    fn remove_pending(&mut self) -> Option<bool> {
6767        if !self.active {
6768            return None;
6769        }
6770        self.active = false;
6771        self.shared
6772            .lock_inner()
6773            .remove_pending(&self.key)
6774            .map(|entry| entry.accepted)
6775    }
6776
6777    fn disarm(&mut self) {
6778        self.active = false;
6779    }
6780}
6781
6782impl Drop for PendingRegistration {
6783    fn drop(&mut self) {
6784        if self.retain_on_drop {
6785            self.disarm();
6786        } else {
6787            let _ = self.remove_pending();
6788        }
6789    }
6790}
6791
6792enum PendingResult {
6793    Terminal(PendingTerminal),
6794    CallError(CallError),
6795    Failure { accepted: bool, reason: String },
6796}
6797
6798impl PendingResult {
6799    fn into_call_result(self) -> Result<TerminalFrame, CallError> {
6800        match self {
6801            Self::Terminal(terminal) => Ok(terminal.into_terminal_frame()),
6802            Self::CallError(err) => Err(err),
6803            Self::Failure { accepted, reason } => Err(classify_failure(
6804                accepted,
6805                reason,
6806                OutcomeUnknownCause::CompletionFailed,
6807            )),
6808        }
6809    }
6810}
6811
6812enum PendingTerminal {
6813    Response {
6814        generation: u64,
6815        body: Vec<u8>,
6816        flags: Flags,
6817    },
6818    Error {
6819        body: ErrorBody,
6820        flags: Flags,
6821    },
6822    StreamEnd,
6823}
6824
6825impl PendingTerminal {
6826    fn into_terminal_frame(self) -> TerminalFrame {
6827        match self {
6828            Self::Response {
6829                generation,
6830                body,
6831                flags,
6832            } => TerminalFrame::Response {
6833                generation,
6834                body,
6835                flags,
6836            },
6837            Self::Error { body, flags } => TerminalFrame::Error { body, flags },
6838            Self::StreamEnd => TerminalFrame::StreamEnd,
6839        }
6840    }
6841}
6842
6843#[derive(Debug)]
6844enum TerminalFrame {
6845    Response {
6846        generation: u64,
6847        body: Vec<u8>,
6848        flags: Flags,
6849    },
6850    Error {
6851        body: ErrorBody,
6852        flags: Flags,
6853    },
6854    StreamEnd,
6855}
6856
6857struct WriteCommand {
6858    frame: Frame,
6859    pending: Option<PendingKey>,
6860}
6861
6862trait ConsumerStream: AsyncRead + AsyncWrite + Unpin + Send {}
6863impl<T: AsyncRead + AsyncWrite + Unpin + Send> ConsumerStream for T {}
6864
6865struct OpenedConnection {
6866    stream: Box<dyn ConsumerStream>,
6867    daemon_origin_trusted: bool,
6868    daemon_ver: String,
6869}
6870
6871async fn open_connection(
6872    path: &Path,
6873    deadline: Duration,
6874    transport: ConsumerTransport,
6875    operator_candidates: Option<&[PathBuf]>,
6876) -> Result<OpenedConnection, ConsumerError> {
6877    let path = operator_candidates
6878        .map(crate::operator_app::owned_candidate)
6879        .unwrap_or(path);
6880    if transport == ConsumerTransport::Local {
6881        let read =
6882            connection_file::read_for_client_with_local_endpoint(path).map_err(|source| {
6883                ConsumerError::ConnectionFile {
6884                    path: path.to_path_buf(),
6885                    source,
6886                }
6887            })?;
6888        let endpoint = read
6889            .local_endpoint
6890            .ok_or_else(|| ConsumerError::NoEndpoint {
6891                path: path.to_path_buf(),
6892            })?;
6893        let label = match &endpoint {
6894            connection_file::LocalEndpoint::Unix { path } => path.display().to_string(),
6895            connection_file::LocalEndpoint::Pipe { name } => name.clone(),
6896            _ => "unsupported local endpoint".to_owned(),
6897        };
6898        let mut stream =
6899            connect_local(&endpoint)
6900                .await
6901                .map_err(|source| ConsumerError::Connect {
6902                    path: path.to_path_buf(),
6903                    endpoint: label.clone(),
6904                    source,
6905                })?;
6906        authenticate_client(&mut stream, &read.info, deadline)
6907            .await
6908            .map_err(|source| ConsumerError::Auth {
6909                path: path.to_path_buf(),
6910                endpoint: label,
6911                source,
6912            })?;
6913        crate::registration::bind_consumer(&mut stream, deadline)
6914            .await
6915            .map_err(ConsumerError::claim)?;
6916        return Ok(OpenedConnection {
6917            stream,
6918            daemon_origin_trusted: trusts_daemon_origin(&read.info.daemon_ver),
6919            daemon_ver: read.info.daemon_ver,
6920        });
6921    }
6922    let conn =
6923        connection_file::read_for_client(path).map_err(|source| ConsumerError::ConnectionFile {
6924            path: path.to_path_buf(),
6925            source,
6926        })?;
6927    open_connection_with_info(path, &conn, deadline).await
6928}
6929
6930async fn connect_local(
6931    endpoint: &connection_file::LocalEndpoint,
6932) -> io::Result<Box<dyn ConsumerStream>> {
6933    match endpoint {
6934        #[cfg(unix)]
6935        connection_file::LocalEndpoint::Unix { path } => {
6936            Ok(Box::new(tokio::net::UnixStream::connect(path).await?))
6937        }
6938        #[cfg(windows)]
6939        connection_file::LocalEndpoint::Pipe { name } => Ok(Box::new(
6940            tokio::net::windows::named_pipe::ClientOptions::new().open(name)?,
6941        )),
6942        _ => Err(io::Error::new(
6943            io::ErrorKind::Unsupported,
6944            "unsupported local endpoint kind",
6945        )),
6946    }
6947}
6948
6949async fn open_connection_with_info(
6950    path: &Path,
6951    conn: &connection_file::ConnectionInfo,
6952    deadline: Duration,
6953) -> Result<OpenedConnection, ConsumerError> {
6954    let endpoint = conn
6955        .endpoints
6956        .first()
6957        .ok_or_else(|| ConsumerError::NoEndpoint {
6958            path: path.to_path_buf(),
6959        })?;
6960    let endpoint_label = format!("{}:{}", endpoint.host, endpoint.port);
6961    let mut stream = TcpStream::connect(&endpoint_label)
6962        .await
6963        .map_err(|source| ConsumerError::Connect {
6964            path: path.to_path_buf(),
6965            endpoint: endpoint_label.clone(),
6966            source,
6967        })?;
6968    // Consumers send a request and wait for its reply, so there is no following
6969    // write for Nagle to coalesce with -- it can only hold the request back until
6970    // an ACK returns. Both ends of the hop must disable it for either to help.
6971    //
6972    // Dropped rather than logged for the same reason as the module path: no logging
6973    // dependency here, and a socket too broken to take the option fails the
6974    // handshake on the next line with a typed error.
6975    let _ = stream.set_nodelay(true);
6976    authenticate_client(&mut stream, conn, deadline)
6977        .await
6978        .map_err(|source| ConsumerError::Auth {
6979            path: path.to_path_buf(),
6980            endpoint: endpoint_label,
6981            source,
6982        })?;
6983    crate::registration::bind_consumer(&mut stream, deadline)
6984        .await
6985        .map_err(ConsumerError::claim)?;
6986    Ok(OpenedConnection {
6987        stream: Box::new(stream),
6988        daemon_origin_trusted: trusts_daemon_origin(&conn.daemon_ver),
6989        daemon_ver: conn.daemon_ver.clone(),
6990    })
6991}
6992
6993fn dispatch_reverse_request(shared: &Arc<Shared>, frame: Frame, handle: RouteHandle) {
6994    let method = serde_json::from_slice::<serde_json::Value>(&frame.body)
6995        .ok()
6996        .and_then(|body| body.get("method")?.as_str().map(str::to_string));
6997    let method_family = method
6998        .as_deref()
6999        .and_then(|method| method.split('/').next())
7000        .filter(|family| !family.is_empty())
7001        .map(str::to_string);
7002    let handler = method_family.as_deref().and_then(|family| {
7003        route_reverse_request_registry(handle.reverse_request_registry_id())
7004            .ok()?
7005            .handler(family)
7006    });
7007    let generation = handle.connection_token();
7008    let shared = Arc::clone(shared);
7009
7010    tokio::spawn(async move {
7011        let (frame_type, body) = if let (Some(handler), Some(method)) = (handler, method) {
7012            let request_body = frame.body.clone();
7013            let corr = frame.header.corr;
7014            match tokio::spawn(async move {
7015                handler(request_body, ReverseRequestContext { corr, method }).await
7016            })
7017            .await
7018            {
7019                Ok(Ok(body)) => (FrameType::Response, body),
7020                Ok(Err(err)) => (
7021                    FrameType::Error,
7022                    serde_json::to_vec(&ErrorBody::new(REVERSE_REQUEST_UNHANDLED, err.to_string()))
7023                        .unwrap_or_default(),
7024                ),
7025                Err(err) => (
7026                    FrameType::Error,
7027                    serde_json::to_vec(&ErrorBody::new(
7028                        REVERSE_REQUEST_UNHANDLED,
7029                        join_error_message(err),
7030                    ))
7031                    .unwrap_or_default(),
7032                ),
7033            }
7034        } else {
7035            let message = method_family.map_or_else(
7036                || "reverse request has no valid method".to_string(),
7037                |family| format!("no reverse-request handler is registered for {family}"),
7038            );
7039            (
7040                FrameType::Error,
7041                serde_json::to_vec(&ErrorBody::new(REVERSE_REQUEST_UNHANDLED, message))
7042                    .unwrap_or_default(),
7043            )
7044        };
7045
7046        if shared.ingress_handle(generation, handle.channel, handle.epoch) != Some(handle) {
7047            return;
7048        }
7049        let reply = match Frame::build_with_version(
7050            frame.header.ver,
7051            frame_type,
7052            Flags::new(false, Priority::Interactive, false),
7053            handle.channel,
7054            handle.epoch,
7055            frame.header.corr,
7056            body,
7057        ) {
7058            Ok(reply) => reply,
7059            Err(_) => return,
7060        };
7061        let writer = shared.lock_inner().writer.clone();
7062        if let Some(writer) = writer {
7063            let _ = writer
7064                .send(WriteCommand {
7065                    frame: reply,
7066                    pending: None,
7067                })
7068                .await;
7069        }
7070    });
7071}
7072
7073fn join_error_message(error: tokio::task::JoinError) -> String {
7074    if !error.is_panic() {
7075        return error.to_string();
7076    }
7077    let payload = error.into_panic();
7078    if let Some(message) = payload.downcast_ref::<String>() {
7079        return message.clone();
7080    }
7081    if let Some(message) = payload.downcast_ref::<&str>() {
7082        return (*message).to_string();
7083    }
7084    "reverse-request handler panicked".to_string()
7085}
7086
7087async fn reader_loop<R: AsyncRead + Unpin>(shared: Arc<Shared>, mut reader: R, generation: u64) {
7088    loop {
7089        match read_frame(&mut reader).await {
7090            Ok(Some(frame)) => {
7091                if !dispatch_frame(&shared, generation, frame).await {
7092                    return;
7093                }
7094            }
7095            Ok(None) => {
7096                shared.handle_generation_drop(generation, "subc connection closed".to_string());
7097                return;
7098            }
7099            Err(err) => {
7100                shared.handle_generation_drop(generation, err.to_string());
7101                return;
7102            }
7103        }
7104    }
7105}
7106
7107async fn dispatch_frame(shared: &Arc<Shared>, generation: u64, frame: Frame) -> bool {
7108    if !shared.record_inbound_if_current(generation) {
7109        return false;
7110    }
7111    if frame.header.channel != 0
7112        && !shared.validate_ingress_handle(generation, frame.header.channel, frame.header.epoch)
7113    {
7114        return true;
7115    }
7116
7117    if frame.header.ty == FrameType::Request && frame.header.channel != 0 {
7118        if let Some(handle) =
7119            shared.ingress_handle(generation, frame.header.channel, frame.header.epoch)
7120        {
7121            dispatch_reverse_request(shared, frame, handle);
7122        }
7123        return true;
7124    }
7125
7126    let key = PendingKey {
7127        generation,
7128        channel: frame.header.channel,
7129        epoch: frame.header.epoch,
7130        corr: frame.header.corr,
7131    };
7132
7133    if frame.header.channel == 0 && frame.header.ty == FrameType::Response {
7134        if let Some(expected) = shared.pending_expected_control_handle(key) {
7135            let echoes_expected = matches!(
7136                serde_json::from_slice::<ClientControlResponse>(&frame.body),
7137                Ok(ClientControlResponse::RoutePoll {
7138                    route_channel,
7139                    route_epoch,
7140                    ..
7141                }) if route_channel == expected.channel && route_epoch == expected.epoch
7142            );
7143            if !echoes_expected {
7144                shared.count_dropped_route_frame();
7145                return true;
7146            }
7147        }
7148    }
7149
7150    // A route.open handle is published before its waiter is resolved. The socket reader
7151    // cannot consume a following same-route frame until this synchronous install finishes.
7152    if frame.header.channel == 0
7153        && frame.header.ty == FrameType::Response
7154        && shared.pending_expects_route_open(key)
7155    {
7156        if let Ok((
7157            ClientControlResponse::RouteOpen {
7158                route_channel,
7159                route_epoch,
7160                ..
7161            },
7162            authority,
7163        )) = decode_route_open_response(&frame.body)
7164        {
7165            let reverse_requests = shared
7166                .pending_route_open_reverse_requests(key)
7167                .unwrap_or_default();
7168            let module = shared
7169                .lock_inner()
7170                .pending
7171                .get(&key)
7172                .and_then(|entry| entry.route_open_module.clone());
7173            let handle =
7174                RouteHandle::new_consumer(route_channel, route_epoch, generation, reverse_requests);
7175            shared.install_ingress_handle(handle);
7176            if let Some(target) = authority.target {
7177                let mut inner = shared.lock_inner();
7178                if inner.route_epochs.get(&handle.channel) == Some(&handle) {
7179                    inner.route_targets.insert(handle, target);
7180                }
7181            }
7182            if let Some(module) = module {
7183                shared
7184                    .lock_inner()
7185                    .route_modules
7186                    .insert(route_channel, module);
7187            }
7188        }
7189    }
7190
7191    match frame.header.ty {
7192        FrameType::Response => shared.settle_pending(
7193            key,
7194            PendingTerminal::Response {
7195                generation,
7196                body: frame.body,
7197                flags: frame.header.flags,
7198            },
7199        ),
7200        FrameType::Error => {
7201            let body =
7202                serde_json::from_slice::<ErrorBody>(&frame.body).unwrap_or_else(|err| ErrorBody {
7203                    code: "invalid_error_body".to_string(),
7204                    message: err.to_string(),
7205                    detail: None,
7206                });
7207            shared.settle_pending(
7208                key,
7209                PendingTerminal::Error {
7210                    body,
7211                    flags: frame.header.flags,
7212                },
7213            );
7214        }
7215        FrameType::StreamEnd => shared.settle_pending(key, PendingTerminal::StreamEnd),
7216        FrameType::StreamData => shared.route_stream_data(key, frame.body),
7217        FrameType::Push if frame.header.channel == 0 => {
7218            shared.control_push(&frame.body);
7219        }
7220        FrameType::Push => shared.route_push(
7221            RouteHandle::new(frame.header.channel, frame.header.epoch, generation),
7222            frame.body,
7223        ),
7224        FrameType::Goodbye if frame.header.channel == 0 => {
7225            shared.handle_generation_drop(generation, "subc sent GOODBYE".to_string());
7226            return false;
7227        }
7228        FrameType::Goodbye => {
7229            let handle = RouteHandle::new(frame.header.channel, frame.header.epoch, generation);
7230            let close_reason = shared.lock_inner().route_end(handle.channel);
7231            shared.invalidate_routes_for_handle(handle);
7232            let pending = {
7233                let mut inner = shared.lock_inner();
7234                drain_pending_handle(&mut inner.pending, handle, true)
7235            };
7236            settle_route_pending_entries(pending, "route closed by subc".to_string(), close_reason);
7237        }
7238        FrameType::Ping if frame.header.channel == 0 => {
7239            if let Ok(pong) = Frame::build_with_version(
7240                frame.header.ver,
7241                FrameType::Pong,
7242                frame.header.flags,
7243                0,
7244                0,
7245                frame.header.corr,
7246                Vec::new(),
7247            ) {
7248                let writer = shared.lock_inner().writer.clone();
7249                if let Some(writer) = writer {
7250                    let _ = writer
7251                        .send(WriteCommand {
7252                            frame: pong,
7253                            pending: None,
7254                        })
7255                        .await;
7256                }
7257            }
7258        }
7259        _ => {}
7260    }
7261    true
7262}
7263
7264impl Shared {
7265    /// Stamp after holding the same state lock that guards generation changes, so a
7266    /// late frame from an older reader can never vouch for a newly installed socket.
7267    ///
7268    /// PLACEMENT IS LOAD-BEARING: the single caller sits on the frame-read
7269    /// return, the one point every inbound frame passes before demux -- which
7270    /// is why one stamp suffices. A future fast path or drain-and-dispatch
7271    /// refactor that hands frames onward without crossing that point makes the
7272    /// stamp skippable, and the liveness watermark quietly stops meaning "the
7273    /// link delivered bytes": the cheapest correctness property in this file
7274    /// and the easiest to lose in a refactor.
7275    fn record_inbound_if_current(&self, generation: u64) -> bool {
7276        let inner = self.lock_inner();
7277        if inner.closed || inner.generation != generation || inner.writer.is_none() {
7278            return false;
7279        }
7280        self.last_inbound_ms
7281            .store(epoch_millis(), Ordering::Release);
7282        true
7283    }
7284
7285    fn generation_is_current(&self, generation: u64) -> bool {
7286        let inner = self.lock_inner();
7287        !inner.closed && inner.generation == generation && inner.writer.is_some()
7288    }
7289
7290    fn pending_expected_control_handle(&self, key: PendingKey) -> Option<RouteHandle> {
7291        self.lock_inner()
7292            .pending
7293            .get(&key)
7294            .and_then(|entry| entry.expected_control_handle)
7295    }
7296
7297    fn count_dropped_route_frame(&self) {
7298        let mut inner = self.lock_inner();
7299        inner.dropped_route_frames = inner.dropped_route_frames.saturating_add(1);
7300    }
7301
7302    fn pending_expects_route_open(&self, key: PendingKey) -> bool {
7303        self.lock_inner()
7304            .pending
7305            .get(&key)
7306            .is_some_and(|entry| entry.retain_late_route_open)
7307    }
7308
7309    fn pending_route_open_reverse_requests(
7310        &self,
7311        key: PendingKey,
7312    ) -> Option<ReverseRequestRegistry> {
7313        self.lock_inner()
7314            .pending
7315            .get(&key)
7316            .and_then(|entry| entry.route_open_reverse_requests.clone())
7317    }
7318
7319    fn ingress_handle(&self, generation: u64, channel: u16, epoch: u32) -> Option<RouteHandle> {
7320        let inner = self.lock_inner();
7321        let handle = inner.route_epochs.get(&channel).copied()?;
7322        (handle.connection_token() == generation && handle.epoch == epoch).then_some(handle)
7323    }
7324
7325    fn validate_ingress_handle(&self, generation: u64, channel: u16, epoch: u32) -> bool {
7326        let mut inner = self.lock_inner();
7327        let expected = RouteHandle::new(channel, epoch, generation);
7328        if inner.route_epochs.get(&channel) == Some(&expected) {
7329            true
7330        } else {
7331            inner.dropped_route_frames = inner.dropped_route_frames.saturating_add(1);
7332            false
7333        }
7334    }
7335
7336    fn install_ingress_handle(&self, handle: RouteHandle) {
7337        let mut inner = self.lock_inner();
7338        if !inner.closed && inner.generation == handle.connection_token() && inner.writer.is_some()
7339        {
7340            inner.route_end_reasons.remove(&handle.channel);
7341            inner.legacy_channel_reasons.remove(&handle.channel);
7342            inner.route_modules.remove(&handle.channel);
7343            if let Some(previous) = inner.route_epochs.insert(handle.channel, handle) {
7344                inner.route_targets.remove(&previous);
7345                if previous.reverse_request_registry_id() != handle.reverse_request_registry_id() {
7346                    release_reverse_request_registry(previous);
7347                }
7348            }
7349        }
7350    }
7351
7352    fn invalidate_routes_for_handle(&self, handle: RouteHandle) {
7353        let removed = {
7354            let mut inner = self.lock_inner();
7355            if inner.route_epochs.get(&handle.channel) != Some(&handle) {
7356                return;
7357            }
7358            inner.release_wire_slots(handle);
7359            let installed = inner.route_epochs.remove(&handle.channel).unwrap();
7360            inner.route_targets.remove(&handle);
7361            inner.retired_routes.remove(&handle);
7362            inner.retirement_goodbyes.remove(&handle);
7363            inner.push_event_receivers.remove(&handle);
7364            release_reverse_request_registry(installed);
7365            inner
7366                .remove_route_by_handle(handle)
7367                .into_iter()
7368                .collect::<Vec<_>>()
7369        };
7370        for route in removed {
7371            route.close();
7372        }
7373    }
7374}
7375
7376async fn retirement_goodbye_loop(shared: Arc<Shared>, generation: u64, notify: Arc<Notify>) {
7377    loop {
7378        let notified = notify.notified();
7379        let next = {
7380            let inner = shared.lock_inner();
7381            if inner.closed || inner.generation != generation || inner.writer.is_none() {
7382                return;
7383            }
7384            inner
7385                .retirement_queue
7386                .front()
7387                .map(|handle| (*handle, inner.writer.as_ref().unwrap().clone()))
7388        };
7389        let Some((handle, writer)) = next else {
7390            notified.await;
7391            continue;
7392        };
7393        let Ok(permit) = writer.reserve().await else {
7394            shared.handle_generation_drop(
7395                generation,
7396                "writer closed before retirement GOODBYE".into(),
7397            );
7398            return;
7399        };
7400        let mut inner = shared.lock_inner();
7401        if inner.closed || inner.generation != generation || inner.writer.is_none() {
7402            return;
7403        }
7404        if inner.retirement_queue.front() != Some(&handle) {
7405            continue;
7406        }
7407        inner.retirement_queue.pop_front();
7408        inner.retirement_goodbyes.remove(&handle);
7409        if inner.route_epochs.get(&handle.channel) == Some(&handle) {
7410            let frame = Frame::build(
7411                FrameType::Goodbye,
7412                Flags::new(false, Priority::Interactive, false),
7413                handle.channel,
7414                handle.epoch,
7415                0,
7416                Vec::new(),
7417            )
7418            .expect("header-only route GOODBYE is valid");
7419            // Queue admission and uninstallation share the lock. No new route
7420            // can claim this channel between those operations.
7421            permit.send(WriteCommand {
7422                frame,
7423                pending: None,
7424            });
7425        }
7426        inner.reap_retired_route(handle);
7427    }
7428}
7429
7430async fn writer_loop<W>(
7431    shared: Arc<Shared>,
7432    writer: W,
7433    mut rx: mpsc::Receiver<WriteCommand>,
7434    generation: u64,
7435) where
7436    W: AsyncWrite + Unpin,
7437{
7438    let mut writer = BufWriter::new(writer);
7439    while let Some(command) = rx.recv().await {
7440        if let Some(key) = command.pending {
7441            if !shared.mark_pending_accepted(key) {
7442                continue;
7443            }
7444        }
7445        if let Err(err) = write_frame(&mut writer, &command.frame).await {
7446            shared.handle_generation_drop_with_cause(
7447                generation,
7448                err.to_string(),
7449                OutcomeUnknownCause::WriterClosed,
7450            );
7451            return;
7452        }
7453        while let Ok(command) = rx.try_recv() {
7454            if let Some(key) = command.pending {
7455                if !shared.mark_pending_accepted(key) {
7456                    continue;
7457                }
7458            }
7459            if let Err(err) = write_frame(&mut writer, &command.frame).await {
7460                shared.handle_generation_drop_with_cause(
7461                    generation,
7462                    err.to_string(),
7463                    OutcomeUnknownCause::WriterClosed,
7464                );
7465                return;
7466            }
7467        }
7468        if let Err(err) = writer.flush().await.map_err(FrameIoError::Io) {
7469            shared.handle_generation_drop_with_cause(
7470                generation,
7471                err.to_string(),
7472                OutcomeUnknownCause::WriterClosed,
7473            );
7474            return;
7475        }
7476    }
7477}
7478
7479impl Shared {
7480    fn implicit_consumer_identity(&self) -> Option<ConsumerIdentity> {
7481        // Operator-app connections must not even consult the launch environment:
7482        // the nonce accessor can consume an inherited credential descriptor.
7483        if self.identity_from_environment && !self.claim_bound {
7484            consumer_identity_from_env()
7485        } else {
7486            None
7487        }
7488    }
7489
7490    fn activity_read_body(&self, request: impl serde::Serialize) -> Result<Vec<u8>, CallError> {
7491        #[derive(serde::Serialize)]
7492        struct ReadRequest<T> {
7493            #[serde(flatten)]
7494            request: T,
7495            #[serde(skip_serializing_if = "Option::is_none")]
7496            consumer_identity: Option<ConsumerIdentity>,
7497        }
7498        serde_json::to_vec(&ReadRequest {
7499            request,
7500            consumer_identity: self.implicit_consumer_identity(),
7501        })
7502        .map_err(|err| CallError::not_sent(format!("failed to encode activity read: {err}")))
7503    }
7504
7505    fn route_open_consumer_identity(
7506        &self,
7507        opts: &CallOptions,
7508    ) -> Result<Option<ConsumerIdentity>, CallError> {
7509        if self.claim_bound && opts.consumer_identity.is_some() {
7510            // Legacy nonce identities cannot describe a claim-bound connection.
7511            return Err(CallError::not_sent(
7512                "consumer identity conflicts with connection binding",
7513            ));
7514        }
7515        Ok(opts
7516            .consumer_identity
7517            .clone()
7518            .or_else(|| self.implicit_consumer_identity()))
7519    }
7520
7521    fn close_route_consumer_identity(
7522        &self,
7523        opts: &CloseRouteOptions,
7524    ) -> Result<Option<ConsumerIdentity>, CallError> {
7525        if self.claim_bound && opts.consumer_identity.is_some() {
7526            return Err(CallError::not_sent(
7527                "consumer identity conflicts with connection binding",
7528            ));
7529        }
7530        Ok(opts
7531            .consumer_identity
7532            .clone()
7533            .or_else(|| self.implicit_consumer_identity()))
7534    }
7535}
7536
7537fn route_open_consumer_capabilities(opts: &CallOptions) -> Option<Vec<String>> {
7538    opts.reverse_requests.seal();
7539    let mut capabilities = opts.reverse_requests.capabilities();
7540    capabilities.extend(opts.consumer_capabilities());
7541    capabilities.sort();
7542    capabilities.dedup();
7543    (!capabilities.is_empty()).then_some(capabilities)
7544}
7545
7546/// The role versions a route is opened and keyed with. An empty map declares
7547/// nothing, and the daemon forwards it as no field at all, so it is folded
7548/// into `None` here: otherwise `Some({})` and `None` would key two routes the
7549/// provider cannot tell apart.
7550fn route_open_role_versions(
7551    role_versions: Option<&BTreeMap<String, String>>,
7552) -> Option<BTreeMap<String, String>> {
7553    role_versions
7554        .filter(|role_versions| !role_versions.is_empty())
7555        .cloned()
7556}
7557
7558fn close_route_consumer_capabilities(opts: &CloseRouteOptions) -> Option<Vec<String>> {
7559    opts.reverse_requests.seal();
7560    let mut capabilities = opts.reverse_requests.capabilities();
7561    capabilities.extend(opts.consumer_capabilities());
7562    capabilities.sort();
7563    capabilities.dedup();
7564    (!capabilities.is_empty()).then_some(capabilities)
7565}
7566
7567fn consumer_identity_from_env() -> Option<ConsumerIdentity> {
7568    let module_id = std::env::var(SUBC_MODULE_ID_ENV)
7569        .ok()
7570        .filter(|value| !value.is_empty())?;
7571    // Through the process's one cached accessor, never a second read of the
7572    // descriptor. An accessor error (for example a process a module spawned,
7573    // which inherits the descriptor variable but not the pipe) opens the
7574    // route without identity: it never falls back to the environment copy,
7575    // because presenting the module's nonce is exactly what such a process
7576    // must no longer be able to do.
7577    let launch_nonce = crate::launch_nonce()
7578        .ok()
7579        .flatten()
7580        .map(|nonce| nonce.value().to_string())?;
7581    Some(ConsumerIdentity {
7582        module_id,
7583        launch_nonce,
7584    })
7585}
7586
7587fn validate_capability_for_resolution(capability: &str) -> Result<(), CallError> {
7588    if is_valid_capability_identifier(capability) {
7589        Ok(())
7590    } else {
7591        Err(CallError::InvalidCapabilityIdentifier {
7592            capability: capability.to_string(),
7593        })
7594    }
7595}
7596
7597fn capability_claimants(catalog: &CatalogList, capability: &str) -> Vec<String> {
7598    let mut claimants = catalog
7599        .modules
7600        .iter()
7601        .filter(|module| {
7602            module.capabilities.as_ref().is_some_and(|capabilities| {
7603                capabilities
7604                    .provides
7605                    .iter()
7606                    .any(|claim| claim == capability)
7607            })
7608        })
7609        .map(|module| module.module_id.clone())
7610        .collect::<Vec<_>>();
7611    claimants.sort();
7612    claimants
7613}
7614
7615fn epoch_millis() -> u64 {
7616    u64::try_from(
7617        SystemTime::now()
7618            .duration_since(UNIX_EPOCH)
7619            .unwrap_or_default()
7620            .as_millis(),
7621    )
7622    .unwrap_or(u64::MAX)
7623}
7624
7625/// Reclassify a route-open failure seen by a managed `call` or `subscribe`.
7626///
7627/// `ensure_route` reports the route.open control request's own outcome, which
7628/// is `OutcomeUnknown` when that request was written but its reply did not
7629/// arrive before the deadline: the daemon may or may not have opened the
7630/// channel. The caller's request body, however, is only written after a route
7631/// is in hand, so when no route came back the body provably never left the
7632/// client. From the caller's point of view that is `NotSent`, and reporting
7633/// `OutcomeUnknown` would wrongly tell it a non-idempotent operation might
7634/// have run. A route.open reply that arrives after its waiter gave up is still
7635/// cleaned up: `settle_pending` sends that channel a GOODBYE instead of caching
7636/// it, so reporting `NotSent` here leaves no route open behind.
7637/// A uniform value in [0, 1) for retry jitter. Jitter needs spread, not
7638/// unpredictability, so this hashes a counter with std's randomly keyed hasher
7639/// instead of taking a dependency on a random-number crate.
7640fn default_random_unit() -> f64 {
7641    use std::hash::{BuildHasher, RandomState};
7642    static COUNTER: AtomicU64 = AtomicU64::new(0);
7643    let bits = RandomState::new().hash_one(COUNTER.fetch_add(1, Ordering::Relaxed));
7644    // The top 53 bits fill an f64 mantissa exactly.
7645    (bits >> 11) as f64 / (1u64 << 53) as f64
7646}
7647
7648fn request_not_sent_after_route_open_failure(err: CallError) -> CallError {
7649    match err {
7650        CallError::OutcomeUnknown(source) => CallError::not_sent_with_cause(
7651            format!("request not sent: route.open did not complete ({source})"),
7652            NotSentCause::RouteOpenAbandoned,
7653        ),
7654        other => other,
7655    }
7656}
7657
7658fn classify_failure(
7659    accepted: bool,
7660    reason: impl Into<String>,
7661    cause: OutcomeUnknownCause,
7662) -> CallError {
7663    classify_failure_with_not_sent_cause(accepted, reason, cause, NotSentCause::WriterRejected)
7664}
7665
7666fn classify_failure_with_not_sent_cause(
7667    accepted: bool,
7668    reason: impl Into<String>,
7669    cause: OutcomeUnknownCause,
7670    not_sent_cause: NotSentCause,
7671) -> CallError {
7672    if accepted {
7673        CallError::outcome_unknown(reason, cause)
7674    } else {
7675        CallError::not_sent_with_cause(reason, not_sent_cause)
7676    }
7677}
7678
7679fn settle_route_pending_entries(
7680    entries: Vec<PendingEntry>,
7681    message: String,
7682    reason: impl Into<RouteEnd>,
7683) {
7684    let reason = reason.into();
7685    let cause = if reason.reason == RouteEndReason::ConnectionLost {
7686        OutcomeUnknownCause::ConnectionFailed
7687    } else {
7688        OutcomeUnknownCause::RouteEnded
7689    };
7690    settle_route_pending_entries_with_cause(entries, message, reason, cause);
7691}
7692
7693fn settle_route_pending_entries_with_cause(
7694    entries: Vec<PendingEntry>,
7695    message: String,
7696    reason: impl Into<RouteEnd>,
7697    cause: OutcomeUnknownCause,
7698) {
7699    let reason = reason.into();
7700    for entry in entries {
7701        let err = if entry.accepted {
7702            CallError::outcome_unknown_source(OutcomeUnknownSource {
7703                message: message.clone(),
7704                cause,
7705                route_reason: Some(reason.clone()),
7706            })
7707        } else {
7708            CallError::NotSent(Box::new(NotSentSource {
7709                message: message.clone(),
7710                cause: NotSentCause::WriterRejected,
7711                never_forwarded: true,
7712                route_reason: Some(reason.clone()),
7713                refusal: None,
7714            }))
7715        };
7716        entry.settle_call_error(err);
7717    }
7718}
7719
7720fn settle_pending_entries(entries: Vec<PendingEntry>, reason: String) {
7721    for entry in entries {
7722        entry.settle_failure(reason.clone());
7723    }
7724}
7725
7726fn drain_pending_generation(
7727    pending: &mut HashMap<PendingKey, PendingEntry>,
7728    generation: u64,
7729) -> Vec<PendingEntry> {
7730    let keys = pending
7731        .keys()
7732        .copied()
7733        .filter(|key| key.generation == generation)
7734        .collect::<Vec<_>>();
7735    keys.into_iter()
7736        .filter_map(|key| pending.remove(&key))
7737        .collect()
7738}
7739
7740fn drain_pending_handle(
7741    pending: &mut HashMap<PendingKey, PendingEntry>,
7742    handle: RouteHandle,
7743    include_subscriptions: bool,
7744) -> Vec<PendingEntry> {
7745    let keys = pending
7746        .iter()
7747        .filter_map(|(key, entry)| {
7748            (key.generation == handle.connection_token()
7749                && key.channel == handle.channel
7750                && key.epoch == handle.epoch
7751                && (include_subscriptions || !entry.is_subscription()))
7752            .then_some(*key)
7753        })
7754        .collect::<Vec<_>>();
7755    keys.into_iter()
7756        .filter_map(|key| pending.remove(&key))
7757        .collect()
7758}
7759
7760fn fail_openings(openings: Vec<Vec<OpeningWaiter>>, failure: SharedCallFailure) {
7761    for waiters in openings {
7762        for waiter in waiters {
7763            let _ = waiter.send(Err(failure.clone()));
7764        }
7765    }
7766}
7767
7768fn emit_callbacks(callbacks: Vec<Callback>, state: ConnectionState) {
7769    for callback in callbacks {
7770        if let Ok(callback) = callback.lock() {
7771            callback(state.clone());
7772        }
7773    }
7774}
7775
7776/// The route-open retry predicate, defined once in `subc_protocol::error_codes`
7777/// so consumers with their own connection layer share it rather than copy it.
7778pub fn is_retryable_route_open_code(code: &str) -> bool {
7779    error_codes::is_retryable_route_open(code)
7780}
7781
7782/// Whether a data-plane ERROR answering a managed call's request is the
7783/// daemon's drain refusal, `module_reloading`, which the call may resend once
7784/// after reopening the route.
7785///
7786/// On an established route the daemon answers `module_reloading` only when the
7787/// module's endpoint is draining and the request could not take a route
7788/// credit, and it answers BEFORE forwarding (`ForwardBackend::handle_bound` in
7789/// subc-daemon's `router.rs`), so the module never received the request and a
7790/// resend cannot run it twice. The protocol documents that guarantee on
7791/// `error_codes::MODULE_RELOADING`.
7792///
7793/// Kept apart from `error_codes::is_established_route_dead` on purpose. That
7794/// shared predicate decides route DEATH, and other consumers map it to their
7795/// own custody, provider or suspect verdicts; adding a drain code there would
7796/// change those verdicts on a protocol bump. Here the code only earns the same
7797/// remedy (evict, reopen, resend once) inside this client's unary call path.
7798fn is_data_plane_drain_refusal(code: &str) -> bool {
7799    code == error_codes::MODULE_RELOADING
7800}
7801
7802// 0.37.15 is the first daemon that marks its own errors and strips the bit from module frames.
7803const DAEMON_ORIGIN_MIN_VERSION: (u64, u64, u64) = (0, 37, 15);
7804
7805/// Whether a connected daemon strips forged `DAEMON_ORIGIN` flags from module
7806/// frames: only exact numeric `major.minor.patch` versions at least 0.37.15.
7807/// Unknown versions, including pre-release and build suffixes, fail closed.
7808///
7809/// Pass the version from the same `ConnectionInfo` used by a successful
7810/// `authenticate_client` handshake. That handshake checks the daemon id against
7811/// the file, but its HMAC does not cover the version itself. Do not re-read the
7812/// file to classify a connection that is already authenticated.
7813pub fn trusts_daemon_origin(daemon_ver: &str) -> bool {
7814    daemon_version_at_least(daemon_ver, DAEMON_ORIGIN_MIN_VERSION)
7815}
7816
7817fn daemon_version_at_least(daemon_ver: &str, minimum: (u64, u64, u64)) -> bool {
7818    let mut components = daemon_ver.split('.');
7819    let mut next = || {
7820        let component = components.next()?;
7821        if component.is_empty() || !component.bytes().all(|byte| byte.is_ascii_digit()) {
7822            return None;
7823        }
7824        component.parse::<u64>().ok()
7825    };
7826    let version = (next(), next(), next());
7827    match version {
7828        (Some(major), Some(minor), Some(patch)) if components.next().is_none() => {
7829            (major, minor, patch) >= minimum
7830        }
7831        _ => false,
7832    }
7833}
7834
7835/// Whether an Error frame proves that its request was never forwarded.
7836///
7837/// This covers only `module_reloading`, `unknown_channel` and
7838/// `stale_route_epoch` with `DAEMON_ORIGIN`, when `daemon_origin_trusted` came
7839/// from [`trusts_daemon_origin`] for this connection's authenticated daemon
7840/// (0.37.15 or later). It proves only this attempt, not any earlier attempts of
7841/// a call. For managed calls use [`CallError::never_forwarded`] instead.
7842/// Unmarked errors and untrusted daemon versions never prove non-delivery.
7843/// This helper cannot see route negotiation and does not classify `route_busy`;
7844/// SDK-managed requests on opted-in routes handle that refusal internally.
7845pub fn is_daemon_refusal_before_forward(
7846    daemon_origin_trusted: bool,
7847    flags: Flags,
7848    code: &str,
7849) -> bool {
7850    daemon_origin_trusted
7851        && flags.is_daemon_origin()
7852        && matches!(
7853            code,
7854            error_codes::MODULE_RELOADING
7855                | error_codes::UNKNOWN_CHANNEL
7856                | error_codes::STALE_ROUTE_EPOCH
7857        )
7858}
7859
7860/// Whether `handle` names a route installed on the current connection. Channel 0 is the
7861/// connection's own control channel: it is never installed as a route and is current for
7862/// as long as the connection is, so a held channel-0 request (the spawn stream) can be
7863/// cancelled like a route subscription.
7864fn route_is_installed(inner: &Inner, handle: RouteHandle) -> bool {
7865    handle.channel == 0 || inner.route_epochs.get(&handle.channel) == Some(&handle)
7866}
7867
7868fn is_retryable_catalog_transport_error(err: &CallError) -> bool {
7869    matches!(err, CallError::NotSent(_) | CallError::OutcomeUnknown(_))
7870}
7871
7872fn is_reconnect_transient(err: &ConsumerError) -> bool {
7873    if let ConsumerError::Connect { source, .. } = err {
7874        if let Some(claim) = source
7875            .get_ref()
7876            .and_then(|source| source.downcast_ref::<crate::ClaimError>())
7877        {
7878            return matches!(claim, crate::ClaimError::Refused { code } if error_codes::is_retryable_claim(code));
7879        }
7880    }
7881    match err {
7882        ConsumerError::Connect { source, .. } => matches!(
7883            source.kind(),
7884            io::ErrorKind::ConnectionRefused
7885                | io::ErrorKind::ConnectionReset
7886                | io::ErrorKind::ConnectionAborted
7887                | io::ErrorKind::TimedOut
7888                | io::ErrorKind::NotConnected
7889                | io::ErrorKind::AddrNotAvailable
7890        ),
7891        ConsumerError::ConnectionFile { source, .. } => match source {
7892            ConnectionFileError::Io { source, .. } => source.kind() == io::ErrorKind::NotFound,
7893            _ => false,
7894        },
7895        // Auth failure is transient during reconnect: the daemon rotates its key
7896        // on every restart, and with a fixed port a client racing the restart can
7897        // read the pre-rotation connection file yet still connect — the proof
7898        // mismatch then means "stale key mid-rotation", not "impostor". Each
7899        // retry re-reads the connection file (open_connection), so the next
7900        // attempt picks up the rotated key, and server-proves-first protects
7901        // every attempt. First-connect auth failures stay permanent: connect()
7902        // surfaces them directly without entering the reconnect classifier.
7903        ConsumerError::Auth { .. } => true,
7904        ConsumerError::Discovery { .. }
7905        | ConsumerError::NoEndpoint { .. }
7906        | ConsumerError::Closed => false,
7907    }
7908}
7909
7910impl From<FrameBuildError> for CallError {
7911    fn from(err: FrameBuildError) -> Self {
7912        Self::not_sent(err.to_string())
7913    }
7914}
7915
7916#[cfg(test)]
7917mod local_transport_tests;
7918
7919#[cfg(test)]
7920mod tests {
7921    use super::*;
7922
7923    mod busy_refusals_tests;
7924    mod not_sent_tests;
7925    mod route_close_tests;
7926    mod route_deadline_tests;
7927
7928    #[derive(Clone)]
7929    struct InstrumentedWriter {
7930        state: Arc<InstrumentedWriterState>,
7931        fail_flush: bool,
7932    }
7933
7934    #[derive(Default)]
7935    struct InstrumentedWriterState {
7936        bytes: Mutex<Vec<u8>>,
7937        flushes: std::sync::atomic::AtomicUsize,
7938    }
7939
7940    impl InstrumentedWriter {
7941        fn new(fail_flush: bool) -> Self {
7942            Self {
7943                state: Arc::new(InstrumentedWriterState::default()),
7944                fail_flush,
7945            }
7946        }
7947
7948        fn bytes(&self) -> Vec<u8> {
7949            self.state
7950                .bytes
7951                .lock()
7952                .unwrap_or_else(|poisoned| poisoned.into_inner())
7953                .clone()
7954        }
7955
7956        fn flush_count(&self) -> usize {
7957            self.state.flushes.load(Ordering::SeqCst)
7958        }
7959    }
7960
7961    impl AsyncWrite for InstrumentedWriter {
7962        fn poll_write(
7963            self: Pin<&mut Self>,
7964            _cx: &mut Context<'_>,
7965            buf: &[u8],
7966        ) -> Poll<io::Result<usize>> {
7967            self.state
7968                .bytes
7969                .lock()
7970                .unwrap_or_else(|poisoned| poisoned.into_inner())
7971                .extend_from_slice(buf);
7972            Poll::Ready(Ok(buf.len()))
7973        }
7974
7975        fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
7976            self.state.flushes.fetch_add(1, Ordering::SeqCst);
7977            if self.fail_flush {
7978                Poll::Ready(Err(io::Error::new(
7979                    io::ErrorKind::BrokenPipe,
7980                    "instrumented flush failure",
7981                )))
7982            } else {
7983                Poll::Ready(Ok(()))
7984            }
7985        }
7986
7987        fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
7988            Poll::Ready(Ok(()))
7989        }
7990    }
7991
7992    fn writer_test_shared() -> Arc<Shared> {
7993        Arc::new(reader_skew_tests::legacy_shared(
7994            PathBuf::from("/tmp/does-not-exist"),
7995            ConsumerOptions {
7996                reconnect_backoff: RetryBackoff {
7997                    max_attempts: 1,
7998                    ..RetryBackoff::default()
7999                },
8000                ..ConsumerOptions::default()
8001            },
8002        ))
8003    }
8004
8005    fn reverse_test_shared(
8006        reverse_requests: ReverseRequestRegistry,
8007    ) -> (Arc<Shared>, mpsc::Receiver<WriteCommand>, RouteHandle) {
8008        let shared = writer_test_shared();
8009        let (writer, receiver) = mpsc::channel(16);
8010        let handle = RouteHandle::new_consumer(17, 3, 1, reverse_requests);
8011        {
8012            let mut inner = shared.lock_inner();
8013            inner.writer = Some(writer);
8014            inner.daemon_ver = "0.39.0".into();
8015            inner.route_epochs.insert(handle.channel, handle);
8016        }
8017        (shared, receiver, handle)
8018    }
8019
8020    fn reverse_request_frame(handle: RouteHandle, corr: u64, body: Vec<u8>) -> Frame {
8021        Frame::build(
8022            FrameType::Request,
8023            Flags::new(false, Priority::Interactive, false),
8024            handle.channel,
8025            handle.epoch,
8026            corr,
8027            body,
8028        )
8029        .unwrap()
8030    }
8031
8032    #[tokio::test]
8033    async fn binary_reply_request_preserves_flagged_non_utf8_bytes() {
8034        let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8035        let consumer = SubcConsumer {
8036            shared: Arc::clone(&shared),
8037        };
8038        shared
8039            .install_one_shot_route(RouteState {
8040                handle,
8041                sem: Arc::new(Semaphore::new(1)),
8042                watch_sem: None,
8043                opted_in: false,
8044            })
8045            .unwrap();
8046        let request = tokio::spawn(async move {
8047            consumer
8048                .request(&handle, b"bytes".to_vec(), CallOptions::default())
8049                .await
8050        });
8051        let command = receiver.recv().await.unwrap();
8052        let bytes = vec![0, 0xff, 0x80, b'{'];
8053        let frame = Frame::build(
8054            FrameType::Response,
8055            Flags::new(true, Priority::Interactive, false),
8056            handle.channel,
8057            handle.epoch,
8058            command.frame.header.corr,
8059            bytes.clone(),
8060        )
8061        .unwrap();
8062        assert!(dispatch_frame(&shared, 1, frame).await);
8063        assert_eq!(request.await.unwrap().unwrap(), bytes);
8064    }
8065
8066    async fn capture_route_open(
8067        reverse_requests: ReverseRequestRegistry,
8068    ) -> (serde_json::Value, RouteHandle) {
8069        capture_route_open_with_options(CallOptions {
8070            reverse_requests,
8071            ..CallOptions::default()
8072        })
8073        .await
8074    }
8075
8076    async fn capture_route_open_with_options(
8077        opts: CallOptions,
8078    ) -> (serde_json::Value, RouteHandle) {
8079        let shared = writer_test_shared();
8080        let (writer, mut receiver) = mpsc::channel(4);
8081        shared.lock_inner().writer = Some(writer);
8082        shared.lock_inner().daemon_ver = "0.39.0".into();
8083        let consumer = SubcConsumer {
8084            shared: Arc::clone(&shared),
8085        };
8086        let task = tokio::spawn(async move {
8087            consumer
8088                .open_route(
8089                    RouteTarget::ToolProvider {
8090                        module_id: "reverse-provider".to_string(),
8091                    },
8092                    BindIdentity::new("test".to_string(), "reverse".to_string()),
8093                    opts,
8094                )
8095                .await
8096        });
8097        let command = receiver.recv().await.expect("route.open frame");
8098        let request = serde_json::from_slice(&command.frame.body).unwrap();
8099        let response_body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
8100            request_window: None,
8101            watch_window: None,
8102            route_channel: 17,
8103            route_epoch: 3,
8104        })
8105        .unwrap();
8106        assert!(
8107            dispatch_frame(
8108                &shared,
8109                1,
8110                response_frame(0, 0, command.frame.header.corr, response_body),
8111            )
8112            .await
8113        );
8114        let handle = task.await.unwrap().unwrap();
8115        (request, handle)
8116    }
8117
8118    /// Keep held subscriptions marked for drain accounting without marking ordinary requests.
8119    #[tokio::test]
8120    async fn held_subscriptions_set_the_flag_but_ordinary_requests_do_not() {
8121        let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8122        let call_shared = Arc::clone(&shared);
8123        let call = tokio::spawn(async move {
8124            call_shared
8125                .send_request(RequestSend {
8126                    binary: false,
8127                    expected_handle: Some(handle),
8128                    channel: handle.channel,
8129                    epoch: handle.epoch,
8130                    body: b"ordinary".to_vec(),
8131                    priority: Priority::Interactive,
8132                    admission_class: AdmissionClass::Normal,
8133                    deadline: Instant::now() + Duration::from_secs(1),
8134                    retain_late_route_open: false,
8135                    route_open_reverse_requests: None,
8136                })
8137                .await
8138        });
8139        let ordinary = receiver.recv().await.unwrap();
8140        assert_eq!(ordinary.frame.header.encode()[6] & FLAG_SUBSCRIPTION, 0);
8141        assert!(
8142            dispatch_frame(
8143                &shared,
8144                1,
8145                response_frame(
8146                    handle.channel,
8147                    handle.epoch,
8148                    ordinary.frame.header.corr,
8149                    Vec::new()
8150                ),
8151            )
8152            .await
8153        );
8154        assert!(call.await.unwrap().is_ok());
8155
8156        let permit = Arc::new(Semaphore::new(1)).acquire_owned().await.unwrap();
8157        let subscription = Arc::clone(&shared)
8158            .send_subscription(SubscriptionSend {
8159                expected_handle: Some(handle),
8160                channel: handle.channel,
8161                epoch: handle.epoch,
8162                body: b"held".to_vec(),
8163                priority: Priority::Interactive,
8164                admission_class: AdmissionClass::Normal,
8165                event_buffer: 1,
8166                deadline: Instant::now() + Duration::from_secs(1),
8167                permit: RoutePermit::legacy(permit),
8168            })
8169            .await
8170            .unwrap();
8171        let held = receiver.recv().await.unwrap();
8172        assert_ne!(
8173            held.frame.header.encode()[6] & FLAG_SUBSCRIPTION,
8174            0,
8175            "a held-open subscription must be marked for drain accounting"
8176        );
8177        drop(subscription);
8178        release_reverse_request_registry(handle);
8179    }
8180
8181    #[tokio::test]
8182    async fn registered_handlers_derive_route_open_consumer_capabilities() {
8183        let registry = ReverseRequestRegistry::new();
8184        registry
8185            .on_request("elicitation", |_body, _ctx| async { Vec::new() })
8186            .unwrap();
8187        let (request, handle) = capture_route_open(registry).await;
8188        assert_eq!(
8189            request.get("consumer_capabilities"),
8190            Some(&serde_json::json!(["elicitation"]))
8191        );
8192        release_reverse_request_registry(handle);
8193    }
8194
8195    #[tokio::test]
8196    async fn declared_consumer_capabilities_merge_with_handler_families_on_route_open() {
8197        let registry = ReverseRequestRegistry::new();
8198        registry
8199            .on_request("elicitation", |_body, _ctx| async { Vec::new() })
8200            .unwrap();
8201        let opts = CallOptions {
8202            reverse_requests: registry,
8203            ..CallOptions::default()
8204        }
8205        .with_consumer_capability("tool-result/v1")
8206        .unwrap()
8207        .with_consumer_capability("elicitation")
8208        .unwrap()
8209        .with_consumer_capability("tool-result/v1")
8210        .unwrap();
8211
8212        let (request, handle) = capture_route_open_with_options(opts).await;
8213        assert_eq!(
8214            request.get("consumer_capabilities"),
8215            Some(&serde_json::json!(["elicitation", "tool-result/v1"]))
8216        );
8217        release_reverse_request_registry(handle);
8218    }
8219
8220    #[test]
8221    fn invalid_consumer_capability_declarations_are_rejected_before_route_open() {
8222        let (shared, mut receiver) = {
8223            let shared = writer_test_shared();
8224            let (writer, receiver) = mpsc::channel(4);
8225            shared.lock_inner().writer = Some(writer);
8226            shared.lock_inner().daemon_ver = "0.39.0".into();
8227            (shared, receiver)
8228        };
8229        let too_long = "x".repeat(65);
8230        for invalid in [
8231            String::new(),
8232            "content v1".to_string(),
8233            "content\tv1".to_string(),
8234            "content\nv1".to_string(),
8235            "cöntent/v1".to_string(),
8236            "content/\u{7f}v1".to_string(),
8237            too_long,
8238        ] {
8239            let error = CallOptions::default()
8240                .with_consumer_capability(invalid.clone())
8241                .expect_err("invalid declarations must not produce route options");
8242            assert_eq!(error.capability(), invalid);
8243            assert!(
8244                receiver.try_recv().is_err(),
8245                "invalid declaration {invalid:?} must be rejected before any frame is queued"
8246            );
8247        }
8248        let close_error = CloseRouteOptions::default()
8249            .with_consumer_capability("bad value")
8250            .expect_err("close-route declarations use the same validation");
8251        assert_eq!(close_error.capability(), "bad value");
8252        let call_options = CallOptions::default()
8253            .with_consumer_capability("tool-result/v1")
8254            .unwrap();
8255        assert_eq!(
8256            call_options.consumer_capabilities(),
8257            vec!["tool-result/v1".to_string()]
8258        );
8259        let close_options = CloseRouteOptions::default()
8260            .with_consumer_capability("tool-result/v1")
8261            .unwrap();
8262        assert_eq!(
8263            close_options.consumer_capabilities(),
8264            vec!["tool-result/v1".to_string()]
8265        );
8266        shared.close_sync("test complete");
8267    }
8268
8269    #[tokio::test]
8270    async fn no_handlers_omit_consumer_capabilities_from_route_open() {
8271        let (request, handle) = capture_route_open(ReverseRequestRegistry::new()).await;
8272        assert!(!request
8273            .as_object()
8274            .unwrap()
8275            .contains_key("consumer_capabilities"));
8276        release_reverse_request_registry(handle);
8277    }
8278
8279    #[tokio::test]
8280    async fn reverse_request_without_handler_returns_typed_error_instead_of_silence() {
8281        let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8282        let body = serde_json::to_vec(&serde_json::json!({
8283            "jsonrpc": "2.0",
8284            "id": 1,
8285            "method": "elicitation/create",
8286            "params": {}
8287        }))
8288        .unwrap();
8289        assert!(dispatch_frame(&shared, 1, reverse_request_frame(handle, 800, body)).await);
8290        let reply = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8291            .await
8292            .unwrap()
8293            .unwrap()
8294            .frame;
8295        assert_eq!(reply.header.ty, FrameType::Error);
8296        assert_eq!(reply.header.corr, 800);
8297        let error: ErrorBody = serde_json::from_slice(&reply.body).unwrap();
8298        assert_eq!(error.code, REVERSE_REQUEST_UNHANDLED);
8299        release_reverse_request_registry(handle);
8300    }
8301
8302    #[tokio::test]
8303    async fn reverse_request_round_trip_preserves_raw_body_corr_and_response() {
8304        let registry = ReverseRequestRegistry::new();
8305        let seen = Arc::new(Mutex::new(None));
8306        let seen_by_handler = Arc::clone(&seen);
8307        let response = br#"{"jsonrpc":"2.0","id":9,"result":{"accepted":true}}"#.to_vec();
8308        let expected_response = response.clone();
8309        registry
8310            .on_request("elicitation", move |body, ctx| {
8311                *seen_by_handler
8312                    .lock()
8313                    .unwrap_or_else(|poisoned| poisoned.into_inner()) =
8314                    Some((body, ctx.corr, ctx.method));
8315                let response = response.clone();
8316                async move { response }
8317            })
8318            .unwrap();
8319        let (shared, mut receiver, handle) = reverse_test_shared(registry);
8320        let request_body =
8321            br#"{"jsonrpc":"2.0","id":9,"method":"elicitation/create","params":{"z":1,"a":2}}"#
8322                .to_vec();
8323        assert!(
8324            dispatch_frame(
8325                &shared,
8326                1,
8327                reverse_request_frame(handle, 801, request_body.clone()),
8328            )
8329            .await
8330        );
8331        let reply = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8332            .await
8333            .unwrap()
8334            .unwrap()
8335            .frame;
8336        assert_eq!(reply.header.ty, FrameType::Response);
8337        assert_eq!(reply.header.corr, 801);
8338        assert_eq!(reply.body, expected_response);
8339        assert_eq!(
8340            seen.lock()
8341                .unwrap_or_else(|poisoned| poisoned.into_inner())
8342                .clone(),
8343            Some((request_body, 801, "elicitation/create".to_string()))
8344        );
8345        release_reverse_request_registry(handle);
8346    }
8347
8348    #[tokio::test]
8349    async fn panicking_reverse_handler_returns_typed_refusal_and_sibling_request_resolves() {
8350        let registry = ReverseRequestRegistry::new();
8351        registry
8352            .on_request("sampling", |_body, _ctx| async move {
8353                panic!("person prompt exploded");
8354            })
8355            .unwrap();
8356        let (shared, mut receiver, handle) = reverse_test_shared(registry);
8357        let sibling_shared = Arc::clone(&shared);
8358        let sibling = tokio::spawn(async move {
8359            sibling_shared
8360                .send_request(RequestSend {
8361                    binary: false,
8362                    expected_handle: Some(handle),
8363                    channel: handle.channel,
8364                    epoch: handle.epoch,
8365                    body: b"sibling".to_vec(),
8366                    priority: Priority::Interactive,
8367                    admission_class: AdmissionClass::Normal,
8368                    deadline: Instant::now() + Duration::from_secs(1),
8369                    retain_late_route_open: false,
8370                    route_open_reverse_requests: None,
8371                })
8372                .await
8373        });
8374        let sibling_request = receiver.recv().await.unwrap();
8375        let reverse_body = serde_json::to_vec(&serde_json::json!({
8376            "method": "sampling/createMessage",
8377            "params": {}
8378        }))
8379        .unwrap();
8380        assert!(
8381            dispatch_frame(&shared, 1, reverse_request_frame(handle, 802, reverse_body),).await
8382        );
8383        assert!(
8384            dispatch_frame(
8385                &shared,
8386                1,
8387                response_frame(
8388                    handle.channel,
8389                    handle.epoch,
8390                    sibling_request.frame.header.corr,
8391                    b"ok".to_vec(),
8392                ),
8393            )
8394            .await
8395        );
8396        assert!(matches!(
8397            sibling.await.unwrap().unwrap(),
8398            TerminalFrame::Response { body, .. } if body == b"ok"
8399        ));
8400        let refusal = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8401            .await
8402            .unwrap()
8403            .unwrap()
8404            .frame;
8405        assert_eq!(refusal.header.ty, FrameType::Error);
8406        let error: ErrorBody = serde_json::from_slice(&refusal.body).unwrap();
8407        assert_eq!(error.code, REVERSE_REQUEST_UNHANDLED);
8408        assert!(error.message.contains("person prompt exploded"));
8409        assert!(shared.generation_is_current(1));
8410        release_reverse_request_registry(handle);
8411    }
8412
8413    fn reservation_stand_in(
8414        credit: usize,
8415        capacity: usize,
8416    ) -> (
8417        Arc<Shared>,
8418        SubcConsumer,
8419        mpsc::Receiver<WriteCommand>,
8420        RouteHandle,
8421        Arc<Semaphore>,
8422    ) {
8423        let shared = writer_test_shared();
8424        let (writer, rx) = mpsc::channel(capacity);
8425        shared.lock_inner().writer = Some(writer);
8426        shared.lock_inner().daemon_ver = "0.39.0".into();
8427        let handle = RouteHandle::new(5, 3, 1);
8428        let sem = Arc::new(Semaphore::new(credit));
8429        shared
8430            .install_one_shot_route(RouteState {
8431                handle,
8432                sem: Arc::clone(&sem),
8433                watch_sem: None,
8434                opted_in: false,
8435            })
8436            .unwrap();
8437        let consumer = SubcConsumer {
8438            shared: Arc::clone(&shared),
8439        };
8440        (shared, consumer, rx, handle, sem)
8441    }
8442
8443    #[tokio::test]
8444    async fn reservation_send_is_synchronous_and_uses_prevalidated_body() {
8445        let oversized = vec![0; subc_protocol::MAX_FRAME_BODY_LEN as usize + 1];
8446        assert!(matches!(
8447            RequestBody::new(oversized),
8448            Err(CallError::NotSent(_))
8449        ));
8450        let body = RequestBody::new(b"valid".to_vec()).unwrap();
8451        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8452        let reserved = consumer
8453            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8454            .await
8455            .unwrap();
8456        let corr = reserved.correlation_id();
8457        assert_eq!(shared.lock_inner().writer.as_ref().unwrap().capacity(), 0);
8458        assert!(rx.try_recv().is_err());
8459
8460        // A concrete tuple proves send returns without awaiting. Inspect the
8461        // writer queue before running the writer or polling PendingReply.
8462        let (sent_corr, reply): (CorrelationId, PendingReply) =
8463            reserved.send(body, CallOptions::default());
8464        assert_eq!(sent_corr, corr);
8465        let command = rx.try_recv().expect("send must enqueue without yielding");
8466        assert_eq!(command.frame.body, b"valid");
8467        assert_eq!(command.frame.header.corr, corr);
8468        assert_eq!(sem.available_permits(), 0);
8469        assert!(shared.mark_pending_accepted(command.pending.unwrap()));
8470        dispatch_frame(
8471            &shared,
8472            1,
8473            response_frame(handle.channel, handle.epoch, corr, b"reply".to_vec()),
8474        )
8475        .await;
8476        assert_eq!(reply.await.unwrap(), b"reply");
8477        assert_eq!(sem.available_permits(), 1);
8478        consumer.close().await;
8479    }
8480
8481    #[tokio::test]
8482    async fn reservation_drop_releases_route_credit_and_writer_capacity_without_sending() {
8483        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8484        let deadline = Instant::now() + Duration::from_secs(1);
8485        let first = consumer.reserve(&handle, deadline).await.unwrap();
8486        let second = consumer.reserve(&handle, deadline);
8487        tokio::pin!(second);
8488        assert_pending(second.as_mut()).await;
8489        assert_eq!(sem.available_permits(), 0);
8490        drop(first);
8491        let second = timeout_at(deadline, second).await.unwrap().unwrap();
8492        drop(second);
8493        assert_eq!(sem.available_permits(), 1);
8494        assert_eq!(shared.lock_inner().writer.as_ref().unwrap().capacity(), 1);
8495        assert!(shared.lock_inner().pending.is_empty());
8496        assert!(rx.try_recv().is_err());
8497        consumer.close().await;
8498    }
8499
8500    #[tokio::test]
8501    async fn reservation_route_closed_before_send_matches_an_ordinary_unwritten_request() {
8502        let (shared, consumer, mut rx, handle, _) = reservation_stand_in(2, 4);
8503        let reserved = consumer
8504            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8505            .await
8506            .unwrap();
8507        let ordinary = consumer.request(&handle, b"ordinary".to_vec(), CallOptions::default());
8508        tokio::pin!(ordinary);
8509        assert_pending(ordinary.as_mut()).await;
8510        let ordinary_command = rx.try_recv().unwrap();
8511        assert_eq!(ordinary_command.frame.body, b"ordinary");
8512        consumer
8513            .close_handle(&handle, CloseRouteOptions::default())
8514            .await
8515            .unwrap();
8516        let (_, reply) = reserved.send(
8517            RequestBody::new(b"reserved".to_vec()).unwrap(),
8518            CallOptions::default(),
8519        );
8520        let ordinary_error = ordinary.await.unwrap_err();
8521        let reserved_error = reply.await.unwrap_err();
8522        assert!(matches!(reserved_error, CallError::NotSent(_)));
8523        assert_eq!(
8524            reserved_error.close_reason(),
8525            Some(&RouteEndReason::ClosedByCaller)
8526        );
8527        assert_eq!(reserved_error.to_string(), ordinary_error.to_string());
8528        assert_eq!(reserved_error.close_reason(), ordinary_error.close_reason());
8529
8530        rx.close();
8531        let writer = InstrumentedWriter::new(false);
8532        writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8533        let bytes = writer.bytes();
8534        let mut bytes = bytes.as_slice();
8535        let frame = read_frame(&mut bytes).await.unwrap().unwrap();
8536        assert_eq!(frame.header.ty, FrameType::Goodbye);
8537        assert!(
8538            bytes.is_empty(),
8539            "the closed route's reserved request must not be written"
8540        );
8541        consumer.close().await;
8542    }
8543
8544    #[tokio::test]
8545    async fn reservation_connection_loss_after_send_preserves_existing_errors() {
8546        for written in [false, true] {
8547            let (shared, consumer, rx, handle, sem) = reservation_stand_in(1, 1);
8548            let reserved = consumer
8549                .reserve(&handle, Instant::now() + Duration::from_secs(1))
8550                .await
8551                .unwrap();
8552            let (_, reply) = reserved.send(
8553                RequestBody::new(b"request".to_vec()).unwrap(),
8554                CallOptions::default(),
8555            );
8556            let writer = InstrumentedWriter::new(written);
8557            if !written {
8558                shared.handle_generation_drop(1, "connection lost before dequeue".to_string());
8559            }
8560            writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8561            let err = reply.await.unwrap_err();
8562            assert_eq!(err.close_reason(), Some(&RouteEndReason::ConnectionLost));
8563            if written {
8564                // `outcome_cause` answers only for `OutcomeUnknown`, so this also
8565                // checks the variant without adding a spelling the
8566                // outcome_unknown_inventory test would have to count.
8567                assert_eq!(err.outcome_cause(), Some(OutcomeUnknownCause::WriterClosed));
8568                assert!(!writer.bytes().is_empty());
8569            } else {
8570                assert!(matches!(err, CallError::NotSent(_)));
8571                assert!(writer.bytes().is_empty());
8572            }
8573            assert_eq!(sem.available_permits(), 1);
8574            consumer.close().await;
8575        }
8576    }
8577
8578    #[tokio::test]
8579    async fn reservation_correlations_are_unique_and_match_frames_written_out_of_order() {
8580        let (shared, consumer, mut rx, handle, _) = reservation_stand_in(3, 3);
8581        let deadline = Instant::now() + Duration::from_secs(1);
8582        let first = consumer.reserve(&handle, deadline).await.unwrap();
8583        let second = consumer.reserve(&handle, deadline).await.unwrap();
8584        let third = consumer.reserve(&handle, deadline).await.unwrap();
8585        let ids = [
8586            first.correlation_id(),
8587            second.correlation_id(),
8588            third.correlation_id(),
8589        ];
8590        assert_eq!(ids.into_iter().collect::<HashSet<_>>().len(), 3);
8591        let opts = CallOptions {
8592            priority: Priority::Background,
8593            admission_class: AdmissionClass::Expedite,
8594            ..CallOptions::default()
8595        };
8596        let mut replies = Vec::new();
8597        for (reserved, expected_id, body) in [
8598            (third, ids[2], "third"),
8599            (first, ids[0], "first"),
8600            (second, ids[1], "second"),
8601        ] {
8602            let (corr, reply) = reserved.send(
8603                RequestBody::new(body.as_bytes().to_vec()).unwrap(),
8604                opts.clone(),
8605            );
8606            assert_eq!(corr, expected_id);
8607            replies.push((corr, body, reply));
8608        }
8609        rx.close();
8610        let writer = InstrumentedWriter::new(false);
8611        writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8612        let bytes = writer.bytes();
8613        let mut bytes = bytes.as_slice();
8614        for (corr, body, reply) in replies {
8615            let frame = read_frame(&mut bytes).await.unwrap().unwrap();
8616            assert_eq!(frame.header.ty, FrameType::Request);
8617            assert_eq!(frame.header.corr, corr);
8618            assert_eq!(frame.header.channel, handle.channel);
8619            assert_eq!(frame.header.epoch, handle.epoch);
8620            assert_eq!(
8621                frame.header.flags,
8622                Flags::new(false, Priority::Background, false)
8623                    .with_admission_class(AdmissionClass::Expedite)
8624            );
8625            assert_eq!(frame.body, body.as_bytes());
8626            dispatch_frame(
8627                &shared,
8628                1,
8629                response_frame(handle.channel, handle.epoch, corr, body.as_bytes().to_vec()),
8630            )
8631            .await;
8632            assert_eq!(reply.await.unwrap(), body.as_bytes());
8633        }
8634        assert!(bytes.is_empty());
8635        consumer.close().await;
8636    }
8637
8638    #[tokio::test(start_paused = true)]
8639    async fn reservation_deadline_before_send_prevents_writing_without_polling_reply() {
8640        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8641        let reserved = consumer
8642            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8643            .await
8644            .unwrap();
8645        tokio::time::advance(Duration::from_secs(2)).await;
8646        let (_, reply) = reserved.send(
8647            RequestBody::new(b"expired".to_vec()).unwrap(),
8648            CallOptions::default(),
8649        );
8650        rx.close();
8651        let writer = InstrumentedWriter::new(false);
8652        writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8653        assert!(writer.bytes().is_empty());
8654        assert!(matches!(reply.await, Err(CallError::NotSent(_))));
8655        assert_eq!(sem.available_permits(), 1);
8656        consumer.close().await;
8657    }
8658
8659    #[tokio::test(start_paused = true)]
8660    async fn reservation_deadline_bounds_writer_capacity_and_releases_credit() {
8661        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(2, 1);
8662        let first = consumer
8663            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8664            .await
8665            .unwrap();
8666        let second = consumer
8667            .reserve(&handle, Instant::now() + Duration::from_millis(25))
8668            .await;
8669        assert!(matches!(second, Err(CallError::NotSent(_))));
8670        assert_eq!(sem.available_permits(), 1);
8671        drop(first);
8672        assert_eq!(sem.available_permits(), 2);
8673        assert!(shared.lock_inner().pending.is_empty());
8674        assert!(rx.try_recv().is_err());
8675        consumer.close().await;
8676    }
8677
8678    #[tokio::test]
8679    async fn reservation_reconnect_during_writer_capacity_wait_fails_promptly_without_writing() {
8680        let (shared, consumer, mut old_rx, handle, sem) = reservation_stand_in(1, 1);
8681        let old_writer = shared.lock_inner().writer.clone().unwrap();
8682        let held_capacity = old_writer.reserve_owned().await.unwrap();
8683        let reserve = consumer.reserve(&handle, Instant::now() + Duration::from_secs(60));
8684        tokio::pin!(reserve);
8685        assert_pending(reserve.as_mut()).await;
8686        assert_eq!(sem.available_permits(), 0);
8687
8688        let mut replacement_rx = drop_and_replace_test_transport(&shared);
8689        assert_ne!(shared.lock_inner().generation, handle.connection_token());
8690        drop(held_capacity);
8691        let result = std::future::poll_fn(|cx| Poll::Ready(reserve.as_mut().poll(cx))).await;
8692        assert!(matches!(
8693            result,
8694            Poll::Ready(Err(CallError::StaleRouteHandle(stale))) if stale == handle
8695        ));
8696        assert!(shared.lock_inner().pending.is_empty());
8697        assert_eq!(sem.available_permits(), 1);
8698        assert!(old_rx.try_recv().is_err());
8699        assert!(replacement_rx.try_recv().is_err());
8700
8701        old_rx.close();
8702        replacement_rx.close();
8703        let writer = InstrumentedWriter::new(false);
8704        writer_loop(
8705            Arc::clone(&shared),
8706            writer.clone(),
8707            old_rx,
8708            handle.connection_token(),
8709        )
8710        .await;
8711        let generation = shared.lock_inner().generation;
8712        writer_loop(
8713            Arc::clone(&shared),
8714            writer.clone(),
8715            replacement_rx,
8716            generation,
8717        )
8718        .await;
8719        assert!(writer.bytes().is_empty());
8720        consumer.close().await;
8721    }
8722
8723    #[tokio::test]
8724    async fn reservation_reply_drop_cleans_up_without_polling() {
8725        let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8726        let reserved = consumer
8727            .reserve(&handle, Instant::now() + Duration::from_secs(1))
8728            .await
8729            .unwrap();
8730        let (_, reply) = reserved.send(
8731            RequestBody::new(b"request".to_vec()).unwrap(),
8732            CallOptions::default(),
8733        );
8734        drop(reply);
8735        assert!(shared.lock_inner().pending.is_empty());
8736        assert_eq!(sem.available_permits(), 1);
8737        rx.close();
8738        let writer = InstrumentedWriter::new(false);
8739        writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8740        assert!(writer.bytes().is_empty());
8741        consumer.close().await;
8742    }
8743
8744    #[tokio::test]
8745    async fn writer_batches_ready_frames_into_one_flush() {
8746        const FRAME_COUNT: usize = 8;
8747
8748        let shared = writer_test_shared();
8749        let (live_writer, _live_rx) = mpsc::channel(1);
8750        let (tx, rx) = mpsc::channel(FRAME_COUNT + 1);
8751        let instrumented = InstrumentedWriter::new(false);
8752        let observer = instrumented.clone();
8753        let mut expected = Vec::with_capacity(FRAME_COUNT);
8754        let mut keys = Vec::with_capacity(FRAME_COUNT);
8755
8756        {
8757            let mut inner = shared.lock_inner();
8758            inner.writer = Some(live_writer);
8759            inner.daemon_ver = "0.39.0".into();
8760            for index in 0..FRAME_COUNT {
8761                let corr = index as u64 + 1;
8762                let frame = response_frame(7, 1, corr, vec![index as u8; index + 1]);
8763                let key = PendingKey {
8764                    generation: 1,
8765                    channel: 7,
8766                    epoch: 1,
8767                    corr,
8768                };
8769                let (pending_tx, _pending_rx) = oneshot::channel();
8770                inner
8771                    .pending
8772                    .insert(key, PendingEntry::unary(pending_tx, false, None, None));
8773                expected.push(frame.clone());
8774                keys.push(key);
8775                tx.try_send(WriteCommand {
8776                    frame,
8777                    pending: Some(key),
8778                })
8779                .expect("the burst should fit in the writer queue");
8780                if index == 0 {
8781                    tx.try_send(WriteCommand {
8782                        frame: response_frame(7, 1, 999, b"skip".to_vec()),
8783                        pending: Some(PendingKey {
8784                            generation: 1,
8785                            channel: 7,
8786                            epoch: 1,
8787                            corr: 999,
8788                        }),
8789                    })
8790                    .expect("the skipped command should fit in the writer queue");
8791                }
8792            }
8793        }
8794        drop(tx);
8795
8796        writer_loop(Arc::clone(&shared), instrumented, rx, 1).await;
8797
8798        {
8799            let inner = shared.lock_inner();
8800            for key in keys {
8801                assert!(
8802                    inner.pending.get(&key).is_some_and(|entry| entry.accepted),
8803                    "every written command must be marked accepted"
8804                );
8805            }
8806        }
8807
8808        let mut wire = std::io::Cursor::new(observer.bytes());
8809        for expected_frame in expected {
8810            let actual = read_frame(&mut wire)
8811                .await
8812                .expect("the emitted frame should decode")
8813                .expect("the emitted frame should be present");
8814            assert_eq!(actual, expected_frame);
8815        }
8816        assert!(
8817            read_frame(&mut wire)
8818                .await
8819                .expect("the end of the emitted burst should be clean")
8820                .is_none(),
8821            "the writer must not emit extra frames"
8822        );
8823
8824        let flush_count = observer.flush_count();
8825        assert_eq!(
8826            flush_count, 1,
8827            "a ready burst must be coalesced into one flush"
8828        );
8829        shared.close_sync("test complete");
8830    }
8831
8832    #[tokio::test]
8833    async fn writer_flush_failure_drops_generation_and_preserves_acceptance_classification() {
8834        let shared = writer_test_shared();
8835        let (live_writer, _live_rx) = mpsc::channel(1);
8836        let accepted_key = PendingKey {
8837            generation: 1,
8838            channel: 3,
8839            epoch: 1,
8840            corr: 1,
8841        };
8842        let not_sent_key = PendingKey {
8843            corr: 2,
8844            ..accepted_key
8845        };
8846        let (accepted_tx, accepted_rx) = oneshot::channel();
8847        let (not_sent_tx, not_sent_rx) = oneshot::channel();
8848        {
8849            let mut inner = shared.lock_inner();
8850            inner.writer = Some(live_writer);
8851            inner.daemon_ver = "0.39.0".into();
8852            inner.pending.insert(
8853                accepted_key,
8854                PendingEntry::unary(accepted_tx, false, None, None),
8855            );
8856            inner.pending.insert(
8857                not_sent_key,
8858                PendingEntry::unary(not_sent_tx, false, None, None),
8859            );
8860        }
8861
8862        let (tx, rx) = mpsc::channel(1);
8863        tx.send(WriteCommand {
8864            frame: response_frame(3, 1, accepted_key.corr, b"accepted".to_vec()),
8865            pending: Some(accepted_key),
8866        })
8867        .await
8868        .unwrap();
8869        drop(tx);
8870
8871        writer_loop(Arc::clone(&shared), InstrumentedWriter::new(true), rx, 1).await;
8872
8873        assert!(
8874            shared.lock_inner().writer.is_none(),
8875            "a flush failure must drop the active generation"
8876        );
8877        let accepted_error = accepted_rx
8878            .await
8879            .expect("the accepted request should be settled")
8880            .into_call_result()
8881            .unwrap_err();
8882        assert!(matches!(accepted_error, CallError::OutcomeUnknown(_)));
8883        assert_eq!(
8884            accepted_error.outcome_cause(),
8885            Some(OutcomeUnknownCause::WriterClosed)
8886        );
8887        let not_sent_error = not_sent_rx
8888            .await
8889            .expect("the unwritten request should be settled")
8890            .into_call_result()
8891            .unwrap_err();
8892        assert!(matches!(not_sent_error, CallError::NotSent(_)));
8893        assert_eq!(not_sent_error.outcome_cause(), None);
8894        shared.close_sync("test complete");
8895    }
8896
8897    #[tokio::test]
8898    async fn consumer_close_attaches_outcome_cause_to_pending_call() {
8899        let shared = writer_test_shared();
8900        let (writer, _writer_rx) = mpsc::channel(1);
8901        shared.lock_inner().writer = Some(writer);
8902        shared.lock_inner().daemon_ver = "0.39.0".into();
8903        let (tx, rx) = oneshot::channel();
8904        let mut entry = PendingEntry::unary(tx, false, None, None);
8905        entry.accepted = true;
8906        shared.lock_inner().pending.insert(
8907            PendingKey {
8908                generation: 1,
8909                channel: 3,
8910                epoch: 1,
8911                corr: 1,
8912            },
8913            entry,
8914        );
8915        let consumer = SubcConsumer { shared };
8916        consumer.close().await;
8917        let err = rx.await.unwrap().into_call_result().unwrap_err();
8918        assert_eq!(
8919            err.outcome_cause(),
8920            Some(OutcomeUnknownCause::ConsumerClosed)
8921        );
8922        assert_eq!(err.to_string(), "request outcome unknown: consumer closed");
8923        assert_eq!(err.close_reason(), None);
8924    }
8925
8926    #[tokio::test]
8927    async fn subscription_completion_drop_attaches_outcome_cause() {
8928        let (tx, rx) = oneshot::channel();
8929        let closed = SubscriptionClosed { rx };
8930        drop(tx);
8931        let err = closed.await.unwrap_err();
8932        assert_eq!(
8933            err.outcome_cause(),
8934            Some(OutcomeUnknownCause::CompletionFailed)
8935        );
8936        assert_eq!(
8937            err.to_string(),
8938            "request outcome unknown: subscription closed result channel dropped"
8939        );
8940    }
8941
8942    #[test]
8943    fn reconnect_classifier_treats_auth_failure_as_transient() {
8944        // Key rotation across a daemon restart on the fixed port: a client racing
8945        // the restart reads the pre-rotation file, connects, and fails the proof.
8946        // That must be retryable — each retry re-reads the file, so the next
8947        // attempt picks up the rotated key. Treating it as a permanent impostor
8948        // verdict would turn every daemon restart into a permanent client wedge.
8949        let auth = ConsumerError::Auth {
8950            path: PathBuf::from("/tmp/subc-connection.json"),
8951            endpoint: "127.0.0.1:8757".to_string(),
8952            source: subc_transport::AuthError::InvalidServerProof,
8953        };
8954        assert!(is_reconnect_transient(&auth), "rotation race must retry");
8955
8956        // Absent file mid-restart stays transient; malformed file stays permanent.
8957        let absent = ConsumerError::ConnectionFile {
8958            path: PathBuf::from("/tmp/subc-connection.json"),
8959            source: ConnectionFileError::Io {
8960                op: "read",
8961                path: PathBuf::from("/tmp/subc-connection.json"),
8962                source: io::Error::new(io::ErrorKind::NotFound, "gone"),
8963            },
8964        };
8965        assert!(is_reconnect_transient(&absent));
8966    }
8967
8968    #[tokio::test]
8969    async fn newer_drop_supersedes_reconnect_and_ignores_stale_completion() {
8970        let shared = Arc::new(reader_skew_tests::legacy_shared(
8971            PathBuf::from("/tmp/does-not-exist"),
8972            ConsumerOptions::default(),
8973        ));
8974        let stale_task = tokio::spawn(std::future::pending::<()>());
8975        {
8976            let mut inner = shared.lock_inner();
8977            inner.generation = 2;
8978            inner.reconnect = ReconnectState::Background {
8979                generation: 1,
8980                task: stale_task,
8981            };
8982        }
8983
8984        assert!(shared.spawn_reconnect(2));
8985        assert!(matches!(
8986            &shared.lock_inner().reconnect,
8987            ReconnectState::Background { generation, .. } if *generation == 2
8988        ));
8989
8990        shared.finish_background_reconnect(1);
8991        assert!(matches!(
8992            &shared.lock_inner().reconnect,
8993            ReconnectState::Background { generation, .. } if *generation == 2
8994        ));
8995        shared.close_sync("test complete");
8996    }
8997
8998    #[test]
8999    fn retryable_route_open_codes_are_code_specific() {
9000        for code in [
9001            "module_reloading",
9002            "module_warming",
9003            "target_unavailable",
9004            "module_timeout",
9005        ] {
9006            assert!(is_retryable_route_open_code(code), "{code} should retry");
9007        }
9008        // "No module of this id is registered or supervised here" is a typo or
9009        // an undeployed peer: the daemon reports a configured-but-late target
9010        // with module_warming/target_unavailable, so retrying unknown_module
9011        // in place only papers over an unsupervised module's HELLO race.
9012        assert!(
9013            !is_retryable_route_open_code(error_codes::UNKNOWN_MODULE),
9014            "unknown_module is terminal"
9015        );
9016        assert!(!is_retryable_route_open_code(error_codes::MODULE_REMOVED));
9017        assert!(!is_retryable_route_open_code("invalid_project_root"));
9018        assert!(!is_retryable_route_open_code("route_rejected"));
9019        assert!(
9020            !is_retryable_route_open_code("capability_forbidden"),
9021            "a capability policy refusal must not enter the route.open retry set"
9022        );
9023    }
9024
9025    #[test]
9026    fn two_routes_record_distinct_reasons_and_reuse_clears_channel() {
9027        let shared = Arc::new(reader_skew_tests::legacy_shared(
9028            PathBuf::new(),
9029            ConsumerOptions::default(),
9030        ));
9031        let (writer, _rx) = mpsc::channel(8);
9032        shared.lock_inner().writer = Some(writer);
9033        shared.lock_inner().daemon_ver = "0.39.0".into();
9034        shared.install_ingress_handle(RouteHandle::new(7, 1, 1));
9035        shared.install_ingress_handle(RouteHandle::new(9, 1, 1));
9036        {
9037            let mut inner = shared.lock_inner();
9038            inner.route_modules.insert(7, "provider".into());
9039            inner.route_modules.insert(9, "provider".into());
9040        }
9041        shared.control_push(br#"{"op":"route.closed","module_id":"provider","channels":[7],"reason":"scope_ended"}"#);
9042        shared.control_push(
9043            br#"{"op":"route.closing","module_id":"provider","channels":[9],"reason":"restart"}"#,
9044        );
9045        shared.control_push(
9046            br#"{"op":"route.closing","module_id":"provider","channels":[7],"reason":"crash"}"#,
9047        );
9048        assert_eq!(
9049            shared.lock_inner().route_end_reason(7),
9050            RouteEndReason::Daemon(RouteCloseReason::ScopeEnded)
9051        );
9052        assert_eq!(
9053            shared.lock_inner().route_end_reason(9),
9054            RouteEndReason::Daemon(RouteCloseReason::Restart)
9055        );
9056        shared.control_push(
9057            br#"{"op":"route.closed","module_id":"provider","channels":[9],"reason":"crash"}"#,
9058        );
9059        assert_eq!(
9060            shared.lock_inner().route_end_reason(9),
9061            RouteEndReason::Daemon(RouteCloseReason::Crash)
9062        );
9063        shared.control_push(br#"{"op":"route.closed","module_id":"provider","reason":"disable"}"#);
9064        shared.install_ingress_handle(RouteHandle::new(7, 2, 1));
9065        assert_eq!(
9066            shared.lock_inner().route_end_reason(7),
9067            RouteEndReason::Unknown
9068        );
9069        assert_eq!(shared.lock_inner().route_end(7).terminal, None);
9070    }
9071
9072    #[test]
9073    fn legacy_route_push_falls_back_only_when_channels_are_absent() {
9074        let shared = reader_skew_tests::legacy_shared(PathBuf::new(), ConsumerOptions::default());
9075        shared
9076            .lock_inner()
9077            .route_modules
9078            .insert(7, "provider".into());
9079        shared.control_push(
9080            br#"{"op":"route.closed","module_id":"provider","channels":[],"reason":"crash"}"#,
9081        );
9082        assert_eq!(
9083            shared.lock_inner().route_end_reason(7),
9084            RouteEndReason::Unknown
9085        );
9086        shared.control_push(br#"{"op":"route.closing","module_id":"provider","reason":"restart"}"#);
9087        assert_eq!(
9088            shared.lock_inner().route_end_reason(7),
9089            RouteEndReason::Daemon(RouteCloseReason::Restart)
9090        );
9091        shared.control_push(br#"{"op":"route.closed","module_id":"provider","reason":"crash"}"#);
9092        assert_eq!(
9093            shared.lock_inner().route_end_reason(7),
9094            RouteEndReason::Daemon(RouteCloseReason::Crash)
9095        );
9096    }
9097
9098    #[tokio::test]
9099    async fn sdk_teardown_paths_attach_caller_and_connection_loss_reasons() {
9100        for local in [true, false] {
9101            let shared = Arc::new(reader_skew_tests::legacy_shared(
9102                PathBuf::new(),
9103                ConsumerOptions::default(),
9104            ));
9105            let (writer, _writer_rx) = mpsc::channel(8);
9106            shared.lock_inner().writer = Some(writer);
9107            shared.lock_inner().daemon_ver = "0.39.0".into();
9108            let handle = RouteHandle::new(7, 1, 1);
9109            shared.install_ingress_handle(handle);
9110            let (tx, rx) = oneshot::channel();
9111            let mut entry = PendingEntry::unary(tx, false, None, None);
9112            entry.accepted = true;
9113            shared.lock_inner().pending.insert(
9114                PendingKey {
9115                    generation: 1,
9116                    channel: 7,
9117                    epoch: 1,
9118                    corr: 1,
9119                },
9120                entry,
9121            );
9122            if local {
9123                shared
9124                    .close_handle(handle, &CloseRouteOptions::default())
9125                    .await
9126                    .unwrap();
9127            } else {
9128                shared.handle_generation_drop(1, "connection gone".into());
9129            }
9130            let err = rx.await.unwrap().into_call_result().err().unwrap();
9131            assert!(matches!(err, CallError::OutcomeUnknown(_)));
9132            assert_eq!(
9133                err.outcome_cause(),
9134                Some(if local {
9135                    OutcomeUnknownCause::RouteEnded
9136                } else {
9137                    OutcomeUnknownCause::ConnectionFailed
9138                })
9139            );
9140            let shared_failure = SharedCallFailure::from(err);
9141            let err = shared_failure.into_call_error();
9142            assert_eq!(
9143                err.close_reason(),
9144                Some(&if local {
9145                    RouteEndReason::ClosedByCaller
9146                } else {
9147                    RouteEndReason::ConnectionLost
9148                })
9149            );
9150            shared.close_sync("test complete");
9151        }
9152    }
9153
9154    #[tokio::test]
9155    async fn route_end_reasons_preserve_pending_retry_classes() {
9156        for reason in [
9157            RouteEndReason::ClosedByCaller,
9158            RouteEndReason::ConnectionLost,
9159            RouteEndReason::Daemon(RouteCloseReason::ScopeEnded),
9160            RouteEndReason::Unknown,
9161        ] {
9162            for accepted in [false, true] {
9163                let (tx, rx) = oneshot::channel();
9164                let mut entry = PendingEntry::unary(tx, false, None, None);
9165                entry.accepted = accepted;
9166                settle_route_pending_entries(vec![entry], "route ended".into(), reason.clone());
9167                let err = rx.await.unwrap().into_call_result().err().unwrap();
9168                assert_eq!(err.close_reason(), Some(&reason));
9169                assert_eq!(err.terminal(), None);
9170                assert_eq!(matches!(err, CallError::OutcomeUnknown(_)), accepted);
9171                assert_eq!(matches!(err, CallError::NotSent(_)), !accepted);
9172            }
9173        }
9174    }
9175
9176    #[test]
9177    fn route_closing_does_not_supply_or_overwrite_a_terminal_verdict() {
9178        let shared = Shared::new(PathBuf::new(), ConsumerOptions::default());
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, None);
9183        shared.control_push(
9184            br#"{"op":"route.closed","channels":[7],"reason":"restart","terminal":false}"#,
9185        );
9186        shared.control_push(
9187            br#"{"op":"route.closing","channels":[7],"reason":"restart","terminal":true}"#,
9188        );
9189        assert_eq!(shared.lock_inner().route_end(7).terminal, Some(false));
9190        assert_eq!(CallError::not_sent("not a route end").terminal(), None);
9191    }
9192
9193    #[test]
9194    fn route_close_reason_classifier_accepts_capability_denied_and_fails_closed_for_unknown() {
9195        assert_eq!(
9196            RouteCloseReason::from_wire("capability_denied"),
9197            RouteCloseReason::CapabilityDenied
9198        );
9199        assert_eq!(
9200            RouteCloseReason::from_wire("capability_denied").disposition(),
9201            RouteCloseDisposition::MustNotReopen
9202        );
9203        assert_eq!(
9204            RouteCloseReason::from_wire("future_policy_reason").disposition(),
9205            RouteCloseDisposition::MustNotReopen,
9206            "an unknown close reason must receive the strictest handling"
9207        );
9208        assert_eq!(
9209            RouteCloseReason::from_wire("reload").disposition(),
9210            RouteCloseDisposition::MayReopen,
9211            "control proves the classifier can distinguish a conservative default"
9212        );
9213    }
9214
9215    #[tokio::test]
9216    async fn module_removed_fails_fast_while_module_reloading_retries_at_the_same_route_open_call_site(
9217    ) {
9218        // Serves rejections with `code` until the caller settles, returning
9219        // (attempts_served, result). The retryable arm must keep retrying past
9220        // any attempt count until the DEADLINE binds — the attempt cap in the
9221        // options below is deliberately tiny so a regression that re-couples
9222        // attempts into the retry condition (the 3.1s-effective-budget defect)
9223        // stops the loop at 2 and fails the `> 2` assertion by name.
9224        async fn reject_route_open_attempts(code: &str, deadline: Duration) -> (usize, CallError) {
9225            let shared = Arc::new(reader_skew_tests::legacy_shared(
9226                PathBuf::from("/tmp/does-not-exist"),
9227                ConsumerOptions::default(),
9228            ));
9229            let (writer, mut receiver) = mpsc::channel(4);
9230            {
9231                let mut inner = shared.lock_inner();
9232                inner.writer = Some(writer);
9233                inner.daemon_ver = "0.39.0".into();
9234            }
9235            let consumer = SubcConsumer {
9236                shared: Arc::clone(&shared),
9237            };
9238            let target = RouteTarget::ToolProvider {
9239                module_id: "retry-polarity".to_string(),
9240            };
9241            let identity = BindIdentity::new("test".to_string(), code.to_string());
9242            let options = CallOptions {
9243                timeout: Duration::from_secs(2),
9244                route_retry: RetryBackoff {
9245                    base: Duration::ZERO,
9246                    cap: Duration::ZERO,
9247                    max_attempts: 2,
9248                },
9249                route_retry_deadline: deadline,
9250                ..CallOptions::default()
9251            };
9252            let mut task =
9253                tokio::spawn(async move { consumer.open_route(target, identity, options).await });
9254
9255            let mut attempts = 0usize;
9256            let result = loop {
9257                tokio::select! {
9258                    command = receiver.recv() => {
9259                        // The consumer tears the writer down when the open
9260                        // settles, so a closed channel here means the task is
9261                        // finishing — join it rather than treating the race as
9262                        // a broken harness.
9263                        let Some(command) = command else {
9264                            break task.await.unwrap().expect_err("route.open must reject");
9265                        };
9266                        attempts += 1;
9267                        let body =
9268                            serde_json::to_vec(&ErrorBody::new(code, "test rejection")).unwrap();
9269                        assert!(
9270                            dispatch_frame(
9271                                &shared,
9272                                1,
9273                                Frame::build(
9274                                    FrameType::Error,
9275                                    Flags::new(false, Priority::Interactive, false),
9276                                    0,
9277                                    0,
9278                                    command.frame.header.corr,
9279                                    body,
9280                                )
9281                                .unwrap(),
9282                            )
9283                            .await
9284                        );
9285                    }
9286                    joined = &mut task => {
9287                        break joined.unwrap().expect_err("route.open must reject");
9288                    }
9289                }
9290            };
9291            assert!(
9292                receiver.try_recv().is_err(),
9293                "a settled route.open must not queue another attempt"
9294            );
9295            (attempts, result)
9296        }
9297
9298        let (reloading_attempts, reloading) =
9299            reject_route_open_attempts(error_codes::MODULE_RELOADING, Duration::from_millis(150))
9300                .await;
9301        assert!(matches!(reloading, CallError::NotSent(_)));
9302        assert!(
9303            reloading_attempts > 2,
9304            "reloading retries must run until the deadline, not an attempt cap \
9305             (served {reloading_attempts} attempts against max_attempts=2)"
9306        );
9307
9308        let (removed_attempts, removed) =
9309            reject_route_open_attempts(error_codes::MODULE_REMOVED, Duration::from_millis(150))
9310                .await;
9311        assert!(matches!(removed, CallError::NotSent(_)));
9312        assert_eq!(
9313            removed_attempts, 1,
9314            "terminal codes settle on the first answer"
9315        );
9316    }
9317
9318    /// splitmix64 over a counter: a seeded stand-in for the consumer's random
9319    /// source, so jittered delays are reproducible.
9320    fn seeded_random(seed: u64) -> Box<dyn Fn() -> f64 + Send + Sync> {
9321        let state = AtomicU64::new(seed);
9322        Box::new(move || {
9323            let mut z = state
9324                .fetch_add(0x9E37_79B9_7F4A_7C15, Ordering::Relaxed)
9325                .wrapping_add(0x9E37_79B9_7F4A_7C15);
9326            z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
9327            z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
9328            z ^= z >> 31;
9329            (z >> 11) as f64 / (1u64 << 53) as f64
9330        })
9331    }
9332
9333    /// A consumer wired to an in-memory writer, standing in for a daemon that
9334    /// the test answers by hand.
9335    fn route_open_stand_in(
9336        random_unit: Box<dyn Fn() -> f64 + Send + Sync>,
9337    ) -> (Arc<Shared>, Arc<SubcConsumer>, mpsc::Receiver<WriteCommand>) {
9338        let mut shared = reader_skew_tests::legacy_shared(
9339            PathBuf::from("/tmp/does-not-exist"),
9340            ConsumerOptions::default(),
9341        );
9342        shared.random_unit = random_unit;
9343        let shared = Arc::new(shared);
9344        let (writer, receiver) = mpsc::channel(64);
9345        shared.lock_inner().writer = Some(writer);
9346        shared.lock_inner().daemon_ver = "0.39.0".into();
9347        let consumer = Arc::new(SubcConsumer {
9348            shared: Arc::clone(&shared),
9349        });
9350        (shared, consumer, receiver)
9351    }
9352
9353    fn restart_target(module_id: &str) -> RouteTarget {
9354        RouteTarget::ToolProvider {
9355            module_id: module_id.to_string(),
9356        }
9357    }
9358
9359    fn restart_identity() -> BindIdentity {
9360        BindIdentity::new("test".to_string(), "restart".to_string())
9361    }
9362
9363    /// The daemon's answer to one route.open: accept it on `channel`, or refuse
9364    /// it with `refusal`.
9365    fn route_open_answer(corr: u64, channel: u16, refusal: Option<ErrorBody>) -> Frame {
9366        match refusal {
9367            None => response_frame(
9368                0,
9369                0,
9370                corr,
9371                serde_json::to_vec(&ClientControlResponse::RouteOpen {
9372                    request_window: None,
9373                    watch_window: None,
9374                    route_channel: channel,
9375                    route_epoch: 1,
9376                })
9377                .unwrap(),
9378            ),
9379            Some(body) => Frame::build(
9380                FrameType::Error,
9381                Flags::new(false, Priority::Interactive, false),
9382                0,
9383                0,
9384                corr,
9385                serde_json::to_vec(&body).unwrap(),
9386            )
9387            .unwrap(),
9388        }
9389    }
9390
9391    /// Answer every route.open the consumer writes, as `answer` decides from the
9392    /// open's target module, until `task` finishes.
9393    async fn answer_route_opens<T>(
9394        shared: &Arc<Shared>,
9395        receiver: &mut mpsc::Receiver<WriteCommand>,
9396        task: &mut JoinHandle<T>,
9397        mut answer: impl FnMut(&str) -> Option<ErrorBody>,
9398    ) -> T {
9399        let mut next_channel = 40u16;
9400        loop {
9401            tokio::select! {
9402                command = receiver.recv() => {
9403                    let Some(command) = command else {
9404                        return (&mut *task).await.unwrap();
9405                    };
9406                    let request: serde_json::Value =
9407                        serde_json::from_slice(&command.frame.body).unwrap();
9408                    let module_id = request["target"]["module_id"].as_str().unwrap().to_string();
9409                    next_channel += 1;
9410                    let frame = route_open_answer(
9411                        command.frame.header.corr,
9412                        next_channel,
9413                        answer(&module_id),
9414                    );
9415                    assert!(dispatch_frame(shared, 1, frame).await);
9416                }
9417                joined = &mut *task => return joined.unwrap(),
9418            }
9419        }
9420    }
9421
9422    fn reloading() -> ErrorBody {
9423        ErrorBody::new(error_codes::MODULE_RELOADING, "module is reloading")
9424    }
9425
9426    fn drain_call<'a>(
9427        consumer: &'a SubcConsumer,
9428        body: &'static [u8],
9429    ) -> impl Future<Output = Result<Vec<u8>, CallError>> + 'a {
9430        consumer.call(
9431            restart_target("plexus"),
9432            restart_identity(),
9433            body.to_vec(),
9434            CallOptions {
9435                timeout: Duration::from_secs(5),
9436                ..CallOptions::default()
9437            },
9438        )
9439    }
9440
9441    async fn refuse_during_drain(shared: &Arc<Shared>, request: &Frame) {
9442        let frame = Frame::build(
9443            FrameType::Error,
9444            request.header.flags,
9445            request.header.channel,
9446            request.header.epoch,
9447            request.header.corr,
9448            serde_json::to_vec(&reloading()).unwrap(),
9449        )
9450        .unwrap();
9451        assert!(dispatch_frame(shared, 1, frame).await);
9452    }
9453
9454    async fn reply_to_drain_call(shared: &Arc<Shared>, request: Frame) {
9455        assert_eq!(request.header.ty, FrameType::Request);
9456        assert!(
9457            dispatch_frame(
9458                shared,
9459                1,
9460                response_frame(
9461                    request.header.channel,
9462                    request.header.epoch,
9463                    request.header.corr,
9464                    request.body,
9465                ),
9466            )
9467            .await
9468        );
9469    }
9470
9471    #[tokio::test(start_paused = true)]
9472    async fn shared_route_drain_delivers_both_refusals_and_resends_both_calls() {
9473        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9474        let (_, old) = open_answered(
9475            &shared,
9476            &consumer,
9477            &mut receiver,
9478            None,
9479            41,
9480            "initial shared route",
9481        )
9482        .await;
9483        let mut seed = Box::pin(drain_call(&consumer, b"seed"));
9484        assert_pending(seed.as_mut()).await;
9485        reply_to_drain_call(&shared, receiver.recv().await.unwrap().frame).await;
9486        assert_eq!(seed.await.unwrap(), b"seed");
9487        shared.control_push(
9488            &serde_json::to_vec(&serde_json::json!({
9489                "op": "route.closing", "module_id": "plexus",
9490                "channels": [old.channel], "terminal": false
9491            }))
9492            .unwrap(),
9493        );
9494        let mut first = Box::pin(drain_call(&consumer, b"first"));
9495        let mut second = Box::pin(drain_call(&consumer, b"second"));
9496        assert_pending(first.as_mut()).await;
9497        assert_pending(second.as_mut()).await;
9498        let first_command = receiver.recv().await.unwrap();
9499        let second_command = receiver.recv().await.unwrap();
9500        // Observing a frame at the daemon means the real writer accepted it.
9501        assert!(shared.mark_pending_accepted(first_command.pending.unwrap()));
9502        assert!(shared.mark_pending_accepted(second_command.pending.unwrap()));
9503        let first_request = first_command.frame;
9504        let second_request = second_command.frame;
9505        assert_eq!(first_request.header.channel, old.channel);
9506        assert_eq!(second_request.header.channel, old.channel);
9507
9508        refuse_during_drain(&shared, &first_request).await;
9509        assert_pending(first.as_mut()).await;
9510        // Holding route.open unanswered is the barrier: the first call has
9511        // invalidated the old route before its sibling's refusal arrives.
9512        let (open_corr, _) = next_route_open(&mut receiver, "replacement route barrier").await;
9513        refuse_during_drain(&shared, &second_request).await;
9514        for (ty, channel, epoch, corr) in [
9515            (FrameType::Goodbye, old.channel, old.epoch, 0),
9516            (FrameType::Ping, 0, 0, 991),
9517        ] {
9518            let frame = Frame::build(
9519                ty,
9520                Flags::new(false, Priority::Interactive, false),
9521                channel,
9522                epoch,
9523                corr,
9524                Vec::new(),
9525            )
9526            .unwrap();
9527            assert!(dispatch_frame(&shared, 1, frame).await);
9528        }
9529        // The same dispatcher used by the socket reader emits Pong only after
9530        // processing the second refusal and the old-route GOODBYE.
9531        let pong = receiver.recv().await.unwrap().frame;
9532        assert_eq!(pong.header.ty, FrameType::Pong);
9533        assert_eq!(pong.header.corr, 991);
9534        assert_pending(second.as_mut()).await;
9535        assert!(dispatch_frame(&shared, 1, route_open_answer(open_corr, 42, None)).await);
9536        assert_pending(first.as_mut()).await;
9537        assert_pending(second.as_mut()).await;
9538        while let Ok(command) = receiver.try_recv() {
9539            assert_eq!(command.frame.header.channel, 42);
9540            reply_to_drain_call(&shared, command.frame).await;
9541        }
9542        assert_eq!(first.await.expect("first call resends"), b"first");
9543        assert_eq!(
9544            second.await.expect("second refusal must not time out"),
9545            b"second"
9546        );
9547        assert!(shared.lock_inner().pending.is_empty());
9548    }
9549
9550    #[tokio::test(start_paused = true)]
9551    async fn shared_route_drain_preserves_unrefused_reply_without_resending() {
9552        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9553        let (_, old) = open_answered(
9554            &shared,
9555            &consumer,
9556            &mut receiver,
9557            None,
9558            41,
9559            "initial shared route",
9560        )
9561        .await;
9562        let mut first = Box::pin(drain_call(&consumer, b"refused"));
9563        let mut second = Box::pin(drain_call(&consumer, b"executing"));
9564        assert_pending(first.as_mut()).await;
9565        assert_pending(second.as_mut()).await;
9566        let first_request = receiver.recv().await.unwrap().frame;
9567        let second_request = receiver.recv().await.unwrap().frame;
9568        let executing_corr = second_request.header.corr;
9569        assert_eq!(second_request.header.channel, old.channel);
9570        let mut executing_requests = 1;
9571
9572        refuse_during_drain(&shared, &first_request).await;
9573        assert_pending(first.as_mut()).await;
9574        let (open_corr, _) = next_route_open(&mut receiver, "replacement route barrier").await;
9575        assert_pending(second.as_mut()).await;
9576        assert!(dispatch_frame(&shared, 1, route_open_answer(open_corr, 42, None)).await);
9577        assert_pending(first.as_mut()).await;
9578        assert_pending(second.as_mut()).await;
9579        while let Ok(command) = receiver.try_recv() {
9580            assert_eq!(command.frame.header.ty, FrameType::Request);
9581            // Managed resends allocate a new corr; count the logical request's
9582            // body as well so an unsafe resend cannot hide behind a new corr.
9583            if command.frame.header.corr == executing_corr || command.frame.body == b"executing" {
9584                executing_requests += 1;
9585            }
9586            reply_to_drain_call(&shared, command.frame).await;
9587        }
9588        reply_to_drain_call(&shared, second_request).await;
9589        assert_eq!(first.await.expect("refused call resends"), b"refused");
9590        assert_eq!(
9591            second.await.expect("real old-route reply arrives"),
9592            b"executing"
9593        );
9594        assert_eq!(executing_requests, 1, "unrefused call must never resend");
9595    }
9596
9597    #[tokio::test(start_paused = true)]
9598    async fn invalidated_route_ingress_is_uninstalled_after_last_pending_settles() {
9599        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9600        let (_, old) = open_answered(
9601            &shared,
9602            &consumer,
9603            &mut receiver,
9604            None,
9605            41,
9606            "initial shared route",
9607        )
9608        .await;
9609        let mut first = Box::pin(drain_call(&consumer, b"first"));
9610        let mut second = Box::pin(drain_call(&consumer, b"second"));
9611        assert_pending(first.as_mut()).await;
9612        assert_pending(second.as_mut()).await;
9613        let first_request = receiver.recv().await.unwrap().frame;
9614        let second_request = receiver.recv().await.unwrap().frame;
9615        refuse_during_drain(&shared, &first_request).await;
9616        assert_pending(first.as_mut()).await;
9617        let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9618        assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), Some(old));
9619        assert!(route_reverse_request_registry(old.reverse_request_registry_id()).is_ok());
9620        reply_to_drain_call(&shared, second_request).await;
9621        assert_eq!(second.await.unwrap(), b"second");
9622        assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), None);
9623        assert!(shared.lock_inner().retired_routes.is_empty());
9624        assert!(route_reverse_request_registry(old.reverse_request_registry_id()).is_err());
9625        drop(first);
9626    }
9627
9628    #[tokio::test(start_paused = true)]
9629    async fn invalidated_route_ingress_cleans_up_on_drop_deadline_goodbye_and_disconnect() {
9630        for ending in ["drop", "deadline", "goodbye", "disconnect"] {
9631            let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9632            let (_, old) = open_answered(
9633                &shared,
9634                &consumer,
9635                &mut receiver,
9636                None,
9637                41,
9638                "initial shared route",
9639            )
9640            .await;
9641            let mut first = Box::pin(drain_call(&consumer, b"refused"));
9642            let mut second = Box::pin(drain_call(&consumer, b"executing"));
9643            assert_pending(first.as_mut()).await;
9644            assert_pending(second.as_mut()).await;
9645            let first_request = receiver.recv().await.unwrap().frame;
9646            let second_command = receiver.recv().await.unwrap();
9647            assert!(shared.mark_pending_accepted(second_command.pending.unwrap()));
9648            refuse_during_drain(&shared, &first_request).await;
9649            assert_pending(first.as_mut()).await;
9650            let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9651            match ending {
9652                "drop" => drop(second),
9653                "deadline" => {
9654                    assert_eq!(
9655                        second.await.unwrap_err().outcome_cause(),
9656                        Some(OutcomeUnknownCause::Deadline)
9657                    );
9658                }
9659                "goodbye" => {
9660                    let frame = Frame::build(
9661                        FrameType::Goodbye,
9662                        Flags::new(false, Priority::Interactive, false),
9663                        old.channel,
9664                        old.epoch,
9665                        0,
9666                        Vec::new(),
9667                    )
9668                    .unwrap();
9669                    assert!(dispatch_frame(&shared, 1, frame).await);
9670                    assert_eq!(
9671                        second.await.unwrap_err().outcome_cause(),
9672                        Some(OutcomeUnknownCause::RouteEnded)
9673                    );
9674                }
9675                "disconnect" => {
9676                    shared.handle_generation_drop(1, "test disconnect".into());
9677                    assert_eq!(
9678                        second.await.unwrap_err().outcome_cause(),
9679                        Some(OutcomeUnknownCause::ConnectionFailed)
9680                    );
9681                }
9682                _ => unreachable!(),
9683            }
9684            assert_eq!(
9685                shared.ingress_handle(1, old.channel, old.epoch),
9686                None,
9687                "{ending}"
9688            );
9689            assert!(shared.lock_inner().retired_routes.is_empty(), "{ending}");
9690            assert!(
9691                route_reverse_request_registry(old.reverse_request_registry_id()).is_err(),
9692                "{ending}"
9693            );
9694            drop(first);
9695        }
9696    }
9697
9698    #[tokio::test(start_paused = true)]
9699    async fn invalidated_route_subscription_cancel_and_overflow_uninstall_ingress() {
9700        for overflow in [false, true] {
9701            let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9702            let (_, old) = open_answered(
9703                &shared,
9704                &consumer,
9705                &mut receiver,
9706                None,
9707                41,
9708                "initial shared route",
9709            )
9710            .await;
9711            let mut subscription = consumer
9712                .subscribe_route(&old, b"watch".to_vec(), SubscribeOptions::default())
9713                .await
9714                .unwrap();
9715            let request = receiver.recv().await.unwrap().frame;
9716            let mut call = Box::pin(drain_call(&consumer, b"refused"));
9717            assert_pending(call.as_mut()).await;
9718            let refused = receiver.recv().await.unwrap().frame;
9719            refuse_during_drain(&shared, &refused).await;
9720            assert_pending(call.as_mut()).await;
9721            let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9722            assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), Some(old));
9723            assert!(matches!(
9724                consumer
9725                    .request(&old, b"new".to_vec(), CallOptions::default())
9726                    .await,
9727                Err(CallError::StaleRouteHandle(_))
9728            ));
9729            if overflow {
9730                for _ in 0..=DEFAULT_SUBSCRIPTION_EVENT_BUFFER {
9731                    assert!(
9732                        dispatch_frame(
9733                            &shared,
9734                            1,
9735                            watch_terminal(&request, FrameType::StreamData, vec![1])
9736                        )
9737                        .await
9738                    );
9739                }
9740                assert_eq!(subscription.ended().await, SubscriptionEnd::Backpressure);
9741            } else {
9742                subscription.unsubscribe().unwrap();
9743                assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
9744            }
9745            assert_eq!(
9746                receiver.recv().await.unwrap().frame.header.ty,
9747                FrameType::Cancel
9748            );
9749            assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), None);
9750            assert!(shared.lock_inner().retired_routes.is_empty());
9751            drop(call);
9752        }
9753    }
9754
9755    #[tokio::test(start_paused = true)]
9756    async fn the_default_retry_deadline_outlasts_a_60s_restart_and_the_open_succeeds() {
9757        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9758        let started = Instant::now();
9759        // A call deadline past the retry deadline, so the retry deadline is
9760        // the one under test.
9761        let options = CallOptions {
9762            timeout: Duration::from_secs(120),
9763            ..CallOptions::default()
9764        };
9765        let mut task = tokio::spawn(async move {
9766            consumer
9767                .open_route(restart_target("restarting"), restart_identity(), options)
9768                .await
9769        });
9770        let opened = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9771            (started.elapsed() < Duration::from_secs(60)).then(reloading)
9772        })
9773        .await;
9774        let handle =
9775            opened.unwrap_or_else(|err| panic!("the open must survive the restart: {err}"));
9776        assert!(handle.channel > 40);
9777        assert!(started.elapsed() >= Duration::from_secs(60));
9778    }
9779
9780    #[tokio::test(start_paused = true)]
9781    async fn a_call_timeout_shorter_than_the_retry_deadline_ends_the_retries_at_the_call_timeout() {
9782        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(2));
9783        let started = Instant::now();
9784        let options = CallOptions {
9785            timeout: Duration::from_secs(10),
9786            ..CallOptions::default()
9787        };
9788        let mut task = tokio::spawn(async move {
9789            consumer
9790                .open_route(restart_target("restarting"), restart_identity(), options)
9791                .await
9792        });
9793        let err = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9794            (started.elapsed() < Duration::from_secs(60)).then(reloading)
9795        })
9796        .await
9797        .expect_err("the call timeout must end the retries before the module is back");
9798        let elapsed = started.elapsed();
9799        assert!(matches!(err, CallError::NotSent(_)), "got {err:?}");
9800        assert!(
9801            elapsed >= Duration::from_secs(9) && elapsed <= Duration::from_secs(10),
9802            "the retries must stop at the 10s call timeout, stopped after {elapsed:?}"
9803        );
9804    }
9805
9806    #[tokio::test(start_paused = true)]
9807    async fn two_routes_refused_together_retry_at_different_jittered_times() {
9808        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(42));
9809        let started = Instant::now();
9810        let mut task = tokio::spawn(async move {
9811            let alpha = consumer.open_route(
9812                restart_target("alpha"),
9813                restart_identity(),
9814                CallOptions::default(),
9815            );
9816            let beta = consumer.open_route(
9817                restart_target("beta"),
9818                restart_identity(),
9819                CallOptions::default(),
9820            );
9821            let (alpha, beta) = tokio::join!(alpha, beta);
9822            (alpha.is_ok(), beta.is_ok())
9823        });
9824        let mut first_open = HashMap::<String, Duration>::new();
9825        let mut retried_at = HashMap::<String, Duration>::new();
9826        let opened = answer_route_opens(&shared, &mut receiver, &mut task, |module_id| {
9827            let at = started.elapsed();
9828            if first_open.contains_key(module_id) {
9829                retried_at.insert(module_id.to_string(), at);
9830                None
9831            } else {
9832                first_open.insert(module_id.to_string(), at);
9833                Some(reloading())
9834            }
9835        })
9836        .await;
9837        assert_eq!(opened, (true, true));
9838        assert_eq!(first_open["alpha"], first_open["beta"], "refused together");
9839        // Equal jitter keeps half of the 100ms base delay and randomizes the rest.
9840        for at in retried_at.values() {
9841            assert!(
9842                *at >= Duration::from_millis(50) && *at <= Duration::from_millis(100),
9843                "retry at {at:?} is outside the jitter window"
9844            );
9845        }
9846        assert_ne!(
9847            retried_at["alpha"], retried_at["beta"],
9848            "routes refused together must not retry in lock step"
9849        );
9850    }
9851
9852    #[tokio::test(start_paused = true)]
9853    async fn twenty_concurrent_opens_never_have_more_than_eight_outstanding_at_the_daemon() {
9854        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(3));
9855        let mut task = tokio::spawn(async move {
9856            let mut opens = tokio::task::JoinSet::new();
9857            for i in 0..20 {
9858                let consumer = Arc::clone(&consumer);
9859                opens.spawn(async move {
9860                    consumer
9861                        .open_route(
9862                            restart_target(&format!("module-{i}")),
9863                            restart_identity(),
9864                            CallOptions::default(),
9865                        )
9866                        .await
9867                });
9868            }
9869            let mut opened = 0usize;
9870            while let Some(result) = opens.join_next().await {
9871                result.unwrap().unwrap();
9872                opened += 1;
9873            }
9874            opened
9875        });
9876        // Hold every open until the consumer has gone quiet, so everything it
9877        // is willing to send at once is outstanding together; then answer them.
9878        let mut held = Vec::new();
9879        let mut max_outstanding = 0usize;
9880        let mut next_channel = 40u16;
9881        let opened = loop {
9882            tokio::select! {
9883                command = receiver.recv() => {
9884                    // The writer closes when the last consumer handle drops,
9885                    // which means every open has settled.
9886                    let Some(command) = command else {
9887                        break (&mut task).await.unwrap();
9888                    };
9889                    held.push(command.frame.header.corr);
9890                    max_outstanding = max_outstanding.max(held.len());
9891                }
9892                () = sleep(Duration::from_millis(25)), if !held.is_empty() => {
9893                    for corr in held.drain(..) {
9894                        next_channel += 1;
9895                        assert!(dispatch_frame(&shared, 1, route_open_answer(corr, next_channel, None)).await);
9896                    }
9897                }
9898                joined = &mut task => break joined.unwrap(),
9899            }
9900        };
9901        assert_eq!(opened, 20);
9902        assert_eq!(max_outstanding, MAX_ROUTE_OPENS_IN_FLIGHT);
9903    }
9904
9905    #[tokio::test(start_paused = true)]
9906    async fn an_exhausted_deadline_names_module_reloading_not_the_later_admission_pressure() {
9907        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(4));
9908        let options = CallOptions {
9909            route_retry_deadline: Duration::from_secs(5),
9910            ..CallOptions::default()
9911        };
9912        let mut task = tokio::spawn(async move {
9913            consumer
9914                .open_route(restart_target("restarting"), restart_identity(), options)
9915                .await
9916        });
9917        let mut opens = 0usize;
9918        let err = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9919            opens += 1;
9920            Some(if opens <= 2 {
9921                reloading().with_detail(serde_json::json!({ "reason": "restart" }))
9922            } else {
9923                ErrorBody::new(
9924                    error_codes::TARGET_UNAVAILABLE,
9925                    "connection already has 8 route.open binds in flight (limit 8); retry after one settles",
9926                )
9927            })
9928        })
9929        .await
9930        .expect_err("the module never comes back");
9931        assert!(opens > 2);
9932        assert!(matches!(err, CallError::NotSent(_)), "got {err:?}");
9933        assert_eq!(
9934            err.route_open_refusal().map(|body| body.code.as_str()),
9935            Some(error_codes::MODULE_RELOADING)
9936        );
9937        let message = err.to_string();
9938        assert!(
9939            message.starts_with(
9940                "request not sent: route.open failed for target tool_provider:restarting: \
9941                 module_reloading (reason restart) (module is reloading); \
9942                 the most recent refusal was target_unavailable"
9943            ),
9944            "got {message}"
9945        );
9946    }
9947
9948    #[tokio::test]
9949    async fn close_route_flips_inflight_opening_so_a_racing_open_discards() {
9950        // The load-bearing close-beats-reopen guard, in isolation: a close that lands
9951        // while a route.open is in flight (channel not yet cached) must flip the
9952        // opening's `closed` flag, so the lead opener re-checks it before installing and
9953        // GOODBYEs the channel it opened instead of caching it.
9954        let shared = Arc::new(reader_skew_tests::legacy_shared(
9955            PathBuf::from("/tmp/does-not-exist"),
9956            ConsumerOptions::default(),
9957        ));
9958        let key = RouteKey::new(
9959            &RouteTarget::ToolProvider {
9960                module_id: "m".into(),
9961            },
9962            &BindIdentity::new("h", "s"),
9963            None,
9964            None,
9965        );
9966        // Simulate an in-flight lead open: an openings entry exists, not yet closed,
9967        // with no cached route (channel hasn't been installed yet).
9968        shared.lock_inner().openings.insert(
9969            key.clone(),
9970            Opening {
9971                waiters: Vec::new(),
9972                closed: false,
9973            },
9974        );
9975
9976        // close_route with no cached route is an idempotent no-op on routes, but MUST
9977        // flip the in-flight opening's flag so the racing open discards.
9978        shared
9979            .close_route(&key, &CloseRouteOptions::default())
9980            .await;
9981        assert!(
9982            shared
9983                .lock_inner()
9984                .openings
9985                .get(&key)
9986                .is_some_and(|o| o.closed),
9987            "close_route must flip the in-flight opening's closed flag (close-beats-reopen)"
9988        );
9989
9990        // And closing a key with neither a route nor an in-flight open is a no-op.
9991        let absent = RouteKey::new(
9992            &RouteTarget::ToolProvider {
9993                module_id: "absent".into(),
9994            },
9995            &BindIdentity::new("h", "s"),
9996            None,
9997            None,
9998        );
9999        shared
10000            .close_route(&absent, &CloseRouteOptions::default())
10001            .await;
10002    }
10003
10004    #[test]
10005    fn route_key_is_structured() {
10006        let target = RouteTarget::InternalService {
10007            module_id: "a\0b".into(),
10008            service_id: "svc".into(),
10009        };
10010        let identity = BindIdentity::new("h", "s");
10011        let key = RouteKey::new(&target, &identity, None, None);
10012        assert!(matches!(key.target, RouteTargetKey::InternalService { .. }));
10013    }
10014
10015    async fn assert_pending(mut future: Pin<&mut (impl Future + ?Sized)>) {
10016        assert!(
10017            std::future::poll_fn(|cx| Poll::Ready(future.as_mut().poll(cx).is_pending())).await
10018        );
10019    }
10020
10021    /// Replace only the transport, leaving the actual generation-drop cleanup in use.
10022    fn drop_and_replace_test_transport(shared: &Arc<Shared>) -> mpsc::Receiver<WriteCommand> {
10023        let generation = shared.lock_inner().generation;
10024        // Keep the background supervisor from touching a real connection file.
10025        shared.lock_inner().reconnect = ReconnectState::Inline { generation };
10026        shared.handle_generation_drop(generation, "test connection drop".into());
10027        let (writer, receiver) = mpsc::channel(64);
10028        let mut inner = shared.lock_inner();
10029        inner.generation += 1;
10030        inner.epoch += 1;
10031        inner.next_corr = Some(1);
10032        inner.writer = Some(writer);
10033        inner.daemon_ver = "0.39.0".into();
10034        inner.reconnect = ReconnectState::Idle;
10035        receiver
10036    }
10037
10038    #[tokio::test(start_paused = true)]
10039    async fn route_open_single_flight_survives_generation_drop_during_backoff() {
10040        let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
10041        let opts = CallOptions::default();
10042        let opener = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10043        tokio::pin!(opener);
10044        assert_pending(opener.as_mut()).await;
10045        let first = receiver.try_recv().unwrap();
10046        assert!(
10047            dispatch_frame(
10048                &shared,
10049                1,
10050                route_open_answer(first.frame.header.corr, 0, Some(reloading())),
10051            )
10052            .await
10053        );
10054        assert_pending(opener.as_mut()).await;
10055
10056        // A caller already waiting and one arriving after the drop must both stay
10057        // behind the same lead opener, including its unfinished retry backoff.
10058        let waiting = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10059        tokio::pin!(waiting);
10060        assert_pending(waiting.as_mut()).await;
10061        let mut receiver = drop_and_replace_test_transport(&shared);
10062        assert_pending(waiting.as_mut()).await;
10063        let arriving = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10064        tokio::pin!(arriving);
10065        assert_pending(arriving.as_mut()).await;
10066        assert!(
10067            receiver.try_recv().is_err(),
10068            "a second opener bypassed the backoff"
10069        );
10070
10071        tokio::time::advance(opts.route_retry.base).await;
10072        assert_pending(opener.as_mut()).await;
10073        let retry = receiver.try_recv().unwrap();
10074        assert!(
10075            dispatch_frame(
10076                &shared,
10077                2,
10078                route_open_answer(retry.frame.header.corr, 42, None),
10079            )
10080            .await
10081        );
10082        let handle = opener.await.unwrap();
10083        assert_eq!(waiting.await.unwrap(), handle);
10084        assert_eq!(arriving.await.unwrap(), handle);
10085        assert!(
10086            receiver.try_recv().is_err(),
10087            "more than one retry was emitted"
10088        );
10089        let inner = shared.lock_inner();
10090        assert!(inner.openings.is_empty());
10091        assert_eq!(inner.routes.len(), 1);
10092        assert_eq!(inner.route_epochs.len(), 1);
10093    }
10094
10095    #[tokio::test(start_paused = true)]
10096    async fn close_route_during_backoff_survives_generation_drop() {
10097        let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
10098        let opts = CallOptions::default();
10099        let opener = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10100        tokio::pin!(opener);
10101        assert_pending(opener.as_mut()).await;
10102        let first = receiver.try_recv().unwrap();
10103        assert!(
10104            dispatch_frame(
10105                &shared,
10106                1,
10107                route_open_answer(first.frame.header.corr, 0, Some(reloading())),
10108            )
10109            .await
10110        );
10111        assert_pending(opener.as_mut()).await;
10112        consumer
10113            .close_route(
10114                restart_target("m"),
10115                restart_identity(),
10116                CloseRouteOptions::default(),
10117            )
10118            .await;
10119        let mut receiver = drop_and_replace_test_transport(&shared);
10120        tokio::time::advance(opts.route_retry.base).await;
10121        assert_pending(opener.as_mut()).await;
10122        let retry = receiver.try_recv().unwrap();
10123        assert!(
10124            dispatch_frame(
10125                &shared,
10126                2,
10127                route_open_answer(retry.frame.header.corr, 42, None),
10128            )
10129            .await
10130        );
10131        let err = opener.await.expect_err("close must win over the retry");
10132        assert!(matches!(err, CallError::NotSent(_)));
10133        let goodbye = receiver
10134            .try_recv()
10135            .expect("discarded route must get GOODBYE");
10136        assert_eq!(goodbye.frame.header.ty, FrameType::Goodbye);
10137        assert_eq!(goodbye.frame.header.channel, 42);
10138        assert!(receiver.try_recv().is_err());
10139        let inner = shared.lock_inner();
10140        assert!(inner.routes.is_empty());
10141        assert!(inner.route_epochs.is_empty());
10142        assert!(inner.openings.is_empty());
10143    }
10144
10145    fn route_teardown_stand_in() -> (
10146        Arc<Shared>,
10147        SubcConsumer,
10148        mpsc::Receiver<WriteCommand>,
10149        tokio::io::DuplexStream,
10150        RouteKey,
10151        RouteState,
10152    ) {
10153        let shared = writer_test_shared();
10154        let (stream, peer) = tokio::io::duplex(1024);
10155        shared
10156            .install_initial(OpenedConnection {
10157                stream: Box::new(stream),
10158                daemon_origin_trusted: true,
10159                daemon_ver: "0.39.0".into(),
10160            })
10161            .unwrap();
10162        let (writer, rx) = mpsc::channel(1);
10163        writer
10164            .try_send(WriteCommand {
10165                frame: response_frame(0, 0, 99, b"filler".to_vec()),
10166                pending: None,
10167            })
10168            .unwrap();
10169        let key = RouteKey::new(&restart_target("teardown"), &restart_identity(), None, None);
10170        let route = RouteState {
10171            handle: RouteHandle::new(17, 23, 1),
10172            sem: Arc::new(Semaphore::new(1)),
10173            watch_sem: None,
10174            opted_in: false,
10175        };
10176        {
10177            let mut inner = shared.lock_inner();
10178            inner.writer = Some(writer);
10179            inner.cache_route(key.clone(), route.clone());
10180        }
10181        let consumer = SubcConsumer {
10182            shared: Arc::clone(&shared),
10183        };
10184        (shared, consumer, rx, peer, key, route)
10185    }
10186
10187    async fn assert_reopened_request_after_goodbye(
10188        shared: &Arc<Shared>,
10189        consumer: &SubcConsumer,
10190        rx: &mut mpsc::Receiver<WriteCommand>,
10191        old: RouteHandle,
10192    ) {
10193        let reopened = RouteHandle::new(old.channel, old.epoch + 1, old.connection_token());
10194        shared
10195            .install_one_shot_route(RouteState {
10196                handle: reopened,
10197                sem: Arc::new(Semaphore::new(1)),
10198                watch_sem: None,
10199                opted_in: false,
10200            })
10201            .unwrap();
10202        let request = consumer.request(&reopened, b"reopened".to_vec(), CallOptions::default());
10203        tokio::pin!(request);
10204        assert_pending(request.as_mut()).await;
10205        let command = rx.recv().await.unwrap();
10206        assert_eq!(command.frame.header.ty, FrameType::Goodbye);
10207        assert_eq!(
10208            (command.frame.header.channel, command.frame.header.epoch),
10209            (old.channel, old.epoch)
10210        );
10211        assert_pending(request.as_mut()).await;
10212        let command = rx.recv().await.unwrap();
10213        assert_eq!(command.frame.header.ty, FrameType::Request);
10214        assert_eq!(command.frame.header.channel, reopened.channel);
10215        assert_eq!(command.frame.header.epoch, reopened.epoch);
10216        dispatch_frame(
10217            shared,
10218            reopened.connection_token(),
10219            response_frame(
10220                reopened.channel,
10221                reopened.epoch,
10222                command.frame.header.corr,
10223                Vec::new(),
10224            ),
10225        )
10226        .await;
10227        request.await.unwrap();
10228    }
10229
10230    #[tokio::test]
10231    async fn route_teardown_close_waits_for_goodbye_before_channel_reuse() {
10232        for by_handle in [false, true] {
10233            let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10234            let close = async {
10235                if by_handle {
10236                    consumer
10237                        .close_handle(&route.handle, CloseRouteOptions::default())
10238                        .await
10239                        .unwrap();
10240                } else {
10241                    consumer
10242                        .close_route(
10243                            restart_target("teardown"),
10244                            restart_identity(),
10245                            CloseRouteOptions::default(),
10246                        )
10247                        .await;
10248                }
10249            };
10250            tokio::pin!(close);
10251            assert_pending(close.as_mut()).await;
10252            assert!(route.sem.is_closed());
10253            assert!(!shared.lock_inner().routes.contains_key(&key));
10254            assert_eq!(
10255                shared.lock_inner().route_epochs.get(&route.handle.channel),
10256                Some(&route.handle)
10257            );
10258            let mut reopened = route.clone();
10259            reopened.handle = RouteHandle::new(route.handle.channel, route.handle.epoch + 1, 1);
10260            assert!(shared.install_one_shot_route(reopened).is_err());
10261            assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10262            close.await;
10263            assert_reopened_request_after_goodbye(&shared, &consumer, &mut rx, route.handle).await;
10264            consumer.close().await;
10265        }
10266    }
10267
10268    #[tokio::test]
10269    async fn route_teardown_retirement_waits_for_goodbye_before_channel_reuse() {
10270        let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10271        shared.invalidate_route_with_deadline(&key, Some(route.handle), true);
10272        assert!(route.sem.is_closed());
10273        assert_eq!(
10274            shared.lock_inner().route_epochs.get(&route.handle.channel),
10275            Some(&route.handle)
10276        );
10277        let mut reopened = route.clone();
10278        reopened.handle = RouteHandle::new(route.handle.channel, route.handle.epoch + 1, 1);
10279        assert!(shared.install_one_shot_route(reopened).is_err());
10280        assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10281        tokio::time::timeout(Duration::from_secs(1), async {
10282            while shared
10283                .lock_inner()
10284                .route_epochs
10285                .contains_key(&route.handle.channel)
10286            {
10287                tokio::task::yield_now().await;
10288            }
10289        })
10290        .await
10291        .expect("retirement must queue its GOODBYE after writer capacity frees");
10292        assert_reopened_request_after_goodbye(&shared, &consumer, &mut rx, route.handle).await;
10293        consumer.close().await;
10294    }
10295
10296    #[tokio::test]
10297    async fn route_teardown_retirements_flush_in_order() {
10298        let (shared, consumer, mut rx, _peer, first_key, first) = route_teardown_stand_in();
10299        let second_key = RouteKey::new(&restart_target("second"), &restart_identity(), None, None);
10300        let mut second = first.clone();
10301        second.handle = RouteHandle::new(first.handle.channel + 1, 31, 1);
10302        shared
10303            .lock_inner()
10304            .cache_route(second_key.clone(), second.clone());
10305        shared.invalidate_route_with_deadline(&first_key, Some(first.handle), true);
10306        shared.invalidate_route_with_deadline(&second_key, Some(second.handle), true);
10307        assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10308        for handle in [first.handle, second.handle] {
10309            let command = tokio::time::timeout(Duration::from_secs(1), rx.recv())
10310                .await
10311                .unwrap()
10312                .unwrap();
10313            assert_eq!(command.frame.header.ty, FrameType::Goodbye);
10314            assert_eq!(
10315                (command.frame.header.channel, command.frame.header.epoch),
10316                (handle.channel, handle.epoch)
10317            );
10318            assert!(!shared
10319                .lock_inner()
10320                .route_epochs
10321                .contains_key(&handle.channel));
10322        }
10323        assert!(shared.lock_inner().retirement_queue.is_empty());
10324        assert!(shared.lock_inner().retirement_goodbyes.is_empty());
10325        assert!(rx.try_recv().is_err());
10326        consumer.close().await;
10327    }
10328
10329    #[tokio::test]
10330    async fn route_teardown_dead_connection_ends_writer_wait_and_discards_retirements() {
10331        for death in 0..3 {
10332            let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10333            let opts = CloseRouteOptions::default();
10334            let close = shared.close_route(&key, &opts);
10335            tokio::pin!(close);
10336            assert_pending(close.as_mut()).await;
10337            match death {
10338                0 => rx.close(),
10339                1 => shared.handle_generation_drop(1, "test connection lost".into()),
10340                _ => shared.close_sync("test connection closed"),
10341            }
10342            tokio::time::timeout(Duration::from_secs(1), close)
10343                .await
10344                .unwrap();
10345            assert!(!shared
10346                .lock_inner()
10347                .route_epochs
10348                .contains_key(&route.handle.channel));
10349            assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10350            assert!(rx.try_recv().is_err());
10351            consumer.close().await;
10352
10353            let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10354            shared.invalidate_route_with_deadline(&key, Some(route.handle), true);
10355            if death == 1 {
10356                shared.handle_generation_drop(1, "test connection lost".into());
10357            } else {
10358                consumer.close().await;
10359            }
10360            assert!(shared.lock_inner().retirement_queue.is_empty());
10361            assert!(shared.lock_inner().retirement_goodbyes.is_empty());
10362            assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10363            assert!(rx.try_recv().is_err());
10364            consumer.close().await;
10365        }
10366    }
10367
10368    #[tokio::test]
10369    async fn route_channel_index_tracks_lookup_close_and_generation_drop() {
10370        let shared = writer_test_shared();
10371        let (writer, _rx) = mpsc::channel(32);
10372        let mut expected = Vec::new();
10373        {
10374            let mut inner = shared.lock_inner();
10375            inner.writer = Some(writer);
10376            inner.daemon_ver = "0.39.0".into();
10377            for channel in 1..=8 {
10378                let key = RouteKey::new(
10379                    &RouteTarget::ToolProvider {
10380                        module_id: format!("module-{channel}"),
10381                    },
10382                    &BindIdentity::new("test", format!("session-{channel}")),
10383                    None,
10384                    None,
10385                );
10386                let route = RouteState {
10387                    handle: RouteHandle::new(channel, channel.into(), 1),
10388                    sem: Arc::new(Semaphore::new(DEFAULT_ROUTE_WINDOW)),
10389                    watch_sem: None,
10390                    opted_in: false,
10391                };
10392                inner.cache_route(key.clone(), route.clone());
10393                expected.push((key, route));
10394            }
10395        }
10396
10397        for (key, expected_route) in &expected {
10398            let resolved = shared
10399                .route_state(expected_route.handle)
10400                .expect("an indexed route handle should resolve");
10401            assert_eq!(resolved.handle, expected_route.handle);
10402            assert!(Arc::ptr_eq(&resolved.sem, &expected_route.sem));
10403
10404            let inner = shared.lock_inner();
10405            assert_eq!(
10406                inner.route_by_channel.get(&expected_route.handle.channel),
10407                Some(key)
10408            );
10409            assert_eq!(
10410                inner.route_epochs.get(&expected_route.handle.channel),
10411                Some(&expected_route.handle)
10412            );
10413            assert!(inner
10414                .routes
10415                .get(key)
10416                .is_some_and(|route| route.handle == expected_route.handle));
10417        }
10418
10419        let (closed_key, closed_route) = &expected[3];
10420        shared
10421            .close_route(closed_key, &CloseRouteOptions::default())
10422            .await;
10423        {
10424            let inner = shared.lock_inner();
10425            assert!(!inner.routes.contains_key(closed_key));
10426            assert!(!inner
10427                .route_by_channel
10428                .contains_key(&closed_route.handle.channel));
10429            assert!(!inner
10430                .route_epochs
10431                .contains_key(&closed_route.handle.channel));
10432        }
10433        assert!(matches!(
10434            shared.route_state(closed_route.handle),
10435            Err(CallError::StaleRouteHandle(handle)) if handle == closed_route.handle
10436        ));
10437
10438        shared.handle_generation_drop(1, "test generation dropped".into());
10439        {
10440            let inner = shared.lock_inner();
10441            assert!(inner.routes.is_empty());
10442            assert!(inner.route_by_channel.is_empty());
10443            assert!(inner.route_epochs.is_empty());
10444        }
10445        shared.close_sync("test complete");
10446    }
10447
10448    #[tokio::test]
10449    async fn stale_push_is_not_delivered_after_connection_generation_changes() {
10450        let shared = writer_test_shared();
10451        let old_handle = RouteHandle::new(7, 1, 1);
10452        let (writer, _writer_rx) = mpsc::channel(1);
10453        {
10454            let mut inner = shared.lock_inner();
10455            inner.writer = Some(writer);
10456            inner.daemon_ver = "0.39.0".into();
10457            inner.route_epochs.insert(old_handle.channel, old_handle);
10458        }
10459        let mut pushes = shared
10460            .register_push_events(old_handle)
10461            .expect("the old live route should accept a receiver");
10462
10463        {
10464            let mut inner = shared.lock_inner();
10465            inner.generation = 2;
10466            inner.close_routes();
10467            inner.route_epochs.clear();
10468            inner.route_modules.clear();
10469            inner.route_end_reasons.clear();
10470            inner.legacy_channel_reasons.clear();
10471        }
10472        shared.route_push(old_handle, b"stale".to_vec());
10473
10474        assert!(
10475            pushes.recv().await.is_none(),
10476            "connection teardown must end the old receiver before a stale Push can arrive"
10477        );
10478        shared.close_sync("test complete");
10479    }
10480
10481    #[test]
10482    fn route_key_canonicalizes_consumer_capabilities() {
10483        let target = RouteTarget::ToolProvider {
10484            module_id: "aft".into(),
10485        };
10486        let identity = BindIdentity::new("h", "s");
10487        let left = RouteKey::new(
10488            &target,
10489            &identity,
10490            None,
10491            Some(&["sampling".to_string(), "elicitation".to_string()]),
10492        );
10493        let right = RouteKey::new(
10494            &target,
10495            &identity,
10496            None,
10497            Some(&[
10498                "elicitation".to_string(),
10499                "sampling".to_string(),
10500                "sampling".to_string(),
10501            ]),
10502        );
10503        assert_eq!(left, right);
10504    }
10505
10506    #[tokio::test]
10507    async fn routes_with_and_without_declared_consumer_capabilities_are_kept_apart() {
10508        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(10));
10509        let (undeclared_request, undeclared) = open_answered_with(
10510            &shared,
10511            &consumer,
10512            &mut receiver,
10513            CallOptions::default(),
10514            74,
10515            "the undeclared route opens first",
10516        )
10517        .await;
10518        assert!(undeclared_request.get("consumer_capabilities").is_none());
10519
10520        let declared_opts = CallOptions::default()
10521            .with_consumer_capability("tool-result/v1")
10522            .unwrap();
10523        let (declared_request, declared) = open_answered_with(
10524            &shared,
10525            &consumer,
10526            &mut receiver,
10527            declared_opts.clone(),
10528            75,
10529            "a declared open must not reuse the undeclared route",
10530        )
10531        .await;
10532        assert_eq!(
10533            declared_request["consumer_capabilities"],
10534            serde_json::json!(["tool-result/v1"])
10535        );
10536        assert_ne!(undeclared, declared);
10537
10538        assert_eq!(
10539            consumer
10540                .open_route(restart_target("plexus"), restart_identity(), declared_opts)
10541                .await
10542                .unwrap(),
10543            declared,
10544            "the same declaration must reuse its cached route"
10545        );
10546        assert_eq!(
10547            consumer
10548                .open_route(
10549                    restart_target("plexus"),
10550                    restart_identity(),
10551                    CallOptions::default(),
10552                )
10553                .await
10554                .unwrap(),
10555            undeclared,
10556            "an undeclared open must continue to reuse only its own route"
10557        );
10558        assert!(
10559            receiver.try_recv().is_err(),
10560            "both subsequent opens are cache hits"
10561        );
10562        shared.close_sync("test complete");
10563    }
10564
10565    fn scope_selector(owner: &str, scope_ref: &str, scope_epoch: u64) -> ScopeSelector {
10566        ScopeSelector::new(
10567            subc_protocol::Principal::Reserved {
10568                module_id: owner.to_string(),
10569            },
10570            scope_ref.to_string(),
10571            Some(scope_epoch),
10572        )
10573    }
10574
10575    #[test]
10576    fn route_key_separates_scopes_by_owner_ref_and_epoch_and_from_unscoped() {
10577        let target = RouteTarget::ToolProvider {
10578            module_id: "plexus".into(),
10579        };
10580        let identity = BindIdentity::new("h", "s");
10581        let key = |scope: Option<ScopeSelector>| {
10582            RouteKey::new(&target, &identity, None, None).with_scope(scope.as_ref())
10583        };
10584        let base = key(Some(scope_selector("owner", "session-a", 1)));
10585        assert_eq!(base, key(Some(scope_selector("owner", "session-a", 1))));
10586        for (label, other) in [
10587            ("epoch", key(Some(scope_selector("owner", "session-a", 2)))),
10588            ("ref", key(Some(scope_selector("owner", "session-b", 1)))),
10589            ("owner", key(Some(scope_selector("other", "session-a", 1)))),
10590            ("unscoped", key(None)),
10591        ] {
10592            assert_ne!(base, other, "a different {label} must be a different route");
10593        }
10594        let mut no_epoch = scope_selector("owner", "session-a", 1);
10595        no_epoch.scope_epoch = None;
10596        assert_ne!(base, key(Some(no_epoch)));
10597    }
10598
10599    /// The next route.open the consumer writes, skipping any other frame
10600    /// (a GOODBYE, a cancel). Fails the test by name if none arrives, which is
10601    /// what a cache hit that should have been a miss looks like.
10602    async fn next_route_open(
10603        receiver: &mut mpsc::Receiver<WriteCommand>,
10604        why: &str,
10605    ) -> (u64, serde_json::Value) {
10606        loop {
10607            let command = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
10608                .await
10609                .unwrap_or_else(|_| panic!("no route.open was sent: {why}"))
10610                .expect("writer channel open");
10611            if command.frame.header.channel != 0 || command.frame.header.ty != FrameType::Request {
10612                continue;
10613            }
10614            let request: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
10615            if request["op"] == "route.open" {
10616                return (command.frame.header.corr, request);
10617            }
10618        }
10619    }
10620
10621    /// Open a route (scoped when `scope` is set) through the stand-in daemon,
10622    /// accept its route.open on `channel`, and return the open's body and handle.
10623    async fn open_answered(
10624        shared: &Arc<Shared>,
10625        consumer: &Arc<SubcConsumer>,
10626        receiver: &mut mpsc::Receiver<WriteCommand>,
10627        scope: Option<ScopeSelector>,
10628        channel: u16,
10629        why: &str,
10630    ) -> (serde_json::Value, RouteHandle) {
10631        let consumer = Arc::clone(consumer);
10632        let task = tokio::spawn(async move {
10633            match scope {
10634                Some(scope) => {
10635                    consumer
10636                        .open_route_scoped(
10637                            restart_target("plexus"),
10638                            restart_identity(),
10639                            scope,
10640                            CallOptions::default(),
10641                        )
10642                        .await
10643                }
10644                None => {
10645                    consumer
10646                        .open_route(
10647                            restart_target("plexus"),
10648                            restart_identity(),
10649                            CallOptions::default(),
10650                        )
10651                        .await
10652                }
10653            }
10654        });
10655        let (corr, request) = next_route_open(receiver, why).await;
10656        assert!(dispatch_frame(shared, 1, route_open_answer(corr, channel, None)).await);
10657        let handle = task.await.unwrap().expect("the stand-in accepted the open");
10658        (request, handle)
10659    }
10660
10661    /// Open an unscoped `plexus` route with `opts` through the stand-in
10662    /// daemon, accept its route.open on `channel`, and return the open's body
10663    /// and handle.
10664    async fn open_answered_with(
10665        shared: &Arc<Shared>,
10666        consumer: &Arc<SubcConsumer>,
10667        receiver: &mut mpsc::Receiver<WriteCommand>,
10668        opts: CallOptions,
10669        channel: u16,
10670        why: &str,
10671    ) -> (serde_json::Value, RouteHandle) {
10672        let consumer = Arc::clone(consumer);
10673        let task = tokio::spawn(async move {
10674            consumer
10675                .open_route(restart_target("plexus"), restart_identity(), opts)
10676                .await
10677        });
10678        let (corr, request) = next_route_open(receiver, why).await;
10679        assert!(dispatch_frame(shared, 1, route_open_answer(corr, channel, None)).await);
10680        let handle = task.await.unwrap().expect("the stand-in accepted the open");
10681        (request, handle)
10682    }
10683
10684    fn with_role_versions(entries: &[(&str, &str)]) -> CallOptions {
10685        CallOptions {
10686            role_versions: Some(
10687                entries
10688                    .iter()
10689                    .map(|(role, version)| (role.to_string(), version.to_string()))
10690                    .collect(),
10691            ),
10692            ..CallOptions::default()
10693        }
10694    }
10695
10696    /// A provider picks its wire shape from the role versions at bind, so a
10697    /// legacy route and a versioned one to the same target must never be
10698    /// shared, while the same declaration again (and an empty map, which
10699    /// declares nothing) reuses the route it matches.
10700    #[tokio::test]
10701    async fn routes_differing_only_in_role_versions_are_kept_apart() {
10702        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(9));
10703        let (legacy_request, legacy) = open_answered_with(
10704            &shared,
10705            &consumer,
10706            &mut receiver,
10707            CallOptions::default(),
10708            71,
10709            "first, legacy open",
10710        )
10711        .await;
10712        assert!(
10713            legacy_request.get("role_versions").is_none(),
10714            "{legacy_request}"
10715        );
10716
10717        let (v1_request, v1) = open_answered_with(
10718            &shared,
10719            &consumer,
10720            &mut receiver,
10721            with_role_versions(&[("tool-provider", "v1")]),
10722            72,
10723            "a v1 open must not reuse the legacy route",
10724        )
10725        .await;
10726        assert_eq!(
10727            v1_request["role_versions"],
10728            serde_json::json!({ "tool-provider": "v1" })
10729        );
10730        assert_ne!(legacy, v1);
10731
10732        let (v2_request, v2) = open_answered_with(
10733            &shared,
10734            &consumer,
10735            &mut receiver,
10736            with_role_versions(&[("tool-provider", "v2")]),
10737            73,
10738            "a v2 open must not reuse the v1 route",
10739        )
10740        .await;
10741        assert_eq!(
10742            v2_request["role_versions"],
10743            serde_json::json!({ "tool-provider": "v2" })
10744        );
10745        assert!(![legacy, v1].contains(&v2));
10746
10747        let open = |opts: CallOptions| {
10748            let consumer = Arc::clone(&consumer);
10749            async move {
10750                consumer
10751                    .open_route(restart_target("plexus"), restart_identity(), opts)
10752                    .await
10753                    .unwrap()
10754            }
10755        };
10756        assert_eq!(
10757            open(with_role_versions(&[("tool-provider", "v1")])).await,
10758            v1
10759        );
10760        assert_eq!(open(CallOptions::default()).await, legacy);
10761        assert_eq!(
10762            open(CallOptions {
10763                role_versions: Some(BTreeMap::new()),
10764                ..CallOptions::default()
10765            })
10766            .await,
10767            legacy,
10768            "an empty map declares nothing and reuses the legacy route"
10769        );
10770        assert!(
10771            receiver.try_recv().is_err(),
10772            "a cache hit must not send a route.open"
10773        );
10774        shared.close_sync("test complete");
10775    }
10776
10777    #[tokio::test]
10778    async fn scoped_routes_are_cached_per_owner_ref_and_epoch_and_apart_from_unscoped() {
10779        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(8));
10780        let selector = scope_selector("owner", "session-a", 1);
10781        let (request, first) = open_answered(
10782            &shared,
10783            &consumer,
10784            &mut receiver,
10785            Some(selector.clone()),
10786            61,
10787            "first scoped open",
10788        )
10789        .await;
10790        assert_eq!(request["scope"], serde_json::to_value(&selector).unwrap());
10791
10792        // The same selector again is a cache hit: no route.open, same handle.
10793        let again = consumer
10794            .open_route_scoped(
10795                restart_target("plexus"),
10796                restart_identity(),
10797                selector,
10798                CallOptions::default(),
10799            )
10800            .await
10801            .unwrap();
10802        assert_eq!(again, first);
10803        assert!(
10804            receiver.try_recv().is_err(),
10805            "a cache hit must not send a route.open"
10806        );
10807
10808        let mut handles = vec![first];
10809        for (channel, scope, why) in [
10810            (
10811                62,
10812                Some(scope_selector("owner", "session-a", 2)),
10813                "another epoch of the same scope must open its own route",
10814            ),
10815            (
10816                63,
10817                Some(scope_selector("owner", "session-b", 1)),
10818                "another scope ref must open its own route",
10819            ),
10820            (
10821                64,
10822                Some(scope_selector("other-owner", "session-a", 1)),
10823                "another owner's scope must open its own route",
10824            ),
10825            (65, None, "an unscoped open must not reuse a scoped route"),
10826        ] {
10827            let expected_scope = scope
10828                .as_ref()
10829                .map(|scope| serde_json::to_value(scope).unwrap());
10830            let (request, handle) =
10831                open_answered(&shared, &consumer, &mut receiver, scope, channel, why).await;
10832            assert_eq!(
10833                request.get("scope").cloned(),
10834                expected_scope,
10835                "the route.open must carry exactly the requested scope: {why}"
10836            );
10837            assert!(!handles.contains(&handle), "{why}");
10838            handles.push(handle);
10839        }
10840        shared.close_sync("test complete");
10841    }
10842
10843    #[tokio::test]
10844    async fn a_dropped_scoped_route_reopens_with_the_same_selector() {
10845        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(7));
10846        let selector = scope_selector("owner", "session-a", 3);
10847        let (first_request, first) = open_answered(
10848            &shared,
10849            &consumer,
10850            &mut receiver,
10851            Some(selector.clone()),
10852            51,
10853            "first scoped open",
10854        )
10855        .await;
10856
10857        // The daemon ends the route, as it does when the provider restarts.
10858        let goodbye = Frame::build(
10859            FrameType::Goodbye,
10860            Flags::new(false, Priority::Interactive, false),
10861            first.channel,
10862            first.epoch,
10863            0,
10864            Vec::new(),
10865        )
10866        .unwrap();
10867        assert!(dispatch_frame(&shared, 1, goodbye).await);
10868        assert!(matches!(
10869            shared.route_state(first),
10870            Err(CallError::StaleRouteHandle(_))
10871        ));
10872
10873        let (second_request, second) = open_answered(
10874            &shared,
10875            &consumer,
10876            &mut receiver,
10877            Some(selector.clone()),
10878            52,
10879            "the reopen after the route dropped",
10880        )
10881        .await;
10882        assert_eq!(
10883            first_request["scope"],
10884            serde_json::to_value(&selector).unwrap()
10885        );
10886        assert_eq!(second_request["scope"], first_request["scope"]);
10887        assert_ne!(second, first);
10888        shared.close_sync("test complete");
10889    }
10890
10891    /// Refuse every scoped route.open with `code` until the open settles, and
10892    /// return how many attempts were served and the error the caller got.
10893    async fn refuse_scoped_opens(code: &str) -> (usize, CallError) {
10894        refuse_scoped_operation(code, "open").await
10895    }
10896
10897    async fn refuse_scoped_operation(code: &str, operation: &str) -> (usize, CallError) {
10898        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(9));
10899        let selector = scope_selector("owner", "session-a", 1);
10900        let options = CallOptions {
10901            scope: Some(selector.clone()),
10902            timeout: Duration::from_secs(2),
10903            route_retry: RetryBackoff {
10904                base: Duration::ZERO,
10905                cap: Duration::ZERO,
10906                max_attempts: 2,
10907            },
10908            route_retry_deadline: Duration::from_millis(150),
10909            ..CallOptions::default()
10910        };
10911        let operation = operation.to_string();
10912        let mut task = tokio::spawn(async move {
10913            match operation.as_str() {
10914                "call" => consumer
10915                    .call(
10916                        restart_target("plexus"),
10917                        restart_identity(),
10918                        b"{}".to_vec(),
10919                        options,
10920                    )
10921                    .await
10922                    .map(|_| ()),
10923                "subscribe" => consumer
10924                    .subscribe(
10925                        restart_target("plexus"),
10926                        restart_identity(),
10927                        b"{}".to_vec(),
10928                        SubscribeOptions {
10929                            scope: options.scope,
10930                            route_open_timeout: options.timeout,
10931                            route_retry: options.route_retry,
10932                            route_retry_deadline: options.route_retry_deadline,
10933                            ..SubscribeOptions::default()
10934                        },
10935                    )
10936                    .await
10937                    .map(|_| ()),
10938                "open" => consumer
10939                    .open_route_scoped(
10940                        restart_target("plexus"),
10941                        restart_identity(),
10942                        scope_selector("owner", "session-a", 1),
10943                        options,
10944                    )
10945                    .await
10946                    .map(|_| ()),
10947                _ => unreachable!(),
10948            }
10949        });
10950        let mut attempts = 0usize;
10951        let err = loop {
10952            tokio::select! {
10953                command = receiver.recv() => {
10954                    let Some(command) = command else {
10955                        break task.await.unwrap().expect_err("route.open must be refused");
10956                    };
10957                    let open: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
10958                    assert_eq!(open["scope"], serde_json::to_value(&selector).unwrap());
10959                    attempts += 1;
10960                    let frame = route_open_answer(
10961                        command.frame.header.corr,
10962                        0,
10963                        Some(ErrorBody::new(code, "test refusal")),
10964                    );
10965                    assert!(dispatch_frame(&shared, 1, frame).await);
10966                }
10967                joined = &mut task => {
10968                    break joined.unwrap().expect_err("route.open must be refused");
10969                }
10970            }
10971        };
10972        shared.close_sync("test complete");
10973        (attempts, err)
10974    }
10975
10976    #[tokio::test]
10977    async fn scoped_managed_operations_retry_only_transient_scope_refusals() {
10978        for operation in ["call", "subscribe"] {
10979            for (code, retryable) in [
10980                (error_codes::SCOPE_NOT_SYNCED, true),
10981                (error_codes::SCOPE_CHANGED, true),
10982                (error_codes::SCOPE_ENDED, false),
10983                (error_codes::SCOPE_NOT_LIVE, false),
10984                (error_codes::SCOPE_EPOCH_REQUIRED, false),
10985                (error_codes::SCOPE_NOT_CARRIER, false),
10986            ] {
10987                let (attempts, err) = refuse_scoped_operation(code, operation).await;
10988                if retryable {
10989                    assert!(attempts > 1, "{operation}: {code} must be retried");
10990                } else {
10991                    assert_eq!(attempts, 1, "{operation}: {code} must be terminal");
10992                }
10993                assert!(matches!(err, CallError::NotSent(_)), "{operation}: {err}");
10994                assert_eq!(err.never_forwarded(), Some(true));
10995                assert_eq!(err.route_open_refusal().unwrap().code, code);
10996            }
10997        }
10998    }
10999
11000    #[tokio::test]
11001    async fn scoped_open_retries_not_synced_and_changed_and_ends_on_the_terminal_scope_codes() {
11002        for code in [error_codes::SCOPE_NOT_SYNCED, error_codes::SCOPE_CHANGED] {
11003            let (attempts, err) = refuse_scoped_opens(code).await;
11004            assert!(attempts > 1, "{code} must be retried, served {attempts}");
11005            assert_eq!(
11006                err.route_open_refusal().map(|body| body.code.as_str()),
11007                Some(code)
11008            );
11009        }
11010        for code in [
11011            error_codes::SCOPE_ENDED,
11012            error_codes::SCOPE_NOT_LIVE,
11013            error_codes::SCOPE_EPOCH_REQUIRED,
11014            error_codes::SCOPE_NOT_CARRIER,
11015        ] {
11016            let (attempts, err) = refuse_scoped_opens(code).await;
11017            assert_eq!(attempts, 1, "{code} is terminal and must not be retried");
11018            assert!(matches!(err, CallError::NotSent(_)));
11019            assert_eq!(
11020                err.route_open_refusal().map(|body| body.code.as_str()),
11021                Some(code)
11022            );
11023        }
11024    }
11025
11026    /// The daemon refuses the first route.open with `module_warming`, then the
11027    /// retry is written and accepted but never answered, so the retry deadline
11028    /// expires while that attempt is still waiting. The caller must still get
11029    /// the refusal it already received, as `NotSent`, rather than the bare
11030    /// "timed out at its deadline" of the unanswered attempt. A busy daemon
11031    /// that answers the final retry a few milliseconds late hits this path.
11032    #[tokio::test]
11033    async fn refusal_survives_a_retry_still_in_flight_at_the_deadline() {
11034        let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(11));
11035        let options = CallOptions {
11036            timeout: Duration::from_secs(5),
11037            route_retry: RetryBackoff {
11038                base: Duration::ZERO,
11039                cap: Duration::ZERO,
11040                max_attempts: 2,
11041            },
11042            route_retry_deadline: Duration::from_millis(300),
11043            ..CallOptions::default()
11044        };
11045        let mut task = tokio::spawn(async move {
11046            consumer
11047                .open_route(restart_target("warming"), restart_identity(), options)
11048                .await
11049        });
11050        let generation = shared.lock_inner().generation;
11051        let refusal = ErrorBody {
11052            code: error_codes::MODULE_WARMING.to_string(),
11053            message: "warming is not ready".to_string(),
11054            detail: Some(serde_json::json!({"reason": "required_capability_unprovided"})),
11055        };
11056        let mut attempts = 0usize;
11057        let mut held = false;
11058        let err = loop {
11059            tokio::select! {
11060                command = receiver.recv() => {
11061                    let Some(command) = command else {
11062                        break task.await.unwrap().expect_err("route.open must fail");
11063                    };
11064                    if command.frame.header.ty != FrameType::Request {
11065                        continue;
11066                    }
11067                    attempts += 1;
11068                    if attempts == 1 {
11069                        let frame = route_open_answer(
11070                            command.frame.header.corr,
11071                            0,
11072                            Some(refusal.clone()),
11073                        );
11074                        assert!(dispatch_frame(&shared, generation, frame).await);
11075                    } else {
11076                        // What the writer task does once the frame is on the
11077                        // socket: from here a timeout is OutcomeUnknown.
11078                        held = shared.mark_pending_accepted(
11079                            command.pending.expect("a route.open is a pending request"),
11080                        );
11081                    }
11082                }
11083                joined = &mut task => {
11084                    break joined.unwrap().expect_err("route.open must fail");
11085                }
11086            }
11087        };
11088        shared.close_sync("test complete");
11089        assert_eq!(
11090            attempts, 2,
11091            "one refused attempt, then one held past the deadline"
11092        );
11093        assert!(
11094            held,
11095            "the second attempt must be accepted and left unanswered"
11096        );
11097        assert!(
11098            err.is_not_sent(),
11099            "a refused route never delivered the request: {err}"
11100        );
11101        let body = err
11102            .route_open_refusal()
11103            .unwrap_or_else(|| panic!("the refusal must survive the deadline: {err}"));
11104        assert_eq!(body.code, error_codes::MODULE_WARMING);
11105        assert_eq!(body.detail, refusal.detail);
11106    }
11107
11108    #[test]
11109    fn every_scope_close_reason_must_not_reopen() {
11110        for reason in [
11111            subc_protocol::RouteCloseReason::ScopeEnded,
11112            subc_protocol::RouteCloseReason::ScopeCarrierRemoved,
11113            subc_protocol::RouteCloseReason::ScopeDelegationChanged,
11114            subc_protocol::RouteCloseReason::ScopeParentEnded,
11115        ] {
11116            let wire = serde_json::to_value(reason).unwrap();
11117            let wire = wire.as_str().expect("a close reason is a string");
11118            assert!(wire.starts_with("scope_"), "{wire}");
11119            assert_eq!(
11120                RouteCloseReason::from_wire(wire).disposition(),
11121                RouteCloseDisposition::MustNotReopen,
11122                "a route closed for {wire} must not be reopened"
11123            );
11124        }
11125    }
11126
11127    // The fake module receives the queued Request and injects frames through the
11128    // same dispatcher as the socket reader, without a daemon process.
11129    async fn watch_subscribed() -> (
11130        SubcConsumer,
11131        mpsc::Receiver<WriteCommand>,
11132        Subscription,
11133        Frame,
11134    ) {
11135        let (shared, mut rx, handle) = reverse_test_shared(ReverseRequestRegistry::new());
11136        shared.lock_inner().one_shot_routes.insert(
11137            handle.channel,
11138            RouteState {
11139                handle,
11140                sem: Arc::new(Semaphore::new(1)),
11141                watch_sem: None,
11142                opted_in: false,
11143            },
11144        );
11145        let consumer = SubcConsumer { shared };
11146        let subscription = consumer
11147            .subscribe_route(&handle, b"watch".to_vec(), SubscribeOptions::default())
11148            .await
11149            .unwrap();
11150        let request = rx.recv().await.unwrap().frame;
11151        (consumer, rx, subscription, request)
11152    }
11153
11154    fn watch_terminal(request: &Frame, ty: FrameType, body: Vec<u8>) -> Frame {
11155        Frame::build(
11156            ty,
11157            Flags::new(false, Priority::Interactive, false),
11158            request.header.channel,
11159            request.header.epoch,
11160            request.header.corr,
11161            body,
11162        )
11163        .unwrap()
11164    }
11165
11166    #[tokio::test]
11167    async fn subscription_ended_preserves_response_body_and_closed_stays_ok() {
11168        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11169        let body = vec![0, 255, 128, 1, 10];
11170        assert!(
11171            dispatch_frame(
11172                &consumer.shared,
11173                1,
11174                watch_terminal(&request, FrameType::Response, body.clone())
11175            )
11176            .await
11177        );
11178        subscription.closed().await.unwrap();
11179        assert_eq!(
11180            subscription.ended().await,
11181            SubscriptionEnd::Response(body.clone())
11182        );
11183        subscription.unsubscribe().unwrap();
11184        assert_eq!(subscription.ended().await, SubscriptionEnd::Response(body));
11185        assert_eq!(subscription.events().recv().await, None);
11186    }
11187
11188    #[tokio::test]
11189    async fn subscription_ended_distinguishes_empty_response_from_stream_end() {
11190        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11191        assert!(
11192            dispatch_frame(
11193                &consumer.shared,
11194                1,
11195                watch_terminal(&request, FrameType::Response, Vec::new())
11196            )
11197            .await
11198        );
11199        assert_eq!(
11200            subscription.ended().await,
11201            SubscriptionEnd::Response(Vec::new())
11202        );
11203        subscription.closed().await.unwrap();
11204    }
11205
11206    #[tokio::test]
11207    async fn subscription_ended_reports_stream_end_and_closed_stays_ok() {
11208        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11209        assert!(
11210            dispatch_frame(
11211                &consumer.shared,
11212                1,
11213                watch_terminal(&request, FrameType::StreamEnd, Vec::new())
11214            )
11215            .await
11216        );
11217        assert_eq!(subscription.ended().await, SubscriptionEnd::StreamEnd);
11218        subscription.closed().await.unwrap();
11219    }
11220
11221    #[tokio::test]
11222    async fn subscription_ended_reports_module_error_code_and_detail() {
11223        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11224        let error = ErrorBody {
11225            code: "no_grant".to_string(),
11226            message: "not accepted: no grant".to_string(),
11227            detail: Some(serde_json::json!({"capability": "watch"})),
11228        };
11229        assert!(
11230            dispatch_frame(
11231                &consumer.shared,
11232                1,
11233                watch_terminal(
11234                    &request,
11235                    FrameType::Error,
11236                    serde_json::to_vec(&error).unwrap()
11237                )
11238            )
11239            .await
11240        );
11241        assert_eq!(
11242            subscription.ended().await,
11243            SubscriptionEnd::Error(error.clone())
11244        );
11245        let CallError::Module(closed_error) = subscription.closed().await.unwrap_err() else {
11246            panic!("closed must still return the module error");
11247        };
11248        assert_eq!(closed_error, error);
11249        subscription.unsubscribe().unwrap();
11250        assert_eq!(subscription.ended().await, SubscriptionEnd::Error(error));
11251    }
11252
11253    #[tokio::test]
11254    async fn subscription_ended_reports_unsubscribe_as_cancelled_and_ignores_late_terminal() {
11255        let (consumer, mut rx, mut subscription, request) = watch_subscribed().await;
11256        subscription.unsubscribe().unwrap();
11257        subscription.unsubscribe().unwrap();
11258        subscription.closed().await.unwrap();
11259        assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
11260        let cancel = rx.recv().await.unwrap().frame;
11261        assert_eq!(cancel.header.ty, FrameType::Cancel);
11262        assert_eq!(cancel.header.corr, request.header.corr);
11263        assert!(rx.try_recv().is_err());
11264        assert!(
11265            dispatch_frame(
11266                &consumer.shared,
11267                1,
11268                watch_terminal(&request, FrameType::Response, b"late".to_vec())
11269            )
11270            .await
11271        );
11272        assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
11273    }
11274
11275    #[tokio::test]
11276    async fn subscription_ended_retains_route_close_reason() {
11277        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11278        let push = Frame::build(FrameType::Push, Flags::new(false, Priority::Interactive, false), 0, 0, 0,
11279            serde_json::to_vec(&serde_json::json!({"op": "route.closed", "module_id": "watch", "reason": "capability_denied", "channels": [request.header.channel]})).unwrap()).unwrap();
11280        assert!(dispatch_frame(&consumer.shared, 1, push).await);
11281        assert!(
11282            dispatch_frame(
11283                &consumer.shared,
11284                1,
11285                watch_terminal(&request, FrameType::Goodbye, Vec::new())
11286            )
11287            .await
11288        );
11289        let reason = RouteEndReason::Daemon(RouteCloseReason::CapabilityDenied);
11290        assert_eq!(
11291            subscription.ended().await,
11292            SubscriptionEnd::RouteClosed {
11293                reason: reason.clone()
11294            }
11295        );
11296        assert_eq!(
11297            subscription.closed().await.unwrap_err().close_reason(),
11298            Some(&reason)
11299        );
11300    }
11301
11302    #[tokio::test]
11303    async fn subscription_ended_reports_connection_loss() {
11304        let (consumer, _rx, mut subscription, _request) = watch_subscribed().await;
11305        consumer
11306            .shared
11307            .handle_generation_drop(1, "fake connection lost".to_string());
11308        assert_eq!(subscription.ended().await, SubscriptionEnd::ConnectionLost);
11309        assert!(subscription.closed().await.is_err());
11310    }
11311
11312    #[tokio::test]
11313    async fn subscription_ended_waiter_wakes_on_stream_end() {
11314        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11315        let (end, dispatched) = tokio::join!(subscription.ended(), async {
11316            tokio::task::yield_now().await;
11317            dispatch_frame(
11318                &consumer.shared,
11319                1,
11320                watch_terminal(&request, FrameType::StreamEnd, Vec::new()),
11321            )
11322            .await
11323        });
11324        assert!(dispatched);
11325        assert_eq!(end, SubscriptionEnd::StreamEnd);
11326        subscription.closed().await.unwrap();
11327    }
11328
11329    #[tokio::test]
11330    async fn subscription_ended_reports_backpressure_without_hiding_closed_error() {
11331        let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11332        for _ in 0..=DEFAULT_SUBSCRIPTION_EVENT_BUFFER {
11333            assert!(
11334                dispatch_frame(
11335                    &consumer.shared,
11336                    1,
11337                    watch_terminal(&request, FrameType::StreamData, vec![1])
11338                )
11339                .await
11340            );
11341        }
11342        assert_eq!(subscription.ended().await, SubscriptionEnd::Backpressure);
11343        assert!(matches!(
11344            subscription.closed().await,
11345            Err(CallError::SubscriptionBackpressure(_))
11346        ));
11347    }
11348
11349    #[tokio::test]
11350    async fn subscription_ended_reports_client_close_as_route_closed_by_caller() {
11351        let (consumer, _rx, mut subscription, _request) = watch_subscribed().await;
11352        consumer.close().await;
11353        assert_eq!(
11354            subscription.ended().await,
11355            SubscriptionEnd::RouteClosed {
11356                reason: RouteEndReason::ClosedByCaller
11357            }
11358        );
11359        assert!(subscription.closed().await.is_err());
11360    }
11361
11362    #[test]
11363    fn drain_pending_channel_can_skip_subscriptions() {
11364        let mut pending = HashMap::new();
11365        let generation = 7;
11366        let channel = 11;
11367        let handle = RouteHandle::new(channel, 3, generation);
11368        let unary_key = PendingKey {
11369            generation,
11370            channel,
11371            epoch: handle.epoch,
11372            corr: 1,
11373        };
11374        let subscription_key = PendingKey {
11375            generation,
11376            channel,
11377            epoch: handle.epoch,
11378            corr: 2,
11379        };
11380        let (unary_tx, _unary_rx) = oneshot::channel();
11381        pending.insert(unary_key, PendingEntry::unary(unary_tx, false, None, None));
11382
11383        let (events_tx, _events_rx) = mpsc::channel(1);
11384        let (closed_tx, _closed_rx) = oneshot::channel();
11385        let (ended_tx, _ended_rx) = watch::channel(None);
11386        let permit = Arc::new(Semaphore::new(1))
11387            .try_acquire_owned()
11388            .expect("test semaphore permit should be available");
11389        pending.insert(
11390            subscription_key,
11391            PendingEntry::subscription(
11392                events_tx,
11393                closed_tx,
11394                ended_tx,
11395                RoutePermit::legacy(permit),
11396                Priority::Interactive,
11397            ),
11398        );
11399
11400        let drained = drain_pending_handle(&mut pending, handle, false);
11401        assert_eq!(drained.len(), 1);
11402        assert!(pending.contains_key(&subscription_key));
11403
11404        let drained = drain_pending_handle(&mut pending, handle, true);
11405        assert_eq!(drained.len(), 1);
11406        assert!(pending.is_empty());
11407    }
11408
11409    fn response_frame(channel: u16, epoch: u32, corr: u64, body: Vec<u8>) -> Frame {
11410        Frame::build(
11411            FrameType::Response,
11412            Flags::new(false, Priority::Interactive, false),
11413            channel,
11414            epoch,
11415            corr,
11416            body,
11417        )
11418        .unwrap()
11419    }
11420
11421    #[tokio::test]
11422    async fn stale_epoch_ingress_drops_without_settling_matching_corr() {
11423        let shared = Arc::new(reader_skew_tests::legacy_shared(
11424            PathBuf::from("/tmp/does-not-exist"),
11425            ConsumerOptions::default(),
11426        ));
11427        let (writer, _rx) = mpsc::channel(4);
11428        let current = RouteHandle::new(9, 2, 1);
11429        let stale_key = PendingKey {
11430            generation: 1,
11431            channel: 9,
11432            epoch: 1,
11433            corr: 77,
11434        };
11435        let key = PendingKey {
11436            generation: 1,
11437            channel: 9,
11438            epoch: 2,
11439            corr: 77,
11440        };
11441        let (stale_tx, mut stale_response) = oneshot::channel();
11442        let (tx, mut response) = oneshot::channel();
11443        {
11444            let mut inner = shared.lock_inner();
11445            inner.writer = Some(writer);
11446            inner.daemon_ver = "0.39.0".into();
11447            inner.route_epochs.insert(9, current);
11448            inner
11449                .pending
11450                .insert(stale_key, PendingEntry::unary(stale_tx, false, None, None));
11451            inner
11452                .pending
11453                .insert(key, PendingEntry::unary(tx, false, None, None));
11454        }
11455
11456        assert!(dispatch_frame(&shared, 1, response_frame(9, 1, 77, b"stale".to_vec())).await);
11457        assert!(matches!(
11458            response.try_recv(),
11459            Err(oneshot::error::TryRecvError::Empty)
11460        ));
11461        assert!(matches!(
11462            stale_response.try_recv(),
11463            Err(oneshot::error::TryRecvError::Empty)
11464        ));
11465        assert!(shared.lock_inner().pending.contains_key(&stale_key));
11466        assert!(shared.lock_inner().pending.contains_key(&key));
11467        assert_eq!(shared.lock_inner().dropped_route_frames, 1);
11468
11469        assert!(dispatch_frame(&shared, 1, response_frame(9, 2, 77, b"current".to_vec())).await);
11470        let PendingResult::Terminal(PendingTerminal::Response { body, .. }) =
11471            response.await.unwrap()
11472        else {
11473            panic!("current epoch must settle its own pending request");
11474        };
11475        assert_eq!(body, b"current");
11476        assert!(shared.lock_inner().pending.contains_key(&stale_key));
11477    }
11478
11479    #[tokio::test]
11480    async fn route_poll_response_must_echo_expected_handle_before_settling() {
11481        let shared = Arc::new(reader_skew_tests::legacy_shared(
11482            PathBuf::from("/tmp/does-not-exist"),
11483            ConsumerOptions::default(),
11484        ));
11485        let (writer, _rx) = mpsc::channel(4);
11486        let handle = RouteHandle::new(3, 9, 1);
11487        let key = PendingKey {
11488            generation: 1,
11489            channel: 0,
11490            epoch: 0,
11491            corr: 88,
11492        };
11493        let (tx, mut response) = oneshot::channel();
11494        {
11495            let mut inner = shared.lock_inner();
11496            inner.writer = Some(writer);
11497            inner.daemon_ver = "0.39.0".into();
11498            inner.route_epochs.insert(handle.channel, handle);
11499            inner
11500                .pending
11501                .insert(key, PendingEntry::unary(tx, false, Some(handle), None));
11502        }
11503        let wrong = serde_json::to_vec(&ClientControlResponse::RoutePoll {
11504            route_channel: handle.channel,
11505            route_epoch: handle.epoch + 1,
11506            status: Some("wrong".to_string()),
11507            live: Some(true),
11508        })
11509        .unwrap();
11510        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, key.corr, wrong)).await);
11511        assert!(matches!(
11512            response.try_recv(),
11513            Err(oneshot::error::TryRecvError::Empty)
11514        ));
11515        assert!(shared.lock_inner().pending.contains_key(&key));
11516
11517        let correct = serde_json::to_vec(&ClientControlResponse::RoutePoll {
11518            route_channel: handle.channel,
11519            route_epoch: handle.epoch,
11520            status: Some("ready".to_string()),
11521            live: Some(true),
11522        })
11523        .unwrap();
11524        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, key.corr, correct)).await);
11525        assert!(matches!(
11526            response.await.unwrap(),
11527            PendingResult::Terminal(PendingTerminal::Response { .. })
11528        ));
11529    }
11530
11531    #[tokio::test]
11532    async fn stale_connection_handle_emits_no_request_cancel_or_goodbye() {
11533        let shared = Arc::new(reader_skew_tests::legacy_shared(
11534            PathBuf::from("/tmp/does-not-exist"),
11535            ConsumerOptions::default(),
11536        ));
11537        let (writer, mut rx) = mpsc::channel(4);
11538        let stale = RouteHandle::new(4, 1, 1);
11539        let current = RouteHandle::new(4, 1, 2);
11540        {
11541            let mut inner = shared.lock_inner();
11542            inner.generation = 2;
11543            inner.writer = Some(writer);
11544            inner.daemon_ver = "0.39.0".into();
11545            inner.route_epochs.insert(4, current);
11546        }
11547
11548        let err = shared
11549            .send_request(RequestSend {
11550                binary: false,
11551                expected_handle: Some(stale),
11552                channel: stale.channel,
11553                epoch: stale.epoch,
11554                body: b"request".to_vec(),
11555                priority: Priority::Interactive,
11556                admission_class: AdmissionClass::Normal,
11557                deadline: Instant::now() + Duration::from_millis(10),
11558                retain_late_route_open: false,
11559                route_open_reverse_requests: None,
11560            })
11561            .await
11562            .unwrap_err();
11563        assert!(matches!(err, CallError::StaleRouteHandle(handle) if handle == stale));
11564        shared.send_cancel(stale, 8, Priority::Interactive);
11565        assert!(!shared.send_route_goodbye(stale, false));
11566        assert!(
11567            rx.try_recv().is_err(),
11568            "stale operations must not queue frames"
11569        );
11570    }
11571
11572    #[tokio::test]
11573    async fn route_poll_refusal_preserves_daemon_code_message_and_detail() {
11574        let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
11575        let handle = RouteHandle::new(3, 9, 1);
11576        shared
11577            .lock_inner()
11578            .route_epochs
11579            .insert(handle.channel, handle);
11580        let poll = consumer.poll_route(&handle, PollKind::Liveness, Duration::from_secs(1));
11581        tokio::pin!(poll);
11582        assert_pending(poll.as_mut()).await;
11583        let request = receiver.try_recv().unwrap();
11584        let refusal = ErrorBody {
11585            code: "unknown_route".into(),
11586            message: "the route is no longer present".into(),
11587            detail: Some(serde_json::json!({ "route_channel": 3, "route_epoch": 9 })),
11588        };
11589        assert!(
11590            dispatch_frame(
11591                &shared,
11592                1,
11593                channel_zero_frame(
11594                    FrameType::Error,
11595                    request.frame.header.corr,
11596                    serde_json::to_vec(&refusal).unwrap(),
11597                ),
11598            )
11599            .await
11600        );
11601        let err = poll.await.unwrap_err();
11602        assert_eq!(err.code(), Some("unknown_route"));
11603        let CallError::Module(body) = err else {
11604            panic!("a delivered refusal must not be classified as a send failure");
11605        };
11606        assert_eq!(body.code, refusal.code);
11607        assert_eq!(body.message, refusal.message);
11608        assert_eq!(body.detail, refusal.detail);
11609    }
11610
11611    #[tokio::test]
11612    async fn late_route_open_queues_goodbye_and_full_queue_closes_connection() {
11613        let shared = Arc::new(reader_skew_tests::legacy_shared(
11614            PathBuf::from("/tmp/does-not-exist"),
11615            ConsumerOptions::default(),
11616        ));
11617        let (writer, mut rx) = mpsc::channel(2);
11618        let key = PendingKey {
11619            generation: 1,
11620            channel: 0,
11621            epoch: 0,
11622            corr: 41,
11623        };
11624        let (tx, response) = oneshot::channel();
11625        drop(response);
11626        {
11627            let mut inner = shared.lock_inner();
11628            inner.writer = Some(writer);
11629            inner.daemon_ver = "0.39.0".into();
11630            inner
11631                .pending
11632                .insert(key, PendingEntry::unary(tx, true, None, None));
11633        }
11634        let body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11635            request_window: None,
11636            watch_window: None,
11637            route_channel: 12,
11638            route_epoch: 7,
11639        })
11640        .unwrap();
11641        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, 41, body)).await);
11642        let cleanup = rx.recv().await.unwrap().frame;
11643        assert_eq!(cleanup.header.ty, FrameType::Goodbye);
11644        assert_eq!((cleanup.header.channel, cleanup.header.epoch), (12, 7));
11645
11646        let shared = Arc::new(reader_skew_tests::legacy_shared(
11647            PathBuf::from("/tmp/does-not-exist"),
11648            ConsumerOptions {
11649                reconnect_backoff: RetryBackoff {
11650                    max_attempts: 1,
11651                    ..RetryBackoff::default()
11652                },
11653                ..ConsumerOptions::default()
11654            },
11655        ));
11656        let (writer, _rx) = mpsc::channel(1);
11657        let filler = response_frame(0, 0, 1, Vec::new());
11658        writer
11659            .try_send(WriteCommand {
11660                frame: filler,
11661                pending: None,
11662            })
11663            .unwrap();
11664        let key = PendingKey {
11665            generation: 1,
11666            channel: 0,
11667            epoch: 0,
11668            corr: 42,
11669        };
11670        let (tx, response) = oneshot::channel();
11671        drop(response);
11672        {
11673            let mut inner = shared.lock_inner();
11674            inner.writer = Some(writer);
11675            inner.daemon_ver = "0.39.0".into();
11676            inner
11677                .pending
11678                .insert(key, PendingEntry::unary(tx, true, None, None));
11679        }
11680        let body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11681            request_window: None,
11682            watch_window: None,
11683            route_channel: 13,
11684            route_epoch: 8,
11685        })
11686        .unwrap();
11687        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, 42, body)).await);
11688        assert!(shared.lock_inner().writer.is_none());
11689    }
11690
11691    #[tokio::test]
11692    async fn correlation_allocator_emits_max_once_then_closes_without_reuse() {
11693        let shared = Arc::new(reader_skew_tests::legacy_shared(
11694            PathBuf::from("/tmp/does-not-exist"),
11695            ConsumerOptions {
11696                reconnect_backoff: RetryBackoff {
11697                    max_attempts: 1,
11698                    ..RetryBackoff::default()
11699                },
11700                ..ConsumerOptions::default()
11701            },
11702        ));
11703        let (writer, mut rx) = mpsc::channel(4);
11704        {
11705            let mut inner = shared.lock_inner();
11706            inner.writer = Some(writer);
11707            inner.daemon_ver = "0.39.0".into();
11708            inner.next_corr = Some(u64::MAX);
11709        }
11710        let request_shared = Arc::clone(&shared);
11711        let request = tokio::spawn(async move {
11712            request_shared
11713                .send_request(RequestSend {
11714                    binary: false,
11715                    expected_handle: None,
11716                    channel: 0,
11717                    epoch: 0,
11718                    body: Vec::new(),
11719                    priority: Priority::Interactive,
11720                    admission_class: AdmissionClass::Normal,
11721                    deadline: Instant::now() + Duration::from_secs(1),
11722                    retain_late_route_open: false,
11723                    route_open_reverse_requests: None,
11724                })
11725                .await
11726        });
11727        let command = rx.recv().await.unwrap();
11728        assert_eq!(command.frame.header.corr, u64::MAX);
11729        assert!(dispatch_frame(&shared, 1, response_frame(0, 0, u64::MAX, Vec::new()),).await);
11730        assert!(request.await.unwrap().is_ok());
11731
11732        let exhausted = shared
11733            .send_request(RequestSend {
11734                binary: false,
11735                expected_handle: None,
11736                channel: 0,
11737                epoch: 0,
11738                body: Vec::new(),
11739                priority: Priority::Interactive,
11740                admission_class: AdmissionClass::Normal,
11741                deadline: Instant::now() + Duration::from_millis(10),
11742                retain_late_route_open: false,
11743                route_open_reverse_requests: None,
11744            })
11745            .await
11746            .unwrap_err();
11747        assert!(matches!(exhausted, CallError::NotSent(_)));
11748        assert!(rx.try_recv().is_err());
11749        assert!(shared.lock_inner().writer.is_none());
11750    }
11751
11752    #[tokio::test]
11753    async fn managed_call_deadline_bounds_flow_control_wait() {
11754        let shared = Arc::new(reader_skew_tests::legacy_shared(
11755            PathBuf::from("/tmp/does-not-exist"),
11756            ConsumerOptions::default(),
11757        ));
11758        let (writer, mut rx) = mpsc::channel(4);
11759        let target = RouteTarget::ToolProvider {
11760            module_id: "flow-controlled".to_string(),
11761        };
11762        let identity = BindIdentity::new("test".to_string(), "deadline".to_string());
11763        let consumer_identity = Some(ConsumerIdentity {
11764            module_id: "caller".to_string(),
11765            launch_nonce: "nonce".to_string(),
11766        });
11767        let first_opts = CallOptions {
11768            timeout: Duration::from_secs(1),
11769            consumer_identity: consumer_identity.clone(),
11770            ..CallOptions::default()
11771        };
11772        let second_opts = CallOptions {
11773            timeout: Duration::from_millis(25),
11774            consumer_identity,
11775            ..CallOptions::default()
11776        };
11777        let key = RouteKey::new(
11778            &target,
11779            &identity,
11780            first_opts.consumer_identity.as_ref(),
11781            None,
11782        );
11783        let handle = RouteHandle::new(5, 3, 1);
11784        {
11785            let mut inner = shared.lock_inner();
11786            inner.writer = Some(writer);
11787            inner.daemon_ver = "0.39.0".into();
11788            inner.cache_route(
11789                key,
11790                RouteState {
11791                    handle,
11792                    sem: Arc::new(Semaphore::new(1)),
11793                    watch_sem: None,
11794                    opted_in: false,
11795                },
11796            );
11797        }
11798
11799        let first = tokio::spawn({
11800            let consumer = SubcConsumer {
11801                shared: Arc::clone(&shared),
11802            };
11803            let target = target.clone();
11804            let identity = identity.clone();
11805            async move {
11806                consumer
11807                    .call(target, identity, b"first".to_vec(), first_opts)
11808                    .await
11809            }
11810        });
11811        let first_frame = rx
11812            .recv()
11813            .await
11814            .expect("the first request should enter the fake daemon queue");
11815        assert_eq!(first_frame.frame.header.ty, FrameType::Request);
11816        assert_eq!(first_frame.frame.body, b"first");
11817        assert!(shared.mark_pending_accepted(
11818            first_frame
11819                .pending
11820                .expect("request commands retain their pending key"),
11821        ));
11822
11823        let consumer = SubcConsumer {
11824            shared: Arc::clone(&shared),
11825        };
11826        let result = tokio::time::timeout(
11827            Duration::from_millis(250),
11828            consumer.call(target, identity, b"second".to_vec(), second_opts),
11829        )
11830        .await
11831        .expect("a flow-controlled call must finish at its own deadline")
11832        .unwrap_err();
11833        assert!(matches!(result, CallError::NotSent(_)));
11834        assert!(
11835            rx.try_recv().is_err(),
11836            "the timed-out second request must not reach the fake daemon"
11837        );
11838
11839        first.abort();
11840        let _ = first.await;
11841    }
11842
11843    #[tokio::test]
11844    async fn admitted_route_open_emits_one_frame_without_retrying_daemon_errors() {
11845        let shared = Arc::new(reader_skew_tests::legacy_shared(
11846            PathBuf::from("/tmp/does-not-exist"),
11847            ConsumerOptions {
11848                call_timeout: Duration::from_secs(1),
11849                ..ConsumerOptions::default()
11850            },
11851        ));
11852        let (writer, mut rx) = mpsc::channel(4);
11853        {
11854            let mut inner = shared.lock_inner();
11855            inner.writer = Some(writer);
11856            inner.daemon_ver = "0.39.0".into();
11857        }
11858
11859        let consumer = SubcConsumer {
11860            shared: Arc::clone(&shared),
11861        };
11862        let target = RouteTarget::ToolProvider {
11863            module_id: "admitted-target".to_string(),
11864        };
11865        let identity = BindIdentity::new("test".to_string(), "admitted".to_string());
11866        let task = tokio::spawn(async move {
11867            consumer
11868                .open_route_with_admission_facts(
11869                    target,
11870                    identity,
11871                    serde_json::json!({"schema": 1, "verified_class": "member"}),
11872                )
11873                .await
11874        });
11875
11876        let command = rx.recv().await.expect("one route.open must be queued");
11877        let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
11878        let ClientControlRequest::RouteOpen {
11879            admission_facts, ..
11880        } = request
11881        else {
11882            panic!("expected route.open")
11883        };
11884        assert_eq!(
11885            admission_facts,
11886            Some(serde_json::json!({"schema": 1, "verified_class": "member"}))
11887        );
11888
11889        let error_body = serde_json::to_vec(&ErrorBody {
11890            code: "admission_facts_not_permitted".to_string(),
11891            message: "not permitted".to_string(),
11892            detail: None,
11893        })
11894        .unwrap();
11895        assert!(
11896            dispatch_frame(
11897                &shared,
11898                1,
11899                Frame::build(
11900                    FrameType::Error,
11901                    Flags::new(false, Priority::Interactive, false),
11902                    0,
11903                    0,
11904                    command.frame.header.corr,
11905                    error_body,
11906                )
11907                .unwrap(),
11908            )
11909            .await
11910        );
11911        let result = task.await.unwrap();
11912        assert!(matches!(result, Err(CallError::NotSent(_))));
11913        assert!(rx.try_recv().is_err(), "one-shot route.open must not retry");
11914    }
11915
11916    /// Drive one admitted route.open to success on a test writer and return the
11917    /// route.open request that was sent, the resolved handle, and the writer.
11918    async fn open_admitted_route_for_test(
11919        opts: Option<CallOptions>,
11920    ) -> (
11921        Arc<Shared>,
11922        SubcConsumer,
11923        ClientControlRequest,
11924        Result<RouteHandle, CallError>,
11925        mpsc::Receiver<WriteCommand>,
11926    ) {
11927        let shared = writer_test_shared();
11928        let (writer, mut rx) = mpsc::channel(8);
11929        let generation = {
11930            let mut inner = shared.lock_inner();
11931            inner.writer = Some(writer);
11932            inner.daemon_ver = "0.39.0".into();
11933            inner.generation
11934        };
11935        let consumer = SubcConsumer {
11936            shared: Arc::clone(&shared),
11937        };
11938        let target = RouteTarget::ToolProvider {
11939            module_id: "cerebellum".to_string(),
11940        };
11941        let identity = BindIdentity::new("test".to_string(), "admitted".to_string());
11942        let facts = serde_json::json!({"schema": 1, "verified_class": "member"});
11943        // The consumer is returned from the task and kept alive by the caller:
11944        // dropping it closes the connection, after which no frame is dispatched.
11945        let task = tokio::spawn(async move {
11946            let result = match opts {
11947                Some(opts) => {
11948                    consumer
11949                        .open_route_with_admission_facts_and_options(target, identity, facts, opts)
11950                        .await
11951                }
11952                None => {
11953                    consumer
11954                        .open_route_with_admission_facts(target, identity, facts)
11955                        .await
11956                }
11957            };
11958            (consumer, result)
11959        });
11960        let command = rx.recv().await.expect("one route.open must be queued");
11961        let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
11962        let response = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11963            request_window: None,
11964            watch_window: None,
11965            route_channel: 21,
11966            route_epoch: 4,
11967        })
11968        .unwrap();
11969        assert!(
11970            dispatch_frame(
11971                &shared,
11972                generation,
11973                Frame::build(
11974                    FrameType::Response,
11975                    Flags::new(false, Priority::Interactive, false),
11976                    0,
11977                    0,
11978                    command.frame.header.corr,
11979                    response,
11980                )
11981                .unwrap(),
11982            )
11983            .await
11984        );
11985        let (consumer, result) = tokio::time::timeout(Duration::from_secs(1), task)
11986            .await
11987            .expect("admitted route.open resolves")
11988            .unwrap();
11989        (shared, consumer, request, result, rx)
11990    }
11991
11992    #[tokio::test]
11993    async fn admitted_route_open_refusal_keeps_the_daemon_code_and_detail() {
11994        let shared = writer_test_shared();
11995        let (writer, mut rx) = mpsc::channel(8);
11996        let generation = {
11997            let mut inner = shared.lock_inner();
11998            inner.writer = Some(writer);
11999            inner.daemon_ver = "0.39.0".into();
12000            inner.generation
12001        };
12002        let consumer = SubcConsumer {
12003            shared: Arc::clone(&shared),
12004        };
12005        let task = tokio::spawn(async move {
12006            let result = consumer
12007                .open_route_with_admission_facts(
12008                    RouteTarget::ToolProvider {
12009                        module_id: "cerebellum".to_string(),
12010                    },
12011                    BindIdentity::new("test".to_string(), "admitted".to_string()),
12012                    serde_json::json!({"schema": 1, "verified_class": "member"}),
12013                )
12014                .await;
12015            (consumer, result)
12016        });
12017        let command = rx.recv().await.expect("one route.open must be queued");
12018        let refusal = ErrorBody {
12019            code: "module_warming".to_string(),
12020            message: "cerebellum is not ready".to_string(),
12021            detail: Some(serde_json::json!({"reason": "declared_not_ready"})),
12022        };
12023        assert!(
12024            dispatch_frame(
12025                &shared,
12026                generation,
12027                Frame::build(
12028                    FrameType::Error,
12029                    Flags::new(false, Priority::Interactive, false),
12030                    0,
12031                    0,
12032                    command.frame.header.corr,
12033                    serde_json::to_vec(&refusal).unwrap(),
12034                )
12035                .unwrap(),
12036            )
12037            .await
12038        );
12039        let (_consumer, result) = tokio::time::timeout(Duration::from_secs(1), task)
12040            .await
12041            .expect("admitted route.open resolves")
12042            .unwrap();
12043        let error = result.expect_err("a refused open is an error");
12044        assert!(
12045            error.is_not_sent(),
12046            "a refused open never reached the module: {error}"
12047        );
12048        let body = error
12049            .route_open_refusal()
12050            .unwrap_or_else(|| panic!("the refusal's code must survive: {error}"));
12051        assert_eq!(body.code, "module_warming");
12052        assert_eq!(
12053            body.detail,
12054            Some(serde_json::json!({"reason": "declared_not_ready"}))
12055        );
12056        assert!(
12057            error.to_string().contains("tool_provider:cerebellum"),
12058            "the error names its target: {error}"
12059        );
12060    }
12061
12062    #[tokio::test]
12063    async fn admitted_route_without_options_opens_and_declares_no_reverse_capabilities() {
12064        let (_shared, _consumer, request, result, _rx) = open_admitted_route_for_test(None).await;
12065        let ClientControlRequest::RouteOpen {
12066            consumer_capabilities,
12067            admission_facts,
12068            ..
12069        } = request
12070        else {
12071            panic!("expected route.open")
12072        };
12073        assert_eq!(consumer_capabilities, None);
12074        assert!(admission_facts.is_some());
12075        let handle = result.expect("admitted route opens");
12076        assert_eq!((handle.channel, handle.epoch), (21, 4));
12077    }
12078
12079    // An admitted route opened with handlers declares their capabilities and
12080    // delivers the provider's reverse requests to them, replying under the
12081    // provider's own correlation id: the browser plane's consent prompts arrive
12082    // as elicitation on exactly this kind of route.
12083    #[tokio::test]
12084    async fn admitted_route_with_options_delivers_elicitation_to_its_handler() {
12085        let opts = CallOptions::default();
12086        let seen = Arc::new(Mutex::new(None));
12087        let seen_by_handler = Arc::clone(&seen);
12088        let reply_body = br#"{"jsonrpc":"2.0","id":3,"result":{"action":"accept"}}"#.to_vec();
12089        let expected_reply = reply_body.clone();
12090        opts.reverse_requests
12091            .on_request("elicitation", move |body, ctx| {
12092                *seen_by_handler
12093                    .lock()
12094                    .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some((body, ctx.corr));
12095                let reply_body = reply_body.clone();
12096                async move { reply_body }
12097            })
12098            .unwrap();
12099
12100        let (shared, _consumer, request, result, mut rx) =
12101            open_admitted_route_for_test(Some(opts)).await;
12102        let ClientControlRequest::RouteOpen {
12103            consumer_capabilities,
12104            admission_facts,
12105            ..
12106        } = request
12107        else {
12108            panic!("expected route.open")
12109        };
12110        assert_eq!(consumer_capabilities, Some(vec!["elicitation".to_string()]));
12111        assert_eq!(
12112            admission_facts,
12113            Some(serde_json::json!({"schema": 1, "verified_class": "member"}))
12114        );
12115        let handle = result.expect("admitted route opens");
12116
12117        let request_body =
12118            br#"{"jsonrpc":"2.0","id":3,"method":"elicitation/create","params":{}}"#.to_vec();
12119        assert!(
12120            dispatch_frame(
12121                &shared,
12122                handle.connection_token(),
12123                reverse_request_frame(handle, 900, request_body.clone()),
12124            )
12125            .await
12126        );
12127        let reply = tokio::time::timeout(Duration::from_secs(1), rx.recv())
12128            .await
12129            .expect("the handler replies")
12130            .unwrap()
12131            .frame;
12132        assert_eq!(reply.header.ty, FrameType::Response);
12133        assert_eq!(reply.header.corr, 900);
12134        assert_eq!(reply.header.channel, 21);
12135        assert_eq!(reply.body, expected_reply);
12136        assert_eq!(
12137            seen.lock()
12138                .unwrap_or_else(|poisoned| poisoned.into_inner())
12139                .clone(),
12140            Some((request_body, 900))
12141        );
12142    }
12143
12144    #[tokio::test]
12145    async fn route_open_waiter_deadline_is_not_sent_without_writing() {
12146        let shared = Arc::new(reader_skew_tests::legacy_shared(
12147            PathBuf::from("/tmp/does-not-exist"),
12148            ConsumerOptions::default(),
12149        ));
12150        let (writer, mut rx) = mpsc::channel(4);
12151        let target = RouteTarget::ToolProvider {
12152            module_id: "single-flight".to_string(),
12153        };
12154        let identity = BindIdentity::new("test".to_string(), "route-open".to_string());
12155        let opts = CallOptions {
12156            timeout: Duration::from_millis(25),
12157            consumer_identity: Some(ConsumerIdentity {
12158                module_id: "caller".to_string(),
12159                launch_nonce: "nonce".to_string(),
12160            }),
12161            ..CallOptions::default()
12162        };
12163        let key = RouteKey::new(&target, &identity, opts.consumer_identity.as_ref(), None);
12164        {
12165            let mut inner = shared.lock_inner();
12166            inner.writer = Some(writer);
12167            inner.daemon_ver = "0.39.0".into();
12168            inner.openings.insert(
12169                key,
12170                Opening {
12171                    waiters: Vec::new(),
12172                    closed: false,
12173                },
12174            );
12175        }
12176
12177        let consumer = SubcConsumer { shared };
12178        let result = tokio::time::timeout(
12179            Duration::from_millis(250),
12180            consumer.open_route(target, identity, opts),
12181        )
12182        .await
12183        .expect("a route.open waiter must finish at its own deadline")
12184        .unwrap_err();
12185        assert!(matches!(result, CallError::NotSent(_)));
12186        assert!(
12187            rx.try_recv().is_err(),
12188            "a timed-out route.open waiter must not write a control frame"
12189        );
12190    }
12191
12192    // A route.open whose control reply never arrives before the deadline has an
12193    // unknown outcome of its own (the daemon may have opened the channel), but
12194    // the managed call's request body was never written. The call and the
12195    // subscription must therefore report NotSent, not OutcomeUnknown: callers
12196    // use that distinction to decide whether a non-idempotent retry is safe.
12197    async fn managed_op_with_unanswered_route_open(subscribe: bool) -> CallError {
12198        let shared = Arc::new(reader_skew_tests::legacy_shared(
12199            PathBuf::from("/tmp/does-not-exist"),
12200            ConsumerOptions::default(),
12201        ));
12202        let (writer, mut rx) = mpsc::channel(4);
12203        {
12204            let mut inner = shared.lock_inner();
12205            inner.writer = Some(writer);
12206            inner.daemon_ver = "0.39.0".into();
12207        }
12208        let consumer = SubcConsumer {
12209            shared: Arc::clone(&shared),
12210        };
12211        let target = RouteTarget::ToolProvider {
12212            module_id: "slow-route-open".to_string(),
12213        };
12214        let identity = BindIdentity::new("test".to_string(), "slow-route-open".to_string());
12215        let task = tokio::spawn(async move {
12216            if subscribe {
12217                consumer
12218                    .subscribe(
12219                        target,
12220                        identity,
12221                        b"{}".to_vec(),
12222                        SubscribeOptions {
12223                            route_open_timeout: Duration::from_millis(200),
12224                            route_retry_deadline: Duration::from_millis(100),
12225                            ..SubscribeOptions::default()
12226                        },
12227                    )
12228                    .await
12229                    .map(|_| ())
12230            } else {
12231                consumer
12232                    .call(
12233                        target,
12234                        identity,
12235                        b"{}".to_vec(),
12236                        CallOptions {
12237                            timeout: Duration::from_millis(200),
12238                            route_retry_deadline: Duration::from_millis(100),
12239                            ..CallOptions::default()
12240                        },
12241                    )
12242                    .await
12243                    .map(|_| ())
12244            }
12245        });
12246
12247        // Play the writer task: accept the route.open onto the wire (so the
12248        // consumer knows the control frame left) and then never answer it,
12249        // which is what a daemon under load looks like from the client.
12250        let command = rx.recv().await.expect("route.open must be queued");
12251        assert_eq!(command.frame.header.channel, 0);
12252        let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
12253        assert!(matches!(request, ClientControlRequest::RouteOpen { .. }));
12254        assert!(shared.mark_pending_accepted(command.pending.expect("route.open is tracked")));
12255
12256        let err = tokio::time::timeout(Duration::from_secs(2), task)
12257            .await
12258            .expect("the managed op must settle at its own deadline")
12259            .unwrap()
12260            .expect_err("an unanswered route.open cannot yield a route");
12261        while let Ok(command) = rx.try_recv() {
12262            assert_eq!(
12263                command.frame.header.channel, 0,
12264                "no data-plane frame may be written without an open route"
12265            );
12266        }
12267        err
12268    }
12269
12270    #[tokio::test]
12271    async fn call_whose_route_open_times_out_after_send_is_not_sent() {
12272        let err = managed_op_with_unanswered_route_open(false).await;
12273        assert!(
12274            matches!(err, CallError::NotSent(_)),
12275            "call body never left the client, got {err:?}"
12276        );
12277    }
12278
12279    #[tokio::test]
12280    async fn subscribe_whose_route_open_times_out_after_send_is_not_sent() {
12281        let err = managed_op_with_unanswered_route_open(true).await;
12282        assert!(
12283            matches!(err, CallError::NotSent(_)),
12284            "subscription request never left the client, got {err:?}"
12285        );
12286    }
12287
12288    #[tokio::test]
12289    async fn route_poll_deadline_bounds_writer_capacity() {
12290        let shared = Arc::new(reader_skew_tests::legacy_shared(
12291            PathBuf::from("/tmp/does-not-exist"),
12292            ConsumerOptions::default(),
12293        ));
12294        let (writer, mut rx) = mpsc::channel(1);
12295        let handle = RouteHandle::new(8, 4, 1);
12296        writer
12297            .try_send(WriteCommand {
12298                frame: response_frame(0, 0, 99, Vec::new()),
12299                pending: None,
12300            })
12301            .expect("the fake daemon queue should accept its filler frame");
12302        {
12303            let mut inner = shared.lock_inner();
12304            inner.writer = Some(writer);
12305            inner.daemon_ver = "0.39.0".into();
12306            inner.route_epochs.insert(handle.channel, handle);
12307        }
12308
12309        let consumer = SubcConsumer { shared };
12310        let result = tokio::time::timeout(
12311            Duration::from_millis(250),
12312            consumer.poll_route(&handle, PollKind::Liveness, Duration::from_millis(25)),
12313        )
12314        .await
12315        .expect("a control request must finish at its own deadline")
12316        .unwrap_err();
12317        assert!(matches!(result, CallError::NotSent(_)));
12318        assert_eq!(
12319            rx.recv()
12320                .await
12321                .expect("the filler must still be the only queued frame")
12322                .frame
12323                .header
12324                .corr,
12325            99
12326        );
12327        assert!(
12328            rx.try_recv().is_err(),
12329            "the timed-out control request must not reach the fake daemon"
12330        );
12331    }
12332
12333    #[tokio::test]
12334    async fn subscription_deadline_bounds_writer_capacity() {
12335        let shared = Arc::new(reader_skew_tests::legacy_shared(
12336            PathBuf::from("/tmp/does-not-exist"),
12337            ConsumerOptions::default(),
12338        ));
12339        let (writer, mut rx) = mpsc::channel(1);
12340        let handle = RouteHandle::new(9, 2, 1);
12341        let route_sem = Arc::new(Semaphore::new(1));
12342        writer
12343            .try_send(WriteCommand {
12344                frame: response_frame(0, 0, 100, Vec::new()),
12345                pending: None,
12346            })
12347            .expect("the fake daemon queue should accept its filler frame");
12348        {
12349            let mut inner = shared.lock_inner();
12350            inner.writer = Some(writer);
12351            inner.daemon_ver = "0.39.0".into();
12352            inner.cache_route(
12353                RouteKey::new(
12354                    &RouteTarget::ToolProvider {
12355                        module_id: "subscriptions".to_string(),
12356                    },
12357                    &BindIdentity::new("test".to_string(), "subscription".to_string()),
12358                    None,
12359                    None,
12360                ),
12361                RouteState {
12362                    handle,
12363                    sem: Arc::clone(&route_sem),
12364                    watch_sem: None,
12365                    opted_in: false,
12366                },
12367            );
12368        }
12369
12370        let consumer = SubcConsumer { shared };
12371        let result = tokio::time::timeout(
12372            Duration::from_millis(250),
12373            consumer.subscribe_route(
12374                &handle,
12375                b"subscribe".to_vec(),
12376                SubscribeOptions {
12377                    route_open_timeout: Duration::from_millis(25),
12378                    ..SubscribeOptions::default()
12379                },
12380            ),
12381        )
12382        .await
12383        .expect("a subscription must finish at its route-open deadline");
12384        let result = match result {
12385            Ok(_) => panic!("a subscription blocked before writing must time out"),
12386            Err(err) => err,
12387        };
12388        assert!(matches!(result, CallError::NotSent(_)));
12389        assert_eq!(
12390            rx.recv()
12391                .await
12392                .expect("the filler must still be the only queued frame")
12393                .frame
12394                .header
12395                .corr,
12396            100
12397        );
12398        assert!(
12399            rx.try_recv().is_err(),
12400            "the timed-out subscription must not reach the fake daemon"
12401        );
12402        assert!(
12403            route_sem.try_acquire().is_ok(),
12404            "a pre-write subscription timeout must release its route credit"
12405        );
12406    }
12407
12408    #[test]
12409    fn catalog_list_deserializes_golden_reply_and_ignores_unknown_fields() {
12410        let mut reply: serde_json::Value = serde_json::from_str(include_str!(
12411            "../../subc-control/tests/golden/client_control_response_catalog_list.json"
12412        ))
12413        .expect("the catalog.list golden reply must be valid JSON");
12414        reply["future_top_level"] = serde_json::json!(true);
12415        reply["modules"][0]["future_module_field"] = serde_json::json!("ignored");
12416
12417        let catalog: CatalogList =
12418            serde_json::from_value(reply).expect("catalog.list should tolerate additive fields");
12419        assert_eq!(catalog.generation, 7);
12420        assert_eq!(catalog.modules.len(), 1);
12421        assert!(catalog.subc_ops.iter().any(|op| op == "catalog.list"));
12422
12423        let tools = catalog.modules[0]
12424            .roles
12425            .iter()
12426            .find_map(|role| match role {
12427                subc_protocol::manifest::ProviderRole::ToolProvider { tools, .. } => Some(tools),
12428                _ => None,
12429            })
12430            .expect("the golden module must advertise a tool_provider role");
12431        let tool = tools
12432            .first()
12433            .expect("the golden tool_provider role must advertise a tool");
12434        assert!(!tool.name.is_empty());
12435        assert_eq!(
12436            tool.schema.get("type").and_then(serde_json::Value::as_str),
12437            Some("object")
12438        );
12439        assert!(matches!(
12440            tool.execution_mode,
12441            subc_protocol::manifest::ExecutionMode::Pure
12442        ));
12443    }
12444
12445    #[tokio::test]
12446    async fn catalog_list_sends_an_unfiltered_channel_zero_request() {
12447        let shared = Arc::new(reader_skew_tests::legacy_shared(
12448            PathBuf::from("/tmp/does-not-exist"),
12449            ConsumerOptions::default(),
12450        ));
12451        let (writer, mut rx) = mpsc::channel(1);
12452        shared.lock_inner().writer = Some(writer);
12453        shared.lock_inner().daemon_ver = "0.39.0".into();
12454
12455        let consumer = SubcConsumer {
12456            shared: Arc::clone(&shared),
12457        };
12458        let request = tokio::spawn(async move { consumer.catalog_list().await });
12459        let command = rx
12460            .recv()
12461            .await
12462            .expect("catalog.list must queue a channel-0 request");
12463        assert_eq!(command.frame.header.channel, 0);
12464        let body: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
12465        assert_eq!(body["op"], "catalog.list");
12466        assert!(
12467            body.get("module_id").is_none(),
12468            "catalog.list must request the complete catalog without a module filter"
12469        );
12470
12471        let response = serde_json::to_vec(&ClientControlResponse::CatalogList {
12472            generation: 9,
12473            modules: Vec::new(),
12474            subc_ops: vec!["catalog.list".to_string()],
12475        })
12476        .unwrap();
12477        assert!(
12478            dispatch_frame(
12479                &shared,
12480                1,
12481                response_frame(0, 0, command.frame.header.corr, response),
12482            )
12483            .await
12484        );
12485        let catalog = request.await.unwrap().unwrap();
12486        assert_eq!(catalog.generation, 9);
12487        assert!(catalog.modules.is_empty());
12488    }
12489
12490    #[tokio::test]
12491    async fn spawn_snapshot_sends_a_channel_zero_request_and_returns_the_snapshot() {
12492        let shared = Arc::new(reader_skew_tests::legacy_shared(
12493            PathBuf::from("/tmp/does-not-exist"),
12494            ConsumerOptions::default(),
12495        ));
12496        let (writer, mut rx) = mpsc::channel(1);
12497        shared.lock_inner().writer = Some(writer);
12498        shared.lock_inner().daemon_ver = "0.39.0".into();
12499
12500        let consumer = SubcConsumer {
12501            shared: Arc::clone(&shared),
12502        };
12503        let request = tokio::spawn(async move { consumer.spawn_snapshot().await });
12504        let command = rx
12505            .recv()
12506            .await
12507            .expect("supervisor.spawn_snapshot must queue a channel-0 request");
12508        assert_eq!(command.frame.header.channel, 0);
12509        let body: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
12510        assert_eq!(body["op"], "supervisor.spawn_snapshot");
12511
12512        let snapshot = SpawnSnapshot {
12513            cursor: SpawnCursor {
12514                daemon_incarnation: "incarnation-a".to_string(),
12515                seq: 41,
12516            },
12517            ring_bound: 256,
12518            live: vec![LiveSpawn {
12519                module_id: "participant".to_string(),
12520                spawn_generation: 3,
12521                pid: 4242,
12522                spawned_at_ms: 1_700_000_000_000,
12523            }],
12524        };
12525        let response = serde_json::to_vec(&ClientControlResponse::SupervisorSpawnSnapshot {
12526            snapshot: snapshot.clone(),
12527        })
12528        .unwrap();
12529        assert!(
12530            dispatch_frame(
12531                &shared,
12532                1,
12533                response_frame(0, 0, command.frame.header.corr, response),
12534            )
12535            .await
12536        );
12537        assert_eq!(request.await.unwrap().unwrap(), snapshot);
12538    }
12539
12540    #[tokio::test]
12541    async fn spawn_snapshot_refusal_keeps_the_daemon_code() {
12542        let shared = Arc::new(reader_skew_tests::legacy_shared(
12543            PathBuf::from("/tmp/does-not-exist"),
12544            ConsumerOptions::default(),
12545        ));
12546        let (writer, mut rx) = mpsc::channel(1);
12547        shared.lock_inner().writer = Some(writer);
12548        shared.lock_inner().daemon_ver = "0.39.0".into();
12549
12550        let consumer = SubcConsumer {
12551            shared: Arc::clone(&shared),
12552        };
12553        let request = tokio::spawn(async move { consumer.spawn_snapshot().await });
12554        let command = rx
12555            .recv()
12556            .await
12557            .expect("supervisor.spawn_snapshot must queue a channel-0 request");
12558        let refusal = serde_json::to_vec(&ErrorBody {
12559            code: "op_not_permitted".to_string(),
12560            message: "refused by the test".to_string(),
12561            detail: None,
12562        })
12563        .unwrap();
12564        let frame = Frame::build(
12565            FrameType::Error,
12566            Flags::new(false, Priority::Interactive, false),
12567            0,
12568            0,
12569            command.frame.header.corr,
12570            refusal,
12571        )
12572        .unwrap();
12573        assert!(dispatch_frame(&shared, 1, frame).await);
12574        let error = request.await.unwrap().unwrap_err();
12575        assert_eq!(error.code(), Some("op_not_permitted"));
12576    }
12577
12578    fn spawn_cursor(seq: u64) -> SpawnCursor {
12579        SpawnCursor {
12580            daemon_incarnation: "incarnation-a".to_string(),
12581            seq,
12582        }
12583    }
12584
12585    fn spawn_event(seq: u64, kind: SpawnEventKind, generation: u64) -> SpawnEvent {
12586        SpawnEvent {
12587            cursor: spawn_cursor(seq),
12588            kind,
12589            module_id: "participant".to_string(),
12590            spawn_generation: generation,
12591            pid: 4242,
12592            exit_code: (kind == SpawnEventKind::Exited).then_some(0),
12593            exit_signal: None,
12594        }
12595    }
12596
12597    fn channel_zero_frame(ty: FrameType, corr: u64, body: Vec<u8>) -> Frame {
12598        Frame::build(
12599            ty,
12600            Flags::new(false, Priority::Interactive, false),
12601            0,
12602            0,
12603            corr,
12604            body,
12605        )
12606        .unwrap()
12607    }
12608
12609    fn spawn_error_frame(corr: u64, code: &str, detail: serde_json::Value) -> Frame {
12610        channel_zero_frame(
12611            FrameType::Error,
12612            corr,
12613            serde_json::to_vec(&ErrorBody {
12614                code: code.to_string(),
12615                message: "sent by the test".to_string(),
12616                detail: Some(detail),
12617            })
12618            .unwrap(),
12619        )
12620    }
12621
12622    /// A consumer over the writer-test harness, subscribed from `since`, with the
12623    /// request frame it queued.
12624    async fn spawn_subscribed(
12625        since: Option<SpawnCursor>,
12626    ) -> (
12627        Arc<Shared>,
12628        mpsc::Receiver<WriteCommand>,
12629        SpawnSubscription,
12630        Frame,
12631    ) {
12632        let shared = writer_test_shared();
12633        let (writer, mut rx) = mpsc::channel(8);
12634        shared.lock_inner().writer = Some(writer);
12635        shared.lock_inner().daemon_ver = "0.39.0".into();
12636        let consumer = SubcConsumer {
12637            shared: Arc::clone(&shared),
12638        };
12639        let subscription = consumer
12640            .spawn_subscribe(since)
12641            .await
12642            .expect("supervisor.spawn_subscribe must be sent");
12643        std::mem::forget(consumer);
12644        let command = rx
12645            .recv()
12646            .await
12647            .expect("supervisor.spawn_subscribe must queue a channel-0 request");
12648        (shared, rx, subscription, command.frame)
12649    }
12650
12651    #[tokio::test]
12652    async fn spawn_subscribe_sends_its_cursor_on_channel_zero_and_yields_events_until_stream_end() {
12653        let (shared, _rx, mut subscription, request) =
12654            spawn_subscribed(Some(spawn_cursor(7))).await;
12655        assert_eq!(request.header.channel, 0);
12656        assert_eq!(request.header.ty, FrameType::Request);
12657        let body: serde_json::Value = serde_json::from_slice(&request.body).unwrap();
12658        assert_eq!(
12659            body,
12660            serde_json::json!({
12661                "op": "supervisor.spawn_subscribe",
12662                "since": {"daemon_incarnation": "incarnation-a", "seq": 7},
12663            })
12664        );
12665
12666        let corr = request.header.corr;
12667        let events = [
12668            spawn_event(8, SpawnEventKind::Exited, 3),
12669            spawn_event(9, SpawnEventKind::Spawned, 4),
12670        ];
12671        for event in &events {
12672            let body = serde_json::to_vec(event).unwrap();
12673            assert!(
12674                dispatch_frame(
12675                    &shared,
12676                    1,
12677                    channel_zero_frame(FrameType::StreamData, corr, body)
12678                )
12679                .await
12680            );
12681        }
12682        assert!(
12683            dispatch_frame(
12684                &shared,
12685                1,
12686                channel_zero_frame(FrameType::StreamEnd, corr, Vec::new())
12687            )
12688            .await
12689        );
12690        assert_eq!(subscription.next().await.unwrap(), Some(events[0].clone()));
12691        assert_eq!(subscription.next().await.unwrap(), Some(events[1].clone()));
12692        assert_eq!(subscription.next().await.unwrap(), None);
12693        assert_eq!(
12694            subscription.next().await.unwrap(),
12695            None,
12696            "a finished stream stays finished"
12697        );
12698    }
12699
12700    #[tokio::test]
12701    async fn spawn_subscribe_without_a_cursor_omits_since() {
12702        let (_shared, _rx, _subscription, request) = spawn_subscribed(None).await;
12703        let body: serde_json::Value = serde_json::from_slice(&request.body).unwrap();
12704        assert_eq!(
12705            body,
12706            serde_json::json!({"op": "supervisor.spawn_subscribe"})
12707        );
12708    }
12709
12710    #[tokio::test]
12711    async fn spawn_cursor_refusals_surface_as_coded_errors_with_their_detail() {
12712        let (shared, _rx, mut subscription, request) =
12713            spawn_subscribed(Some(spawn_cursor(7))).await;
12714        let frame = spawn_error_frame(
12715            request.header.corr,
12716            "spawn_cursor_incarnation_mismatch",
12717            serde_json::json!({"current_daemon_incarnation": "incarnation-b"}),
12718        );
12719        assert!(dispatch_frame(&shared, 1, frame).await);
12720        let error = subscription.next().await.unwrap_err();
12721        assert_eq!(error.code(), Some("spawn_cursor_incarnation_mismatch"));
12722        let SpawnStreamError::CursorIncarnationMismatch {
12723            current_daemon_incarnation,
12724            body,
12725        } = &error
12726        else {
12727            panic!("expected the incarnation refusal, got {error:?}");
12728        };
12729        assert_eq!(current_daemon_incarnation, "incarnation-b");
12730        assert_eq!(body.code, "spawn_cursor_incarnation_mismatch");
12731        assert_eq!(subscription.next().await.unwrap(), None);
12732
12733        let (shared, _rx, mut subscription, request) =
12734            spawn_subscribed(Some(spawn_cursor(1))).await;
12735        let frame = spawn_error_frame(
12736            request.header.corr,
12737            "spawn_cursor_too_old",
12738            serde_json::json!({"oldest_retained_cursor": spawn_cursor(90)}),
12739        );
12740        assert!(dispatch_frame(&shared, 1, frame).await);
12741        let error = subscription.next().await.unwrap_err();
12742        assert_eq!(error.code(), Some("spawn_cursor_too_old"));
12743        let SpawnStreamError::CursorTooOld {
12744            oldest_retained_cursor,
12745            ..
12746        } = &error
12747        else {
12748            panic!("expected the too-old refusal, got {error:?}");
12749        };
12750        assert_eq!(oldest_retained_cursor, &spawn_cursor(90));
12751    }
12752
12753    #[tokio::test]
12754    async fn a_lagged_spawn_stream_yields_its_queued_events_then_the_lag_error() {
12755        let (shared, _rx, mut subscription, request) =
12756            spawn_subscribed(Some(spawn_cursor(7))).await;
12757        let corr = request.header.corr;
12758        let queued = spawn_event(8, SpawnEventKind::Exited, 3);
12759        assert!(
12760            dispatch_frame(
12761                &shared,
12762                1,
12763                channel_zero_frame(
12764                    FrameType::StreamData,
12765                    corr,
12766                    serde_json::to_vec(&queued).unwrap()
12767                ),
12768            )
12769            .await
12770        );
12771        let frame = spawn_error_frame(
12772            corr,
12773            "spawn_subscriber_lagged",
12774            serde_json::json!({"first_undelivered_cursor": spawn_cursor(9)}),
12775        );
12776        assert!(dispatch_frame(&shared, 1, frame).await);
12777        assert_eq!(subscription.next().await.unwrap(), Some(queued));
12778        let error = subscription.next().await.unwrap_err();
12779        assert_eq!(error.code(), Some("spawn_subscriber_lagged"));
12780        let SpawnStreamError::SubscriberLagged {
12781            first_undelivered_cursor,
12782            ..
12783        } = &error
12784        else {
12785            panic!("expected the lag error, got {error:?}");
12786        };
12787        assert_eq!(first_undelivered_cursor, &spawn_cursor(9));
12788    }
12789
12790    #[tokio::test]
12791    async fn dropping_a_spawn_subscription_sends_a_channel_zero_cancel_for_its_corr() {
12792        let (_shared, mut rx, subscription, request) =
12793            spawn_subscribed(Some(spawn_cursor(7))).await;
12794        drop(subscription);
12795        let cancel = tokio::time::timeout(Duration::from_secs(1), rx.recv())
12796            .await
12797            .expect("dropping the subscription must queue a Cancel")
12798            .expect("the writer stays open");
12799        assert_eq!(cancel.frame.header.ty, FrameType::Cancel);
12800        assert_eq!(cancel.frame.header.channel, 0);
12801        assert_eq!(cancel.frame.header.corr, request.header.corr);
12802    }
12803
12804    #[tokio::test]
12805    async fn reconnect_completion_between_wait_decision_and_registration_wakes_caller() {
12806        let shared = Arc::new(reader_skew_tests::legacy_shared(
12807            PathBuf::from("/tmp/subc-client-rs-reconnect-wakeup"),
12808            ConsumerOptions::default(),
12809        ));
12810        let (sender, _receiver) = mpsc::channel(EGRESS_BUFFER);
12811        {
12812            let mut inner = shared.lock_inner();
12813            inner.reconnect = ReconnectState::Inline {
12814                generation: inner.generation,
12815            };
12816        }
12817        let completing = Arc::clone(&shared);
12818        *shared.before_wait.lock().unwrap() = Some(Box::new(move || {
12819            completing.lock_inner().writer = Some(sender);
12820            completing.lock_inner().daemon_ver = "0.39.0".into();
12821            completing.notify.notify_waiters();
12822        }));
12823
12824        let result = shared
12825            .ensure_connected_for_call(Instant::now() + Duration::from_millis(30))
12826            .await;
12827        assert!(
12828            result.is_ok(),
12829            "connected caller should not time out: {result:?}"
12830        );
12831        assert!(shared.before_wait.lock().unwrap().is_none());
12832    }
12833
12834    #[tokio::test]
12835    async fn catalog_list_deadline_is_not_sent_when_reconnection_stays_down() {
12836        let shared = Arc::new(reader_skew_tests::legacy_shared(
12837            PathBuf::from("/tmp/subc-client-rs-catalog-list-unavailable"),
12838            ConsumerOptions {
12839                call_timeout: Duration::from_millis(25),
12840                reconnect_backoff: RetryBackoff {
12841                    base: Duration::from_millis(1),
12842                    cap: Duration::from_millis(1),
12843                    max_attempts: 100,
12844                },
12845                ..ConsumerOptions::default()
12846            },
12847        ));
12848        let consumer = SubcConsumer { shared };
12849        let result = tokio::time::timeout(Duration::from_millis(250), consumer.catalog_list())
12850            .await
12851            .expect("catalog.list must finish at its configured deadline")
12852            .unwrap_err();
12853        assert!(matches!(result, CallError::NotSent(_)));
12854    }
12855
12856    fn consumer_with_malformed_connection_file(
12857    ) -> (cortexkit_test_support::ScratchDir, SubcConsumer) {
12858        let temp = cortexkit_test_support::ScratchDir::new("consumer-malformed-connection");
12859        let path = temp.path().join("connection.json");
12860        std::fs::write(&path, b"not JSON").unwrap();
12861        #[cfg(unix)]
12862        {
12863            use std::os::unix::fs::PermissionsExt;
12864            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap();
12865        }
12866        let shared = Arc::new(reader_skew_tests::legacy_shared(
12867            path,
12868            ConsumerOptions {
12869                call_timeout: Duration::from_millis(100),
12870                reconnect_backoff: RetryBackoff {
12871                    base: Duration::from_millis(20),
12872                    cap: Duration::from_millis(40),
12873                    max_attempts: 6,
12874                },
12875                ..ConsumerOptions::default()
12876            },
12877        ));
12878        (temp, SubcConsumer { shared })
12879    }
12880
12881    // A malformed file fails synchronously. Keep the clock running so an unpaced
12882    // retry loop reaches its deadline instead of hanging a paused-time runtime.
12883    #[tokio::test]
12884    async fn catalog_list_backs_off_after_malformed_connection_file_and_close_cancels_it() {
12885        let (_temp, consumer) = consumer_with_malformed_connection_file();
12886        let call = consumer.catalog_list();
12887        tokio::pin!(call);
12888        assert_pending(call.as_mut()).await;
12889        consumer.close().await;
12890        let err = call.await.unwrap_err();
12891        assert!(matches!(err, CallError::NotSent(_)));
12892        assert!(err.to_string().contains("consumer closed"));
12893    }
12894
12895    #[tokio::test]
12896    async fn spawn_snapshot_backs_off_after_malformed_connection_file_and_close_cancels_it() {
12897        let (_temp, consumer) = consumer_with_malformed_connection_file();
12898        let call = consumer.spawn_snapshot();
12899        tokio::pin!(call);
12900        assert_pending(call.as_mut()).await;
12901        consumer.close().await;
12902        let err = call.await.unwrap_err();
12903        assert!(matches!(err, CallError::NotSent(_)));
12904        assert!(err.to_string().contains("consumer closed"));
12905    }
12906}
12907
12908#[cfg(test)]
12909mod launch_nonce_redaction_tests {
12910    use super::*;
12911
12912    const NONCE: &str = "nonce-f00dfeed1234abcd";
12913
12914    #[test]
12915    fn option_types_and_route_keys_never_print_the_nonce() {
12916        let identity = ConsumerIdentity {
12917            module_id: "wernicke".to_string(),
12918            launch_nonce: NONCE.to_string(),
12919        };
12920        let call = CallOptions {
12921            consumer_identity: Some(identity.clone()),
12922            ..CallOptions::default()
12923        };
12924        let key = ConsumerIdentityKey::from(&identity);
12925        for printed in [format!("{call:?}"), format!("{key:?}")] {
12926            assert!(!printed.contains(NONCE), "launch nonce printed: {printed}");
12927        }
12928    }
12929}