Skip to main content

reef_core/runtime/
event.rs

1//! Owned outward events and the three strong-acceptance delivery seams.
2//!
3//! Ownership of the outward plane is settled by ADR-007: the loop produces
4//! events, the consumer decides the three strong seams, and a successful channel
5//! send is never treated as acceptance.
6//!
7//! This plane is an observable projection, not transcript serialization. Content
8//! is published before the corresponding transcript append linearizes and exposes
9//! renderable text plus provider item identity, not the complete
10//! [`SegmentExtensions`](crate::value::content::SegmentExtensions) or record-level
11//! provider data. Ordinary publication also fails closed after interruption, so a
12//! committed input may have no `InputAdmitted` projection. Current history comes
13//! from the Transcript; a composition layer that needs a byte-faithful resumable
14//! journal uses [`TranscriptHooks`](super::hook::TranscriptHooks) and restores a
15//! [`Snapshot`](crate::transcript::store::Snapshot).
16
17use std::error::Error;
18use std::fmt;
19use std::pin::Pin;
20use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
21use std::sync::{Arc, Mutex as SyncMutex};
22use std::task::{Context, Poll};
23
24use crate::cancel::Token;
25#[cfg(test)]
26use tokio::sync::Semaphore;
27use tokio::sync::{Mutex, Notify, mpsc};
28
29use crate::audit;
30use crate::redact;
31use crate::transcript::item;
32use crate::value::lifecycle::{Coord, Outcome};
33use crate::value::tool_call::ToolCall;
34
35/// The observable category of one outward event.
36///
37/// The set answers one question: what must a consumer be able to *distinguish*
38/// in order to render an agent or host a Run? A fact that can be read from an
39/// existing category plus its payload is deliberately not a category of its own,
40/// and a fact that belongs to a policy rather than to the runtime is not one
41/// either — see ADR-021 for the per-candidate reasoning.
42///
43/// Two absences are decisions rather than gaps:
44///
45/// - **There is no `GenerationStart`.** Hooks observe one
46///   ([`hook::LifecycleObservation::GenerationStart`]) because its payload is
47///   the frozen [`model::Request`] their own [`ModelHooks::before_model`] just
48///   finished editing. A consumer must not receive that value: it is the whole projected
49///   history plus the system instruction, which the consumer can already read
50///   from the transcript and which no event should copy onto a stream that may be
51///   logged. What a consumer needs — that a generation opened, and under which
52///   coordinate — is [`Kind::StepStart`], which the phase machine publishes
53///   exactly once per generation, and the [`Coord`] every later event carries.
54/// - **There is no interrupted category.** An interruption closes the outward
55///   lane before anything else can be published (C18/C20), so such a category
56///   could not have a production emitter — which is exactly the state this set
57///   was re-derived to leave. A consumer learns an interruption from its event
58///   stream closing and from [`run::Terminal`], which is observable only after
59///   cleanup has completed (C25).
60///
61/// One presence is worth naming for the same reason:
62///
63/// - **Input admission is a category, because nothing else could carry it.**
64///   An admitted input batch is the one kind of transcript record reef commits
65///   that the model did not produce, so it needs its own outward representation.
66///   That representation is best-effort under the fail-closed interruption rule,
67///   not an authoritative recovery record. A start or `NextTurn` batch opens a
68///   Turn; a `NextStep` batch
69///   is admitted at a Step boundary and does not. Deriving admission from
70///   [`Kind::TurnStart`] therefore fails in both directions — a Turn also opens
71///   without any admission at all, and a `NextStep` batch opens no Turn — and
72///   the record itself appears in no other category. See
73///   [`Kind::InputAdmitted`] and ADR-025.
74///
75/// [`hook::LifecycleObservation::GenerationStart`]: super::hook::LifecycleObservation::GenerationStart
76/// [`ModelHooks::before_model`]: super::hook::ModelHooks::before_model
77/// [`model::Request`]: super::model::Request
78/// [`run::Terminal`]: super::run::Terminal
79#[derive(Clone, Copy, Debug, Eq, PartialEq)]
80#[non_exhaustive]
81pub enum Kind {
82    /// Incremental answer text.
83    TextDelta,
84    /// Consolidated answer text.
85    Text,
86    /// Incremental model reasoning.
87    ThinkingDelta,
88    /// Consolidated model reasoning.
89    Thinking,
90    /// A turn began.
91    TurnStart,
92    /// A turn ended.
93    TurnEnd,
94    /// A step began.
95    StepStart,
96    /// A step ended.
97    StepEnd,
98    /// A real model generation ended.
99    GenerationEnd,
100    /// The model produced a complete tool call.
101    ToolCall,
102    /// A tool result was finalized.
103    ToolResult,
104    /// A recoverable extension degradation.
105    Error,
106    /// A non-model-visible audit fact.
107    Audit,
108    /// A policy requested a graceful run stop.
109    Stop,
110    /// An input batch was accepted and atomically recorded.
111    ///
112    /// Attempted once per batch, after the transcript append has committed and
113    /// before the Turn or Step that batch opens. So it is a statement of fact,
114    /// not a request: by the time a consumer sees it the record exists and
115    /// nothing can take it back. The converse is not promised: C18/C20 suppress
116    /// this ordinary event if interruption latches after commit. The Transcript
117    /// remains authoritative. [`Event::admitted_input`] carries the projected
118    /// items and which of the three routes they arrived by.
119    ///
120    /// A registration that wants a say runs at
121    /// [`InputHooks::before_input_admit`], which is the boundary *before* the
122    /// commit and the only place a batch can still be rewritten or refused.
123    ///
124    /// [`InputHooks::before_input_admit`]: super::hook::InputHooks::before_input_admit
125    InputAdmitted,
126    /// A claimed input batch was permanently refused.
127    ///
128    /// Only a mailbox batch can reach this: it has already left the
129    /// [`InputMailbox`] when the refusal happens, so nothing will retry it and
130    /// the sender would otherwise wait forever for an answer that is never
131    /// coming. [`Event::rejection_reason`] carries the reason the refusing
132    /// registration gave.
133    ///
134    /// [`InputMailbox`]: super::session::InputMailbox
135    InputRejected,
136}
137
138/// Which of reef's three input routes produced an admitted batch.
139///
140/// The routes are indistinguishable in the transcript — every one of them
141/// records an [`item::User`] and nothing in the record says which — so this is
142/// stated here or nowhere. A consumer that renders a conversation needs it: a
143/// continuation is the agent asking itself to keep going, and drawing it as
144/// something the human said would be wrong.
145#[derive(Clone, Copy, Debug, Eq, PartialEq)]
146#[non_exhaustive]
147pub enum InputOrigin {
148    /// The input [`Agent::start`] admitted, recorded before the loop began.
149    ///
150    /// This is the only route that can be rewritten before it is recorded, by a
151    /// [`RunHooks::prepare`](super::hook::RunHooks::prepare) registration, which
152    /// is why the batch is reported rather than assumed to be what the caller
153    /// passed.
154    ///
155    /// [`Agent::start`]: super::agent::Agent::start
156    Start,
157    /// A batch claimed from the Session's [`InputMailbox`].
158    ///
159    /// [`InputMailbox`]: super::session::InputMailbox
160    Mailbox,
161    /// Items a [`RunHooks::compose_continuation`](super::hook::RunHooks::compose_continuation)
162    /// registration composed to open another Turn.
163    Continuation,
164}
165
166/// One input batch exactly as it was recorded.
167///
168/// The items are the committed records and not the parts a caller submitted:
169/// [`RunHooks::prepare`](super::hook::RunHooks::prepare) and
170/// [`InputHooks::before_input_admit`](super::hook::InputHooks::before_input_admit)
171/// both rewrite input before it is recorded, so what the transcript holds is the
172/// only version worth reporting.
173#[derive(Clone, Debug)]
174pub struct AdmittedInput {
175    origin: InputOrigin,
176    items: Vec<item::Item>,
177}
178
179impl AdmittedInput {
180    /// Returns which route this batch arrived by.
181    #[must_use]
182    pub const fn origin(&self) -> InputOrigin {
183        self.origin
184    }
185
186    /// Returns the recorded items in transcript order.
187    #[must_use]
188    pub fn items(&self) -> &[item::Item] {
189        &self.items
190    }
191}
192
193/// One of the only three boundaries requiring an explicit consumer decision.
194#[derive(Clone, Copy, Debug, Eq, PartialEq)]
195#[non_exhaustive]
196pub enum DecisionPoint {
197    /// Before tool-hook policy and executor processing.
198    ToolCall,
199    /// Before later result or lifecycle publication.
200    ToolResult,
201    /// Before work following [`ToolHooks::after_tool_commit`](super::hook::ToolHooks::after_tool_commit).
202    AfterToolCommit,
203}
204
205/// A validated, nonempty opaque stop classification.
206#[derive(Clone, Debug, Eq, PartialEq)]
207pub struct StopCode(String);
208
209impl StopCode {
210    /// Validates an opaque stop code.
211    ///
212    /// # Errors
213    ///
214    /// [`ValidationError::EmptyStopCode`] if `code` has no characters. Core never
215    /// interprets the code, so an empty one would tell a consumer only that
216    /// something stopped the Run and refuse to say what — which is the one thing
217    /// this value exists to carry.
218    pub fn new(code: String) -> Result<Self, ValidationError> {
219        if code.is_empty() {
220            return Err(ValidationError::EmptyStopCode);
221        }
222        Ok(Self(code))
223    }
224
225    /// Returns the opaque code.
226    #[must_use]
227    pub fn as_str(&self) -> &str {
228        &self.0
229    }
230}
231
232/// A stable outward-event validation failure.
233#[derive(Clone, Copy, Debug, Eq, PartialEq)]
234#[non_exhaustive]
235pub enum ValidationError {
236    /// An audit kind was empty.
237    EmptyAuditKind,
238    /// A tool-call identity was empty.
239    EmptyToolCallId,
240    /// A tool name was empty.
241    EmptyToolName,
242    /// A stop code was empty.
243    EmptyStopCode,
244    /// The event category and its private payload disagreed.
245    PayloadMismatch,
246    /// A private producer selected a decision point inconsistent with the event.
247    InvalidDecisionPoint,
248}
249
250impl fmt::Display for ValidationError {
251    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
252        formatter.write_str(match self {
253            Self::EmptyAuditKind => "event audit kind must be non-empty",
254            Self::EmptyToolCallId => "event tool-call identity must be non-empty",
255            Self::EmptyToolName => "event tool name must be non-empty",
256            Self::EmptyStopCode => "event stop code must be non-empty",
257            Self::PayloadMismatch => "event category and payload do not match",
258            Self::InvalidDecisionPoint => "event used an invalid decision point",
259        })
260    }
261}
262
263impl Error for ValidationError {}
264
265#[derive(Clone)]
266enum Payload {
267    Text(String),
268    Lifecycle(Option<Outcome>),
269    ToolCall(ToolCall),
270    ToolResult(item::ToolResult),
271    Audit(audit::Event),
272    Error(Arc<dyn Error + Send + Sync>),
273    Stop(StopCode),
274    Input(AdmittedInput),
275    Rejection(String),
276}
277
278impl fmt::Debug for Payload {
279    /// Sizes the one variant that carries model text and flattens the error.
280    ///
281    /// `Text` is answer or reasoning content on its way to a consumer. `Error`
282    /// holds an arbitrary third-party failure whose own `Debug` this crate does
283    /// not control, so it is rendered through `Display`, which is the operator
284    /// diagnostic the type is for. Every other variant already redacts itself.
285    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
286        match self {
287            Self::Text(text) => formatter
288                .debug_tuple("Text")
289                .field(&redact::Bytes(text.len()))
290                .finish(),
291            Self::Lifecycle(outcome) => formatter.debug_tuple("Lifecycle").field(outcome).finish(),
292            Self::ToolCall(call) => formatter.debug_tuple("ToolCall").field(call).finish(),
293            Self::ToolResult(result) => formatter.debug_tuple("ToolResult").field(result).finish(),
294            Self::Audit(audit) => formatter.debug_tuple("Audit").field(audit).finish(),
295            Self::Error(error) => formatter
296                .debug_tuple("Error")
297                .field(&error.to_string())
298                .finish(),
299            Self::Stop(code) => formatter.debug_tuple("Stop").field(code).finish(),
300            // `Item` redacts itself, so the batch prints its own way; the reason
301            // is a diagnostic a registration wrote for an operator to read.
302            Self::Input(input) => formatter.debug_tuple("Input").field(input).finish(),
303            Self::Rejection(reason) => formatter.debug_tuple("Rejection").field(reason).finish(),
304        }
305    }
306}
307
308/// An immutable outward event; loop-owned variants have no public constructors.
309#[derive(Clone, Debug)]
310pub struct Event {
311    kind: Kind,
312    coord: Option<Coord>,
313    item_id: Option<String>,
314    payload: Payload,
315}
316
317impl Event {
318    /// Constructs a validated extension-produced audit event.
319    ///
320    /// # Errors
321    ///
322    /// [`ValidationError::EmptyAuditKind`] if the audit fact does not name a
323    /// kind. An audit fact is classified by its kind, and an unclassifiable one
324    /// cannot be filtered, routed, or counted by whoever consumes the stream.
325    ///
326    /// This is the only construction check on the two event kinds an extension
327    /// may build. The remaining [`ValidationError`] variants describe private
328    /// producer mistakes and cannot be reached from here.
329    pub fn from_audit(audit: audit::Event) -> Result<Self, ValidationError> {
330        if audit.kind().is_empty() {
331            return Err(ValidationError::EmptyAuditKind);
332        }
333        Ok(Self {
334            kind: Kind::Audit,
335            coord: None,
336            item_id: None,
337            payload: Payload::Audit(audit),
338        })
339    }
340
341    /// Constructs a validated extension-produced non-fatal error event.
342    #[must_use]
343    pub fn from_error(error: Arc<dyn Error + Send + Sync>) -> Self {
344        Self {
345            kind: Kind::Error,
346            coord: None,
347            item_id: None,
348            payload: Payload::Error(error),
349        }
350    }
351
352    /// Returns the event category.
353    #[must_use]
354    pub const fn kind(&self) -> Kind {
355        self.kind
356    }
357
358    /// Returns the runtime-stamped coordinate, when applicable.
359    #[must_use]
360    pub const fn coord(&self) -> Option<&Coord> {
361        self.coord.as_ref()
362    }
363
364    /// Returns the provider's identity for the content item this event is part of.
365    ///
366    /// [`coord`](Self::coord) says where the event sits in reef's own
367    /// Run/Turn/Step structure; this says which of the provider's items it
368    /// belongs to. A single generation can produce several — an answer alongside
369    /// reasoning, or several separate answer items — and they interleave, so a
370    /// consumer rendering incrementally needs this to put each fragment under
371    /// the right heading rather than concatenating everything a Step emitted.
372    ///
373    /// Present on all four content kinds, and the same string on both sides: a
374    /// delta reports the identity of the
375    /// [`model::Event::ContentDelta`](crate::runtime::model::Event::ContentDelta)
376    /// it projects, the consolidated event reports the one the committed
377    /// [`Segment`](crate::value::content::Segment) kept, and
378    /// [`model::StreamGrammar`](crate::runtime::model::StreamGrammar) refuses a
379    /// stream whose final does not close the identity its deltas opened. So
380    /// grouping deltas by this value and then matching the consolidated event to
381    /// the same group is sound, and it stays sound for a provider that streams
382    /// no deltas at all.
383    ///
384    /// `None` on every other kind, and on a content event whose segment no
385    /// provider produced — one an
386    /// [`OnAfterModel`](crate::runtime::hook::ModelHooks::after_model)
387    /// registration composed, for instance. A registration that replaces
388    /// assistant content decides its identity too, including deciding it has
389    /// none, and what reaches a consumer here is always the identity of the
390    /// content it is attached to rather than of the content the provider
391    /// originally sent.
392    #[must_use]
393    pub fn item_id(&self) -> Option<&str> {
394        self.item_id.as_deref()
395    }
396
397    /// Returns text carried by a text or thinking event.
398    #[must_use]
399    pub fn text(&self) -> Option<&str> {
400        match &self.payload {
401            Payload::Text(text) => Some(text),
402            _ => None,
403        }
404    }
405
406    /// Returns a tool-call payload.
407    #[must_use]
408    pub const fn tool_call(&self) -> Option<&ToolCall> {
409        match &self.payload {
410            Payload::ToolCall(call) => Some(call),
411            _ => None,
412        }
413    }
414
415    /// Returns a tool-result payload.
416    #[must_use]
417    pub const fn tool_result(&self) -> Option<&item::ToolResult> {
418        match &self.payload {
419            Payload::ToolResult(result) => Some(result),
420            _ => None,
421        }
422    }
423
424    /// Returns the committed batch an [`InputAdmitted`](Kind::InputAdmitted) event projects.
425    ///
426    /// Never empty: an empty batch is refused before it can be recorded, because
427    /// recording one would assert that somebody said nothing.
428    #[must_use]
429    pub const fn admitted_input(&self) -> Option<&AdmittedInput> {
430        match &self.payload {
431            Payload::Input(input) => Some(input),
432            _ => None,
433        }
434    }
435
436    /// Returns why an [`InputRejected`](Kind::InputRejected) event refused a batch.
437    ///
438    /// Never empty: a rejection with no reason is a hook defect that fails the
439    /// Run, because the reason is the only thing the refusal leaves behind.
440    #[must_use]
441    pub fn rejection_reason(&self) -> Option<&str> {
442        match &self.payload {
443            Payload::Rejection(reason) => Some(reason),
444            _ => None,
445        }
446    }
447
448    /// Returns a lifecycle end outcome.
449    #[must_use]
450    pub const fn outcome(&self) -> Option<Outcome> {
451        match self.payload {
452            Payload::Lifecycle(outcome) => outcome,
453            _ => None,
454        }
455    }
456
457    /// Returns an audit payload.
458    #[must_use]
459    pub const fn as_audit(&self) -> Option<&audit::Event> {
460        match &self.payload {
461            Payload::Audit(audit) => Some(audit),
462            _ => None,
463        }
464    }
465
466    /// Returns a recoverable error payload.
467    #[must_use]
468    pub fn as_error(&self) -> Option<&(dyn Error + Send + Sync)> {
469        match &self.payload {
470            Payload::Error(error) => Some(error.as_ref()),
471            _ => None,
472        }
473    }
474
475    /// Returns the opaque stop classification.
476    #[must_use]
477    pub const fn stop_code(&self) -> Option<&StopCode> {
478        match &self.payload {
479            Payload::Stop(code) => Some(code),
480            _ => None,
481        }
482    }
483
484    const fn driver_text(kind: Kind, text: String, coord: Coord, item_id: Option<String>) -> Self {
485        Self {
486            kind,
487            coord: Some(coord),
488            item_id,
489            payload: Payload::Text(text),
490        }
491    }
492
493    const fn driver_lifecycle(kind: Kind, outcome: Option<Outcome>, coord: Coord) -> Self {
494        Self {
495            kind,
496            coord: Some(coord),
497            item_id: None,
498            payload: Payload::Lifecycle(outcome),
499        }
500    }
501
502    const fn driver_tool_call(call: ToolCall, coord: Coord) -> Self {
503        Self {
504            kind: Kind::ToolCall,
505            coord: Some(coord),
506            item_id: None,
507            payload: Payload::ToolCall(call),
508        }
509    }
510
511    const fn driver_tool_result(result: item::ToolResult, coord: Coord) -> Self {
512        Self {
513            kind: Kind::ToolResult,
514            coord: Some(coord),
515            item_id: None,
516            payload: Payload::ToolResult(result),
517        }
518    }
519
520    const fn driver_stop(code: StopCode, coord: Coord) -> Self {
521        Self {
522            kind: Kind::Stop,
523            coord: Some(coord),
524            item_id: None,
525            payload: Payload::Stop(code),
526        }
527    }
528
529    const fn driver_input_admitted(
530        origin: InputOrigin,
531        items: Vec<item::Item>,
532        coord: Coord,
533    ) -> Self {
534        Self {
535            kind: Kind::InputAdmitted,
536            coord: Some(coord),
537            item_id: None,
538            payload: Payload::Input(AdmittedInput { origin, items }),
539        }
540    }
541
542    const fn driver_input_rejected(reason: String, coord: Coord) -> Self {
543        Self {
544            kind: Kind::InputRejected,
545            coord: Some(coord),
546            item_id: None,
547            payload: Payload::Rejection(reason),
548        }
549    }
550
551    fn validate(&self, decision_point: Option<DecisionPoint>) -> Result<(), ValidationError> {
552        if !payload_matches(self.kind, &self.payload) {
553            return Err(ValidationError::PayloadMismatch);
554        }
555        match &self.payload {
556            Payload::ToolCall(call) if call.id().as_str().is_empty() => {
557                Err(ValidationError::EmptyToolCallId)
558            }
559            Payload::ToolCall(call) if call.name().as_str().is_empty() => {
560                Err(ValidationError::EmptyToolName)
561            }
562            Payload::ToolResult(result) if result.call_id().as_str().is_empty() => {
563                Err(ValidationError::EmptyToolCallId)
564            }
565            Payload::ToolResult(result) if result.tool_name().as_str().is_empty() => {
566                Err(ValidationError::EmptyToolName)
567            }
568            Payload::Audit(audit) if audit.kind().is_empty() => {
569                Err(ValidationError::EmptyAuditKind)
570            }
571            Payload::Stop(code) if code.as_str().is_empty() => Err(ValidationError::EmptyStopCode),
572            _ if decision_point != expected_decision_point(self.kind, decision_point) => {
573                Err(ValidationError::InvalidDecisionPoint)
574            }
575            _ => Ok(()),
576        }
577    }
578}
579
580const fn payload_matches(kind: Kind, payload: &Payload) -> bool {
581    matches!(
582        (kind, payload),
583        (
584            Kind::TextDelta | Kind::Text | Kind::ThinkingDelta | Kind::Thinking,
585            Payload::Text(_)
586        ) | (Kind::TurnStart | Kind::StepStart, Payload::Lifecycle(None))
587            | (
588                Kind::TurnEnd | Kind::StepEnd | Kind::GenerationEnd,
589                Payload::Lifecycle(Some(_))
590            )
591            | (Kind::ToolCall, Payload::ToolCall(_))
592            | (Kind::ToolResult, Payload::ToolResult(_))
593            | (Kind::Error, Payload::Error(_))
594            | (Kind::Audit, Payload::Audit(_))
595            | (Kind::Stop, Payload::Stop(_))
596            | (Kind::InputAdmitted, Payload::Input(_))
597            | (Kind::InputRejected, Payload::Rejection(_))
598    )
599}
600
601fn expected_decision_point(kind: Kind, requested: Option<DecisionPoint>) -> Option<DecisionPoint> {
602    match kind {
603        Kind::ToolCall => Some(DecisionPoint::ToolCall),
604        Kind::ToolResult => Some(DecisionPoint::ToolResult),
605        Kind::Audit | Kind::Error if requested == Some(DecisionPoint::AfterToolCommit) => requested,
606        _ => None,
607    }
608}
609
610/// A delivery decision was already completed.
611#[derive(Clone, Copy, Debug, Eq, PartialEq)]
612#[non_exhaustive]
613pub enum DecisionError {
614    /// This ordinary event has no decision barrier.
615    NotRequired,
616    /// Another decision or cancellation already won.
617    AlreadyDecided,
618}
619
620impl fmt::Display for DecisionError {
621    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
622        formatter.write_str(match self {
623            Self::NotRequired => "event delivery does not require acceptance",
624            Self::AlreadyDecided => "event delivery was already decided",
625        })
626    }
627}
628
629impl Error for DecisionError {}
630
631const PENDING: u8 = 0;
632const ACCEPTED: u8 = 1;
633const REJECTED: u8 = 2;
634const CANCELED: u8 = 3;
635
636struct Decision {
637    value: AtomicU8,
638    changed: Notify,
639    /// The composite interruption token this wait must wake on.
640    cancel: Token,
641    /// The run's shared single linearization point for its nonfatal cause.
642    ///
643    /// The composite token alone cannot distinguish parent cancellation from the
644    /// child cancellation caused by this run's own `request_stop`/Drop, so every
645    /// interruption value is selected here instead of from the token.
646    nonfatal: Arc<NonfatalCause>,
647    #[cfg(test)]
648    after_pending_check: SyncMutex<Option<WaitBarriers>>,
649}
650
651#[cfg(test)]
652struct WaitBarriers {
653    checked: Arc<std::sync::Barrier>,
654    resume: Arc<std::sync::Barrier>,
655}
656
657impl Decision {
658    fn decide(&self, value: u8) -> Result<(), DecisionError> {
659        self.value
660            .compare_exchange(PENDING, value, Ordering::AcqRel, Ordering::Acquire)
661            .map(|_| self.changed.notify_waiters())
662            .map_err(|_| DecisionError::AlreadyDecided)
663    }
664
665    fn decide_consumer(&self, value: u8) -> Result<(), DecisionError> {
666        if self.cancel.is_cancelled() {
667            let _already_decided = self.decide(self.nonfatal.interrupted_decision());
668            Err(DecisionError::AlreadyDecided)
669        } else {
670            self.decide(value)
671        }
672    }
673
674    fn abandon(&self) -> Result<(), DecisionError> {
675        let value = if self.cancel.is_cancelled() {
676            self.nonfatal.interrupted_decision()
677        } else {
678            REJECTED
679        };
680        self.decide(value)
681    }
682
683    async fn wait(&self) -> StrongDecision {
684        loop {
685            let changed = self.changed.notified();
686            tokio::pin!(changed);
687            let _already_ready = changed.as_mut().enable();
688            match self.value.load(Ordering::Acquire) {
689                ACCEPTED => return StrongDecision::Accepted,
690                REJECTED => return StrongDecision::Rejected,
691                CANCELED => return StrongDecision::Cancelled,
692                _ => {
693                    #[cfg(test)]
694                    self.pause_after_pending_check();
695                    tokio::select! {
696                        biased;
697                        () = self.cancel.cancelled() => {
698                            let _already_decided =
699                                self.decide(self.nonfatal.interrupted_decision());
700                        }
701                        () = &mut changed => {}
702                    }
703                }
704            }
705        }
706    }
707
708    #[cfg(test)]
709    fn pause_after_pending_check(&self) {
710        let barriers = self
711            .after_pending_check
712            .lock()
713            .expect("event wait barrier lock poisoned")
714            .take();
715        if let Some(barriers) = barriers {
716            barriers.checked.wait();
717            barriers.resume.wait();
718        }
719    }
720}
721
722/// One event and, at a strong decision point, its exactly-once decision guard.
723///
724/// Most deliveries are ordinary transport: read the [`event`](Delivery::event)
725/// and move on. Three decision points are rendezvous the Run is blocked on, and
726/// it does not proceed until this delivery is [`accept`](Delivery::accept)ed or
727/// [`reject`](Delivery::reject)ed. Dropping one undecided rejects it.
728///
729/// Do not infer this from [`Event::kind`].
730/// [`AfterToolCommit`](DecisionPoint::AfterToolCommit) can accompany either an
731/// [`Audit`](Kind::Audit) or [`Error`](Kind::Error) event, and either kind can
732/// also be an ordinary delivery. Always call
733/// [`decision_point`](Delivery::decision_point) for each delivery; that makes the
734/// whole acceptance protocol one line:
735///
736/// ```
737/// # use reef_core::runtime::event;
738/// # fn handle(delivery: &event::Delivery) -> Result<(), event::DecisionError> {
739/// if delivery.decision_point().is_some() {
740///     delivery.accept()?;
741/// }
742/// # Ok(())
743/// # }
744/// ```
745///
746/// A consumer that means to refuse further work — a policy that says no, a host
747/// shutting down — calls [`reject`](Delivery::reject) instead. At
748/// [`ToolCall`](DecisionPoint::ToolCall), rejection prevents tool-hook and executor
749/// processing. At [`ToolResult`](DecisionPoint::ToolResult) or
750/// [`AfterToolCommit`](DecisionPoint::AfterToolCommit), execution and commit have
751/// already happened; rejection does not undo those facts and only prevents later
752/// work.
753pub struct Delivery {
754    event: Event,
755    decision_point: Option<DecisionPoint>,
756    decision: Option<Arc<Decision>>,
757}
758
759impl fmt::Debug for Delivery {
760    /// Shows the event, the decision point, and whether a decision is owed.
761    ///
762    /// The decision guard is reported by presence rather than by state: reading
763    /// its state would mean loading the very atomic whose exactly-once
764    /// transition the guard exists to serialise, and a formatter has no business
765    /// participating in that handshake.
766    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
767        formatter
768            .debug_struct("Delivery")
769            .field("event", &self.event)
770            .field("decision_point", &self.decision_point)
771            .field("decision", &redact::Presence(self.decision.is_some()))
772            .finish()
773    }
774}
775
776impl Delivery {
777    /// Returns the immutable event.
778    #[must_use]
779    pub const fn event(&self) -> &Event {
780        &self.event
781    }
782
783    /// Returns the strong decision point, or `None` for ordinary transport delivery.
784    #[must_use]
785    pub const fn decision_point(&self) -> Option<DecisionPoint> {
786        self.decision_point
787    }
788
789    /// Accepts this strong boundary exactly once.
790    ///
791    /// # Errors
792    ///
793    /// - [`DecisionError::NotRequired`] if this is ordinary transport delivery
794    ///   rather than one of the three strong seams. Check
795    ///   [`decision_point`](Self::decision_point) to tell them apart; nothing is owed
796    ///   for an ordinary delivery and nothing happens if it is dropped undecided.
797    /// - [`DecisionError::AlreadyDecided`] if this delivery has already been
798    ///   decided, or if cancellation resolved it first. A cancelled Run's
799    ///   deliveries report this even on a first call, because acceptance would
800    ///   authorize work the Run is already unwinding out of — so a consumer
801    ///   cannot treat this variant as "somebody else said yes".
802    ///
803    /// Either way the governed work does not proceed on this call's authority,
804    /// and the decision that did win is not displaced.
805    pub fn accept(&self) -> Result<(), DecisionError> {
806        self.decision
807            .as_ref()
808            .ok_or(DecisionError::NotRequired)?
809            .decide_consumer(ACCEPTED)
810    }
811
812    /// Rejects this strong boundary exactly once.
813    ///
814    /// At [`DecisionPoint::ToolCall`], rejection prevents subsequent tool-hook and
815    /// executor processing. At [`DecisionPoint::ToolResult`] or
816    /// [`DecisionPoint::AfterToolCommit`], the tool has already executed and its
817    /// result has already been committed. Rejection does not undo those facts; it
818    /// only prevents later work.
819    ///
820    /// # Errors
821    ///
822    /// [`DecisionError::NotRequired`] if this is ordinary transport delivery, or
823    /// [`DecisionError::AlreadyDecided`] if a decision or a cancellation already
824    /// won — the same two conditions [`accept`](Self::accept) reports, for the
825    /// same reasons.
826    ///
827    /// Neither is a reason to retry. `NotRequired` means no decision was owed;
828    /// `AlreadyDecided` means the winning decision remains in force, and this
829    /// error does not reveal whether it accepted, rejected, or cancelled the
830    /// boundary.
831    pub fn reject(&self) -> Result<(), DecisionError> {
832        self.decision
833            .as_ref()
834            .ok_or(DecisionError::NotRequired)?
835            .decide_consumer(REJECTED)
836    }
837}
838
839impl Drop for Delivery {
840    fn drop(&mut self) {
841        if let Some(decision) = &self.decision {
842            let _already_decided = decision.abandon();
843        }
844    }
845}
846
847/// The unique consumer of a run's outward events.
848///
849/// There is exactly one of these per Run. An observable start receives it atomically
850/// from [`Agent::start_observed`](crate::runtime::agent::Agent::start_observed); the
851/// compatibility [`Run::take_events`](crate::runtime::run::Run::take_events) path hands
852/// it over once after `Agent::start`. Draining it to `None` is how a consumer knows
853/// the Run's outward lane is closed; the
854/// [`Terminal`](crate::runtime::run::Terminal) is then already resolved or about
855/// to be, and [`Run::wait`](crate::runtime::run::Run::wait) produces it.
856///
857/// Dropping this stream asks the Run to stop. That is deliberate — a consumer
858/// that has stopped listening is stating it wants nothing further — so a Run you
859/// mean to finish should be drained rather than abandoned.
860///
861/// ```
862/// # use reef_core::runtime::event;
863/// # async fn drain(events: &mut event::Stream) -> Vec<event::Kind> {
864/// let mut seen = Vec::new();
865/// while let Some(delivery) = events.recv().await {
866///     seen.push(delivery.event().kind());
867///     // Three decision points are rendezvous; do not infer them from Event::kind.
868///     // AfterToolCommit can accompany Audit or Error. Always ask the delivery.
869///     if delivery.decision_point().is_some() {
870///         delivery.accept().expect("a fresh strong delivery accepts once");
871///     }
872/// }
873/// seen
874/// # }
875/// ```
876///
877/// It also implements [`futures_core::Stream`], so a consumer already built
878/// around stream combinators can use it directly.
879pub struct Stream {
880    receiver: mpsc::UnboundedReceiver<Delivery>,
881    control: Arc<Control>,
882}
883
884impl fmt::Debug for Stream {
885    /// Reports whether the run's outward lane has latched a fatal violation.
886    ///
887    /// The load is relaxed on purpose: this is a diagnostic read, and ordering
888    /// it against the producer would let formatting influence the very
889    /// termination sequence it is trying to describe.
890    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
891        formatter
892            .debug_struct("Stream")
893            .field("fatal", &self.control.fatal.load(Ordering::Relaxed))
894            .finish()
895    }
896}
897
898impl Stream {
899    /// Receives the next delivery.
900    pub async fn recv(&mut self) -> Option<Delivery> {
901        self.receiver.recv().await
902    }
903}
904
905impl futures_core::Stream for Stream {
906    type Item = Delivery;
907
908    fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
909        self.receiver.poll_recv(context)
910    }
911}
912
913impl Drop for Stream {
914    fn drop(&mut self) {
915        self.control.request_stop();
916        self.receiver.close();
917    }
918}
919
920#[derive(Clone, Copy, Debug, Eq, PartialEq)]
921pub(crate) enum DeliveryOutcome {
922    Delivered,
923    Accepted,
924    Rejected,
925}
926
927/// The precise decision at one of the three runtime-owned strong seams.
928///
929/// This stays crate-private so the outward delivery API remains unchanged.
930#[derive(Clone, Copy, Debug, Eq, PartialEq)]
931pub(crate) enum StrongDecision {
932    Accepted,
933    Rejected,
934    Cancelled,
935}
936
937impl From<StrongDecision> for DeliveryOutcome {
938    fn from(decision: StrongDecision) -> Self {
939        match decision {
940            StrongDecision::Accepted => Self::Accepted,
941            StrongDecision::Rejected | StrongDecision::Cancelled => Self::Rejected,
942        }
943    }
944}
945
946#[derive(Clone, Copy, Debug, Eq, PartialEq)]
947struct DeliveryResolution {
948    outward: DeliveryOutcome,
949    strong: Option<StrongDecision>,
950}
951
952impl DeliveryResolution {
953    const fn ordinary(outward: DeliveryOutcome) -> Self {
954        Self {
955            outward,
956            strong: None,
957        }
958    }
959
960    fn strong(decision: StrongDecision) -> Self {
961        Self {
962            outward: decision.into(),
963            strong: Some(decision),
964        }
965    }
966}
967
968#[derive(Clone, Copy, Debug, Eq, PartialEq)]
969pub(crate) enum TerminalIntent {
970    Running,
971    Stopped,
972    Cancelled,
973    Failed,
974}
975
976impl TerminalIntent {
977    #[cfg_attr(not(test), expect(dead_code, reason = "reached only by tests so far"))]
978    pub(crate) const fn outcome(self) -> Option<Outcome> {
979        match self {
980            Self::Running => None,
981            Self::Stopped => Some(Outcome::Stopped),
982            Self::Cancelled => Some(Outcome::Cancelled),
983            Self::Failed => Some(Outcome::Failed),
984        }
985    }
986}
987
988/// No nonfatal terminal cause has been frozen yet.
989const NONFATAL_NONE: u8 = 0;
990/// A normal `request_stop`/`Stream` Drop won the linearization point.
991const NONFATAL_STOPPED: u8 = 1;
992/// Real parent cancellation won the linearization point.
993const NONFATAL_CANCELED: u8 = 2;
994
995/// The run's single linearization point for its one nonfatal terminal cause.
996///
997/// `Stopped` and `Cancelled` are two *causes* of the same interruption, so they
998/// cannot be derived independently from the cancellation tree: the child token
999/// this run cancels for its own normal stop is indistinguishable from parent
1000/// cancellation once observed. Only the caller-owned `parent` token — which this
1001/// run never cancels — separates the two, and the first observer to resolve the
1002/// cause freezes it here for every later observer.
1003///
1004/// The frozen cause is never rewritten. A fatal failure is a strictly higher,
1005/// independent latch on [`Control`], so it can still upgrade the terminal in
1006/// either order without this cause ever being lost or reinterpreted.
1007struct NonfatalCause {
1008    /// The caller-owned token whose cancellation is real parent cancellation.
1009    parent: Token,
1010    cause: SyncMutex<u8>,
1011}
1012
1013impl NonfatalCause {
1014    /// Resolves the frozen nonfatal cause, freezing it on first resolution.
1015    ///
1016    /// `normal_stop` is `true` only for `request_stop`/`Stream` Drop, which
1017    /// is itself a stop request. Every other caller merely observes: it can
1018    /// freeze `Cancelled` from an already cancelled parent, but never invents a
1019    /// stop. Reading `parent` inside the critical section is what keeps a
1020    /// stop-induced child cancellation from ever being reported as `Cancelled`,
1021    /// and what makes a parent cancellation that already won outrank a later
1022    /// normal stop.
1023    fn freeze(&self, normal_stop: bool) -> u8 {
1024        let mut cause = self
1025            .cause
1026            .lock()
1027            .expect("event nonfatal cause lock poisoned");
1028        if *cause == NONFATAL_NONE {
1029            if self.parent.is_cancelled() {
1030                *cause = NONFATAL_CANCELED;
1031            } else if normal_stop {
1032                *cause = NONFATAL_STOPPED;
1033            }
1034        }
1035        *cause
1036    }
1037
1038    /// Reads the frozen cause without resolving or freezing anything.
1039    #[cfg(test)]
1040    fn frozen(&self) -> u8 {
1041        *self
1042            .cause
1043            .lock()
1044            .expect("event nonfatal cause lock poisoned")
1045    }
1046
1047    /// Selects the strong decision point value an interrupted delivery must linearize to.
1048    fn interrupted_decision(&self) -> u8 {
1049        if self.freeze(false) == NONFATAL_CANCELED {
1050            CANCELED
1051        } else {
1052            REJECTED
1053        }
1054    }
1055}
1056
1057#[cfg(test)]
1058#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1059pub(crate) enum FreezePoint {
1060    Stop,
1061    Fatal,
1062}
1063
1064#[cfg(test)]
1065struct TestFreezePause {
1066    point: FreezePoint,
1067    reached: Arc<std::sync::Barrier>,
1068    resume: Arc<std::sync::Barrier>,
1069}
1070
1071#[cfg(test)]
1072struct TestFinalConfirmPause {
1073    reached: Semaphore,
1074    resume: Semaphore,
1075}
1076
1077/// One held tool emission, announced synchronously and released asynchronously.
1078///
1079/// The waiter is a synchronous tool mapper on the loop's own runtime thread, so
1080/// the announcement cannot be a future: nothing would poll it.
1081#[cfg(test)]
1082struct TestEmitPause {
1083    reached: std::sync::mpsc::Sender<()>,
1084    resume: Semaphore,
1085}
1086
1087struct Control {
1088    /// The one frozen nonfatal cause, shared with every strong decision.
1089    nonfatal: Arc<NonfatalCause>,
1090    fatal: AtomicBool,
1091    fatal_event: SyncMutex<Option<ValidationError>>,
1092    stop_emitted: AtomicBool,
1093    pending: SyncMutex<Option<Arc<Decision>>>,
1094    /// The composite interruption token cancelled by parent cancellation and by
1095    /// this run's own normal stop.
1096    cancel: Token,
1097    interruption: Token,
1098    #[cfg(test)]
1099    before_reject_pause: SyncMutex<Option<TestFreezePause>>,
1100    #[cfg(test)]
1101    after_final_confirm_pause: SyncMutex<Option<Arc<TestFinalConfirmPause>>>,
1102}
1103
1104/// Abandons and clears the producer's strong-decision slot on completion or future Drop.
1105///
1106/// The serialized producer owns at most one decision. Keeping that registration
1107/// behind an RAII guard prevents a dropped `Driver::run` future from leaving a
1108/// stale strong decision reachable through `Control` after its delivery owner has
1109/// already been unwound.
1110struct PendingDecision<'a> {
1111    control: &'a Control,
1112    decision: Arc<Decision>,
1113}
1114
1115impl Drop for PendingDecision<'_> {
1116    fn drop(&mut self) {
1117        // The producer future owns the live side of this handshake. If that
1118        // future is dropped, terminate the decision before making the slot
1119        // available to a successor; otherwise an already-delivered guard could
1120        // still accept work whose owner no longer exists.
1121        let _already_decided = self.decision.abandon();
1122        self.control.clear(&self.decision);
1123    }
1124}
1125
1126impl Control {
1127    fn intent(&self) -> TerminalIntent {
1128        // Fatal is an independent, strictly higher latch, so it wins in either
1129        // interleaving order without ever consulting the nonfatal cause.
1130        if self.fatal.load(Ordering::Acquire) {
1131            return TerminalIntent::Failed;
1132        }
1133        // Observing only: this can freeze Cancelled from an already cancelled
1134        // parent, but it never invents a stop.
1135        match self.nonfatal.freeze(false) {
1136            NONFATAL_CANCELED => TerminalIntent::Cancelled,
1137            NONFATAL_STOPPED => TerminalIntent::Stopped,
1138            _ => TerminalIntent::Running,
1139        }
1140    }
1141
1142    fn strong_interruption(&self) -> Option<StrongDecision> {
1143        if self.fatal.load(Ordering::Acquire) {
1144            return Some(StrongDecision::Rejected);
1145        }
1146        match self.nonfatal.freeze(false) {
1147            NONFATAL_CANCELED => Some(StrongDecision::Cancelled),
1148            NONFATAL_STOPPED => Some(StrongDecision::Rejected),
1149            _ => None,
1150        }
1151    }
1152
1153    /// Linearizes the decision exposed to the strong decision point caller.
1154    ///
1155    /// A consumer acceptance is only an internal handshake result. Stop or fatal
1156    /// control may freeze after that CAS but before `reject_pending` reaches it;
1157    /// consulting this shared control point prevents such an internal acceptance
1158    /// from authorizing tool execution. Rejection and cancellation already encode
1159    /// a terminal consumer/control choice and are preserved.
1160    fn final_confirm_strong(&self, decision: StrongDecision) -> StrongDecision {
1161        if decision == StrongDecision::Accepted {
1162            self.strong_interruption().unwrap_or(decision)
1163        } else {
1164            decision
1165        }
1166    }
1167
1168    #[cfg(test)]
1169    fn pause_before_reject(&self, point: FreezePoint) {
1170        let pause = {
1171            let mut slot = self
1172                .before_reject_pause
1173                .lock()
1174                .expect("event freeze pause lock poisoned");
1175            if slot.as_ref().is_some_and(|pause| pause.point == point) {
1176                slot.take()
1177            } else {
1178                None
1179            }
1180        };
1181        if let Some(pause) = pause {
1182            pause.reached.wait();
1183            pause.resume.wait();
1184        }
1185    }
1186
1187    #[cfg(test)]
1188    async fn pause_after_final_confirm(&self) {
1189        let pause = self
1190            .after_final_confirm_pause
1191            .lock()
1192            .expect("event final-confirm pause lock poisoned")
1193            .take();
1194        if let Some(pause) = pause {
1195            pause.reached.add_permits(1);
1196            pause
1197                .resume
1198                .acquire()
1199                .await
1200                .expect("event final-confirm pause remains open")
1201                .forget();
1202        }
1203    }
1204
1205    /// Reports whether an interruption is already frozen for this run.
1206    ///
1207    /// This is the shared gate for registration and ordinary emission: both must
1208    /// fail closed once any nonfatal cause or fatal failure has been latched.
1209    fn interrupted(&self) -> bool {
1210        self.fatal.load(Ordering::Acquire) || self.nonfatal.freeze(false) != NONFATAL_NONE
1211    }
1212
1213    fn register(&self, decision: &Arc<Decision>) {
1214        let mut pending = self.pending.lock().expect("event pending lock poisoned");
1215        if self.interrupted() {
1216            let _already_decided = decision.decide(self.nonfatal.interrupted_decision());
1217        } else {
1218            *pending = Some(decision.clone());
1219        }
1220    }
1221
1222    fn clear(&self, decision: &Arc<Decision>) {
1223        let mut pending = self.pending.lock().expect("event pending lock poisoned");
1224        if pending
1225            .as_ref()
1226            .is_some_and(|current| Arc::ptr_eq(current, decision))
1227        {
1228            pending.take();
1229        }
1230    }
1231
1232    /// Terminates the registered strong decision with the frozen nonfatal cause.
1233    fn reject_pending(&self) {
1234        let decided = self.nonfatal.interrupted_decision();
1235        if let Some(decision) = self
1236            .pending
1237            .lock()
1238            .expect("event pending lock poisoned")
1239            .take()
1240        {
1241            let _already_decided = decision.decide(decided);
1242        }
1243    }
1244
1245    /// Freezes a normal stop cause, unless a parent cancellation already won.
1246    fn latch_stop(&self) {
1247        let _cause = self.nonfatal.freeze(true);
1248        #[cfg(test)]
1249        self.pause_before_reject(FreezePoint::Stop);
1250        self.reject_pending();
1251        self.interruption.cancel();
1252    }
1253
1254    fn request_stop(&self) {
1255        self.latch_stop();
1256        // The composite token is cancelled only after the cause is frozen, so no
1257        // observer can mistake this run's own stop for parent cancellation.
1258        self.cancel.cancel();
1259    }
1260
1261    fn fail(&self, event_error: Option<ValidationError>) -> Option<ValidationError> {
1262        let first_event_error = {
1263            let mut fatal_event = self
1264                .fatal_event
1265                .lock()
1266                .expect("event fatal latch lock poisoned");
1267            if !self.fatal.load(Ordering::Acquire) {
1268                *fatal_event = event_error;
1269                self.fatal.store(true, Ordering::Release);
1270            }
1271            *fatal_event
1272        };
1273        #[cfg(test)]
1274        self.pause_before_reject(FreezePoint::Fatal);
1275        self.reject_pending();
1276        self.interruption.cancel();
1277        self.cancel.cancel();
1278        first_event_error
1279    }
1280}
1281
1282pub(crate) struct Producer {
1283    sender: mpsc::UnboundedSender<Delivery>,
1284    control: Arc<Control>,
1285    serial: Mutex<()>,
1286}
1287
1288impl Producer {
1289    pub(crate) async fn emit_text(
1290        &self,
1291        kind: Kind,
1292        text: String,
1293        coord: Coord,
1294        item_id: Option<String>,
1295    ) -> Result<DeliveryOutcome, ValidationError> {
1296        self.emit(Event::driver_text(kind, text, coord, item_id), None)
1297            .await
1298    }
1299
1300    pub(crate) async fn emit_lifecycle(
1301        &self,
1302        kind: Kind,
1303        outcome: Option<Outcome>,
1304        coord: Coord,
1305    ) -> Result<DeliveryOutcome, ValidationError> {
1306        self.emit(Event::driver_lifecycle(kind, outcome, coord), None)
1307            .await
1308    }
1309
1310    pub(crate) async fn emit_input_admitted(
1311        &self,
1312        origin: InputOrigin,
1313        items: Vec<item::Item>,
1314        coord: Coord,
1315    ) -> Result<DeliveryOutcome, ValidationError> {
1316        self.emit(Event::driver_input_admitted(origin, items, coord), None)
1317            .await
1318    }
1319
1320    pub(crate) async fn emit_input_rejected(
1321        &self,
1322        reason: String,
1323        coord: Coord,
1324    ) -> Result<DeliveryOutcome, ValidationError> {
1325        self.emit(Event::driver_input_rejected(reason, coord), None)
1326            .await
1327    }
1328
1329    pub(crate) async fn emit_tool_call(
1330        &self,
1331        call: ToolCall,
1332        coord: Coord,
1333    ) -> Result<StrongDecision, ValidationError> {
1334        self.emit_strong(
1335            Event::driver_tool_call(call, coord),
1336            DecisionPoint::ToolCall,
1337        )
1338        .await
1339    }
1340
1341    pub(crate) async fn emit_tool_result(
1342        &self,
1343        result: item::ToolResult,
1344        coord: Coord,
1345    ) -> Result<StrongDecision, ValidationError> {
1346        self.emit_strong(
1347            Event::driver_tool_result(result, coord),
1348            DecisionPoint::ToolResult,
1349        )
1350        .await
1351    }
1352
1353    pub(crate) async fn emit_extension(
1354        &self,
1355        mut event: Event,
1356        coord: Coord,
1357    ) -> Result<DeliveryOutcome, ValidationError> {
1358        event.coord = Some(coord);
1359        self.emit(event, None).await
1360    }
1361
1362    pub(crate) async fn emit_after_tool_commit(
1363        &self,
1364        mut event: Event,
1365        coord: Coord,
1366    ) -> Result<StrongDecision, ValidationError> {
1367        event.coord = Some(coord);
1368        self.emit_strong(event, DecisionPoint::AfterToolCommit)
1369            .await
1370    }
1371
1372    pub(crate) async fn emit(
1373        &self,
1374        event: Event,
1375        decision_point: Option<DecisionPoint>,
1376    ) -> Result<DeliveryOutcome, ValidationError> {
1377        if let Some(decision_point) = decision_point {
1378            return self
1379                .emit_strong(event, decision_point)
1380                .await
1381                .map(Into::into);
1382        }
1383        let _serial = self.serial.lock().await;
1384        if self.control.interrupted() {
1385            return Ok(DeliveryOutcome::Rejected);
1386        }
1387        self.emit_locked(event, None)
1388            .await
1389            .map(|resolution| resolution.outward)
1390    }
1391
1392    async fn emit_strong(
1393        &self,
1394        event: Event,
1395        decision_point: DecisionPoint,
1396    ) -> Result<StrongDecision, ValidationError> {
1397        let _serial = self.serial.lock().await;
1398        if let Some(decision) = self.control.strong_interruption() {
1399            return Ok(decision);
1400        }
1401        Ok(self
1402            .emit_locked(event, Some(decision_point))
1403            .await?
1404            .strong
1405            .expect("a strong decision point always has a decision"))
1406    }
1407
1408    async fn emit_locked(
1409        &self,
1410        event: Event,
1411        decision_point: Option<DecisionPoint>,
1412    ) -> Result<DeliveryResolution, ValidationError> {
1413        if let Err(error) = event.validate(decision_point) {
1414            let _first_event_error = self.control.fail(Some(error));
1415            return Err(error);
1416        }
1417        let decision = decision_point.map(|_| {
1418            Arc::new(Decision {
1419                value: AtomicU8::new(PENDING),
1420                changed: Notify::new(),
1421                cancel: self.control.cancel.clone(),
1422                nonfatal: Arc::clone(&self.control.nonfatal),
1423                #[cfg(test)]
1424                after_pending_check: SyncMutex::new(None),
1425            })
1426        });
1427        let _pending = decision.as_ref().map(|decision| {
1428            self.control.register(decision);
1429            PendingDecision {
1430                control: &self.control,
1431                decision: Arc::clone(decision),
1432            }
1433        });
1434        let delivery = Delivery {
1435            event,
1436            decision_point,
1437            decision: decision.clone(),
1438        };
1439        // An unbounded lane accepts the delivery immediately, so the only two
1440        // reasons not to hand it over are that this Run is already interrupted
1441        // or that the consumer has dropped its stream. Cancellation is checked
1442        // first to keep the pre-existing precedence: an interrupted Run does not
1443        // publish, even when the consumer is still listening.
1444        let delivered = !self.control.cancel.is_cancelled() && self.sender.send(delivery).is_ok();
1445        let outcome = if let Some(decision) = &decision {
1446            if !delivered {
1447                let _already_decided = decision.abandon();
1448            }
1449            let decision = self.control.final_confirm_strong(decision.wait().await);
1450            #[cfg(test)]
1451            self.control.pause_after_final_confirm().await;
1452            DeliveryResolution::strong(decision)
1453        } else {
1454            DeliveryResolution::ordinary(if delivered {
1455                DeliveryOutcome::Delivered
1456            } else {
1457                DeliveryOutcome::Rejected
1458            })
1459        };
1460        Ok(outcome)
1461    }
1462
1463    pub(crate) async fn emit_stop(
1464        &self,
1465        code: StopCode,
1466        coord: Coord,
1467    ) -> Result<DeliveryOutcome, ValidationError> {
1468        if self.control.stop_emitted.swap(true, Ordering::AcqRel) {
1469            return Ok(DeliveryOutcome::Rejected);
1470        }
1471        self.control.latch_stop();
1472        let _serial = self.serial.lock().await;
1473        if self.control.cancel.is_cancelled() {
1474            return Ok(DeliveryOutcome::Rejected);
1475        }
1476        self.emit_locked(Event::driver_stop(code, coord), None)
1477            .await
1478            .map(|resolution| resolution.outward)
1479    }
1480}
1481
1482/// A restricted per-invocation emit failure.
1483#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1484#[non_exhaustive]
1485pub enum ToolEmitError {
1486    /// The invocation's emit window already closed.
1487    Closed,
1488    /// The event was not delivered to the outward consumer.
1489    Rejected,
1490    /// The supplied extension fact was invalid.
1491    Invalid(ValidationError),
1492}
1493
1494impl fmt::Display for ToolEmitError {
1495    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1496        match self {
1497            Self::Closed => formatter.write_str("tool invocation emit window is closed"),
1498            Self::Rejected => formatter.write_str("tool invocation event was not delivered"),
1499            Self::Invalid(error) => write!(formatter, "invalid tool invocation event: {error}"),
1500        }
1501    }
1502}
1503
1504impl Error for ToolEmitError {
1505    fn source(&self) -> Option<&(dyn Error + 'static)> {
1506        match self {
1507            Self::Invalid(error) => Some(error),
1508            Self::Closed | Self::Rejected => None,
1509        }
1510    }
1511}
1512
1513struct Outward {
1514    producer: Arc<Producer>,
1515    coord: Coord,
1516}
1517
1518enum EmitTarget {
1519    Closed,
1520    Open(Outward),
1521}
1522
1523struct EmitterState {
1524    target: EmitTarget,
1525    active: usize,
1526}
1527
1528struct ToolEmitterInner {
1529    state: SyncMutex<EmitterState>,
1530    idle: Notify,
1531    /// Holds one emission inside its open window until a test releases it.
1532    ///
1533    /// The outward lane is unbounded, so a real emission never stays in flight
1534    /// long enough for a test to observe the close/drain barrier it is supposed
1535    /// to cross. This is the same shape as the two `Control` pauses.
1536    #[cfg(test)]
1537    pause: SyncMutex<Option<Arc<TestEmitPause>>>,
1538}
1539
1540impl ToolEmitterInner {
1541    #[cfg(test)]
1542    async fn pause(&self) {
1543        let pause = self
1544            .pause
1545            .lock()
1546            .expect("tool emitter pause lock poisoned")
1547            .take();
1548        if let Some(pause) = pause {
1549            let _observer_may_be_gone = pause.reached.send(());
1550            pause
1551                .resume
1552                .acquire()
1553                .await
1554                .expect("tool emitter pause remains open")
1555                .forget();
1556        }
1557    }
1558
1559    fn enter(&self) -> Option<(ActiveEmit<'_>, Arc<Producer>, Coord)> {
1560        let mut state = self.state.lock().expect("tool emitter lock poisoned");
1561        match &state.target {
1562            EmitTarget::Closed => None,
1563            EmitTarget::Open(outward) => {
1564                let producer = Arc::clone(&outward.producer);
1565                let coord = outward.coord.clone();
1566                state.active += 1;
1567                Some((ActiveEmit { inner: self }, producer, coord))
1568            }
1569        }
1570    }
1571
1572    fn leave(&self) {
1573        let mut state = self.state.lock().expect("tool emitter lock poisoned");
1574        state.active -= 1;
1575        if state.active == 0 {
1576            self.idle.notify_waiters();
1577        }
1578    }
1579
1580    fn close(&self) {
1581        self.state
1582            .lock()
1583            .expect("tool emitter lock poisoned")
1584            .target = EmitTarget::Closed;
1585    }
1586
1587    async fn drain(&self) {
1588        loop {
1589            let idle = self.idle.notified();
1590            tokio::pin!(idle);
1591            let _already_ready = idle.as_mut().enable();
1592            if self
1593                .state
1594                .lock()
1595                .expect("tool emitter lock poisoned")
1596                .active
1597                == 0
1598            {
1599                return;
1600            }
1601            idle.await;
1602        }
1603    }
1604}
1605
1606/// Releases one in-flight emission even when the executor future is dropped.
1607struct ActiveEmit<'a> {
1608    inner: &'a ToolEmitterInner,
1609}
1610
1611impl Drop for ActiveEmit<'_> {
1612    fn drop(&mut self) {
1613        self.inner.leave();
1614    }
1615}
1616
1617/// The only emit capability handed to one tool invocation.
1618///
1619/// The typed constructors make loop-owned categories unrepresentable: an
1620/// executor cannot forge text, thinking, tool, lifecycle, or stop events, and it
1621/// cannot replay an [`Event`] observed from the outward stream. The runtime
1622/// stamps the call's [`Coord`], so neither producer authority nor outward event
1623/// state is ever reachable from an executor.
1624///
1625/// [`emit_audit`](Self::emit_audit) and [`emit_error`](Self::emit_error) are
1626/// async: each call is serialized with other outward emissions and returns once
1627/// the event is enqueued on the unbounded outward lane. Ordinary Audit/Error
1628/// delivery has no consumer acknowledgement; success means the stream remained
1629/// open for the enqueue. This differs from a hook scope's synchronous
1630/// `emit_audit` and `emit_error` methods, which queue locally and return
1631/// immediately because a synchronous callback cannot await.
1632/// Immediately after the paired invocation returns, the runtime closes this
1633/// window and every later call is a [`ToolEmitError::Closed`] no-op.
1634pub struct ToolEmitter {
1635    inner: Arc<ToolEmitterInner>,
1636}
1637
1638impl fmt::Debug for ToolEmitter {
1639    /// Prints the bare type name, which is the honest answer here.
1640    ///
1641    /// This is the one type in the crate with nothing to distinguish two live
1642    /// values by. Its entire state is an emitter-state machine behind a mutex
1643    /// and a `Notify`; whether the window is open changes under the reader's
1644    /// feet, and reporting it would describe a moment that has already passed.
1645    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1646        formatter.debug_struct("ToolEmitter").finish()
1647    }
1648}
1649
1650impl ToolEmitter {
1651    /// Creates an emitter that is already closed and carries no authority.
1652    ///
1653    /// Composition layers and tests that route a call outside a live run use
1654    /// this to satisfy the invocation contract; every emission is a
1655    /// [`ToolEmitError::Closed`] no-op.
1656    #[must_use]
1657    pub fn closed() -> Self {
1658        Self {
1659            inner: Arc::new(ToolEmitterInner {
1660                state: SyncMutex::new(EmitterState {
1661                    target: EmitTarget::Closed,
1662                    active: 0,
1663                }),
1664                idle: Notify::new(),
1665                #[cfg(test)]
1666                pause: SyncMutex::new(None),
1667            }),
1668        }
1669    }
1670
1671    /// Emits one non-model-visible audit fact.
1672    ///
1673    /// # Errors
1674    ///
1675    /// Returns [`ToolEmitError::Invalid`] for an empty audit kind,
1676    /// [`ToolEmitError::Closed`] after the invocation window closed, and
1677    /// [`ToolEmitError::Rejected`] when the outward stream closed before enqueue.
1678    ///
1679    /// # Panics
1680    ///
1681    /// If the lock guarding the invocation's emit window is poisoned, per the
1682    /// crate-level [lock-poisoning contract](crate#lock-poisoning).
1683    pub async fn emit_audit(&self, audit: audit::Event) -> Result<(), ToolEmitError> {
1684        let event = Event::from_audit(audit).map_err(ToolEmitError::Invalid)?;
1685        self.emit_extension(event).await
1686    }
1687
1688    /// Emits one recoverable, non-fatal degradation notice.
1689    ///
1690    /// # Errors
1691    ///
1692    /// Returns [`ToolEmitError::Closed`] after the invocation window closed and
1693    /// [`ToolEmitError::Rejected`] when the outward stream closed before enqueue.
1694    ///
1695    /// # Panics
1696    ///
1697    /// If the lock guarding the invocation's emit window is poisoned, per the
1698    /// crate-level [lock-poisoning contract](crate#lock-poisoning).
1699    pub async fn emit_error(
1700        &self,
1701        error: Arc<dyn Error + Send + Sync>,
1702    ) -> Result<(), ToolEmitError> {
1703        self.emit_extension(Event::from_error(error)).await
1704    }
1705
1706    async fn emit_extension(&self, event: Event) -> Result<(), ToolEmitError> {
1707        let Some((_active, producer, coord)) = self.inner.enter() else {
1708            return Err(ToolEmitError::Closed);
1709        };
1710        #[cfg(test)]
1711        self.inner.pause().await;
1712        let outcome = producer.emit_extension(event, coord).await;
1713        // Both public constructors pre-validate, so the producer's fatal
1714        // validation lane is unreachable here and non-delivery is the only
1715        // remaining failure fact.
1716        if matches!(outcome, Ok(DeliveryOutcome::Delivered)) {
1717            Ok(())
1718        } else {
1719            Err(ToolEmitError::Rejected)
1720        }
1721    }
1722}
1723
1724/// The runtime-owned close side of one invocation's emit window.
1725pub(crate) struct ToolEmitterGate {
1726    inner: Arc<ToolEmitterInner>,
1727}
1728
1729impl ToolEmitterGate {
1730    /// Closes the window, then waits for every already-active emission.
1731    pub(crate) async fn close_and_wait(self) {
1732        self.inner.close();
1733        self.inner.drain().await;
1734    }
1735}
1736
1737/// Mints one invocation-scoped emitter and its runtime-owned close gate.
1738pub(crate) fn tool_emitter(
1739    producer: &Arc<Producer>,
1740    coord: Coord,
1741) -> (ToolEmitter, ToolEmitterGate) {
1742    let inner = Arc::new(ToolEmitterInner {
1743        state: SyncMutex::new(EmitterState {
1744            target: EmitTarget::Open(Outward {
1745                producer: Arc::clone(producer),
1746                coord,
1747            }),
1748            active: 0,
1749        }),
1750        idle: Notify::new(),
1751        #[cfg(test)]
1752        pause: SyncMutex::new(None),
1753    });
1754    (
1755        ToolEmitter {
1756            inner: Arc::clone(&inner),
1757        },
1758        ToolEmitterGate { inner },
1759    )
1760}
1761
1762pub(crate) struct EventSource {
1763    stream: Option<Stream>,
1764    control: Arc<Control>,
1765}
1766
1767#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1768pub(crate) struct StreamTakenError;
1769
1770impl EventSource {
1771    pub(crate) fn take_stream(&mut self) -> Result<Stream, StreamTakenError> {
1772        self.stream.take().ok_or(StreamTakenError)
1773    }
1774
1775    pub(crate) fn request_stop(&self) {
1776        self.control.request_stop();
1777    }
1778
1779    pub(crate) fn terminal_intent(&self) -> TerminalIntent {
1780        self.control.intent()
1781    }
1782
1783    /// Resolves when outward control stops or fails the run.
1784    ///
1785    /// This signal is deliberately independent of the parent-derived cancellation
1786    /// token. Consumer drop must wake the Driver even though it cannot cancel the
1787    /// parent, while explicit parent cancellation stays on the Driver's normal
1788    /// cancellation path so already-durable facts and real fatal errors retain
1789    /// their established priority.
1790    pub(crate) async fn interruption(&self) {
1791        self.control.interruption.cancelled().await;
1792    }
1793
1794    pub(crate) fn latch_failure(&self) -> Option<ValidationError> {
1795        self.control.fail(None)
1796    }
1797
1798    #[cfg(test)]
1799    fn state(&self) -> (bool, bool, bool) {
1800        (
1801            self.control.nonfatal.frozen() == NONFATAL_STOPPED,
1802            self.control.fatal.load(Ordering::Acquire),
1803            self.control.cancel.is_cancelled(),
1804        )
1805    }
1806}
1807
1808/// Creates the outward lane for one Run.
1809///
1810/// The lane is unbounded on purpose. Every blocking boundary Reef has is an
1811/// explicit acknowledgement — the three strong seams wait on their own
1812/// [`Decision`], not on buffer space — so letting a full buffer also stall the
1813/// loop would make delivery latency a second, invisible flow-control mechanism.
1814/// With an unbounded lane a slow or inattentive consumer can never wedge a Run:
1815/// the only way a send fails is that the consumer dropped its stream, which is
1816/// that consumer stating it wants nothing further.
1817pub(crate) fn channel(parent: &Token) -> (Arc<Producer>, EventSource) {
1818    let (sender, receiver) = mpsc::unbounded_channel();
1819    let nonfatal = Arc::new(NonfatalCause {
1820        parent: parent.clone(),
1821        cause: SyncMutex::new(NONFATAL_NONE),
1822    });
1823    let control = Arc::new(Control {
1824        nonfatal,
1825        fatal: AtomicBool::new(false),
1826        fatal_event: SyncMutex::new(None),
1827        stop_emitted: AtomicBool::new(false),
1828        pending: SyncMutex::new(None),
1829        cancel: parent.child_token(),
1830        interruption: Token::new(),
1831        #[cfg(test)]
1832        before_reject_pause: SyncMutex::new(None),
1833        #[cfg(test)]
1834        after_final_confirm_pause: SyncMutex::new(None),
1835    });
1836    let producer = Arc::new(Producer {
1837        sender,
1838        control: control.clone(),
1839        serial: Mutex::new(()),
1840    });
1841    let stream = Stream {
1842        receiver,
1843        control: control.clone(),
1844    };
1845    (
1846        producer,
1847        EventSource {
1848            stream: Some(stream),
1849            control,
1850        },
1851    )
1852}
1853
1854#[cfg(test)]
1855pub(crate) mod testing {
1856    use super::*;
1857
1858    /// The runtime path that publishes one event category.
1859    ///
1860    /// This exists so that "which variants can a consumer actually see" is a
1861    /// value rather than a comment. Nothing in the crate reads it to make a
1862    /// decision; it is read by
1863    /// `driver_tests::every_event_kind_reaches_a_consumer_from_a_real_run`.
1864    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
1865    pub(crate) enum Emission {
1866        /// [`Producer::emit_text`], from streamed or consolidated content.
1867        Content,
1868        /// [`Producer::emit_lifecycle`], from a Turn, Step or Generation boundary.
1869        Lifecycle,
1870        /// [`Producer::emit_tool_call`], at the `ToolCall` strong decision point.
1871        ToolCall,
1872        /// [`Producer::emit_tool_result`], at the `ToolResult` strong decision point.
1873        ToolResult,
1874        /// [`ToolEmitter`], the only extension-owned emission authority.
1875        Extension,
1876        /// [`Producer::emit_stop`], the single privately owned `EventStop`.
1877        Stop,
1878        /// [`Producer::emit_input_admitted`]/[`Producer::emit_input_rejected`],
1879        /// the loop's two statements about a claimed or composed input batch.
1880        Input,
1881    }
1882
1883    /// The runtime path that publishes `kind`.
1884    ///
1885    /// Exhaustive with no wildcard arm on purpose. Adding a variant to [`Kind`]
1886    /// stops the crate compiling here, and the compiler error lands on the one
1887    /// list a new variant has to join — [`ALL_KINDS`] is immediately below it.
1888    /// Once the variant is in that list,
1889    /// `every_event_kind_reaches_a_consumer_from_a_real_run` requires a real
1890    /// [`Driver`] run to publish it, so a variant cannot be declared without
1891    /// being wired.
1892    ///
1893    /// Rust has no stable way to enumerate an enum's variants, so the list itself
1894    /// is written by hand; what is mechanical is that the list cannot be reached
1895    /// without a compiler error first, and cannot be satisfied afterwards without
1896    /// a production emitter.
1897    ///
1898    /// [`Driver`]: crate::runtime::driver::Driver
1899    pub(crate) const fn emission(kind: Kind) -> Emission {
1900        match kind {
1901            Kind::TextDelta | Kind::Text | Kind::ThinkingDelta | Kind::Thinking => {
1902                Emission::Content
1903            }
1904            Kind::TurnStart
1905            | Kind::TurnEnd
1906            | Kind::StepStart
1907            | Kind::StepEnd
1908            | Kind::GenerationEnd => Emission::Lifecycle,
1909            Kind::ToolCall => Emission::ToolCall,
1910            Kind::ToolResult => Emission::ToolResult,
1911            Kind::Audit | Kind::Error => Emission::Extension,
1912            Kind::Stop => Emission::Stop,
1913            Kind::InputAdmitted | Kind::InputRejected => Emission::Input,
1914        }
1915    }
1916
1917    /// Every event category a consumer can observe.
1918    pub(crate) const ALL_KINDS: &[Kind] = &[
1919        Kind::TextDelta,
1920        Kind::Text,
1921        Kind::ThinkingDelta,
1922        Kind::Thinking,
1923        Kind::TurnStart,
1924        Kind::TurnEnd,
1925        Kind::StepStart,
1926        Kind::StepEnd,
1927        Kind::GenerationEnd,
1928        Kind::ToolCall,
1929        Kind::ToolResult,
1930        Kind::Error,
1931        Kind::Audit,
1932        Kind::Stop,
1933        Kind::InputAdmitted,
1934        Kind::InputRejected,
1935    ];
1936
1937    pub(crate) fn text(kind: Kind, text: &str, coord: Coord) -> Event {
1938        Event::driver_text(kind, text.into(), coord, None)
1939    }
1940
1941    pub(crate) fn lifecycle(kind: Kind, outcome: Option<Outcome>, coord: Coord) -> Event {
1942        Event::driver_lifecycle(kind, outcome, coord)
1943    }
1944
1945    pub(crate) fn tool_call(call: ToolCall, coord: Coord) -> Event {
1946        Event::driver_tool_call(call, coord)
1947    }
1948
1949    pub(crate) fn tool_result(result: item::ToolResult, coord: Coord) -> Event {
1950        Event::driver_tool_result(result, coord)
1951    }
1952
1953    pub(crate) fn stop(code: StopCode, coord: Coord) -> Event {
1954        Event::driver_stop(code, coord)
1955    }
1956
1957    pub(crate) fn input_admitted(
1958        origin: InputOrigin,
1959        items: Vec<item::Item>,
1960        coord: Coord,
1961    ) -> Event {
1962        Event::driver_input_admitted(origin, items, coord)
1963    }
1964
1965    pub(crate) fn input_rejected(reason: String, coord: Coord) -> Event {
1966        Event::driver_input_rejected(reason, coord)
1967    }
1968
1969    pub(crate) fn forged(kind: Kind, event: Event) -> Event {
1970        Event { kind, ..event }
1971    }
1972
1973    pub(crate) fn invalid_audit(coord: Coord) -> Event {
1974        Event {
1975            kind: Kind::Audit,
1976            coord: Some(coord),
1977            item_id: None,
1978            payload: Payload::Audit(audit::Event::new(String::new(), None)),
1979        }
1980    }
1981
1982    pub(crate) fn invalid_stop(coord: Coord) -> Event {
1983        Event {
1984            kind: Kind::Stop,
1985            coord: Some(coord),
1986            item_id: None,
1987            payload: Payload::Stop(StopCode(String::new())),
1988        }
1989    }
1990
1991    pub(crate) fn control(source: &EventSource) -> (bool, bool, bool) {
1992        source.state()
1993    }
1994
1995    pub(crate) use super::FreezePoint;
1996
1997    #[derive(Clone)]
1998    pub(crate) struct InterruptionProbe(Arc<Control>);
1999
2000    impl InterruptionProbe {
2001        pub(crate) fn request_stop(&self) {
2002            self.0.request_stop();
2003        }
2004
2005        pub(crate) fn fail(&self) {
2006            let _first_event_error = self.0.fail(Some(ValidationError::PayloadMismatch));
2007        }
2008    }
2009
2010    pub(crate) fn interruption_probe(source: &EventSource) -> InterruptionProbe {
2011        InterruptionProbe(Arc::clone(&source.control))
2012    }
2013
2014    pub(crate) struct FreezePauseProbe {
2015        reached: Arc<std::sync::Barrier>,
2016        resume: Arc<std::sync::Barrier>,
2017    }
2018
2019    impl FreezePauseProbe {
2020        pub(crate) fn wait_until_frozen(&self) {
2021            self.reached.wait();
2022        }
2023
2024        pub(crate) fn resume_rejection(&self) {
2025            self.resume.wait();
2026        }
2027    }
2028
2029    pub(crate) fn pause_before_reject(
2030        source: &EventSource,
2031        point: FreezePoint,
2032    ) -> (InterruptionProbe, FreezePauseProbe) {
2033        let reached = Arc::new(std::sync::Barrier::new(2));
2034        let resume = Arc::new(std::sync::Barrier::new(2));
2035        *source
2036            .control
2037            .before_reject_pause
2038            .lock()
2039            .expect("event freeze pause lock poisoned") = Some(TestFreezePause {
2040            point,
2041            reached: Arc::clone(&reached),
2042            resume: Arc::clone(&resume),
2043        });
2044        (
2045            interruption_probe(source),
2046            FreezePauseProbe { reached, resume },
2047        )
2048    }
2049
2050    pub(crate) struct FinalConfirmPauseProbe(Arc<TestFinalConfirmPause>);
2051
2052    impl FinalConfirmPauseProbe {
2053        pub(crate) async fn wait_until_confirmed(&self) {
2054            self.0
2055                .reached
2056                .acquire()
2057                .await
2058                .expect("event final-confirm pause remains open")
2059                .forget();
2060        }
2061
2062        pub(crate) fn resume_return(&self) {
2063            self.0.resume.add_permits(1);
2064        }
2065    }
2066
2067    pub(crate) fn pause_after_final_confirm(source: &EventSource) -> FinalConfirmPauseProbe {
2068        let pause = Arc::new(TestFinalConfirmPause {
2069            reached: Semaphore::new(0),
2070            resume: Semaphore::new(0),
2071        });
2072        *source
2073            .control
2074            .after_final_confirm_pause
2075            .lock()
2076            .expect("event final-confirm pause lock poisoned") = Some(Arc::clone(&pause));
2077        FinalConfirmPauseProbe(pause)
2078    }
2079
2080    pub(crate) fn intent(source: &EventSource) -> TerminalIntent {
2081        source.terminal_intent()
2082    }
2083
2084    pub(crate) fn has_pending_strong_decision(source: &EventSource) -> bool {
2085        source
2086            .control
2087            .pending
2088            .lock()
2089            .expect("event pending lock poisoned")
2090            .is_some()
2091    }
2092
2093    pub(crate) fn stale_pending_guard_preserves_successor(source: &EventSource) -> (bool, bool) {
2094        let decision = || {
2095            Arc::new(Decision {
2096                value: AtomicU8::new(PENDING),
2097                changed: Notify::new(),
2098                cancel: source.control.cancel.clone(),
2099                nonfatal: Arc::clone(&source.control.nonfatal),
2100                after_pending_check: SyncMutex::new(None),
2101            })
2102        };
2103        let stale = decision();
2104        source.control.register(&stale);
2105        let stale_guard = PendingDecision {
2106            control: &source.control,
2107            decision: Arc::clone(&stale),
2108        };
2109        let successor = decision();
2110        source.control.register(&successor);
2111
2112        drop(stale_guard);
2113        let successor_preserved = source
2114            .control
2115            .pending
2116            .lock()
2117            .expect("event pending lock poisoned")
2118            .as_ref()
2119            .is_some_and(|pending| Arc::ptr_eq(pending, &successor));
2120        let stale_abandoned = stale.decide(ACCEPTED) == Err(DecisionError::AlreadyDecided);
2121        source.control.reject_pending();
2122        (successor_preserved, stale_abandoned)
2123    }
2124
2125    #[derive(Clone)]
2126    pub(crate) struct EmitterProbe(Arc<ToolEmitterInner>);
2127
2128    impl EmitterProbe {
2129        pub(crate) fn state(&self) -> (bool, usize) {
2130            let state = self.0.state.lock().expect("tool emitter lock poisoned");
2131            (matches!(state.target, EmitTarget::Closed), state.active)
2132        }
2133    }
2134
2135    pub(crate) fn emitter_probe(emitter: &ToolEmitter) -> EmitterProbe {
2136        EmitterProbe(Arc::clone(&emitter.inner))
2137    }
2138
2139    /// Holds one emission open inside its window until the test releases it.
2140    #[derive(Clone)]
2141    pub(crate) struct EmitPauseProbe(Arc<TestEmitPause>);
2142
2143    impl EmitPauseProbe {
2144        /// Announces the held emission on `reached` once it is inside the window.
2145        pub(crate) fn new(reached: std::sync::mpsc::Sender<()>) -> Self {
2146            Self(Arc::new(TestEmitPause {
2147                reached,
2148                resume: Semaphore::new(0),
2149            }))
2150        }
2151
2152        /// Arms this pause for the emitter's next emission only.
2153        pub(crate) fn arm(&self, emitter: &ToolEmitter) {
2154            *emitter
2155                .inner
2156                .pause
2157                .lock()
2158                .expect("tool emitter pause lock poisoned") = Some(Arc::clone(&self.0));
2159        }
2160
2161        pub(crate) fn resume(&self) {
2162            self.0.resume.add_permits(1);
2163        }
2164    }
2165
2166    /// Cancels the Run-local token without latching a nonfatal cause.
2167    ///
2168    /// Every public route into this state latches the cause first, which makes
2169    /// the outward hand-over's own cancellation check unobservable from outside.
2170    /// That check is the last thing standing between a cancelled Run and a
2171    /// published event, so it is worth pinning rather than assuming.
2172    pub(crate) fn cancel_lane(source: &EventSource) {
2173        source.control.cancel.cancel();
2174    }
2175
2176    pub(crate) fn fail(source: &EventSource) {
2177        let _first_event_error = source.control.fail(Some(ValidationError::PayloadMismatch));
2178    }
2179
2180    #[derive(Clone)]
2181    pub(crate) struct DecisionProbe(Arc<Decision>);
2182
2183    impl DecisionProbe {
2184        pub(crate) fn plain(cancel: Token) -> Self {
2185            let nonfatal = Arc::new(NonfatalCause {
2186                parent: cancel.clone(),
2187                cause: SyncMutex::new(NONFATAL_NONE),
2188            });
2189            Self(Arc::new(Decision {
2190                value: AtomicU8::new(PENDING),
2191                changed: Notify::new(),
2192                cancel,
2193                nonfatal,
2194                after_pending_check: SyncMutex::new(None),
2195            }))
2196        }
2197
2198        pub(crate) fn paused_after_pending_check(
2199            cancel: Token,
2200        ) -> (Self, Arc<std::sync::Barrier>, Arc<std::sync::Barrier>) {
2201            let checked = Arc::new(std::sync::Barrier::new(2));
2202            let resume = Arc::new(std::sync::Barrier::new(2));
2203            let nonfatal = Arc::new(NonfatalCause {
2204                parent: cancel.clone(),
2205                cause: SyncMutex::new(NONFATAL_NONE),
2206            });
2207            let decision = Arc::new(Decision {
2208                value: AtomicU8::new(PENDING),
2209                changed: Notify::new(),
2210                cancel,
2211                nonfatal,
2212                after_pending_check: SyncMutex::new(Some(WaitBarriers {
2213                    checked: checked.clone(),
2214                    resume: resume.clone(),
2215                })),
2216            });
2217            (Self(decision), checked, resume)
2218        }
2219
2220        pub(crate) fn accept(&self) -> Result<(), DecisionError> {
2221            self.0.decide_consumer(ACCEPTED)
2222        }
2223
2224        pub(crate) fn reject(&self) -> Result<(), DecisionError> {
2225            self.0.decide_consumer(REJECTED)
2226        }
2227
2228        pub(crate) async fn wait(&self) -> StrongDecision {
2229            self.0.wait().await
2230        }
2231    }
2232
2233    pub(crate) fn register_probe(source: &EventSource) -> bool {
2234        let decision = DecisionProbe::plain(source.control.cancel.clone()).0;
2235        source.control.register(&decision);
2236        decision.value.load(Ordering::Acquire) == REJECTED
2237    }
2238
2239    /// Observes one emitter's in-flight emission count so concurrency tests can
2240    /// wait on real state instead of task-scheduling luck.
2241    pub(crate) fn tool_emitter_active(emitter: &ToolEmitter) -> usize {
2242        emitter
2243            .inner
2244            .state
2245            .lock()
2246            .expect("tool emitter lock poisoned")
2247            .active
2248    }
2249}
2250
2251/// The serialized form of [`Kind`] (ADR-019 D5).
2252///
2253/// A kind travels as its own tag and nothing else. [`Event`] itself is not
2254/// serializable and cannot be: its private payload carries an
2255/// `Arc<dyn Error + Send + Sync>`, and its loop-owned variants have no public
2256/// constructors. So a serialized `Kind` is the tag a lifecycle record carries,
2257/// not a protocol, and nothing here should be read as delivering one.
2258///
2259/// `Kind` is `#[non_exhaustive]`, but its serialized form carries no schema
2260/// version. Compatibility is content-driven: an unknown tag on ingress is an
2261/// error rather than a fallback variant, while a recognized tag is not rejected
2262/// merely because a different reef version wrote it.
2263#[cfg(feature = "serde")]
2264mod serde_impl {
2265    use std::fmt::{self, Formatter};
2266
2267    use serde_core::de::{
2268        Deserialize, Deserializer, EnumAccess, Error as DeError, VariantAccess, Visitor,
2269    };
2270    use serde_core::ser::{Serialize, Serializer};
2271
2272    use super::Kind;
2273    use crate::wire::IdentifierSeed;
2274
2275    const NAME: &str = "Kind";
2276    const VARIANTS: &[&str] = &[
2277        "text_delta",
2278        "text",
2279        "thinking_delta",
2280        "thinking",
2281        "turn_start",
2282        "turn_end",
2283        "step_start",
2284        "step_end",
2285        "generation_end",
2286        "tool_call",
2287        "tool_result",
2288        "error",
2289        "audit",
2290        "stop",
2291        "input_admitted",
2292        "input_rejected",
2293    ];
2294
2295    impl Serialize for Kind {
2296        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
2297        where
2298            S: Serializer,
2299        {
2300            let (index, tag) = match self {
2301                Self::TextDelta => (0, "text_delta"),
2302                Self::Text => (1, "text"),
2303                Self::ThinkingDelta => (2, "thinking_delta"),
2304                Self::Thinking => (3, "thinking"),
2305                Self::TurnStart => (4, "turn_start"),
2306                Self::TurnEnd => (5, "turn_end"),
2307                Self::StepStart => (6, "step_start"),
2308                Self::StepEnd => (7, "step_end"),
2309                Self::GenerationEnd => (8, "generation_end"),
2310                Self::ToolCall => (9, "tool_call"),
2311                Self::ToolResult => (10, "tool_result"),
2312                Self::Error => (11, "error"),
2313                Self::Audit => (12, "audit"),
2314                Self::Stop => (13, "stop"),
2315                Self::InputAdmitted => (14, "input_admitted"),
2316                Self::InputRejected => (15, "input_rejected"),
2317            };
2318            serializer.serialize_unit_variant(NAME, index, tag)
2319        }
2320    }
2321
2322    impl<'de> Deserialize<'de> for Kind {
2323        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
2324        where
2325            D: Deserializer<'de>,
2326        {
2327            deserializer.deserialize_enum(NAME, VARIANTS, KindVisitor)
2328        }
2329    }
2330
2331    struct KindVisitor;
2332
2333    impl<'de> Visitor<'de> for KindVisitor {
2334        type Value = Kind;
2335
2336        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
2337            formatter.write_str("an outward event kind")
2338        }
2339
2340        fn visit_enum<A>(self, data: A) -> Result<Self::Value, A::Error>
2341        where
2342            A: EnumAccess<'de>,
2343        {
2344            let (tag, variant) = data.variant_seed(IdentifierSeed(VARIANTS))?;
2345            variant.unit_variant()?;
2346            match tag.0.as_str() {
2347                "text_delta" => Ok(Kind::TextDelta),
2348                "text" => Ok(Kind::Text),
2349                "thinking_delta" => Ok(Kind::ThinkingDelta),
2350                "thinking" => Ok(Kind::Thinking),
2351                "turn_start" => Ok(Kind::TurnStart),
2352                "turn_end" => Ok(Kind::TurnEnd),
2353                "step_start" => Ok(Kind::StepStart),
2354                "step_end" => Ok(Kind::StepEnd),
2355                "generation_end" => Ok(Kind::GenerationEnd),
2356                "tool_call" => Ok(Kind::ToolCall),
2357                "tool_result" => Ok(Kind::ToolResult),
2358                "error" => Ok(Kind::Error),
2359                "audit" => Ok(Kind::Audit),
2360                "stop" => Ok(Kind::Stop),
2361                "input_admitted" => Ok(Kind::InputAdmitted),
2362                "input_rejected" => Ok(Kind::InputRejected),
2363                unknown => Err(A::Error::unknown_variant(unknown, VARIANTS)),
2364            }
2365        }
2366    }
2367}