Skip to main content

gaze_inspection/
lib.rs

1//! Provider-neutral, bounded inspection delivery for Gaze.
2//!
3//! Sensitive bytes can be observed only through intentionally named callbacks. Calling such a
4//! callback, or delivering a payload-bearing event to an [`InspectionSink`], is trusted
5//! declassification: bytes deliberately copied by trusted sink code cannot be revoked. The
6//! metadata-only path never constructs content-derived projections.
7
8#![forbid(unsafe_code)]
9
10use gaze_types::inspection::{
11    AttestationTraceV1, DashboardCaptureDescriptorV1, DecisionTraceV1, InspectionDomainV1,
12    InspectionDropCodeV1, InspectionEmissionIdV1, InspectionEpochV1, InspectionEventMetaV1,
13    InspectionMeasurementV1, InspectionSafeFieldsV1, InspectionSequenceV1, InspectionStageDomainV1,
14    JsonShapeSummaryV1, LogicalInspectionIdV1, PiiSummaryV1, ProjectionAvailabilityV1,
15    ProjectionOmissionReasonV1, SseTimelineMetaV1,
16};
17use std::cell::Cell;
18use std::collections::VecDeque;
19use std::fmt;
20use std::marker::PhantomData;
21use std::panic::{catch_unwind, AssertUnwindSafe};
22use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
23use std::sync::{Arc, Condvar, Mutex, MutexGuard, TryLockError, Weak};
24use zeroize::Zeroize;
25
26const MAX_QUEUE_ITEMS_V1: usize = 4_096;
27const MAX_QUEUE_BYTES_V1: usize = 64 * 1024 * 1024;
28
29static NEXT_REGISTRATION_ID: AtomicU64 = AtomicU64::new(1);
30static NEXT_LOGICAL_ID: AtomicU64 = AtomicU64::new(1);
31static NEXT_EMISSION_ID: AtomicU64 = AtomicU64::new(1);
32
33struct SensitiveBytes {
34    bytes: Vec<u8>,
35    #[cfg(test)]
36    zeroize_probe: Option<Arc<AtomicBool>>,
37}
38
39impl SensitiveBytes {
40    fn new(bytes: Vec<u8>) -> Self {
41        Self {
42            bytes,
43            #[cfg(test)]
44            zeroize_probe: None,
45        }
46    }
47
48    fn len(&self) -> usize {
49        self.bytes.len()
50    }
51
52    fn with_declassified_bytes<R, F>(&self, callback: F) -> R
53    where
54        F: for<'a> FnOnce(&'a [u8]) -> R,
55    {
56        callback(&self.bytes)
57    }
58
59    #[cfg(test)]
60    fn with_zeroize_probe(bytes: Vec<u8>, probe: Arc<AtomicBool>) -> Self {
61        Self {
62            bytes,
63            zeroize_probe: Some(probe),
64        }
65    }
66}
67
68impl Drop for SensitiveBytes {
69    fn drop(&mut self) {
70        self.bytes.zeroize();
71        #[cfg(test)]
72        if let Some(probe) = &self.zeroize_probe {
73            probe.store(self.bytes.iter().all(|byte| *byte == 0), Ordering::SeqCst);
74        }
75    }
76}
77
78macro_rules! sensitive_payload {
79    ($name:ident, $description:literal) => {
80        #[doc = $description]
81        pub struct $name {
82            bytes: SensitiveBytes,
83        }
84
85        impl $name {
86            /// Captures owned bytes into a zeroizing, non-formatting domain wrapper.
87            #[must_use]
88            pub fn capture(bytes: Vec<u8>) -> Self {
89                Self {
90                    bytes: SensitiveBytes::new(bytes),
91                }
92            }
93
94            /// Intentionally declassifies the bytes to one non-consuming trusted callback.
95            ///
96            /// The higher-ranked callback lifetime prevents a borrow from escaping. Trusted code
97            /// can still deliberately copy the bytes; such a copy is outside runtime revocation.
98            pub fn with_declassified_bytes<R, F>(&self, callback: F) -> R
99            where
100                F: for<'a> FnOnce(&'a [u8]) -> R,
101            {
102                self.bytes.with_declassified_bytes(callback)
103            }
104
105            fn sensitive_len(&self) -> usize {
106                self.bytes.len()
107            }
108
109            #[cfg(test)]
110            fn capture_with_probe(bytes: Vec<u8>, probe: Arc<AtomicBool>) -> Self {
111                Self {
112                    bytes: SensitiveBytes::with_zeroize_probe(bytes, probe),
113                }
114            }
115        }
116    };
117}
118
119sensitive_payload!(
120    OwnerRawPayloadV1,
121    "Zeroizing owner-request bytes. This type has no formatting, serialization, cloning, equality, hashing, dereferencing, or implicit-conversion surface."
122);
123sensitive_payload!(
124    ProviderVisiblePayloadV1,
125    "Zeroizing pseudonymized provider-visible bytes. This type has no formatting, serialization, cloning, equality, hashing, dereferencing, or implicit-conversion surface."
126);
127sensitive_payload!(
128    OwnerRestoredPayloadV1,
129    "Zeroizing owner-restored bytes. This type has no formatting, serialization, cloning, equality, hashing, dereferencing, or implicit-conversion surface."
130);
131
132macro_rules! domain_projection {
133    ($name:ident, $payload:ident, $description:literal) => {
134        #[doc = $description]
135        pub struct $name {
136            payload: ProjectionAvailabilityV1<$payload>,
137            measurement: ProjectionAvailabilityV1<InspectionMeasurementV1>,
138            json_shape: ProjectionAvailabilityV1<JsonShapeSummaryV1>,
139            sse_timeline: ProjectionAvailabilityV1<SseTimelineMetaV1>,
140            pii_summary: ProjectionAvailabilityV1<PiiSummaryV1>,
141            decision_trace: ProjectionAvailabilityV1<DecisionTraceV1>,
142            attestation: ProjectionAvailabilityV1<AttestationTraceV1>,
143        }
144
145        impl $name {
146            /// Creates one total authorized projection. Every absent component has a reason.
147            #[allow(clippy::too_many_arguments)]
148            #[must_use]
149            pub fn new(
150                payload: ProjectionAvailabilityV1<$payload>,
151                measurement: ProjectionAvailabilityV1<InspectionMeasurementV1>,
152                json_shape: ProjectionAvailabilityV1<JsonShapeSummaryV1>,
153                sse_timeline: ProjectionAvailabilityV1<SseTimelineMetaV1>,
154                pii_summary: ProjectionAvailabilityV1<PiiSummaryV1>,
155                decision_trace: ProjectionAvailabilityV1<DecisionTraceV1>,
156                attestation: ProjectionAvailabilityV1<AttestationTraceV1>,
157            ) -> Self {
158                Self {
159                    payload,
160                    measurement,
161                    json_shape,
162                    sse_timeline,
163                    pii_summary,
164                    decision_trace,
165                    attestation,
166                }
167            }
168
169            /// Returns the typed payload availability.
170            #[must_use]
171            pub const fn payload(&self) -> &ProjectionAvailabilityV1<$payload> {
172                &self.payload
173            }
174
175            /// Returns the authorized aggregate measurement availability.
176            #[must_use]
177            pub const fn measurement(&self) -> &ProjectionAvailabilityV1<InspectionMeasurementV1> {
178                &self.measurement
179            }
180
181            /// Returns the authorized JSON-shape availability.
182            #[must_use]
183            pub const fn json_shape(&self) -> &ProjectionAvailabilityV1<JsonShapeSummaryV1> {
184                &self.json_shape
185            }
186
187            /// Returns the authorized SSE-timeline availability.
188            #[must_use]
189            pub const fn sse_timeline(&self) -> &ProjectionAvailabilityV1<SseTimelineMetaV1> {
190                &self.sse_timeline
191            }
192
193            /// Returns the authorized PII-summary availability.
194            #[must_use]
195            pub const fn pii_summary(&self) -> &ProjectionAvailabilityV1<PiiSummaryV1> {
196                &self.pii_summary
197            }
198
199            /// Returns the authorized decision-trace availability.
200            #[must_use]
201            pub const fn decision_trace(&self) -> &ProjectionAvailabilityV1<DecisionTraceV1> {
202                &self.decision_trace
203            }
204
205            /// Returns the authorized attestation availability.
206            #[must_use]
207            pub const fn attestation(&self) -> &ProjectionAvailabilityV1<AttestationTraceV1> {
208                &self.attestation
209            }
210
211            fn sensitive_len(&self) -> usize {
212                let payload = match &self.payload {
213                    ProjectionAvailabilityV1::Present(payload) => payload.sensitive_len(),
214                    ProjectionAvailabilityV1::Omitted(_) => 0,
215                };
216                payload
217                    .saturating_add(projected_slice_bytes(
218                        &self.json_shape,
219                        |value| value.nodes().len(),
220                        std::mem::size_of::<gaze_types::inspection::JsonShapeNodeV1>(),
221                    ))
222                    .saturating_add(projected_slice_bytes(
223                        &self.sse_timeline,
224                        |value| value.entries().len(),
225                        std::mem::size_of::<gaze_types::inspection::SseTimelineEntryV1>(),
226                    ))
227                    .saturating_add(projected_slice_bytes(
228                        &self.pii_summary,
229                        |value| value.entries().len(),
230                        std::mem::size_of::<gaze_types::inspection::PiiCountV1>(),
231                    ))
232                    .saturating_add(projected_slice_bytes(
233                        &self.decision_trace,
234                        |value| value.entries().len(),
235                        std::mem::size_of::<gaze_types::inspection::DecisionTraceEntryV1>(),
236                    ))
237            }
238        }
239    };
240}
241
242fn projected_slice_bytes<T, F>(
243    availability: &ProjectionAvailabilityV1<T>,
244    len: F,
245    element_size: usize,
246) -> usize
247where
248    F: FnOnce(&T) -> usize,
249{
250    match availability {
251        ProjectionAvailabilityV1::Present(value) => len(value).saturating_mul(element_size),
252        ProjectionAvailabilityV1::Omitted(_) => 0,
253    }
254}
255
256domain_projection!(
257    OwnerRawProjectionV1,
258    OwnerRawPayloadV1,
259    "Domain-authorized owner-request projection."
260);
261domain_projection!(
262    ProviderVisibleProjectionV1,
263    ProviderVisiblePayloadV1,
264    "Domain-authorized provider-visible projection."
265);
266domain_projection!(
267    OwnerRestoredProjectionV1,
268    OwnerRestoredPayloadV1,
269    "Domain-authorized owner-restored projection."
270);
271
272enum InspectionEventBodyV1 {
273    OwnerRequest(ProjectionAvailabilityV1<OwnerRawProjectionV1>),
274    ProviderRequest(ProjectionAvailabilityV1<ProviderVisibleProjectionV1>),
275    ProviderResponse(ProjectionAvailabilityV1<ProviderVisibleProjectionV1>),
276    OwnerRestoredResponse(ProjectionAvailabilityV1<OwnerRestoredProjectionV1>),
277}
278
279impl InspectionEventBodyV1 {
280    fn stage_domain(&self) -> InspectionStageDomainV1 {
281        match self {
282            Self::OwnerRequest(_) => InspectionStageDomainV1::OwnerRequest,
283            Self::ProviderRequest(_) => InspectionStageDomainV1::ProviderRequest,
284            Self::ProviderResponse(_) => InspectionStageDomainV1::ProviderResponse,
285            Self::OwnerRestoredResponse(_) => InspectionStageDomainV1::OwnerRestoredResponse,
286        }
287    }
288
289    fn sensitive_len(&self) -> usize {
290        match self {
291            Self::OwnerRequest(ProjectionAvailabilityV1::Present(value)) => value.sensitive_len(),
292            Self::ProviderRequest(ProjectionAvailabilityV1::Present(value))
293            | Self::ProviderResponse(ProjectionAvailabilityV1::Present(value)) => {
294                value.sensitive_len()
295            }
296            Self::OwnerRestoredResponse(ProjectionAvailabilityV1::Present(value)) => {
297                value.sensitive_len()
298            }
299            Self::OwnerRequest(ProjectionAvailabilityV1::Omitted(_))
300            | Self::ProviderRequest(ProjectionAvailabilityV1::Omitted(_))
301            | Self::ProviderResponse(ProjectionAvailabilityV1::Omitted(_))
302            | Self::OwnerRestoredResponse(ProjectionAvailabilityV1::Omitted(_)) => 0,
303        }
304    }
305}
306
307/// Content-free event kind for routing and hostile-sink assertions.
308#[derive(Clone, Copy, Debug, Eq, PartialEq)]
309pub enum InspectionEventKindV1 {
310    OwnerRequest,
311    ProviderRequest,
312    ProviderResponse,
313    OwnerRestoredResponse,
314    Omitted {
315        stage_domain: InspectionStageDomainV1,
316        reason: ProjectionOmissionReasonV1,
317    },
318}
319
320/// Borrowed typed event view. It never erases a payload to generic bytes/domain pairs.
321pub enum InspectionEventViewV1<'a> {
322    OwnerRequest(&'a OwnerRawProjectionV1),
323    ProviderRequest(&'a ProviderVisibleProjectionV1),
324    ProviderResponse(&'a ProviderVisibleProjectionV1),
325    OwnerRestoredResponse(&'a OwnerRestoredProjectionV1),
326    Omitted {
327        stage_domain: InspectionStageDomainV1,
328        reason: ProjectionOmissionReasonV1,
329    },
330}
331
332/// Non-serializable, non-formatting inspection event delivered to a trusted sink.
333pub struct InspectionEventV1 {
334    meta: InspectionEventMetaV1,
335    body: InspectionEventBodyV1,
336}
337
338impl InspectionEventV1 {
339    /// Returns hostile-sink-safe metadata.
340    #[must_use]
341    pub const fn meta(&self) -> &InspectionEventMetaV1 {
342        &self.meta
343    }
344
345    /// Returns a content-free event kind.
346    #[must_use]
347    pub fn kind(&self) -> InspectionEventKindV1 {
348        match &self.body {
349            InspectionEventBodyV1::OwnerRequest(ProjectionAvailabilityV1::Present(_)) => {
350                InspectionEventKindV1::OwnerRequest
351            }
352            InspectionEventBodyV1::ProviderRequest(ProjectionAvailabilityV1::Present(_)) => {
353                InspectionEventKindV1::ProviderRequest
354            }
355            InspectionEventBodyV1::ProviderResponse(ProjectionAvailabilityV1::Present(_)) => {
356                InspectionEventKindV1::ProviderResponse
357            }
358            InspectionEventBodyV1::OwnerRestoredResponse(ProjectionAvailabilityV1::Present(_)) => {
359                InspectionEventKindV1::OwnerRestoredResponse
360            }
361            InspectionEventBodyV1::OwnerRequest(ProjectionAvailabilityV1::Omitted(reason))
362            | InspectionEventBodyV1::ProviderRequest(ProjectionAvailabilityV1::Omitted(reason))
363            | InspectionEventBodyV1::ProviderResponse(ProjectionAvailabilityV1::Omitted(reason))
364            | InspectionEventBodyV1::OwnerRestoredResponse(ProjectionAvailabilityV1::Omitted(
365                reason,
366            )) => InspectionEventKindV1::Omitted {
367                stage_domain: self.body.stage_domain(),
368                reason: *reason,
369            },
370        }
371    }
372
373    /// Returns a typed projection view. Sensitive payload bytes remain behind their callback.
374    #[must_use]
375    pub fn view(&self) -> InspectionEventViewV1<'_> {
376        match &self.body {
377            InspectionEventBodyV1::OwnerRequest(ProjectionAvailabilityV1::Present(value)) => {
378                InspectionEventViewV1::OwnerRequest(value)
379            }
380            InspectionEventBodyV1::ProviderRequest(ProjectionAvailabilityV1::Present(value)) => {
381                InspectionEventViewV1::ProviderRequest(value)
382            }
383            InspectionEventBodyV1::ProviderResponse(ProjectionAvailabilityV1::Present(value)) => {
384                InspectionEventViewV1::ProviderResponse(value)
385            }
386            InspectionEventBodyV1::OwnerRestoredResponse(ProjectionAvailabilityV1::Present(
387                value,
388            )) => InspectionEventViewV1::OwnerRestoredResponse(value),
389            InspectionEventBodyV1::OwnerRequest(ProjectionAvailabilityV1::Omitted(reason))
390            | InspectionEventBodyV1::ProviderRequest(ProjectionAvailabilityV1::Omitted(reason))
391            | InspectionEventBodyV1::ProviderResponse(ProjectionAvailabilityV1::Omitted(reason))
392            | InspectionEventBodyV1::OwnerRestoredResponse(ProjectionAvailabilityV1::Omitted(
393                reason,
394            )) => InspectionEventViewV1::Omitted {
395                stage_domain: self.body.stage_domain(),
396                reason: *reason,
397            },
398        }
399    }
400}
401
402/// Closed, sanitized sink rejection.
403#[derive(Clone, Copy, Debug, Eq, PartialEq)]
404pub enum InspectionSinkErrorV1 {
405    Rejected,
406    Closed,
407    FailedClosed,
408}
409
410/// Object-safe trusted inspection delivery boundary.
411pub trait InspectionSink: Send + Sync + 'static {
412    /// Receives one fully constructed event on the dispatcher thread, never the producer path.
413    fn try_emit(&self, event: InspectionEventV1) -> Result<(), InspectionSinkErrorV1>;
414}
415
416/// Sink that deliberately drops every event without revealing payload bytes.
417#[derive(Default)]
418pub struct NoopInspectionSinkV1;
419
420impl InspectionSink for NoopInspectionSinkV1 {
421    fn try_emit(&self, _event: InspectionEventV1) -> Result<(), InspectionSinkErrorV1> {
422        Ok(())
423    }
424}
425
426/// Bounded queue configuration.
427#[derive(Clone, Copy, Debug, Eq, PartialEq)]
428pub struct InspectionQueueLimitsV1 {
429    max_items: usize,
430    max_bytes: usize,
431}
432
433impl InspectionQueueLimitsV1 {
434    /// Creates limits inside the reviewed hard ceilings.
435    pub const fn new(max_items: usize, max_bytes: usize) -> Result<Self, InspectionLimitErrorV1> {
436        if max_items == 0 || max_items > MAX_QUEUE_ITEMS_V1 {
437            return Err(InspectionLimitErrorV1::InvalidItemLimit);
438        }
439        if max_bytes == 0 || max_bytes > MAX_QUEUE_BYTES_V1 {
440            return Err(InspectionLimitErrorV1::InvalidByteLimit);
441        }
442        Ok(Self {
443            max_items,
444            max_bytes,
445        })
446    }
447}
448
449/// Closed queue-limit validation failure.
450#[derive(Clone, Copy, Debug, Eq, PartialEq)]
451pub enum InspectionLimitErrorV1 {
452    InvalidItemLimit,
453    InvalidByteLimit,
454}
455
456impl fmt::Display for InspectionLimitErrorV1 {
457    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
458        formatter.write_str(match self {
459            Self::InvalidItemLimit => "invalid_inspection_item_limit",
460            Self::InvalidByteLimit => "invalid_inspection_byte_limit",
461        })
462    }
463}
464
465impl std::error::Error for InspectionLimitErrorV1 {}
466
467/// Opaque one-shot producer half supplied before atomic installation.
468#[must_use]
469pub struct PendingInspectionProducerV1 {
470    descriptor: DashboardCaptureDescriptorV1,
471}
472
473impl PendingInspectionProducerV1 {
474    /// Creates the producer pending half for one immutable descriptor.
475    pub const fn new(descriptor: DashboardCaptureDescriptorV1) -> Self {
476        Self { descriptor }
477    }
478}
479
480/// Opaque one-shot consumer half supplied after adopter acknowledgement.
481#[must_use]
482pub struct PendingInspectionConsumerV1 {
483    descriptor: DashboardCaptureDescriptorV1,
484    sink: Arc<dyn InspectionSink>,
485    limits: InspectionQueueLimitsV1,
486    binding: Option<Arc<InspectionConsumerBindingSharedV1>>,
487}
488
489impl PendingInspectionConsumerV1 {
490    /// Seals the exact descriptor, sink, and bounded queue configuration into a pending half.
491    pub fn new(
492        descriptor: DashboardCaptureDescriptorV1,
493        sink: Arc<dyn InspectionSink>,
494        limits: InspectionQueueLimitsV1,
495    ) -> Self {
496        Self {
497            descriptor,
498            sink,
499            limits,
500            binding: None,
501        }
502    }
503
504    /// Seals a gated pending half and returns its inspection-owned one-shot binding capability.
505    pub fn new_with_binding(
506        descriptor: DashboardCaptureDescriptorV1,
507        sink: Arc<dyn InspectionSink>,
508        limits: InspectionQueueLimitsV1,
509    ) -> (Self, InspectionConsumerBindingV1) {
510        let shared = Arc::new(InspectionConsumerBindingSharedV1 {
511            state: Mutex::new(InspectionConsumerBindingStateV1::Pending),
512        });
513        (
514            Self {
515                descriptor,
516                sink,
517                limits,
518                binding: Some(Arc::clone(&shared)),
519            },
520            InspectionConsumerBindingV1 {
521                shared: Some(shared),
522            },
523        )
524    }
525}
526
527enum InspectionConsumerBindingStateV1 {
528    Pending,
529    Installed(Weak<RegistrationState>),
530    Bound,
531    Cancelled,
532}
533
534struct InspectionConsumerBindingSharedV1 {
535    state: Mutex<InspectionConsumerBindingStateV1>,
536}
537
538/// Inspection-owned, one-shot proof capability for one gated pending consumer.
539///
540/// It exposes no identity, comparison, formatting, serialization, cloning, or dereferencing
541/// surface. Dropping it cancels a pending installation or disables its exact installed
542/// registration.
543///
544/// ```compile_fail
545/// use gaze_inspection::InspectionConsumerBindingV1;
546///
547/// fn forge() -> InspectionConsumerBindingV1 {
548///     InspectionConsumerBindingV1 { shared: None }
549/// }
550/// ```
551#[must_use]
552pub struct InspectionConsumerBindingV1 {
553    shared: Option<Arc<InspectionConsumerBindingSharedV1>>,
554}
555
556/// Closed binding failure without pointer, descriptor, or source text.
557#[derive(Clone, Copy, Debug, Eq, PartialEq)]
558pub enum InspectionConsumerBindErrorV1 {
559    NotInstalled,
560    RegistrationMismatch,
561    Cancelled,
562}
563
564impl fmt::Display for InspectionConsumerBindErrorV1 {
565    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
566        formatter.write_str(match self {
567            Self::NotInstalled => "inspection_consumer_not_installed",
568            Self::RegistrationMismatch => "inspection_consumer_registration_mismatch",
569            Self::Cancelled => "inspection_consumer_binding_cancelled",
570        })
571    }
572}
573
574impl std::error::Error for InspectionConsumerBindErrorV1 {}
575
576/// Closed installation failure without source text.
577#[derive(Clone, Copy, Debug, Eq, PartialEq)]
578pub enum InspectionInstallErrorV1 {
579    DescriptorMismatch,
580    RegistrationIdentityExhausted,
581    DispatcherUnavailable,
582}
583
584impl fmt::Display for InspectionInstallErrorV1 {
585    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
586        formatter.write_str(match self {
587            Self::DescriptorMismatch => "inspection_descriptor_mismatch",
588            Self::RegistrationIdentityExhausted => "inspection_registration_identity_exhausted",
589            Self::DispatcherUnavailable => "inspection_dispatcher_unavailable",
590        })
591    }
592}
593
594impl std::error::Error for InspectionInstallErrorV1 {}
595
596struct RegistrationIdentity {
597    _nonce: u64,
598}
599
600enum LifecycleStateV1 {
601    Running(u64),
602    Purging { from: u64, to: u64 },
603    Disabled,
604}
605
606struct RuntimeInner {
607    lifecycle: LifecycleStateV1,
608    queue: VecDeque<QueuedInspectionEventV1>,
609    sink_panics: u64,
610    sink_rejections: u64,
611}
612
613struct QueueAccounting {
614    items: AtomicUsize,
615    bytes: AtomicUsize,
616}
617
618struct QueueReservation {
619    accounting: Arc<QueueAccounting>,
620    bytes: usize,
621}
622
623impl QueueReservation {
624    fn new(accounting: Arc<QueueAccounting>, bytes: usize) -> Self {
625        accounting.items.fetch_add(1, Ordering::AcqRel);
626        accounting.bytes.fetch_add(bytes, Ordering::AcqRel);
627        Self { accounting, bytes }
628    }
629}
630
631impl Drop for QueueReservation {
632    fn drop(&mut self) {
633        self.accounting.items.fetch_sub(1, Ordering::AcqRel);
634        self.accounting
635            .bytes
636            .fetch_sub(self.bytes, Ordering::AcqRel);
637    }
638}
639
640struct QueuedInspectionEventV1 {
641    epoch: u64,
642    event: InspectionEventV1,
643    reservation: QueueReservation,
644}
645
646#[cfg(test)]
647#[derive(Default)]
648struct DispatchHooks {
649    before_wait: Option<std::sync::mpsc::Sender<()>>,
650    after_dequeue: Option<Arc<std::sync::Barrier>>,
651    after_permit: Option<Arc<std::sync::Barrier>>,
652}
653
654struct RegistrationState {
655    _identity: RegistrationIdentity,
656    descriptor: DashboardCaptureDescriptorV1,
657    limits: InspectionQueueLimitsV1,
658    inner: Mutex<RuntimeInner>,
659    changed: Condvar,
660    accounting: Arc<QueueAccounting>,
661    producer_open: AtomicBool,
662    #[cfg(test)]
663    hooks: Mutex<DispatchHooks>,
664}
665
666impl RegistrationState {
667    fn try_inner(&self) -> Result<MutexGuard<'_, RuntimeInner>, InspectionDropCodeV1> {
668        match self.inner.try_lock() {
669            Ok(inner) => Ok(inner),
670            Err(TryLockError::WouldBlock) => Err(InspectionDropCodeV1::QueueContended),
671            Err(TryLockError::Poisoned(poisoned)) => {
672                let mut inner = poisoned.into_inner();
673                terminate(&mut inner, &self.changed);
674                Err(InspectionDropCodeV1::Disabled)
675            }
676        }
677    }
678
679    fn disable(&self) -> InspectionDisableOutcomeV1 {
680        let mut inner = lock_without_recovery(&self.inner);
681        if matches!(inner.lifecycle, LifecycleStateV1::Disabled) {
682            return InspectionDisableOutcomeV1::AlreadyDisabled;
683        }
684        terminate(&mut inner, &self.changed);
685        InspectionDisableOutcomeV1::Disabled
686    }
687}
688
689fn terminate(inner: &mut RuntimeInner, changed: &Condvar) {
690    inner.lifecycle = LifecycleStateV1::Disabled;
691    inner.queue.clear();
692    changed.notify_all();
693}
694
695fn lock_without_recovery<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
696    mutex
697        .lock()
698        .unwrap_or_else(std::sync::PoisonError::into_inner)
699}
700
701fn next_bounded_id(counter: &AtomicU64) -> Option<u64> {
702    counter
703        .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
704            current.checked_add(1)
705        })
706        .ok()
707}
708
709fn associate_consumer_binding(
710    binding: &InspectionConsumerBindingSharedV1,
711    registration: &Arc<RegistrationState>,
712) -> Result<(), Option<Arc<RegistrationState>>> {
713    let mut state = lock_without_recovery(&binding.state);
714    if matches!(*state, InspectionConsumerBindingStateV1::Pending) {
715        *state = InspectionConsumerBindingStateV1::Installed(Arc::downgrade(registration));
716        return Ok(());
717    }
718    let prior = std::mem::replace(&mut *state, InspectionConsumerBindingStateV1::Cancelled);
719    drop(state);
720    let prior_registration = match prior {
721        InspectionConsumerBindingStateV1::Installed(expected) => expected.upgrade(),
722        InspectionConsumerBindingStateV1::Pending
723        | InspectionConsumerBindingStateV1::Bound
724        | InspectionConsumerBindingStateV1::Cancelled => None,
725    };
726    Err(prior_registration)
727}
728
729fn cancel_consumer_binding(
730    binding: &InspectionConsumerBindingSharedV1,
731) -> Option<Arc<RegistrationState>> {
732    let mut state = lock_without_recovery(&binding.state);
733    let prior = std::mem::replace(&mut *state, InspectionConsumerBindingStateV1::Cancelled);
734    let registration = match prior {
735        InspectionConsumerBindingStateV1::Installed(expected) => expected.upgrade(),
736        InspectionConsumerBindingStateV1::Bound => {
737            *state = InspectionConsumerBindingStateV1::Bound;
738            None
739        }
740        InspectionConsumerBindingStateV1::Pending | InspectionConsumerBindingStateV1::Cancelled => {
741            None
742        }
743    };
744    drop(state);
745    registration
746}
747
748#[cfg(test)]
749thread_local! {
750    static FORCE_DISPATCHER_SPAWN_FAILURE: Cell<bool> = const { Cell::new(false) };
751}
752
753fn spawn_dispatcher(
754    state: Arc<RegistrationState>,
755    sink: Arc<dyn InspectionSink>,
756) -> Result<(), InspectionInstallErrorV1> {
757    #[cfg(test)]
758    if FORCE_DISPATCHER_SPAWN_FAILURE.with(|forced| forced.replace(false)) {
759        return Err(InspectionInstallErrorV1::DispatcherUnavailable);
760    }
761    std::thread::Builder::new()
762        .name("gaze-inspection".to_owned())
763        .spawn(move || dispatcher_loop(state, sink))
764        .map(|_| ())
765        .map_err(|_| InspectionInstallErrorV1::DispatcherUnavailable)
766}
767
768/// Sole consuming atomic installation operation for the matched pending halves.
769pub fn install_inspection_v1(
770    producer: PendingInspectionProducerV1,
771    consumer: PendingInspectionConsumerV1,
772) -> Result<(InstalledInspectionProducerV1, ActivatedInspectionConsumerV1), InspectionInstallErrorV1>
773{
774    if producer.descriptor != consumer.descriptor {
775        return Err(InspectionInstallErrorV1::DescriptorMismatch);
776    }
777    let PendingInspectionConsumerV1 {
778        descriptor: _,
779        sink,
780        limits,
781        binding,
782    } = consumer;
783    let registration_id = next_bounded_id(&NEXT_REGISTRATION_ID)
784        .ok_or(InspectionInstallErrorV1::RegistrationIdentityExhausted)?;
785    let state = Arc::new(RegistrationState {
786        _identity: RegistrationIdentity {
787            _nonce: registration_id,
788        },
789        descriptor: producer.descriptor,
790        limits,
791        inner: Mutex::new(RuntimeInner {
792            lifecycle: LifecycleStateV1::Running(0),
793            queue: VecDeque::new(),
794            sink_panics: 0,
795            sink_rejections: 0,
796        }),
797        changed: Condvar::new(),
798        accounting: Arc::new(QueueAccounting {
799            items: AtomicUsize::new(0),
800            bytes: AtomicUsize::new(0),
801        }),
802        producer_open: AtomicBool::new(true),
803        #[cfg(test)]
804        hooks: Mutex::new(DispatchHooks::default()),
805    });
806    if let Some(binding) = &binding {
807        if let Err(prior_registration) = associate_consumer_binding(binding, &state) {
808            if let Some(prior_registration) = prior_registration {
809                prior_registration.disable();
810            }
811            state.disable();
812            return Err(InspectionInstallErrorV1::DispatcherUnavailable);
813        }
814    }
815    if let Err(error) = spawn_dispatcher(state.clone(), sink) {
816        if let Some(binding) = &binding {
817            if let Some(registration) = cancel_consumer_binding(binding) {
818                registration.disable();
819            }
820        }
821        state.disable();
822        return Err(error);
823    }
824    Ok((
825        InstalledInspectionProducerV1 {
826            state: state.clone(),
827        },
828        ActivatedInspectionConsumerV1 {
829            state,
830            _single_owner: PhantomData,
831        },
832    ))
833}
834
835fn dispatcher_loop(state: Arc<RegistrationState>, sink: Arc<dyn InspectionSink>) {
836    loop {
837        let queued = {
838            let mut inner = lock_without_recovery(&state.inner);
839            while inner.queue.is_empty() && !matches!(inner.lifecycle, LifecycleStateV1::Disabled) {
840                #[cfg(test)]
841                if let Some(ready) = lock_without_recovery(&state.hooks).before_wait.take() {
842                    let _ = ready.send(());
843                }
844                inner = state
845                    .changed
846                    .wait(inner)
847                    .unwrap_or_else(std::sync::PoisonError::into_inner);
848            }
849            match inner.queue.pop_front() {
850                Some(queued) => queued,
851                None => return,
852            }
853        };
854
855        #[cfg(test)]
856        run_dispatch_hook(&state.hooks, |hooks| hooks.after_dequeue.clone());
857
858        let permit = {
859            let inner = lock_without_recovery(&state.inner);
860            matches!(
861                inner.lifecycle,
862                LifecycleStateV1::Running(epoch) if epoch == queued.epoch
863            )
864        };
865        if !permit {
866            drop(queued);
867            continue;
868        }
869
870        #[cfg(test)]
871        run_dispatch_hook(&state.hooks, |hooks| hooks.after_permit.clone());
872
873        let QueuedInspectionEventV1 {
874            event, reservation, ..
875        } = queued;
876        let delivered = catch_unwind(AssertUnwindSafe(|| sink.try_emit(event)));
877        drop(reservation);
878        let mut inner = lock_without_recovery(&state.inner);
879        match delivered {
880            Ok(Ok(())) => {}
881            Ok(Err(_)) => inner.sink_rejections = inner.sink_rejections.saturating_add(1),
882            Err(_) => inner.sink_panics = inner.sink_panics.saturating_add(1),
883        }
884    }
885}
886
887#[cfg(test)]
888fn run_dispatch_hook<F>(hooks: &Mutex<DispatchHooks>, select: F)
889where
890    F: FnOnce(&DispatchHooks) -> Option<Arc<std::sync::Barrier>>,
891{
892    let barrier = select(&lock_without_recovery(hooks));
893    if let Some(barrier) = barrier {
894        barrier.wait();
895        barrier.wait();
896    }
897}
898
899/// Matched installed producer capability. It exposes no sink, epoch, control, or identity.
900#[must_use]
901pub struct InstalledInspectionProducerV1 {
902    state: Arc<RegistrationState>,
903}
904
905impl InstalledInspectionProducerV1 {
906    /// Mints one registration-bound logical emitter with a fresh content-independent ID.
907    pub fn begin_logical(
908        &self,
909    ) -> Result<InspectionLogicalEmitterV1, InspectionBeginLogicalErrorV1> {
910        if !self.state.producer_open.load(Ordering::Acquire) {
911            return Err(InspectionBeginLogicalErrorV1::Closed);
912        }
913        let inner = self.state.try_inner().map_err(|drop| match drop {
914            InspectionDropCodeV1::QueueContended => InspectionBeginLogicalErrorV1::Contended,
915            _ => InspectionBeginLogicalErrorV1::Disabled,
916        })?;
917        self.logical_from_inner(inner)
918    }
919
920    /// Mints a logical emitter after acquiring the registration lock.
921    ///
922    /// Use on a control thread after a purge acknowledgement, never on the nonblocking
923    /// capture path. Purging, disabled, and closed registrations still return an error.
924    pub fn begin_logical_blocking(
925        &self,
926    ) -> Result<InspectionLogicalEmitterV1, InspectionBeginLogicalErrorV1> {
927        if !self.state.producer_open.load(Ordering::Acquire) {
928            return Err(InspectionBeginLogicalErrorV1::Closed);
929        }
930        let inner = self.state.inner.lock().map_err(|poisoned| {
931            let mut inner = poisoned.into_inner();
932            terminate(&mut inner, &self.state.changed);
933            InspectionBeginLogicalErrorV1::Disabled
934        })?;
935        self.logical_from_inner(inner)
936    }
937
938    fn logical_from_inner(
939        &self,
940        inner: MutexGuard<'_, RuntimeInner>,
941    ) -> Result<InspectionLogicalEmitterV1, InspectionBeginLogicalErrorV1> {
942        match inner.lifecycle {
943            LifecycleStateV1::Running(_) => {}
944            LifecycleStateV1::Purging { .. } => return Err(InspectionBeginLogicalErrorV1::Purging),
945            LifecycleStateV1::Disabled => return Err(InspectionBeginLogicalErrorV1::Disabled),
946        }
947        drop(inner);
948        let logical_id = next_bounded_id(&NEXT_LOGICAL_ID)
949            .map(LogicalInspectionIdV1::new)
950            .ok_or(InspectionBeginLogicalErrorV1::IdOverflow)?;
951        Ok(InspectionLogicalEmitterV1 {
952            state: self.state.clone(),
953            logical_id,
954            sequence: InspectionSequenceV1::new(0),
955            exhausted: false,
956        })
957    }
958}
959
960impl Drop for InstalledInspectionProducerV1 {
961    fn drop(&mut self) {
962        self.state.producer_open.store(false, Ordering::Release);
963        self.state.changed.notify_all();
964    }
965}
966
967/// Closed logical-emitter creation failure.
968#[derive(Clone, Copy, Debug, Eq, PartialEq)]
969pub enum InspectionBeginLogicalErrorV1 {
970    Contended,
971    Purging,
972    Disabled,
973    Closed,
974    IdOverflow,
975}
976
977/// Closed bounded admission result.
978#[derive(Clone, Copy, Debug, Eq, PartialEq)]
979pub enum InspectionAdmissionOutcomeV1 {
980    Accepted {
981        emission_id: InspectionEmissionIdV1,
982        sequence: InspectionSequenceV1,
983    },
984    Dropped(InspectionDropCodeV1),
985}
986
987/// Registration-bound per-logical producer cursor.
988#[must_use]
989pub struct InspectionLogicalEmitterV1 {
990    state: Arc<RegistrationState>,
991    logical_id: LogicalInspectionIdV1,
992    sequence: InspectionSequenceV1,
993    exhausted: bool,
994}
995
996impl InspectionLogicalEmitterV1 {
997    /// Emits OwnerRaw only when the immutable startup descriptor authorizes it.
998    pub fn try_emit_owner_request<F>(
999        &mut self,
1000        safe: InspectionSafeFieldsV1,
1001        build: F,
1002    ) -> InspectionAdmissionOutcomeV1
1003    where
1004        F: FnOnce() -> ProjectionAvailabilityV1<OwnerRawProjectionV1>,
1005    {
1006        self.try_emit(
1007            InspectionStageDomainV1::OwnerRequest,
1008            safe,
1009            build,
1010            InspectionEventBodyV1::OwnerRequest,
1011        )
1012    }
1013
1014    /// Emits ProviderVisible request only when the immutable descriptor authorizes it.
1015    pub fn try_emit_provider_request<F>(
1016        &mut self,
1017        safe: InspectionSafeFieldsV1,
1018        build: F,
1019    ) -> InspectionAdmissionOutcomeV1
1020    where
1021        F: FnOnce() -> ProjectionAvailabilityV1<ProviderVisibleProjectionV1>,
1022    {
1023        self.try_emit(
1024            InspectionStageDomainV1::ProviderRequest,
1025            safe,
1026            build,
1027            InspectionEventBodyV1::ProviderRequest,
1028        )
1029    }
1030
1031    /// Emits ProviderVisible response only when the immutable descriptor authorizes it.
1032    pub fn try_emit_provider_response<F>(
1033        &mut self,
1034        safe: InspectionSafeFieldsV1,
1035        build: F,
1036    ) -> InspectionAdmissionOutcomeV1
1037    where
1038        F: FnOnce() -> ProjectionAvailabilityV1<ProviderVisibleProjectionV1>,
1039    {
1040        self.try_emit(
1041            InspectionStageDomainV1::ProviderResponse,
1042            safe,
1043            build,
1044            InspectionEventBodyV1::ProviderResponse,
1045        )
1046    }
1047
1048    /// Emits OwnerRestored only when the immutable startup descriptor authorizes it.
1049    pub fn try_emit_owner_restored_response<F>(
1050        &mut self,
1051        safe: InspectionSafeFieldsV1,
1052        build: F,
1053    ) -> InspectionAdmissionOutcomeV1
1054    where
1055        F: FnOnce() -> ProjectionAvailabilityV1<OwnerRestoredProjectionV1>,
1056    {
1057        self.try_emit(
1058            InspectionStageDomainV1::OwnerRestoredResponse,
1059            safe,
1060            build,
1061            InspectionEventBodyV1::OwnerRestoredResponse,
1062        )
1063    }
1064
1065    fn try_emit<T, F, W>(
1066        &mut self,
1067        stage_domain: InspectionStageDomainV1,
1068        safe: InspectionSafeFieldsV1,
1069        build: F,
1070        wrap: W,
1071    ) -> InspectionAdmissionOutcomeV1
1072    where
1073        F: FnOnce() -> ProjectionAvailabilityV1<T>,
1074        W: FnOnce(ProjectionAvailabilityV1<T>) -> InspectionEventBodyV1,
1075    {
1076        if self.exhausted {
1077            return InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::SequenceOverflow);
1078        }
1079        let next_sequence = match self.sequence.checked_next() {
1080            Ok(sequence) => sequence,
1081            Err(_) => {
1082                self.exhausted = true;
1083                return InspectionAdmissionOutcomeV1::Dropped(
1084                    InspectionDropCodeV1::SequenceOverflow,
1085                );
1086            }
1087        };
1088        let (epoch, selected) = match self.pre_projection(stage_domain.domain()) {
1089            Ok(result) => result,
1090            Err(drop) => return InspectionAdmissionOutcomeV1::Dropped(drop),
1091        };
1092        let projection = if selected {
1093            match catch_unwind(AssertUnwindSafe(build)) {
1094                Ok(projection) => projection,
1095                Err(_) => {
1096                    return InspectionAdmissionOutcomeV1::Dropped(
1097                        InspectionDropCodeV1::PartialEvent,
1098                    )
1099                }
1100            }
1101        } else {
1102            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotCapturedByPolicy)
1103        };
1104        self.final_admission(epoch, next_sequence, safe, wrap(projection))
1105    }
1106
1107    fn pre_projection(
1108        &self,
1109        domain: InspectionDomainV1,
1110    ) -> Result<(u64, bool), InspectionDropCodeV1> {
1111        if !self.state.producer_open.load(Ordering::Acquire) {
1112            return Err(InspectionDropCodeV1::QueueClosed);
1113        }
1114        let inner = self.state.try_inner()?;
1115        match inner.lifecycle {
1116            LifecycleStateV1::Running(epoch) => Ok((epoch, self.state.descriptor.captures(domain))),
1117            LifecycleStateV1::Purging { .. } => Err(InspectionDropCodeV1::Purging),
1118            LifecycleStateV1::Disabled => Err(InspectionDropCodeV1::Disabled),
1119        }
1120    }
1121
1122    fn final_admission(
1123        &mut self,
1124        expected_epoch: u64,
1125        sequence: InspectionSequenceV1,
1126        safe: InspectionSafeFieldsV1,
1127        body: InspectionEventBodyV1,
1128    ) -> InspectionAdmissionOutcomeV1 {
1129        let sensitive_len = body.sensitive_len();
1130        if sensitive_len > self.state.limits.max_bytes {
1131            return InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueByteLimit);
1132        }
1133        if !self.state.producer_open.load(Ordering::Acquire) {
1134            return InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueClosed);
1135        }
1136        let mut inner = match self.state.try_inner() {
1137            Ok(inner) => inner,
1138            Err(drop) => return InspectionAdmissionOutcomeV1::Dropped(drop),
1139        };
1140        match inner.lifecycle {
1141            LifecycleStateV1::Running(epoch) if epoch == expected_epoch => {}
1142            LifecycleStateV1::Running(_) => {
1143                return InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::StaleEpoch)
1144            }
1145            LifecycleStateV1::Purging { .. } => {
1146                return InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::Purging)
1147            }
1148            LifecycleStateV1::Disabled => {
1149                return InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::Disabled)
1150            }
1151        }
1152        let current_items = self.state.accounting.items.load(Ordering::Acquire);
1153        let current_bytes = self.state.accounting.bytes.load(Ordering::Acquire);
1154        if current_items >= self.state.limits.max_items {
1155            return InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueFull);
1156        }
1157        if current_bytes
1158            .checked_add(sensitive_len)
1159            .is_none_or(|sum| sum > self.state.limits.max_bytes)
1160        {
1161            return InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueByteLimit);
1162        }
1163        let emission_id = match next_bounded_id(&NEXT_EMISSION_ID) {
1164            Some(id) => InspectionEmissionIdV1::new(id),
1165            None => {
1166                self.exhausted = true;
1167                return InspectionAdmissionOutcomeV1::Dropped(
1168                    InspectionDropCodeV1::SequenceOverflow,
1169                );
1170            }
1171        };
1172        let meta = InspectionEventMetaV1::new(
1173            self.logical_id,
1174            emission_id,
1175            sequence,
1176            InspectionEpochV1::new(expected_epoch),
1177            body.stage_domain(),
1178            safe,
1179        );
1180        let event = InspectionEventV1 { meta, body };
1181        let reservation = QueueReservation::new(self.state.accounting.clone(), sensitive_len);
1182        inner.queue.push_back(QueuedInspectionEventV1 {
1183            epoch: expected_epoch,
1184            event,
1185            reservation,
1186        });
1187        self.sequence = sequence;
1188        drop(inner);
1189        self.state.changed.notify_one();
1190        InspectionAdmissionOutcomeV1::Accepted {
1191            emission_id,
1192            sequence,
1193        }
1194    }
1195}
1196
1197/// Sole post-install registration-bound consumer authority.
1198#[must_use]
1199pub struct ActivatedInspectionConsumerV1 {
1200    state: Arc<RegistrationState>,
1201    _single_owner: PhantomData<Cell<()>>,
1202}
1203
1204impl ActivatedInspectionConsumerV1 {
1205    /// Begins a reusable purge and returns its self-bound completion guard.
1206    pub fn begin_purge(&mut self) -> Result<InspectionPurgeGuardV1, InspectionPurgeErrorV1> {
1207        let mut inner = lock_without_recovery(&self.state.inner);
1208        let (from, to) = match inner.lifecycle {
1209            LifecycleStateV1::Running(from) => match from.checked_add(1) {
1210                Some(to) => (from, to),
1211                None => {
1212                    terminate(&mut inner, &self.state.changed);
1213                    return Err(InspectionPurgeErrorV1::EpochOverflow);
1214                }
1215            },
1216            LifecycleStateV1::Purging { .. } => return Err(InspectionPurgeErrorV1::AlreadyPurging),
1217            LifecycleStateV1::Disabled => return Err(InspectionPurgeErrorV1::Disabled),
1218        };
1219        inner.lifecycle = LifecycleStateV1::Purging { from, to };
1220        inner.queue.clear();
1221        drop(inner);
1222        self.state.changed.notify_all();
1223        Ok(InspectionPurgeGuardV1 {
1224            state: self.state.clone(),
1225            from,
1226            to,
1227            completed: false,
1228        })
1229    }
1230
1231    /// Performs the idempotent one-way disable transition and drains queued events.
1232    pub fn disable(&mut self) -> InspectionDisableOutcomeV1 {
1233        self.state.disable()
1234    }
1235}
1236
1237impl Drop for ActivatedInspectionConsumerV1 {
1238    fn drop(&mut self) {
1239        self.state.disable();
1240    }
1241}
1242
1243enum InspectionConsumerBindOutcomeV1 {
1244    Bound,
1245    Rejected {
1246        error: InspectionConsumerBindErrorV1,
1247        expected: Option<Arc<RegistrationState>>,
1248    },
1249}
1250
1251impl InspectionConsumerBindingV1 {
1252    /// Consumes this capability and one raw candidate, returning a proof-carrying bound authority
1253    /// only when both originate from the exact same private registration allocation.
1254    pub fn bind(
1255        mut self,
1256        mut activated: ActivatedInspectionConsumerV1,
1257    ) -> Result<BoundActivatedInspectionConsumerV1, InspectionConsumerBindErrorV1> {
1258        let shared = self
1259            .shared
1260            .take()
1261            .expect("inspection binding capability is consumed exactly once");
1262        let outcome = {
1263            let mut state = lock_without_recovery(&shared.state);
1264            let prior = std::mem::replace(&mut *state, InspectionConsumerBindingStateV1::Cancelled);
1265            match prior {
1266                InspectionConsumerBindingStateV1::Installed(expected) => match expected.upgrade() {
1267                    Some(expected) if Arc::ptr_eq(&expected, &activated.state) => {
1268                        *state = InspectionConsumerBindingStateV1::Bound;
1269                        InspectionConsumerBindOutcomeV1::Bound
1270                    }
1271                    Some(expected) => InspectionConsumerBindOutcomeV1::Rejected {
1272                        error: InspectionConsumerBindErrorV1::RegistrationMismatch,
1273                        expected: Some(expected),
1274                    },
1275                    None => InspectionConsumerBindOutcomeV1::Rejected {
1276                        error: InspectionConsumerBindErrorV1::Cancelled,
1277                        expected: None,
1278                    },
1279                },
1280                InspectionConsumerBindingStateV1::Pending => {
1281                    InspectionConsumerBindOutcomeV1::Rejected {
1282                        error: InspectionConsumerBindErrorV1::NotInstalled,
1283                        expected: None,
1284                    }
1285                }
1286                InspectionConsumerBindingStateV1::Bound
1287                | InspectionConsumerBindingStateV1::Cancelled => {
1288                    InspectionConsumerBindOutcomeV1::Rejected {
1289                        error: InspectionConsumerBindErrorV1::Cancelled,
1290                        expected: None,
1291                    }
1292                }
1293            }
1294        };
1295        match outcome {
1296            InspectionConsumerBindOutcomeV1::Bound => {
1297                Ok(BoundActivatedInspectionConsumerV1 { activated })
1298            }
1299            InspectionConsumerBindOutcomeV1::Rejected { error, expected } => {
1300                if let Some(expected) = expected {
1301                    expected.disable();
1302                }
1303                let _ = activated.disable();
1304                Err(error)
1305            }
1306        }
1307    }
1308}
1309
1310impl Drop for InspectionConsumerBindingV1 {
1311    fn drop(&mut self) {
1312        let Some(shared) = self.shared.take() else {
1313            return;
1314        };
1315        if let Some(registration) = cancel_consumer_binding(&shared) {
1316            registration.disable();
1317        }
1318    }
1319}
1320
1321/// Proof-carrying activated consumer authority bound to its exact gated pending consumer.
1322///
1323/// The wrapper exposes only the lifecycle operations required by a dashboard runtime. It cannot
1324/// be constructed from a raw activated handle outside this crate.
1325///
1326/// ```compile_fail
1327/// use gaze_inspection::{ActivatedInspectionConsumerV1, BoundActivatedInspectionConsumerV1};
1328///
1329/// fn forge(raw: ActivatedInspectionConsumerV1) -> BoundActivatedInspectionConsumerV1 {
1330///     BoundActivatedInspectionConsumerV1 { activated: raw }
1331/// }
1332/// ```
1333#[must_use]
1334pub struct BoundActivatedInspectionConsumerV1 {
1335    activated: ActivatedInspectionConsumerV1,
1336}
1337
1338impl BoundActivatedInspectionConsumerV1 {
1339    /// Begins a reusable purge on the exact bound registration.
1340    pub fn begin_purge(&mut self) -> Result<InspectionPurgeGuardV1, InspectionPurgeErrorV1> {
1341        self.activated.begin_purge()
1342    }
1343
1344    /// Performs the idempotent one-way disable transition on the exact bound registration.
1345    pub fn disable(&mut self) -> InspectionDisableOutcomeV1 {
1346        self.activated.disable()
1347    }
1348}
1349
1350/// Registration-bound purge completion guard.
1351#[must_use]
1352pub struct InspectionPurgeGuardV1 {
1353    state: Arc<RegistrationState>,
1354    from: u64,
1355    to: u64,
1356    completed: bool,
1357}
1358
1359impl InspectionPurgeGuardV1 {
1360    /// Returns the runtime-selected next epoch; callers cannot choose it.
1361    #[must_use]
1362    pub const fn next_epoch(&self) -> InspectionEpochV1 {
1363        InspectionEpochV1::new(self.to)
1364    }
1365
1366    /// Consumes the matching guard and reopens only its own registration.
1367    pub fn complete(mut self) -> Result<InspectionEpochV1, InspectionPurgeErrorV1> {
1368        {
1369            let mut inner = lock_without_recovery(&self.state.inner);
1370            match inner.lifecycle {
1371                LifecycleStateV1::Purging { from, to } if from == self.from && to == self.to => {
1372                    inner.lifecycle = LifecycleStateV1::Running(to);
1373                }
1374                LifecycleStateV1::Disabled => return Err(InspectionPurgeErrorV1::Disabled),
1375                LifecycleStateV1::Running(_) | LifecycleStateV1::Purging { .. } => {
1376                    return Err(InspectionPurgeErrorV1::MismatchedGuard)
1377                }
1378            }
1379        }
1380        self.completed = true;
1381        self.state.changed.notify_all();
1382        Ok(InspectionEpochV1::new(self.to))
1383    }
1384}
1385
1386impl Drop for InspectionPurgeGuardV1 {
1387    fn drop(&mut self) {
1388        if self.completed {
1389            return;
1390        }
1391        let mut inner = lock_without_recovery(&self.state.inner);
1392        if matches!(
1393            inner.lifecycle,
1394            LifecycleStateV1::Purging { from, to } if from == self.from && to == self.to
1395        ) {
1396            terminate(&mut inner, &self.state.changed);
1397        }
1398    }
1399}
1400
1401/// Closed purge lifecycle failure.
1402#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1403pub enum InspectionPurgeErrorV1 {
1404    AlreadyPurging,
1405    Disabled,
1406    EpochOverflow,
1407    MismatchedGuard,
1408}
1409
1410/// Closed idempotent disable result.
1411#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1412pub enum InspectionDisableOutcomeV1 {
1413    Disabled,
1414    AlreadyDisabled,
1415}
1416
1417#[cfg(test)]
1418mod tests {
1419    use super::*;
1420    use gaze_types::inspection::*;
1421    use std::sync::atomic::{AtomicUsize, Ordering};
1422    use std::sync::{Arc, Barrier, Condvar, Mutex};
1423    use std::time::{Duration, Instant};
1424
1425    fn isolated_registration() -> Arc<RegistrationState> {
1426        Arc::new(RegistrationState {
1427            _identity: RegistrationIdentity { _nonce: 0 },
1428            descriptor: DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible),
1429            limits: InspectionQueueLimitsV1::new(4, 1024).unwrap(),
1430            inner: Mutex::new(RuntimeInner {
1431                lifecycle: LifecycleStateV1::Running(0),
1432                queue: VecDeque::new(),
1433                sink_panics: 0,
1434                sink_rejections: 0,
1435            }),
1436            changed: Condvar::new(),
1437            accounting: Arc::new(QueueAccounting {
1438                items: AtomicUsize::new(0),
1439                bytes: AtomicUsize::new(0),
1440            }),
1441            producer_open: AtomicBool::new(true),
1442            hooks: Mutex::new(DispatchHooks::default()),
1443        })
1444    }
1445
1446    struct OwnedDispatcher {
1447        state: Arc<RegistrationState>,
1448        thread: Option<std::thread::JoinHandle<()>>,
1449        done: std::sync::mpsc::Receiver<()>,
1450        release_sink: Option<Arc<BlockingSink>>,
1451    }
1452
1453    impl OwnedDispatcher {
1454        fn start(state: Arc<RegistrationState>, sink: Arc<dyn InspectionSink>) -> Self {
1455            let (done, receiver) = std::sync::mpsc::channel();
1456            let mut dispatcher = Self {
1457                state: state.clone(),
1458                thread: None,
1459                done: receiver,
1460                release_sink: None,
1461            };
1462            dispatcher.thread = Some(std::thread::spawn(move || {
1463                dispatcher_loop(state, sink);
1464                let _ = done.send(());
1465            }));
1466            dispatcher
1467        }
1468
1469        fn finish(&mut self) -> std::thread::Result<()> {
1470            if let Some(sink) = &self.release_sink {
1471                sink.release();
1472            }
1473            // Independent rescue: a missing production notification must not strand the test.
1474            {
1475                let mut inner = lock_without_recovery(&self.state.inner);
1476                inner.lifecycle = LifecycleStateV1::Disabled;
1477                inner.queue.clear();
1478                self.state.changed.notify_all();
1479            }
1480            match self.thread.take() {
1481                Some(thread) => {
1482                    let joined = thread.join();
1483                    eprintln!("owned dispatcher cleanup joined");
1484                    joined
1485                }
1486                None => Ok(()),
1487            }
1488        }
1489    }
1490
1491    impl Drop for OwnedDispatcher {
1492        fn drop(&mut self) {
1493            let _ = self.finish();
1494        }
1495    }
1496
1497    #[test]
1498    fn nonblocking_poison_disables_and_wakes_waiting_dispatcher() {
1499        let state = isolated_registration();
1500        let producer = InstalledInspectionProducerV1 {
1501            state: state.clone(),
1502        };
1503        let (ready, waiting) = std::sync::mpsc::channel();
1504        lock_without_recovery(&state.hooks).before_wait = Some(ready);
1505        let mut dispatcher =
1506            OwnedDispatcher::start(state.clone(), Arc::new(RecordingSink::default()));
1507        let observed = waiting.recv_timeout(Duration::from_secs(10)).map(|()| {
1508            // Readiness was sent under inner; acquiring it proves wait released the lock.
1509            let poisoned = catch_unwind(AssertUnwindSafe(|| {
1510                let _inner = lock_without_recovery(&state.inner);
1511                panic!("synthetic registration poison");
1512            }));
1513            let deadline = Instant::now() + Duration::from_secs(10);
1514            let begin = loop {
1515                let result = producer.begin_logical().err();
1516                if result != Some(InspectionBeginLogicalErrorV1::Contended)
1517                    || Instant::now() >= deadline
1518                {
1519                    break result;
1520                }
1521                std::thread::yield_now();
1522            };
1523            let exited = dispatcher.done.recv_timeout(Duration::from_secs(2));
1524            let inner = lock_without_recovery(&state.inner);
1525            (
1526                poisoned.is_err(),
1527                begin,
1528                exited,
1529                matches!(inner.lifecycle, LifecycleStateV1::Disabled),
1530                inner.queue.is_empty(),
1531            )
1532        });
1533        let joined = dispatcher.finish();
1534        assert!(joined.is_ok(), "dispatcher cleanup must join successfully");
1535        let (poisoned, begin, exited, disabled, empty) =
1536            observed.expect("dispatcher wait readiness");
1537        assert!(poisoned);
1538        assert_eq!(begin, Some(InspectionBeginLogicalErrorV1::Disabled));
1539        assert!(
1540            exited.is_ok(),
1541            "poison disable must wake the waiting dispatcher: {exited:?}"
1542        );
1543        assert!(disabled && empty);
1544        assert_eq!(state.disable(), InspectionDisableOutcomeV1::AlreadyDisabled);
1545    }
1546
1547    fn probed_provider_projection(probe: Arc<AtomicBool>) -> ProviderVisibleProjectionV1 {
1548        ProviderVisibleProjectionV1::new(
1549            ProjectionAvailabilityV1::Present(ProviderVisiblePayloadV1::capture_with_probe(
1550                b"<Email_1>".to_vec(),
1551                probe,
1552            )),
1553            ProjectionAvailabilityV1::Present(InspectionMeasurementV1::new(9, 1)),
1554            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::UnsupportedFormat),
1555            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
1556            ProjectionAvailabilityV1::Present(PiiSummaryV1::empty()),
1557            ProjectionAvailabilityV1::Present(DecisionTraceV1::empty()),
1558            ProjectionAvailabilityV1::Present(AttestationTraceV1::NotApplicable),
1559        )
1560    }
1561
1562    #[test]
1563    fn terminal_paths_zeroize_queued_payloads_and_preserve_in_flight_reservations() {
1564        for path in [
1565            "nonblocking poison",
1566            "blocking poison",
1567            "disable",
1568            "overflow",
1569            "guard drop",
1570        ] {
1571            let state = isolated_registration();
1572            let producer = InstalledInspectionProducerV1 {
1573                state: state.clone(),
1574            };
1575            let mut consumer = ActivatedInspectionConsumerV1 {
1576                state: state.clone(),
1577                _single_owner: PhantomData,
1578            };
1579            let mut logical = begin_logical_for_test(&producer);
1580            let in_flight_zeroized = Arc::new(AtomicBool::new(false));
1581            let queued_zeroized = Arc::new(AtomicBool::new(false));
1582            for probe in [&in_flight_zeroized, &queued_zeroized] {
1583                assert!(matches!(
1584                    logical.try_emit_provider_request(safe_fields(), || {
1585                        ProjectionAvailabilityV1::Present(probed_provider_projection(probe.clone()))
1586                    }),
1587                    InspectionAdmissionOutcomeV1::Accepted { .. }
1588                ));
1589            }
1590            let in_flight = lock_without_recovery(&state.inner)
1591                .queue
1592                .pop_front()
1593                .unwrap();
1594            match path {
1595                "nonblocking poison" | "blocking poison" => {
1596                    let poisoned = catch_unwind(AssertUnwindSafe(|| {
1597                        let _inner = lock_without_recovery(&state.inner);
1598                        panic!("synthetic registration poison");
1599                    }));
1600                    assert!(poisoned.is_err());
1601                    let error = if path == "nonblocking poison" {
1602                        producer.begin_logical().err()
1603                    } else {
1604                        producer.begin_logical_blocking().err()
1605                    };
1606                    assert_eq!(error, Some(InspectionBeginLogicalErrorV1::Disabled));
1607                }
1608                "disable" => assert_eq!(consumer.disable(), InspectionDisableOutcomeV1::Disabled),
1609                "overflow" => {
1610                    lock_without_recovery(&state.inner).lifecycle =
1611                        LifecycleStateV1::Running(u64::MAX);
1612                    assert!(matches!(
1613                        consumer.begin_purge(),
1614                        Err(InspectionPurgeErrorV1::EpochOverflow)
1615                    ));
1616                }
1617                "guard drop" => {
1618                    // Seed a queued payload to check defensive drain even in a purging fixture.
1619                    lock_without_recovery(&state.inner).lifecycle =
1620                        LifecycleStateV1::Purging { from: 0, to: 1 };
1621                    drop(InspectionPurgeGuardV1 {
1622                        state: state.clone(),
1623                        from: 0,
1624                        to: 1,
1625                        completed: false,
1626                    });
1627                }
1628                _ => unreachable!(),
1629            }
1630            assert!(
1631                matches!(
1632                    lock_without_recovery(&state.inner).lifecycle,
1633                    LifecycleStateV1::Disabled
1634                ),
1635                "{path}"
1636            );
1637            assert!(
1638                lock_without_recovery(&state.inner).queue.is_empty(),
1639                "{path}"
1640            );
1641            assert!(queued_zeroized.load(Ordering::SeqCst), "{path}");
1642            assert!(!in_flight_zeroized.load(Ordering::SeqCst), "{path}");
1643            assert_eq!(state.accounting.items.load(Ordering::Acquire), 1, "{path}");
1644            assert_eq!(state.accounting.bytes.load(Ordering::Acquire), 9, "{path}");
1645            assert_eq!(
1646                consumer.disable(),
1647                InspectionDisableOutcomeV1::AlreadyDisabled,
1648                "{path}"
1649            );
1650            assert!(state.producer_open.load(Ordering::Acquire), "{path}");
1651            drop(in_flight);
1652            assert!(in_flight_zeroized.load(Ordering::SeqCst), "{path}");
1653            assert_eq!(state.accounting.items.load(Ordering::Acquire), 0, "{path}");
1654            assert_eq!(state.accounting.bytes.load(Ordering::Acquire), 0, "{path}");
1655        }
1656    }
1657
1658    #[test]
1659    fn producer_drop_rejects_new_projection_but_drains_accepted_delivery() {
1660        struct DrainSink {
1661            blocking: Arc<BlockingSink>,
1662            delivered: std::sync::mpsc::Sender<()>,
1663        }
1664        impl InspectionSink for DrainSink {
1665            fn try_emit(&self, event: InspectionEventV1) -> Result<(), InspectionSinkErrorV1> {
1666                self.blocking.try_emit(event)?;
1667                let _ = self.delivered.send(());
1668                Ok(())
1669            }
1670        }
1671        let state = isolated_registration();
1672        let producer = InstalledInspectionProducerV1 {
1673            state: state.clone(),
1674        };
1675        let mut logical = begin_logical_for_test(&producer);
1676        let blocking = Arc::new(BlockingSink::default());
1677        let (delivered, deliveries) = std::sync::mpsc::channel();
1678        let sink = Arc::new(DrainSink {
1679            blocking: blocking.clone(),
1680            delivered,
1681        });
1682        let mut dispatcher = OwnedDispatcher::start(state.clone(), sink);
1683        dispatcher.release_sink = Some(blocking.clone());
1684        let accepted_first = logical.try_emit_provider_request_for_test(safe_fields(), || {
1685            ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
1686        });
1687        blocking.wait_until_entered();
1688        let accepted_queued = logical.try_emit_provider_request_for_test(safe_fields(), || {
1689            ProjectionAvailabilityV1::Present(provider_projection(b"<Email_2>"))
1690        });
1691        drop(producer);
1692        let calls = AtomicUsize::new(0);
1693        let rejected = logical.try_emit_provider_request(safe_fields(), || {
1694            calls.fetch_add(1, Ordering::SeqCst);
1695            ProjectionAvailabilityV1::Present(provider_projection(b"<Email_3>"))
1696        });
1697        let still_running = matches!(
1698            lock_without_recovery(&state.inner).lifecycle,
1699            LifecycleStateV1::Running(0)
1700        );
1701        blocking.release();
1702        let first_delivered = deliveries.recv_timeout(Duration::from_secs(10));
1703        let queued_delivered = deliveries.recv_timeout(Duration::from_secs(10));
1704        let joined = dispatcher.finish();
1705        assert!(joined.is_ok());
1706        assert!(matches!(
1707            accepted_first,
1708            InspectionAdmissionOutcomeV1::Accepted { .. }
1709        ));
1710        assert!(matches!(
1711            accepted_queued,
1712            InspectionAdmissionOutcomeV1::Accepted { .. }
1713        ));
1714        assert_eq!(
1715            rejected,
1716            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueClosed)
1717        );
1718        assert_eq!(calls.load(Ordering::SeqCst), 0);
1719        assert!(still_running);
1720        assert!(first_delivered.is_ok() && queued_delivered.is_ok());
1721        assert_eq!(state.accounting.items.load(Ordering::Acquire), 0);
1722        assert_eq!(state.accounting.bytes.load(Ordering::Acquire), 0);
1723    }
1724
1725    #[derive(Default)]
1726    struct RecordingSink {
1727        events: Mutex<
1728            Vec<(
1729                InspectionSequenceV1,
1730                InspectionEventKindV1,
1731                InspectionEmissionIdV1,
1732                LogicalInspectionIdV1,
1733            )>,
1734        >,
1735        changed: Condvar,
1736    }
1737
1738    impl RecordingSink {
1739        fn wait_for(&self, count: usize) {
1740            let guard = self.events.lock().unwrap();
1741            let (guard, timeout) = self
1742                .changed
1743                .wait_timeout_while(guard, Duration::from_secs(60), |events| {
1744                    events.len() < count
1745                })
1746                .unwrap();
1747            assert!(!timeout.timed_out(), "inspection delivery timed out");
1748            assert!(guard.len() >= count);
1749        }
1750    }
1751
1752    impl InspectionSink for RecordingSink {
1753        fn try_emit(&self, event: InspectionEventV1) -> Result<(), InspectionSinkErrorV1> {
1754            self.events.lock().unwrap().push((
1755                event.meta().sequence(),
1756                event.kind(),
1757                event.meta().emission_id(),
1758                event.meta().logical_id(),
1759            ));
1760            self.changed.notify_all();
1761            Ok(())
1762        }
1763    }
1764
1765    fn safe_fields() -> InspectionSafeFieldsV1 {
1766        InspectionSafeFieldsV1::new(
1767            RouteCodeV1::AnthropicMessages,
1768            ProviderProfileCodeV1::AnthropicMessagesDirect,
1769            EndpointSelectionCodeV1::FixedHttpsOrigin,
1770            PortSelectionCodeV1::NotApplicable,
1771            InspectionOperationalStatusV1::Accepted,
1772            InspectionErrorCodeV1::None,
1773            InspectionDropCodeV1::None,
1774            InspectionDeliveryCodeV1::Pending,
1775            CoarseDurationBucketV1::NotMeasured,
1776            InspectionQueueSnapshotV1::default(),
1777        )
1778    }
1779
1780    fn provider_projection(bytes: &[u8]) -> ProviderVisibleProjectionV1 {
1781        ProviderVisibleProjectionV1::new(
1782            ProjectionAvailabilityV1::Present(ProviderVisiblePayloadV1::capture(bytes.to_vec())),
1783            ProjectionAvailabilityV1::Present(InspectionMeasurementV1::new(bytes.len() as u64, 1)),
1784            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::UnsupportedFormat),
1785            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
1786            ProjectionAvailabilityV1::Present(PiiSummaryV1::empty()),
1787            ProjectionAvailabilityV1::Present(DecisionTraceV1::empty()),
1788            ProjectionAvailabilityV1::Present(AttestationTraceV1::NotApplicable),
1789        )
1790    }
1791
1792    fn owner_raw_projection(bytes: &[u8]) -> OwnerRawProjectionV1 {
1793        OwnerRawProjectionV1::new(
1794            ProjectionAvailabilityV1::Present(OwnerRawPayloadV1::capture(bytes.to_vec())),
1795            ProjectionAvailabilityV1::Present(InspectionMeasurementV1::new(bytes.len() as u64, 1)),
1796            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::UnsupportedFormat),
1797            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
1798            ProjectionAvailabilityV1::Present(PiiSummaryV1::empty()),
1799            ProjectionAvailabilityV1::Present(DecisionTraceV1::empty()),
1800            ProjectionAvailabilityV1::Present(AttestationTraceV1::NotApplicable),
1801        )
1802    }
1803
1804    fn owner_restored_projection(bytes: &[u8]) -> OwnerRestoredProjectionV1 {
1805        OwnerRestoredProjectionV1::new(
1806            ProjectionAvailabilityV1::Present(OwnerRestoredPayloadV1::capture(bytes.to_vec())),
1807            ProjectionAvailabilityV1::Present(InspectionMeasurementV1::new(bytes.len() as u64, 1)),
1808            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::UnsupportedFormat),
1809            ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
1810            ProjectionAvailabilityV1::Present(PiiSummaryV1::empty()),
1811            ProjectionAvailabilityV1::Present(DecisionTraceV1::empty()),
1812            ProjectionAvailabilityV1::Present(AttestationTraceV1::NotApplicable),
1813        )
1814    }
1815
1816    fn begin_logical_for_test(
1817        producer: &InstalledInspectionProducerV1,
1818    ) -> InspectionLogicalEmitterV1 {
1819        producer
1820            .begin_logical_blocking()
1821            .expect("logical test setup")
1822    }
1823
1824    fn expect_begin_logical_err_for_test(
1825        producer: &InstalledInspectionProducerV1,
1826        expected: InspectionBeginLogicalErrorV1,
1827    ) {
1828        assert_eq!(producer.begin_logical_blocking().err(), Some(expected));
1829    }
1830
1831    fn admit_for_test<F>(mut attempt: F) -> InspectionAdmissionOutcomeV1
1832    where
1833        F: FnMut() -> InspectionAdmissionOutcomeV1,
1834    {
1835        const DEADLINE: Duration = Duration::from_secs(60);
1836        let started = Instant::now();
1837        loop {
1838            match attempt() {
1839                InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueContended)
1840                    if started.elapsed() < DEADLINE =>
1841                {
1842                    std::thread::yield_now();
1843                }
1844                InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueContended) => {
1845                    panic!(
1846                        "inspection admission remained contended beyond the {DEADLINE:?} test deadline"
1847                    )
1848                }
1849                outcome => return outcome,
1850            }
1851        }
1852    }
1853
1854    impl InspectionLogicalEmitterV1 {
1855        fn try_emit_owner_request_for_test<F>(
1856            &mut self,
1857            safe: InspectionSafeFieldsV1,
1858            mut build: F,
1859        ) -> InspectionAdmissionOutcomeV1
1860        where
1861            F: FnMut() -> ProjectionAvailabilityV1<OwnerRawProjectionV1>,
1862        {
1863            admit_for_test(|| self.try_emit_owner_request(safe, &mut build))
1864        }
1865
1866        fn try_emit_provider_request_for_test<F>(
1867            &mut self,
1868            safe: InspectionSafeFieldsV1,
1869            mut build: F,
1870        ) -> InspectionAdmissionOutcomeV1
1871        where
1872            F: FnMut() -> ProjectionAvailabilityV1<ProviderVisibleProjectionV1>,
1873        {
1874            admit_for_test(|| self.try_emit_provider_request(safe, &mut build))
1875        }
1876
1877        fn try_emit_provider_response_for_test<F>(
1878            &mut self,
1879            safe: InspectionSafeFieldsV1,
1880            mut build: F,
1881        ) -> InspectionAdmissionOutcomeV1
1882        where
1883            F: FnMut() -> ProjectionAvailabilityV1<ProviderVisibleProjectionV1>,
1884        {
1885            admit_for_test(|| self.try_emit_provider_response(safe, &mut build))
1886        }
1887
1888        fn try_emit_owner_restored_response_for_test<F>(
1889            &mut self,
1890            safe: InspectionSafeFieldsV1,
1891            mut build: F,
1892        ) -> InspectionAdmissionOutcomeV1
1893        where
1894            F: FnMut() -> ProjectionAvailabilityV1<OwnerRestoredProjectionV1>,
1895        {
1896            admit_for_test(|| self.try_emit_owner_restored_response(safe, &mut build))
1897        }
1898    }
1899
1900    fn wait_for_accounting(state: &RegistrationState, items: usize, bytes: usize) {
1901        let deadline = Instant::now() + Duration::from_secs(60);
1902        loop {
1903            let observed = (
1904                state.accounting.items.load(Ordering::Acquire),
1905                state.accounting.bytes.load(Ordering::Acquire),
1906            );
1907            if observed == (items, bytes) {
1908                return;
1909            }
1910            assert!(
1911                Instant::now() < deadline,
1912                "queue accounting did not converge"
1913            );
1914            std::thread::sleep(Duration::from_millis(1));
1915        }
1916    }
1917
1918    #[derive(Default)]
1919    struct BlockingSink {
1920        entered: Mutex<bool>,
1921        entered_changed: Condvar,
1922        released: Mutex<bool>,
1923        released_changed: Condvar,
1924    }
1925
1926    impl BlockingSink {
1927        fn wait_until_entered(&self) {
1928            let guard = self.entered.lock().unwrap();
1929            let (guard, timeout) = self
1930                .entered_changed
1931                .wait_timeout_while(guard, Duration::from_secs(60), |entered| !*entered)
1932                .unwrap();
1933            assert!(!timeout.timed_out());
1934            assert!(*guard);
1935        }
1936
1937        fn release(&self) {
1938            *self.released.lock().unwrap() = true;
1939            self.released_changed.notify_all();
1940        }
1941    }
1942
1943    impl InspectionSink for BlockingSink {
1944        fn try_emit(&self, _event: InspectionEventV1) -> Result<(), InspectionSinkErrorV1> {
1945            *self.entered.lock().unwrap() = true;
1946            self.entered_changed.notify_all();
1947            let guard = self.released.lock().unwrap();
1948            drop(
1949                self.released_changed
1950                    .wait_while(guard, |released| !*released)
1951                    .unwrap(),
1952            );
1953            Ok(())
1954        }
1955    }
1956
1957    struct PanicSink;
1958
1959    impl InspectionSink for PanicSink {
1960        fn try_emit(&self, _event: InspectionEventV1) -> Result<(), InspectionSinkErrorV1> {
1961            panic!("synthetic inspection sink panic")
1962        }
1963    }
1964
1965    #[derive(Default)]
1966    struct ReentrantSink {
1967        emitter: Mutex<Option<InspectionLogicalEmitterV1>>,
1968        calls: Mutex<usize>,
1969        changed: Condvar,
1970    }
1971
1972    impl ReentrantSink {
1973        fn wait_for(&self, count: usize) {
1974            let guard = self.calls.lock().unwrap();
1975            let (guard, timeout) = self
1976                .changed
1977                .wait_timeout_while(guard, Duration::from_secs(60), |calls| *calls < count)
1978                .unwrap();
1979            assert!(!timeout.timed_out());
1980            assert!(*guard >= count);
1981        }
1982    }
1983
1984    impl InspectionSink for ReentrantSink {
1985        fn try_emit(&self, _event: InspectionEventV1) -> Result<(), InspectionSinkErrorV1> {
1986            let should_reenter = {
1987                let mut calls = self.calls.lock().unwrap();
1988                let should_reenter = *calls == 0;
1989                *calls += 1;
1990                self.changed.notify_all();
1991                should_reenter
1992            };
1993            if should_reenter {
1994                let outcome = self
1995                    .emitter
1996                    .lock()
1997                    .unwrap()
1998                    .as_mut()
1999                    .unwrap()
2000                    .try_emit_provider_response_for_test(safe_fields(), || {
2001                        ProjectionAvailabilityV1::Present(provider_projection(b"<Email_2>"))
2002                    });
2003                assert!(matches!(
2004                    outcome,
2005                    InspectionAdmissionOutcomeV1::Accepted { .. }
2006                ));
2007            }
2008            Ok(())
2009        }
2010    }
2011
2012    #[test]
2013    fn atomic_install_rejects_descriptor_mismatch() {
2014        let producer = PendingInspectionProducerV1::new(DashboardCaptureDescriptorV1::new(
2015            CaptureDomainsV1::ProviderVisible,
2016        ));
2017        let consumer = PendingInspectionConsumerV1::new(
2018            DashboardCaptureDescriptorV1::new(CaptureDomainsV1::MetadataOnly),
2019            Arc::new(RecordingSink::default()),
2020            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2021        );
2022        assert!(matches!(
2023            install_inspection_v1(producer, consumer),
2024            Err(InspectionInstallErrorV1::DescriptorMismatch)
2025        ));
2026    }
2027
2028    #[test]
2029    fn gated_binding_rejects_descriptor_equal_swap_and_disables_both_registrations() {
2030        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2031        let (consumer_a, binding_a) = PendingInspectionConsumerV1::new_with_binding(
2032            descriptor,
2033            Arc::new(RecordingSink::default()),
2034            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2035        );
2036        let (consumer_b, binding_b) = PendingInspectionConsumerV1::new_with_binding(
2037            descriptor,
2038            Arc::new(RecordingSink::default()),
2039            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2040        );
2041        let (producer_a, activated_a) =
2042            install_inspection_v1(PendingInspectionProducerV1::new(descriptor), consumer_a)
2043                .unwrap();
2044        let (producer_b, activated_b) =
2045            install_inspection_v1(PendingInspectionProducerV1::new(descriptor), consumer_b)
2046                .unwrap();
2047
2048        assert!(matches!(
2049            binding_a.bind(activated_b),
2050            Err(InspectionConsumerBindErrorV1::RegistrationMismatch)
2051        ));
2052        expect_begin_logical_err_for_test(&producer_a, InspectionBeginLogicalErrorV1::Disabled);
2053        expect_begin_logical_err_for_test(&producer_b, InspectionBeginLogicalErrorV1::Disabled);
2054
2055        drop(activated_a);
2056        drop(binding_b);
2057    }
2058
2059    #[test]
2060    fn gated_binding_matches_exact_registration_and_preserves_isolated_epoch_authority() {
2061        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2062        let (consumer_a, binding_a) = PendingInspectionConsumerV1::new_with_binding(
2063            descriptor,
2064            Arc::new(RecordingSink::default()),
2065            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2066        );
2067        let (consumer_b, binding_b) = PendingInspectionConsumerV1::new_with_binding(
2068            descriptor,
2069            Arc::new(RecordingSink::default()),
2070            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2071        );
2072        let (producer_a, activated_a) =
2073            install_inspection_v1(PendingInspectionProducerV1::new(descriptor), consumer_a)
2074                .unwrap();
2075        let (producer_b, activated_b) =
2076            install_inspection_v1(PendingInspectionProducerV1::new(descriptor), consumer_b)
2077                .unwrap();
2078        let mut bound_a = binding_a.bind(activated_a).unwrap();
2079
2080        let guard = bound_a.begin_purge().unwrap();
2081        assert_eq!(guard.next_epoch().get(), 1);
2082        expect_begin_logical_err_for_test(&producer_a, InspectionBeginLogicalErrorV1::Purging);
2083        let _ = begin_logical_for_test(&producer_b);
2084        assert_eq!(guard.complete().unwrap().get(), 1);
2085        let _ = begin_logical_for_test(&producer_a);
2086        assert_eq!(bound_a.disable(), InspectionDisableOutcomeV1::Disabled);
2087        expect_begin_logical_err_for_test(&producer_a, InspectionBeginLogicalErrorV1::Disabled);
2088        let _ = begin_logical_for_test(&producer_b);
2089
2090        drop(activated_b);
2091        drop(binding_b);
2092    }
2093
2094    #[test]
2095    fn dropping_binding_before_install_prevents_a_usable_registration() {
2096        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::MetadataOnly);
2097        let (consumer, binding) = PendingInspectionConsumerV1::new_with_binding(
2098            descriptor,
2099            Arc::new(RecordingSink::default()),
2100            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2101        );
2102        drop(binding);
2103
2104        assert!(matches!(
2105            install_inspection_v1(PendingInspectionProducerV1::new(descriptor), consumer),
2106            Err(InspectionInstallErrorV1::DispatcherUnavailable)
2107        ));
2108    }
2109
2110    #[test]
2111    fn dropping_binding_after_install_disables_its_exact_registration() {
2112        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::MetadataOnly);
2113        let (consumer, binding) = PendingInspectionConsumerV1::new_with_binding(
2114            descriptor,
2115            Arc::new(RecordingSink::default()),
2116            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2117        );
2118        let (producer, activated) =
2119            install_inspection_v1(PendingInspectionProducerV1::new(descriptor), consumer).unwrap();
2120        drop(binding);
2121
2122        expect_begin_logical_err_for_test(&producer, InspectionBeginLogicalErrorV1::Disabled);
2123        drop(activated);
2124    }
2125
2126    #[test]
2127    fn legacy_ungated_activated_handle_cannot_satisfy_gated_binding() {
2128        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::MetadataOnly);
2129        let (gated_consumer, binding) = PendingInspectionConsumerV1::new_with_binding(
2130            descriptor,
2131            Arc::new(RecordingSink::default()),
2132            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2133        );
2134        let (gated_producer, gated_activated) =
2135            install_inspection_v1(PendingInspectionProducerV1::new(descriptor), gated_consumer)
2136                .unwrap();
2137        let (legacy_producer, legacy_activated) = install_inspection_v1(
2138            PendingInspectionProducerV1::new(descriptor),
2139            PendingInspectionConsumerV1::new(
2140                descriptor,
2141                Arc::new(RecordingSink::default()),
2142                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2143            ),
2144        )
2145        .unwrap();
2146
2147        assert!(matches!(
2148            binding.bind(legacy_activated),
2149            Err(InspectionConsumerBindErrorV1::RegistrationMismatch)
2150        ));
2151        expect_begin_logical_err_for_test(&gated_producer, InspectionBeginLogicalErrorV1::Disabled);
2152        expect_begin_logical_err_for_test(
2153            &legacy_producer,
2154            InspectionBeginLogicalErrorV1::Disabled,
2155        );
2156        drop(gated_activated);
2157    }
2158
2159    #[test]
2160    fn dispatcher_spawn_failure_cancels_binding_without_a_usable_registration() {
2161        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::MetadataOnly);
2162        let (consumer, binding) = PendingInspectionConsumerV1::new_with_binding(
2163            descriptor,
2164            Arc::new(RecordingSink::default()),
2165            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2166        );
2167        FORCE_DISPATCHER_SPAWN_FAILURE.with(|forced| forced.set(true));
2168        assert!(matches!(
2169            install_inspection_v1(PendingInspectionProducerV1::new(descriptor), consumer),
2170            Err(InspectionInstallErrorV1::DispatcherUnavailable)
2171        ));
2172
2173        let (candidate_producer, candidate) = install_inspection_v1(
2174            PendingInspectionProducerV1::new(descriptor),
2175            PendingInspectionConsumerV1::new(
2176                descriptor,
2177                Arc::new(RecordingSink::default()),
2178                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2179            ),
2180        )
2181        .unwrap();
2182        assert!(matches!(
2183            binding.bind(candidate),
2184            Err(InspectionConsumerBindErrorV1::Cancelled)
2185        ));
2186        expect_begin_logical_err_for_test(
2187            &candidate_producer,
2188            InspectionBeginLogicalErrorV1::Disabled,
2189        );
2190    }
2191
2192    #[test]
2193    fn producer_and_consumer_capabilities_have_the_required_thread_traits() {
2194        fn require_send<T: Send>() {}
2195        fn require_send_sync<T: Send + Sync>() {}
2196        require_send_sync::<InstalledInspectionProducerV1>();
2197        require_send::<ActivatedInspectionConsumerV1>();
2198    }
2199
2200    #[test]
2201    fn metadata_only_skips_projection_before_allocation() {
2202        let sink = Arc::new(RecordingSink::default());
2203        let producer = PendingInspectionProducerV1::new(DashboardCaptureDescriptorV1::new(
2204            CaptureDomainsV1::MetadataOnly,
2205        ));
2206        let consumer = PendingInspectionConsumerV1::new(
2207            DashboardCaptureDescriptorV1::new(CaptureDomainsV1::MetadataOnly),
2208            sink.clone(),
2209            InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2210        );
2211        let (producer, _consumer) = install_inspection_v1(producer, consumer).unwrap();
2212        let mut logical = begin_logical_for_test(&producer);
2213        let projected = AtomicUsize::new(0);
2214        assert!(matches!(
2215            logical.try_emit_provider_request_for_test(safe_fields(), || {
2216                projected.fetch_add(1, Ordering::SeqCst);
2217                ProjectionAvailabilityV1::Present(provider_projection(b"alice@example.invalid"))
2218            }),
2219            InspectionAdmissionOutcomeV1::Accepted { .. }
2220        ));
2221        sink.wait_for(1);
2222        assert_eq!(projected.load(Ordering::SeqCst), 0);
2223        assert_eq!(
2224            sink.events.lock().unwrap()[0].1,
2225            InspectionEventKindV1::Omitted {
2226                stage_domain: InspectionStageDomainV1::ProviderRequest,
2227                reason: ProjectionOmissionReasonV1::NotCapturedByPolicy,
2228            }
2229        );
2230    }
2231
2232    #[test]
2233    fn every_startup_combination_selects_projection_before_callback() {
2234        for domains in CaptureDomainsV1::ALL {
2235            let descriptor = DashboardCaptureDescriptorV1::new(domains);
2236            let sink = Arc::new(RecordingSink::default());
2237            let (producer, _consumer) = install_inspection_v1(
2238                PendingInspectionProducerV1::new(descriptor),
2239                PendingInspectionConsumerV1::new(
2240                    descriptor,
2241                    sink.clone(),
2242                    InspectionQueueLimitsV1::new(8, 16 * 1024).unwrap(),
2243                ),
2244            )
2245            .unwrap();
2246            let mut logical = begin_logical_for_test(&producer);
2247            let raw_calls = AtomicUsize::new(0);
2248            let provider_calls = AtomicUsize::new(0);
2249            let restored_calls = AtomicUsize::new(0);
2250            let owner_request = logical.try_emit_owner_request_for_test(safe_fields(), || {
2251                raw_calls.fetch_add(1, Ordering::SeqCst);
2252                ProjectionAvailabilityV1::Present(owner_raw_projection(b"alice@example.invalid"))
2253            });
2254            assert!(matches!(
2255                owner_request,
2256                InspectionAdmissionOutcomeV1::Accepted { .. }
2257            ));
2258            let provider_request =
2259                logical.try_emit_provider_request_for_test(safe_fields(), || {
2260                    provider_calls.fetch_add(1, Ordering::SeqCst);
2261                    ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2262                });
2263            assert!(matches!(
2264                provider_request,
2265                InspectionAdmissionOutcomeV1::Accepted { .. }
2266            ));
2267            let owner_restored_response =
2268                logical.try_emit_owner_restored_response_for_test(safe_fields(), || {
2269                    restored_calls.fetch_add(1, Ordering::SeqCst);
2270                    ProjectionAvailabilityV1::Present(owner_restored_projection(
2271                        b"alice@example.invalid",
2272                    ))
2273                });
2274            assert!(matches!(
2275                owner_restored_response,
2276                InspectionAdmissionOutcomeV1::Accepted { .. }
2277            ));
2278            sink.wait_for(3);
2279            assert_eq!(
2280                raw_calls.load(Ordering::SeqCst) > 0,
2281                domains.captures(InspectionDomainV1::OwnerRaw)
2282            );
2283            assert_eq!(
2284                provider_calls.load(Ordering::SeqCst) > 0,
2285                domains.captures(InspectionDomainV1::ProviderVisible)
2286            );
2287            assert_eq!(
2288                restored_calls.load(Ordering::SeqCst) > 0,
2289                domains.captures(InspectionDomainV1::OwnerRestored)
2290            );
2291        }
2292    }
2293
2294    #[test]
2295    fn sequences_are_strictly_monotonic_per_logical_id() {
2296        let sink = Arc::new(RecordingSink::default());
2297        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2298        let (producer, _consumer) = install_inspection_v1(
2299            PendingInspectionProducerV1::new(descriptor),
2300            PendingInspectionConsumerV1::new(
2301                descriptor,
2302                sink.clone(),
2303                InspectionQueueLimitsV1::new(8, 4096).unwrap(),
2304            ),
2305        )
2306        .unwrap();
2307        let mut logical = begin_logical_for_test(&producer);
2308        for _ in 0..3 {
2309            let outcome = logical.try_emit_provider_response_for_test(safe_fields(), || {
2310                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2311            });
2312            assert!(matches!(
2313                outcome,
2314                InspectionAdmissionOutcomeV1::Accepted { .. }
2315            ));
2316        }
2317        sink.wait_for(3);
2318        let sequences: Vec<_> = sink
2319            .events
2320            .lock()
2321            .unwrap()
2322            .iter()
2323            .map(|(sequence, ..)| sequence.get())
2324            .collect();
2325        assert_eq!(sequences, [1, 2, 3]);
2326        let events = sink.events.lock().unwrap();
2327        assert!(events.windows(2).all(|pair| pair[0].2 != pair[1].2));
2328        assert!(events.iter().all(|event| event.3 == events[0].3));
2329    }
2330
2331    #[test]
2332    fn equal_descriptor_installations_remain_isolated() {
2333        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2334        let sink_a = Arc::new(RecordingSink::default());
2335        let sink_b = Arc::new(RecordingSink::default());
2336        let (producer_a, mut consumer_a) = install_inspection_v1(
2337            PendingInspectionProducerV1::new(descriptor),
2338            PendingInspectionConsumerV1::new(
2339                descriptor,
2340                sink_a.clone(),
2341                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2342            ),
2343        )
2344        .unwrap();
2345        let (producer_b, _consumer_b) = install_inspection_v1(
2346            PendingInspectionProducerV1::new(descriptor),
2347            PendingInspectionConsumerV1::new(
2348                descriptor,
2349                sink_b.clone(),
2350                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2351            ),
2352        )
2353        .unwrap();
2354        let mut logical_a = begin_logical_for_test(&producer_a);
2355        let mut logical_b = begin_logical_for_test(&producer_b);
2356        let guard = consumer_a.begin_purge().unwrap();
2357        assert!(matches!(
2358            logical_a.try_emit_provider_request_for_test(safe_fields(), || {
2359                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2360            }),
2361            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::Purging)
2362        ));
2363        assert!(matches!(
2364            logical_b.try_emit_provider_request_for_test(safe_fields(), || {
2365                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2366            }),
2367            InspectionAdmissionOutcomeV1::Accepted { .. }
2368        ));
2369        sink_b.wait_for(1);
2370        guard.complete().unwrap();
2371        assert!(sink_a.events.lock().unwrap().is_empty());
2372    }
2373
2374    #[test]
2375    fn sequence_overflow_fails_closed_before_projection() {
2376        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2377        let (producer, _consumer) = install_inspection_v1(
2378            PendingInspectionProducerV1::new(descriptor),
2379            PendingInspectionConsumerV1::new(
2380                descriptor,
2381                Arc::new(RecordingSink::default()),
2382                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2383            ),
2384        )
2385        .unwrap();
2386        let mut logical = begin_logical_for_test(&producer);
2387        logical.sequence = InspectionSequenceV1::new(u64::MAX);
2388        let calls = AtomicUsize::new(0);
2389        assert_eq!(
2390            logical.try_emit_provider_request_for_test(safe_fields(), || {
2391                calls.fetch_add(1, Ordering::SeqCst);
2392                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2393            }),
2394            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::SequenceOverflow)
2395        );
2396        assert_eq!(calls.load(Ordering::SeqCst), 0);
2397    }
2398
2399    #[test]
2400    fn projection_panic_is_caught_and_later_emission_can_continue() {
2401        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2402        let sink = Arc::new(RecordingSink::default());
2403        let (producer, _consumer) = install_inspection_v1(
2404            PendingInspectionProducerV1::new(descriptor),
2405            PendingInspectionConsumerV1::new(
2406                descriptor,
2407                sink.clone(),
2408                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2409            ),
2410        )
2411        .unwrap();
2412        let mut logical = begin_logical_for_test(&producer);
2413        assert_eq!(
2414            logical.try_emit_provider_request_for_test(safe_fields(), || {
2415                panic!("synthetic projection panic")
2416            }),
2417            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::PartialEvent)
2418        );
2419        assert!(matches!(
2420            logical.try_emit_provider_request_for_test(safe_fields(), || {
2421                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2422            }),
2423            InspectionAdmissionOutcomeV1::Accepted { .. }
2424        ));
2425        sink.wait_for(1);
2426        assert_eq!(sink.events.lock().unwrap()[0].0.get(), 1);
2427    }
2428
2429    #[test]
2430    fn begin_logical_returns_contended_while_registration_lock_is_held() {
2431        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2432        let (producer, _consumer) = install_inspection_v1(
2433            PendingInspectionProducerV1::new(descriptor),
2434            PendingInspectionConsumerV1::new(
2435                descriptor,
2436                Arc::new(RecordingSink::default()),
2437                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2438            ),
2439        )
2440        .unwrap();
2441        let locked = lock_without_recovery(&producer.state.inner);
2442        assert!(matches!(
2443            producer.begin_logical(),
2444            Err(InspectionBeginLogicalErrorV1::Contended)
2445        ));
2446        drop(locked);
2447    }
2448
2449    #[test]
2450    fn blocking_logical_begin_preserves_purge_and_disable_contract() {
2451        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2452        let (producer, mut consumer) = install_inspection_v1(
2453            PendingInspectionProducerV1::new(descriptor),
2454            PendingInspectionConsumerV1::new(
2455                descriptor,
2456                Arc::new(RecordingSink::default()),
2457                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2458            ),
2459        )
2460        .unwrap();
2461        let guard = consumer.begin_purge().unwrap();
2462        assert!(matches!(
2463            producer.begin_logical_blocking(),
2464            Err(InspectionBeginLogicalErrorV1::Purging)
2465        ));
2466        guard.complete().unwrap();
2467        assert!(producer.begin_logical_blocking().is_ok());
2468        consumer.disable();
2469        assert!(matches!(
2470            producer.begin_logical_blocking(),
2471            Err(InspectionBeginLogicalErrorV1::Disabled)
2472        ));
2473        producer.state.producer_open.store(false, Ordering::Release);
2474        assert!(matches!(
2475            producer.begin_logical_blocking(),
2476            Err(InspectionBeginLogicalErrorV1::Closed)
2477        ));
2478    }
2479
2480    #[test]
2481    fn blocking_logical_begin_fails_closed_on_poison() {
2482        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2483        let (producer, _consumer) = install_inspection_v1(
2484            PendingInspectionProducerV1::new(descriptor),
2485            PendingInspectionConsumerV1::new(
2486                descriptor,
2487                Arc::new(RecordingSink::default()),
2488                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2489            ),
2490        )
2491        .unwrap();
2492        let _ = catch_unwind(AssertUnwindSafe(|| {
2493            let _inner = producer.state.inner.lock().unwrap();
2494            panic!("synthetic registration poison");
2495        }));
2496        assert!(matches!(
2497            producer.begin_logical_blocking(),
2498            Err(InspectionBeginLogicalErrorV1::Disabled)
2499        ));
2500    }
2501
2502    #[test]
2503    fn queue_contention_drops_before_projection_without_waiting() {
2504        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2505        let (producer, _consumer) = install_inspection_v1(
2506            PendingInspectionProducerV1::new(descriptor),
2507            PendingInspectionConsumerV1::new(
2508                descriptor,
2509                Arc::new(RecordingSink::default()),
2510                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2511            ),
2512        )
2513        .unwrap();
2514        let mut logical = begin_logical_for_test(&producer);
2515        let locked = lock_without_recovery(&producer.state.inner);
2516        let calls = AtomicUsize::new(0);
2517        assert_eq!(
2518            logical.try_emit_provider_request(safe_fields(), || {
2519                calls.fetch_add(1, Ordering::SeqCst);
2520                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2521            }),
2522            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueContended)
2523        );
2524        assert_eq!(calls.load(Ordering::SeqCst), 0);
2525        drop(locked);
2526    }
2527
2528    #[test]
2529    fn byte_limit_drop_zeroizes_partial_projection_and_conserves_accounting() {
2530        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2531        let (producer, _consumer) = install_inspection_v1(
2532            PendingInspectionProducerV1::new(descriptor),
2533            PendingInspectionConsumerV1::new(
2534                descriptor,
2535                Arc::new(RecordingSink::default()),
2536                InspectionQueueLimitsV1::new(4, 8).unwrap(),
2537            ),
2538        )
2539        .unwrap();
2540        let mut logical = begin_logical_for_test(&producer);
2541        let zeroized = Arc::new(AtomicBool::new(false));
2542        assert_eq!(
2543            logical.try_emit_provider_request_for_test(safe_fields(), || {
2544                ProjectionAvailabilityV1::Present(ProviderVisibleProjectionV1::new(
2545                    ProjectionAvailabilityV1::Present(
2546                        ProviderVisiblePayloadV1::capture_with_probe(
2547                            b"<Email_123>".to_vec(),
2548                            zeroized.clone(),
2549                        ),
2550                    ),
2551                    ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
2552                    ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
2553                    ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
2554                    ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
2555                    ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
2556                    ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
2557                ))
2558            }),
2559            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueByteLimit)
2560        );
2561        assert!(zeroized.load(Ordering::SeqCst));
2562        assert_eq!(producer.state.accounting.items.load(Ordering::Acquire), 0);
2563        assert_eq!(producer.state.accounting.bytes.load(Ordering::Acquire), 0);
2564    }
2565
2566    #[test]
2567    fn queue_full_and_blocked_sink_never_wait_on_producer_admission() {
2568        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2569        let sink = Arc::new(BlockingSink::default());
2570        let (producer, mut consumer) = install_inspection_v1(
2571            PendingInspectionProducerV1::new(descriptor),
2572            PendingInspectionConsumerV1::new(
2573                descriptor,
2574                sink.clone(),
2575                InspectionQueueLimitsV1::new(2, 4096).unwrap(),
2576            ),
2577        )
2578        .unwrap();
2579        let mut logical = begin_logical_for_test(&producer);
2580        assert!(matches!(
2581            logical.try_emit_provider_request_for_test(safe_fields(), || {
2582                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2583            }),
2584            InspectionAdmissionOutcomeV1::Accepted { .. }
2585        ));
2586        sink.wait_until_entered();
2587        assert!(matches!(
2588            logical.try_emit_provider_request_for_test(safe_fields(), || {
2589                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_2>"))
2590            }),
2591            InspectionAdmissionOutcomeV1::Accepted { .. }
2592        ));
2593        assert_eq!(
2594            logical.try_emit_provider_request_for_test(safe_fields(), || {
2595                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_3>"))
2596            }),
2597            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueFull)
2598        );
2599        assert_eq!(consumer.disable(), InspectionDisableOutcomeV1::Disabled);
2600        assert_eq!(
2601            consumer.disable(),
2602            InspectionDisableOutcomeV1::AlreadyDisabled
2603        );
2604        sink.release();
2605        wait_for_accounting(&producer.state, 0, 0);
2606    }
2607
2608    #[test]
2609    fn purge_drain_and_payload_drop_zeroize_and_release_one_reservation() {
2610        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2611        let sink = Arc::new(BlockingSink::default());
2612        let (producer, mut consumer) = install_inspection_v1(
2613            PendingInspectionProducerV1::new(descriptor),
2614            PendingInspectionConsumerV1::new(
2615                descriptor,
2616                sink.clone(),
2617                InspectionQueueLimitsV1::new(3, 4096).unwrap(),
2618            ),
2619        )
2620        .unwrap();
2621        let mut logical = begin_logical_for_test(&producer);
2622        assert!(matches!(
2623            logical.try_emit_provider_request_for_test(safe_fields(), || {
2624                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2625            }),
2626            InspectionAdmissionOutcomeV1::Accepted { .. }
2627        ));
2628        sink.wait_until_entered();
2629        let zeroized = Arc::new(AtomicBool::new(false));
2630        assert!(matches!(
2631            logical.try_emit_provider_request_for_test(safe_fields(), || {
2632                ProjectionAvailabilityV1::Present(ProviderVisibleProjectionV1::new(
2633                    ProjectionAvailabilityV1::Present(
2634                        ProviderVisiblePayloadV1::capture_with_probe(
2635                            b"<Email_2>".to_vec(),
2636                            zeroized.clone(),
2637                        ),
2638                    ),
2639                    ProjectionAvailabilityV1::Present(InspectionMeasurementV1::new(9, 1)),
2640                    ProjectionAvailabilityV1::Omitted(
2641                        ProjectionOmissionReasonV1::UnsupportedFormat,
2642                    ),
2643                    ProjectionAvailabilityV1::Omitted(ProjectionOmissionReasonV1::NotApplicable),
2644                    ProjectionAvailabilityV1::Present(PiiSummaryV1::empty()),
2645                    ProjectionAvailabilityV1::Present(DecisionTraceV1::empty()),
2646                    ProjectionAvailabilityV1::Present(AttestationTraceV1::NotApplicable),
2647                ))
2648            }),
2649            InspectionAdmissionOutcomeV1::Accepted { .. }
2650        ));
2651        let guard = consumer.begin_purge().unwrap();
2652        assert!(zeroized.load(Ordering::SeqCst));
2653        assert_eq!(producer.state.accounting.items.load(Ordering::Acquire), 1);
2654        sink.release();
2655        wait_for_accounting(&producer.state, 0, 0);
2656        guard.complete().unwrap();
2657    }
2658
2659    #[test]
2660    fn every_sensitive_domain_zeroizes_on_drop() {
2661        let raw = Arc::new(AtomicBool::new(false));
2662        let provider = Arc::new(AtomicBool::new(false));
2663        let restored = Arc::new(AtomicBool::new(false));
2664        drop(OwnerRawPayloadV1::capture_with_probe(
2665            b"alice@example.invalid".to_vec(),
2666            raw.clone(),
2667        ));
2668        drop(ProviderVisiblePayloadV1::capture_with_probe(
2669            b"<Email_1>".to_vec(),
2670            provider.clone(),
2671        ));
2672        drop(OwnerRestoredPayloadV1::capture_with_probe(
2673            b"alice@example.invalid".to_vec(),
2674            restored.clone(),
2675        ));
2676        assert!(raw.load(Ordering::SeqCst));
2677        assert!(provider.load(Ordering::SeqCst));
2678        assert!(restored.load(Ordering::SeqCst));
2679    }
2680
2681    #[test]
2682    fn dropped_purge_guard_disables_without_implicit_resume() {
2683        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2684        let (producer, mut consumer) = install_inspection_v1(
2685            PendingInspectionProducerV1::new(descriptor),
2686            PendingInspectionConsumerV1::new(
2687                descriptor,
2688                Arc::new(RecordingSink::default()),
2689                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2690            ),
2691        )
2692        .unwrap();
2693        let mut logical = begin_logical_for_test(&producer);
2694        drop(consumer.begin_purge().unwrap());
2695        let calls = AtomicUsize::new(0);
2696        assert_eq!(
2697            logical.try_emit_provider_request_for_test(safe_fields(), || {
2698                calls.fetch_add(1, Ordering::SeqCst);
2699                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2700            }),
2701            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::Disabled)
2702        );
2703        assert_eq!(calls.load(Ordering::SeqCst), 0);
2704        assert!(matches!(
2705            consumer.begin_purge(),
2706            Err(InspectionPurgeErrorV1::Disabled)
2707        ));
2708    }
2709
2710    #[test]
2711    fn epoch_overflow_disables_and_drains_fail_closed() {
2712        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2713        let (producer, mut consumer) = install_inspection_v1(
2714            PendingInspectionProducerV1::new(descriptor),
2715            PendingInspectionConsumerV1::new(
2716                descriptor,
2717                Arc::new(RecordingSink::default()),
2718                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2719            ),
2720        )
2721        .unwrap();
2722        lock_without_recovery(&producer.state.inner).lifecycle =
2723            LifecycleStateV1::Running(u64::MAX);
2724        assert!(matches!(
2725            consumer.begin_purge(),
2726            Err(InspectionPurgeErrorV1::EpochOverflow)
2727        ));
2728        assert_eq!(
2729            consumer.disable(),
2730            InspectionDisableOutcomeV1::AlreadyDisabled
2731        );
2732    }
2733
2734    #[test]
2735    fn dropping_installed_producer_closes_existing_logical_emitters() {
2736        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2737        let (producer, _consumer) = install_inspection_v1(
2738            PendingInspectionProducerV1::new(descriptor),
2739            PendingInspectionConsumerV1::new(
2740                descriptor,
2741                Arc::new(RecordingSink::default()),
2742                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2743            ),
2744        )
2745        .unwrap();
2746        let mut logical = begin_logical_for_test(&producer);
2747        drop(producer);
2748        let calls = AtomicUsize::new(0);
2749        assert_eq!(
2750            logical.try_emit_provider_request_for_test(safe_fields(), || {
2751                calls.fetch_add(1, Ordering::SeqCst);
2752                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2753            }),
2754            InspectionAdmissionOutcomeV1::Dropped(InspectionDropCodeV1::QueueClosed)
2755        );
2756        assert_eq!(calls.load(Ordering::SeqCst), 0);
2757    }
2758
2759    #[test]
2760    fn post_dequeue_fence_drops_when_purge_wins_before_permit() {
2761        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2762        let sink = Arc::new(RecordingSink::default());
2763        let (producer, mut consumer) = install_inspection_v1(
2764            PendingInspectionProducerV1::new(descriptor),
2765            PendingInspectionConsumerV1::new(
2766                descriptor,
2767                sink.clone(),
2768                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2769            ),
2770        )
2771        .unwrap();
2772        let barrier = Arc::new(Barrier::new(2));
2773        lock_without_recovery(&producer.state.hooks).after_dequeue = Some(barrier.clone());
2774        let mut logical = begin_logical_for_test(&producer);
2775        assert!(matches!(
2776            logical.try_emit_provider_request_for_test(safe_fields(), || {
2777                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2778            }),
2779            InspectionAdmissionOutcomeV1::Accepted { .. }
2780        ));
2781        barrier.wait();
2782        let guard = consumer.begin_purge().unwrap();
2783        barrier.wait();
2784        wait_for_accounting(&producer.state, 0, 0);
2785        assert!(sink.events.lock().unwrap().is_empty());
2786        guard.complete().unwrap();
2787    }
2788
2789    #[test]
2790    fn synchronized_permit_is_the_delivery_linearization_point() {
2791        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2792        let sink = Arc::new(RecordingSink::default());
2793        let (producer, mut consumer) = install_inspection_v1(
2794            PendingInspectionProducerV1::new(descriptor),
2795            PendingInspectionConsumerV1::new(
2796                descriptor,
2797                sink.clone(),
2798                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2799            ),
2800        )
2801        .unwrap();
2802        let barrier = Arc::new(Barrier::new(2));
2803        lock_without_recovery(&producer.state.hooks).after_permit = Some(barrier.clone());
2804        let mut logical = begin_logical_for_test(&producer);
2805        assert!(matches!(
2806            logical.try_emit_provider_request_for_test(safe_fields(), || {
2807                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2808            }),
2809            InspectionAdmissionOutcomeV1::Accepted { .. }
2810        ));
2811        barrier.wait();
2812        let guard = consumer.begin_purge().unwrap();
2813        barrier.wait();
2814        sink.wait_for(1);
2815        guard.complete().unwrap();
2816    }
2817
2818    #[test]
2819    fn sink_panic_is_contained_to_dispatcher_and_releases_accounting() {
2820        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2821        let (producer, _consumer) = install_inspection_v1(
2822            PendingInspectionProducerV1::new(descriptor),
2823            PendingInspectionConsumerV1::new(
2824                descriptor,
2825                Arc::new(PanicSink),
2826                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2827            ),
2828        )
2829        .unwrap();
2830        let mut logical = begin_logical_for_test(&producer);
2831        assert!(matches!(
2832            logical.try_emit_provider_request_for_test(safe_fields(), || {
2833                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2834            }),
2835            InspectionAdmissionOutcomeV1::Accepted { .. }
2836        ));
2837        wait_for_accounting(&producer.state, 0, 0);
2838        assert_eq!(lock_without_recovery(&producer.state.inner).sink_panics, 1);
2839    }
2840
2841    #[test]
2842    fn sink_reentry_never_runs_under_the_queue_lock() {
2843        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::ProviderVisible);
2844        let sink = Arc::new(ReentrantSink::default());
2845        let (producer, _consumer) = install_inspection_v1(
2846            PendingInspectionProducerV1::new(descriptor),
2847            PendingInspectionConsumerV1::new(
2848                descriptor,
2849                sink.clone(),
2850                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2851            ),
2852        )
2853        .unwrap();
2854        *sink.emitter.lock().unwrap() = Some(begin_logical_for_test(&producer));
2855        let mut logical = begin_logical_for_test(&producer);
2856        assert!(matches!(
2857            logical.try_emit_provider_request_for_test(safe_fields(), || {
2858                ProjectionAvailabilityV1::Present(provider_projection(b"<Email_1>"))
2859            }),
2860            InspectionAdmissionOutcomeV1::Accepted { .. }
2861        ));
2862        sink.wait_for(2);
2863        wait_for_accounting(&producer.state, 0, 0);
2864    }
2865
2866    #[test]
2867    fn metadata_only_serialization_is_content_invariant_after_id_normalization() {
2868        #[derive(Default)]
2869        struct MetadataSink {
2870            values: Mutex<Vec<serde_json::Value>>,
2871            changed: Condvar,
2872        }
2873        impl InspectionSink for MetadataSink {
2874            fn try_emit(&self, event: InspectionEventV1) -> Result<(), InspectionSinkErrorV1> {
2875                assert!(matches!(
2876                    event.view(),
2877                    InspectionEventViewV1::Omitted {
2878                        reason: ProjectionOmissionReasonV1::NotCapturedByPolicy,
2879                        ..
2880                    }
2881                ));
2882                self.values
2883                    .lock()
2884                    .unwrap()
2885                    .push(serde_json::to_value(event.meta()).unwrap());
2886                self.changed.notify_all();
2887                Ok(())
2888            }
2889        }
2890        let sink = Arc::new(MetadataSink::default());
2891        let descriptor = DashboardCaptureDescriptorV1::new(CaptureDomainsV1::MetadataOnly);
2892        let (producer, _consumer) = install_inspection_v1(
2893            PendingInspectionProducerV1::new(descriptor),
2894            PendingInspectionConsumerV1::new(
2895                descriptor,
2896                sink.clone(),
2897                InspectionQueueLimitsV1::new(4, 1024).unwrap(),
2898            ),
2899        )
2900        .unwrap();
2901        let mut logical = begin_logical_for_test(&producer);
2902        for content in [
2903            b"a".as_slice(),
2904            b"alice@example.invalid and more".as_slice(),
2905        ] {
2906            let outcome = logical.try_emit_provider_request_for_test(safe_fields(), || {
2907                ProjectionAvailabilityV1::Present(provider_projection(content))
2908            });
2909            assert!(matches!(
2910                outcome,
2911                InspectionAdmissionOutcomeV1::Accepted { .. }
2912            ));
2913        }
2914        let guard = sink.values.lock().unwrap();
2915        let (mut guard, timeout) = sink
2916            .changed
2917            .wait_timeout_while(guard, Duration::from_secs(60), |values| values.len() < 2)
2918            .unwrap();
2919        assert!(!timeout.timed_out());
2920        for value in &mut *guard {
2921            let object = value.as_object_mut().unwrap();
2922            object.remove("logical_id");
2923            object.remove("emission_id");
2924            object.remove("sequence");
2925        }
2926        assert_eq!(guard[0], guard[1]);
2927    }
2928}