Skip to main content

decl_lang/
phase_events.rs

1//! Bounded, opt-in phase breadcrumbs which survive an interrupted evaluation.
2//!
3//! A caller supplies one empty, regular file and keeps its [`SinkGuard`] on the
4//! evaluation thread. Each publication writes one fixed record directly, without
5//! formatting, allocation-ledger access, or retained runtime values. This is
6//! diagnostic I/O, not a source of uncontaminated latency measurements. Successful
7//! writes reach the kernel; this module does not provide host-crash durability.
8//!
9//! Every record is [`RECORD_SIZE`] bytes, encoded little-endian: magic (0..8),
10//! schema u16 (8..10), kind u8 (10), outcome u8 (11), stage u32 (12..16), sequence
11//! u64 (16..24), monotonic ns u64 (24..32), span u64 (32..40), parent u64 (40..48),
12//! ordinal u64 (48..56), root hash u64 (56..64), root UTF-8 length u64 (64..72),
13//! installation generation u64 (72..80), process ID u32 (80..84), errno i32
14//! (84..88), root kind u8 (88), stop reason u8 (89), two zero bytes (90..92), and
15//! open-scope depth u32 (92..96). Header ordinal holds the record limit instead.
16//! Stages are caller-defined IDs whose dictionary must accompany the file.
17//!
18//! A complete prefix confirms published boundaries only. It cannot identify the
19//! exact instruction at process termination. Missing terminal records, partial
20//! tails, and reported publication failures must remain distinguishable from a
21//! successfully closed stream. The final record slot is reserved for a terminal.
22
23use serde::Serialize;
24use std::cell::Cell;
25use std::fs::File;
26use std::io::{Seek, SeekFrom};
27use std::marker::PhantomData;
28use std::os::fd::AsRawFd;
29use std::rc::Rc;
30use std::sync::atomic::{AtomicU64, Ordering};
31
32/// Magic bytes repeated at the start of every record.
33pub const MAGIC: [u8; 8] = *b"DCLPHEV1";
34/// Version of the fixed little-endian record layout.
35pub const SCHEMA_VERSION: u16 = 1;
36/// Bytes per record, including its schema and magic.
37pub const RECORD_SIZE: usize = 96;
38/// Hard limit including the header and reserved terminal: at most 1.5 MiB.
39pub const MAX_RECORDS: u64 = 16_384;
40const EINTR_RETRIES: u32 = 3;
41
42/// Wire record category.
43#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
44#[repr(u8)]
45pub enum EventKind {
46    /// Installation header; its ordinal contains the configured record limit.
47    Header = 1,
48    /// Explicit entry into a new, uniquely numbered nested attempt.
49    Enter = 2,
50    /// Explicit start of a new stage within an existing attempt.
51    Transition = 3,
52    /// End of a scope; the outcome describes how it ended.
53    End = 4,
54    /// Last record of a closed or intentionally truncated stream.
55    Terminal = 5,
56}
57
58/// Caller outcome or guard/stream termination classification.
59#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
60#[repr(u8)]
61pub enum Outcome {
62    /// No ending outcome applies to this event.
63    None = 0,
64    /// Caller explicitly completed the scope, or explicitly closed the sink.
65    Ok = 1,
66    /// Caller reported deferred work.
67    Defer = 2,
68    /// Caller reported a tainted result.
69    Taint = 3,
70    /// Caller reported an evaluation failure.
71    Eval = 4,
72    /// Caller rejected the attempted operation.
73    Rejected = 5,
74    /// A scope was dropped without an explicit outcome.
75    Incomplete = 6,
76    /// A scope or sink ended while its thread was unwinding.
77    Unwound = 7,
78    /// The configured record limit ended publication.
79    Truncated = 8,
80    /// A sink was dropped without explicit closure.
81    Abandoned = 9,
82}
83
84/// Origin category for a root's scalar identity.
85#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
86#[repr(u8)]
87pub enum RootKind {
88    /// No root identity was supplied.
89    Unknown = 0,
90    /// Root production evaluates a source expression.
91    Expression = 1,
92    /// Root production binds a supplied document.
93    Document = 2,
94}
95
96/// Scalar root label, with no borrowed text or runtime ownership.
97#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
98pub struct RootIdentity {
99    /// FNV-1a 64-bit hash of the UTF-8 name; not a collision-free identifier.
100    pub hash: u64,
101    /// Number of UTF-8 bytes hashed.
102    pub utf8_len: u64,
103    /// Expression, document, or unspecified origin.
104    pub kind: RootKind,
105}
106impl RootIdentity {
107    /// Unspecified root. An actual empty name instead has the FNV offset hash.
108    pub const NONE: Self = Self {
109        hash: 0,
110        utf8_len: 0,
111        kind: RootKind::Unknown,
112    };
113
114    /// Hash a name without retaining it or allocating; dictionaries must check
115    /// collisions before treating hash and byte length as exact name identity.
116    pub fn new(name: &str, kind: RootKind) -> Self {
117        let mut hash = 14_695_981_039_346_656_037_u64;
118        for byte in name.bytes() {
119            hash ^= u64::from(byte);
120            hash = hash.wrapping_mul(1_099_511_628_211);
121        }
122        Self {
123            hash,
124            utf8_len: name.len() as u64,
125            kind,
126        }
127    }
128}
129
130/// First reason publication was disabled; language evaluation is unaffected.
131#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
132#[repr(u8)]
133pub enum StopReason {
134    /// No telemetry failure; an explicit terminal may still have closed it.
135    None = 0,
136    /// The bounded stream used its reserved terminal slot.
137    Cap = 1,
138    /// The monotonic clock failed, overflowed, or moved backwards.
139    Clock = 2,
140    /// A write failed with an error other than an exhausted EINTR allowance.
141    Write = 3,
142    /// A write produced fewer bytes than one complete record.
143    ShortWrite = 4,
144    /// EINTR persisted beyond the bounded retry allowance.
145    Interrupted = 5,
146    /// A scope transitioned or ended while another scope was current.
147    ScopeOrder = 6,
148    /// Publication was recursively attempted while already publishing.
149    Reentrant = 7,
150    /// The sink guard was dropped without explicit closure.
151    Abandoned = 8,
152    /// Explicit sink closure occurred with scopes still open.
153    OpenScopes = 9,
154    /// A sequence, scope ID, or depth counter could not be advanced safely.
155    CounterOverflow = 10,
156}
157
158/// Scalar snapshot of one installation, serializable after measured work.
159#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
160pub struct Status {
161    /// Unique process-local installation ID, also carried in every record.
162    pub generation: u64,
163    /// Configured count including header and terminal.
164    pub max_records: u64,
165    /// Complete records successfully written; failed partial tails are excluded.
166    pub records_written: u64,
167    /// Actual bytes written, including any partial final record.
168    pub bytes_written: u64,
169    /// Last successfully written sequence, zero before the header succeeds.
170    pub last_sequence: u64,
171    /// Most recently published monotonic clock sample, or zero initially.
172    pub last_monotonic_ns: u64,
173    /// Whether another nonterminal publication is currently allowed.
174    pub enabled: bool,
175    /// Whether a complete terminal record was successfully written.
176    pub terminal_written: bool,
177    /// Open scopes at the last successful structural boundary.
178    pub open_scopes: u32,
179    /// Reason publication stopped; a failed terminal reports its publication
180    /// failure instead of the intended cap, abandonment, or open-scope reason.
181    pub stop_reason: StopReason,
182    /// OS error associated with a clock or write failure, otherwise zero.
183    pub errno: i32,
184}
185
186/// Installation failure before an owning sink guard can be returned.
187#[derive(Clone, Copy, Debug, Eq, PartialEq)]
188pub enum InstallError {
189    /// The requested count is outside 2..=MAX_RECORDS.
190    InvalidLimit,
191    /// This thread already has an installed sink, including a disabled one.
192    AlreadyInstalled,
193    /// Installation was attempted recursively during publication.
194    Busy,
195    /// Thread-local state was no longer accessible.
196    ThreadUnavailable,
197    /// The supplied file was not an empty regular file.
198    NotEmptyRegularFile,
199    /// File metadata or initial seeking failed with this OS error.
200    File(i32),
201    /// All process-local installation IDs were consumed.
202    GenerationExhausted,
203}
204
205#[derive(Clone, Copy)]
206struct Payload {
207    kind: EventKind,
208    outcome: Outcome,
209    stage: u32,
210    span: u64,
211    parent: u64,
212    ordinal: u64,
213    root: RootIdentity,
214    depth: u32,
215}
216#[derive(Clone, Copy)]
217struct State {
218    fd: i32,
219    pid: u32,
220    status: Status,
221    next_span: u64,
222    current_span: u64,
223}
224struct Local {
225    state: Cell<Option<State>>,
226    busy: Cell<bool>,
227    reentered: Cell<bool>,
228}
229thread_local! {
230    static LOCAL: Local = const { Local {
231        state: Cell::new(None), busy: Cell::new(false), reentered: Cell::new(false),
232    } };
233}
234static NEXT_GENERATION: AtomicU64 = AtomicU64::new(1);
235
236fn os_errno() -> i32 {
237    std::io::Error::last_os_error().raw_os_error().unwrap_or(0)
238}
239fn clock_ns() -> Result<u64, i32> {
240    #[cfg(test)]
241    if test_io::clock_fails() {
242        return Err(libc::EIO);
243    }
244    let mut ts = libc::timespec {
245        tv_sec: 0,
246        tv_nsec: 0,
247    };
248    // SAFETY: writable local timespec and the supported monotonic clock ID.
249    if unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut ts) } != 0 {
250        return Err(os_errno());
251    }
252    if ts.tv_sec < 0 || ts.tv_nsec < 0 || ts.tv_nsec >= 1_000_000_000 {
253        return Err(0);
254    }
255    (ts.tv_sec as u64)
256        .checked_mul(1_000_000_000)
257        .and_then(|v| v.checked_add(ts.tv_nsec as u64))
258        .ok_or(0)
259}
260fn write_record(fd: i32, record: &[u8; RECORD_SIZE]) -> Result<usize, i32> {
261    #[cfg(test)]
262    if let Some(result) = test_io::intercept(fd, record) {
263        return result;
264    }
265    // SAFETY: the owning !Send SinkGuard keeps this descriptor open on this
266    // thread. No user callback runs while this local byte array is borrowed.
267    let written = unsafe { libc::write(fd, record.as_ptr().cast(), RECORD_SIZE) };
268    if written < 0 {
269        Err(os_errno())
270    } else {
271        Ok(written as usize)
272    }
273}
274fn encode(state: &State, p: Payload, time: u64) -> [u8; RECORD_SIZE] {
275    let mut out = [0_u8; RECORD_SIZE];
276    out[..8].copy_from_slice(&MAGIC);
277    out[8..10].copy_from_slice(&SCHEMA_VERSION.to_le_bytes());
278    out[10] = p.kind as u8;
279    out[11] = p.outcome as u8;
280    out[12..16].copy_from_slice(&p.stage.to_le_bytes());
281    out[16..24].copy_from_slice(&(state.status.records_written + 1).to_le_bytes());
282    out[24..32].copy_from_slice(&time.to_le_bytes());
283    out[32..40].copy_from_slice(&p.span.to_le_bytes());
284    out[40..48].copy_from_slice(&p.parent.to_le_bytes());
285    out[48..56].copy_from_slice(&p.ordinal.to_le_bytes());
286    out[56..64].copy_from_slice(&p.root.hash.to_le_bytes());
287    out[64..72].copy_from_slice(&p.root.utf8_len.to_le_bytes());
288    out[72..80].copy_from_slice(&state.status.generation.to_le_bytes());
289    out[80..84].copy_from_slice(&state.pid.to_le_bytes());
290    out[84..88].copy_from_slice(&state.status.errno.to_le_bytes());
291    out[88] = p.root.kind as u8;
292    out[89] = state.status.stop_reason as u8;
293    out[92..96].copy_from_slice(&p.depth.to_le_bytes());
294    out
295}
296impl State {
297    fn stop(&mut self, reason: StopReason, errno: i32) {
298        if matches!(
299            self.status.stop_reason,
300            StopReason::None | StopReason::Cap | StopReason::Abandoned | StopReason::OpenScopes
301        ) {
302            self.status.stop_reason = reason;
303            self.status.errno = errno;
304        }
305        self.status.enabled = false;
306    }
307    fn terminal(&self, outcome: Outcome) -> Payload {
308        Payload {
309            kind: EventKind::Terminal,
310            outcome,
311            stage: 0,
312            span: self.current_span,
313            parent: 0,
314            ordinal: 0,
315            root: RootIdentity::NONE,
316            depth: self.status.open_scopes,
317        }
318    }
319    fn publish(&mut self, payload: Payload) -> bool {
320        if !self.status.enabled {
321            return false;
322        }
323        if payload.kind != EventKind::Terminal
324            && self.status.records_written >= self.status.max_records - 1
325        {
326            self.status.stop_reason = StopReason::Cap;
327            self.publish(self.terminal(Outcome::Truncated));
328            self.status.enabled = false;
329            return false;
330        }
331        if self.status.records_written >= self.status.max_records {
332            self.stop(StopReason::Cap, 0);
333            return false;
334        }
335        let time = match clock_ns() {
336            Ok(time) if time >= self.status.last_monotonic_ns => time,
337            Ok(_) => {
338                self.stop(StopReason::Clock, 0);
339                return false;
340            }
341            Err(errno) => {
342                self.stop(StopReason::Clock, errno);
343                return false;
344            }
345        };
346        let record = encode(self, payload, time);
347        let mut retries = 0;
348        loop {
349            match write_record(self.fd, &record) {
350                Ok(bytes) => {
351                    self.status.bytes_written += bytes as u64;
352                    if bytes != RECORD_SIZE {
353                        self.stop(StopReason::ShortWrite, 0);
354                        return false;
355                    }
356                    self.status.records_written += 1;
357                    self.status.last_sequence = self.status.records_written;
358                    self.status.last_monotonic_ns = time;
359                    self.status.terminal_written = payload.kind == EventKind::Terminal;
360                    if self.status.terminal_written {
361                        self.status.enabled = false;
362                    }
363                    return true;
364                }
365                Err(errno) if errno == libc::EINTR && retries < EINTR_RETRIES => retries += 1,
366                Err(errno) => {
367                    self.stop(
368                        if errno == libc::EINTR {
369                            StopReason::Interrupted
370                        } else {
371                            StopReason::Write
372                        },
373                        errno,
374                    );
375                    return false;
376                }
377            }
378        }
379    }
380}
381
382fn with_state<T>(generation: Option<u64>, f: impl FnOnce(&mut State) -> T) -> Option<T> {
383    LOCAL
384        .try_with(|local| {
385            if local.busy.replace(true) {
386                local.reentered.set(true);
387                return None;
388            }
389            let result = local.state.get().and_then(|mut state| {
390                if generation.is_some_and(|id| id != state.status.generation) {
391                    return None;
392                }
393                let result = f(&mut state);
394                if local.reentered.replace(false) {
395                    state.stop(StopReason::Reentrant, 0);
396                }
397                // Detachment always wins, including an out-of-order guard drop.
398                if local
399                    .state
400                    .get()
401                    .is_some_and(|s| s.status.generation == state.status.generation)
402                {
403                    local.state.set(Some(state));
404                }
405                Some(result)
406            });
407            local.busy.set(false);
408            result
409        })
410        .ok()
411        .flatten()
412}
413
414/// An owning, thread-bound installation. Drop detaches TLS before closing the
415/// file; surviving scopes cannot write to its descriptor or a later installation.
416pub struct SinkGuard {
417    file: File,
418    generation: u64,
419    last_status: Cell<Status>,
420    attached: Cell<bool>,
421    thread_bound: PhantomData<Rc<()>>,
422}
423
424/// Install an owned empty regular file on this thread, then attempt its header.
425///
426/// The limit includes header and terminal. Nested installation is rejected.
427/// Header I/O or clock failure returns an installed but disabled guard, exposing
428/// the failure through [`SinkGuard::status`]; it does not fail evaluation.
429/// Callers must ensure no other file handle writes to the same file.
430pub fn install(mut file: File, max_records: u64) -> Result<SinkGuard, InstallError> {
431    if !(2..=MAX_RECORDS).contains(&max_records) {
432        return Err(InstallError::InvalidLimit);
433    }
434    LOCAL
435        .try_with(|local| {
436            if local.busy.get() {
437                return Err(InstallError::Busy);
438            }
439            if local.state.get().is_some() {
440                return Err(InstallError::AlreadyInstalled);
441            }
442            let metadata = file
443                .metadata()
444                .map_err(|e| InstallError::File(e.raw_os_error().unwrap_or(0)))?;
445            if !metadata.is_file() || metadata.len() != 0 {
446                return Err(InstallError::NotEmptyRegularFile);
447            }
448            file.seek(SeekFrom::Start(0))
449                .map_err(|e| InstallError::File(e.raw_os_error().unwrap_or(0)))?;
450            let generation = NEXT_GENERATION
451                .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |v| v.checked_add(1))
452                .map_err(|_| InstallError::GenerationExhausted)?;
453            let status = Status {
454                generation,
455                max_records,
456                records_written: 0,
457                bytes_written: 0,
458                last_sequence: 0,
459                last_monotonic_ns: 0,
460                enabled: true,
461                terminal_written: false,
462                open_scopes: 0,
463                stop_reason: StopReason::None,
464                errno: 0,
465            };
466            let state = State {
467                fd: file.as_raw_fd(),
468                pid: std::process::id(),
469                status,
470                next_span: 1,
471                current_span: 0,
472            };
473            local.state.set(Some(state));
474            let guard = SinkGuard {
475                file,
476                generation,
477                last_status: Cell::new(status),
478                attached: Cell::new(true),
479                thread_bound: PhantomData,
480            };
481            with_state(Some(generation), |s| {
482                s.publish(Payload {
483                    kind: EventKind::Header,
484                    outcome: Outcome::None,
485                    stage: 0,
486                    span: 0,
487                    parent: 0,
488                    ordinal: max_records,
489                    root: RootIdentity::NONE,
490                    depth: 0,
491                })
492            });
493            Ok(guard)
494        })
495        .unwrap_or(Err(InstallError::ThreadUnavailable))
496}
497impl SinkGuard {
498    /// Copy current scalar status without publishing or retaining runtime data.
499    pub fn status(&self) -> Status {
500        if let Some(status) = with_state(Some(self.generation), |s| s.status) {
501            self.last_status.set(status);
502        }
503        self.last_status.get()
504    }
505    fn close(&self, explicit: bool) -> Status {
506        if self.attached.replace(false) {
507            with_state(Some(self.generation), |s| {
508                if s.status.enabled {
509                    let outcome = if !explicit {
510                        s.status.stop_reason = StopReason::Abandoned;
511                        if std::thread::panicking() {
512                            Outcome::Unwound
513                        } else {
514                            Outcome::Abandoned
515                        }
516                    } else if s.status.open_scopes != 0 {
517                        s.status.stop_reason = StopReason::OpenScopes;
518                        Outcome::Incomplete
519                    } else {
520                        Outcome::Ok
521                    };
522                    s.publish(s.terminal(outcome));
523                    s.status.enabled = false;
524                }
525                self.last_status.set(s.status);
526            });
527            let _ = LOCAL.try_with(|local| {
528                if local
529                    .state
530                    .get()
531                    .is_some_and(|s| s.status.generation == self.generation)
532                {
533                    local.state.set(None);
534                }
535            });
536        }
537        self.last_status.get()
538    }
539    /// Attempt the terminal, detach, and close the owned file. No fsync occurs.
540    /// An open scope makes closure explicitly incomplete; publication failures
541    /// leave their last valid prefix and scalar failure status intact.
542    pub fn finish(self) -> Status {
543        self.close(true)
544    }
545}
546impl Drop for SinkGuard {
547    fn drop(&mut self) {
548        self.close(false);
549        // The owned File's normal field drop follows detachment, and never
550        // invokes user evaluation code.
551        let _ = &self.file;
552    }
553}
554
555/// One thread-bound nested attempt. It retains scalar labels only. End and
556/// transition methods borrow immutably, allowing use inside native callbacks.
557pub struct EventScope {
558    generation: u64,
559    span: u64,
560    parent: u64,
561    ordinal: u64,
562    root: RootIdentity,
563    stage: Cell<u32>,
564    active: Cell<bool>,
565    thread_bound: PhantomData<Rc<()>>,
566}
567impl EventScope {
568    /// Publish an explicit entry, or return an inert guard when no sink is active.
569    /// The ordinal is caller metadata; each attempt receives a separate span ID.
570    pub fn begin(stage: u32, ordinal: u64, root: RootIdentity) -> Self {
571        let ids = with_state(None, |s| {
572            if !s.status.enabled {
573                return None;
574            }
575            let Some(next_span) = s.next_span.checked_add(1) else {
576                s.stop(StopReason::CounterOverflow, 0);
577                return None;
578            };
579            let Some(depth) = s.status.open_scopes.checked_add(1) else {
580                s.stop(StopReason::CounterOverflow, 0);
581                return None;
582            };
583            let span = s.next_span;
584            let parent = s.current_span;
585            if !s.publish(Payload {
586                kind: EventKind::Enter,
587                outcome: Outcome::None,
588                stage,
589                span,
590                parent,
591                ordinal,
592                root,
593                depth,
594            }) {
595                return None;
596            }
597            s.next_span = next_span;
598            s.current_span = span;
599            s.status.open_scopes = depth;
600            Some((s.status.generation, span, parent))
601        })
602        .flatten();
603        let (generation, span, parent) = ids.unwrap_or((0, 0, 0));
604        Self {
605            generation,
606            span,
607            parent,
608            ordinal,
609            root,
610            stage: Cell::new(stage),
611            active: Cell::new(ids.is_some()),
612            thread_bound: PhantomData,
613        }
614    }
615    /// Publish entry into the next stage. This labels subsequent work, not the
616    /// interval just completed. A noncurrent scope disables telemetry.
617    pub fn transition(&self, stage: u32) {
618        if !self.active.get() {
619            return;
620        }
621        let published = with_state(Some(self.generation), |s| {
622            if !s.status.enabled {
623                return false;
624            }
625            if s.current_span != self.span {
626                s.stop(StopReason::ScopeOrder, 0);
627                return false;
628            }
629            s.publish(self.payload(
630                EventKind::Transition,
631                Outcome::None,
632                stage,
633                s.status.open_scopes,
634            ))
635        })
636        .unwrap_or(false);
637        if published {
638            self.stage.set(stage);
639        }
640    }
641    fn payload(&self, kind: EventKind, outcome: Outcome, stage: u32, depth: u32) -> Payload {
642        Payload {
643            kind,
644            outcome,
645            stage,
646            span: self.span,
647            parent: self.parent,
648            ordinal: self.ordinal,
649            root: self.root,
650            depth,
651        }
652    }
653    /// Publish the explicit outcome once and restore the parent as current.
654    /// Repeated calls and drops after this call have no effect.
655    pub fn finish(&self, outcome: Outcome) {
656        if !self.active.replace(false) {
657            return;
658        }
659        with_state(Some(self.generation), |s| {
660            if !s.status.enabled {
661                return;
662            }
663            if s.current_span != self.span || s.status.open_scopes == 0 {
664                s.stop(StopReason::ScopeOrder, 0);
665                return;
666            }
667            let depth = s.status.open_scopes - 1;
668            if s.publish(self.payload(EventKind::End, outcome, self.stage.get(), depth)) {
669                s.current_span = self.parent;
670                s.status.open_scopes = depth;
671            }
672        });
673    }
674}
675impl Drop for EventScope {
676    fn drop(&mut self) {
677        self.finish(if std::thread::panicking() {
678            Outcome::Unwound
679        } else {
680            Outcome::Incomplete
681        });
682    }
683}
684
685#[cfg(test)]
686#[path = "../tests/private/phase_events_test.rs"]
687mod tests;
688
689#[cfg(test)]
690mod test_io {
691    use super::*;
692    #[derive(Clone, Copy)]
693    pub(super) enum Mode {
694        Real,
695        Short(usize),
696        Error(i32, u32),
697        Reenter,
698    }
699    thread_local! {
700        pub(super) static MODE: Cell<Mode> = const { Cell::new(Mode::Real) };
701        pub(super) static CLOCK_FAIL: Cell<bool> = const { Cell::new(false) };
702    }
703    pub(super) fn clock_fails() -> bool {
704        CLOCK_FAIL.get()
705    }
706    pub(super) fn intercept(fd: i32, record: &[u8; RECORD_SIZE]) -> Option<Result<usize, i32>> {
707        match MODE.get() {
708            Mode::Real => None,
709            Mode::Short(bytes) => {
710                MODE.set(Mode::Real);
711                let bytes = bytes.min(RECORD_SIZE - 1);
712                // SAFETY: same owned descriptor and array as the production call;
713                // this test-only branch deliberately creates a partial tail.
714                let n = unsafe { libc::write(fd, record.as_ptr().cast(), bytes) };
715                Some(if n < 0 {
716                    Err(os_errno())
717                } else {
718                    Ok(n as usize)
719                })
720            }
721            Mode::Error(errno, remaining) => {
722                MODE.set(if remaining <= 1 {
723                    Mode::Real
724                } else {
725                    Mode::Error(errno, remaining - 1)
726                });
727                Some(Err(errno))
728            }
729            Mode::Reenter => {
730                MODE.set(Mode::Real);
731                let _scope = EventScope::begin(999, 0, RootIdentity::NONE);
732                None
733            }
734        }
735    }
736}