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