Skip to main content

detcore/
tool_local.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9//! The process-local portion of the Detcore Reverie-tool.
10
11use std::collections::BTreeMap;
12use std::collections::BTreeSet;
13use std::collections::HashMap;
14use std::os::fd::BorrowedFd;
15use std::path::Path;
16use std::sync::Arc;
17use std::sync::Mutex;
18use std::sync::MutexGuard;
19use std::time::Duration;
20
21use detcore_model::pedigree::Pedigree;
22use detcore_model::summary::TimesliceStats;
23use nix::fcntl::OFlag;
24use nix::sys::stat;
25use nix::unistd::Pid;
26use rand::Rng as _;
27use rand::RngExt as _;
28use rand::SeedableRng;
29use rand_distr::Distribution;
30use rand_distr::Exp;
31use rand_pcg::Pcg64Mcg;
32use reverie::Errno;
33use reverie::Error;
34use reverie::Guest;
35use reverie::syscalls::CloneFlags;
36use reverie::syscalls::Syscall;
37use reverie::syscalls::Sysno;
38use serde::Deserialize;
39use serde::Serialize;
40use sha2::Digest as _;
41use sha2::Sha256;
42use tracing::debug;
43use tracing::info;
44
45use crate::config::Config;
46use crate::detlog;
47use crate::fd::*;
48use crate::memory::MemoryMetadata;
49use crate::preemptions::ThreadHistoryIterator;
50use crate::record_or_replay::NoopTool;
51use crate::record_or_replay::RecordOrReplay;
52use crate::resources::ChaosEpochTransition;
53use crate::resources::Device;
54use crate::resources::Permission;
55use crate::resources::ResourceID;
56use crate::resources::Resources;
57use crate::scheduler::Priority;
58use crate::stat::*;
59use crate::types::*;
60
61/// The detcore tool and its per-process state.
62#[derive(Debug, Serialize, Deserialize)]
63pub struct Detcore<T = NoopTool> {
64    //
65    // TODO:
66    //  - Add Pid cache here.
67    //
68    /// The detpid of this process.
69    pub(crate) detpid: DetPid,
70
71    /// Cached copy of the tool Config.  Immutable over the lifetime of the program.
72    pub(crate) cfg: Config,
73
74    /// The record or replay sub-tool. Any events that cannot be made
75    /// deterministic are forwarded to this tool. Thus, Detcore acts as a
76    /// filter-map for syscalls.
77    pub(crate) record_or_replay: T,
78}
79
80/// The metadata associated with the file system view of a particular *process*.
81#[derive(Debug, Clone, Serialize, Deserialize)]
82pub struct FileMetadata {
83    /// Identity of the Linux descriptor table represented by `file_handles`.
84    pub(crate) files_id: FilesId,
85    /// Sequence used to allocate open file descriptions observed through this table.
86    next_open_file_sequence: u64,
87    /// Socket-only sequence used for backend-independent socket cookies.
88    #[serde(default)]
89    next_socket_open_file_sequence: u64,
90    /// A random-device or timerfd OFD from this table has been promoted.
91    /// Retain this history after its final close so exec cannot reuse a
92    /// canonical identity. (Serialized under its earlier name, which the
93    /// field had while only random devices were promoted.)
94    #[serde(default, rename = "has_promoted_random_files")]
95    has_promoted_shared_files: bool,
96    /// Track what file handles actually point to (e.g. after dup2).
97    /// This includes both the identifying resource (usually inode) and the deterministic file handle.
98    /// Deserialization restores aliasing (`crate::fd::intern_open_files`).
99    #[serde(deserialize_with = "deserialize_interned_file_handles")]
100    pub(crate) file_handles: HashMap<RawFd, DetFd>,
101    /// Blocking accepts waiting in this table, each as (operation, listener):
102    /// a `close` of a listener here is refused while an accept waits on it
103    /// (`crate::syscalls::accept_in_turn`). Waits never cross a fork or an
104    /// exec: a fork's child and an exec'd task start with none, and each wait
105    /// removes only its own entry, from the table it registered in.
106    // TODO-HUMAN-REVIEW(PR-3908)
107    #[serde(skip)]
108    accept_waits: Vec<(u64, RawFd)>,
109    /// The next accept-wait operation number in this table.
110    #[serde(skip)]
111    next_accept_wait: u64,
112    /// Whether the session renders `/proc/cpuinfo`, so that a memfd named as
113    /// its placeholder may be one when this table rediscovers descriptors
114    /// without a guest at hand (an in-guest backend's image after `exec`):
115    /// the session's own answer (`Detcore::rendered_files`), taken at the
116    /// image's first guest callback (`decide_cpuinfo_placeholders`), and kept
117    /// by `fork_for` and `for_exec`. `None` until then, and when absent from
118    /// an older serialized table. Detcore makes no such placeholder in a
119    /// session that does not render the file, so there a memfd of that name
120    /// stays an ordinary memfd.
121    #[serde(default)]
122    cpuinfo_placeholders: Option<bool>,
123    /// Descriptors rediscovered before [`Self::cpuinfo_placeholders`] was
124    /// decided whose memfd is named as a `/proc/cpuinfo` placeholder: kept as
125    /// the ordinary descriptors they look like until the session's answer
126    /// says whether they are placeholders (`decide_cpuinfo_placeholders`).
127    #[serde(default)]
128    pending_cpuinfo_placeholders: Vec<RawFd>,
129}
130
131/// Deserializes a descriptor table with its aliases restored, so a table
132/// carried across fork (or any other state migration) keeps one open file
133/// description object per `OpenFileId`.
134fn deserialize_interned_file_handles<'de, D>(
135    deserializer: D,
136) -> Result<HashMap<RawFd, DetFd>, D::Error>
137where
138    D: serde::Deserializer<'de>,
139{
140    let mut handles = <HashMap<RawFd, DetFd> as Deserialize>::deserialize(deserializer)?;
141    crate::fd::intern_open_files(&mut handles);
142    Ok(handles)
143}
144
145/// A descriptor identity held across an awaited syscall.
146///
147/// The clone retains the source open-file description until the operation
148/// finishes. `files_id` binds it to the table in which the syscall began.
149#[derive(Debug)]
150pub(crate) struct CapturedDetFd {
151    files_id: FilesId,
152    detfd: DetFd,
153}
154
155/// A captured descriptor could not be installed into the current descriptor
156/// table. The capture is returned so the caller can release any resource held
157/// alive solely by the in-flight operation.
158#[derive(Debug)]
159pub(crate) struct CapturedDetFdInstallError {
160    pub(crate) expected_files_id: FilesId,
161    pub(crate) actual_files_id: FilesId,
162    returned_fd: RawFd,
163    pub(crate) captured: CapturedDetFd,
164}
165
166/// Cleanup required after the kernel created a descriptor but Detcore could not
167/// install its captured open-file-description identity in the current table.
168#[derive(Debug, PartialEq, Eq)]
169pub(crate) struct CapturedDetFdInstallCleanup {
170    /// The exact kernel-returned descriptor that must be closed.
171    pub(crate) close_fd: RawFd,
172    /// A scheduler resource whose final modeled OFD reference was the capture.
173    pub(crate) release_open_file: Option<OpenFileId>,
174}
175
176impl CapturedDetFdInstallError {
177    /// Abandon the failed capture and preserve both cleanup obligations.
178    pub(crate) fn into_cleanup(self) -> CapturedDetFdInstallCleanup {
179        let release_open_file = (self.captured.detfd.open_file_alias_count() == 1)
180            .then(|| self.captured.detfd.open_file_id());
181        drop(self.captured);
182        CapturedDetFdInstallCleanup {
183            close_fd: self.returned_fd,
184            release_open_file,
185        }
186    }
187}
188
189/// Whether a pidfd target is proven to use the caller's exact descriptor table.
190///
191/// Linux pidfds name a specific task, and `pidfd_open(2)` accepts a thread-group
192/// leader. Equal TGIDs alone are not enough: a `CLONE_THREAD` child may omit
193/// `CLONE_FILES` and therefore have a different `files_struct`. Restrict the
194/// modeled path to the leader itself, where `target == getpid() == gettid()`
195/// proves that the task named by the pidfd and the caller are identical.
196pub(crate) fn pidfd_getfd_targets_calling_task(
197    target: Option<DetPid>,
198    current_tgid: DetPid,
199    current_tid: DetTid,
200) -> bool {
201    target == Some(current_tgid) && current_tid == current_tgid
202}
203
204// AUTONOMOUS-BOT-IMPLEMENTED
205// TODO-HUMAN-REVIEW(PR-1154): Review SaBRe exec descriptor-status handoff state.
206/// Descriptor numbers that Detcore keeps physically nonblocking while presenting them as
207/// blocking to the guest. SaBRe carries this narrow status set across an exec plugin reload.
208pub type ExecFdBlockingOverrides = BTreeSet<RawFd>;
209
210/// Metadata carried by the existing exec preparation/completion exchange.
211/// Descriptor numbers are authorized by that exchange's process/image fence,
212/// not by rediscovering whichever object later occupies a numeric stdio slot.
213#[derive(Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
214pub struct ExecFdState {
215    pub(crate) blocking: ExecFdBlockingOverrides,
216    pub(crate) inherited_reads: BTreeMap<RawFd, crate::fd::InheritedExternalRead>,
217    /// Set only by the global first-image completion, never by a preparation.
218    pub(crate) initialize_inherited_stdio: bool,
219    /// Offered only to the registered root's initial image by its launcher.
220    #[serde(default)]
221    pub(crate) initial_input: Option<reverie::InheritedInputIdentity>,
222    /// The owner-death wakes a successful exec makes Linux deliver, read
223    /// before the exec where the backend runs the native execve outside
224    /// Detcore's handler (DBT). The coordinator delivers them at the new
225    /// image's reconnect, or when the caller's thread ends without one (an
226    /// exec that ends its group), and drops them with an exec cancelled before
227    /// its point of no return (<https://github.com/rrnewton/hermit/issues/4268>).
228    #[serde(default)]
229    pub(crate) robust_wakes: Vec<(DetTid, FutexID)>,
230    /// Promoted random-device handles and allocator state of a reloaded tool.
231    /// Nonrandom descriptors retain their existing exec restoration paths.
232    #[serde(default)]
233    pub(crate) open_files: Option<ExecOpenFiles>,
234    /// Maps descriptions surviving a reload retain their opened target image,
235    /// aliases and any cached bytes. Kernel EOF must not erase this authority.
236    #[serde(default)]
237    pub(crate) maps: Option<ExecMapsFiles>,
238    /// Under `--pipe-wake-latency`, on a backend that rediscovers its
239    /// descriptors after exec: the channel end each surviving descriptor is,
240    /// reattached after rediscovery (`crate::pipe_wake`).
241    #[serde(default)]
242    pub(crate) channels: BTreeMap<RawFd, crate::pipe_wake::ChannelEnd>,
243    /// Under `--pipe-wake-latency`, on such a backend, at every exec: the old
244    /// table's open-file creator and next sequence, reserved before any
245    /// rediscovery, so that no description of the new image reuses an id a
246    /// channel elsewhere may still carry.
247    #[serde(default)]
248    pub(crate) open_file_namespace: Option<(DetTid, u64)>,
249    /// The image the exec runs, as Detcore resolved it from the exec's
250    /// arguments before the exec ([`crate::exec_record`]), or for the
251    /// registered root's first image the one its launch named
252    /// (`Config::launch_image`), once the coordinator checked it against the
253    /// kernel's link. `None` leaves the new image without a record.
254    #[serde(default)]
255    pub(crate) exe: Option<crate::exec_record::ExecRecord>,
256}
257
258/// Written out, not derived, so that the `--pipe-wake-latency` fields are
259/// printed only when set: an exec without the option traces as before.
260impl std::fmt::Debug for ExecFdState {
261    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
262        let mut debug = f.debug_struct("ExecFdState");
263        debug
264            .field("blocking", &self.blocking)
265            .field("inherited_reads", &self.inherited_reads)
266            .field(
267                "initialize_inherited_stdio",
268                &self.initialize_inherited_stdio,
269            )
270            .field("initial_input", &self.initial_input)
271            .field("robust_wakes", &self.robust_wakes)
272            .field("open_files", &self.open_files);
273        if let Some(maps) = &self.maps {
274            // Native authority tokens and kernel descriptor identities are
275            // transport-only; they must not enter canonical guest logs.
276            debug.field("maps_survivors", &maps.handles.len());
277        }
278        if !self.channels.is_empty() {
279            debug.field("channels", &self.channels);
280        }
281        if let Some(namespace) = &self.open_file_namespace {
282            debug.field("open_file_namespace", namespace);
283        }
284        if let Some(exe) = &self.exe {
285            debug.field("exe", &exe.exe);
286        }
287        debug.finish()
288    }
289}
290
291#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
292pub(crate) struct ExecOpenFiles {
293    pub(crate) creator: DetTid,
294    next_sequence: u64,
295    next_socket_sequence: u64,
296    handles: BTreeMap<RawFd, ExecOpenFile>,
297}
298
299#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
300pub(crate) struct ExecMapsFiles {
301    creator: DetTid,
302    next_sequence: u64,
303    handles: BTreeMap<RawFd, ExecMapsFile>,
304}
305
306#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
307struct ExecMapsFile {
308    identity: ExecOpenFile,
309    procfs: crate::procfs::ProcfsFile,
310    flags: i32,
311    path: Option<std::path::PathBuf>,
312}
313
314#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
315struct ExecOpenFile {
316    id: OpenFileId,
317    dev: u64,
318    ino: u64,
319    rdev: u64,
320    file_type: u32,
321    access: i32,
322}
323
324impl std::fmt::Debug for ExecOpenFile {
325    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
326        f.debug_struct("ExecOpenFile")
327            .field("id", &self.id)
328            .finish_non_exhaustive()
329    }
330}
331
332impl ExecOpenFile {
333    fn capture(fd: RawFd, id: OpenFileId) -> Result<Self, Errno> {
334        let mut stat: libc::stat = unsafe { std::mem::zeroed() };
335        // Runtime-owned read-only inspection of this process's descriptor table.
336        let result = unsafe {
337            crate::util::raw_syscall(
338                libc::SYS_fstat,
339                [fd as u64, (&raw mut stat) as u64, 0, 0, 0, 0],
340            )
341        };
342        if result < 0 {
343            return Err(Errno::new(-result as i32));
344        }
345        let flags = unsafe {
346            crate::util::raw_syscall(
347                libc::SYS_fcntl,
348                [fd as u64, libc::F_GETFL as u64, 0, 0, 0, 0],
349            )
350        };
351        if flags < 0 {
352            return Err(Errno::new(-flags as i32));
353        }
354        Ok(Self {
355            id,
356            dev: stat.st_dev,
357            ino: stat.st_ino,
358            rdev: stat.st_rdev,
359            file_type: stat.st_mode & libc::S_IFMT,
360            access: flags as i32 & libc::O_ACCMODE,
361        })
362    }
363}
364
365impl ExecFdState {
366    pub(crate) fn open_file_creator(&self) -> Option<DetTid> {
367        self.open_files
368            .as_ref()
369            .map(|files| files.creator)
370            .or_else(|| self.open_file_namespace.map(|(creator, _)| creator))
371            .or_else(|| self.maps.as_ref().map(|maps| maps.creator))
372    }
373
374    pub(crate) fn is_empty(&self) -> bool {
375        self.blocking.is_empty()
376            && self.inherited_reads.is_empty()
377            && !self.initialize_inherited_stdio
378            && self.initial_input.is_none()
379            && self.open_files.is_none()
380            && self.maps.is_none()
381            && self.channels.is_empty()
382            && self.open_file_namespace.is_none()
383            && self.exe.is_none()
384    }
385}
386
387impl From<ExecFdBlockingOverrides> for ExecFdState {
388    fn from(blocking: ExecFdBlockingOverrides) -> Self {
389        Self {
390            blocking,
391            ..Self::default()
392        }
393    }
394}
395
396/// The wakes an exec's walk of each owner's list found, in delivery order:
397/// owners in walk order, each owner's words in futex-key order.
398pub(crate) fn flatten_exec_robust_list_wakes(
399    wakes: Vec<(DetTid, Vec<RobustListWake>)>,
400) -> Vec<(DetTid, RobustListWake)> {
401    wakes
402        .into_iter()
403        .flat_map(|(owner, mut wakes)| {
404            wakes.sort_by_key(|wake| format!("{:?}", wake.futex));
405            wakes.into_iter().map(move |wake| (owner, wake))
406        })
407        .collect()
408}
409
410/// A single POSIX per-process interval timer created by `timer_create(2)`.
411///
412/// Detcore records arming against virtual time and schedules supported
413/// `SIGEV_SIGNAL` notifications through the deterministic scheduler.
414// AUTONOMOUS-BOT-IMPLEMENTED
415// TODO-HUMAN-REVIEW(#869)
416#[derive(Debug, Clone, Serialize, Deserialize)]
417struct PosixTimer {
418    /// Reload interval for periodic timers, in nanoseconds (0 => one-shot).
419    interval_ns: u64,
420    /// Absolute virtual-time deadline of the next expiration, or `None` when the
421    /// timer is disarmed (`it_value == 0`).
422    deadline: Option<LogicalTime>,
423    /// Signal number configured by `timer_create`, or `None` for notifications
424    /// that Detcore cannot deliver through its scheduler.
425    signal: Option<i32>,
426    /// The thread a `SIGEV_THREAD_ID` timer notifies, or `None` for a
427    /// process-directed one.
428    #[serde(default)]
429    thread: Option<DetTid>,
430    /// The `si_value` of its signal: `sigev_value`, or `sival_int = id`
431    /// for a timer created with no `sigevent` (`do_timer_create`).
432    #[serde(default)]
433    value: u64,
434}
435
436/// The set of POSIX timers owned by a *process*.
437///
438/// Timers are shared among all threads of a process and, per POSIX, are **not**
439/// inherited across `fork(2)`. Detcore therefore shares this table on
440/// `CLONE_THREAD` and starts a fresh, empty table for every new process (see
441/// `init_thread_state`). Successful exec deletes the timers as well.
442#[derive(Debug, Clone, Default, Serialize, Deserialize)]
443pub struct PosixTimers {
444    /// Deterministic id allocator. Kernel `timer_t`s are opaque, so we hand out
445    /// ids as 0, 1, 2, ... in creation order to keep them reproducible.
446    next_id: i32,
447    timers: HashMap<i32, PosixTimer>,
448}
449
450impl PosixTimers {
451    // AUTONOMOUS-BOT-IMPLEMENTED
452    // TODO-HUMAN-REVIEW(#869)
453    /// Allocate a new (disarmed) timer, returning its deterministic id.
454    /// `thread` is the thread a `SIGEV_THREAD_ID` timer notifies, and
455    /// `value` its `sigev_value`, or `None` for a timer created with no
456    /// `sigevent`, whose `si_value` is its id.
457    pub(crate) fn create(
458        &mut self,
459        signal: Option<i32>,
460        thread: Option<DetTid>,
461        value: Option<u64>,
462    ) -> i32 {
463        let id = self.next_id;
464        self.next_id += 1;
465        self.timers.insert(
466            id,
467            PosixTimer {
468                interval_ns: 0,
469                deadline: None,
470                signal,
471                thread,
472                value: value.unwrap_or(id as u32 as u64),
473            },
474        );
475        id
476    }
477
478    /// The `si_value` of timer `id`'s signal.
479    pub(crate) fn value(&self, id: i32) -> Option<u64> {
480        self.timers.get(&id).map(|timer| timer.value)
481    }
482
483    /// Arm or disarm timer `id`. `interval_ns` is the periodic reload and
484    /// `deadline` the absolute virtual-time expiration (the caller derives it
485    /// from the request flags and the current virtual clock; `None` disarms).
486    /// Returns the previous `(remaining_ns, interval_ns)` for `old_value`, or
487    /// `None` if the id is unknown.
488    pub(crate) fn settime(
489        &mut self,
490        id: i32,
491        interval_ns: u64,
492        deadline: Option<LogicalTime>,
493        now: LogicalTime,
494    ) -> Option<(u64, u64)> {
495        let timer = self.timers.get_mut(&id)?;
496        let old = (
497            remaining_ns(timer.deadline, timer.interval_ns, now),
498            timer.interval_ns,
499        );
500        timer.interval_ns = interval_ns;
501        timer.deadline = deadline;
502        Some(old)
503    }
504
505    /// Report the current `(remaining_ns, interval_ns)` for `timer_gettime`, or
506    /// `None` if the id is unknown.
507    pub(crate) fn gettime(&self, id: i32, now: LogicalTime) -> Option<(u64, u64)> {
508        let timer = self.timers.get(&id)?;
509        Some((
510            remaining_ns(timer.deadline, timer.interval_ns, now),
511            timer.interval_ns,
512        ))
513    }
514
515    /// Whether a timer with this id currently exists.
516    pub(crate) fn contains(&self, id: i32) -> bool {
517        self.timers.contains_key(&id)
518    }
519
520    // AUTONOMOUS-BOT-IMPLEMENTED
521    // TODO-HUMAN-REVIEW(#869)
522    pub(crate) fn signal(&self, id: i32) -> Option<Option<i32>> {
523        self.timers.get(&id).map(|timer| timer.signal)
524    }
525
526    /// The thread timer `id` notifies, if it is a `SIGEV_THREAD_ID` timer.
527    pub(crate) fn thread(&self, id: i32) -> Option<DetTid> {
528        self.timers.get(&id).and_then(|timer| timer.thread)
529    }
530
531    /// Remove a timer; returns whether it existed.
532    pub(crate) fn remove(&mut self, id: i32) -> bool {
533        self.timers.remove(&id).is_some()
534    }
535
536    /// Linux deletes all POSIX timers on successful exec. Keep the process's
537    /// ID allocator, but invalidate armed, disarmed and non-notifying timers.
538    pub(crate) fn clear_for_exec(&mut self) {
539        self.timers.clear();
540    }
541}
542
543/// One virtualized resource limit, represented in the `prlimit64` ABI's units.
544#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
545pub(crate) struct ResourceLimit {
546    pub(crate) current: u64,
547    pub(crate) maximum: u64,
548}
549
550/// Deterministic resource limits owned by one guest process.
551#[derive(Debug, Clone, Serialize, Deserialize)]
552pub(crate) struct ResourceLimits {
553    limits: Vec<ResourceLimit>,
554}
555
556impl Default for ResourceLimits {
557    fn default() -> Self {
558        let unlimited = ResourceLimit {
559            current: libc::RLIM64_INFINITY,
560            maximum: libc::RLIM64_INFINITY,
561        };
562        let mut limits = vec![unlimited; libc::RLIMIT_RTTIME as usize + 1];
563        limits[libc::RLIMIT_STACK as usize] = ResourceLimit {
564            current: 8 * 1024 * 1024,
565            maximum: libc::RLIM64_INFINITY,
566        };
567        limits[libc::RLIMIT_NOFILE as usize] = ResourceLimit {
568            current: 1_048_576,
569            maximum: 1_048_576,
570        };
571        Self { limits }
572    }
573}
574
575/// The limit every guest process starts with for `resource`, as
576/// `(current, maximum)` in the `prlimit64` ABI's units, or `None` for an
577/// invalid resource number.
578///
579/// A backend whose guest reads a limit before Detcore runs answers it with
580/// this. SaBRe is one: its guest's dynamic loader and libc startup run before
581/// the plugin is initialized, and libc sizes default thread stacks from
582/// `RLIMIT_STACK` there.
583pub fn initial_resource_limit(resource: u32) -> Option<(u64, u64)> {
584    ResourceLimits::default()
585        .get(resource)
586        .map(|limit| (limit.current, limit.maximum))
587}
588
589impl ResourceLimits {
590    /// Return a limit when `resource` is a valid Linux resource number.
591    pub(crate) fn get(&self, resource: u32) -> Option<ResourceLimit> {
592        self.limits.get(resource as usize).copied()
593    }
594
595    /// Replace a previously validated resource limit.
596    pub(crate) fn set(&mut self, resource: u32, limit: ResourceLimit) {
597        self.limits[resource as usize] = limit;
598    }
599}
600
601/// Nanoseconds remaining until `deadline` relative to `now`, saturating at 0.
602/// A disarmed timer (`None`) or an elapsed one-shot reports 0. Periodic timers
603/// advance arithmetically to their next virtual deadline.
604fn remaining_ns(deadline: Option<LogicalTime>, interval_ns: u64, now: LogicalTime) -> u64 {
605    match deadline {
606        Some(d) if d > now => d.as_nanos() - now.as_nanos(),
607        Some(d) if interval_ns != 0 => {
608            let elapsed = now.as_nanos() - d.as_nanos();
609            interval_ns - (elapsed % interval_ns)
610        }
611        Some(_) => 0,
612        None => 0,
613    }
614}
615
616impl<T> Default for Detcore<T> {
617    fn default() -> Self {
618        // TODO(T77816673): eventually we want to remove this requirement.
619        // In the meantime... just don't call this.
620        // Instead see the new() method defined in lib.rs
621        panic!("Detcore Default impl should not be called");
622    }
623}
624
625impl<T: RecordOrReplay> AsRef<T> for Detcore<T> {
626    fn as_ref(&self) -> &T {
627        &self.record_or_replay
628    }
629}
630
631impl<T: RecordOrReplay> AsMut<T> for Detcore<T> {
632    fn as_mut(&mut self) -> &mut T {
633        &mut self.record_or_replay
634    }
635}
636
637impl<T: RecordOrReplay> Detcore<T> {
638    /// Delegate to the record/replay tool without collapsing a tool failure
639    /// into a guest-visible errno. Syscall errors remain [`Error::Errno`], while
640    /// failures of the record/replay machinery retain their non-errno variant.
641    pub(crate) async fn record_or_replay_preserving_tool_errors<G, S>(
642        &self,
643        guest: &mut G,
644        syscall: S,
645    ) -> Result<i64, Error>
646    where
647        G: Guest<Self>,
648        S: Into<Syscall>,
649    {
650        preserve_record_or_replay_error(
651            self.translated_record_or_replay(guest, syscall.into())
652                .await,
653        )?
654        .map_err(Error::from)
655    }
656
657    /// The record-or-replay tool's handling of `syscall`, with a `/proc`
658    /// path that names a process or thread by the guest's number reaching
659    /// the kernel's directory for it (DBT; see
660    /// `syscalls::files::procfs_numbers`).
661    async fn translated_record_or_replay<G: Guest<Self>>(
662        &self,
663        guest: &mut G,
664        syscall: Syscall,
665    ) -> Result<i64, Error> {
666        let translated = Self::procfs_translated_call(guest, &syscall).await?;
667        let result = self
668            .record_or_replay
669            .handle_syscall_event(
670                &mut guest.into_guest(),
671                translated
672                    .as_ref()
673                    .map_or(syscall, |translated| translated.call),
674            )
675            .await;
676        if let Some(translated) = translated {
677            Self::finish_translated_call(guest, translated).await;
678        }
679        result
680    }
681
682    /// Helper function for delegating the injection of a syscall to the
683    /// record_or_replay tool.
684    ///
685    /// It is important to classify the cases where we need to call `inject`. We
686    /// have three main choices to make when handling a syscall:
687    ///  1. Fully determinize the syscall. In this case, it doesn't need to call
688    ///     `inject` at all.
689    ///  2. Partially determinize the syscall. In this case, it can't fully
690    ///     determinize a syscall but only part of it. For example, a `stat` syscall
691    ///     is ultimately non-deterministic because the file may not always exist.
692    ///     However, the mtime or inode numbers can be made deterministic.
693    ///  3. The syscall cannot be determinized at all. For example, a call to
694    ///     `recvfrom` cannot be made deterministic.
695    ///
696    /// Thus, this is called whenever `inject` would be called for non-bookkeeping
697    /// operations.
698    pub(crate) async fn record_or_replay<G, S>(
699        &self,
700        guest: &mut G,
701        syscall: S,
702    ) -> Result<i64, Errno>
703    where
704        G: Guest<Self>,
705        S: Into<Syscall>,
706    {
707        self.translated_record_or_replay(guest, syscall.into())
708            .await
709            // TODO: Get rid of this and make this whole function use the Error type.
710            .map_err(|err| err.into_errno().unwrap())
711    }
712}
713
714fn preserve_record_or_replay_error(
715    result: Result<i64, Error>,
716) -> Result<Result<i64, Errno>, Error> {
717    match result {
718        Ok(value) => Ok(Ok(value)),
719        Err(Error::Errno(error)) => Ok(Err(error)),
720        Err(error) => Err(error),
721    }
722}
723
724/// Linux reports a positive byte count when a later guest-visible write error
725/// follows partial progress. An error in the record/replay tool is different:
726/// replay itself failed, so it must remain fatal even after earlier bytes were
727/// accepted.
728pub(crate) fn finish_partial_record_or_replay_write(
729    written: i64,
730    error: Error,
731) -> Result<i64, Error> {
732    match error {
733        Error::Errno(_) if written > 0 => Ok(written),
734        error => Err(error),
735    }
736}
737
738#[cfg(test)]
739mod record_or_replay_error_tests {
740    use super::*;
741
742    #[test]
743    fn errno_remains_a_guest_syscall_result() {
744        let result = preserve_record_or_replay_error(Err(Error::Errno(Errno::EBADF)))
745            .expect("guest errno must not abort the tool");
746        assert_eq!(result, Err(Errno::EBADF));
747    }
748
749    #[test]
750    fn tool_failure_remains_an_outer_error() {
751        let failure =
752            preserve_record_or_replay_error(Err(Error::Tool(anyhow::anyhow!("restore failed"))))
753                .expect_err("tool failure must abort replay");
754        assert!(matches!(failure.into_errno(), Err(Error::Tool(_))));
755    }
756
757    #[test]
758    fn partial_write_suppresses_only_guest_errno() {
759        assert_eq!(
760            finish_partial_record_or_replay_write(7, Error::Errno(Errno::EPIPE)).unwrap(),
761            7
762        );
763
764        let io_failure = finish_partial_record_or_replay_write(
765            7,
766            Error::Io(std::io::Error::from_raw_os_error(libc::ENOSPC)),
767        )
768        .expect_err("host replay-output failure must not become a partial guest write");
769        assert!(matches!(io_failure.into_errno(), Err(Error::Io(_))));
770
771        let tool_failure = finish_partial_record_or_replay_write(
772            7,
773            Error::Tool(anyhow::anyhow!("replay endpoint disappeared")),
774        )
775        .expect_err("tool failure must not become a partial guest write");
776        assert!(matches!(tool_failure.into_errno(), Err(Error::Tool(_))));
777
778        let guest_failure = finish_partial_record_or_replay_write(0, Error::Errno(Errno::EPIPE))
779            .expect_err("zero-progress guest failure must remain guest-visible");
780        assert_eq!(guest_failure.into_errno().unwrap(), Errno::EPIPE);
781    }
782}
783
784impl FileMetadata {
785    /// create an empty file metadata
786    pub(crate) fn new(owner: DetTid) -> Self {
787        FileMetadata {
788            files_id: FilesId::initial(owner),
789            next_open_file_sequence: 0,
790            next_socket_open_file_sequence: 0,
791            has_promoted_shared_files: false,
792            file_handles: HashMap::new(),
793            accept_waits: Vec::new(),
794            next_accept_wait: 0,
795            cpuinfo_placeholders: None,
796            pending_cpuinfo_placeholders: Vec::new(),
797        }
798    }
799
800    /// Take the session's answer to whether it renders `/proc/cpuinfo`
801    /// (`rendered`: `Detcore::rendered_files(guest).cpuinfo`), at the first
802    /// guest callback of this image, before guest code runs. A descriptor
803    /// rediscovered before it whose memfd is named as a `/proc/cpuinfo`
804    /// placeholder becomes the placeholder it is where the session renders
805    /// the file, and stays an ordinary memfd where it does not. Later answers
806    /// of the same session are the same and change nothing.
807    pub(crate) fn decide_cpuinfo_placeholders(&mut self, rendered: bool) -> Result<(), Errno> {
808        if self.cpuinfo_placeholders.is_some() {
809            return Ok(());
810        }
811        self.cpuinfo_placeholders = Some(rendered);
812        let pending = std::mem::take(&mut self.pending_cpuinfo_placeholders);
813        if !rendered {
814            return Ok(());
815        }
816        for fd in pending {
817            if !self.file_handles.contains_key(&fd) {
818                continue;
819            }
820            let raw_stat =
821                stat::fstat(unsafe { BorrowedFd::borrow_raw(fd) }).map_err(|_| Errno::last())?;
822            let fd_flags = unsafe { libc::fcntl(fd, libc::F_GETFD) };
823            if let Some((path, snapshot)) =
824                placeholder_behind(fd, crate::procfs::RenderedFiles::ALL)
825            {
826                self.adopt_placeholder(fd, &raw_stat, fd_flags, path, snapshot)?;
827            }
828        }
829        Ok(())
830    }
831
832    /// Register a blocking accept waiting on `listener` and return the
833    /// operation number that removes it again.
834    pub(crate) fn add_accept_wait(&mut self, listener: RawFd) -> u64 {
835        let operation = self.next_accept_wait;
836        self.next_accept_wait += 1;
837        self.accept_waits.push((operation, listener));
838        operation
839    }
840
841    /// Remove the accept wait registered as `operation`, if it is here.
842    pub(crate) fn remove_accept_wait(&mut self, operation: u64) {
843        self.accept_waits
844            .retain(|(waiting, _)| *waiting != operation);
845    }
846
847    /// The lowest descriptor in `fds` that a blocking accept waits on.
848    pub(crate) fn waited_listener_in(&self, fds: std::ops::RangeInclusive<u32>) -> Option<RawFd> {
849        self.accept_waits
850            .iter()
851            .map(|(_, listener)| *listener)
852            .filter(|listener| u32::try_from(*listener).is_ok_and(|fd| fds.contains(&fd)))
853            .min()
854    }
855
856    fn allocate_open_file_id(&mut self, creator: DetTid, ty: FdType) -> OpenFileId {
857        if ty == FdType::Socket {
858            let id = OpenFileId::new_socket(creator, self.next_socket_open_file_sequence);
859            self.next_socket_open_file_sequence += 1;
860            id
861        } else {
862            let id = OpenFileId::new(creator, self.next_open_file_sequence);
863            self.next_open_file_sequence += 1;
864            id
865        }
866    }
867
868    fn count_open_files_at_paths(&self, paths: &[&Path]) -> usize {
869        self.file_handles
870            .values()
871            .filter(|fd| {
872                fd.path()
873                    .is_some_and(|path| paths.iter().any(|candidate| path == *candidate))
874            })
875            .map(DetFd::open_file_id)
876            .collect::<BTreeSet<_>>()
877            .len()
878    }
879
880    fn has_loopback_peer(&self) -> bool {
881        self.file_handles.values().any(DetFd::is_loopback_peer)
882    }
883
884    // TODO-HUMAN-REVIEW(#2373)
885    /// True when `vfork` must be refused because some open file description
886    /// either holds a lock or carries a cached claim that may now be wrong.
887    ///
888    /// ⚠️ NEVER-OBSERVED IS DELIBERATELY NOT UNSAFE. The previous form refused
889    /// on `!= Some(None)`, which also caught descriptors Detcore had simply
890    /// never observed. stdin, stdout and stderr are marked unobserved at
891    /// container setup because they predate Detcore, so that form refused
892    /// `vfork` for EVERY guest that reached it -- measured: fds 0, 1 and 2 were
893    /// the sole reason `run_dbt_virtualizes_process_identities` was refused,
894    /// and that guest never calls `flock` at all. A guard that cannot pass is
895    /// not conservative, it is broken.
896    ///
897    /// The hazard is a STALE CACHE: a copied runtime mutating a lock that this
898    /// side still has a claim about. A description Detcore never observed
899    /// carries no claim, so there is nothing about it that can go stale.
900    fn has_unsafe_vfork_flock_state(&self) -> bool {
901        self.file_handles.values().any(|detfd| {
902            matches!(detfd.known_flock_mode(), Some(Some(_))) || detfd.flock_mode_may_be_stale()
903        })
904    }
905
906    fn has_unsafe_vfork_ofd_state(&self) -> bool {
907        self.file_handles
908            .values()
909            .any(|detfd| detfd.may_hold_ofd_lock())
910    }
911
912    fn forget_flock_modes(&self) {
913        for detfd in self.file_handles.values() {
914            detfd.forget_local_flock_mode_at_fork();
915        }
916    }
917
918    // TODO-HUMAN-REVIEW(#2373)
919    /// Fork the file table for `child`.
920    ///
921    /// Local flock caches retain the existing conservative invalidation.
922    /// A promoted description has one canonical model, so copying a table
923    /// neither invalidates that model nor contacts it before child admission.
924    /// Same-process aliases keep their lock; a separately hosted runtime
925    /// resets copied locks at its physical child boundary.
926    pub(crate) fn fork_for(&self, child: DetTid) -> Self {
927        self.forget_flock_modes();
928        Self {
929            files_id: FilesId::forked(child),
930            next_open_file_sequence: self.next_open_file_sequence,
931            next_socket_open_file_sequence: self.next_socket_open_file_sequence,
932            has_promoted_shared_files: self.has_promoted_shared_files,
933            file_handles: self.file_handles.clone(),
934            accept_waits: Vec::new(),
935            next_accept_wait: 0,
936            cpuinfo_placeholders: self.cpuinfo_placeholders,
937            pending_cpuinfo_placeholders: self.pending_cpuinfo_placeholders.clone(),
938        }
939    }
940
941    pub(crate) fn for_exec(&self, task: DetTid) -> Self {
942        Self {
943            files_id: self.files_id.for_exec(task),
944            next_open_file_sequence: self.next_open_file_sequence,
945            next_socket_open_file_sequence: self.next_socket_open_file_sequence,
946            has_promoted_shared_files: self.has_promoted_shared_files,
947            file_handles: self
948                .file_handles
949                .iter()
950                .filter_map(|(&fd, detfd)| (!detfd.is_cloexec()).then_some((fd, detfd.clone())))
951                .collect(),
952            accept_waits: Vec::new(),
953            next_accept_wait: 0,
954            cpuinfo_placeholders: self.cpuinfo_placeholders,
955            pending_cpuinfo_placeholders: self.pending_cpuinfo_placeholders.clone(),
956        }
957    }
958
959    /// Read the live table incarnation for an independently owned exec cut.
960    pub fn native_exec_files_id(&self) -> FilesId {
961        self.files_id
962    }
963
964    /// Validate before and after preparation: `for_exec` intentionally drops
965    /// waits and CLOEXEC-only descriptions, so checking only its result would
966    /// lose evidence about their skipped runtime capabilities.
967    pub(crate) fn validate_native_exec_cut(
968        &self,
969        expected: FilesId,
970        prepared: bool,
971    ) -> Result<(), crate::native_exec::NativeExecCutError> {
972        use crate::native_exec::NativeExecCutError;
973
974        if self.files_id != expected {
975            return Err(NativeExecCutError::Identity("files_id"));
976        }
977        if !self.accept_waits.is_empty() {
978            return Err(NativeExecCutError::LiveCapability("accept_waits"));
979        }
980        if prepared && self.next_accept_wait != 0 {
981            return Err(NativeExecCutError::PreparedState("next_accept_wait"));
982        }
983        // The native final cut repeats this check after freezing counters.
984        // Compare prior descriptors directly so validation neither allocates a
985        // scratch map nor changes the carried Tool heap. The state transport
986        // separately bounds this first, quiescent single-thread domain.
987        for (index, (&slot, fd)) in self.file_handles.iter().enumerate() {
988            if slot < 0 || slot != fd.fd {
989                return Err(NativeExecCutError::Descriptor("slot number"));
990            }
991            if prepared && fd.is_cloexec() {
992                return Err(NativeExecCutError::PreparedState("CLOEXEC slot"));
993            }
994            let (id, owner) = fd.validate_native_exec_runtime_state()?;
995            for (_, previous) in self.file_handles.iter().take(index) {
996                let (previous_id, previous_owner) =
997                    previous.validate_native_exec_runtime_state()?;
998                if (id == previous_id) != (owner == previous_owner) {
999                    return Err(NativeExecCutError::Descriptor("OFD alias identity"));
1000                }
1001            }
1002        }
1003        Ok(())
1004    }
1005
1006    pub(crate) fn exec_blocking_overrides(&self) -> ExecFdBlockingOverrides {
1007        self.file_handles
1008            .iter()
1009            .filter_map(|(&fd, detfd)| {
1010                (!detfd.is_cloexec() && detfd.physically_nonblocking() && !detfd.is_nonblocking())
1011                    .then_some(fd)
1012            })
1013            .collect()
1014    }
1015
1016    pub(crate) fn apply_exec_blocking_overrides(
1017        &mut self,
1018        owner: DetTid,
1019        overrides: ExecFdBlockingOverrides,
1020    ) {
1021        for fd in overrides {
1022            tracing::trace!(
1023                "[detcore, dtid {}] restoring descriptor {} as logically blocking after exec",
1024                owner,
1025                fd,
1026            );
1027            match self.discover_fd_from_current_process(owner, fd) {
1028                Ok(()) => {
1029                    self.with_detfd(fd, |detfd| detfd.set_logical_nonblocking(false))
1030                        .expect("a just-discovered descriptor must remain registered");
1031                }
1032                Err(error) => {
1033                    tracing::warn!(
1034                        "[detcore, dtid {}] unable to restore inherited descriptor {} after exec: {}",
1035                        owner,
1036                        fd,
1037                        error,
1038                    );
1039                }
1040            }
1041        }
1042    }
1043
1044    fn inherited_reads_for_exec(&self) -> BTreeMap<RawFd, crate::fd::InheritedExternalRead> {
1045        self.file_handles
1046            .iter()
1047            .filter(|(_, detfd)| !detfd.is_cloexec())
1048            .filter_map(|(&fd, detfd)| {
1049                detfd
1050                    .inherited_external_read()
1051                    .map(|terminal| (fd, terminal))
1052            })
1053            .collect()
1054    }
1055
1056    /// Called only in the actual shared guest descriptor table, after the
1057    /// global state confirms this is the container's first image. TCGETS is
1058    /// read-only: neither terminal settings nor OFD flags are changed.
1059    fn discover_inherited_terminals(&mut self, descriptors: impl IntoIterator<Item = RawFd>) {
1060        for fd in descriptors {
1061            let Some(detfd) = self.file_handles.get(&fd) else {
1062                continue;
1063            };
1064            let Some(stat) = detfd.stat() else { continue };
1065            if stat.mode & libc::S_IFMT != libc::S_IFCHR {
1066                continue;
1067            }
1068            let mut settings: libc::termios = unsafe { std::mem::zeroed() };
1069            // SAFETY: TCGETS writes only to this live, adequately sized buffer.
1070            if unsafe { libc::ioctl(fd, libc::TCGETS, &raw mut settings) } != 0 {
1071                continue;
1072            }
1073            detfd.set_inherited_external_read(crate::fd::InheritedExternalRead {
1074                origin: detfd.open_file_id(),
1075                dev: stat.dev,
1076                inode: stat.inode,
1077                rdev: stat.rdev,
1078                file_type: libc::S_IFCHR,
1079                access_mode: detfd.status_flags() & libc::O_ACCMODE,
1080                resource: detfd.resource(),
1081            });
1082        }
1083    }
1084
1085    /// Called only in the actual shared guest descriptor table, after the
1086    /// global state confirms this is the container's first image, beside
1087    /// `discover_inherited_terminals`. The guest has not run yet, so a pipe
1088    /// end the first image holds came from outside the run: a readable one is
1089    /// an inherited external read, as a terminal or a launcher-bound input is
1090    /// (https://github.com/rrnewton/hermit/issues/4447), and its reads take
1091    /// the same external-input path theirs do. That holds even when the image
1092    /// also holds the pipe's write end: such a pipe was not made by Detcore's
1093    /// `pipe2`, so it is not physically nonblocking and cannot take the
1094    /// internal-pipe path, whose invariant (`record_or_replay_blocking`) a
1095    /// blocking read of it would otherwise trip. The decision reads only what
1096    /// discovery recorded for the descriptor (its type, the kernel's stat and
1097    /// its access mode), so no later probe can change it; a description a
1098    /// launcher already bound keeps its binding. Inherited descriptors above 2
1099    /// are not discovered here.
1100    fn discover_inherited_pipes(&mut self, descriptors: impl IntoIterator<Item = RawFd>) {
1101        for fd in descriptors {
1102            let Some(detfd) = self.file_handles.get(&fd) else {
1103                continue;
1104            };
1105            let access_mode = detfd.status_flags() & libc::O_ACCMODE;
1106            if detfd.ty() != FdType::Pipe
1107                || detfd.is_socketpair_endpoint()
1108                || access_mode == libc::O_WRONLY
1109                || detfd.inherited_external_read().is_some()
1110            {
1111                continue;
1112            }
1113            let Some(stat) = detfd.stat() else { continue };
1114            detfd.set_inherited_external_read(crate::fd::InheritedExternalRead {
1115                origin: detfd.open_file_id(),
1116                dev: stat.dev,
1117                inode: stat.inode,
1118                rdev: stat.rdev,
1119                file_type: libc::S_IFIFO,
1120                access_mode,
1121                resource: detfd.resource(),
1122            });
1123        }
1124    }
1125
1126    /// Restore only external-read descriptions proven to survive the prepared exec. Unknown
1127    /// descriptors and guest-created PTYs are not promoted by rediscovery.
1128    fn restore_inherited_reads(
1129        &mut self,
1130        owner: DetTid,
1131        inherited_reads: BTreeMap<RawFd, crate::fd::InheritedExternalRead>,
1132    ) -> Result<(), Errno> {
1133        let mut aliases: HashMap<OpenFileId, DetFd> = HashMap::new();
1134        for (fd, terminal) in inherited_reads {
1135            self.discover_fd_from_current_process(owner, fd)?;
1136            let detfd = self.file_handles.get_mut(&fd).ok_or(Errno::EBADF)?;
1137            let stat =
1138                stat::fstat(unsafe { BorrowedFd::borrow_raw(fd) }).map_err(|_| Errno::last())?;
1139            if stat.st_mode & libc::S_IFMT != terminal.file_type
1140                || (stat.st_dev, stat.st_ino, stat.st_rdev)
1141                    != (terminal.dev, terminal.inode, terminal.rdev)
1142                || detfd.status_flags() & libc::O_ACCMODE != terminal.access_mode
1143            {
1144                return Err(Errno::EIO);
1145            }
1146            // Do not repeat TCGETS here: a hung-up terminal may return EIO
1147            // from that query while still being the inherited open file.
1148            if let Some(alias) = aliases.get(&terminal.origin) {
1149                if detfd.status_flags() != alias.status_flags() {
1150                    return Err(Errno::EIO);
1151                }
1152                detfd.share_open_file_with(alias);
1153            } else {
1154                detfd.set_resource(terminal.resource.clone());
1155                detfd.set_inherited_external_read(terminal.clone());
1156                aliases.insert(terminal.origin, detfd.clone());
1157            }
1158        }
1159        Ok(())
1160    }
1161
1162    fn install_inherited_input(
1163        &mut self,
1164        owner: DetTid,
1165        input: reverie::InheritedInputIdentity,
1166    ) -> Result<(), Errno> {
1167        let fd = input.guest_fd();
1168        self.discover_fd_from_current_process(owner, fd)?;
1169        let stat = stat::fstat(unsafe { BorrowedFd::borrow_raw(fd) }).map_err(|_| Errno::last())?;
1170        let flags = unsafe { libc::fcntl(fd, libc::F_GETFL) };
1171        let detfd = self.file_handles.get(&fd).ok_or(Errno::EBADF)?;
1172        if !input.matches(&stat, flags) || detfd.ty() != FdType::Pipe {
1173            return Err(Errno::EIO);
1174        }
1175        detfd.set_inherited_external_read(crate::fd::InheritedExternalRead {
1176            origin: detfd.open_file_id(),
1177            dev: input.dev(),
1178            inode: input.inode(),
1179            rdev: input.rdev(),
1180            file_type: libc::S_IFIFO,
1181            access_mode: input.access_mode(),
1182            resource: detfd.resource(),
1183        });
1184        Ok(())
1185    }
1186
1187    pub(crate) fn apply_exec_fd_state(
1188        &mut self,
1189        owner: DetTid,
1190        state: ExecFdState,
1191        shared_guest_table: bool,
1192    ) -> Result<(), Errno> {
1193        if shared_guest_table && let Some(maps) = &state.maps {
1194            // The existing exec exchange authorizes these survivors. Validate
1195            // every slot before installing any carried maps authority, and
1196            // reserve its old ID space before lazy discovery allocates IDs.
1197            for (&fd, survivor) in &maps.handles {
1198                if ExecOpenFile::capture(fd, survivor.identity.id)? != survivor.identity {
1199                    return Err(Errno::EIO);
1200                }
1201            }
1202            if state
1203                .open_files
1204                .as_ref()
1205                .is_some_and(|files| files.creator != maps.creator)
1206                || state
1207                    .open_file_namespace
1208                    .is_some_and(|(creator, _)| creator != maps.creator)
1209            {
1210                return Err(Errno::EIO);
1211            }
1212            self.next_open_file_sequence = self.next_open_file_sequence.max(maps.next_sequence);
1213        }
1214        // Legacy discovery also allocates IDs. Reserve the complete old
1215        // namespace before it can create any nonrandom descriptions, including
1216        // same-leader exec where the creator did not change.
1217        let owner = if shared_guest_table && let Some(open_files) = &state.open_files {
1218            self.next_open_file_sequence =
1219                self.next_open_file_sequence.max(open_files.next_sequence);
1220            self.next_socket_open_file_sequence = self
1221                .next_socket_open_file_sequence
1222                .max(open_files.next_socket_sequence);
1223            open_files.creator
1224        } else if shared_guest_table
1225            && let Some((creator, next_sequence)) = state.open_file_namespace
1226        {
1227            // `--pipe-wake-latency`: no new description may take an id that a
1228            // carried channel names (`crate::pipe_wake`).
1229            self.next_open_file_sequence = self.next_open_file_sequence.max(next_sequence);
1230            creator
1231        } else if shared_guest_table && let Some(maps) = &state.maps {
1232            maps.creator
1233        } else {
1234            owner
1235        };
1236        self.apply_exec_blocking_overrides(owner, state.blocking);
1237        if !shared_guest_table {
1238            return Ok(());
1239        }
1240        if let Some(input) = state.initial_input {
1241            self.install_inherited_input(owner, input)?;
1242        }
1243        if state.initialize_inherited_stdio {
1244            self.discover_inherited_terminals(0..=2);
1245            self.discover_inherited_pipes(0..=2);
1246        } else {
1247            self.restore_inherited_reads(owner, state.inherited_reads)?;
1248        }
1249        if let Some(open_files) = state.open_files {
1250            let mut handles = HashMap::new();
1251            for (fd, survivor) in open_files.handles {
1252                if ExecOpenFile::capture(fd, survivor.id)? != survivor {
1253                    return Err(Errno::EIO);
1254                }
1255                handles.insert(fd, DetFd::shared_survivor(fd, survivor.id));
1256            }
1257            crate::fd::intern_open_files(&mut handles);
1258            // Replace only the authenticated random-device and timerfd survivors. Pipes,
1259            // sockets and other descriptors retain the legacy restoration above;
1260            // in particular, do not reconnect an old socket's port association.
1261            self.file_handles.extend(handles);
1262            self.has_promoted_shared_files = true;
1263        }
1264        // Last, so that no restoration above can replace a description after
1265        // its channel is set: every carried channel end, discovering a
1266        // descriptor not yet rediscovered (one the guest left `O_NONBLOCK`).
1267        for (fd, end) in state.channels {
1268            match self.discover_fd_from_current_process(owner, fd) {
1269                Ok(()) => {
1270                    self.with_detfd(fd, |detfd| detfd.set_channel(end))
1271                        .expect("a just-discovered descriptor must remain registered");
1272                }
1273                Err(error) => {
1274                    tracing::warn!(
1275                        "[detcore, dtid {}] descriptor {} carried a pipe channel across exec \
1276                         but cannot be rediscovered; it keeps none: {}",
1277                        owner,
1278                        fd,
1279                        error,
1280                    );
1281                }
1282            }
1283        }
1284        if let Some(maps) = state.maps {
1285            let mut handles = HashMap::new();
1286            for (fd, survivor) in maps.handles {
1287                let raw_stat = stat::fstat(unsafe { BorrowedFd::borrow_raw(fd) })
1288                    .map_err(|error| Errno::new(error as i32))?;
1289                let handle = DetFd::new(
1290                    fd,
1291                    OFlag::from_bits_truncate(survivor.flags),
1292                    FdType::Regular,
1293                    survivor.identity.id,
1294                )
1295                .with_stat(DetStat::from(raw_stat));
1296                if let Some(path) = survivor.path {
1297                    handle.set_path(path);
1298                }
1299                handle.set_procfs(survivor.procfs);
1300                handle.mark_flock_mode_unobserved();
1301                handles.insert(fd, handle);
1302            }
1303            // Aliases retain one old snapshot/cursor. Independent opens of the
1304            // same proc inode remain separate because their IDs differ.
1305            crate::fd::intern_open_files(&mut handles);
1306            self.file_handles.extend(handles);
1307        }
1308        Ok(())
1309    }
1310
1311    pub(crate) fn open_files_closed_on_exec(&self, table_is_shared: bool) -> Vec<OpenFileId> {
1312        if table_is_shared {
1313            return Vec::new();
1314        }
1315
1316        let mut open_files = HashMap::new();
1317        for detfd in self.file_handles.values() {
1318            let id = detfd.open_file_id();
1319            let total_aliases = detfd.open_file_alias_count();
1320            let entry = open_files.entry(id).or_insert((0, total_aliases, true));
1321            debug_assert_eq!(entry.1, total_aliases);
1322            entry.0 += 1;
1323            entry.2 &= detfd.is_cloexec();
1324        }
1325
1326        let mut closed: Vec<_> = open_files
1327            .into_iter()
1328            .filter_map(|(id, (table_aliases, total_aliases, all_cloexec))| {
1329                (all_cloexec && table_aliases == total_aliases).then_some(id)
1330            })
1331            .collect();
1332        closed.sort();
1333        closed
1334    }
1335
1336    /// set default fds
1337    fn setup_stdio(mut self, _pid: Pid, owner: DetTid) -> Self {
1338        // guest stdio can be a pipe, which make things difficult
1339        // hence use a dummy stat here.
1340        // The raw syscall, not libc's interposable fstat: this runs inside the
1341        // guest under in-guest LiteInst (see crate::util::raw_syscall).
1342        let mut metadata: libc::stat = unsafe { std::mem::zeroed() };
1343        // SAFETY: fstat writes only into `metadata`.
1344        let status = unsafe {
1345            crate::util::raw_syscall(libc::SYS_fstat, [0, (&raw mut metadata) as u64, 0, 0, 0, 0])
1346        };
1347        if let Err(error) = crate::util::raw_zero_result(status) {
1348            panic!(
1349                "fstat of the guest's stdin failed (errno {})",
1350                error.raw_os_error().unwrap_or(0)
1351            );
1352        }
1353        let stat: DetStat = metadata.into();
1354        let stdin = DetFd::new(
1355            0,
1356            OFlag::empty(),
1357            FdType::Regular,
1358            self.allocate_open_file_id(owner, FdType::Regular),
1359        )
1360        .with_stat(stat)
1361        .with_resource(ResourceID::Device(Device::ContainerStdin));
1362        let stdout = DetFd::new(
1363            1,
1364            OFlag::empty(),
1365            FdType::Regular,
1366            self.allocate_open_file_id(owner, FdType::Regular),
1367        )
1368        .with_stat(stat)
1369        .with_resource(ResourceID::Device(Device::ContainerStdout));
1370        let stderr = DetFd::new(
1371            2,
1372            OFlag::empty(),
1373            FdType::Regular,
1374            self.allocate_open_file_id(owner, FdType::Regular),
1375        )
1376        .with_stat(stat)
1377        .with_resource(ResourceID::Device(Device::ContainerStderr));
1378
1379        // These descriptors existed before Detcore began observing the guest,
1380        // so they may already carry flock state that we cannot query.
1381        stdin.mark_flock_mode_unobserved();
1382        stdout.mark_flock_mode_unobserved();
1383        stderr.mark_flock_mode_unobserved();
1384
1385        self.add_detfd(stdin);
1386        self.add_detfd(stdout);
1387        self.add_detfd(stderr);
1388
1389        self
1390    }
1391
1392    // AUTONOMOUS-BOT-IMPLEMENTED
1393    // TODO-HUMAN-REVIEW(PR-845): Review SaBRe on-demand inherited descriptor discovery.
1394    fn discover_fd_from_current_process(&mut self, owner: DetTid, fd: RawFd) -> Result<(), Errno> {
1395        if self.file_handles.contains_key(&fd) {
1396            return Ok(());
1397        }
1398
1399        let fd_flags = unsafe { libc::fcntl(fd, libc::F_GETFD) };
1400        let status_flags = unsafe { libc::fcntl(fd, libc::F_GETFL) };
1401        if fd_flags == -1 || status_flags == -1 {
1402            return Err(Errno::last());
1403        }
1404        let raw_stat =
1405            stat::fstat(unsafe { BorrowedFd::borrow_raw(fd) }).map_err(|_| Errno::last())?;
1406        let file_type = stat::SFlag::from_bits_truncate(raw_stat.st_mode);
1407        let ty = if file_type.contains(stat::SFlag::S_IFIFO) {
1408            FdType::Pipe
1409        } else if file_type.contains(stat::SFlag::S_IFSOCK) {
1410            FdType::Socket
1411        } else {
1412            FdType::Regular
1413        };
1414        let mut flags = OFlag::from_bits_truncate(status_flags);
1415        let physically_nonblocking = flags.contains(OFlag::O_NONBLOCK);
1416        // Discovered descriptors have unknown provenance, so an observed
1417        // O_NONBLOCK bit must remain guest-visible. Detcore-created scheduler
1418        // pipes are registered when created and do not reach this fallback.
1419        if fd_flags & libc::FD_CLOEXEC != 0 {
1420            flags.insert(OFlag::O_CLOEXEC);
1421        }
1422        self.add_fd(owner, fd, flags, ty, Some(raw_stat.into()))?;
1423        // This newly discovered description predates our observation. Its
1424        // kernel lock may be held, but no cached lock claim existed to go stale.
1425        self.with_detfd(fd, |detfd| detfd.mark_flock_mode_unobserved())?;
1426        // A placeholder for a procfs file Detcore renders, which the backend
1427        // rediscovers after `exec`: the file again, at the position the old
1428        // image left and with the snapshot it took, as a backend that keeps
1429        // Detcore's state across `exec` has them (`syscalls::files::rendered_procfs`).
1430        // The snapshot is the one its name carries (`procfs::placeholder_name`).
1431        // Only an empty regular file with no link can be one.
1432        let may_be_placeholder = raw_stat.st_mode & libc::S_IFMT == libc::S_IFREG
1433            && raw_stat.st_nlink == 0
1434            && raw_stat.st_size == 0;
1435        // A `/proc/cpuinfo` placeholder only once the session's answer says
1436        // it renders the file (`decide_cpuinfo_placeholders`); before that
1437        // answer, one waits for it as the ordinary descriptor it looks like.
1438        let decided = self.cpuinfo_placeholders;
1439        // A process's `mountinfo` or `mounts` has a placeholder only in a
1440        // session with a container mount table, the only one that renders it.
1441        let files = crate::procfs::RenderedFiles {
1442            cpuinfo: decided == Some(true),
1443            mounts: true,
1444        };
1445        let found = may_be_placeholder
1446            .then(|| placeholder_behind(fd, files))
1447            .flatten();
1448        if found.is_none()
1449            && decided.is_none()
1450            && may_be_placeholder
1451            && placeholder_behind(fd, crate::procfs::RenderedFiles::ALL)
1452                .is_some_and(|(path, _)| path == std::path::Path::new("/proc/cpuinfo"))
1453        {
1454            self.pending_cpuinfo_placeholders.push(fd);
1455        }
1456        if let Some((path, snapshot)) = found {
1457            if self.adopt_placeholder(fd, &raw_stat, fd_flags, path, snapshot)? {
1458                return Ok(());
1459            }
1460        }
1461        // A fixed procfs file the kernel opened (through a symbolic link),
1462        // which the old image read from Detcore's rendering: the file again,
1463        // at the position Detcore kept in the kernel
1464        // (`DetFd::procfs_keeps_kernel_position`), so the new image does not
1465        // read the host's file. procfs files report size 0.
1466        else if raw_stat.st_mode & libc::S_IFMT == libc::S_IFREG
1467            && raw_stat.st_size == 0
1468            && let Some(procfs) = fixed_procfs_behind(fd)
1469        {
1470            // SAFETY: lseek only reads the descriptor's position.
1471            let offset = unsafe {
1472                crate::util::raw_syscall(
1473                    libc::SYS_lseek,
1474                    [fd as u64, 0, libc::SEEK_CUR as u64, 0, 0, 0],
1475                )
1476            };
1477            let offset = usize::try_from(offset).unwrap_or(0);
1478            let path = procfs
1479                .rendered_path(crate::procfs::RenderedFiles::WITHOUT_CPUINFO)
1480                .expect("a fixed procfs file has a path");
1481            self.with_detfd(fd, |detfd| {
1482                detfd.set_path(path);
1483                detfd.set_procfs(procfs.clone());
1484                detfd.set_procfs_offset(offset);
1485            })?;
1486        }
1487        if let Some(resource) = stdio_resource(fd) {
1488            self.with_detfd(fd, |detfd| detfd.set_resource(resource.clone()))?;
1489        }
1490        if ty == FdType::Pipe && physically_nonblocking {
1491            self.with_detfd(fd, |detfd| detfd.set_physically_nonblocking())?;
1492        }
1493        Ok(())
1494    }
1495
1496    /// Make descriptor `fd`, already in this table, the placeholder for the
1497    /// rendered file `path` that its memfd (`raw_stat`, descriptor flags
1498    /// `fd_flags`) is, with the snapshot its name carries. Returns whether it
1499    /// joined another descriptor's open file (an alias), whose state it then
1500    /// shares.
1501    fn adopt_placeholder(
1502        &mut self,
1503        fd: RawFd,
1504        raw_stat: &libc::stat,
1505        fd_flags: libc::c_int,
1506        path: &'static std::path::Path,
1507        snapshot: Vec<u8>,
1508    ) -> Result<bool, Errno> {
1509        crate::syscalls::rendered_procfs::register_placeholder(
1510            raw_stat.st_dev,
1511            raw_stat.st_ino,
1512            path,
1513        );
1514        // Every open makes its own placeholder, so another descriptor on
1515        // the same one is the same open file: one cursor, as before.
1516        if let Some(alias) = self.rendered_alias(fd, raw_stat.st_dev, raw_stat.st_ino) {
1517            let mut alias = alias.with_fd(fd);
1518            alias.set_cloexec(fd_flags & libc::FD_CLOEXEC != 0);
1519            self.add_detfd(alias);
1520            return Ok(true);
1521        }
1522        // SAFETY: lseek only reads the descriptor's position.
1523        let offset = unsafe {
1524            crate::util::raw_syscall(
1525                libc::SYS_lseek,
1526                [fd as u64, 0, libc::SEEK_CUR as u64, 0, 0, 0],
1527            )
1528        };
1529        let offset = usize::try_from(offset).unwrap_or(0);
1530        let procfs = crate::procfs::ProcfsFile::from_rendered_path(path)
1531            .expect("a rendered path is a procfs file")
1532            .into_rendered();
1533        let procfs = if snapshot.is_empty() {
1534            procfs
1535        } else {
1536            procfs.with_rendered_snapshot(snapshot)
1537        };
1538        self.with_detfd(fd, |detfd| {
1539            detfd.set_path(path);
1540            detfd.set_procfs(procfs.clone());
1541            detfd.set_procfs_offset(offset);
1542        })?;
1543        Ok(false)
1544    }
1545
1546    /// Another descriptor of this process open on the placeholder `(dev,
1547    /// ino)`, which `fd` is too.
1548    fn rendered_alias(&self, fd: RawFd, dev: u64, ino: u64) -> Option<DetFd> {
1549        self.file_handles
1550            .iter()
1551            .filter(|(other, detfd)| **other != fd && detfd.procfs_rendered_path().is_some())
1552            .find(|(other, _)| {
1553                stat::fstat(unsafe { BorrowedFd::borrow_raw(**other) })
1554                    .is_ok_and(|stat| stat.st_dev == dev && stat.st_ino == ino)
1555            })
1556            .map(|(_, detfd)| detfd.clone())
1557    }
1558
1559    /// get detfd from rawfd, rawfd must be added or dup-ed first.
1560    fn with_detfd<F, U>(&mut self, fd: RawFd, mut f: F) -> Result<U, Errno>
1561    where
1562        F: FnMut(&mut DetFd) -> U,
1563    {
1564        let detfd = self.file_handles.get_mut(&fd).ok_or(Errno::EBADF)?;
1565        Ok(f(detfd))
1566    }
1567
1568    /// add a detfd
1569    fn add_detfd(&mut self, detfd: DetFd) {
1570        let fd = detfd.fd;
1571        self.file_handles.insert(fd, detfd);
1572    }
1573
1574    /// add a raw fd
1575    fn add_fd(
1576        &mut self,
1577        creator: DetTid,
1578        fd: RawFd,
1579        flags: OFlag,
1580        ty: FdType,
1581        stat: Option<DetStat>,
1582    ) -> Result<(), Errno> {
1583        let id = self.allocate_open_file_id(creator, ty);
1584        let detfd = DetFd::new(fd, flags, ty, id).with_stat(stat);
1585        self.add_detfd(detfd);
1586        Ok(())
1587    }
1588
1589    /// remove a rawfd
1590    fn remove_fd(&mut self, fd: RawFd) -> Option<OpenFileId> {
1591        let detfd = self.file_handles.remove(&fd)?;
1592        (detfd.open_file_alias_count() == 1).then(|| detfd.open_file_id())
1593    }
1594
1595    /// Remove every modeled descriptor in an inclusive close_range interval.
1596    fn remove_fd_range(&mut self, first: u32, last: u32) -> Vec<OpenFileId> {
1597        let mut descriptors: Vec<_> = self
1598            .file_handles
1599            .keys()
1600            .copied()
1601            .filter(|fd| *fd >= 0 && first <= *fd as u32 && *fd as u32 <= last)
1602            .collect();
1603        descriptors.sort_unstable();
1604        descriptors
1605            .into_iter()
1606            .filter_map(|fd| self.remove_fd(fd))
1607            .collect()
1608    }
1609
1610    /// dup raw fds.
1611    fn dup_fd(
1612        &mut self,
1613        oldfd: RawFd,
1614        newfd: RawFd,
1615        flags: OFlag,
1616    ) -> Result<Option<OpenFileId>, Errno> {
1617        if oldfd == newfd {
1618            self.with_detfd(oldfd, |_| ())?;
1619            return Ok(None);
1620        }
1621
1622        let detfd = self.with_detfd(oldfd, |old_detfd| {
1623            old_detfd.clone().with_fd(newfd).with_fd_flags(flags)
1624        })?;
1625        let replaced = self.file_handles.insert(newfd, detfd);
1626        Ok(replaced
1627            .and_then(|detfd| (detfd.open_file_alias_count() == 1).then(|| detfd.open_file_id())))
1628    }
1629
1630    /// Capture the exact open-file description currently named by `fd`.
1631    fn capture_fd(&mut self, fd: RawFd) -> Result<CapturedDetFd, Errno> {
1632        let detfd = self.with_detfd(fd, |detfd| detfd.clone())?;
1633        Ok(CapturedDetFd {
1634            files_id: self.files_id,
1635            detfd,
1636        })
1637    }
1638
1639    /// Install a previously captured open-file description as `newfd`.
1640    ///
1641    /// Unlike [`Self::dup_fd`], this never resolves the source fd number again.
1642    /// It succeeds only if the destination still belongs to the descriptor
1643    /// table in which the source was captured.
1644    fn install_captured_fd(
1645        &mut self,
1646        captured: CapturedDetFd,
1647        newfd: RawFd,
1648        flags: OFlag,
1649    ) -> Result<Option<OpenFileId>, CapturedDetFdInstallError> {
1650        if captured.files_id != self.files_id {
1651            return Err(CapturedDetFdInstallError {
1652                expected_files_id: captured.files_id,
1653                actual_files_id: self.files_id,
1654                returned_fd: newfd,
1655                captured,
1656            });
1657        }
1658
1659        let detfd = captured.detfd.with_fd(newfd).with_fd_flags(flags);
1660        let replaced = self.file_handles.insert(newfd, detfd);
1661        Ok(replaced
1662            .and_then(|detfd| (detfd.open_file_alias_count() == 1).then(|| detfd.open_file_id())))
1663    }
1664
1665    /// Drop a capture that was not installed and report whether it retained the
1666    /// final reference to the open-file description.
1667    fn abandon_captured_fd(&mut self, captured: CapturedDetFd) -> Option<OpenFileId> {
1668        let release =
1669            (captured.detfd.open_file_alias_count() == 1).then(|| captured.detfd.open_file_id());
1670        drop(captured);
1671        release
1672    }
1673}
1674
1675fn stdio_resource(fd: RawFd) -> Option<ResourceID> {
1676    match fd {
1677        0 => Some(ResourceID::Device(Device::ContainerStdin)),
1678        1 => Some(ResourceID::Device(Device::ContainerStdout)),
1679        2 => Some(ResourceID::Device(Device::ContainerStderr)),
1680        _ => None,
1681    }
1682}
1683
1684#[cfg(test)]
1685mod posix_timers_tests {
1686    use super::*;
1687
1688    fn t(ns: u64) -> LogicalTime {
1689        LogicalTime::from_nanos(ns)
1690    }
1691
1692    #[test]
1693    fn ids_are_deterministic_and_sequential() {
1694        let mut timers = PosixTimers::default();
1695        assert_eq!(timers.create(None, None, None), 0);
1696        assert_eq!(timers.create(Some(libc::SIGALRM), None, None), 1);
1697        assert_eq!(timers.create(None, None, None), 2);
1698    }
1699
1700    #[test]
1701    fn settime_reports_previous_arming_and_remaining_uses_virtual_clock() {
1702        let mut timers = PosixTimers::default();
1703        let id = timers.create(None, None, None);
1704
1705        // Arm a one-shot timer for 100ns at t=0. A freshly created timer was
1706        // disarmed, so the reported old value is zero.
1707        let old = timers.settime(id, 0, Some(t(100)), t(0)).expect("known id");
1708        assert_eq!(old, (0, 0));
1709
1710        // At t=40 there should be 60ns remaining and no interval.
1711        assert_eq!(timers.gettime(id, t(40)), Some((60, 0)));
1712        // Past the deadline the remaining time saturates at 0.
1713        assert_eq!(timers.gettime(id, t(150)), Some((0, 0)));
1714    }
1715
1716    #[test]
1717    fn resetting_reports_old_remaining() {
1718        let mut timers = PosixTimers::default();
1719        let id = timers.create(None, None, None);
1720        timers.settime(id, 0, Some(t(100)), t(0));
1721        // Re-arm at t=30 (70ns remained) with a periodic 50ns timer.
1722        let old = timers
1723            .settime(id, 50, Some(t(200)), t(30))
1724            .expect("known id");
1725        assert_eq!(old, (70, 0));
1726        assert_eq!(timers.gettime(id, t(30)), Some((170, 50)));
1727    }
1728
1729    // AUTONOMOUS-BOT-IMPLEMENTED
1730    // TODO-HUMAN-REVIEW(#869)
1731    #[test]
1732    fn periodic_remaining_advances_past_each_deadline() {
1733        let mut timers = PosixTimers::default();
1734        let id = timers.create(Some(libc::SIGALRM), None, None);
1735        timers.settime(id, 50, Some(t(100)), t(0));
1736
1737        assert_eq!(timers.gettime(id, t(100)), Some((50, 50)));
1738        assert_eq!(timers.gettime(id, t(125)), Some((25, 50)));
1739        assert_eq!(timers.gettime(id, t(150)), Some((50, 50)));
1740        assert_eq!(timers.signal(id), Some(Some(libc::SIGALRM)));
1741    }
1742
1743    #[test]
1744    fn disarm_and_unknown_ids() {
1745        let mut timers = PosixTimers::default();
1746        let id = timers.create(None, None, None);
1747        timers.settime(id, 0, Some(t(100)), t(0));
1748        // Disarm: value of 0 -> deadline None -> remaining 0.
1749        timers.settime(id, 0, None, t(10));
1750        assert_eq!(timers.gettime(id, t(10)), Some((0, 0)));
1751
1752        // Unknown ids are rejected.
1753        assert_eq!(timers.settime(99, 0, Some(t(1)), t(0)), None);
1754        assert_eq!(timers.gettime(99, t(0)), None);
1755        assert!(!timers.contains(99));
1756    }
1757
1758    #[test]
1759    fn delete_removes_timer() {
1760        let mut timers = PosixTimers::default();
1761        let id = timers.create(None, None, None);
1762        assert!(timers.contains(id));
1763        assert!(timers.remove(id));
1764        assert!(!timers.contains(id));
1765        // Deleting again fails.
1766        assert!(!timers.remove(id));
1767    }
1768}
1769
1770#[cfg(test)]
1771mod resource_limits_tests {
1772    use super::*;
1773
1774    #[test]
1775    fn defaults_are_fixed_and_cover_linux_resources() {
1776        let limits = ResourceLimits::default();
1777        assert_eq!(
1778            limits.get(libc::RLIMIT_STACK),
1779            Some(ResourceLimit {
1780                current: 8 * 1024 * 1024,
1781                maximum: libc::RLIM64_INFINITY,
1782            })
1783        );
1784        assert_eq!(
1785            limits.get(libc::RLIMIT_NOFILE),
1786            Some(ResourceLimit {
1787                current: 1_048_576,
1788                maximum: 1_048_576,
1789            })
1790        );
1791        assert_eq!(
1792            limits.get(libc::RLIMIT_CORE),
1793            Some(ResourceLimit {
1794                current: libc::RLIM64_INFINITY,
1795                maximum: libc::RLIM64_INFINITY,
1796            })
1797        );
1798        assert_eq!(limits.get(libc::RLIMIT_RTTIME + 1), None);
1799    }
1800
1801    #[test]
1802    fn cloned_process_state_changes_independently() {
1803        let parent = ResourceLimits::default();
1804        let mut child = parent.clone();
1805        let lowered = ResourceLimit {
1806            current: 1024,
1807            maximum: 1_048_576,
1808        };
1809        child.set(libc::RLIMIT_NOFILE, lowered);
1810
1811        assert_eq!(child.get(libc::RLIMIT_NOFILE), Some(lowered));
1812        assert_eq!(
1813            parent.get(libc::RLIMIT_NOFILE),
1814            Some(ResourceLimit {
1815                current: 1_048_576,
1816                maximum: 1_048_576,
1817            })
1818        );
1819    }
1820}
1821
1822#[cfg(test)]
1823mod file_metadata_tests {
1824    mod inherited_input;
1825    use std::os::fd::AsRawFd;
1826
1827    use super::*;
1828    use crate::pipe_wake::ChannelEnd;
1829    use crate::pipe_wake::ChannelId;
1830
1831    #[test]
1832    fn maps_exec_survivors_keep_opened_target_aliases_and_cursor() {
1833        use crate::procfs::BoundTask;
1834        use crate::procfs::MapsTarget;
1835        use crate::procfs::ProcfsFile;
1836        use crate::procfs::ProcfsSnapshotContext;
1837        use crate::procfs::TaskIncarnation;
1838
1839        let owner = DetTid::from_raw(9021);
1840        let config = Config::default();
1841        let mut parent = ThreadState::new(owner, &config, ());
1842        let maps = std::fs::File::open("/proc/self/maps").unwrap();
1843        let alias = maps.try_clone().unwrap();
1844        let closed = maps.try_clone().unwrap();
1845        let unread = std::fs::File::open("/proc/self/maps").unwrap();
1846        let fd = maps.as_raw_fd();
1847        let alias_fd = alias.as_raw_fd();
1848        let closed_fd = closed.as_raw_fd();
1849        let unread_fd = unread.as_raw_fd();
1850        let target = MapsTarget {
1851            task: BoundTask {
1852                process: 9021,
1853                thread: None,
1854            },
1855            incarnation: TaskIncarnation {
1856                process: 1,
1857                thread: None,
1858            },
1859            mm: MmId::initial(owner),
1860            private: reverie::RuntimePrivateMemorySnapshot {
1861                owner: [1, 2, 3, 4],
1862                version: 7,
1863                regions: vec![reverie::RuntimePrivateMemoryRegion {
1864                    start: 0x1000,
1865                    end: 0x2000,
1866                }],
1867            },
1868        };
1869        for number in [fd, unread_fd] {
1870            parent
1871                .add_fd(
1872                    number,
1873                    OFlag::O_RDONLY | OFlag::O_NONBLOCK,
1874                    FdType::Regular,
1875                    None,
1876                )
1877                .unwrap();
1878            let mut procfs = ProcfsFile::from_path(Path::new("/proc/self/maps")).unwrap();
1879            procfs.bind_maps_target(target.clone());
1880            parent
1881                .with_detfd(number, |handle| {
1882                    handle.set_path("/proc/self/maps");
1883                    handle.set_procfs(procfs.clone());
1884                })
1885                .unwrap();
1886        }
1887        parent.dup_fd(fd, alias_fd, OFlag::empty()).unwrap();
1888        parent.dup_fd(fd, closed_fd, OFlag::O_CLOEXEC).unwrap();
1889        parent
1890            .with_detfd(fd, |handle| {
1891                handle.initialize_procfs(
1892                    b"3000-4000 rw-p 00000000 00:00 0 \n".to_vec(),
1893                    ProcfsSnapshotContext::default(),
1894                );
1895                handle.commit_procfs_read(0, 7);
1896            })
1897            .unwrap();
1898        assert!(
1899            parent.maps_for_exec(None).unwrap().is_none(),
1900            "exec maps carry requires an advertised private-memory provider"
1901        );
1902        let transfer = parent
1903            .maps_for_exec(Some(&reverie::RuntimePrivateMemory::Unavailable))
1904            .unwrap()
1905            .unwrap();
1906        let ready_transfer = parent
1907            .maps_for_exec(Some(&reverie::RuntimePrivateMemory::Ready(
1908                target.private.clone(),
1909            )))
1910            .unwrap()
1911            .unwrap();
1912        assert!(ready_transfer == transfer);
1913        let original_preview = parent
1914            .with_detfd(fd, |h| h.preview_procfs(3))
1915            .unwrap()
1916            .unwrap();
1917        assert!(!transfer.handles.contains_key(&closed_fd));
1918        assert_eq!(
1919            transfer.handles[&fd].identity.id,
1920            transfer.handles[&alias_fd].identity.id
1921        );
1922        assert_ne!(
1923            transfer.handles[&fd].identity.id,
1924            transfer.handles[&unread_fd].identity.id
1925        );
1926        let old_id = transfer.handles[&fd].identity.id;
1927        let old_unread_id = transfer.handles[&unread_fd].identity.id;
1928        let next_sequence = transfer.next_sequence;
1929        let state = ExecFdState {
1930            maps: Some(transfer),
1931            ..ExecFdState::default()
1932        };
1933        assert!(!state.is_empty());
1934        // Exercise the actual serialized exec preparation/completion payload.
1935        let state: ExecFdState =
1936            serde_json::from_slice(&serde_json::to_vec(&state).unwrap()).unwrap();
1937        drop(state.clone()); // cancelled preparation leaves the original model alone
1938        assert_eq!(
1939            parent
1940                .with_detfd(fd, |h| h.procfs_position())
1941                .unwrap()
1942                .unwrap()
1943                .0,
1944            7
1945        );
1946        let receiving_tid = DetTid::from_raw(9022);
1947        let mut successor_thread = ThreadState::new(receiving_tid, &config, ());
1948        // The same creator choice used by the real exec-completion handler.
1949        assert_eq!(state.open_file_creator(), Some(owner));
1950        successor_thread.set_open_file_creator(state.open_file_creator().unwrap());
1951        let mut successor = successor_thread.metadata();
1952        successor
1953            .apply_exec_fd_state(receiving_tid, state.clone(), true)
1954            .unwrap();
1955        assert!(
1956            successor.file_handles.contains_key(&fd),
1957            "exec must retain maps provenance before lazy discovery"
1958        );
1959        assert!(!successor.file_handles.contains_key(&closed_fd));
1960        for number in [fd, alias_fd, unread_fd] {
1961            assert_eq!(
1962                successor.file_handles[&number].procfs_maps_target(),
1963                Some(target.clone())
1964            );
1965            assert!(successor.file_handles[&number].is_nonblocking());
1966        }
1967        assert_eq!(successor.file_handles[&fd].open_file_id(), old_id);
1968        assert_eq!(
1969            successor.file_handles[&unread_fd].open_file_id(),
1970            old_unread_id
1971        );
1972        assert_eq!(successor.file_handles[&fd].procfs_position().unwrap().0, 7);
1973        assert!(successor.file_handles[&unread_fd].procfs_needs_snapshot());
1974        let (offset, bytes) = successor.file_handles[&alias_fd].preview_procfs(3).unwrap();
1975        assert_eq!((offset, bytes.clone()), original_preview);
1976        successor.file_handles[&alias_fd].commit_procfs_read(offset, bytes.len());
1977        assert_eq!(successor.file_handles[&fd].procfs_position().unwrap().0, 10);
1978        assert_eq!(
1979            parent
1980                .with_detfd(fd, |h| h.procfs_position())
1981                .unwrap()
1982                .unwrap()
1983                .0,
1984            7
1985        );
1986        assert!(successor.next_open_file_sequence >= parent.metadata().next_open_file_sequence);
1987        drop(successor);
1988        let next = tempfile::tempfile().unwrap();
1989        successor_thread
1990            .add_fd(next.as_raw_fd(), OFlag::O_RDWR, FdType::Regular, None)
1991            .unwrap();
1992        assert_eq!(
1993            successor_thread
1994                .with_detfd(next.as_raw_fd(), |h| h.open_file_id())
1995                .unwrap(),
1996            OpenFileId::new(owner, next_sequence),
1997        );
1998        // A reused numeric slot cannot acquire the old target's authority.
1999        let replacement = tempfile::tempfile().unwrap();
2000        assert_eq!(
2001            unsafe { libc::dup2(replacement.as_raw_fd(), alias_fd) },
2002            alias_fd
2003        );
2004        assert_eq!(
2005            FileMetadata::new(owner).apply_exec_fd_state(owner, state, true),
2006            Err(Errno::EIO)
2007        );
2008    }
2009
2010    #[test]
2011    fn shared_exec_survivors_keep_aliases_and_allocator_after_closed_high_ids() {
2012        crate::fd::install_test_shared_open_file_channel();
2013        let creator = DetTid::from_raw(9011);
2014        let leader = DetTid::from_raw(9012);
2015        let config = Config::default();
2016        let mut parent = ThreadState::new(creator, &config, ());
2017        parent.set_open_file_creator(creator);
2018        parent.metadata().file_handles.clear();
2019        let file = std::fs::File::open("/dev/urandom").unwrap();
2020        let alias = nix::unistd::dup(&file).unwrap();
2021        let distinct = std::fs::File::open("/dev/urandom").unwrap();
2022        let cloexec = nix::unistd::dup(&file).unwrap();
2023        let (socket, _peer) = std::os::unix::net::UnixStream::pair().unwrap();
2024        let (fd, alias_fd, distinct_fd, closed_fd, socket_fd) = (
2025            file.as_raw_fd(),
2026            alias.as_raw_fd(),
2027            distinct.as_raw_fd(),
2028            cloexec.as_raw_fd(),
2029            socket.as_raw_fd(),
2030        );
2031        for fd in [fd, alias_fd, distinct_fd, socket_fd] {
2032            assert_eq!(unsafe { libc::fcntl(fd, libc::F_SETFD, 0) }, 0);
2033        }
2034        parent
2035            .add_fd(fd, OFlag::O_RDONLY, FdType::Rng, None)
2036            .unwrap();
2037        parent.dup_fd(fd, alias_fd, OFlag::empty()).unwrap();
2038        parent.dup_fd(fd, closed_fd, OFlag::O_CLOEXEC).unwrap();
2039        parent
2040            .add_fd(distinct_fd, OFlag::O_RDONLY, FdType::Rng, None)
2041            .unwrap();
2042        parent
2043            .add_fd(socket_fd, OFlag::O_RDWR, FdType::Socket, None)
2044            .unwrap();
2045        let first_id = parent.metadata().file_handles[&fd].open_file_id();
2046        let distinct_id = parent.metadata().file_handles[&distinct_fd].open_file_id();
2047        let old_socket_id = parent.metadata().file_handles[&socket_fd].open_file_id();
2048        assert_ne!(
2049            first_id, distinct_id,
2050            "same inode does not identify one OFD"
2051        );
2052        parent.metadata().file_handles[&fd]
2053            .with_random_device_stream::<Errno>(|offset| {
2054                assert_eq!(offset, 0);
2055                Ok(7)
2056            })
2057            .unwrap();
2058        // Closed and CLOEXEC descriptions still consume allocator identities.
2059        let high = parent
2060            .metadata()
2061            .allocate_open_file_id(creator, FdType::Rng);
2062        let high_socket = parent
2063            .metadata()
2064            .allocate_open_file_id(creator, FdType::Socket);
2065        parent.promote_shared_open_files().unwrap();
2066        assert!(!parent.metadata().file_handles[&socket_fd].is_shared());
2067        let transfer = parent.shared_open_files_for_exec().unwrap().unwrap();
2068        assert_eq!(transfer.creator, creator);
2069        assert!(!transfer.handles.contains_key(&closed_fd));
2070        assert!(!transfer.handles.contains_key(&socket_fd));
2071        assert_eq!(transfer.handles[&fd].id, transfer.handles[&alias_fd].id);
2072        // Dropping a cancelled preparation cannot change any cursor.
2073        drop(transfer.clone());
2074        parent.metadata().file_handles[&fd]
2075            .with_random_device_stream::<Errno>(|offset| {
2076                assert_eq!(offset, 7);
2077                Ok(0)
2078            })
2079            .unwrap();
2080
2081        // A genuinely replaced descriptor must not acquire a survivor's ID.
2082        // This owns only a duplicate, never one of the test process's stdio FDs.
2083        let replacement = tempfile::tempfile().unwrap();
2084        assert_eq!(
2085            unsafe { libc::dup2(replacement.as_raw_fd(), alias_fd) },
2086            alias_fd
2087        );
2088        assert_eq!(
2089            FileMetadata::new(leader).apply_exec_fd_state(
2090                leader,
2091                ExecFdState {
2092                    open_files: Some(transfer.clone()),
2093                    ..ExecFdState::default()
2094                },
2095                true,
2096            ),
2097            Err(Errno::EIO),
2098        );
2099        assert_eq!(unsafe { libc::dup2(fd, alias_fd) }, alias_fd);
2100
2101        let mut successor = ThreadState::new(leader, &config, ());
2102        // Preserve the new image's existing nonrandom association. The handover
2103        // must not restore the old socket ID used by ReleasePort bookkeeping.
2104        successor
2105            .add_fd(socket_fd, OFlag::O_RDWR, FdType::Socket, None)
2106            .unwrap();
2107        let new_socket_id = successor.metadata().file_handles[&socket_fd].open_file_id();
2108        assert_ne!(old_socket_id, new_socket_id);
2109        let stdio_ids: Vec<_> = (0..=2)
2110            .map(|fd| successor.metadata().file_handles[&fd].open_file_id())
2111            .collect();
2112        successor.set_open_file_creator(transfer.creator);
2113        successor
2114            .metadata()
2115            .apply_exec_fd_state(
2116                creator,
2117                ExecFdState {
2118                    open_files: Some(transfer),
2119                    ..ExecFdState::default()
2120                },
2121                true,
2122            )
2123            .unwrap();
2124        assert!(!successor.metadata().file_handles.contains_key(&closed_fd));
2125        assert_eq!(
2126            successor.metadata().file_handles[&socket_fd].open_file_id(),
2127            new_socket_id
2128        );
2129        assert!(!successor.metadata().file_handles[&socket_fd].is_shared());
2130        assert_eq!(
2131            (0..=2)
2132                .map(|fd| successor.metadata().file_handles[&fd].open_file_id())
2133                .collect::<Vec<_>>(),
2134            stdio_ids
2135        );
2136        successor.metadata().file_handles[&alias_fd]
2137            .with_random_device_stream::<Errno>(|offset| {
2138                assert_eq!(offset, 7);
2139                Ok(5)
2140            })
2141            .unwrap();
2142        parent.metadata().file_handles[&fd]
2143            .with_random_device_stream::<Errno>(|offset| {
2144                assert_eq!(offset, 12);
2145                Ok(0)
2146            })
2147            .unwrap();
2148        successor.metadata().file_handles[&distinct_fd]
2149            .with_random_device_stream::<Errno>(|offset| {
2150                assert_eq!(offset, 0);
2151                Ok(0)
2152            })
2153            .unwrap();
2154        successor.remove_fd(fd);
2155        successor
2156            .add_fd(fd, OFlag::O_RDONLY, FdType::Rng, None)
2157            .unwrap();
2158        let reopened = successor.metadata().file_handles[&fd].open_file_id();
2159        assert_ne!(reopened, first_id);
2160        assert_ne!(reopened, high);
2161        assert_eq!(
2162            reopened,
2163            OpenFileId::new(creator, successor.metadata().next_open_file_sequence - 1)
2164        );
2165        assert_ne!(
2166            successor
2167                .metadata()
2168                .allocate_open_file_id(creator, FdType::Socket),
2169            high_socket
2170        );
2171        successor.promote_shared_open_files().unwrap();
2172        let second = successor.shared_open_files_for_exec().unwrap().unwrap();
2173        assert_eq!(
2174            second.creator, creator,
2175            "nonleader creator survives repeated exec"
2176        );
2177        let mut again = FileMetadata::new(leader);
2178        again
2179            .apply_exec_fd_state(
2180                creator,
2181                ExecFdState {
2182                    open_files: Some(second),
2183                    ..ExecFdState::default()
2184                },
2185                true,
2186            )
2187            .unwrap();
2188        assert_eq!(again.file_handles[&fd].open_file_id(), reopened);
2189        again.file_handles[&alias_fd]
2190            .with_random_device_stream::<Errno>(|offset| {
2191                assert_eq!(offset, 12);
2192                Ok(0)
2193            })
2194            .unwrap();
2195
2196        // No surviving RNG descriptor does not mean its old identities are free.
2197        for fd in [fd, alias_fd, distinct_fd] {
2198            successor.remove_fd(fd);
2199        }
2200        let empty = successor.shared_open_files_for_exec().unwrap().unwrap();
2201        assert!(empty.handles.is_empty());
2202        let next_sequence = empty.next_sequence;
2203        let mut after_close = ThreadState::new(leader, &config, ());
2204        after_close.set_open_file_creator(empty.creator);
2205        after_close
2206            .metadata()
2207            .apply_exec_fd_state(
2208                creator,
2209                ExecFdState {
2210                    open_files: Some(empty),
2211                    ..ExecFdState::default()
2212                },
2213                true,
2214            )
2215            .unwrap();
2216        after_close
2217            .add_fd(fd, OFlag::O_RDONLY, FdType::Rng, None)
2218            .unwrap();
2219        assert_eq!(
2220            after_close.metadata().file_handles[&fd].open_file_id(),
2221            OpenFileId::new(creator, next_sequence)
2222        );
2223        // The canonical store still owns all old models: reusing an ID refuses.
2224        after_close.promote_shared_open_files().unwrap();
2225    }
2226
2227    #[test]
2228    fn shared_random_promotion_leaves_nonrandom_tables_local() {
2229        let state = ThreadState::new(DetTid::from_raw(9013), &Config::default(), ());
2230        let regular = tempfile::tempfile().unwrap();
2231        let (socket, _peer) = std::os::unix::net::UnixStream::pair().unwrap();
2232        state
2233            .add_fd(regular.as_raw_fd(), OFlag::O_RDWR, FdType::Regular, None)
2234            .unwrap();
2235        state
2236            .add_fd(socket.as_raw_fd(), OFlag::O_RDWR, FdType::Socket, None)
2237            .unwrap();
2238        let before: HashMap<_, _> = state
2239            .metadata()
2240            .file_handles
2241            .iter()
2242            .map(|(&fd, handle)| (fd, handle.open_file_id()))
2243            .collect();
2244        state.promote_shared_open_files().unwrap();
2245        assert!(state.shared_open_files_for_exec().unwrap().is_none());
2246        for (fd, id) in before {
2247            let metadata = state.metadata();
2248            let handle = &metadata.file_handles[&fd];
2249            assert!(!handle.is_shared());
2250            assert_eq!(handle.open_file_id(), id);
2251        }
2252    }
2253
2254    #[test]
2255    fn shared_exec_restores_allocator_before_legacy_pipe_discovery() {
2256        crate::fd::install_test_shared_open_file_channel();
2257        let owner = DetTid::from_raw(9014);
2258        let config = Config::default();
2259        let parent = ThreadState::new(owner, &config, ());
2260        let random = std::fs::File::open("/dev/random").unwrap();
2261        let fd = random.as_raw_fd();
2262        assert_eq!(unsafe { libc::fcntl(fd, libc::F_SETFD, 0) }, 0);
2263        parent
2264            .add_fd(fd, OFlag::O_RDONLY, FdType::Rng, None)
2265            .unwrap();
2266        parent.promote_shared_open_files().unwrap();
2267        let transfer = parent.shared_open_files_for_exec().unwrap().unwrap();
2268        let random_id = transfer.handles[&fd].id;
2269        let old_next = transfer.next_sequence;
2270        let (pipe, _writer) = nix::unistd::pipe2(OFlag::O_NONBLOCK).unwrap();
2271        let pipe_fd = pipe.as_raw_fd();
2272        let successor = ThreadState::new(owner, &config, ());
2273        successor
2274            .metadata()
2275            .apply_exec_fd_state(
2276                owner,
2277                ExecFdState {
2278                    blocking: [pipe_fd].into_iter().collect(),
2279                    open_files: Some(transfer),
2280                    ..ExecFdState::default()
2281                },
2282                true,
2283            )
2284            .unwrap();
2285        let mut metadata = successor.metadata();
2286        let pipe_id = metadata.file_handles[&pipe_fd].open_file_id();
2287        assert_eq!(pipe_id, OpenFileId::new(owner, old_next));
2288        assert_ne!(pipe_id, random_id);
2289        assert_eq!(metadata.file_handles[&pipe_fd].ty(), FdType::Pipe);
2290        assert!(!metadata.file_handles[&pipe_fd].is_nonblocking());
2291        assert!(metadata.file_handles[&pipe_fd].physically_nonblocking());
2292        assert!(!metadata.file_handles[&pipe_fd].is_shared());
2293        assert_eq!(metadata.file_handles[&fd].open_file_id(), random_id);
2294        assert_ne!(
2295            metadata.allocate_open_file_id(owner, FdType::Regular),
2296            pipe_id
2297        );
2298        // Interning must never merge the unrelated restored pipe and RNG.
2299        crate::fd::intern_open_files(&mut metadata.file_handles);
2300        assert_eq!(metadata.file_handles[&pipe_fd].ty(), FdType::Pipe);
2301        assert_eq!(metadata.file_handles[&fd].ty(), FdType::Rng);
2302    }
2303
2304    /// The channel end of a pipe made through `ThreadState::add_fd`, as
2305    /// `handle_pipe2` stores it on the read end under `--pipe-wake-latency`.
2306    fn pipe_with_channel(
2307        state: &ThreadState<()>,
2308    ) -> (std::os::fd::OwnedFd, std::os::fd::OwnedFd, ChannelEnd) {
2309        let (reader, writer) = nix::unistd::pipe2(OFlag::empty()).unwrap();
2310        state
2311            .add_fd(reader.as_raw_fd(), OFlag::O_RDONLY, FdType::Pipe, None)
2312            .unwrap();
2313        let id = state.metadata().file_handles[&reader.as_raw_fd()].open_file_id();
2314        let end = ChannelEnd {
2315            channel: ChannelId::Pipe(id),
2316            reads: true,
2317            writes: false,
2318        };
2319        state
2320            .with_detfd(reader.as_raw_fd(), |detfd| detfd.set_channel(end))
2321            .unwrap();
2322        (reader, writer, end)
2323    }
2324
2325    /// A channel lives on the open file description, so a `dup` and a forked
2326    /// child's copy of the table carry it with no copy step, while a
2327    /// descriptor Detcore discovers afresh, as it does one it did not create
2328    /// (one received over `SCM_RIGHTS`), has none
2329    /// (<https://github.com/rrnewton/hermit/issues/4380>).
2330    #[test]
2331    fn a_pipe_channel_follows_its_description_through_dup_and_fork() {
2332        let owner = DetTid::from_raw(9018);
2333        let mut parent = FileMetadata::new(owner);
2334        let (reader, _writer) = nix::unistd::pipe2(OFlag::empty()).unwrap();
2335        let fd = reader.as_raw_fd();
2336        parent
2337            .add_fd(owner, fd, OFlag::empty(), FdType::Pipe, None)
2338            .unwrap();
2339        let end = ChannelEnd {
2340            channel: ChannelId::Pipe(parent.with_detfd(fd, |detfd| detfd.open_file_id()).unwrap()),
2341            reads: true,
2342            writes: false,
2343        };
2344        parent
2345            .with_detfd(fd, |detfd| detfd.set_channel(end))
2346            .unwrap();
2347        let alias = fd + 100;
2348        parent.dup_fd(fd, alias, OFlag::empty()).unwrap();
2349        assert_eq!(
2350            parent.with_detfd(alias, |detfd| detfd.channel()).unwrap(),
2351            Some(end)
2352        );
2353        let mut child = parent.fork_for(DetTid::from_raw(9019));
2354        for fd in [fd, alias] {
2355            assert_eq!(
2356                child.with_detfd(fd, |detfd| detfd.channel()).unwrap(),
2357                Some(end)
2358            );
2359        }
2360        let (received, _peer) = nix::unistd::pipe2(OFlag::empty()).unwrap();
2361        parent
2362            .discover_fd_from_current_process(owner, received.as_raw_fd())
2363            .unwrap();
2364        assert_eq!(
2365            parent
2366                .with_detfd(received.as_raw_fd(), |detfd| detfd.channel())
2367                .unwrap(),
2368            None
2369        );
2370    }
2371
2372    /// Under `--pipe-wake-latency` a rediscovering exec carries each surviving
2373    /// descriptor's channel end and the old numbering. The same leader, whose
2374    /// new image restarts its open-file sequence, rediscovers pipe A with A's
2375    /// channel; a pipe B it then makes, past every id the old table allocated,
2376    /// has another channel value. A descriptor left `O_NONBLOCK`, outside the
2377    /// blocking set, gets its channel too
2378    /// (https://github.com/rrnewton/hermit/issues/4380).
2379    #[test]
2380    fn a_rediscovering_exec_keeps_pipe_channels_apart() {
2381        let leader = DetTid::from_raw(9015);
2382        let config = Config::default();
2383        let before = ThreadState::new(leader, &config, ());
2384        let (a_reader, _a_writer, a_end) = pipe_with_channel(&before);
2385        assert_eq!(
2386            unsafe { libc::fcntl(a_reader.as_raw_fd(), libc::F_SETFL, libc::O_NONBLOCK) },
2387            0
2388        );
2389        let channels = before.pipe_channels_for_exec();
2390        assert_eq!(channels, BTreeMap::from([(a_reader.as_raw_fd(), a_end)]));
2391        let namespace = before.open_file_namespace_for_exec();
2392        assert_eq!(
2393            namespace,
2394            (leader, before.metadata().next_open_file_sequence)
2395        );
2396
2397        let after = ThreadState::new(leader, &config, ());
2398        after
2399            .metadata()
2400            .apply_exec_fd_state(
2401                leader,
2402                ExecFdState {
2403                    channels,
2404                    open_file_namespace: Some(namespace),
2405                    ..ExecFdState::default()
2406                },
2407                true,
2408            )
2409            .unwrap();
2410        assert_eq!(
2411            after
2412                .with_detfd(a_reader.as_raw_fd(), |detfd| detfd.channel())
2413                .unwrap(),
2414            Some(a_end),
2415            "the carried channel survives rediscovery"
2416        );
2417        let (b_reader, _b_writer, b_end) = pipe_with_channel(&after);
2418        assert_ne!(b_end.channel, a_end.channel);
2419        let metadata = after.metadata();
2420        assert_ne!(
2421            metadata.file_handles[&b_reader.as_raw_fd()].open_file_id(),
2422            metadata.file_handles[&a_reader.as_raw_fd()].open_file_id()
2423        );
2424    }
2425
2426    /// A channel held by another process is kept apart too: the old image
2427    /// made pipe A, a child holds it, and the exec carries no channel at all;
2428    /// the old numbering is still reserved, so a pipe the new image makes
2429    /// cannot take A's id.
2430    #[test]
2431    fn an_exec_carrying_no_channel_still_reserves_the_old_numbering() {
2432        let leader = DetTid::from_raw(9016);
2433        let config = Config::default();
2434        let before = ThreadState::new(leader, &config, ());
2435        let (a_reader, _a_writer, a_end) = pipe_with_channel(&before);
2436        let namespace = before.open_file_namespace_for_exec();
2437        drop(a_reader);
2438
2439        let after = ThreadState::new(leader, &config, ());
2440        let state = ExecFdState {
2441            open_file_namespace: Some(namespace),
2442            ..ExecFdState::default()
2443        };
2444        assert!(
2445            !state.is_empty(),
2446            "a namespace-only state survives reconnect"
2447        );
2448        after
2449            .metadata()
2450            .apply_exec_fd_state(leader, state, true)
2451            .unwrap();
2452        let (_b_reader, _b_writer, b_end) = pipe_with_channel(&after);
2453        assert_ne!(b_end.channel, a_end.channel);
2454    }
2455
2456    /// With the option off the exec state carries neither field: nothing is
2457    /// reserved, the new image numbers as a fresh one does, and the state's
2458    /// trace prints as it did before the fields existed. A channel-only state
2459    /// is not empty.
2460    #[test]
2461    fn an_exec_without_the_pipe_wake_latency_is_unchanged() {
2462        let leader = DetTid::from_raw(9017);
2463        let config = Config::default();
2464        let after = ThreadState::new(leader, &config, ());
2465        let state = ExecFdState::default();
2466        assert!(state.is_empty());
2467        assert_eq!(
2468            format!("{state:?}"),
2469            "ExecFdState { blocking: {}, inherited_reads: {}, \
2470             initialize_inherited_stdio: false, initial_input: None, \
2471             robust_wakes: [], open_files: None }"
2472        );
2473        after
2474            .metadata()
2475            .apply_exec_fd_state(leader, state, true)
2476            .unwrap();
2477        let (reader, _writer, _) = pipe_with_channel(&after);
2478        let fresh = ThreadState::new(leader, &config, ());
2479        let (fresh_reader, _fresh_writer, _) = pipe_with_channel(&fresh);
2480        assert_eq!(
2481            after.metadata().file_handles[&reader.as_raw_fd()].open_file_id(),
2482            fresh.metadata().file_handles[&fresh_reader.as_raw_fd()].open_file_id()
2483        );
2484        let channel_only = ExecFdState {
2485            channels: BTreeMap::from([(
2486                reader.as_raw_fd(),
2487                ChannelEnd {
2488                    channel: ChannelId::Pipe(OpenFileId::new(leader, 0)),
2489                    reads: true,
2490                    writes: false,
2491                },
2492            )]),
2493            ..ExecFdState::default()
2494        };
2495        assert!(!channel_only.is_empty());
2496        assert!(format!("{channel_only:?}").contains("channels: {"));
2497
2498        // A description prints its channel only when it has one.
2499        let (plain, _plain_writer) = nix::unistd::pipe2(OFlag::empty()).unwrap();
2500        after
2501            .add_fd(plain.as_raw_fd(), OFlag::O_RDONLY, FdType::Pipe, None)
2502            .unwrap();
2503        let printed = format!("{:?}", after.metadata().file_handles[&plain.as_raw_fd()]);
2504        assert!(!printed.contains(" channel:"), "{printed}");
2505        assert!(printed.contains("timerfd: None }"), "{printed}");
2506        let printed = format!("{:?}", after.metadata().file_handles[&reader.as_raw_fd()]);
2507        assert!(
2508            printed.contains("timerfd: None, channel: ChannelEnd {"),
2509            "{printed}"
2510        );
2511    }
2512
2513    fn terminal_pair() -> (std::os::fd::OwnedFd, std::os::fd::OwnedFd) {
2514        use std::os::fd::FromRawFd;
2515        let (mut master, mut slave) = (-1, -1);
2516        assert_eq!(
2517            unsafe {
2518                libc::openpty(
2519                    &raw mut master,
2520                    &raw mut slave,
2521                    std::ptr::null_mut(),
2522                    std::ptr::null(),
2523                    std::ptr::null(),
2524                )
2525            },
2526            0
2527        );
2528        unsafe {
2529            (
2530                std::os::fd::OwnedFd::from_raw_fd(master),
2531                std::os::fd::OwnedFd::from_raw_fd(slave),
2532            )
2533        }
2534    }
2535
2536    #[test]
2537    fn inherited_terminal_discovery_keeps_kernel_flags_and_nonterminal_types() {
2538        let owner = DetTid::from_raw(9);
2539        let (_master, slave) = terminal_pair();
2540        let regular = tempfile::tempfile().unwrap();
2541        let zero = std::fs::File::open("/dev/zero").unwrap();
2542        let null = std::fs::File::open("/dev/null").unwrap();
2543        let (pipe, _writer) = nix::unistd::pipe().unwrap();
2544        let fds = [
2545            slave.as_raw_fd(),
2546            regular.as_raw_fd(),
2547            zero.as_raw_fd(),
2548            null.as_raw_fd(),
2549            pipe.as_raw_fd(),
2550        ];
2551        let before: Vec<_> = fds
2552            .iter()
2553            .map(|fd| unsafe {
2554                (
2555                    libc::fcntl(*fd, libc::F_GETFL),
2556                    libc::fcntl(*fd, libc::F_GETFD),
2557                )
2558            })
2559            .collect();
2560        let mut metadata = FileMetadata::new(owner);
2561        for fd in fds {
2562            metadata
2563                .discover_fd_from_current_process(owner, fd)
2564                .unwrap();
2565        }
2566        metadata.discover_inherited_terminals(fds);
2567        for (index, fd) in fds.into_iter().enumerate() {
2568            let detfd = &metadata.file_handles[&fd];
2569            assert_eq!(detfd.inherited_external_read().is_some(), index == 0);
2570            assert_eq!(
2571                detfd.ty(),
2572                if index == 4 {
2573                    FdType::Pipe
2574                } else {
2575                    FdType::Regular
2576                }
2577            );
2578            assert_eq!(
2579                unsafe {
2580                    (
2581                        libc::fcntl(fd, libc::F_GETFL),
2582                        libc::fcntl(fd, libc::F_GETFD),
2583                    )
2584                },
2585                before[index]
2586            );
2587        }
2588    }
2589
2590    /// A memfd named and sealed as a `/proc/cpuinfo` placeholder, met by a
2591    /// table that rediscovers descriptors before the session's answer (an
2592    /// in-guest backend's image after `exec`), is a placeholder only once the
2593    /// session says it renders the file. With CPUID virtualized but not
2594    /// intercepted (SaBRe), `Detcore::rendered_files` says it does not, and
2595    /// the memfd stays the ordinary memfd it is (Codex and
2596    /// deterministic-scheduling review of
2597    /// https://github.com/rrnewton/hermit/issues/4213).
2598    #[test]
2599    fn a_cpuinfo_placeholder_waits_for_the_sessions_answer() {
2600        let owner = DetTid::from_raw(9);
2601        let forged = || {
2602            // SAFETY: the name is NUL-terminated; the result is checked.
2603            let raw = unsafe {
2604                libc::memfd_create(
2605                    c"hermit-procfs:/proc/cpuinfo@".as_ptr(),
2606                    libc::MFD_ALLOW_SEALING,
2607                )
2608            };
2609            assert!(
2610                raw >= 0,
2611                "memfd_create: {}",
2612                std::io::Error::last_os_error()
2613            );
2614            // SAFETY: `raw` is a descriptor this test just made and owns.
2615            let fd = unsafe { <std::os::fd::OwnedFd as std::os::fd::FromRawFd>::from_raw_fd(raw) };
2616            let seals = crate::syscalls::rendered_procfs::PLACEHOLDER_SEALS;
2617            assert_eq!(unsafe { libc::fcntl(raw, libc::F_ADD_SEALS, seals) }, 0);
2618            fd
2619        };
2620        let ordinary = |metadata: &FileMetadata, fd: RawFd| {
2621            metadata.file_handles[&fd].procfs_rendered_path().is_none()
2622        };
2623        // The session does not render /proc/cpuinfo (CPUID virtualized by
2624        // the configuration, but the backend delivers no CPUID to Detcore).
2625        let fd = forged();
2626        let mut metadata = FileMetadata::new(owner);
2627        metadata
2628            .discover_fd_from_current_process(owner, fd.as_raw_fd())
2629            .unwrap();
2630        assert!(ordinary(&metadata, fd.as_raw_fd()));
2631        metadata.decide_cpuinfo_placeholders(false).unwrap();
2632        assert!(ordinary(&metadata, fd.as_raw_fd()));
2633        // Once decided, a later descriptor is not one either.
2634        let later = forged();
2635        metadata
2636            .discover_fd_from_current_process(owner, later.as_raw_fd())
2637            .unwrap();
2638        assert!(ordinary(&metadata, later.as_raw_fd()));
2639        // A later answer of the same session changes nothing.
2640        metadata.decide_cpuinfo_placeholders(true).unwrap();
2641        assert!(ordinary(&metadata, fd.as_raw_fd()));
2642        // The session renders it: the waiting descriptor becomes the
2643        // placeholder, and so is one met after the answer.
2644        let mut metadata = FileMetadata::new(owner);
2645        metadata
2646            .discover_fd_from_current_process(owner, fd.as_raw_fd())
2647            .unwrap();
2648        assert!(ordinary(&metadata, fd.as_raw_fd()));
2649        metadata.decide_cpuinfo_placeholders(true).unwrap();
2650        assert_eq!(
2651            metadata.file_handles[&fd.as_raw_fd()].procfs_rendered_path(),
2652            Some(std::path::Path::new("/proc/cpuinfo"))
2653        );
2654        let after = forged();
2655        metadata
2656            .discover_fd_from_current_process(owner, after.as_raw_fd())
2657            .unwrap();
2658        assert_eq!(
2659            metadata.file_handles[&after.as_raw_fd()].procfs_rendered_path(),
2660            Some(std::path::Path::new("/proc/cpuinfo"))
2661        );
2662    }
2663
2664    #[test]
2665    fn inherited_terminal_aliases_survive_fork_serialization_and_exec_handoff() {
2666        use std::os::fd::FromRawFd;
2667        let owner = DetTid::from_raw(9);
2668        let (_master, slave) = terminal_pair();
2669        let fd = slave.as_raw_fd();
2670        let duplicate = unsafe { libc::fcntl(fd, libc::F_DUPFD_CLOEXEC, 3) };
2671        assert!(duplicate >= 0);
2672        let duplicate = unsafe { std::os::fd::OwnedFd::from_raw_fd(duplicate) };
2673        let alias = duplicate.as_raw_fd();
2674        // Make this alias survive the real descriptor boundary as the model does.
2675        assert_eq!(unsafe { libc::fcntl(alias, libc::F_SETFD, 0) }, 0);
2676        let mut metadata = FileMetadata::new(owner);
2677        metadata
2678            .discover_fd_from_current_process(owner, fd)
2679            .unwrap();
2680        metadata.file_handles[&fd].set_resource(ResourceID::Device(Device::ContainerStdin));
2681        metadata.discover_inherited_terminals([fd]);
2682        metadata.dup_fd(fd, alias, OFlag::empty()).unwrap();
2683        metadata.dup_fd(fd, 100_000, OFlag::O_CLOEXEC).unwrap();
2684        let child = metadata.fork_for(DetTid::from_raw(10));
2685        let encoded = serde_json::to_vec(&child).unwrap();
2686        let child: FileMetadata = serde_json::from_slice(&encoded).unwrap();
2687        let state = ExecFdState {
2688            inherited_reads: child.inherited_reads_for_exec(),
2689            ..Default::default()
2690        };
2691        assert_eq!(
2692            state.inherited_reads.len(),
2693            2,
2694            "CLOEXEC alias is not transferred"
2695        );
2696        assert_eq!(state.inherited_reads[&fd], state.inherited_reads[&alias]);
2697        let mut restored = FileMetadata::new(owner);
2698        restored
2699            .apply_exec_fd_state(
2700                owner,
2701                serde_json::from_slice(&serde_json::to_vec(&state).unwrap()).unwrap(),
2702                true,
2703            )
2704            .unwrap();
2705        assert_eq!(
2706            restored.file_handles[&fd].open_file_id(),
2707            restored.file_handles[&alias].open_file_id()
2708        );
2709        assert_eq!(
2710            restored.file_handles[&alias].resource(),
2711            Some(ResourceID::Device(Device::ContainerStdin))
2712        );
2713        let flags = unsafe { libc::fcntl(alias, libc::F_GETFL) };
2714        assert_eq!(
2715            unsafe { libc::fcntl(alias, libc::F_SETFL, flags | libc::O_NONBLOCK) },
2716            0
2717        );
2718        restored.file_handles[&alias].set_status_flags(flags | libc::O_NONBLOCK);
2719        assert!(restored.file_handles[&fd].is_nonblocking());
2720        assert!(restored.file_handles[&fd].physically_nonblocking());
2721        assert_eq!(
2722            unsafe { libc::fcntl(fd, libc::F_GETFL) },
2723            flags | libc::O_NONBLOCK
2724        );
2725        let mut byte = 0_u8;
2726        assert_eq!(unsafe { libc::read(fd, (&raw mut byte).cast(), 1) }, -1);
2727        assert_eq!(Errno::last(), Errno::EAGAIN);
2728    }
2729
2730    #[test]
2731    fn guest_created_terminal_and_reused_descriptor_do_not_gain_inherited_provenance() {
2732        let owner = DetTid::from_raw(9);
2733        let (_master, slave) = terminal_pair();
2734        let fd = slave.as_raw_fd();
2735        let mut guest_created = FileMetadata::new(owner);
2736        guest_created
2737            .discover_fd_from_current_process(owner, fd)
2738            .unwrap();
2739        guest_created.dup_fd(fd, 0, OFlag::empty()).unwrap();
2740        assert!(guest_created.inherited_reads_for_exec().is_empty());
2741        let mut fresh = FileMetadata::new(owner);
2742        fresh
2743            .apply_exec_fd_state(owner, ExecFdState::default(), true)
2744            .unwrap();
2745        fresh.discover_fd_from_current_process(owner, fd).unwrap();
2746        assert!(fresh.file_handles[&fd].inherited_external_read().is_none());
2747
2748        guest_created.discover_inherited_terminals([fd]);
2749        let state = ExecFdState {
2750            inherited_reads: guest_created.inherited_reads_for_exec(),
2751            ..Default::default()
2752        };
2753        // Remove the synthetic slot; only the actual owned fd enters this check.
2754        let state = ExecFdState {
2755            inherited_reads: state
2756                .inherited_reads
2757                .into_iter()
2758                .filter(|(number, _)| *number == fd)
2759                .collect(),
2760            ..Default::default()
2761        };
2762        guest_created.remove_fd(fd);
2763        let zero = std::fs::File::open("/dev/zero").unwrap();
2764        assert_eq!(unsafe { libc::dup2(zero.as_raw_fd(), fd) }, fd);
2765        let mut reused = FileMetadata::new(owner);
2766        assert_eq!(
2767            reused.apply_exec_fd_state(owner, state, true),
2768            Err(Errno::EIO)
2769        );
2770        assert!(reused.file_handles[&fd].inherited_external_read().is_none());
2771    }
2772
2773    #[test]
2774    fn on_demand_discovery_finds_a_live_descriptor() {
2775        let owner = DetTid::from_raw(9);
2776        let file = tempfile::NamedTempFile::new().expect("create test descriptor");
2777        let fd = file.as_raw_fd();
2778        assert_eq!(unsafe { libc::flock(fd, libc::LOCK_SH | libc::LOCK_NB) }, 0);
2779        let mut metadata = FileMetadata::new(owner);
2780
2781        assert_eq!(metadata.with_detfd(fd, |_| ()), Err(Errno::EBADF));
2782        metadata
2783            .discover_fd_from_current_process(owner, fd)
2784            .expect("live descriptor should be discovered");
2785        assert_eq!(
2786            metadata
2787                .with_detfd(fd, |detfd| detfd.ty())
2788                .expect("discovered descriptor should be tracked"),
2789            FdType::Regular
2790        );
2791        assert_eq!(
2792            metadata
2793                .with_detfd(fd, |detfd| detfd.known_flock_mode())
2794                .expect("discovered descriptor should be tracked"),
2795            None,
2796            "a live descriptor may already hold a flock that Detcore did not observe"
2797        );
2798        assert!(
2799            !metadata
2800                .with_detfd(fd, |detfd| detfd.flock_mode_may_be_stale())
2801                .expect("discovered descriptor should be tracked"),
2802            "first discovery must not invent a previously known lock state"
2803        );
2804        assert!(
2805            !metadata.has_unsafe_vfork_flock_state(),
2806            "never-observed history is distinct from a held or invalidated cached claim"
2807        );
2808
2809        // The metadata repair must not query by converting or dropping the
2810        // inherited lock. A separate open must still be excluded by it.
2811        let separate = std::fs::OpenOptions::new()
2812            .read(true)
2813            .write(true)
2814            .open(file.path())
2815            .expect("open an independent file description");
2816        assert_eq!(
2817            unsafe { libc::flock(separate.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) },
2818            -1
2819        );
2820        assert_eq!(Errno::last(), Errno::EWOULDBLOCK);
2821
2822        metadata
2823            .with_detfd(fd, |detfd| detfd.set_flock_mode(None))
2824            .expect("discovered descriptor should remain tracked");
2825        assert_eq!(metadata.file_handles[&fd].known_flock_mode(), None);
2826        assert!(!metadata.file_handles[&fd].flock_mode_may_be_stale());
2827    }
2828
2829    #[test]
2830    fn rediscovery_preserves_known_and_invalidated_flock_history() {
2831        let owner = DetTid::from_raw(9);
2832        let file = tempfile::tempfile().expect("create test descriptor");
2833        let fd = file.as_raw_fd();
2834        let mut metadata = FileMetadata::new(owner);
2835        metadata
2836            .add_fd(owner, fd, OFlag::O_RDWR, FdType::Regular, None)
2837            .expect("register an observed open");
2838        let description = metadata.file_handles[&fd].open_file_id();
2839        assert_eq!(metadata.file_handles[&fd].known_flock_mode(), Some(None));
2840        metadata.file_handles[&fd].set_flock_mode(Some(libc::LOCK_SH));
2841
2842        metadata
2843            .discover_fd_from_current_process(owner, fd)
2844            .expect("rediscover an existing descriptor");
2845        assert_eq!(metadata.file_handles[&fd].open_file_id(), description);
2846        assert_eq!(
2847            metadata.file_handles[&fd].known_flock_mode(),
2848            Some(Some(libc::LOCK_SH))
2849        );
2850        assert!(metadata.has_unsafe_vfork_flock_state());
2851
2852        metadata.file_handles[&fd].forget_flock_mode();
2853        metadata
2854            .discover_fd_from_current_process(owner, fd)
2855            .expect("rediscover an invalidated descriptor");
2856        assert_eq!(metadata.file_handles[&fd].open_file_id(), description);
2857        assert_eq!(metadata.file_handles[&fd].known_flock_mode(), None);
2858        assert!(metadata.file_handles[&fd].flock_mode_may_be_stale());
2859        assert!(metadata.has_unsafe_vfork_flock_state());
2860    }
2861
2862    /// A table carried through serialization (in-guest LiteInst's fork) keeps
2863    /// its aliases: two descriptors that shared one open file description
2864    /// before still share one object after, while a separate open stays
2865    /// separate and descriptor flags stay per descriptor.
2866    #[test]
2867    fn a_deserialized_table_keeps_dup_aliases_as_one_open_file() {
2868        let owner = DetTid::from_raw(9);
2869        let mut metadata = FileMetadata::new(owner);
2870        metadata
2871            .add_fd(owner, 3, OFlag::empty(), FdType::Rng, None)
2872            .expect("register descriptor");
2873        metadata
2874            .dup_fd(3, 4, OFlag::O_CLOEXEC)
2875            .expect("dup the descriptor");
2876        metadata
2877            .add_fd(owner, 5, OFlag::empty(), FdType::Rng, None)
2878            .expect("register a separate open");
2879        let encoded = serde_json::to_string(&metadata).expect("serialize the table");
2880        let restored: FileMetadata = serde_json::from_str(&encoded).expect("deserialize the table");
2881        let three = restored.file_handles[&3].clone();
2882        let four = restored.file_handles[&4].clone();
2883        let five = restored.file_handles[&5].clone();
2884        assert_eq!(three.open_file_id(), four.open_file_id());
2885        assert_ne!(three.open_file_id(), five.open_file_id());
2886        // One object again: a read through one alias moves the other's cursor.
2887        four.advance_random_device_offset(50);
2888        assert_eq!(three.random_device_offset(), 50);
2889        assert_eq!(five.random_device_offset(), 0);
2890        // The table plus the two local handles above.
2891        assert_eq!(three.open_file_alias_count(), 4);
2892        // Descriptor flags stay per descriptor.
2893        assert!(!three.is_cloexec());
2894        assert!(four.is_cloexec());
2895    }
2896
2897    #[test]
2898    fn fork_makes_inherited_flock_state_unknown_in_parent_and_child() {
2899        let owner = DetTid::from_raw(9);
2900        let child = DetTid::from_raw(10);
2901        let mut metadata = FileMetadata::new(owner);
2902        metadata
2903            .add_fd(owner, 3, OFlag::empty(), FdType::Regular, None)
2904            .expect("register descriptor");
2905        metadata
2906            .with_detfd(3, |detfd| detfd.set_flock_mode(Some(libc::LOCK_SH)))
2907            .expect("registered descriptor");
2908
2909        let mut child_metadata = metadata.fork_for(child);
2910        assert_eq!(
2911            metadata
2912                .with_detfd(3, |detfd| detfd.known_flock_mode())
2913                .expect("parent descriptor should remain tracked"),
2914            None,
2915            "parent cache must not become stale when the child changes the shared open file description"
2916        );
2917        assert_eq!(
2918            child_metadata
2919                .with_detfd(3, |detfd| detfd.known_flock_mode())
2920                .expect("child descriptor should be inherited"),
2921            None,
2922            "child starts with the same deliberately unknown shared state"
2923        );
2924    }
2925
2926    #[test]
2927    fn exec_preserves_known_flock_mode_for_surviving_descriptors() {
2928        let owner = DetTid::from_raw(9);
2929        let mut metadata = FileMetadata::new(owner);
2930        metadata
2931            .add_fd(owner, 3, OFlag::empty(), FdType::Regular, None)
2932            .expect("register descriptor");
2933        metadata
2934            .with_detfd(3, |detfd| detfd.set_flock_mode(Some(libc::LOCK_SH)))
2935            .expect("registered descriptor");
2936
2937        let mut after_exec = metadata.for_exec(DetTid::from_raw(10));
2938        assert_eq!(
2939            after_exec
2940                .with_detfd(3, |detfd| detfd.known_flock_mode())
2941                .expect("non-cloexec descriptor should survive"),
2942            Some(Some(libc::LOCK_SH)),
2943            "exec must preserve known flock state for a surviving open file description"
2944        );
2945    }
2946
2947    #[test]
2948    fn discovered_stdio_uses_container_wide_resources() {
2949        let owner = DetTid::from_raw(9);
2950        let mut metadata = FileMetadata::new(owner);
2951
2952        metadata
2953            .discover_fd_from_current_process(owner, libc::STDOUT_FILENO)
2954            .expect("live stdout should be discovered");
2955
2956        assert_eq!(
2957            metadata
2958                .with_detfd(libc::STDOUT_FILENO, |detfd| detfd.resource())
2959                .expect("discovered stdout should be tracked"),
2960            Some(ResourceID::Device(Device::ContainerStdout))
2961        );
2962
2963        // Observe real metadata transitions without closing the test process's
2964        // stdio. The narrow repair preserves slot identities for inherited
2965        // resources and leaves aliases above fd 2 in the ordinary inode pool.
2966        use crate::syscalls::deterministic_stdio_inode_for_resource;
2967
2968        let inherited_stat = metadata
2969            .with_detfd(libc::STDOUT_FILENO, |detfd| detfd.stat().unwrap())
2970            .unwrap();
2971        metadata.dup_fd(1, 7, OFlag::empty()).unwrap();
2972        assert_eq!(
2973            metadata.with_detfd(7, |detfd| detfd.resource()).unwrap(),
2974            Some(ResourceID::Device(Device::ContainerStdout))
2975        );
2976        assert_eq!(
2977            metadata
2978                .with_detfd(7, |detfd| {
2979                    deterministic_stdio_inode_for_resource(7, detfd.resource())
2980                })
2981                .unwrap(),
2982            None
2983        );
2984        for fd in 0..=2 {
2985            metadata.remove_fd(fd);
2986            let mut ordinary = inherited_stat;
2987            ordinary.inode = 123 + fd as u64;
2988            metadata
2989                .add_fd(owner, fd, OFlag::empty(), FdType::Regular, Some(ordinary))
2990                .unwrap();
2991            metadata.dup_fd(fd, 8, OFlag::empty()).unwrap();
2992            for ordinary_fd in [fd, 8] {
2993                assert_eq!(
2994                    metadata
2995                        .with_detfd(ordinary_fd, |detfd| {
2996                            deterministic_stdio_inode_for_resource(ordinary_fd, detfd.resource())
2997                        })
2998                        .unwrap(),
2999                    None
3000                );
3001            }
3002            assert_eq!(
3003                metadata
3004                    .with_detfd(fd, |detfd| detfd.open_file_id())
3005                    .unwrap(),
3006                metadata
3007                    .with_detfd(8, |detfd| detfd.open_file_id())
3008                    .unwrap()
3009            );
3010            metadata.dup_fd(7, fd, OFlag::empty()).unwrap();
3011            assert_eq!(
3012                metadata
3013                    .with_detfd(fd, |detfd| {
3014                        deterministic_stdio_inode_for_resource(fd, detfd.resource())
3015                    })
3016                    .unwrap(),
3017                Some(DetInode::mint(1000 + fd as u64)),
3018                "inherited streams retain the existing numeric-slot outcome"
3019            );
3020        }
3021        metadata.dup_fd(7, 9, OFlag::O_CLOEXEC).unwrap();
3022        let child = metadata.fork_for(DetTid::from_raw(10));
3023        let after_exec = child.for_exec(DetTid::from_raw(10));
3024        assert!(!after_exec.file_handles.contains_key(&9));
3025        assert!(after_exec.file_handles.contains_key(&7));
3026    }
3027
3028    #[test]
3029    fn discovered_pipe_preserves_inherited_nonblocking() {
3030        let owner = DetTid::from_raw(9);
3031        let mut fds = [-1; 2];
3032        assert_eq!(
3033            unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_NONBLOCK) },
3034            0
3035        );
3036        let mut metadata = FileMetadata::new(owner);
3037
3038        metadata
3039            .discover_fd_from_current_process(owner, fds[0])
3040            .expect("live pipe should be discovered");
3041        let flags = metadata
3042            .with_detfd(fds[0], |detfd| {
3043                (detfd.is_nonblocking(), detfd.physically_nonblocking())
3044            })
3045            .expect("discovered pipe should be tracked");
3046
3047        assert_eq!(flags, (true, true));
3048        unsafe {
3049            libc::close(fds[0]);
3050            libc::close(fds[1]);
3051        }
3052    }
3053
3054    #[test]
3055    fn exec_handoff_restores_scheduler_pipe_as_logically_blocking() {
3056        let owner = DetTid::from_raw(9);
3057        let mut fds = [-1; 2];
3058        assert_eq!(
3059            unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_NONBLOCK) },
3060            0
3061        );
3062        let mut before_exec = FileMetadata::new(owner);
3063        before_exec
3064            .add_fd(owner, fds[0], OFlag::empty(), FdType::Pipe, None)
3065            .expect("scheduler pipe should be registered");
3066        before_exec
3067            .with_detfd(fds[0], |detfd| detfd.set_physically_nonblocking())
3068            .expect("scheduler pipe should remain registered");
3069
3070        let overrides = before_exec.exec_blocking_overrides();
3071        assert_eq!(overrides, BTreeSet::from([fds[0]]));
3072
3073        let mut after_exec = FileMetadata::new(owner);
3074        after_exec.apply_exec_blocking_overrides(owner, overrides);
3075        assert_eq!(
3076            after_exec
3077                .with_detfd(fds[0], |detfd| {
3078                    (detfd.is_nonblocking(), detfd.physically_nonblocking())
3079                })
3080                .expect("inherited pipe should be rediscovered"),
3081            (false, true)
3082        );
3083
3084        unsafe {
3085            libc::close(fds[0]);
3086            libc::close(fds[1]);
3087        }
3088    }
3089
3090    #[test]
3091    fn fork_copies_slots_but_preserves_open_file_aliases() {
3092        let parent_tid = DetTid::from_raw(10);
3093        let child_tid = DetTid::from_raw(11);
3094        let mut parent = FileMetadata::new(parent_tid);
3095        parent
3096            .add_fd(parent_tid, 3, OFlag::O_NONBLOCK, FdType::Socket, None)
3097            .expect("parent fd should be inserted");
3098        parent
3099            .dup_fd(3, 4, OFlag::O_CLOEXEC)
3100            .expect("dup should succeed");
3101
3102        let parent_open = parent
3103            .with_detfd(3, |fd| fd.open_file_id())
3104            .expect("parent fd should exist");
3105        let duplicate_open = parent
3106            .with_detfd(4, |fd| fd.open_file_id())
3107            .expect("duplicate fd should exist");
3108        assert_eq!(parent_open, duplicate_open);
3109
3110        let initial_timestamp = LogicalTime::from_nanos(1_234_567_890);
3111        parent
3112            .with_detfd(3, |fd| fd.set_socket_receive_timestamp(initial_timestamp))
3113            .expect("parent socket should accept a receive timestamp");
3114
3115        let mut child = parent.fork_for(child_tid);
3116        assert_ne!(parent.files_id, child.files_id);
3117        assert_ne!(
3118            FdSlot {
3119                files: parent.files_id,
3120                fd: 3,
3121            },
3122            FdSlot {
3123                files: child.files_id,
3124                fd: 3,
3125            }
3126        );
3127        assert_eq!(
3128            parent_open,
3129            child
3130                .with_detfd(3, |fd| fd.open_file_id())
3131                .expect("forked fd should retain its open file identity")
3132        );
3133        assert_eq!(
3134            child
3135                .with_detfd(3, |fd| fd.socket_receive_timestamp())
3136                .expect("forked fd should retain its receive timestamp"),
3137            Some(initial_timestamp)
3138        );
3139        let child_timestamp = LogicalTime::from_nanos(2_345_678_901);
3140        child
3141            .with_detfd(3, |fd| fd.set_socket_receive_timestamp(child_timestamp))
3142            .expect("child socket should update the shared receive timestamp");
3143        assert_eq!(
3144            parent
3145                .with_detfd(4, |fd| fd.socket_receive_timestamp())
3146                .expect("parent duplicate should see the child update"),
3147            Some(child_timestamp)
3148        );
3149
3150        parent
3151            .add_fd(parent_tid, 5, OFlag::empty(), FdType::Regular, None)
3152            .expect("new parent fd should be inserted");
3153        child
3154            .add_fd(child_tid, 5, OFlag::empty(), FdType::Regular, None)
3155            .expect("new child fd should be inserted");
3156        assert_ne!(
3157            parent
3158                .with_detfd(5, |fd| fd.open_file_id())
3159                .expect("new parent fd should exist"),
3160            child
3161                .with_detfd(5, |fd| fd.open_file_id())
3162                .expect("new child fd should exist"),
3163            "separate opens after fork must not alias"
3164        );
3165    }
3166
3167    #[test]
3168    fn pidfd_getfd_target_requires_the_calling_leader() {
3169        let leader = DetPid::from_raw(31);
3170        assert!(pidfd_getfd_targets_calling_task(
3171            Some(leader),
3172            leader,
3173            DetTid::from_raw(31),
3174        ));
3175        assert!(!pidfd_getfd_targets_calling_task(
3176            Some(leader),
3177            leader,
3178            DetTid::from_raw(32),
3179        ));
3180        assert!(!pidfd_getfd_targets_calling_task(
3181            Some(DetPid::from_raw(32)),
3182            leader,
3183            DetTid::from_raw(31),
3184        ));
3185    }
3186
3187    #[test]
3188    fn captured_fd_installs_when_the_descriptor_table_is_unchanged() {
3189        let owner = DetTid::from_raw(32);
3190        let mut metadata = FileMetadata::new(owner);
3191        metadata
3192            .add_fd(owner, 3, OFlag::empty(), FdType::Regular, None)
3193            .expect("source should be inserted");
3194        let source_id = metadata
3195            .with_detfd(3, |fd| fd.open_file_id())
3196            .expect("source should exist");
3197        let captured = metadata.capture_fd(3).expect("source should be captured");
3198
3199        assert_eq!(
3200            metadata
3201                .install_captured_fd(captured, 4, OFlag::O_CLOEXEC)
3202                .expect("an unchanged table should accept the captured alias"),
3203            None
3204        );
3205        assert_eq!(
3206            metadata
3207                .with_detfd(4, |fd| (fd.open_file_id(), fd.is_cloexec()))
3208                .expect("captured alias should be installed"),
3209            (source_id, true)
3210        );
3211    }
3212
3213    #[test]
3214    fn failed_captured_fd_install_preserves_cleanup_obligations() {
3215        let owner = DetTid::from_raw(36);
3216        let mut original = FileMetadata::new(owner);
3217        original
3218            .add_fd(owner, 3, OFlag::empty(), FdType::Socket, None)
3219            .expect("source should be inserted");
3220        let source_id = original
3221            .with_detfd(3, |fd| fd.open_file_id())
3222            .expect("source should exist");
3223        let captured = original.capture_fd(3).expect("source should be captured");
3224        assert_eq!(
3225            original.remove_fd(3),
3226            None,
3227            "the capture defers final-OFD cleanup while the syscall is in flight"
3228        );
3229
3230        let mut replacement_table = FileMetadata::new(DetTid::from_raw(37));
3231        let failure = replacement_table
3232            .install_captured_fd(captured, 41, OFlag::O_CLOEXEC)
3233            .expect_err("a capture must not cross descriptor-table identity");
3234        assert_ne!(failure.expected_files_id, failure.actual_files_id);
3235        let cleanup = failure.into_cleanup();
3236        assert_eq!(cleanup.close_fd, 41);
3237        assert_eq!(cleanup.release_open_file, Some(source_id));
3238    }
3239
3240    #[test]
3241    fn equal_fd_dup_preserves_descriptor_flags() {
3242        let owner = DetTid::from_raw(20);
3243        let mut metadata = FileMetadata::new(owner);
3244        metadata
3245            .add_fd(owner, 3, OFlag::O_CLOEXEC, FdType::Regular, None)
3246            .expect("fd should be inserted");
3247
3248        assert_eq!(
3249            metadata
3250                .dup_fd(3, 3, OFlag::empty())
3251                .expect("equal-fd dup should validate the source"),
3252            None
3253        );
3254        assert!(
3255            metadata
3256                .with_detfd(3, |fd| fd.is_cloexec())
3257                .expect("fd should remain present"),
3258            "dup2(fd, fd) must not clear close-on-exec"
3259        );
3260    }
3261
3262    #[test]
3263    fn last_open_file_alias_survives_dup_and_fork() {
3264        let parent_tid = DetTid::from_raw(30);
3265        let child_tid = DetTid::from_raw(31);
3266        let mut parent = FileMetadata::new(parent_tid);
3267        parent
3268            .add_fd(parent_tid, 3, OFlag::empty(), FdType::Socket, None)
3269            .expect("socket should be inserted");
3270        let open_file_id = parent
3271            .with_detfd(3, |fd| fd.open_file_id())
3272            .expect("socket should exist");
3273        assert_eq!(
3274            parent
3275                .dup_fd(3, 4, OFlag::empty())
3276                .expect("dup should succeed"),
3277            None
3278        );
3279        assert_eq!(parent.remove_fd(3), None, "duplicate retains the OFD");
3280
3281        let mut child = parent.fork_for(child_tid);
3282        assert_eq!(parent.remove_fd(4), None, "forked child retains the OFD");
3283        assert_eq!(
3284            child.remove_fd(4),
3285            Some(open_file_id),
3286            "only the final alias releases the OFD"
3287        );
3288
3289        let mut replacement = FileMetadata::new(parent_tid);
3290        replacement
3291            .add_fd(parent_tid, 3, OFlag::empty(), FdType::Socket, None)
3292            .expect("source should be inserted");
3293        replacement
3294            .add_fd(parent_tid, 4, OFlag::empty(), FdType::Socket, None)
3295            .expect("target should be inserted");
3296        let target_id = replacement
3297            .with_detfd(4, |fd| fd.open_file_id())
3298            .expect("target should exist");
3299        assert_eq!(
3300            replacement
3301                .dup_fd(3, 4, OFlag::empty())
3302                .expect("dup replacement should succeed"),
3303            Some(target_id),
3304            "replacing the target must release its last OFD alias"
3305        );
3306    }
3307
3308    #[test]
3309    fn close_range_removes_selected_slots_and_releases_final_aliases() {
3310        let owner = DetTid::from_raw(35);
3311        let mut metadata = FileMetadata::new(owner);
3312        metadata
3313            .add_fd(owner, 3, OFlag::empty(), FdType::Regular, None)
3314            .expect("source should be inserted");
3315        metadata
3316            .dup_fd(3, 4, OFlag::empty())
3317            .expect("duplicate should be inserted");
3318        metadata
3319            .add_fd(owner, 100, OFlag::empty(), FdType::Regular, None)
3320            .expect("high fd should be inserted");
3321        let high_id = metadata
3322            .with_detfd(100, |fd| fd.open_file_id())
3323            .expect("high fd should exist");
3324
3325        assert_eq!(metadata.remove_fd_range(4, 100), [high_id]);
3326        assert!(metadata.with_detfd(3, |_| ()).is_ok());
3327        assert_eq!(metadata.with_detfd(4, |_| ()), Err(Errno::EBADF));
3328        assert_eq!(metadata.with_detfd(100, |_| ()), Err(Errno::EBADF));
3329    }
3330
3331    #[test]
3332    fn exec_reports_only_cloexec_open_files_with_no_other_aliases() {
3333        let owner = DetTid::from_raw(40);
3334        let child_tid = DetTid::from_raw(41);
3335        let mut metadata = FileMetadata::new(owner);
3336        metadata
3337            .add_fd(owner, 3, OFlag::O_CLOEXEC, FdType::Socket, None)
3338            .expect("socket should be inserted");
3339        let open_file_id = metadata
3340            .with_detfd(3, |fd| fd.open_file_id())
3341            .expect("socket should exist");
3342
3343        assert_eq!(metadata.open_files_closed_on_exec(false), [open_file_id]);
3344        assert!(
3345            metadata.open_files_closed_on_exec(true).is_empty(),
3346            "a shared descriptor table retains the original slot"
3347        );
3348
3349        let child = metadata.fork_for(child_tid);
3350        assert!(
3351            metadata.open_files_closed_on_exec(false).is_empty(),
3352            "a copied table retains an OFD alias"
3353        );
3354        drop(child);
3355
3356        metadata
3357            .dup_fd(3, 4, OFlag::empty())
3358            .expect("non-CLOEXEC alias should be created");
3359        assert!(
3360            metadata.open_files_closed_on_exec(false).is_empty(),
3361            "a non-CLOEXEC alias keeps the OFD live across exec"
3362        );
3363    }
3364}
3365
3366/// Various measurements of one guest thread's execution. This is useful for printing
3367/// context in logs as we go and printing a final summary.
3368#[derive(Debug, Serialize, Deserialize, Clone, Default)]
3369pub struct ThreadStats {
3370    /// A simple count of how many syscalls have been handled on this thread.
3371    pub syscall_count: u64,
3372
3373    /// This thread's happens-before counting state: per (syscall, fd, futex
3374    /// operation) a syscall-occurrence anchor names, how many of this thread's
3375    /// syscall entries matched, and the origin of each relative anchor whose
3376    /// base this thread reached (`HappensBeforeProgram::count_syscall_occurrences`).
3377    /// Empty unless the run has such an anchor; empty for every new thread,
3378    /// like `syscall_count`.
3379    pub hb_occurrences: detcore_model::happens_before::HbThreadCounters,
3380
3381    /// The posthook happens-before anchors the current syscall entry reached
3382    /// (`Anchor::fires_at_posthook`): counted at its prehook, they check in
3383    /// with the scheduler when the call completes. Empty between syscalls.
3384    pub hb_pending_posthook: Vec<String>,
3385
3386    /// How many register-file samples this thread has CONSIDERED for `--detlog-regs`.
3387    ///
3388    /// This is the cadence index, and it exists because no pre-existing counter is a clean
3389    /// zero-based count of control points: the logged syscall ordinal starts at 2, and
3390    /// `syscall_count` also counts points this sampler never reaches. Keying the cadence on either
3391    /// let a short guest whose points never landed on a multiple of N emit ZERO samples while the
3392    /// run still reported PASS -- a spot-tier green backed by nothing. Counting the samples
3393    /// themselves makes index 0 the first control point of every thread, so a spot-tier run always
3394    /// samples at least once.
3395    pub regs_sample_index: u64,
3396
3397    /// A count of how many signals have arrived at this thread, total.
3398    pub signal_count: u64,
3399
3400    /// How many syscalls this time slice (since last preemption)?
3401    pub timeslice_syscall_count: u64,
3402
3403    /// How many signals this time slice (since last preemption)?
3404    pub timeslice_signal_count: u64,
3405
3406    /// How many logical timeslices have we completed before the current one?
3407    /// These correspond to when we are preempted at the `end_of_timeslice`.
3408    pub timeslice_count: u64,
3409
3410    /// The timeslice_count for the timeslice which was the last one that had a recorded end time in
3411    /// the `--replay-preemptions-from` log.
3412    pub last_recorded_slice: Option<u64>,
3413
3414    /// Distribution (min/max/sum/count) of completed timeslice durations for this
3415    /// thread, in virtual nanoseconds. A slice's duration is the delta of
3416    /// `thread_logical_time` between two consecutive `next_timeslice` resets.
3417    pub timeslice_stats: TimesliceStats,
3418
3419    /// The per-thread logical time (virtual ns) at which the current timeslice
3420    /// began. `None` until the first slice is opened. Used to compute the
3421    /// duration of a slice when the next reset occurs.
3422    pub timeslice_start_ns: Option<LogicalTime>,
3423}
3424
3425impl ThreadStats {
3426    /// Create a new thread stats with zero counters.
3427    pub fn new() -> Self {
3428        Default::default()
3429    }
3430
3431    // TODO: this can evolve to keep a full histogram:
3432    /// Increment the count of system calls
3433    pub fn count_syscall(&mut self) {
3434        self.syscall_count += 1;
3435        self.timeslice_syscall_count += 1;
3436    }
3437
3438    /// Increment the count of signals.
3439    pub fn count_signal(&mut self) {
3440        self.signal_count += 1;
3441        self.timeslice_signal_count += 1;
3442    }
3443
3444    /// Reset counters for a new timeslice.
3445    /// Increases the count of completed timeslices.
3446    pub(crate) fn reset_timeslice(&mut self) {
3447        self.timeslice_syscall_count = 0;
3448        self.timeslice_signal_count = 0;
3449        self.timeslice_count += 1;
3450    }
3451
3452    /// Close the final, in-progress timeslice at thread exit, recording its
3453    /// virtual-ns duration. This captures short-lived or I/O-bound threads that
3454    /// exit (or block until exit) before ever exhausting a slice, so they still
3455    /// contribute one sample. Idempotent: consumes `timeslice_start_ns`.
3456    pub fn close_final_timeslice(&mut self, now: LogicalTime) {
3457        if let Some(start) = self.timeslice_start_ns.take()
3458            && now >= start
3459        {
3460            self.timeslice_stats.record((now - start).as_nanos());
3461        }
3462    }
3463}
3464
3465/// Information inherited by a `CLONE_VFORK` child so it can register itself
3466/// while its parent is blocked inside the kernel.
3467#[derive(Debug, Clone, Serialize, Deserialize)]
3468pub struct PendingVfork {
3469    pub parent_dettid: DetTid,
3470    pub parent_detpid: DetPid,
3471    pub child_tid_addr: usize,
3472    pub flags: CloneFlags,
3473    pub exit_signal: libc::c_int,
3474    pub child_priority_entropy: Option<u64>,
3475}
3476
3477// TODO-HUMAN-REVIEW(#797): Review process-wide logical CPU aggregation.
3478#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize)]
3479pub(crate) struct ProcessCpuSnapshot {
3480    pub user: LogicalTime,
3481    pub system: LogicalTime,
3482    pub children_user: LogicalTime,
3483    pub children_system: LogicalTime,
3484}
3485
3486/// Runtime-only readiness for one child birth. A retired or replaced token can
3487/// never be made ready again; cancelled waiters leave only weak references.
3488#[derive(Debug)]
3489pub(crate) struct ChildCpuPublication(Mutex<ChildCpuPublicationState>);
3490
3491#[derive(Debug)]
3492enum ChildCpuPublicationState {
3493    Pending(Vec<std::sync::Weak<futures::task::AtomicWaker>>),
3494    Published,
3495    Invalidated,
3496}
3497
3498impl ChildCpuPublication {
3499    fn pending() -> Arc<Self> {
3500        Arc::new(Self(Mutex::new(ChildCpuPublicationState::Pending(
3501            Vec::new(),
3502        ))))
3503    }
3504
3505    fn finish(&self, published: bool) {
3506        let waiters = {
3507            let mut state = self.0.lock().expect("child CPU publication mutex poisoned");
3508            if matches!(*state, ChildCpuPublicationState::Invalidated)
3509                || published && matches!(*state, ChildCpuPublicationState::Published)
3510            {
3511                return;
3512            }
3513            let next = if published {
3514                ChildCpuPublicationState::Published
3515            } else {
3516                ChildCpuPublicationState::Invalidated
3517            };
3518            match std::mem::replace(&mut *state, next) {
3519                ChildCpuPublicationState::Pending(waiters) => waiters,
3520                _ => Vec::new(),
3521            }
3522        };
3523        // Do not call an arbitrary task waker under either accounting lock.
3524        for waiter in waiters.into_iter().filter_map(|waiter| waiter.upgrade()) {
3525            waiter.wake();
3526        }
3527    }
3528
3529    async fn wait(&self) -> bool {
3530        let waiter = Arc::new(futures::task::AtomicWaker::new());
3531        {
3532            let mut state = self.0.lock().expect("child CPU publication mutex poisoned");
3533            match &mut *state {
3534                ChildCpuPublicationState::Pending(waiters) => {
3535                    waiters.retain(|waiter| waiter.strong_count() != 0);
3536                    waiters.push(Arc::downgrade(&waiter));
3537                }
3538                ChildCpuPublicationState::Published => return true,
3539                ChildCpuPublicationState::Invalidated => return false,
3540            }
3541        }
3542        futures::future::poll_fn(|cx| {
3543            waiter.register(cx.waker());
3544            let state = self.0.lock().expect("child CPU publication mutex poisoned");
3545            match *state {
3546                ChildCpuPublicationState::Pending(_) => std::task::Poll::Pending,
3547                ChildCpuPublicationState::Published => std::task::Poll::Ready(true),
3548                ChildCpuPublicationState::Invalidated => std::task::Poll::Ready(false),
3549            }
3550        })
3551        .await
3552    }
3553}
3554
3555#[derive(Debug, Default, Clone, Serialize, Deserialize)]
3556pub(crate) struct ProcessCpuTime {
3557    snapshot: ProcessCpuSnapshot,
3558    exited_children: BTreeMap<DetPid, ProcessCpuSnapshot>,
3559    // Runtime ownership, not record-format state. ThreadState clones retain the
3560    // same parent accounting Arc; notification tokens also retain their identity.
3561    #[serde(skip)]
3562    child_cpu_publications: BTreeMap<DetPid, Arc<ChildCpuPublication>>,
3563}
3564
3565impl ProcessCpuTime {
3566    fn validate_native_exec_cut(&self) -> Result<(), crate::native_exec::NativeExecCutError> {
3567        if !self.child_cpu_publications.is_empty() {
3568            return Err(crate::native_exec::NativeExecCutError::LiveCapability(
3569                "child_cpu_publications",
3570            ));
3571        }
3572        Ok(())
3573    }
3574
3575    fn add_thread_delta(&mut self, user: LogicalTime, system: LogicalTime) {
3576        self.snapshot.user = self.snapshot.user + user;
3577        self.snapshot.system = self.snapshot.system + system;
3578    }
3579
3580    fn record_exited_child(&mut self, pid: DetPid, child: ProcessCpuSnapshot) {
3581        self.exited_children
3582            .entry(pid)
3583            .and_modify(|previous| {
3584                previous.user = previous.user.max(child.user);
3585                previous.system = previous.system.max(child.system);
3586                previous.children_user = previous.children_user.max(child.children_user);
3587                previous.children_system = previous.children_system.max(child.children_system);
3588            })
3589            .or_insert(child);
3590    }
3591
3592    fn reap_child(&mut self, pid: DetPid) {
3593        let Some(child) = self.exited_children.remove(&pid) else {
3594            return;
3595        };
3596        self.snapshot.children_user =
3597            self.snapshot.children_user + child.user + child.children_user;
3598        self.snapshot.children_system =
3599            self.snapshot.children_system + child.system + child.children_system;
3600    }
3601
3602    fn prepare_child(&mut self, pid: DetPid) {
3603        self.exited_children.remove(&pid);
3604    }
3605}
3606
3607/// Guest-visible logical clock shared by an entire process tree.
3608///
3609/// The scheduler's raw logical time already includes the configured epoch and
3610/// is the clock used to judge absolute deadlines. Guest time must therefore
3611/// track it directly: subtracting a per-process or per-exec origin can put a
3612/// newly computed absolute deadline in the scheduler's past. The shared floor
3613/// preserves monotonicity if a backend supplies a stale local observation.
3614#[derive(Debug, Default, Serialize, Deserialize)]
3615pub(crate) struct GuestClock {
3616    now: LogicalTime,
3617}
3618
3619/// One modeled robust-futex wake that must wait until Linux has completed the
3620/// corresponding task-exit cleanup.
3621#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
3622pub(crate) struct RobustListWake {
3623    pub(crate) futex: FutexID,
3624}
3625
3626/// The physical-exit condition under which staged robust-futex wakes become
3627/// safe to deliver.
3628#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
3629pub(crate) enum RobustListExit {
3630    ExitGroup,
3631    Signal(i32),
3632}
3633
3634/// Wakes collected while guest memory is still readable, keyed by the owner
3635/// whose physical exit makes them safe.
3636#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
3637pub(crate) struct PendingRobustListWakes {
3638    pub(crate) reason: RobustListExit,
3639    pub(crate) wakes: Vec<RobustListWake>,
3640}
3641
3642impl PendingRobustListWakes {
3643    fn matches_exit(&self, exit_signal: Option<i32>) -> bool {
3644        match self.reason {
3645            RobustListExit::ExitGroup => true,
3646            RobustListExit::Signal(expected) => exit_signal == Some(expected),
3647        }
3648    }
3649}
3650
3651/// How long a thread an exit_group killed waits for its robust-list walk
3652/// ([`ThreadState::wait_for_exit_group_robust_walk`]).
3653pub(crate) const EXIT_GROUP_ROBUST_WALK_WAIT: std::time::Duration =
3654    std::time::Duration::from_secs(10);
3655
3656/// A registered robust list: its owner and head.
3657#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3658pub(crate) struct RobustListOwner {
3659    pub(crate) dettid: DetTid,
3660    pub(crate) head: usize,
3661}
3662
3663/// Robust-list registrations and staged wakes shared by one Linux thread
3664/// group. A forked process starts with an empty instance; `CLONE_THREAD`
3665/// members share it.
3666#[derive(Debug, Clone, Default, Serialize, Deserialize)]
3667pub(crate) struct RobustListProcessState {
3668    heads: BTreeMap<DetTid, usize>,
3669    /// Threads whose own exit Detcore has already walked on DBT
3670    /// ([`crate::syscalls::threads`]'s `OwnerDeathPath::Barrier`).
3671    #[serde(default)]
3672    tool_walked: BTreeSet<DetTid>,
3673    /// An exit_group on DBT (`OwnerDeathPath::Barrier`) has been filed: an
3674    /// exiting thread keeps its head here for that exit_group's walk
3675    /// ([`ThreadState::drop_robust_list_head_at_exit`]).
3676    #[serde(default)]
3677    exit_group_filed: bool,
3678    /// The threads whose filed exit_group is still pending: filed, and
3679    /// neither granted nor cancelled by the thread's own death.
3680    #[serde(default)]
3681    exit_group_filers: BTreeSet<DetTid>,
3682    /// The thread whose filed exit_group was granted and is walking the
3683    /// group's lists ([`ThreadState::begin_exit_group_robust_walk`]).
3684    #[serde(default)]
3685    exit_group_walker: Option<DetTid>,
3686    /// That exit_group's walk has finished
3687    /// ([`ThreadState::finish_exit_group_robust_walk`]).
3688    #[serde(default)]
3689    exit_group_walked: bool,
3690    pending: BTreeMap<DetTid, PendingRobustListWakes>,
3691    matched_physical_exits: BTreeMap<DetTid, DetTime>,
3692    /// Wakes read at an `execve`'s entry, delivered only if it succeeds.
3693    exec_pending: Vec<(DetTid, RobustListWake)>,
3694}
3695
3696impl GuestClock {
3697    fn observe(&mut self, raw: LogicalTime) -> LogicalTime {
3698        self.now = self.now.max(raw);
3699        self.now
3700    }
3701}
3702
3703/// Linux's initial per-task timer slack, in nanoseconds.
3704///
3705/// Detcore uses the kernel default rather than inheriting the launcher's
3706/// physical timer slack.  Guest writes are kept in virtual per-thread state so
3707/// they cannot perturb the host-timed waits Detcore still uses internally.
3708pub(crate) const DEFAULT_TIMER_SLACK_NS: u64 = 50_000;
3709
3710fn default_timer_slack_ns() -> u64 {
3711    DEFAULT_TIMER_SLACK_NS
3712}
3713
3714/// The most deliveries in a row that continue their thread's own
3715/// `rt_sigreturn` (`ThreadState::consecutive_continuations`). A chosen,
3716/// bounded preference budget: as many as Linux has standard signals, so any
3717/// set of distinct standard signals pending when a run begins is delivered
3718/// before other threads run. A cap of 1 cut short a second pending signal
3719/// and restarted the cycle <https://github.com/rrnewton/hermit/issues/4505>
3720/// fixes (Claude re-check of https://github.com/rrnewton/hermit/pull/4509).
3721/// It is not a promise that every backlog drains first: realtime signals
3722/// queue several instances and a periodic timer can re-arm during a run
3723/// (v6.12 kernel/signal.c:1070 and :695). Reaching the cap only drops the
3724/// preference; no signal is lost, and the next delivery waits its turn.
3725pub(crate) const MAX_SIGRETURN_CONTINUATIONS: u8 = 32;
3726
3727/// The Detcore per-thread state.
3728#[derive(Serialize, Deserialize, Clone)]
3729pub struct ThreadState<T> {
3730    /// The deterministic thread ID of the this thread.
3731    pub dettid: DetTid,
3732    /// The deterministic process ID of the this thread.
3733    pub detpid: Option<DetTid>,
3734
3735    /// Whether the backend entered the thread-start callback. Construction
3736    /// alone does not imply that this thread was admitted to the scheduler.
3737    pub(crate) thread_start_entered: bool,
3738
3739    /// Host thread ID supplied by a backend whose scheduler identity is
3740    /// virtual. `None` keeps the existing direct-ID behavior for other
3741    /// backends.
3742    #[serde(default)]
3743    pub physical_tid: Option<i32>,
3744
3745    /// Backend lifetime retained for consuming signal effects after retirement.
3746    #[serde(default)]
3747    pub(crate) signal_task_identity: Option<reverie::SignalTaskIdentity>,
3748
3749    // AUTONOMOUS-BOT-IMPLEMENTED
3750    // TODO-HUMAN-REVIEW(PR-1063): Review backend-supplied open-file creator identity.
3751    /// Stable identity used when allocating deterministic open-file descriptions.
3752    #[serde(default)]
3753    pub(crate) open_file_creator: Option<DetTid>,
3754
3755    /// Linux memory address space shared by tasks created with `CLONE_VM`.
3756    pub mm_id: MmId,
3757
3758    /// Last acknowledged ownership publication. A new mm or changed provider
3759    /// result is published before ordinary RPC can transfer the turn.
3760    #[serde(skip)]
3761    pub(crate) published_runtime_private_memory: Option<(MmId, reverie::RuntimePrivateMemory)>,
3762
3763    /// Shared memory mappings used to resolve process-shared futex keys.
3764    pub(crate) memory_metadata: Arc<Mutex<MemoryMetadata>>,
3765
3766    /// This threads path within the thread/process ancestry tree. (The terminology comes from
3767    /// Cilk.)
3768    pub pedigree: Pedigree,
3769
3770    /// Counting various events.
3771    pub stats: ThreadStats,
3772
3773    /// In chaos mode with --replay-preemptions-from, we hold a list of our future preemption points.
3774    pub preemption_points: Option<ThreadHistoryIterator>,
3775
3776    /// User defined interruption points
3777    pub interrupt_at: BTreeSet<u64>,
3778
3779    /// clone flags when SYS_clone is called.
3780    ///
3781    /// This is just a place to stash the value temporarily, where it can be read out by
3782    /// the child thread upon `init_thread_state`.  After that point, it is consumed by
3783    /// the child and becomes `None` again.
3784    ///
3785    /// Stated differently, this is just for message-passing communication.
3786    pub clone_flags: Option<CloneFlags>,
3787
3788    /// Registration metadata for a child whose parent cannot resume until the
3789    /// backend finishes the child. The child consumes this in
3790    /// `handle_thread_start`; the parent clears its copy when injection returns.
3791    pub pending_vfork: Option<PendingVfork>,
3792
3793    /// Shared file metadata among all threads in the same process.
3794    /// Initialized for new threads (shared or fresh), and then overwritten again on `execve`.
3795    pub file_metadata: Arc<Mutex<FileMetadata>>,
3796
3797    // AUTONOMOUS-BOT-IMPLEMENTED
3798    // TODO-HUMAN-REVIEW(PR-845): Review backend-gated live descriptor discovery state.
3799    /// Whether the tool runs in the guest's process and shares its descriptor
3800    /// table, so a descriptor detcore has not seen yet may be inspected live
3801    /// (copied from `BackendCapabilities::tool_shares_guest_descriptor_table`).
3802    #[serde(default)]
3803    pub(crate) tool_shares_guest_descriptor_table: bool,
3804
3805    // AUTONOMOUS-BOT-IMPLEMENTED
3806    // TODO-HUMAN-REVIEW(PR-2150): Review the per-thread timer-slack state
3807    // and the creator-current-as-child-default inheritance rule.
3808    /// Virtualized Linux timer slack for this thread.  Both prctl(2) and the
3809    /// top-level `/proc/<tid>/timerslack_ns` interface use these fields; the
3810    /// physical tracee value remains untouched.
3811    #[serde(default = "default_timer_slack_ns")]
3812    pub(crate) timer_slack_ns: u64,
3813    /// Value restored by a zero timer-slack write.  Linux gives a new task the
3814    /// creating thread's current value as both its current and its default.
3815    #[serde(default = "default_timer_slack_ns")]
3816    pub(crate) default_timer_slack_ns: u64,
3817
3818    /// This thread lives below the container's PID namespace: it, or an
3819    /// ancestor, was created with `CLONE_NEWPID`. Its pids are those of its
3820    /// own namespace, which Detcore translates
3821    /// (`scheduler::pid_namespaces`); at depth 0 nothing is asked.
3822    #[serde(default)]
3823    pub(crate) nested_pid_namespace: bool,
3824
3825    /// This task's root directory may not be the container's: a task it shares
3826    /// its root with (`CLONE_FS`), or one it inherited the root from, changed
3827    /// it with `chroot`. Detcore then leaves whether a procfs file exists to
3828    /// the kernel (`rendered_procfs`). Shared like the root itself: every task
3829    /// that shares the creator's filesystem information shares this flag.
3830    #[serde(default)]
3831    pub(crate) changed_root: Arc<std::sync::atomic::AtomicBool>,
3832
3833    /// The image this thread's process executes ([`crate::exec_record`]),
3834    /// which answers the process's `/proc/<pid>/exe` link; `None` leaves the
3835    /// link to the kernel. A new task starts with its creator's, and a
3836    /// successful exec replaces it (`tool_global::mark_past_first_execve`).
3837    #[serde(default)]
3838    pub(crate) exe: Option<Arc<crate::exec_record::ExecRecord>>,
3839
3840    /// The identity of the descriptor table this thread's process holds:
3841    /// the one its thread-group leader holds now, which procfs reads for
3842    /// the process's descriptor links (`/proc/self/fd/N`, `/proc/<pid>/fd/N`,
3843    /// `/dev/fd/N`). A new process sets it to the table it starts with (its
3844    /// creator's under `CLONE_FILES`, a copy otherwise), and an exec to the
3845    /// table exec gives it; `unshare` is refused, so a leader's table
3846    /// changes at nothing else. A thread (`CLONE_THREAD`) copies its
3847    /// creator's. A plain copy suffices: it changes only where the group has
3848    /// one thread (a new process, a successful exec), and a failed exec
3849    /// restores the exec'ing thread's own copy. `None` where it is not
3850    /// known, which only a state serialized before this field restores.
3851    #[serde(default)]
3852    pub(crate) process_files: Option<FilesId>,
3853
3854    /// POSIX per-process timers created via `timer_create(2)`. Shared among the
3855    /// threads of a process (`CLONE_THREAD`) and not inherited across `fork`.
3856    pub(crate) posix_timers: Arc<Mutex<PosixTimers>>,
3857
3858    /// Resource limits shared by threads and copied when a new process forks.
3859    pub(crate) resource_limits: Arc<Mutex<ResourceLimits>>,
3860
3861    /// Logical CPU accounting shared by all threads in this process.
3862    pub(crate) process_cpu_time: Arc<Mutex<ProcessCpuTime>>,
3863
3864    /// Guest-visible logical clock shared by every task in this process tree.
3865    #[serde(default)]
3866    pub(crate) guest_clock: Arc<Mutex<GuestClock>>,
3867
3868    /// Parent process accounting notified when this process leader exits.
3869    pub(crate) parent_process_cpu_time: Option<Arc<Mutex<ProcessCpuTime>>>,
3870
3871    /// Actual sequential KVM child's birth-owned publication capability.
3872    #[serde(skip)]
3873    pub(crate) parent_cpu_publication: Option<Arc<ChildCpuPublication>>,
3874
3875    /// The deadline of a wait this thread's last syscall ended with
3876    /// `ERESTART_RESTARTBLOCK`, for the `restart_syscall` that resumes it
3877    /// (`syscalls::helpers::RestartBlock`). The next syscall takes it
3878    /// (`Detcore::handle_syscall_event`).
3879    #[serde(skip)]
3880    pub(crate) restart_block: Option<crate::syscalls::helpers::RestartBlock>,
3881
3882    /// Whether this thread's process has a guest handler for SIGALRM, so that
3883    /// signal phase 1's table (`sigalrm_phase1`) gates its syscalls. Set by the
3884    /// runtime's handler admission (phase 1 step I3), in the same turn it
3885    /// publishes the disposition to the scheduler's ledger; until then only
3886    /// tests set it.
3887    pub(crate) sigalrm_handled: bool,
3888
3889    /// Detcore's own copy of this thread's signal dispositions and masks
3890    /// (audit step A5: recorded from the calls that change them, checked
3891    /// against the kernel where it can be read, and read by the decisions
3892    /// step 2 converted). `None` until the first image seeds it, and wherever it
3893    /// cannot be seeded: `None` means unknown, never default actions.
3894    #[serde(default)]
3895    pub(crate) signal_shadow: Option<crate::signal_state::SignalShadow>,
3896
3897    /// Whether this thread, or the thread that created it, lost its signal
3898    /// state copy after a divergence: a lost copy is never seeded again.
3899    #[serde(default)]
3900    pub(crate) signal_shadow_lost: bool,
3901
3902    /// What this thread was doing at its last guest event, for checking a
3903    /// signal delivery against the kernel's syscall registers (A5 step 3.2,
3904    /// `signal_shadow::check_delivery`): the syscall it entered, the result
3905    /// Detcore finished it with, a handler frame just approved, or no
3906    /// syscall. `None` is unknown (a new thread or image), and the check then
3907    /// takes the registers' own answer.
3908    #[serde(skip)]
3909    pub(crate) delivery_interruption: Option<reverie::Interruption>,
3910
3911    /// With `delivery_interruption` `AfterFrame`, the handler address the
3912    /// kernel's frame jumps to: a further delivery at the same exit, before
3913    /// any guest instruction, stops with the instruction pointer there.
3914    #[serde(skip)]
3915    pub(crate) delivery_frame_handler: u64,
3916
3917    /// This thread's counts of checked signal deliveries (A5 step 3.2),
3918    /// logged when it exits.
3919    #[serde(skip)]
3920    pub(crate) delivery_counters: crate::syscalls::signal_shadow::DeliveryCounters,
3921
3922    /// The process's record of its dispositions publications (A5 step 2b,
3923    /// `signal_shadow::publish_dispositions`): what the scheduler holds, the
3924    /// latest generation used, and the latest one the scheduler took. Shared
3925    /// by the threads of a process, which publish one entry.
3926    #[serde(default)]
3927    pub(crate) published_dispositions:
3928        Arc<Mutex<crate::syscalls::signal_shadow::PublishedDispositions>>,
3929
3930    /// What the scheduler holds as this thread's mask from Detcore's copy
3931    /// (A5 step 2b, `signal_shadow::publish_mask`): `Some(None)` nothing,
3932    /// `Some(Some(mask))` that mask; `None` when that is unknown (after an
3933    /// exec), so the next request publishes or withdraws.
3934    #[serde(default)]
3935    pub(crate) published_mask: Option<Option<u64>>,
3936
3937    /// The SIGALRM blocked bit this thread last published to the scheduler's
3938    /// ledger (signal phase 1). A handler's return changes the virtual mask
3939    /// without a syscall; the next syscall's entry compares the runtime's
3940    /// virtual bit with this one and publishes a change.
3941    pub(crate) sigalrm_blocked_published: bool,
3942
3943    /// The real-time signals this thread's process has already recorded as
3944    /// unblocked by a handler's restored mask
3945    /// (`Scheduler::handler_restore_unblocked`), so a delivery adds nothing
3946    /// new without asking the kernel or the scheduler.
3947    pub(crate) handler_restore_rt_reported: u64,
3948
3949    /// While Detcore runs its signal pipeline for a SIGALRM it delivers at a
3950    /// syscall's completion: the registers as that completion leaves them
3951    /// (`completed_syscall_projection`), which the pipeline reads instead of
3952    /// the backend's, whose context still shows the syscall's entry. Never
3953    /// written back.
3954    #[serde(skip)]
3955    pub(crate) signal_register_projection: Option<libc::user_regs_struct>,
3956
3957    /// Per-thread checkpoints used to add only new work to the process totals.
3958    pub(crate) last_accounted_user_time: LogicalTime,
3959    pub(crate) last_accounted_system_time: LogicalTime,
3960
3961    /// Absolute logical-clock values at this thread's creation. Child clocks
3962    /// inherit the parent's absolute position for scheduler ordering, but Linux
3963    /// `RUSAGE_THREAD` starts accounting at the calling thread's own creation.
3964    pub(crate) thread_cpu_start_user_time: LogicalTime,
3965    pub(crate) thread_cpu_start_system_time: LogicalTime,
3966
3967    /// pseudo random number state
3968    pub prng: Pcg64Mcg,
3969
3970    /// One initial-image auxv write completed by an authenticated backend
3971    /// before libc initialization. Consumed by the first post-exec callback;
3972    /// normal construction and child derivation never manufacture this fact.
3973    #[serde(default)]
3974    /// The initial image whose AT_RANDOM a backend wrote before post-exec, the
3975    /// bytes it wrote and its getrandom fills, until post-exec emits their
3976    /// records.
3977    pub(crate) initialized_random_auxv: Option<(
3978        crate::random::InitialImage,
3979        [u8; 16],
3980        Vec<crate::random::EarlyRequest>,
3981    )>,
3982
3983    /// RNG to drive chaos scheduling decisions, separate from other (guest) RNG.
3984    pub chaos_prng: Pcg64Mcg,
3985
3986    /// logical time, measuring progress of this thread and only this thread.
3987    pub thread_logical_time: DetTime,
3988
3989    /// the last RCB clock value committed to `thread_logical_time`
3990    pub committed_clock_value: u64,
3991
3992    /// Syscalls this thread made in the current backend-runtime bootstrap
3993    /// window without charging their cost to `thread_logical_time`. Zero
3994    /// outside a window; see [`ThreadState::charge_syscall_time`].
3995    #[serde(default)]
3996    pub(crate) uncharged_bootstrap_syscalls: u32,
3997
3998    /// True from the moment [`ThreadState::charge_syscall_time`] leaves the
3999    /// syscall this thread is handling uncharged until that syscall's handler
4000    /// finishes. Resource requests made meanwhile through
4001    /// `tool_global::resource_request` are marked
4002    /// [`Resources::backend_runtime_bootstrap`], so the scheduler withholds
4003    /// their turn time as well, except for an IO-polling retry, which still
4004    /// advances it. Requests that bypass `resource_request` (direct futex and
4005    /// thread-lifecycle requests) are not marked and advance it as usual.
4006    /// Cleared at the start of every handler and before the syscall handler's
4007    /// post-hook.
4008    #[serde(default)]
4009    pub(crate) in_uncharged_bootstrap_syscall: bool,
4010
4011    /// Set by the syscall handler when a `FUTEX_WAKE` woke a waiter and
4012    /// [`Config::yields_after_futex_wake`] holds, so that the
4013    /// syscall's post-hook takes a yield turn. A logically killed waker gets
4014    /// `EINTR` (4) as its wake count and may set this although the scheduler
4015    /// did not requeue it; that thread is already being torn down. The other
4016    /// way round, the scheduler requeues the waker without a yield following
4017    /// when the wake is the robust-list owner-death wake of an exiting thread
4018    /// (which never sets this and skips the post-hook), and when the syscall
4019    /// handler returns an error after the wake and skips the post-hook. In
4020    /// both the thread is retiring or the run is failing, and the requeue
4021    /// alone only reorders the run queue deterministically. Cleared at the
4022    /// start of every handler and by that post-hook.
4023    #[serde(default)]
4024    pub(crate) yield_after_futex_wake: bool,
4025    /// Under `--pipe-wake-latency` (`crate::pipe_wake`): the thread time at
4026    /// which this thread hands the turn to the pollers its actions readied,
4027    /// set at the readying action that the scheduler says starts a window
4028    /// (`crate::pipe_wake::ReadyOutcome`), checked at syscall boundaries, and
4029    /// cleared by the hand-off or by a scheduler request of its own. Always
4030    /// `None` with the option unset.
4031    #[serde(default)]
4032    pub(crate) pipe_handoff_due: Option<LogicalTime>,
4033    /// A signal this thread sent to its own multi-threaded process, which it
4034    /// must dequeue before another thread runs: until its own delivery stop
4035    /// for that signal no timeslice of it ends, at the target, at the PMU
4036    /// maximum or in a timer callback (<https://github.com/rrnewton/hermit/issues/4034>).
4037    #[serde(default)]
4038    pub(crate) own_signal_turn_hold: Option<libc::c_int>,
4039    /// Set when this thread's `rt_sigreturn` passes through, cleared by its
4040    /// next event of any other kind (`pre_handler_hook`). A signal stop that
4041    /// finds it set is the thread's first Detcore event since that
4042    /// `rt_sigreturn`: usually the delivery Linux makes on that same return
4043    /// to user space of a signal the restored mask unblocks, and otherwise a
4044    /// fault or host signal its user code met with no intercepted event in
4045    /// between (`Resources::continues_sigreturn`,
4046    /// <https://github.com/rrnewton/hermit/issues/4505>).
4047    #[serde(default)]
4048    pub(crate) returned_from_sigreturn: bool,
4049    /// How many of this thread's latest scheduler requests in a row were
4050    /// deliveries marked `Resources::continues_sigreturn`; any other request
4051    /// resets it. A delivery is marked only while it is below
4052    /// [`MAX_SIGRETURN_CONTINUATIONS`]. That cap is what stops a handler that
4053    /// raises its own signal from holding the CPU for ever, in every mode: a
4054    /// timeslice end did not interrupt such a run in practice (7,773
4055    /// deliveries in 15 s without one), and under `--max-timeslice=disabled`
4056    /// there is none.
4057    #[serde(default)]
4058    pub(crate) consecutive_continuations: u8,
4059
4060    /// Thread state associated with record/replay.
4061    pub record_or_replay: T,
4062
4063    /// How much longer does this thread get to run before it must check-in with the
4064    /// scheduler?  Note that this notion of time slice can extend across a region of time
4065    /// that includes syscalls (and thus handlers).
4066    ///
4067    /// If set to `None`, the thread can run indefinitely without preemption.
4068    ///
4069    /// This is in units of virtual Nanoseconds.  And it is an exact time in the future,
4070    /// not a relative duration.
4071    pub end_of_timeslice: Option<LogicalTime>,
4072
4073    // AUTONOMOUS-BOT-IMPLEMENTED
4074    // TODO-HUMAN-REVIEW(PR-1151)
4075    /// Exact per-thread PMU RCB target for the active preemption-replay slice.
4076    /// `None` selects the legacy logical-time deadline path.
4077    #[serde(default)]
4078    pub replay_rcb_end: Option<u64>,
4079
4080    // AUTONOMOUS-BOT-IMPLEMENTED
4081    // TODO-HUMAN-REVIEW(PR-1151)
4082    /// Deterministic chaos epoch this thread was in at its last `next_timeslice`.
4083    /// Used only to detect epoch transitions for `CHAOSEPOCH` logging; the epoch
4084    /// itself is recomputed each slice from `thread_logical_time`. Sentinel
4085    /// `u64::MAX` guarantees the first slice always logs its initial epoch.
4086    #[serde(default = "chaos_epoch_sentinel")]
4087    pub chaos_epoch: u64,
4088
4089    // AUTONOMOUS-BOT-IMPLEMENTED
4090    // TODO-HUMAN-REVIEW(PR-1151)
4091    /// Exact multiplier currently used to convert this thread's RCBs to virtual time.
4092    #[serde(default)]
4093    pub chaos_slowdown_factor: RcbTimeMultiplier,
4094
4095    // AUTONOMOUS-BOT-IMPLEMENTED
4096    // TODO-HUMAN-REVIEW(PR-1151)
4097    /// True when live chaos configuration or a replay artifact supplies the factor.
4098    #[serde(default)]
4099    pub chaos_slowdown_active: bool,
4100
4101    /// This thread claimed a `SIGCHLD` for a sleep (`SleepSignal::Claimed`),
4102    /// and the claimed copy's delivery stop has not come yet. That stop places
4103    /// the delivery (`ChildExitSigchldControl::ClaimedDelivery`) just before
4104    /// it asks for its turn, so the mark the scheduler keeps is bound to that
4105    /// copy. A system call, or a copy the ledger drops, clears this once
4106    /// SIGCHLD is no longer pending for the thread (the claimed copy was never
4107    /// delivered to it; `syscalls::signal::claim_still_pending`).
4108    #[serde(default)]
4109    pub(crate) claimed_sigchld: bool,
4110
4111    // AUTONOMOUS-BOT-IMPLEMENTED
4112    // TODO-HUMAN-REVIEW(PR-1151)
4113    /// Transitions waiting to be committed into the preemption artifact.
4114    #[serde(default)]
4115    pub pending_chaos_epochs: Vec<ChaosEpochTransition>,
4116
4117    /// Absolute deadline enforced by the PMU-backed `--max-timeslice` timer. This is separate from
4118    /// `end_of_timeslice` so syscall-heavy workloads can use a shorter, cheap target deadline.
4119    pub max_timeslice_end: Option<LogicalTime>,
4120
4121    /// The deadline hint carried by the last scheduler reply this thread
4122    /// received (`ThreadState::cap_timeslice_at_deadline`). Applied when the
4123    /// reply arrives, and again by the two paths that then install a fresh
4124    /// slice end: thread start and the exec continuation.
4125    pub last_grant_deadline: Option<Duration>,
4126
4127    /// Track what our last timer was set for, just to double check that RCB timers are behaving
4128    /// as expected and see if we went over.  (For exmaple, this behaves badly if threads are not
4129    /// pinned and our we migrate between cores.)
4130    pub last_rcb_timer: Option<u64>,
4131
4132    /// Whether `last_rcb_timer` represents the maximum deadline rather than a manual interrupt.
4133    #[serde(default)]
4134    pub last_rcb_timer_is_max: bool,
4135
4136    /// Are we past the global moment when the guest's first execve of its root binary completes
4137    /// (with a successful exit code).
4138    pub(crate) past_global_first_execve: bool,
4139
4140    /// Guest address of this thread's `struct robust_list_head`, as last
4141    /// registered by a successful `set_robust_list(2)`.
4142    ///
4143    /// Linux clears `task->robust_list` in `copy_process()` and in `execve`, so
4144    /// this is never inherited: every thread re-registers its own head (glibc
4145    /// does so in `start_thread`). Detcore replays the kernel's
4146    /// `exit_robust_list()` walk from this address when the thread exits; see
4147    /// `crate::syscalls::robust_list`.
4148    #[serde(default)]
4149    pub(crate) robust_list_head: Option<usize>,
4150
4151    /// Per-thread registrations are mirrored here while their shared address
4152    /// space is readable, so a group exit can walk every dying sibling's list.
4153    #[serde(default)]
4154    pub(crate) robust_list_process: Arc<Mutex<RobustListProcessState>>,
4155}
4156
4157/// We cannot assume that the record_or_replay "subtool" is Debug, so it is handy to be able to
4158/// print the Detcore threadstate alone.
4159impl<T> std::fmt::Debug for ThreadState<T> {
4160    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4161        f.debug_struct("ThreadState")
4162            .field("dettid", &self.dettid)
4163            .field("detpid", &self.detpid)
4164            .field("physical_tid", &self.physical_tid)
4165            .field("mm_id", &self.mm_id)
4166            .field("memory_metadata", &self.memory_metadata)
4167            .field("stats", &self.stats)
4168            .field("clone_flags", &self.clone_flags)
4169            .field("file_metadata", &self.file_metadata)
4170            .field("process_files", &self.process_files)
4171            .field("posix_timers", &self.posix_timers)
4172            .field("resource_limits", &self.resource_limits)
4173            .field("process_cpu_time", &self.process_cpu_time)
4174            .field("prng", &self.prng)
4175            .field("chaos_prng", &self.chaos_prng)
4176            .field("thread_logical_time", &self.thread_logical_time)
4177            .field("committed_clock_value", &self.committed_clock_value)
4178            .field("end_of_timeslice", &self.end_of_timeslice)
4179            .field("replay_rcb_end", &self.replay_rcb_end)
4180            .field("chaos_epoch", &self.chaos_epoch)
4181            .field("chaos_slowdown_factor", &self.chaos_slowdown_factor)
4182            .field("chaos_slowdown_active", &self.chaos_slowdown_active)
4183            .field("max_timeslice_end", &self.max_timeslice_end)
4184            .field("last_rcb_timer", &self.last_rcb_timer)
4185            .field("last_rcb_timer_is_max", &self.last_rcb_timer_is_max)
4186            .finish()
4187    }
4188}
4189
4190impl<T> Default for ThreadState<T> {
4191    fn default() -> Self {
4192        unreachable!()
4193    }
4194}
4195
4196// AUTONOMOUS-BOT-IMPLEMENTED
4197// TODO-HUMAN-REVIEW(PR-1151)
4198/// Sentinel for `ThreadState::chaos_epoch` before the first `next_timeslice`.
4199/// `u64::MAX` can never equal a real epoch (`current_ns / N`), so the first
4200/// chaos slice always emits its `CHAOSEPOCH` transition.
4201pub(crate) fn chaos_epoch_sentinel() -> u64 {
4202    u64::MAX
4203}
4204
4205impl<T> AsRef<T> for ThreadState<T> {
4206    fn as_ref(&self) -> &T {
4207        &self.record_or_replay
4208    }
4209}
4210
4211impl<T> AsMut<T> for ThreadState<T> {
4212    fn as_mut(&mut self) -> &mut T {
4213        &mut self.record_or_replay
4214    }
4215}
4216
4217// AUTONOMOUS-BOT-IMPLEMENTED
4218// TODO-HUMAN-REVIEW(PR-1149)
4219/// RR-style stable per-thread slowdown factor for chaos scheduling.
4220///
4221/// Returns the multiplier applied to a thread's *mean* chaos timeslice length.
4222/// A factor `> 1.0` means the thread is preempted less often (runs "faster"
4223/// between preemptions — a slower relative wall-clock for its peers), `< 1.0`
4224/// means it is preempted more often. The factor is drawn log-uniformly from
4225/// `[1/max_factor, max_factor]`, so slow and fast are symmetric in log-space
4226/// and `1.0` is the geometric center.
4227///
4228/// The value is a **pure, deterministic function** of `(sched_seed, dettid)`:
4229/// it depends on no run-order, no wall-clock, and no shared PRNG state, so it
4230/// is stable for a thread across the whole run and reproducible under a fixed
4231/// seed (unlike the per-timeslice `chaos_prng` draw, which is redrawn every
4232/// slice and averages out over a long run). Threads are perturbed by a fixed
4233/// constant so the factor stream differs from other seed-derived streams (e.g.
4234/// `post_fork_prng`) that also start from `sched_seed`.
4235///
4236/// `max_factor <= 1.0` disables the spread and returns `1.0` (nominal) for
4237/// every thread; callers validate `max_factor >= 1.0`.
4238// AUTONOMOUS-BOT-IMPLEMENTED
4239// TODO-HUMAN-REVIEW(PR-1151)
4240/// `epoch` selects a deterministic chaos EPOCH: the factor is redrawn per
4241/// (thread, epoch) so a thread's bias changes in deterministic phases across a
4242/// long run instead of staying fixed. `epoch == 0` reproduces the epoch-less
4243/// per-thread-slowdown value EXACTLY (the epoch term is `0` and cancels out of
4244/// the mix), so enabling epochs never perturbs the first epoch's behavior.
4245pub(crate) fn chaos_per_thread_slowdown_factor(
4246    sched_seed: u64,
4247    dettid: DetTid,
4248    epoch: u64,
4249    max_factor: f64,
4250) -> RcbTimeMultiplier {
4251    // `<=` (rather than `!(max_factor > 1.0)`) keeps clippy's partial-ord lint
4252    // happy; validate_invariants already rejects non-finite factors upstream.
4253    if max_factor <= 1.0 {
4254        return RcbTimeMultiplier::ONE;
4255    }
4256    // Mix the seed with the (stable) deterministic thread id to give each
4257    // thread its own point in the factor distribution. The salt keeps this
4258    // stream distinct from other sched_seed-derived streams.
4259    const SLOWDOWN_SALT: u64 = 0x736c_6f77_646f_776e; // "slowdown"
4260    // AUTONOMOUS-BOT-IMPLEMENTED
4261    // TODO-HUMAN-REVIEW(PR-1151)
4262    // Fold the epoch into the mix with its own golden-ratio multiplier. At
4263    // `epoch == 0` this term is 0, leaving `mixed` identical to the epoch-less
4264    // factor; each successive epoch decorrelates the draw deterministically.
4265    const EPOCH_GOLDEN: u64 = 0xbf58_476d_1ce4_e5b9;
4266    let mixed = sched_seed
4267        ^ SLOWDOWN_SALT
4268        ^ ((dettid.as_raw() as u32 as u64).wrapping_mul(0x9e37_79b9_7f4a_7c15))
4269        ^ epoch.wrapping_mul(EPOCH_GOLDEN);
4270    let mut prng = Pcg64Mcg::seed_from_u64(mixed);
4271    // u in [0,1); map to exponent in [-1, 1) then factor = max_factor^exp,
4272    // i.e. a log-uniform draw over [1/max_factor, max_factor).
4273    let u: f64 = prng.random::<f64>();
4274    let exponent = 2.0 * u - 1.0;
4275    RcbTimeMultiplier::from_f64(max_factor.powf(exponent))
4276}
4277
4278impl<T> ThreadState<T> {
4279    /// What `observe_guest_clock(raw)` would return, without raising the
4280    /// clock's floor: the guest clock as of a raw observation.
4281    pub(crate) fn peek_guest_clock(&self, raw: LogicalTime) -> LogicalTime {
4282        let clock = self.guest_clock.lock().expect("guest clock mutex poisoned");
4283        clock.now.max(raw)
4284    }
4285
4286    /// Inspect the live per-thread cut. Physical task count, childlessness,
4287    /// coordinator leases and signal dispositions need their own admission;
4288    /// neither serde nor these lock probes establish those facts.
4289    pub(crate) fn validate_native_exec_cut(
4290        &self,
4291        binding: &crate::native_exec::NativeExecCutBinding,
4292        config: &Config,
4293    ) -> Result<(), crate::native_exec::NativeExecCutError> {
4294        use crate::native_exec::NativeExecCutError;
4295        use crate::native_exec::try_native_exec_lock;
4296
4297        if self.dettid != binding.dettid
4298            || self.detpid != Some(binding.detpid)
4299            || self.physical_tid != Some(binding.physical_tid)
4300        {
4301            return Err(NativeExecCutError::Identity("ThreadState IDs"));
4302        }
4303        if !self.thread_start_entered || !self.past_global_first_execve {
4304            return Err(NativeExecCutError::PreparedState("initial lifecycle"));
4305        }
4306        if self.tool_shares_guest_descriptor_table
4307            != config.backend.tool_shares_guest_descriptor_table
4308        {
4309            return Err(NativeExecCutError::Identity("descriptor-table capability"));
4310        }
4311        if self.nested_pid_namespace {
4312            return Err(NativeExecCutError::LiveCapability("nested PID namespace"));
4313        }
4314        if self.signal_task_identity.is_some() {
4315            return Err(NativeExecCutError::LiveCapability("signal task identity"));
4316        }
4317        if self.parent_process_cpu_time.is_some() || self.parent_cpu_publication.is_some() {
4318            return Err(NativeExecCutError::LiveCapability("parent CPU ownership"));
4319        }
4320        if self.restart_block.is_some() || self.signal_register_projection.is_some() {
4321            return Err(NativeExecCutError::LiveCapability("restart/projection"));
4322        }
4323        if self.claimed_sigchld {
4324            return Err(NativeExecCutError::LiveCapability("claimed SIGCHLD"));
4325        }
4326        if self.clone_flags.is_some() || self.pending_vfork.is_some() {
4327            return Err(NativeExecCutError::LiveCapability("clone/vfork"));
4328        }
4329        if self.own_signal_turn_hold.is_some()
4330            || self.sigalrm_handled
4331            || self.handler_restore_rt_reported != 0
4332        {
4333            return Err(NativeExecCutError::LiveCapability("guest signal handler"));
4334        }
4335        if self.initialized_random_auxv.is_some() {
4336            return Err(NativeExecCutError::LiveCapability("initial random handoff"));
4337        }
4338        if self.uncharged_bootstrap_syscalls != 0
4339            || self.in_uncharged_bootstrap_syscall
4340            || self.yield_after_futex_wake
4341        {
4342            return Err(NativeExecCutError::LiveCapability(
4343                "bootstrap/yield transient",
4344            ));
4345        }
4346        if self.preemption_points.is_some()
4347            || !self.interrupt_at.is_empty()
4348            || self.replay_rcb_end.is_some()
4349            || self.last_rcb_timer.is_some()
4350            || self.last_rcb_timer_is_max
4351            || self.max_timeslice_end.is_some()
4352            || self.chaos_slowdown_active
4353            || !self.pending_chaos_epochs.is_empty()
4354        {
4355            return Err(NativeExecCutError::LiveCapability("RCB/replay/chaos state"));
4356        }
4357        let user = self.thread_logical_time.user_cpu_time();
4358        let system = self.thread_logical_time.system_cpu_time();
4359        if self.thread_cpu_start_user_time > self.last_accounted_user_time
4360            || self.last_accounted_user_time > user
4361            || self.thread_cpu_start_system_time > self.last_accounted_system_time
4362            || self.last_accounted_system_time > system
4363        {
4364            return Err(NativeExecCutError::PreparedState(
4365                "CPU accounting checkpoints",
4366            ));
4367        }
4368        try_native_exec_lock(&self.process_cpu_time, "process_cpu_time")?
4369            .validate_native_exec_cut()?;
4370        // Do not call observe/accounting routines: pending deltas and the
4371        // process-tree guest floor are continuing state, not a new epoch.
4372        drop(try_native_exec_lock(&self.guest_clock, "guest_clock")?);
4373        drop(try_native_exec_lock(
4374            &self.resource_limits,
4375            "resource_limits",
4376        )?);
4377        drop(try_native_exec_lock(&self.posix_timers, "posix_timers")?);
4378        Ok(())
4379    }
4380
4381    pub(crate) fn validate_old_native_exec_robust_state(
4382        &self,
4383    ) -> Result<(), crate::native_exec::NativeExecCutError> {
4384        use crate::native_exec::NativeExecCutError;
4385        let process = crate::native_exec::try_native_exec_lock(
4386            &self.robust_list_process,
4387            "robust_list_process",
4388        )?;
4389        if process.heads.len() != usize::from(self.robust_list_head.is_some())
4390            || process.heads.get(&self.dettid).copied() != self.robust_list_head
4391            || !process.pending.is_empty()
4392            || !process.matched_physical_exits.is_empty()
4393            || !process.exec_pending.is_empty()
4394            || !process.tool_walked.is_empty()
4395            || process.exit_group_filed
4396            || !process.exit_group_filers.is_empty()
4397            || process.exit_group_walker.is_some()
4398            || process.exit_group_walked
4399        {
4400            return Err(NativeExecCutError::LiveCapability(
4401                "old robust process state",
4402            ));
4403        }
4404        Ok(())
4405    }
4406
4407    pub(crate) fn validate_prepared_native_exec_cut(
4408        &self,
4409        binding: &crate::native_exec::NativeExecCutBinding,
4410    ) -> Result<(), crate::native_exec::NativeExecCutError> {
4411        use crate::native_exec::NativeExecCutError;
4412        use crate::native_exec::try_native_exec_lock;
4413
4414        if self.mm_id != binding.prepared_mm() {
4415            return Err(NativeExecCutError::Identity("prepared mm"));
4416        }
4417        try_native_exec_lock(&self.file_metadata, "prepared file_metadata")?
4418            .validate_native_exec_cut(binding.prepared_files(), true)?;
4419        if !try_native_exec_lock(&self.memory_metadata, "memory_metadata")?
4420            .is_fresh_for_native_exec()
4421        {
4422            return Err(NativeExecCutError::PreparedState("memory_metadata"));
4423        }
4424        let process = try_native_exec_lock(&self.robust_list_process, "robust_list_process")?;
4425        if self.robust_list_head.is_some()
4426            || !process.heads.is_empty()
4427            || !process.pending.is_empty()
4428            || !process.matched_physical_exits.is_empty()
4429            || !process.tool_walked.is_empty()
4430            || process.exit_group_filed
4431            || !process.exit_group_filers.is_empty()
4432            || process.exit_group_walker.is_some()
4433            || process.exit_group_walked
4434        {
4435            return Err(NativeExecCutError::PreparedState("robust process state"));
4436        }
4437        // These wakes belong to the old image. Preserve their order and keys
4438        // for the actual successful post-exec hook; do not rebase or consume.
4439        for (owner, wake) in &process.exec_pending {
4440            if *owner != binding.dettid
4441                || matches!(wake.futex, FutexID::Private { mm, .. } if mm != binding.old_mm)
4442            {
4443                return Err(NativeExecCutError::PreparedState("staged robust wake"));
4444            }
4445        }
4446        Ok(())
4447    }
4448
4449    pub(crate) fn observe_guest_clock(&self, raw: LogicalTime) -> LogicalTime {
4450        self.guest_clock
4451            .lock()
4452            .expect("guest clock mutex poisoned")
4453            .observe(raw)
4454    }
4455
4456    // AUTONOMOUS-BOT-IMPLEMENTED
4457    // TODO-HUMAN-REVIEW(PR-1060): Review backend-stable child RNG reseeding.
4458    /// Replaces the host-TID-derived child streams with a backend-provided,
4459    /// deterministic identity before the thread enters its start hook.
4460    pub fn reseed_child_rngs(&mut self, parent: &Self, entropy: u128) {
4461        self.prng = thread_rng_from_parent_entropy("USER RAND", &parent.prng, entropy);
4462        self.chaos_prng = thread_rng_from_parent_entropy("CHAOSRAND", &parent.chaos_prng, entropy);
4463    }
4464
4465    // AUTONOMOUS-BOT-IMPLEMENTED
4466    // TODO-HUMAN-REVIEW(PR-845): Review SaBRe orphan-thread memory identity recovery.
4467    /// Repair a thread state that a remote backend had to initialize without
4468    /// access to its parent's state.
4469    pub(crate) fn recover_process_mm_id(&mut self, detpid: DetPid) -> bool {
4470        if self.dettid == detpid || self.mm_id != MmId::initial(self.dettid) {
4471            return false;
4472        }
4473
4474        self.mm_id = MmId::initial(detpid);
4475        true
4476    }
4477
4478    pub(crate) fn account_process_cpu_time(&mut self) {
4479        let user = self.thread_logical_time.user_cpu_time();
4480        let system = self.thread_logical_time.system_cpu_time();
4481        let user_delta = user - self.last_accounted_user_time;
4482        let system_delta = system - self.last_accounted_system_time;
4483        self.process_cpu_time
4484            .lock()
4485            .expect("process CPU time mutex poisoned")
4486            .add_thread_delta(user_delta, system_delta);
4487        self.last_accounted_user_time = user;
4488        self.last_accounted_system_time = system;
4489    }
4490
4491    /// Decide whether the syscall this thread is making now charges its cost
4492    /// to `thread_logical_time`. `in_backend_runtime_bootstrap` is the
4493    /// backend's `Guest::is_backend_runtime_bootstrap()` answer for this
4494    /// thread at this syscall.
4495    ///
4496    /// Outside a bootstrap window every syscall is charged, and the
4497    /// per-window count of uncharged syscalls goes back to zero. Inside a
4498    /// window a syscall that observes virtual time is always charged; any
4499    /// other syscall is left uncharged until
4500    /// [`syscall_time::MAX_UNCHARGED_BOOTSTRAP_SYSCALLS`] of them have been,
4501    /// and every syscall after that in the same window is charged. Reaching
4502    /// the cap logs one info line for the window.
4503    ///
4504    /// [`syscall_time::MAX_UNCHARGED_BOOTSTRAP_SYSCALLS`]: crate::syscall_time::MAX_UNCHARGED_BOOTSTRAP_SYSCALLS
4505    pub(crate) fn charge_syscall_time(
4506        &mut self,
4507        in_backend_runtime_bootstrap: bool,
4508        sysno: Sysno,
4509    ) -> bool {
4510        if !in_backend_runtime_bootstrap {
4511            if self.uncharged_bootstrap_syscalls != 0 {
4512                debug!(
4513                    "[dtid {}] backend runtime bootstrap window left {} syscalls uncharged",
4514                    self.dettid, self.uncharged_bootstrap_syscalls
4515                );
4516                self.uncharged_bootstrap_syscalls = 0;
4517            }
4518            return true;
4519        }
4520        if crate::syscall_time::observes_virtual_time(sysno) {
4521            return true;
4522        }
4523        if self.uncharged_bootstrap_syscalls < crate::syscall_time::MAX_UNCHARGED_BOOTSTRAP_SYSCALLS
4524        {
4525            self.uncharged_bootstrap_syscalls += 1;
4526            if self.uncharged_bootstrap_syscalls
4527                == crate::syscall_time::MAX_UNCHARGED_BOOTSTRAP_SYSCALLS
4528            {
4529                // Once per window: the count stays at the cap from here on.
4530                info!(
4531                    "[dtid {}] backend runtime bootstrap window reached its cap of {} uncharged syscalls; every further syscall in this window is charged",
4532                    self.dettid,
4533                    crate::syscall_time::MAX_UNCHARGED_BOOTSTRAP_SYSCALLS
4534                );
4535            }
4536            return false;
4537        }
4538        true
4539    }
4540
4541    pub(crate) fn process_cpu_time(&mut self) -> ProcessCpuSnapshot {
4542        self.account_process_cpu_time();
4543        self.process_cpu_time
4544            .lock()
4545            .expect("process CPU time mutex poisoned")
4546            .snapshot
4547    }
4548
4549    /// This thread's own logical (user, system) CPU time.
4550    ///
4551    /// `getrusage(RUSAGE_THREAD)` needs the per-thread counters, not the process aggregate
4552    /// that [`Self::process_cpu_time`] returns; for a multithreaded guest the two differ and
4553    /// reporting the aggregate would over-report every thread. Reads the same
4554    /// `thread_logical_time` counters that `account_process_cpu_time` folds into the process
4555    /// total, minus the absolute clock inherited when this thread was created.
4556    pub(crate) fn thread_cpu_time(&self) -> (LogicalTime, LogicalTime) {
4557        (
4558            self.thread_logical_time.user_cpu_time() - self.thread_cpu_start_user_time,
4559            self.thread_logical_time.system_cpu_time() - self.thread_cpu_start_system_time,
4560        )
4561    }
4562
4563    pub(crate) fn record_exited_child_process_cpu_time(&mut self, pid: DetPid) -> bool {
4564        self.account_process_cpu_time();
4565        let Some(parent) = &self.parent_process_cpu_time else {
4566            return true;
4567        };
4568        let child = self
4569            .process_cpu_time
4570            .lock()
4571            .expect("process CPU time mutex poisoned")
4572            .snapshot;
4573        {
4574            let mut parent = parent
4575                .lock()
4576                .expect("parent process CPU time mutex poisoned");
4577            if let Some(publication) = &self.parent_cpu_publication
4578                && !parent
4579                    .child_cpu_publications
4580                    .get(&pid)
4581                    .is_some_and(|current| Arc::ptr_eq(current, publication))
4582            {
4583                return false;
4584            }
4585            parent.record_exited_child(pid, child);
4586        }
4587        if let Some(publication) = &self.parent_cpu_publication {
4588            publication.finish(true);
4589        }
4590        true
4591    }
4592
4593    /// Called once at the process child's ThreadState birth. The later external
4594    /// registration's legacy prepare_child call must not replace this token.
4595    pub(crate) fn prepare_child_cpu_publication(&self, pid: DetPid) -> Arc<ChildCpuPublication> {
4596        let publication = ChildCpuPublication::pending();
4597        let previous = {
4598            let mut parent = self
4599                .process_cpu_time
4600                .lock()
4601                .expect("process CPU time mutex poisoned");
4602            parent.prepare_child(pid);
4603            parent
4604                .child_cpu_publications
4605                .insert(pid, Arc::clone(&publication))
4606        };
4607        if let Some(previous) = previous {
4608            previous.finish(false);
4609        }
4610        publication
4611    }
4612
4613    pub(crate) async fn wait_for_child_cpu_publication(&self, pid: DetPid) -> bool {
4614        let publication = {
4615            let parent = self
4616                .process_cpu_time
4617                .lock()
4618                .expect("process CPU time mutex poisoned");
4619            let Some(publication) = parent.child_cpu_publications.get(&pid) else {
4620                return false;
4621            };
4622            Arc::clone(publication)
4623        };
4624        // Subscription and publication share the token mutex. Registration
4625        // followed by a state recheck cannot lose a publication wake. Neither
4626        // this mutex nor the accounting mutex survives a Pending return.
4627        if !publication.wait().await {
4628            return false;
4629        }
4630        let parent = self
4631            .process_cpu_time
4632            .lock()
4633            .expect("process CPU time mutex poisoned");
4634        parent
4635            .child_cpu_publications
4636            .get(&pid)
4637            .is_some_and(|current| Arc::ptr_eq(current, &publication))
4638            && parent.exited_children.contains_key(&pid)
4639    }
4640
4641    pub(crate) fn has_exited_child_process_cpu_time(&self, pid: DetPid) -> bool {
4642        self.process_cpu_time
4643            .lock()
4644            .expect("process CPU time mutex poisoned")
4645            .exited_children
4646            .contains_key(&pid)
4647    }
4648
4649    pub(crate) fn reap_child_process_cpu_time(&mut self, pid: DetPid) {
4650        self.account_process_cpu_time();
4651        let publication = {
4652            let mut parent = self
4653                .process_cpu_time
4654                .lock()
4655                .expect("process CPU time mutex poisoned");
4656            // Preserve legacy missing-snapshot behavior. The KVM waitid path
4657            // requires the snapshot before its irreversible completion.
4658            let had_snapshot = parent.exited_children.contains_key(&pid);
4659            parent.reap_child(pid);
4660            if had_snapshot {
4661                parent.child_cpu_publications.remove(&pid)
4662            } else {
4663                None
4664            }
4665        };
4666        if let Some(publication) = publication {
4667            publication.finish(false);
4668        }
4669    }
4670
4671    pub(crate) fn prepare_child_process_cpu_time(&self, pid: DetPid) {
4672        let mut parent = self
4673            .process_cpu_time
4674            .lock()
4675            .expect("process CPU time mutex poisoned");
4676        // External registration may repeat preparation after ThreadState birth.
4677        // Only that birth replaces a KVM token; registration must preserve both
4678        // a pending token and any already-published snapshot for this birth.
4679        if !parent.child_cpu_publications.contains_key(&pid) {
4680            parent.prepare_child(pid);
4681        }
4682    }
4683
4684    /// Create a fresh new thread state from nothing.  In practice this is only used for the thread
4685    /// state of the root thread of the container.
4686    pub fn new(pid: DetPid, cfg: &Config, record_or_replay: T) -> Self {
4687        detlog!(
4688            "USER RAND: seeding PRNG for root thread with seed {}",
4689            cfg.rng_seed()
4690        );
4691        detlog!(
4692            "CHAOSRAND: seeding chaos scheduler with seed {}",
4693            cfg.sched_seed()
4694        );
4695        let thread_logical_time = DetTime::new(cfg);
4696        let last_accounted_user_time = thread_logical_time.user_cpu_time();
4697        let last_accounted_system_time = thread_logical_time.system_cpu_time();
4698        let file_metadata = if cfg.backend.tool_shares_guest_descriptor_table {
4699            let mut metadata = FileMetadata::new(pid);
4700            for fd in 0..=2 {
4701                match metadata.discover_fd_from_current_process(pid, fd) {
4702                    Ok(()) | Err(Errno::EBADF) => {}
4703                    Err(error) => panic!("unable to discover guest stdio {fd}: {error}"),
4704                }
4705            }
4706            metadata
4707        } else {
4708            FileMetadata::new(pid).setup_stdio(pid.into(), pid)
4709        };
4710        let process_files = Some(file_metadata.files_id);
4711        ThreadState {
4712            dettid: pid,
4713            detpid: None, // Initialized later.
4714            thread_start_entered: false,
4715            physical_tid: None,
4716            signal_task_identity: None,
4717            open_file_creator: None,
4718            mm_id: MmId::initial(pid),
4719            memory_metadata: Arc::new(Mutex::new(MemoryMetadata::new())),
4720            pedigree: Pedigree::new(), // Root thread.
4721            stats: ThreadStats::new(),
4722            file_metadata: Arc::new(Mutex::new(file_metadata)),
4723            tool_shares_guest_descriptor_table: cfg.backend.tool_shares_guest_descriptor_table,
4724            timer_slack_ns: DEFAULT_TIMER_SLACK_NS,
4725            default_timer_slack_ns: DEFAULT_TIMER_SLACK_NS,
4726            nested_pid_namespace: false,
4727            changed_root: Default::default(),
4728            exe: None,
4729            process_files,
4730            posix_timers: Arc::new(Mutex::new(PosixTimers::default())),
4731            resource_limits: Arc::new(Mutex::new(ResourceLimits::default())),
4732            process_cpu_time: Arc::new(Mutex::new(ProcessCpuTime::default())),
4733            guest_clock: Arc::new(Mutex::new(GuestClock::default())),
4734            parent_process_cpu_time: None,
4735            parent_cpu_publication: None,
4736            restart_block: None,
4737            sigalrm_handled: false,
4738            signal_shadow: None,
4739            signal_shadow_lost: false,
4740            delivery_interruption: None,
4741            delivery_frame_handler: 0,
4742            delivery_counters: Default::default(),
4743            published_mask: Some(None),
4744            published_dispositions: Arc::default(),
4745            sigalrm_blocked_published: false,
4746            handler_restore_rt_reported: 0,
4747            signal_register_projection: None,
4748            last_accounted_user_time,
4749            last_accounted_system_time,
4750            thread_cpu_start_user_time: last_accounted_user_time,
4751            thread_cpu_start_system_time: last_accounted_system_time,
4752            clone_flags: None,
4753            pending_vfork: None,
4754            // For the root thread, we initialize from the seed in the config:
4755            prng: crate::random::root_prng(cfg.rng_seed()),
4756            initialized_random_auxv: None,
4757            chaos_prng: Pcg64Mcg::seed_from_u64(cfg.sched_seed()),
4758            thread_logical_time,
4759            committed_clock_value: 0,
4760            uncharged_bootstrap_syscalls: 0,
4761            in_uncharged_bootstrap_syscall: false,
4762            yield_after_futex_wake: false,
4763            pipe_handoff_due: None,
4764            own_signal_turn_hold: None,
4765            returned_from_sigreturn: false,
4766            consecutive_continuations: 0,
4767            end_of_timeslice: None, // Temporary/bogus.
4768            replay_rcb_end: None,
4769            // AUTONOMOUS-BOT-IMPLEMENTED
4770            // TODO-HUMAN-REVIEW(PR-1151)
4771            chaos_epoch: chaos_epoch_sentinel(),
4772            // AUTONOMOUS-BOT-IMPLEMENTED
4773            // TODO-HUMAN-REVIEW(PR-1151)
4774            chaos_slowdown_factor: RcbTimeMultiplier::ONE,
4775            chaos_slowdown_active: false,
4776            claimed_sigchld: false,
4777            pending_chaos_epochs: Vec::new(),
4778            max_timeslice_end: None,
4779            last_grant_deadline: None,
4780            published_runtime_private_memory: None,
4781            last_rcb_timer: None,
4782            last_rcb_timer_is_max: false,
4783            record_or_replay,
4784            preemption_points: None,
4785            past_global_first_execve: false,
4786            interrupt_at: cfg.interrupts_for_thread(pid),
4787            robust_list_head: None,
4788            robust_list_process: Arc::new(Mutex::new(RobustListProcessState::default())),
4789        }
4790    }
4791
4792    /// Apply a required, authenticated initial-image random handoff to the
4793    /// normal root. Errors are tool initialization failures, never guest errno.
4794    pub fn apply_initial_random_state(
4795        &mut self,
4796        bytes: &[u8],
4797        config: &Config,
4798        image: crate::random::InitialImage,
4799    ) -> Result<(), Errno> {
4800        if self.initialized_random_auxv.is_some()
4801            || self.past_global_first_execve
4802            || self.dettid.as_raw() != image.pid
4803            || self.clone_flags.is_some()
4804            || self.pedigree.raw() != Pedigree::new().raw()
4805        {
4806            return Err(Errno::EPROTO);
4807        }
4808        let (prng, at_random_value, early_requests) =
4809            crate::random::decode_initial_state(bytes, config, image)?;
4810        self.prng = prng;
4811        self.initialized_random_auxv = Some((image, at_random_value, early_requests));
4812        Ok(())
4813    }
4814
4815    /// Consume the early auxv write's fact, returning the bytes it wrote and
4816    /// the requests served before post-exec, in order, or `None` when no
4817    /// backend wrote AT_RANDOM before post-exec.
4818    pub(crate) fn complete_initial_random_auxv(
4819        &mut self,
4820        pointer: Option<usize>,
4821    ) -> Result<Option<crate::random::EarlyRandomRecords>, Errno> {
4822        let Some((image, _, _)) = self.initialized_random_auxv.as_ref() else {
4823            return Ok(None);
4824        };
4825        if pointer != Some(image.at_random) || self.dettid.as_raw() != image.pid {
4826            return Err(Errno::EPROTO);
4827        }
4828        let (_, at_random_value, early_requests) =
4829            self.initialized_random_auxv.take().expect("checked above");
4830        Ok(Some((at_random_value, early_requests)))
4831    }
4832
4833    pub(crate) fn record_robust_list_head(&mut self, head: Option<usize>) {
4834        self.robust_list_head = head;
4835        let mut process = self
4836            .robust_list_process
4837            .lock()
4838            .expect("robust-list process state mutex poisoned");
4839        if let Some(head) = head {
4840            process.heads.insert(self.dettid, head);
4841        } else {
4842            process.heads.remove(&self.dettid);
4843        }
4844    }
4845
4846    /// Record that Detcore has walked this thread's own robust list at its
4847    /// exit (`OwnerDeathPath::Barrier`), so a later exit_group of its group
4848    /// does not walk the list again ([`exit_group_robust_list_owners`]).
4849    pub(crate) fn mark_robust_list_walked_by_tool(&self) {
4850        self.robust_list_process
4851            .lock()
4852            .expect("robust-list process state mutex poisoned")
4853            .tool_walked
4854            .insert(self.dettid);
4855    }
4856
4857    /// Note that an exit_group on DBT (`OwnerDeathPath::Barrier`) has been
4858    /// filed. From now on a thread the exit_group's grant kills waits for its
4859    /// walk before its native exit ([`Self::wait_for_exit_group_robust_walk`]),
4860    /// and a thread of the group that exits keeps its head registered for the
4861    /// walk, so the walk sees the registrations current at the grant even if
4862    /// an exit hook runs first. A registration, replacement or unregistration
4863    /// a thread makes still takes effect.
4864    ///
4865    /// Nothing clears the filing: the thread group ends with the exit_group.
4866    /// The one exception is an exec granted first, which kills the filer.
4867    /// Where exec keeps this shared state for the new image, killed threads'
4868    /// old heads would then stay listed for a later exit_group. Only DBT files,
4869    /// and there the exec replaces the in-guest runtime's memory, this state
4870    /// included; modeling exec on DBT
4871    /// (<https://github.com/rrnewton/hermit/issues/4268>) must keep it so.
4872    pub(crate) fn file_exit_group_for_robust_lists(&self) {
4873        let mut process = self
4874            .robust_list_process
4875            .lock()
4876            .expect("robust-list process state mutex poisoned");
4877        process.exit_group_filed = true;
4878        process.exit_group_filers.insert(self.dettid);
4879    }
4880
4881    /// Note that this thread's exit_group was granted and that it now walks
4882    /// the group's lists. Only this thread does not wait for the walk: any
4883    /// other thread, including one that filed an exit_group of its own and
4884    /// was killed by this one's grant, waits.
4885    pub(crate) fn begin_exit_group_robust_walk(&self) {
4886        self.robust_list_process
4887            .lock()
4888            .expect("robust-list process state mutex poisoned")
4889            .exit_group_walker = Some(self.dettid);
4890    }
4891
4892    /// Note that this thread was killed, so any exit_group it filed can never
4893    /// be granted. Once every filing is cancelled this way with none granted
4894    /// (an exec ended the group first), no walk will come, and the threads
4895    /// waiting for one are released ([`Self::wait_for_exit_group_robust_walk`]).
4896    pub(crate) fn cancel_exit_group_filing(&self) {
4897        self.robust_list_process
4898            .lock()
4899            .expect("robust-list process state mutex poisoned")
4900            .exit_group_filers
4901            .remove(&self.dettid);
4902    }
4903
4904    /// Note that the filed exit_group's walk has finished, releasing the
4905    /// threads it killed ([`Self::wait_for_exit_group_robust_walk`]).
4906    pub(crate) fn finish_exit_group_robust_walk(&self) {
4907        self.robust_list_process
4908            .lock()
4909            .expect("robust-list process state mutex poisoned")
4910            .exit_group_walked = true;
4911    }
4912
4913    /// Where an exit_group of this thread's group is filed and this thread is
4914    /// not walking it, wait until that exit_group's walk has finished, or until
4915    /// every filing has been cancelled with none granted, at most `bound`.
4916    /// Returns false if the bound expired first, which the caller treats as a
4917    /// failure of the run, never as permission to go on.
4918    ///
4919    /// A thread the exit_group kills retires with a native exit. On DBT that
4920    /// exit first rewrites the thread's robust-list owner words to its host
4921    /// TID and then lets Linux mark them, which would race the walk: the walk
4922    /// could find a word that no longer names its owner, and could not tell
4923    /// whose it was. Waiting makes the walk see every word as the guest left
4924    /// it. That includes a thread that filed an exit_group of its own and was
4925    /// killed by another's grant; only the thread whose exit_group was granted
4926    /// ([`Self::begin_exit_group_robust_walk`]) does not wait. The wait is on
4927    /// host time, but nothing guest-visible depends on how long it takes: the
4928    /// thread is already logically dead. A walk that never comes, because an
4929    /// exec killed every filer first, is recognised when the last filing is
4930    /// cancelled ([`Self::cancel_exit_group_filing`]). Only DBT files an
4931    /// exit_group, and there each guest thread polls its own callbacks, so the
4932    /// blocking wait holds up only this thread.
4933    pub(crate) fn wait_for_exit_group_robust_walk(&self, bound: std::time::Duration) -> bool {
4934        let started = std::time::Instant::now();
4935        loop {
4936            {
4937                let process = self
4938                    .robust_list_process
4939                    .lock()
4940                    .expect("robust-list process state mutex poisoned");
4941                if !process.exit_group_filed
4942                    || process.exit_group_walked
4943                    || process.exit_group_walker == Some(self.dettid)
4944                    || (process.exit_group_walker.is_none() && process.exit_group_filers.is_empty())
4945                {
4946                    return true;
4947                }
4948            }
4949            if started.elapsed() >= bound {
4950                return false;
4951            }
4952            std::thread::sleep(std::time::Duration::from_micros(200));
4953        }
4954    }
4955
4956    /// The exit hook's counterpart of `record_robust_list_head(None)`: the
4957    /// thread is gone, so its own head is cleared, but while an exit_group is
4958    /// filed ([`Self::file_exit_group_for_robust_lists`]) its registration
4959    /// stays in the group's index.
4960    pub(crate) fn drop_robust_list_head_at_exit(&mut self) {
4961        self.robust_list_head = None;
4962        let mut process = self
4963            .robust_list_process
4964            .lock()
4965            .expect("robust-list process state mutex poisoned");
4966        if !process.exit_group_filed {
4967            process.heads.remove(&self.dettid);
4968        }
4969    }
4970
4971    /// The registrations an exit_group walks on DBT
4972    /// (`OwnerDeathPath::Barrier`), read at its grant: every registration current then, including
4973    /// those of threads the grant killed, less any thread whose own exit
4974    /// Detcore already replayed, so no list is walked twice.
4975    pub(crate) fn robust_list_owners_for_exit_group(&self) -> Vec<RobustListOwner> {
4976        let walked = self
4977            .robust_list_process
4978            .lock()
4979            .expect("robust-list process state mutex poisoned")
4980            .tool_walked
4981            .clone();
4982        self.robust_list_owners()
4983            .into_iter()
4984            .filter(|owner| !walked.contains(&owner.dettid))
4985            .collect()
4986    }
4987
4988    /// [`Self::robust_list_heads`] as [`RobustListOwner`]s.
4989    pub(crate) fn robust_list_owners(&self) -> Vec<RobustListOwner> {
4990        let process = self
4991            .robust_list_process
4992            .lock()
4993            .expect("robust-list process state mutex poisoned");
4994        process
4995            .heads
4996            .iter()
4997            .map(|(&dettid, &head)| RobustListOwner { dettid, head })
4998            .collect()
4999    }
5000
5001    #[cfg(test)]
5002    pub(crate) fn robust_list_heads(&self) -> Vec<(DetTid, usize)> {
5003        self.robust_list_process
5004            .lock()
5005            .expect("robust-list process state mutex poisoned")
5006            .heads
5007            .iter()
5008            .map(|(&tid, &head)| (tid, head))
5009            .collect()
5010    }
5011
5012    pub(crate) fn stage_robust_list_wakes(
5013        &self,
5014        reason: RobustListExit,
5015        wakes: Vec<(DetTid, Vec<RobustListWake>)>,
5016    ) {
5017        let mut process = self
5018            .robust_list_process
5019            .lock()
5020            .expect("robust-list process state mutex poisoned");
5021        process.pending = wakes
5022            .into_iter()
5023            .map(|(owner, wakes)| (owner, PendingRobustListWakes { reason, wakes }))
5024            .collect();
5025        process.matched_physical_exits.clear();
5026    }
5027
5028    pub(crate) fn has_matching_robust_list_exit(&self, exit_signal: Option<i32>) -> bool {
5029        self.robust_list_process
5030            .lock()
5031            .expect("robust-list process state mutex poisoned")
5032            .pending
5033            .get(&self.dettid)
5034            .is_some_and(|pending| pending.matches_exit(exit_signal))
5035    }
5036
5037    pub(crate) fn take_robust_list_wakes_after_exit(
5038        &self,
5039        exit_signal: Option<i32>,
5040        exit_time: DetTime,
5041    ) -> Option<(DetTime, Vec<(DetTid, RobustListWake)>)> {
5042        let mut process = self
5043            .robust_list_process
5044            .lock()
5045            .expect("robust-list process state mutex poisoned");
5046        if !process.exit_group_filed {
5047            process.heads.remove(&self.dettid);
5048        }
5049        let pending = process.pending.get(&self.dettid)?;
5050        if !pending.matches_exit(exit_signal) {
5051            return None;
5052        }
5053
5054        process
5055            .matched_physical_exits
5056            .insert(self.dettid, exit_time);
5057        if process
5058            .pending
5059            .keys()
5060            .any(|owner| !process.matched_physical_exits.contains_key(owner))
5061        {
5062            return None;
5063        }
5064
5065        let request_time = process
5066            .matched_physical_exits
5067            .values()
5068            .max()
5069            .expect("a completed robust-list exit group has a physical-exit time")
5070            .clone();
5071        process.matched_physical_exits.clear();
5072        let pending = std::mem::take(&mut process.pending);
5073        let mut ready = Vec::new();
5074        for (owner, mut pending) in pending {
5075            pending
5076                .wakes
5077                .sort_by_key(|wake| format!("{:?}", wake.futex));
5078            ready.extend(pending.wakes.into_iter().map(|wake| (owner, wake)));
5079        }
5080        Some((request_time, ready))
5081    }
5082
5083    /// Hold the owner-death wakes a successful `execve` makes Linux deliver.
5084    ///
5085    /// Past exec's point of no return, `de_thread` kills every other thread,
5086    /// and each one's exit runs `futex_exit_release` with its own TID; then
5087    /// `exec_mm_release` runs `futex_exec_release` for the caller itself
5088    /// (kernel/fork.c `exit_mm_release`/`exec_mm_release`, kernel/futex/core.c
5089    /// `futex_cleanup`, Linux 7.1.3). Both walk the robust list with
5090    /// `exit_robust_list` before the old address space goes away. A caller that
5091    /// is not the group leader already holds the leader's TID by then
5092    /// (`exchange_tids` in `de_thread`), so its own list is walked with the
5093    /// thread group ID. The lists can only be read before the exec, and a
5094    /// failed exec never reaches that point, so the wakes wait here for
5095    /// `take_robust_list_wakes_for_exec`.
5096    pub(crate) fn stage_robust_list_wakes_for_exec(
5097        &self,
5098        wakes: Vec<(DetTid, Vec<RobustListWake>)>,
5099    ) {
5100        let mut process = self
5101            .robust_list_process
5102            .lock()
5103            .expect("robust-list process state mutex poisoned");
5104        process.exec_pending = flatten_exec_robust_list_wakes(wakes);
5105    }
5106
5107    /// Take the wakes staged at the exec's entry: to deliver them once it has
5108    /// succeeded, or to drop them when it failed and left the old image running.
5109    pub(crate) fn take_robust_list_wakes_for_exec(&self) -> Vec<(DetTid, RobustListWake)> {
5110        std::mem::take(
5111            &mut self
5112                .robust_list_process
5113                .lock()
5114                .expect("robust-list process state mutex poisoned")
5115                .exec_pending,
5116        )
5117    }
5118
5119    /// Clear the robust-list head for a candidate `execve` image, returning the
5120    /// previous value so a *failed* exec can put it back.
5121    ///
5122    /// Linux clears `task->robust_list` when `execve` succeeds, and doing the
5123    /// same is load-bearing rather than tidy: a head recorded against the old
5124    /// address space is a wild pointer in the new one, and consulting it at
5125    /// thread exit would walk unrelated guest memory and write
5126    /// `FUTEX_OWNER_DIED` into whatever happened to look like a futex word.
5127    pub(crate) fn take_robust_list_for_exec(&mut self) -> Option<usize> {
5128        let previous = self.robust_list_head.take();
5129        self.robust_list_process
5130            .lock()
5131            .expect("robust-list process state mutex poisoned")
5132            .heads
5133            .remove(&self.dettid);
5134        previous
5135    }
5136
5137    /// Restore the head after an `execve` that failed and left the old address
5138    /// space intact.
5139    pub(crate) fn restore_robust_list_after_failed_exec(&mut self, previous: Option<usize>) {
5140        self.record_robust_list_head(previous);
5141    }
5142
5143    /// Resolve a futex key from its opcode mode and virtual address.
5144    pub(crate) fn futex_id(&self, address: usize, is_private: bool) -> FutexID {
5145        if is_private {
5146            FutexID::private(self.mm_id, address)
5147        } else {
5148            self.memory_metadata
5149                .lock()
5150                .expect("memory metadata mutex poisoned")
5151                .futex_id(self.mm_id, address)
5152        }
5153    }
5154
5155    /// Record an anonymous shared mapping.
5156    pub(crate) fn map_shared_anonymous(&self, start: usize, len: usize) {
5157        self.memory_metadata
5158            .lock()
5159            .expect("memory metadata mutex poisoned")
5160            .map_anonymous(self.mm_id, start, len);
5161    }
5162
5163    /// Record a file-backed shared mapping.
5164    pub(crate) fn map_shared_object(
5165        &self,
5166        start: usize,
5167        len: usize,
5168        object: SharedMemoryObjectId,
5169        object_offset: u64,
5170    ) {
5171        self.memory_metadata
5172            .lock()
5173            .expect("memory metadata mutex poisoned")
5174            .map_object(start, len, object, object_offset);
5175    }
5176
5177    /// Remove a range from the shared mapping model.
5178    pub(crate) fn unmap_memory(&self, start: usize, len: usize) {
5179        self.memory_metadata
5180            .lock()
5181            .expect("memory metadata mutex poisoned")
5182            .unmap(start, len);
5183    }
5184
5185    /// Move or resize a range in the shared mapping model.
5186    pub(crate) fn remap_memory(
5187        &self,
5188        old_start: usize,
5189        old_len: usize,
5190        new_start: usize,
5191        new_len: usize,
5192        keep_source: bool,
5193    ) {
5194        self.memory_metadata
5195            .lock()
5196            .expect("memory metadata mutex poisoned")
5197            .remap(old_start, old_len, new_start, new_len, keep_source);
5198    }
5199
5200    /// Build a singleton resource request from the current thread.
5201    pub fn mk_request(&self, rid: ResourceID, perm: Permission) -> Resources {
5202        let mut resources = HashMap::new();
5203        resources.insert(rid, perm);
5204        Resources {
5205            tid: self.dettid,
5206            resources,
5207            poll_attempt: 0,
5208            fyi: String::new(),
5209            signal_interrupt_errno: None,
5210            backend_runtime_bootstrap: false,
5211            blocked_signal_mask: None,
5212            blocked_signal_mask_unknown: false,
5213            replay_served_from_log: false,
5214            reads_signalfd: false,
5215            read_fd: None,
5216            polls_guest_state_only: false,
5217            waits_until_nothing_else_can_run: false,
5218            previous_attempt_made_progress: false,
5219            upgraded_from_attempt: 0,
5220            polls_channel: None,
5221            poll_deadline: None,
5222            in_guest_sleep_sigalrm: None,
5223            signal_state_task: None,
5224            decides_signal_interruption_itself: false,
5225            continues_sigreturn: false,
5226            private_sigchld_decides: false,
5227        }
5228    }
5229
5230    /// Generate the next random number using the thread-local chaos_seed.
5231    pub fn chaos_prng_next_u64(&mut self, msg: &str) -> u64 {
5232        let r = self.chaos_prng.next_u64();
5233        detlog!("[dtid {}] CHAOSRAND({}): u64 => {}", self.dettid, msg, r);
5234        r
5235    }
5236
5237    /// get file metadata
5238    fn metadata(&self) -> MutexGuard<'_, FileMetadata> {
5239        self.file_metadata.lock().unwrap()
5240    }
5241
5242    /// Identity of this thread's descriptor table.
5243    pub(crate) fn files_id(&self) -> detcore_model::fd::FilesId {
5244        self.metadata().files_id
5245    }
5246
5247    /// Whether this thread holds the descriptor table its process holds
5248    /// ([`ThreadState::process_files`]), the one procfs reads for the
5249    /// process's descriptor links. `false` where that is not known.
5250    pub(crate) fn holds_process_files(&self) -> bool {
5251        self.process_files == Some(self.files_id())
5252    }
5253
5254    /// Make the descriptor table this thread holds its process's, for a new
5255    /// group: after a successful exec the exec'ing thread is its process's
5256    /// only thread, and leads it, whether or not it led it before.
5257    pub(crate) fn adopt_process_files(&mut self) {
5258        self.process_files = Some(self.files_id());
5259    }
5260
5261    /// Add a new fd, with optional stat data, have side effects on other
5262    /// threads.
5263    ///
5264    /// If stat data is not available, then perform an extra stat ourselves to populate it.
5265    ///
5266    /// # Arguments
5267    ///
5268    /// * `fd` - file descriptor to add
5269    ///
5270    /// * `flags` - flags when creating `fd`
5271    ///
5272    /// * `ty` - fd type (regular file, socket, pipe, etc..)
5273    ///
5274    /// * `stat` - stat returned from fstat
5275    pub fn add_fd(
5276        &self,
5277        fd: RawFd,
5278        flags: OFlag,
5279        ty: FdType,
5280        stat: Option<DetStat>,
5281    ) -> Result<(), Errno> {
5282        self.metadata().add_fd(
5283            self.open_file_creator.unwrap_or(self.dettid),
5284            fd,
5285            flags,
5286            ty,
5287            stat,
5288        )
5289    }
5290
5291    // AUTONOMOUS-BOT-IMPLEMENTED
5292    // TODO-HUMAN-REVIEW(PR-1063): Review backend-supplied open-file creator identity.
5293    /// Overrides the task identity embedded in subsequently allocated open-file descriptions.
5294    pub fn set_open_file_creator(&mut self, creator: DetTid) {
5295        self.open_file_creator = Some(creator);
5296    }
5297
5298    /// This process's timerfds that Detcore keeps on virtual time
5299    /// (`crate::fd::VirtualTimerfd`), one descriptor per open file
5300    /// description, lowest descriptor number first, so callers visit them in
5301    /// a deterministic order.
5302    pub(crate) fn virtual_timerfds(&self) -> Vec<(RawFd, DetFd)> {
5303        let mut timerfds: Vec<(RawFd, DetFd)> = self
5304            .metadata()
5305            .file_handles
5306            .iter()
5307            .filter(|(_, detfd)| detfd.ty() == FdType::Timerfd && detfd.virtual_timerfd().is_some())
5308            .map(|(&fd, detfd)| (fd, detfd.clone()))
5309            .collect();
5310        timerfds.sort_unstable_by_key(|(fd, _)| *fd);
5311        let mut descriptions = Vec::with_capacity(timerfds.len());
5312        timerfds.retain(|(_, detfd)| {
5313            let id = detfd.open_file_id();
5314            let first = !descriptions.contains(&id);
5315            descriptions.push(id);
5316            first
5317        });
5318        timerfds
5319    }
5320
5321    /// Whether this thread's descriptor table holds a signalfd, as Detcore
5322    /// records its descriptors.
5323    pub(crate) fn holds_a_signalfd(&self) -> bool {
5324        self.metadata()
5325            .file_handles
5326            .values()
5327            .any(|detfd| matches!(detfd.ty(), FdType::Signalfd))
5328    }
5329
5330    /// Whether this thread's descriptor table holds a procfs file Detcore
5331    /// renders (`syscalls::files::rendered_procfs`).
5332    pub(crate) fn holds_a_rendered_procfs_file(&self) -> bool {
5333        self.metadata()
5334            .file_handles
5335            .values()
5336            .any(|detfd| detfd.procfs_rendered_path().is_some())
5337    }
5338
5339    /// Get a mutable reference of `DetFd` from a raw file descriptor, and
5340    /// run mutable function `f` on it (`&mut DetFd`).
5341    pub fn with_detfd<F, U>(&self, fd: RawFd, f: F) -> Result<U, Errno>
5342    where
5343        F: FnMut(&mut DetFd) -> U,
5344    {
5345        let mut metadata = self.metadata();
5346        if self.tool_shares_guest_descriptor_table {
5347            metadata.discover_fd_from_current_process(
5348                self.open_file_creator.unwrap_or(self.dettid),
5349                fd,
5350            )?;
5351        }
5352        metadata.with_detfd(fd, f)
5353    }
5354
5355    /// Preserve logical blocking for scheduler-managed descriptors when exec
5356    /// replaces an in-process tool and its descriptor metadata.
5357    pub fn exec_blocking_overrides(&self) -> ExecFdBlockingOverrides {
5358        self.metadata().exec_blocking_overrides()
5359    }
5360
5361    /// Promote the OFDs whose model must stay one copy -- random devices
5362    /// (their cursor) and timerfds (their virtual-time expirations,
5363    /// `crate::fd::VirtualTimerfd`) -- before a backend physically copies or
5364    /// replaces its in-process Tool. The shared model owns their full state;
5365    /// this does not promote sockets or other OFDs. Call only while this task
5366    /// owns its serial grant, before the native lifecycle operation can expose
5367    /// a child/new image. Ptrace's host-side Arc needs no promotion. See
5368    /// <https://github.com/rrnewton/hermit/issues/4381>.
5369    pub fn promote_shared_open_files(&self) -> Result<(), crate::fd::SharedOpenFileError> {
5370        let mut metadata = self.metadata();
5371        let mut fds: Vec<_> = metadata.file_handles.keys().copied().collect();
5372        fds.sort_unstable();
5373        for fd in fds {
5374            let handle = &metadata.file_handles[&fd];
5375            if matches!(handle.ty(), FdType::Rng | FdType::Timerfd) {
5376                handle.promote()?;
5377                // Keep history even if every promoted descriptor later closes.
5378                metadata.has_promoted_shared_files = true;
5379            }
5380        }
5381        Ok(())
5382    }
5383
5384    /// Rebuild only process-local locks after a physical process copy. This
5385    /// is RPC-free and precedes the child's first scheduler admission. Ordinary
5386    /// same-process table clones retain their original shared locks.
5387    pub fn reset_copied_open_file_locks(&self) {
5388        let mut metadata = self.metadata();
5389        let mut handles = metadata
5390            .file_handles
5391            .iter()
5392            .map(|(&fd, handle)| (fd, handle.fork_shared_handle()))
5393            .collect();
5394        crate::fd::intern_open_files(&mut handles);
5395        metadata.file_handles = handles;
5396    }
5397
5398    /// Under `--pipe-wake-latency`: the channel end each descriptor that
5399    /// survives exec is.
5400    pub(crate) fn pipe_channels_for_exec(&self) -> BTreeMap<RawFd, crate::pipe_wake::ChannelEnd> {
5401        self.metadata()
5402            .file_handles
5403            .iter()
5404            .filter(|(_, detfd)| !detfd.is_cloexec())
5405            .filter_map(|(&fd, detfd)| detfd.channel().map(|end| (fd, end)))
5406            .collect()
5407    }
5408
5409    /// The open-file creator and next sequence of this thread's table.
5410    pub(crate) fn open_file_namespace_for_exec(&self) -> (DetTid, u64) {
5411        (
5412            self.open_file_creator.unwrap_or(self.dettid),
5413            self.metadata().next_open_file_sequence,
5414        )
5415    }
5416
5417    pub(crate) fn shared_open_files_for_exec(&self) -> Result<Option<ExecOpenFiles>, Errno> {
5418        let metadata = self.metadata();
5419        if !metadata.has_promoted_shared_files {
5420            return Ok(None);
5421        }
5422        let mut handles = BTreeMap::new();
5423        for (&fd, handle) in &metadata.file_handles {
5424            if !handle.is_shared() || handle.is_cloexec() {
5425                continue;
5426            }
5427            assert!(
5428                matches!(handle.ty(), FdType::Rng | FdType::Timerfd),
5429                "only random and timerfd OFDs are promoted here"
5430            );
5431            handles.insert(fd, ExecOpenFile::capture(fd, handle.open_file_id())?);
5432        }
5433        Ok(Some(ExecOpenFiles {
5434            creator: self.open_file_creator.unwrap_or(self.dettid),
5435            next_sequence: metadata.next_open_file_sequence,
5436            next_socket_sequence: metadata.next_socket_open_file_sequence,
5437            handles,
5438        }))
5439    }
5440
5441    pub(crate) fn maps_for_exec(
5442        &self,
5443        private_memory: Option<&reverie::RuntimePrivateMemory>,
5444    ) -> Result<Option<ExecMapsFiles>, Errno> {
5445        // An unavailable advertised provider still owns saved maps bindings.
5446        // Backends without a provider retain their existing exec behavior.
5447        if private_memory.is_none() {
5448            return Ok(None);
5449        }
5450        let metadata = self.metadata();
5451        let mut handles = BTreeMap::new();
5452        for (&fd, handle) in &metadata.file_handles {
5453            if handle.is_cloexec() {
5454                continue;
5455            }
5456            if let Some(procfs) = handle.maps_for_exec() {
5457                handles.insert(
5458                    fd,
5459                    ExecMapsFile {
5460                        identity: ExecOpenFile::capture(fd, handle.open_file_id())?,
5461                        procfs,
5462                        flags: handle.status_flags(),
5463                        path: handle.path(),
5464                    },
5465                );
5466            }
5467        }
5468        Ok((!handles.is_empty()).then_some(ExecMapsFiles {
5469            creator: self.open_file_creator.unwrap_or(self.dettid),
5470            next_sequence: metadata.next_open_file_sequence,
5471            handles,
5472        }))
5473    }
5474
5475    pub(crate) fn inherited_reads_for_exec(
5476        &self,
5477    ) -> BTreeMap<RawFd, crate::fd::InheritedExternalRead> {
5478        self.metadata().inherited_reads_for_exec()
5479    }
5480
5481    /// Descriptors in this table that Detcore manages as internal pipes: typed
5482    /// `Pipe`, physically nonblocking and logically blocking, which is how
5483    /// `handle_pipe2` leaves a guest-created pipe (and how exec restores it).
5484    /// On ptrace, a pipe inherited from the host is not in this set: stdio is
5485    /// typed `Regular`, and another inherited FIFO is physically nonblocking
5486    /// only when it is logically nonblocking too. On a backend whose tool
5487    /// shares the guest's descriptor table, a readable pipe inherited on fds
5488    /// 0-2 is an inherited external read (`discover_inherited_pipes`), so it is
5489    /// not here either, and a guest `F_SETFL` leaves its kernel status flags
5490    /// as the guest set them (`keeps_physically_nonblocking`).
5491    /// Sorted, so callers probe them in a deterministic order.
5492    pub(crate) fn scheduler_managed_pipe_fds(&self) -> Vec<RawFd> {
5493        let mut fds: Vec<RawFd> = self
5494            .metadata()
5495            .file_handles
5496            .iter()
5497            .filter(|(_, detfd)| {
5498                detfd.ty() == FdType::Pipe
5499                    && detfd.inherited_external_read().is_none()
5500                    && detfd.physically_nonblocking()
5501                    && !detfd.is_nonblocking()
5502            })
5503            .map(|(&fd, _)| fd)
5504            .collect();
5505        fds.sort_unstable();
5506        fds
5507    }
5508
5509    /// Mark every listener in this table eligible for accept in turn as passed
5510    /// over `SCM_RIGHTS` (`DetFd::set_exported`), for a message whose
5511    /// descriptors Detcore could not read.
5512    // TODO-HUMAN-REVIEW(PR-3908)
5513    pub(crate) fn mark_accept_in_turn_listeners_exported(&self) {
5514        for detfd in self.metadata().file_handles.values() {
5515            if detfd.is_accept_in_turn_eligible() {
5516                detfd.set_exported();
5517            }
5518        }
5519    }
5520
5521    /// Descriptors in this table that name a network record/replay channel,
5522    /// sorted.
5523    pub(crate) fn network_channel_fds(&self) -> Vec<RawFd> {
5524        let mut fds: Vec<RawFd> = self
5525            .metadata()
5526            .file_handles
5527            .iter()
5528            .filter(|(_, detfd)| detfd.is_network_channel())
5529            .map(|(&fd, _)| fd)
5530            .collect();
5531        fds.sort_unstable();
5532        fds
5533    }
5534
5535    pub(crate) fn count_open_files_at_paths(&self, paths: &[&Path]) -> usize {
5536        self.metadata().count_open_files_at_paths(paths)
5537    }
5538
5539    /// Whether this task owns a socket that attempted a loopback connection.
5540    pub(crate) fn has_loopback_peer(&self) -> bool {
5541        self.metadata().has_loopback_peer()
5542    }
5543
5544    /// Whether any open file description is held or not proven unlocked.
5545    pub fn has_unsafe_vfork_flock_state(&self) -> bool {
5546        self.metadata().has_unsafe_vfork_flock_state()
5547    }
5548
5549    /// Whether a description in this table may hold an OFD lock. A copied
5550    /// `vfork` child (DBT) runs its lock calls natively, so the
5551    /// `procfs::locks::LockLedger` entry of such a description could go stale
5552    /// and admit a host's identical `/proc/locks` row.
5553    pub fn has_unsafe_vfork_ofd_state(&self) -> bool {
5554        self.metadata().has_unsafe_vfork_ofd_state()
5555    }
5556
5557    /// A new process can change every inherited open file description through
5558    /// a separately hosted tool state, so neither side may keep treating its
5559    /// cached flock mode as authoritative after fork.
5560    pub fn forget_flock_modes(&self) {
5561        self.metadata().forget_flock_modes();
5562    }
5563
5564    /// remove a rawfd
5565    pub fn remove_fd(&self, fd: RawFd) -> Option<OpenFileId> {
5566        self.metadata().remove_fd(fd)
5567    }
5568
5569    /// Remove every modeled descriptor in an inclusive close_range interval.
5570    pub(crate) fn remove_fd_range(&self, first: u32, last: u32) -> Vec<OpenFileId> {
5571        self.metadata().remove_fd_range(first, last)
5572    }
5573
5574    /// How many slots of this thread's table name the open file description
5575    /// `open_file` (`procfs::locks::LockLedger`).
5576    pub(crate) fn slots_naming(&self, open_file: OpenFileId) -> u32 {
5577        let count = self
5578            .metadata()
5579            .file_handles
5580            .values()
5581            .filter(|detfd| detfd.open_file_id() == open_file)
5582            .count();
5583        u32::try_from(count).unwrap_or(u32::MAX)
5584    }
5585
5586    /// The descriptions in this thread's table whose locks
5587    /// `procfs::locks::LockLedger` follows, each with how many slots name it,
5588    /// in description order.
5589    pub(crate) fn lock_tracked_slots(&self) -> Vec<(OpenFileId, u32)> {
5590        let mut slots: BTreeMap<OpenFileId, u32> = BTreeMap::new();
5591        for detfd in self.metadata().file_handles.values() {
5592            if detfd.is_lock_tracked() {
5593                *slots.entry(detfd.open_file_id()).or_default() += 1;
5594            }
5595        }
5596        slots.into_iter().collect()
5597    }
5598
5599    /// The descriptors Detcore's table holds for this thread, in order.
5600    pub(crate) fn open_fds(&self) -> Vec<RawFd> {
5601        let mut fds: Vec<RawFd> = self.metadata().file_handles.keys().copied().collect();
5602        fds.sort_unstable();
5603        fds
5604    }
5605
5606    /// dup raw fds.
5607    pub fn dup_fd(
5608        &mut self,
5609        oldfd: RawFd,
5610        newfd: RawFd,
5611        flags: OFlag,
5612    ) -> Result<Option<OpenFileId>, Errno> {
5613        let mut metadata = self.metadata();
5614        if self.tool_shares_guest_descriptor_table {
5615            metadata.discover_fd_from_current_process(
5616                self.open_file_creator.unwrap_or(self.dettid),
5617                oldfd,
5618            )?;
5619        }
5620        metadata.dup_fd(oldfd, newfd, flags)
5621    }
5622
5623    /// Atomically validate a pidfd target and capture its source descriptor.
5624    ///
5625    /// Both lookups occur under the one descriptor-table mutex. The caller must
5626    /// hold the normal serialized Tool turn until the nonblocking kernel call
5627    /// returns and the captured alias is installed.
5628    pub(crate) fn capture_pidfd_getfd_source(
5629        &self,
5630        pidfd: RawFd,
5631        targetfd: RawFd,
5632        current_tgid: DetPid,
5633        current_tid: DetTid,
5634    ) -> Result<CapturedDetFd, Errno> {
5635        let mut metadata = self.metadata();
5636        if self.tool_shares_guest_descriptor_table {
5637            metadata.discover_fd_from_current_process(
5638                self.open_file_creator.unwrap_or(self.dettid),
5639                pidfd,
5640            )?;
5641        }
5642        let (is_pidfd, target) = metadata.with_detfd(pidfd, |detfd| {
5643            (matches!(detfd.ty(), FdType::Pidfd), detfd.pidfd_target())
5644        })?;
5645        if !is_pidfd {
5646            return Err(Errno::EBADF);
5647        }
5648        if !pidfd_getfd_targets_calling_task(target, current_tgid, current_tid) {
5649            return Err(Errno::EOPNOTSUPP);
5650        }
5651        if self.tool_shares_guest_descriptor_table {
5652            metadata.discover_fd_from_current_process(
5653                self.open_file_creator.unwrap_or(self.dettid),
5654                targetfd,
5655            )?;
5656        }
5657        metadata.capture_fd(targetfd)
5658    }
5659
5660    /// Install an alias from a pre-syscall capture without resolving the source
5661    /// fd slot a second time.
5662    pub(crate) fn install_captured_fd(
5663        &mut self,
5664        captured: CapturedDetFd,
5665        newfd: RawFd,
5666        flags: OFlag,
5667    ) -> Result<Option<OpenFileId>, CapturedDetFdInstallError> {
5668        self.metadata().install_captured_fd(captured, newfd, flags)
5669    }
5670
5671    /// Install `detfd`, which refers to an open file description Detcore
5672    /// models, as descriptor `detfd.fd` of this table: a descriptor that
5673    /// reached the description by a route Detcore does not model
5674    /// (`SCM_RIGHTS`), adopted when the guest first names it
5675    /// (`Detcore::adopt_received_placeholders`).
5676    pub(crate) fn install_alias(&self, detfd: DetFd) {
5677        self.metadata().add_detfd(detfd);
5678    }
5679
5680    /// Abandon an uninstalled capture and identify a deferred final-OFD release.
5681    pub(crate) fn abandon_captured_fd(&self, captured: CapturedDetFd) -> Option<OpenFileId> {
5682        self.metadata().abandon_captured_fd(captured)
5683    }
5684
5685    /// get thread prng, note this rng is deterministic and should not be used
5686    /// for crypto.
5687    pub fn thread_prng(&mut self) -> &mut Pcg64Mcg {
5688        &mut self.prng
5689    }
5690
5691    /// Whether a trapped instruction (`rdtsc`, `cpuid`) should end the current
5692    /// timeslice.
5693    ///
5694    /// By default it ends an expired target, as a syscall does. A trapped
5695    /// instruction can sit inside a user-space spinlock critical section,
5696    /// though, and a thread that yields there leaves every thread that wants
5697    /// the lock spinning until the PMU maximum preempts it. QEMU's
5698    /// `cpu_get_ticks` reads the host TSC under its `vm_clock_lock` spinlock,
5699    /// so a multi-threaded TCG vCPU that yielded at every expired target while
5700    /// reading the TSC held that lock at every yield, and the other vCPU never
5701    /// acquired it. With `--target-timeslice-syscalls-only`, a trapped
5702    /// instruction ends the slice only at the PMU maximum, as a branch would.
5703    /// With no PMU maximum it is the only way out of a busy-wait on the TSC,
5704    /// and it still ends the expired target. Replay of recorded preemptions or
5705    /// schedules keeps its recorded boundaries.
5706    pub(crate) fn instruction_trap_ends_timeslice(&self, cfg: &Config) -> bool {
5707        let replaying = self.preemption_points.is_some() || cfg.replay_schedule_from.is_some();
5708        match self.max_timeslice_end {
5709            Some(max_end) if cfg.target_timeslice_syscalls_only && !replaying => {
5710                self.thread_logical_time.as_nanos() >= max_end
5711            }
5712            _ => self.timeslice_expired(),
5713        }
5714    }
5715
5716    /// End the current slice no later than `remaining` from now: the virtual
5717    /// time that was left before the earliest pending deadline when this
5718    /// thread was granted its turn.
5719    ///
5720    /// Global time advances exactly as this thread's clock does while it runs
5721    /// alone, so its slice then ends, and it takes a turn, once global time has
5722    /// passed that deadline.
5723    ///
5724    /// The slice keeps at least `min_slice`, one scheduler turn charge, and
5725    /// at least one RCB's worth of time. Every cap-induced slice end is a turn
5726    /// charged that much, so a thread runs at least as long as the turn it
5727    /// pays for: the virtual time the cap adds is at most the thread's own
5728    /// work. With a shorter floor, a sibling sleeping just over one turn
5729    /// charge made each slice about 1 us of work per 1-1.5 ms of virtual time.
5730    ///
5731    /// Only the software slice end moves, which takes effect at the thread's
5732    /// next check-in: a syscall, signal or timer event. The PMU maximum keeps
5733    /// its value, so a thread that makes no syscalls still runs to it: a
5734    /// precise PMU stop at every deadline costs about 70 ms of host time each,
5735    /// and a fast timer would make them constant
5736    /// (<https://github.com/rrnewton/hermit/issues/4121>). A schedule replay follows
5737    /// its recorded turns, and a preemption replay its recorded slice ends,
5738    /// neither capped. Past the last recorded point a replay's slice end is
5739    /// `LogicalTime::MAX` (its PMU maximum stays bounded), and the cap may
5740    /// lower it; that need not reproduce the record's own slice ends.
5741    pub(crate) fn cap_timeslice_at_deadline(
5742        &mut self,
5743        remaining: Duration,
5744        clock_multiplier: f64,
5745        min_slice: Duration,
5746        schedule_replay: bool,
5747    ) {
5748        let recorded_slice =
5749            self.preemption_points.is_some() && self.stats.last_recorded_slice.is_none();
5750        if recorded_slice || schedule_replay {
5751            return;
5752        }
5753        let Some(end) = self.end_of_timeslice else {
5754            return;
5755        };
5756        let one_rcb =
5757            (NANOS_PER_RCB * clock_multiplier * self.rcb_time_multiplier().as_f64()).ceil() as u64;
5758        let current = self.thread_logical_time.as_nanos();
5759        let cap = current
5760            + remaining
5761                .max(min_slice)
5762                .max(Duration::from_nanos(one_rcb + 1));
5763        if cap < end {
5764            debug!(
5765                "[dtid {}] end of slice moved from {} to {}, the earliest pending deadline (current {})",
5766                self.dettid, end, cap, current
5767            );
5768            self.end_of_timeslice = Some(cap);
5769        }
5770    }
5771
5772    /// Whether this thread has consumed its current logical timeslice.
5773    pub(crate) fn timeslice_expired(&self) -> bool {
5774        if let Some(replay_rcb_end) = self.replay_rcb_end {
5775            return self.committed_clock_value >= replay_rcb_end;
5776        }
5777        let current_time = self.thread_logical_time.as_nanos();
5778        self.end_of_timeslice
5779            .is_some_and(|end_of_timeslice| current_time >= end_of_timeslice)
5780    }
5781
5782    // AUTONOMOUS-BOT-IMPLEMENTED
5783    // TODO-HUMAN-REVIEW(PR-1151)
5784    /// Current RCB virtual-time multiplier, including recorded replay state.
5785    pub(crate) fn rcb_time_multiplier(&self) -> RcbTimeMultiplier {
5786        if self.chaos_slowdown_active {
5787            self.chaos_slowdown_factor
5788        } else {
5789            RcbTimeMultiplier::ONE
5790        }
5791    }
5792
5793    // AUTONOMOUS-BOT-IMPLEMENTED
5794    // TODO-HUMAN-REVIEW(PR-1151)
5795    pub(crate) fn take_pending_chaos_epochs(&mut self) -> Vec<ChaosEpochTransition> {
5796        std::mem::take(&mut self.pending_chaos_epochs)
5797    }
5798
5799    // AUTONOMOUS-BOT-IMPLEMENTED
5800    // TODO-HUMAN-REVIEW(PR-1151)
5801    fn install_chaos_epoch(&mut self, transition: ChaosEpochTransition, record: bool) {
5802        self.chaos_epoch = transition.epoch;
5803        self.chaos_slowdown_factor = transition.factor;
5804        self.chaos_slowdown_active = true;
5805        if record {
5806            self.pending_chaos_epochs.push(transition);
5807        }
5808        detlog!(
5809            "[dtid {}] CHAOSEPOCH => epoch = {}, factor = {}, logical_time = {}",
5810            self.dettid,
5811            transition.epoch,
5812            transition.factor.as_f64(),
5813            transition.logical_time
5814        );
5815    }
5816
5817    // AUTONOMOUS-BOT-IMPLEMENTED
5818    /// Choose the logical target and PMU maximum deadlines for the next timeslice.
5819    ///
5820    /// Effects:
5821    /// - Sets `end_of_timeslice` for the new timeslice.
5822    /// - Sets `max_timeslice_end` when PMU-backed preemption is enabled.
5823    /// - Resets the statistics for the timeslice.
5824    ///
5825    /// Returns: an optional new priority.
5826    pub fn next_timeslice(&mut self, cfg: &Config) -> Option<Priority> {
5827        let logical_timeslice = cfg.target_timeslice.or(cfg.max_timeslice);
5828        if let Some(timeout_ns) = logical_timeslice {
5829            let current_ns = self.thread_logical_time.as_nanos();
5830
5831            // AUTONOMOUS-BOT-IMPLEMENTED
5832            // TODO-HUMAN-REVIEW(PR-1151)
5833            // Redraw only at scheduler commit boundaries, keyed to elapsed
5834            // deterministic logical time. Replay artifacts take precedence and
5835            // restore the exact recorded Q32 factor even without ambient flags.
5836            let replay_has_epochs = self
5837                .preemption_points
5838                .as_ref()
5839                .is_some_and(ThreadHistoryIterator::has_chaos_epochs);
5840            if replay_has_epochs {
5841                // Precise PMU replay deliberately checks in up to one RCB
5842                // before the recorded logical boundary. The new slice still
5843                // begins at that recorded boundary, so install its factor
5844                // against the prior slice's exact target rather than the
5845                // slightly-early observed clock. Otherwise a short epoch can
5846                // be skipped and the following RCBs receive the wrong weight.
5847                let transition_time = self.end_of_timeslice.unwrap_or(current_ns);
5848                let transition = self
5849                    .preemption_points
5850                    .as_mut()
5851                    .and_then(|history| history.advance_chaos_epoch(transition_time));
5852                if let Some(transition) = transition {
5853                    self.install_chaos_epoch(transition, false);
5854                }
5855            } else if cfg.chaos && cfg.chaos_per_thread_slowdown {
5856                let elapsed_ns = self.thread_logical_time.without_starting().as_nanos();
5857                let epoch = elapsed_ns
5858                    .checked_div(cfg.chaos_epoch_length_ns)
5859                    .unwrap_or(0);
5860                let factor = chaos_per_thread_slowdown_factor(
5861                    cfg.sched_seed(),
5862                    self.dettid,
5863                    epoch,
5864                    cfg.chaos_slowdown_max_factor,
5865                );
5866                if epoch != self.chaos_epoch {
5867                    self.install_chaos_epoch(
5868                        ChaosEpochTransition {
5869                            logical_time: current_ns,
5870                            epoch,
5871                            factor,
5872                        },
5873                        true,
5874                    );
5875                } else {
5876                    self.chaos_slowdown_factor = factor;
5877                    self.chaos_slowdown_active = true;
5878                }
5879            } else {
5880                self.chaos_slowdown_factor = RcbTimeMultiplier::ONE;
5881                self.chaos_slowdown_active = false;
5882                self.pending_chaos_epochs.clear();
5883            }
5884
5885            let mut result = None;
5886            self.replay_rcb_end = None;
5887            let replay_controls_deadline =
5888                self.preemption_points.is_some() || cfg.replay_schedule_from.is_some();
5889
5890            // Preemption-point replay from recorded --chaos configuration.
5891            if let Some(thi) = &mut self.preemption_points {
5892                if self.stats.last_recorded_slice.is_none() {
5893                    // We have not tapped out the recording yet.
5894                    if let Some((end_time, prio, replay_rcb_end)) = thi.next_with_rcbs() {
5895                        debug!(
5896                            "[dtid {}] next timeslice (T{}), set by recording to {:?} (current {}), priority {}",
5897                            self.dettid,
5898                            self.stats.timeslice_count + 1,
5899                            end_time,
5900                            current_ns,
5901                            prio
5902                        );
5903                        let current_rcbs = self.committed_clock_value;
5904                        if let Some(target_rcbs) = replay_rcb_end
5905                            && target_rcbs < current_rcbs
5906                        {
5907                            panic!(
5908                                "Cannot set RCB end of timeslice to {} for thread {}, when current RCB count is already {}.",
5909                                target_rcbs, self.dettid, current_rcbs
5910                            )
5911                        }
5912                        let exact_deadline_is_now =
5913                            replay_rcb_end.is_some_and(|target| target == current_rcbs);
5914                        if end_time <= current_ns && !exact_deadline_is_now {
5915                            // Records that store their epoch are reconciled with
5916                            // this run's epoch before any guest starts (see
5917                            // `adopt_replayed_schedule_epoch` in hermit-cli), so
5918                            // reaching this with such a record means the replay
5919                            // really diverged. A record without an epoch cannot
5920                            // be checked up front; say what usually causes it.
5921                            panic!(
5922                                "Cannot set end of timeslice to {} for thread {}, when current thread logical time is already {}. \
5923                                 The replayed preemption record's timeslice ends are absolute virtual times; if it was \
5924                                 recorded under a different virtual-time epoch, replay it with that --epoch \
5925                                 (https://github.com/rrnewton/hermit/issues/3413).",
5926                                end_time, self.dettid, current_ns
5927                            )
5928                        }
5929                        self.end_of_timeslice = Some(end_time);
5930                        self.replay_rcb_end = replay_rcb_end;
5931                        result = Some(prio);
5932                    } else {
5933                        let max = LogicalTime::MAX;
5934                        let prio = thi.final_priority();
5935                        debug!(
5936                            "[dtid {}] next timeslice (T{}) final slice after recorded preemption points... setting end_of_timeslice to max {}, final priority {}",
5937                            self.dettid,
5938                            self.stats.timeslice_count + 1,
5939                            max,
5940                            prio
5941                        );
5942                        self.stats.last_recorded_slice = Some(self.stats.timeslice_count);
5943                        self.end_of_timeslice = Some(max);
5944                        result = Some(prio)
5945                    }
5946                } else {
5947                    tracing::warn!(
5948                        "[dtid {}] next timeslice: timer expired beyond the last recorded preemption.  Not handled yet.",
5949                        self.dettid
5950                    );
5951                    self.end_of_timeslice = Some(LogicalTime::MAX);
5952                    result = Some(thi.final_priority())
5953                }
5954            } else if !cfg.chaos {
5955                if cfg.replay_schedule_from.is_some() {
5956                    if cfg.no_rcb_time {
5957                        let max_timeslice = cfg
5958                            .max_timeslice
5959                            .expect("schedule replay with PMU requires a maximum");
5960                        self.end_of_timeslice =
5961                            Some(current_ns + Duration::from_nanos(u64::from(max_timeslice)));
5962                    } else {
5963                        // Branch-event replay will overwrite this deadline when needed.
5964                        debug!(
5965                            "[dtid {}] next timeslice (T{}), in replay mode setting timeslice to max (current time {})",
5966                            self.dettid,
5967                            self.stats.timeslice_count + 1,
5968                            current_ns
5969                        );
5970                        self.end_of_timeslice = Some(LogicalTime::MAX);
5971                    }
5972                } else {
5973                    // In non-chaos mode, we only care about preemption for breaking busy-waits,
5974                    // and we can safely reset the clock every time we get control back from the
5975                    // guest.  This is our preemption-of-last-resort:
5976                    self.end_of_timeslice =
5977                        Some(current_ns + Duration::from_nanos(u64::from(timeout_ns)));
5978                    debug!(
5979                        "[dtid {}] next timeslice (T{}), end of slice set to {} (current {})",
5980                        self.dettid,
5981                        self.stats.timeslice_count + 1,
5982                        self.end_of_timeslice.unwrap(),
5983                        current_ns,
5984                    );
5985                }
5986            } else {
5987                // AUTONOMOUS-BOT-IMPLEMENTED
5988                // TODO-HUMAN-REVIEW(PR-1151)
5989                // The slowdown changes RCB-to-virtual-time progression. Converting
5990                // the sampled virtual duration back to RCBs with the SAME factor
5991                // keeps the deadline and guest-visible clock internally consistent.
5992                let slowdown = self.rcb_time_multiplier().as_f64();
5993                let nanos_per_rcb = NANOS_PER_RCB * cfg.clock_multiplier.unwrap_or(1.0) * slowdown;
5994                let target_timeout_rcbs = u64::from(timeout_ns) as f64 / nanos_per_rcb;
5995                if self.chaos_slowdown_active {
5996                    detlog!(
5997                        "[dtid {}] CHAOSSLOWDOWN => factor = {}, virtual ns/rcb = {}",
5998                        self.dettid,
5999                        slowdown,
6000                        nanos_per_rcb
6001                    );
6002                }
6003                let next_rcbs: u64 = if cfg.chaos {
6004                    // Average frequency of preemptions per nanosecond:
6005                    let lambda = 1.0 / target_timeout_rcbs;
6006                    let exp = Exp::new(lambda).unwrap();
6007                    // Add one to prevent generating a zero time slice:
6008                    let rcbs = 1 + exp.sample(&mut self.chaos_prng) as u64;
6009                    detlog!("[dtid {}] CHAOSRAND => next_rcbs = {}", self.dettid, rcbs);
6010                    rcbs
6011                } else {
6012                    target_timeout_rcbs as u64
6013                };
6014                assert!(next_rcbs > 0);
6015                self.last_rcb_timer = None;
6016                self.end_of_timeslice = Some(
6017                    current_ns
6018                        + Duration::from_nanos((next_rcbs as f64 * nanos_per_rcb).ceil() as u64),
6019                );
6020                debug!(
6021                    "[dtid {}] next timeslice (T{}) chosen as {} rcbs, end of slice = {} (current {})",
6022                    self.dettid,
6023                    self.stats.timeslice_count + 1,
6024                    next_rcbs,
6025                    self.end_of_timeslice.unwrap(),
6026                    current_ns
6027                );
6028            }
6029
6030            let configured_max_end = cfg
6031                .max_timeslice
6032                .map(|max_timeslice| current_ns + Duration::from_nanos(u64::from(max_timeslice)));
6033            self.max_timeslice_end = if replay_controls_deadline {
6034                if cfg.max_timeslice.is_some() {
6035                    // A replay history uses `LogicalTime::MAX` after its last
6036                    // recorded preemption. Keep periodic PMU check-ins bounded
6037                    // instead of trying to program that sentinel as an RCB
6038                    // timer, which the kernel rejects with EINVAL.
6039                    self.end_of_timeslice
6040                        .filter(|end| *end != LogicalTime::MAX)
6041                        .or(configured_max_end)
6042                } else {
6043                    None
6044                }
6045            } else if cfg.target_timeslice.is_none() {
6046                match (self.end_of_timeslice, configured_max_end) {
6047                    (Some(logical_end), Some(configured_end)) => {
6048                        Some(logical_end.min(configured_end))
6049                    }
6050                    (_, configured_end) => configured_end,
6051                }
6052            } else {
6053                configured_max_end
6054            };
6055
6056            if let (Some(target_end), Some(max_end)) =
6057                (self.end_of_timeslice, self.max_timeslice_end)
6058                && target_end > max_end
6059            {
6060                self.end_of_timeslice = Some(max_end);
6061            }
6062
6063            self.last_rcb_timer = None;
6064            self.last_rcb_timer_is_max = false;
6065            self.reset_timeslice_stats(current_ns);
6066            result
6067        } else {
6068            self.end_of_timeslice = None;
6069            self.replay_rcb_end = None;
6070            self.max_timeslice_end = None;
6071            self.last_rcb_timer = None;
6072            self.last_rcb_timer_is_max = false;
6073            None
6074        }
6075    }
6076
6077    /// Close the current logical-timeslice statistics without selecting a new
6078    /// preemption point. Used when preemption replay reaches a deterministic
6079    /// guest sched_yield boundary.
6080    pub fn reset_timeslice_for_explicit_yield(&mut self) {
6081        let current_ns = self.thread_logical_time.as_nanos();
6082        self.reset_timeslice_stats(current_ns);
6083    }
6084
6085    fn reset_timeslice_stats(&mut self, current_ns: LogicalTime) {
6086        if let Some(start) = self.stats.timeslice_start_ns
6087            && current_ns >= start
6088        {
6089            self.stats
6090                .timeslice_stats
6091                .record((current_ns - start).as_nanos());
6092        }
6093        self.stats.timeslice_start_ns = Some(current_ns);
6094        self.stats.reset_timeslice();
6095    }
6096
6097    /// Are we within the execution of the (first) guest binary or any child processes called by it?
6098    /// Returns false if we are in the very beginning of execution, when the hermit container has
6099    /// forked our process, but we have not yet executed the guest binary.  There are few guarantees
6100    /// during this early initialization period, and Detcore should make no assumptions, nor
6101    /// guarantee determinism!
6102    pub fn guest_past_first_execve(&self) -> bool {
6103        self.past_global_first_execve
6104    }
6105}
6106
6107#[cfg(test)]
6108mod timeslice_tests {
6109    use std::num::NonZeroU64;
6110
6111    use super::*;
6112    use crate::DEFAULT_PRIORITY;
6113    use crate::preemptions::ThreadHistory;
6114
6115    /// Once an exit_group is filed on DBT (`OwnerDeathPath::Barrier`), an
6116    /// exiting thread's head stays registered for the exit_group's walk, but
6117    /// an unregistration still counts, a registration made after the filing
6118    /// is seen, and a thread whose own exit Detcore replayed is left out
6119    /// (https://github.com/rrnewton/hermit/issues/4238).
6120    #[test]
6121    fn an_exit_group_walks_the_registrations_current_at_its_grant() {
6122        let owner = |tid: i32, head: usize| RobustListOwner {
6123            dettid: DetTid::from_raw(tid),
6124            head,
6125        };
6126        let mut caller = ThreadState::<()>::new(DetTid::from_raw(3), &Config::default(), ());
6127        let sibling = |tid: i32| {
6128            let mut state = caller.clone();
6129            state.dettid = DetTid::from_raw(tid);
6130            state
6131        };
6132        let (mut killed, mut exited, mut late, mut replaced, mut unregistered) =
6133            (sibling(4), sibling(5), sibling(6), sibling(7), sibling(8));
6134        caller.record_robust_list_head(Some(0x3000));
6135        killed.record_robust_list_head(Some(0x4000));
6136        exited.record_robust_list_head(Some(0x5000));
6137        replaced.record_robust_list_head(Some(0x7000));
6138        unregistered.record_robust_list_head(Some(0x8000));
6139
6140        caller.file_exit_group_for_robust_lists();
6141        // Before the grant: thread 5 makes its own exit, which Detcore
6142        // replays; thread 6 registers; thread 7 replaces its head; thread 8
6143        // unregisters.
6144        exited.mark_robust_list_walked_by_tool();
6145        exited.drop_robust_list_head_at_exit();
6146        late.record_robust_list_head(Some(0x6000));
6147        replaced.record_robust_list_head(Some(0x7700));
6148        unregistered.record_robust_list_head(None);
6149        // The grant kills thread 4, whose exit hook runs before the walk.
6150        killed.drop_robust_list_head_at_exit();
6151        assert_eq!(
6152            killed.take_robust_list_wakes_after_exit(None, DetTime::default()),
6153            None
6154        );
6155
6156        assert_eq!(
6157            caller.robust_list_owners_for_exit_group(),
6158            vec![
6159                owner(3, 0x3000),
6160                owner(4, 0x4000),
6161                owner(6, 0x6000),
6162                owner(7, 0x7700)
6163            ]
6164        );
6165    }
6166
6167    /// A thread an exit_group killed waits for that exit_group's walk before
6168    /// its native exit, including one that filed an exit_group of its own,
6169    /// whichever of two competing filings is granted; the walker does not
6170    /// wait, nor does a group with no filing.
6171    #[test]
6172    fn a_killed_thread_waits_for_the_exit_group_walk() {
6173        use std::sync::atomic::AtomicBool;
6174        use std::sync::atomic::Ordering;
6175        const BOUND: std::time::Duration = EXIT_GROUP_ROBUST_WALK_WAIT;
6176
6177        for granted_first_filer in [true, false] {
6178            let first = ThreadState::<()>::new(DetTid::from_raw(3), &Config::default(), ());
6179            let mut second = first.clone();
6180            second.dettid = DetTid::from_raw(4);
6181            // Nothing filed: no wait.
6182            assert!(second.wait_for_exit_group_robust_walk(BOUND));
6183
6184            first.file_exit_group_for_robust_lists();
6185            second.file_exit_group_for_robust_lists();
6186            let (walker, killed) = if granted_first_filer {
6187                (first, second)
6188            } else {
6189                (second, first)
6190            };
6191            walker.begin_exit_group_robust_walk();
6192            assert!(walker.wait_for_exit_group_robust_walk(BOUND));
6193
6194            let released = Arc::new(AtomicBool::new(false));
6195            let entered = Arc::new(AtomicBool::new(false));
6196            let waiter = {
6197                let released = Arc::clone(&released);
6198                let entered = Arc::clone(&entered);
6199                std::thread::spawn(move || {
6200                    killed.cancel_exit_group_filing();
6201                    entered.store(true, Ordering::SeqCst);
6202                    let finished = killed.wait_for_exit_group_robust_walk(BOUND);
6203                    (finished, released.load(Ordering::SeqCst))
6204                })
6205            };
6206            // The killed thread is in the wait before the walk finishes, so the
6207            // check below is not passed by a waiter that started late (Claude
6208            // review of https://github.com/rrnewton/hermit/pull/4277, N6).
6209            while !entered.load(Ordering::SeqCst) {
6210                std::thread::yield_now();
6211            }
6212            std::thread::sleep(std::time::Duration::from_millis(50));
6213            assert!(
6214                !waiter.is_finished(),
6215                "the killed filer did not wait for the walk"
6216            );
6217            released.store(true, Ordering::SeqCst);
6218            walker.finish_exit_group_robust_walk();
6219            assert_eq!(
6220                waiter.join().unwrap(),
6221                (true, true),
6222                "the killed filer went on before the walk finished (first filer granted: {granted_first_filer})"
6223            );
6224        }
6225    }
6226
6227    /// A granted walk that has not finished keeps its killed threads waiting
6228    /// to the bound, which is reported, not taken as completion.
6229    #[test]
6230    fn an_unfinished_walk_is_never_released_by_the_bound() {
6231        let walker = ThreadState::<()>::new(DetTid::from_raw(3), &Config::default(), ());
6232        let mut killed = walker.clone();
6233        killed.dettid = DetTid::from_raw(4);
6234        walker.file_exit_group_for_robust_lists();
6235        walker.begin_exit_group_robust_walk();
6236        killed.cancel_exit_group_filing();
6237        assert!(!killed.wait_for_exit_group_robust_walk(std::time::Duration::from_millis(20)));
6238    }
6239
6240    /// When every filing is cancelled by its filer's death and none was
6241    /// granted (an exec ended the group first), no walk will come, and the
6242    /// killed threads are released at once.
6243    #[test]
6244    fn a_wait_ends_when_every_filing_is_cancelled() {
6245        let filer = ThreadState::<()>::new(DetTid::from_raw(3), &Config::default(), ());
6246        let mut other = filer.clone();
6247        other.dettid = DetTid::from_raw(4);
6248        filer.file_exit_group_for_robust_lists();
6249        other.cancel_exit_group_filing();
6250        assert!(!other.wait_for_exit_group_robust_walk(std::time::Duration::from_millis(20)));
6251        filer.cancel_exit_group_filing();
6252        assert!(other.wait_for_exit_group_robust_walk(std::time::Duration::from_millis(20)));
6253    }
6254
6255    /// Without a filed exit_group an exiting thread's head leaves the index.
6256    #[test]
6257    fn an_exit_drops_its_head_when_no_exit_group_is_filed() {
6258        let mut state = ThreadState::<()>::new(DetTid::from_raw(4), &Config::default(), ());
6259        state.record_robust_list_head(Some(0x4000));
6260        state.drop_robust_list_head_at_exit();
6261        assert!(state.robust_list_heads().is_empty());
6262        assert_eq!(state.robust_list_head, None);
6263    }
6264
6265    /// A stale robust-list head must never survive into a new address space.
6266    /// `run_robust_list_owner_death` walks from whatever this field holds, so if
6267    /// `execve` left the old image's head here, thread exit would follow a wild
6268    /// pointer through the *new* image and write `FUTEX_OWNER_DIED` into
6269    /// whatever happened to sit at the computed word address.
6270    #[test]
6271    fn a_successful_exec_clears_the_robust_list_head() {
6272        let mut state = ThreadState::<()>::new(DetTid::from_raw(3), &Config::default(), ());
6273        assert_eq!(state.robust_list_head, None, "a fresh thread has no list");
6274
6275        state.record_robust_list_head(Some(0x7ffff7bff920));
6276        assert_eq!(
6277            state.take_robust_list_for_exec(),
6278            Some(0x7ffff7bff920),
6279            "the previous head is handed back for the failure path"
6280        );
6281        assert_eq!(
6282            state.robust_list_head, None,
6283            "the candidate exec image starts with no robust list, as after copy_process"
6284        );
6285        assert!(
6286            state.robust_list_heads().is_empty(),
6287            "the old address-space registration must also leave the shared index"
6288        );
6289    }
6290
6291    /// `execve` returns only on failure, and then the old address space -- and
6292    /// so the old head -- is still valid.
6293    #[test]
6294    fn a_failed_exec_restores_the_robust_list_head() {
6295        let mut state = ThreadState::<()>::new(DetTid::from_raw(3), &Config::default(), ());
6296        state.record_robust_list_head(Some(0x404100));
6297
6298        let saved = state.take_robust_list_for_exec();
6299        state.restore_robust_list_after_failed_exec(saved);
6300
6301        assert_eq!(state.robust_list_head, Some(0x404100));
6302        assert_eq!(
6303            state.robust_list_heads(),
6304            vec![(DetTid::from_raw(3), 0x404100)],
6305            "a failed exec keeps the old address-space registration indexed"
6306        );
6307    }
6308
6309    fn two_owner_robust_list_state() -> (
6310        ThreadState<()>,
6311        ThreadState<()>,
6312        RobustListWake,
6313        RobustListWake,
6314        RobustListWake,
6315    ) {
6316        let first_owner = DetTid::from_raw(3);
6317        let second_owner = DetTid::from_raw(4);
6318        let mm = MmId::initial(first_owner);
6319        let lower = RobustListWake {
6320            futex: FutexID::private(mm, 0x4040),
6321        };
6322        let middle = RobustListWake {
6323            futex: FutexID::private(mm, 0x5050),
6324        };
6325        let higher = RobustListWake {
6326            futex: FutexID::private(mm, 0x6060),
6327        };
6328        let mut first = ThreadState::<()>::new(first_owner, &Config::default(), ());
6329        let mut second = first.clone();
6330        second.dettid = second_owner;
6331        first.record_robust_list_head(Some(0x404100));
6332        second.record_robust_list_head(Some(0x404200));
6333        first.stage_robust_list_wakes(
6334            RobustListExit::Signal(libc::SIGTERM),
6335            vec![
6336                (second_owner, vec![higher]),
6337                (first_owner, vec![middle, lower]),
6338            ],
6339        );
6340        (first, second, lower, middle, higher)
6341    }
6342
6343    #[test]
6344    fn group_robust_list_wakes_wait_for_every_owner_and_sort_the_request() {
6345        let (first, second, lower, middle, higher) = two_owner_robust_list_state();
6346        let mut first_time = DetTime::default();
6347        first_time.add_syscall();
6348        let mut second_time = first_time.clone();
6349        second_time.add_syscall();
6350
6351        assert_eq!(
6352            second.take_robust_list_wakes_after_exit(Some(libc::SIGTERM), second_time.clone()),
6353            None,
6354            "the first physical exit must not release part of the group"
6355        );
6356        assert_eq!(
6357            first.take_robust_list_wakes_after_exit(Some(libc::SIGTERM), first_time),
6358            Some((
6359                second_time,
6360                vec![
6361                    (DetTid::from_raw(3), lower),
6362                    (DetTid::from_raw(3), middle),
6363                    (DetTid::from_raw(4), higher),
6364                ],
6365            )),
6366            "the final matching exit releases one owner/futex-sorted request"
6367        );
6368    }
6369
6370    #[test]
6371    fn group_robust_list_wake_request_is_independent_of_exit_arrival_order() {
6372        let release = |reverse: bool| {
6373            let (first, second, _, _, _) = two_owner_robust_list_state();
6374            let first_time = DetTime::default();
6375            let mut second_time = first_time.clone();
6376            second_time.add_syscall();
6377            if reverse {
6378                assert_eq!(
6379                    second.take_robust_list_wakes_after_exit(
6380                        Some(libc::SIGTERM),
6381                        second_time.clone(),
6382                    ),
6383                    None
6384                );
6385                first.take_robust_list_wakes_after_exit(Some(libc::SIGTERM), first_time)
6386            } else {
6387                assert_eq!(
6388                    first.take_robust_list_wakes_after_exit(Some(libc::SIGTERM), first_time),
6389                    None
6390                );
6391                second.take_robust_list_wakes_after_exit(Some(libc::SIGTERM), second_time)
6392            }
6393        };
6394
6395        assert_eq!(release(false), release(true));
6396    }
6397
6398    #[test]
6399    fn mismatched_or_nonfatal_exit_does_not_release_group_robust_list_wakes() {
6400        let (first, second, _, _, _) = two_owner_robust_list_state();
6401        assert_eq!(
6402            first.take_robust_list_wakes_after_exit(Some(libc::SIGKILL), DetTime::default()),
6403            None
6404        );
6405        assert_eq!(
6406            second.take_robust_list_wakes_after_exit(Some(libc::SIGTERM), DetTime::default()),
6407            None,
6408            "one matching owner cannot release a group whose peer exited for another reason"
6409        );
6410
6411        let (first, second, _, _, _) = two_owner_robust_list_state();
6412        assert_eq!(
6413            first.take_robust_list_wakes_after_exit(None, DetTime::default()),
6414            None
6415        );
6416        assert_eq!(
6417            second.take_robust_list_wakes_after_exit(Some(libc::SIGTERM), DetTime::default()),
6418            None,
6419            "a normal exit must not satisfy a staged fatal-signal exit"
6420        );
6421    }
6422
6423    #[test]
6424    fn regular_file_opens_do_not_shift_socket_cookie_identity() {
6425        let owner = DetTid::from_raw(3);
6426        let mut files = FileMetadata::new(owner);
6427        let first = files.allocate_open_file_id(owner, FdType::Socket);
6428        for _ in 0..4 {
6429            files.allocate_open_file_id(owner, FdType::Regular);
6430        }
6431        let second = files.allocate_open_file_id(owner, FdType::Socket);
6432
6433        assert_eq!(first.deterministic_socket_cookie(), 3_u64 << 32);
6434        assert_eq!(second.deterministic_socket_cookie(), (3_u64 << 32) | 1);
6435    }
6436
6437    #[test]
6438    fn guest_clock_tracks_raw_logical_time_without_lag() {
6439        let epoch = LogicalTime::from_secs(1_000);
6440        let mut clock = GuestClock::default();
6441
6442        assert_eq!(
6443            clock.observe(epoch + Duration::from_nanos(41_000_000)),
6444            epoch + Duration::from_nanos(41_000_000)
6445        );
6446        assert_eq!(
6447            clock.observe(epoch + Duration::from_nanos(41_025_000)),
6448            epoch + Duration::from_nanos(41_025_000)
6449        );
6450        // A stale backend-local sample cannot move the process-tree clock back.
6451        assert_eq!(
6452            clock.observe(epoch + Duration::from_nanos(41_010_000)),
6453            epoch + Duration::from_nanos(41_025_000)
6454        );
6455    }
6456
6457    #[test]
6458    fn guest_clock_absolute_deadline_stays_ahead_of_committed_time() {
6459        let committed_time = LogicalTime::from_secs(1_000) + Duration::from_millis(250);
6460        let mut clock = GuestClock::default();
6461        let guest_now = clock.observe(committed_time);
6462        let deadline = guest_now + Duration::from_millis(100);
6463
6464        assert_eq!(guest_now, committed_time);
6465        assert!(deadline > committed_time);
6466    }
6467
6468    #[test]
6469    fn guest_clock_process_tree_shares_one_monotonic_domain() {
6470        let epoch = LogicalTime::from_secs(1_000);
6471        let root = Arc::new(Mutex::new(GuestClock::default()));
6472        let forked_child = Arc::clone(&root);
6473
6474        assert!(Arc::ptr_eq(&root, &forked_child));
6475        assert_eq!(
6476            root.lock().unwrap().observe(epoch + Duration::from_secs(1)),
6477            epoch + Duration::from_secs(1)
6478        );
6479        assert_eq!(
6480            forked_child
6481                .lock()
6482                .unwrap()
6483                .observe(epoch + Duration::from_secs(2)),
6484            epoch + Duration::from_secs(2)
6485        );
6486
6487        // Exec retains the same clock object and does not rebase elapsed time.
6488        let execed_child = Arc::clone(&forked_child);
6489        assert!(Arc::ptr_eq(&root, &execed_child));
6490        assert_eq!(
6491            execed_child
6492                .lock()
6493                .unwrap()
6494                .observe(epoch + Duration::from_secs(9)),
6495            epoch + Duration::from_secs(9)
6496        );
6497    }
6498
6499    #[test]
6500    fn unparented_thread_recovers_process_memory_identity() {
6501        let detpid = DetPid::from_raw(4);
6502        let dettid = DetTid::from_raw(7);
6503        let mut state = ThreadState::new(dettid, &Config::default(), ());
6504
6505        assert!(state.recover_process_mm_id(detpid));
6506        assert_eq!(state.mm_id, MmId::initial(detpid));
6507        assert!(!state.recover_process_mm_id(detpid));
6508    }
6509
6510    #[test]
6511    fn inherited_thread_keeps_existing_memory_identity() {
6512        let detpid = DetPid::from_raw(4);
6513        let dettid = DetTid::from_raw(7);
6514        let inherited_mm = MmId::initial(detpid).for_exec(detpid);
6515        let mut state = ThreadState::new(dettid, &Config::default(), ());
6516        state.mm_id = inherited_mm;
6517
6518        assert!(!state.recover_process_mm_id(detpid));
6519        assert_eq!(state.mm_id, inherited_mm);
6520    }
6521
6522    #[test]
6523    fn backend_can_override_open_file_creator_identity() {
6524        let host_tid = DetTid::from_raw(10_003);
6525        let virtual_tid = DetTid::from_raw(3);
6526        let mut state = ThreadState::new(host_tid, &Config::default(), ());
6527
6528        assert_eq!(state.open_file_creator, None);
6529        state.set_open_file_creator(virtual_tid);
6530        assert_eq!(state.open_file_creator, Some(virtual_tid));
6531    }
6532
6533    // AUTONOMOUS-BOT-IMPLEMENTED
6534    // TODO-HUMAN-REVIEW(PR-1149)
6535    #[test]
6536    fn chaos_per_thread_slowdown_factor_is_stable_and_deterministic() {
6537        let seed = 0xdead_beef_u64;
6538        let max_factor: f64 = 10.0;
6539        // Deterministic: same (seed, dettid) -> identical factor, every call.
6540        for raw in 1..=64 {
6541            let tid = DetTid::from_raw(raw);
6542            let a = chaos_per_thread_slowdown_factor(seed, tid, 0, max_factor);
6543            let b = chaos_per_thread_slowdown_factor(seed, tid, 0, max_factor);
6544            assert_eq!(
6545                a, b,
6546                "factor must be a pure function of (seed, dettid, epoch)"
6547            );
6548            // Log-uniform in [1/R, R].
6549            let a = a.as_f64();
6550            assert!(
6551                a >= 1.0 / max_factor - 1e-9 && a <= max_factor + 1e-9,
6552                "factor {} out of [1/{max_factor}, {max_factor}] for tid {raw}",
6553                a
6554            );
6555        }
6556    }
6557
6558    // AUTONOMOUS-BOT-IMPLEMENTED
6559    // TODO-HUMAN-REVIEW(PR-1149)
6560    #[test]
6561    fn chaos_per_thread_slowdown_factor_varies_across_threads_and_seeds() {
6562        let max_factor = 10.0;
6563        // Different threads (same seed) get a spread of factors, not all equal.
6564        let factors: Vec<f64> = (1..=32)
6565            .map(|raw| {
6566                chaos_per_thread_slowdown_factor(1234, DetTid::from_raw(raw), 0, max_factor)
6567                    .as_f64()
6568            })
6569            .collect();
6570        let first = factors[0];
6571        assert!(
6572            factors.iter().any(|&f| (f - first).abs() > 1e-6),
6573            "per-thread factors should differ across threads"
6574        );
6575        // Different seeds give a different factor for the same thread.
6576        let tid = DetTid::from_raw(7);
6577        let f_a = chaos_per_thread_slowdown_factor(1, tid, 0, max_factor).as_f64();
6578        let f_b = chaos_per_thread_slowdown_factor(2, tid, 0, max_factor).as_f64();
6579        assert!(
6580            (f_a - f_b).abs() > 1e-12,
6581            "different seeds should yield different factors for the same thread"
6582        );
6583    }
6584
6585    // AUTONOMOUS-BOT-IMPLEMENTED
6586    // TODO-HUMAN-REVIEW(PR-1149)
6587    #[test]
6588    fn chaos_per_thread_slowdown_factor_disabled_when_max_factor_at_most_one() {
6589        // max_factor <= 1.0 disables the spread: every thread is nominal (1.0).
6590        for raw in 1..=16 {
6591            let tid = DetTid::from_raw(raw);
6592            assert_eq!(
6593                chaos_per_thread_slowdown_factor(99, tid, 0, 1.0),
6594                RcbTimeMultiplier::ONE
6595            );
6596            assert_eq!(
6597                chaos_per_thread_slowdown_factor(99, tid, 0, 0.5),
6598                RcbTimeMultiplier::ONE
6599            );
6600        }
6601    }
6602
6603    // AUTONOMOUS-BOT-IMPLEMENTED
6604    // TODO-HUMAN-REVIEW(PR-1151)
6605    #[test]
6606    fn chaos_epoch_zero_reproduces_epochless_factor() {
6607        // Enabling epochs must never perturb the FIRST epoch: epoch 0 has to
6608        // yield exactly the value the epoch-less #1149 code produced (the epoch
6609        // term folds to 0 in the mix).
6610        use rand::RngExt as _;
6611        use rand::SeedableRng as _;
6612        let max_factor: f64 = 10.0;
6613        for raw in 1..=64 {
6614            let tid = DetTid::from_raw(raw);
6615            for &seed in &[0u64, 1, 7, 0xdead_beef, u64::MAX] {
6616                let epochless = {
6617                    // Reconstruct the exact epoch-less mix inline to pin the
6618                    // invariant independent of the production function body.
6619                    const SLOWDOWN_SALT: u64 = 0x736c_6f77_646f_776e;
6620                    let mixed = seed
6621                        ^ SLOWDOWN_SALT
6622                        ^ ((tid.as_raw() as u32 as u64).wrapping_mul(0x9e37_79b9_7f4a_7c15));
6623                    let mut prng = Pcg64Mcg::seed_from_u64(mixed);
6624                    let u: f64 = prng.random::<f64>();
6625                    max_factor.powf(2.0 * u - 1.0)
6626                };
6627                assert_eq!(
6628                    chaos_per_thread_slowdown_factor(seed, tid, 0, max_factor),
6629                    RcbTimeMultiplier::from_f64(epochless),
6630                    "epoch 0 must reproduce the epoch-less factor for seed {seed}, tid {raw}"
6631                );
6632            }
6633        }
6634    }
6635
6636    // AUTONOMOUS-BOT-IMPLEMENTED
6637    // TODO-HUMAN-REVIEW(PR-1151)
6638    #[test]
6639    fn chaos_epoch_factor_varies_deterministically_across_epochs() {
6640        let max_factor = 10.0;
6641        let seed = 0x1234_5678_u64;
6642        let tid = DetTid::from_raw(3);
6643        // Each epoch draws a fresh factor for the same thread; the sequence is
6644        // a pure function of (seed, dettid, epoch), hence replayable.
6645        let factors: Vec<f64> = (0..16)
6646            .map(|epoch| chaos_per_thread_slowdown_factor(seed, tid, epoch, max_factor).as_f64())
6647            .collect();
6648        // Purity: recomputing any epoch yields the identical value.
6649        for (epoch, &f) in factors.iter().enumerate() {
6650            assert_eq!(
6651                chaos_per_thread_slowdown_factor(seed, tid, epoch as u64, max_factor).as_f64(),
6652                f,
6653                "factor must be pure in epoch"
6654            );
6655            // Stays in the log-uniform range.
6656            assert!(f >= 1.0 / max_factor - 1e-9 && f <= max_factor + 1e-9);
6657        }
6658        // The factor actually changes across epochs (not a constant stream).
6659        let first = factors[0];
6660        assert!(
6661            factors.iter().any(|&f| (f - first).abs() > 1e-6),
6662            "per-epoch factors should differ across epochs"
6663        );
6664    }
6665
6666    fn cpu_snapshot(
6667        user: u64,
6668        system: u64,
6669        children_user: u64,
6670        children_system: u64,
6671    ) -> ProcessCpuSnapshot {
6672        ProcessCpuSnapshot {
6673            user: LogicalTime::from_nanos(user),
6674            system: LogicalTime::from_nanos(system),
6675            children_user: LogicalTime::from_nanos(children_user),
6676            children_system: LogicalTime::from_nanos(children_system),
6677        }
6678    }
6679
6680    #[test]
6681    fn child_cpu_time_is_hidden_until_reap() {
6682        let pid = DetPid::from_raw(2);
6683        let mut parent = ProcessCpuTime::default();
6684        parent.record_exited_child(pid, cpu_snapshot(10, 20, 3, 4));
6685
6686        assert_eq!(parent.snapshot.children_user, LogicalTime::ZERO);
6687        assert_eq!(parent.snapshot.children_system, LogicalTime::ZERO);
6688
6689        parent.reap_child(pid);
6690        assert_eq!(parent.snapshot.children_user, LogicalTime::from_nanos(13));
6691        assert_eq!(parent.snapshot.children_system, LogicalTime::from_nanos(24));
6692    }
6693
6694    #[test]
6695    fn reaping_nonexited_child_does_not_change_accounting() {
6696        let pid = DetPid::from_raw(2);
6697        let mut parent = ProcessCpuTime::default();
6698
6699        parent.reap_child(pid);
6700        assert_eq!(parent.snapshot.children_user, LogicalTime::ZERO);
6701        assert_eq!(parent.snapshot.children_system, LogicalTime::ZERO);
6702    }
6703
6704    #[test]
6705    fn child_cpu_time_uses_final_thread_snapshot_and_drops_reaped_state() {
6706        let pid = DetPid::from_raw(2);
6707        let mut parent = ProcessCpuTime::default();
6708
6709        parent.record_exited_child(pid, cpu_snapshot(10, 20, 3, 4));
6710        parent.record_exited_child(pid, cpu_snapshot(12, 25, 4, 5));
6711
6712        parent.reap_child(pid);
6713        assert_eq!(parent.snapshot.children_user, LogicalTime::from_nanos(16));
6714        assert_eq!(parent.snapshot.children_system, LogicalTime::from_nanos(30));
6715        assert!(parent.exited_children.is_empty());
6716
6717        parent.reap_child(pid);
6718        assert_eq!(parent.snapshot.children_user, LogicalTime::from_nanos(16));
6719        assert_eq!(parent.snapshot.children_system, LogicalTime::from_nanos(30));
6720    }
6721
6722    #[tokio::test]
6723    async fn child_cpu_publication_replacement_rejects_stale_owner_and_snapshot() {
6724        use std::future::Future;
6725        use std::task::Context;
6726
6727        let cfg = Config::default();
6728        let child = DetPid::from_raw(7);
6729        let mut parent = ThreadState::new(DetPid::from_raw(3), &cfg, ());
6730        assert!(!parent.wait_for_child_cpu_publication(child).await);
6731        let before = serde_json::to_value(&*parent.process_cpu_time.lock().unwrap()).unwrap();
6732        let first = parent.prepare_child_cpu_publication(child);
6733        let mut old_child = ThreadState::new(child, &cfg, ());
6734        old_child.parent_process_cpu_time = Some(Arc::clone(&parent.process_cpu_time));
6735        old_child.parent_cpu_publication = Some(Arc::clone(&first));
6736        let mut old_wait = Box::pin(parent.wait_for_child_cpu_publication(child));
6737        let mut cx = Context::from_waker(futures::task::noop_waker_ref());
6738        assert!(old_wait.as_mut().poll(&mut cx).is_pending());
6739        let second = parent.prepare_child_cpu_publication(child);
6740        assert!(!Arc::ptr_eq(&first, &second));
6741        assert!(!old_wait.await);
6742        assert!(!old_child.record_exited_child_process_cpu_time(child));
6743        assert!(!parent.has_exited_child_process_cpu_time(child));
6744        // Neither runtime notification state nor host wakers enter recordings.
6745        {
6746            let cpu = parent.process_cpu_time.lock().unwrap();
6747            assert_eq!(serde_json::to_value(&*cpu).unwrap(), before);
6748            let clone = cpu.clone();
6749            assert!(Arc::ptr_eq(
6750                clone.child_cpu_publications.get(&child).unwrap(),
6751                &second
6752            ));
6753            let restored: ProcessCpuTime = serde_json::from_value(before).unwrap();
6754            assert!(restored.child_cpu_publications.is_empty());
6755        }
6756
6757        let mut current_child = ThreadState::new(child, &cfg, ());
6758        current_child.parent_process_cpu_time = Some(Arc::clone(&parent.process_cpu_time));
6759        current_child.parent_cpu_publication = Some(Arc::clone(&second));
6760        assert!(current_child.record_exited_child_process_cpu_time(child));
6761        parent.prepare_child_process_cpu_time(child);
6762        assert!(parent.has_exited_child_process_cpu_time(child));
6763        assert!(parent.wait_for_child_cpu_publication(child).await);
6764        // ThreadState clones retain the same process identity.
6765        assert!(Arc::ptr_eq(
6766            current_child
6767                .clone()
6768                .parent_cpu_publication
6769                .as_ref()
6770                .unwrap(),
6771            &second
6772        ));
6773        parent.reap_child_process_cpu_time(child);
6774        assert!(!parent.wait_for_child_cpu_publication(child).await);
6775        assert!(!current_child.record_exited_child_process_cpu_time(child));
6776        assert!(!parent.has_exited_child_process_cpu_time(child));
6777    }
6778
6779    fn nz(value: u64) -> Option<NonZeroU64> {
6780        NonZeroU64::new(value)
6781    }
6782
6783    /// The cap of hermit#4121 only lowers the software slice end, keeps one
6784    /// RCB of room (10 ns at the default clock) plus one nanosecond, and
6785    /// leaves the PMU maximum alone.
6786    #[test]
6787    fn a_deadline_cap_lowers_the_slice_end_and_keeps_one_rcb() {
6788        let config = Config {
6789            max_timeslice: nz(200_000_000),
6790            ..Default::default()
6791        };
6792        let mut state = ThreadState::new(DetPid::from_raw(3), &config, ());
6793        state.next_timeslice(&config);
6794        let now = state.thread_logical_time.as_nanos();
6795        let end = state.end_of_timeslice.unwrap();
6796        assert_eq!(end, now + Duration::from_nanos(200_000_000));
6797        assert_eq!(state.max_timeslice_end, Some(end));
6798
6799        state.cap_timeslice_at_deadline(
6800            Duration::from_nanos(5_000_000),
6801            1.0,
6802            Duration::ZERO,
6803            false,
6804        );
6805        let capped = now + Duration::from_nanos(5_000_000);
6806        assert_eq!(state.end_of_timeslice, Some(capped));
6807        assert_eq!(state.max_timeslice_end, Some(end));
6808
6809        // A later deadline never raises the end.
6810        state.cap_timeslice_at_deadline(
6811            Duration::from_nanos(9_000_000),
6812            1.0,
6813            Duration::ZERO,
6814            false,
6815        );
6816        assert_eq!(state.end_of_timeslice, Some(capped));
6817
6818        // A deadline already due leaves one RCB and a nanosecond.
6819        state.cap_timeslice_at_deadline(Duration::ZERO, 1.0, Duration::ZERO, false);
6820        assert_eq!(state.end_of_timeslice, Some(now + Duration::from_nanos(11)));
6821        assert_eq!(state.max_timeslice_end, Some(end));
6822    }
6823
6824    /// The cap never ends a slice sooner than one scheduler turn charge
6825    /// (`min_slice`) after it is applied, so the turn it causes costs no more
6826    /// virtual time than the work the thread did.
6827    #[test]
6828    fn a_deadline_cap_keeps_at_least_one_turn_charge() {
6829        let config = Config {
6830            max_timeslice: nz(200_000_000),
6831            ..Default::default()
6832        };
6833        let mut state = ThreadState::new(DetPid::from_raw(3), &config, ());
6834        state.next_timeslice(&config);
6835        let now = state.thread_logical_time.as_nanos();
6836        let turn = Duration::from_nanos(500_000);
6837        state.cap_timeslice_at_deadline(Duration::from_nanos(1_000), 1.0, turn, false);
6838        assert_eq!(state.end_of_timeslice, Some(now + turn));
6839        state.cap_timeslice_at_deadline(Duration::ZERO, 1.0, turn, false);
6840        assert_eq!(state.end_of_timeslice, Some(now + turn));
6841        state.cap_timeslice_at_deadline(Duration::from_nanos(700_000), 1.0, turn, false);
6842        assert_eq!(state.end_of_timeslice, Some(now + turn));
6843    }
6844
6845    /// Schedule replay follows its recorded turns: the cap leaves its slices
6846    /// alone.
6847    #[test]
6848    fn schedule_replay_takes_no_deadline_cap() {
6849        let config = Config {
6850            max_timeslice: nz(200_000_000),
6851            ..Default::default()
6852        };
6853        let mut state = ThreadState::new(DetPid::from_raw(3), &config, ());
6854        state.next_timeslice(&config);
6855        let end = state.end_of_timeslice;
6856        state.cap_timeslice_at_deadline(Duration::from_nanos(5_000), 1.0, Duration::ZERO, true);
6857        assert_eq!(state.end_of_timeslice, end);
6858    }
6859
6860    // AUTONOMOUS-BOT-IMPLEMENTED
6861    // TODO-HUMAN-REVIEW(PR-1151)
6862    #[test]
6863    fn constant_slowdown_is_the_single_epoch_case() {
6864        let config = Config {
6865            chaos: true,
6866            chaos_per_thread_slowdown: true,
6867            chaos_epoch_length_ns: 0,
6868            target_timeslice: nz(10_000),
6869            max_timeslice: nz(100_000),
6870            ..Default::default()
6871        };
6872        let mut state = ThreadState::new(DetPid::from_raw(3), &config, ());
6873        state.next_timeslice(&config);
6874        let first = state.take_pending_chaos_epochs().pop().unwrap();
6875        assert_eq!(first.epoch, 0);
6876        assert_eq!(state.chaos_epoch, 0);
6877
6878        state
6879            .thread_logical_time
6880            .add_rcbs_with_multiplier(10_000, first.factor);
6881        state.next_timeslice(&config);
6882        assert_eq!(state.chaos_epoch, 0);
6883        assert_eq!(state.chaos_slowdown_factor, first.factor);
6884        assert!(state.take_pending_chaos_epochs().is_empty());
6885    }
6886
6887    // AUTONOMOUS-BOT-IMPLEMENTED
6888    // TODO-HUMAN-REVIEW(PR-1151)
6889    #[test]
6890    fn epoch_redraw_uses_elapsed_logical_time_at_commit_boundaries() {
6891        let config = Config {
6892            chaos: true,
6893            chaos_per_thread_slowdown: true,
6894            chaos_epoch_length_ns: 100,
6895            target_timeslice: nz(10_000),
6896            max_timeslice: nz(100_000),
6897            ..Default::default()
6898        };
6899        let tid = DetPid::from_raw(5);
6900        let mut state = ThreadState::new(tid, &config, ());
6901        state.next_timeslice(&config);
6902        let first = state.pending_chaos_epochs[0];
6903
6904        state
6905            .thread_logical_time
6906            .add_rcbs_with_multiplier(1_000, first.factor);
6907        let expected_epoch =
6908            state.thread_logical_time.without_starting().as_nanos() / config.chaos_epoch_length_ns;
6909        assert!(expected_epoch > 0);
6910
6911        state.next_timeslice(&config);
6912        let transitions = state.take_pending_chaos_epochs();
6913        assert_eq!(transitions.len(), 2);
6914        assert_eq!(transitions[0], first);
6915        let redraw = transitions[1];
6916        assert_eq!(redraw.epoch, expected_epoch);
6917        assert_eq!(
6918            redraw.factor,
6919            chaos_per_thread_slowdown_factor(
6920                config.sched_seed(),
6921                tid,
6922                expected_epoch,
6923                config.chaos_slowdown_max_factor,
6924            )
6925        );
6926        assert!(redraw.logical_time > first.logical_time);
6927    }
6928
6929    // AUTONOMOUS-BOT-IMPLEMENTED
6930    // TODO-HUMAN-REVIEW(PR-1151)
6931    #[test]
6932    fn replay_installs_recorded_epoch_without_ambient_chaos_flags() {
6933        let config = Config {
6934            target_timeslice: nz(10_000),
6935            max_timeslice: nz(100_000),
6936            ..Default::default()
6937        };
6938        let transition = ChaosEpochTransition {
6939            logical_time: LogicalTime::ZERO,
6940            epoch: 7,
6941            factor: RcbTimeMultiplier::from_f64(3.25),
6942        };
6943        let mut state = ThreadState::new(DetPid::from_raw(5), &config, ());
6944        state.preemption_points = Some(
6945            ThreadHistory::new()
6946                .with_chaos_epochs(vec![transition])
6947                .into_iter(),
6948        );
6949
6950        state.next_timeslice(&config);
6951
6952        assert!(state.chaos_slowdown_active);
6953        assert_eq!(state.chaos_epoch, transition.epoch);
6954        assert_eq!(state.chaos_slowdown_factor, transition.factor);
6955        assert!(state.take_pending_chaos_epochs().is_empty());
6956    }
6957
6958    // AUTONOMOUS-BOT-IMPLEMENTED
6959    // TODO-HUMAN-REVIEW(PR-1151)
6960    #[test]
6961    fn replay_installs_boundary_epoch_when_pmu_checks_in_early() {
6962        let config = Config {
6963            target_timeslice: nz(10_000),
6964            max_timeslice: nz(100_000),
6965            ..Default::default()
6966        };
6967        let mut state = ThreadState::new(DetPid::from_raw(5), &config, ());
6968        let now = state.thread_logical_time.as_nanos();
6969        let first = ChaosEpochTransition {
6970            logical_time: now,
6971            epoch: 0,
6972            factor: RcbTimeMultiplier::from_f64(2.0),
6973        };
6974        let second = ChaosEpochTransition {
6975            logical_time: now + Duration::from_nanos(100),
6976            epoch: 1,
6977            factor: RcbTimeMultiplier::from_f64(3.0),
6978        };
6979        let history = ThreadHistory::new()
6980            .with_prio_changes(vec![
6981                (now + Duration::from_nanos(100), DEFAULT_PRIORITY),
6982                (now + Duration::from_nanos(200), DEFAULT_PRIORITY),
6983            ])
6984            .with_preemption_rcbs(vec![4, 8])
6985            .with_chaos_epochs(vec![first, second]);
6986        state.preemption_points = Some(history.into_iter());
6987
6988        state.next_timeslice(&config);
6989        assert_eq!(state.chaos_slowdown_factor, first.factor);
6990        assert_eq!(
6991            state.end_of_timeslice,
6992            Some(now + Duration::from_nanos(100))
6993        );
6994
6995        // Four 2x RCBs advance to 80ns: within one RCB of the exact 100ns
6996        // boundary, matching the early check-in path in post_handler_hook.
6997        state
6998            .thread_logical_time
6999            .add_rcbs_with_multiplier(4, first.factor);
7000        state.committed_clock_value = 4;
7001        assert!(state.timeslice_expired());
7002        state.next_timeslice(&config);
7003
7004        assert_eq!(
7005            state.thread_logical_time.as_nanos(),
7006            now + Duration::from_nanos(80)
7007        );
7008        assert_eq!(state.chaos_epoch, second.epoch);
7009        assert_eq!(state.chaos_slowdown_factor, second.factor);
7010        assert_eq!(
7011            state.end_of_timeslice,
7012            Some(now + Duration::from_nanos(200))
7013        );
7014    }
7015
7016    // AUTONOMOUS-BOT-IMPLEMENTED
7017    // TODO-HUMAN-REVIEW(PR-1151)
7018    #[test]
7019    fn replay_preserves_adjacent_zero_rcb_slices() {
7020        let config = Config {
7021            target_timeslice: nz(10_000),
7022            max_timeslice: nz(100_000),
7023            ..Default::default()
7024        };
7025        let mut state = ThreadState::new(DetPid::from_raw(5), &config, ());
7026        let now = state.thread_logical_time.as_nanos();
7027        let history = ThreadHistory::new()
7028            .with_prio_changes(vec![
7029                (now + Duration::from_nanos(70), DEFAULT_PRIORITY),
7030                (now + Duration::from_nanos(80), DEFAULT_PRIORITY),
7031            ])
7032            .with_preemption_rcbs(vec![4, 4]);
7033        state.preemption_points = Some(history.into_iter());
7034
7035        state.next_timeslice(&config);
7036        state.thread_logical_time.add_rcbs(4);
7037        state.committed_clock_value = 4;
7038        assert!(state.timeslice_expired());
7039
7040        state.next_timeslice(&config);
7041        assert_eq!(state.replay_rcb_end, Some(4));
7042        assert!(state.timeslice_expired());
7043    }
7044
7045    #[test]
7046    fn target_and_pmu_deadlines_are_independent() {
7047        let config = Config {
7048            target_timeslice: nz(20_000),
7049            max_timeslice: nz(100_000),
7050            ..Default::default()
7051        };
7052        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7053        let now = state.thread_logical_time.as_nanos();
7054
7055        state.next_timeslice(&config);
7056
7057        assert_eq!(
7058            state.end_of_timeslice,
7059            Some(now + Duration::from_nanos(20_000))
7060        );
7061        assert_eq!(
7062            state.max_timeslice_end,
7063            Some(now + Duration::from_nanos(100_000))
7064        );
7065    }
7066
7067    #[test]
7068    fn target_only_mode_does_not_create_a_pmu_deadline() {
7069        let config = Config {
7070            target_timeslice: nz(20_000),
7071            max_timeslice: None,
7072            ..Default::default()
7073        };
7074        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7075        let now = state.thread_logical_time.as_nanos();
7076
7077        state.next_timeslice(&config);
7078
7079        assert_eq!(
7080            state.end_of_timeslice,
7081            Some(now + Duration::from_nanos(20_000))
7082        );
7083        assert_eq!(state.max_timeslice_end, None);
7084    }
7085
7086    #[test]
7087    fn max_timeslice_caps_a_larger_target() {
7088        let config = Config {
7089            target_timeslice: nz(100_000),
7090            max_timeslice: nz(20_000),
7091            ..Default::default()
7092        };
7093        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7094        let now = state.thread_logical_time.as_nanos();
7095
7096        state.next_timeslice(&config);
7097
7098        let max_end = now + Duration::from_nanos(20_000);
7099        assert_eq!(state.end_of_timeslice, Some(max_end));
7100        assert_eq!(state.max_timeslice_end, Some(max_end));
7101    }
7102
7103    #[test]
7104    fn chaos_without_target_caps_randomized_deadline_at_maximum() {
7105        let config = Config {
7106            chaos: true,
7107            target_timeslice: None,
7108            max_timeslice: nz(100_000),
7109            clock_multiplier: Some(1.05),
7110            ..Default::default()
7111        };
7112        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7113        let now = state.thread_logical_time.as_nanos();
7114        let configured_max = now + Duration::from_nanos(100_000);
7115        let minimum_progress = now + Duration::from_nanos(11);
7116
7117        state.next_timeslice(&config);
7118
7119        assert_eq!(state.max_timeslice_end, state.end_of_timeslice);
7120        assert!(state.max_timeslice_end.unwrap() <= configured_max);
7121        assert!(state.max_timeslice_end.unwrap() >= minimum_progress);
7122    }
7123
7124    #[test]
7125    fn schedule_replay_without_rcb_time_arms_pmu_maximum() {
7126        let config = Config {
7127            no_rcb_time: true,
7128            max_timeslice: nz(100_000),
7129            replay_schedule_from: Some(std::path::PathBuf::from("schedule.json")),
7130            ..Default::default()
7131        };
7132        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7133        let now = state.thread_logical_time.as_nanos();
7134
7135        state.next_timeslice(&config);
7136
7137        let expected = now + Duration::from_nanos(100_000);
7138        assert_eq!(state.end_of_timeslice, Some(expected));
7139        assert_eq!(state.max_timeslice_end, Some(expected));
7140    }
7141
7142    #[test]
7143    fn exhausted_preemption_replay_uses_bounded_pmu_maximum() {
7144        let config = Config {
7145            max_timeslice: nz(100_000),
7146            ..Default::default()
7147        };
7148        let mut state = ThreadState::new(DetPid::from_raw(3), &config, ());
7149        state.preemption_points = Some(ThreadHistory::new().into_iter());
7150        let now = state.thread_logical_time.as_nanos();
7151
7152        state.next_timeslice(&config);
7153
7154        let bounded_end = Some(now + Duration::from_nanos(100_000));
7155        assert_eq!(state.end_of_timeslice, bounded_end);
7156        assert_eq!(state.max_timeslice_end, bounded_end);
7157    }
7158
7159    /// A preemption replay keeps a recorded slice end uncapped. Once the
7160    /// recording runs out its slice end is `LogicalTime::MAX`, which the cap
7161    /// may lower.
7162    #[test]
7163    fn preemption_replay_caps_only_past_its_recording() {
7164        let config = Config {
7165            max_timeslice: nz(100_000),
7166            ..Default::default()
7167        };
7168        let mut state = ThreadState::new(DetPid::from_raw(3), &config, ());
7169        let now = state.thread_logical_time.as_nanos();
7170        let recorded_end = now + Duration::from_nanos(50_000);
7171        let history = ThreadHistory::new()
7172            .with_prio_changes(vec![(recorded_end, DEFAULT_PRIORITY)])
7173            .with_preemption_rcbs(vec![5_000]);
7174        state.preemption_points = Some(history.into_iter());
7175
7176        state.next_timeslice(&config);
7177        assert_eq!(state.end_of_timeslice, Some(recorded_end));
7178        state.cap_timeslice_at_deadline(Duration::from_nanos(1_000), 1.0, Duration::ZERO, false);
7179        assert_eq!(state.end_of_timeslice, Some(recorded_end));
7180
7181        let mut exhausted = ThreadState::new(DetPid::from_raw(3), &config, ());
7182        exhausted.preemption_points = Some(ThreadHistory::new().into_iter());
7183        exhausted.next_timeslice(&config);
7184        exhausted.cap_timeslice_at_deadline(
7185            Duration::from_nanos(1_000),
7186            1.0,
7187            Duration::ZERO,
7188            false,
7189        );
7190        let capped = Some(now + Duration::from_nanos(1_000));
7191        assert_eq!(exhausted.end_of_timeslice, capped);
7192        assert_eq!(
7193            exhausted.max_timeslice_end,
7194            Some(now + Duration::from_nanos(100_000))
7195        );
7196    }
7197
7198    #[test]
7199    fn timeslice_expiry_is_inclusive() {
7200        let config = Config::default();
7201        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7202        let now = state.thread_logical_time.as_nanos();
7203
7204        state.end_of_timeslice = Some(now + Duration::from_nanos(1));
7205        assert!(!state.timeslice_expired());
7206        state.end_of_timeslice = Some(now);
7207        assert!(state.timeslice_expired());
7208    }
7209
7210    #[test]
7211    fn instruction_trap_ends_an_expired_target_only_at_the_pmu_maximum() {
7212        let config = Config {
7213            target_timeslice: nz(1_000),
7214            target_timeslice_syscalls_only: true,
7215            max_timeslice: nz(20_000),
7216            ..Default::default()
7217        };
7218        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7219        state.next_timeslice(&config);
7220
7221        // Past the target: a syscall would end the slice, an rdtsc must not.
7222        state.thread_logical_time.add_rcbs(500);
7223        assert!(state.timeslice_expired());
7224        assert!(!state.instruction_trap_ends_timeslice(&config));
7225
7226        // At the PMU maximum the trap ends it, as a branch would.
7227        state.thread_logical_time.add_rcbs(1_500);
7228        assert!(state.instruction_trap_ends_timeslice(&config));
7229    }
7230
7231    #[test]
7232    fn instruction_trap_ends_an_expired_target_by_default() {
7233        let config = Config {
7234            target_timeslice: nz(1_000),
7235            max_timeslice: nz(20_000),
7236            ..Default::default()
7237        };
7238        assert!(!config.target_timeslice_syscalls_only);
7239        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7240        state.next_timeslice(&config);
7241        state.thread_logical_time.add_rcbs(99);
7242        assert!(!state.instruction_trap_ends_timeslice(&config));
7243        state.thread_logical_time.add_rcbs(1);
7244        assert!(state.instruction_trap_ends_timeslice(&config));
7245    }
7246
7247    #[test]
7248    fn instruction_trap_ends_an_expired_target_without_a_pmu_maximum() {
7249        // With PMU preemption disabled nothing else can break a busy-wait on
7250        // the TSC, so the trap keeps ending the expired target.
7251        let config = Config {
7252            target_timeslice: nz(1_000),
7253            target_timeslice_syscalls_only: true,
7254            max_timeslice: None,
7255            ..Default::default()
7256        };
7257        let mut state = ThreadState::new(DetPid::from_raw(1), &config, ());
7258        state.next_timeslice(&config);
7259        assert_eq!(state.max_timeslice_end, None);
7260
7261        // 1,000 ns is 100 RCBs at the default 10 ns per RCB.
7262        state.thread_logical_time.add_rcbs(99);
7263        assert!(!state.instruction_trap_ends_timeslice(&config));
7264        state.thread_logical_time.add_rcbs(1);
7265        assert!(state.instruction_trap_ends_timeslice(&config));
7266    }
7267
7268    #[test]
7269    fn instruction_trap_keeps_replayed_and_untargeted_boundaries() {
7270        // Without a target the slice end is the PMU maximum itself, and a
7271        // replayed preemption record keeps its recorded boundaries: in both
7272        // cases a trap ends exactly the slices it ended before.
7273        let untargeted = Config {
7274            max_timeslice: nz(20_000),
7275            ..Default::default()
7276        };
7277        let mut state = ThreadState::new(DetPid::from_raw(1), &untargeted, ());
7278        state.next_timeslice(&untargeted);
7279        state.thread_logical_time.add_rcbs(1_999);
7280        assert_eq!(
7281            state.instruction_trap_ends_timeslice(&untargeted),
7282            state.timeslice_expired()
7283        );
7284        state.thread_logical_time.add_rcbs(1);
7285        assert!(state.instruction_trap_ends_timeslice(&untargeted));
7286
7287        let targeted = Config {
7288            target_timeslice: nz(1_000),
7289            target_timeslice_syscalls_only: true,
7290            max_timeslice: nz(20_000),
7291            ..Default::default()
7292        };
7293        let mut state = ThreadState::new(DetPid::from_raw(1), &targeted, ());
7294        state.next_timeslice(&targeted);
7295        state.preemption_points = Some(ThreadHistory::new().into_iter());
7296        state.thread_logical_time.add_rcbs(500);
7297        assert!(state.timeslice_expired());
7298        assert!(state.instruction_trap_ends_timeslice(&targeted));
7299    }
7300
7301    #[test]
7302    fn child_rng_distinguishes_adjacent_thread_ids() {
7303        let parent = Pcg64Mcg::seed_from_u64(0);
7304        let mut even = thread_rng_from_parent("test", &parent, DetTid::from_raw(8));
7305        let mut odd = thread_rng_from_parent("test", &parent, DetTid::from_raw(9));
7306
7307        let even_values: [u64; 4] = std::array::from_fn(|_| even.next_u64());
7308        let odd_values: [u64; 4] = std::array::from_fn(|_| odd.next_u64());
7309        assert_ne!(even_values, odd_values);
7310    }
7311
7312    #[test]
7313    fn child_rng_uses_high_entropy_bits() {
7314        let parent = Pcg64Mcg::seed_from_u64(0);
7315        let mut low = thread_rng_from_parent_entropy("test", &parent, 1);
7316        let mut high = thread_rng_from_parent_entropy("test", &parent, (1_u128 << 64) | 1);
7317
7318        let low_values: [u64; 4] = std::array::from_fn(|_| low.next_u64());
7319        let high_values: [u64; 4] = std::array::from_fn(|_| high.next_u64());
7320        assert_ne!(low_values, high_values);
7321    }
7322
7323    #[test]
7324    fn child_rng_pedigree_uses_the_full_unbounded_path() {
7325        let parent_rng = Pcg64Mcg::seed_from_u64(0);
7326        let mut long_path = Pedigree::new();
7327        for index in 0..2_048 {
7328            let (parent, child) = long_path.fork();
7329            long_path = if index % 2 == 0 { child } else { parent };
7330        }
7331        let (left, right) = long_path.fork();
7332        let mut left_rng =
7333            thread_rng_from_parent_pedigree("test", &parent_rng, &left, ChildRngStream::User);
7334        let mut right_rng =
7335            thread_rng_from_parent_pedigree("test", &parent_rng, &right, ChildRngStream::User);
7336
7337        let left_values: [u64; 4] = std::array::from_fn(|_| left_rng.next_u64());
7338        let right_values: [u64; 4] = std::array::from_fn(|_| right_rng.next_u64());
7339        assert_ne!(left_values, right_values);
7340    }
7341
7342    #[test]
7343    fn child_rng_pedigree_separates_user_and_chaos_streams() {
7344        let parent_rng = Pcg64Mcg::seed_from_u64(0);
7345        let (_, child) = Pedigree::new().fork();
7346        let mut user_rng = thread_rng_from_parent_pedigree(
7347            "same logging label",
7348            &parent_rng,
7349            &child,
7350            ChildRngStream::User,
7351        );
7352        let mut chaos_rng = thread_rng_from_parent_pedigree(
7353            "same logging label",
7354            &parent_rng,
7355            &child,
7356            ChildRngStream::Chaos,
7357        );
7358
7359        let user_values: [u64; 4] = std::array::from_fn(|_| user_rng.next_u64());
7360        let chaos_values: [u64; 4] = std::array::from_fn(|_| chaos_rng.next_u64());
7361        assert_ne!(user_values, chaos_values);
7362    }
7363}
7364
7365/// Generate a new thread-local PRNG from the parent's PRNG state, mixing in the
7366/// new DetTid for some deterministic entropy. This ensures sequentially-spawned
7367/// threads get distinct PRNG states.
7368// TODO-HUMAN-REVIEW(PR-1052): Review collision-free child-thread PRNG seeding.
7369pub fn thread_rng_from_parent(msg: &str, parent: &Pcg64Mcg, child: DetTid) -> Pcg64Mcg {
7370    thread_rng_from_parent_entropy_labeled(msg, parent, child.as_raw() as u32 as u128, "tid")
7371}
7372
7373#[derive(Clone, Copy, Debug)]
7374pub(crate) enum ChildRngStream {
7375    User,
7376    Chaos,
7377}
7378
7379impl ChildRngStream {
7380    fn domain(self) -> &'static [u8] {
7381        match self {
7382            Self::User => b"user",
7383            Self::Chaos => b"chaos",
7384        }
7385    }
7386}
7387
7388// TODO-HUMAN-REVIEW(PR-1052): Review pedigree-derived child-thread PRNG seeding.
7389pub(crate) fn thread_rng_from_parent_pedigree(
7390    msg: &str,
7391    parent: &Pcg64Mcg,
7392    child: &Pedigree,
7393    stream: ChildRngStream,
7394) -> Pcg64Mcg {
7395    let bits = child.raw();
7396    let mut packed = Vec::with_capacity(bits.len().div_ceil(8));
7397    let mut byte = 0_u8;
7398    for (index, bit) in bits.iter().enumerate() {
7399        if *bit {
7400            byte |= 1 << (index % 8);
7401        }
7402        if index % 8 == 7 {
7403            packed.push(byte);
7404            byte = 0;
7405        }
7406    }
7407    if !bits.len().is_multiple_of(8) {
7408        packed.push(byte);
7409    }
7410
7411    // Pedigrees are unbounded, while Pcg64Mcg has a 128-bit state. Hash the
7412    // complete, length-delimited path instead of using the fallible compressed
7413    // virtual-PID encoding, so child RNG identity has no artificial tree-depth
7414    // boundary. The domain string prevents this digest from being confused
7415    // with another future use of the same pedigree serialization. Pcg64Mcg
7416    // forces its low state bit, so this retains 127 effective digest bits.
7417    let mut hasher = Sha256::new();
7418    hasher.update(b"hermit-child-rng-pedigree-v1\0");
7419    hasher.update(stream.domain());
7420    hasher.update([0]);
7421    hasher.update((bits.len() as u64).to_le_bytes());
7422    hasher.update(&packed);
7423    let digest = hasher.finalize();
7424
7425    let mut seed = <Pcg64Mcg as SeedableRng>::Seed::default();
7426    parent.clone().fill_bytes(seed.as_mut());
7427    for (seed_byte, pedigree_byte) in seed.iter_mut().zip(digest) {
7428        *seed_byte ^= pedigree_byte;
7429    }
7430    detlog!(
7431        "RNG {} seeding child {:?} pedigree {}: {:?} from parent {:?}",
7432        msg,
7433        stream,
7434        child,
7435        seed,
7436        parent
7437    );
7438    let mut rng = Pcg64Mcg::from_seed(seed);
7439    rng.next_u64();
7440    rng.next_u64();
7441    rng.next_u64();
7442    rng.next_u64();
7443    rng
7444}
7445
7446#[cfg(test)]
7447mod native_exec_cut_tests {
7448    use super::*;
7449    use crate::native_exec::NativeExecCutError;
7450    use crate::native_exec::capture_prepared_native_exec;
7451    use crate::native_exec::tests::fixture;
7452    use crate::native_exec::tests::prepare;
7453    use crate::native_exec::tests::state_bytes;
7454    use crate::native_exec::validate_old_native_exec_cut;
7455
7456    #[test]
7457    fn native_exec_child_publications_refuse_every_runtime_token_state() {
7458        for completion in [None, Some(true), Some(false)] {
7459            let (tool, thread, binding) = fixture();
7460            let before = state_bytes(&thread);
7461            let child = DetPid::from_raw(43);
7462            let token = thread.prepare_child_cpu_publication(child);
7463            if let Some(published) = completion {
7464                token.finish(published);
7465            }
7466            // The map is genuinely invisible to serde in all three states.
7467            assert_eq!(state_bytes(&thread), before);
7468            assert!(matches!(
7469                validate_old_native_exec_cut(&tool, &thread, &binding),
7470                Err(NativeExecCutError::LiveCapability("child_cpu_publications"))
7471            ));
7472            assert!(Arc::ptr_eq(
7473                thread
7474                    .process_cpu_time
7475                    .lock()
7476                    .unwrap()
7477                    .child_cpu_publications
7478                    .get(&child)
7479                    .unwrap(),
7480                &token
7481            ));
7482        }
7483    }
7484
7485    #[test]
7486    fn native_exec_historical_cpu_accounting_survives_without_live_publications() {
7487        let (tool, mut thread, binding) = fixture();
7488        {
7489            let mut cpu = thread.process_cpu_time.lock().unwrap();
7490            cpu.add_thread_delta(LogicalTime::from_nanos(17), LogicalTime::from_nanos(31));
7491            cpu.record_exited_child(
7492                DetPid::from_raw(43),
7493                ProcessCpuSnapshot {
7494                    user: LogicalTime::from_nanos(19),
7495                    system: LogicalTime::from_nanos(23),
7496                    children_user: LogicalTime::from_nanos(29),
7497                    children_system: LogicalTime::from_nanos(37),
7498                },
7499            );
7500            cpu.reap_child(DetPid::from_raw(43));
7501            cpu.record_exited_child(
7502                DetPid::from_raw(44),
7503                ProcessCpuSnapshot {
7504                    user: LogicalTime::from_nanos(41),
7505                    system: LogicalTime::from_nanos(47),
7506                    ..ProcessCpuSnapshot::default()
7507                },
7508            );
7509        }
7510        let before = serde_json::to_value(&*thread.process_cpu_time.lock().unwrap()).unwrap();
7511        let receipt = validate_old_native_exec_cut(&tool, &thread, &binding).unwrap();
7512        prepare(&mut thread, &binding);
7513        let bytes = bincode::serde::encode_to_vec(
7514            capture_prepared_native_exec(&tool, &thread, &binding, &receipt).unwrap(),
7515            bincode::config::legacy(),
7516        )
7517        .unwrap();
7518        let (payload, used): (crate::native_exec::DetcoreExecSnapshotV2, _) =
7519            bincode::serde::decode_from_slice(&bytes, bincode::config::legacy()).unwrap();
7520        assert_eq!(used, bytes.len());
7521        let (_, restored) = payload.into_validated_parts(&binding, &tool.cfg).unwrap();
7522        assert_eq!(
7523            serde_json::to_value(&*restored.process_cpu_time.lock().unwrap()).unwrap(),
7524            before
7525        );
7526        let cpu = restored.process_cpu_time.lock().unwrap();
7527        assert_eq!(cpu.snapshot.children_user, LogicalTime::from_nanos(48));
7528        assert_eq!(cpu.snapshot.children_system, LogicalTime::from_nanos(60));
7529        assert_eq!(cpu.exited_children.len(), 1);
7530        assert!(cpu.child_cpu_publications.is_empty());
7531    }
7532
7533    #[test]
7534    fn native_exec_old_accept_waits_and_invalid_table_slots_refuse() {
7535        let (tool, thread, binding) = fixture();
7536        let operation = {
7537            let mut table = thread.file_metadata.lock().unwrap();
7538            table
7539                .add_fd(binding.dettid, 33, OFlag::O_CLOEXEC, FdType::Socket, None)
7540                .unwrap();
7541            table.add_accept_wait(33)
7542        };
7543        assert!(matches!(
7544            validate_old_native_exec_cut(&tool, &thread, &binding),
7545            Err(NativeExecCutError::LiveCapability("accept_waits"))
7546        ));
7547        let mut table = thread.file_metadata.lock().unwrap();
7548        assert!(table.for_exec(binding.dettid).accept_waits.is_empty());
7549        assert_eq!(table.accept_waits, [(operation, 33)]);
7550        table.remove_accept_wait(operation);
7551        // An old operation counter is historical, but the existing prepared
7552        // table has a fresh counter. Neither validation path resets it.
7553        assert_eq!(table.next_accept_wait, operation + 1);
7554        table
7555            .validate_native_exec_cut(binding.old_files, false)
7556            .unwrap();
7557        let mut prepared = table.for_exec(binding.dettid);
7558        prepared
7559            .validate_native_exec_cut(binding.prepared_files(), true)
7560            .unwrap();
7561        prepared.next_accept_wait = 1;
7562        assert_eq!(
7563            prepared.validate_native_exec_cut(binding.prepared_files(), true),
7564            Err(NativeExecCutError::PreparedState("next_accept_wait"))
7565        );
7566        let only = table.file_handles.remove(&33).unwrap();
7567        table.file_handles.insert(34, only);
7568        assert_eq!(
7569            table.validate_native_exec_cut(binding.old_files, false),
7570            Err(NativeExecCutError::Descriptor("slot number"))
7571        );
7572        table.file_handles.clear();
7573        table.file_handles.insert(
7574            -1,
7575            DetFd::new(
7576                -1,
7577                OFlag::empty(),
7578                FdType::Rng,
7579                OpenFileId::new(binding.dettid, 1),
7580            ),
7581        );
7582        assert_eq!(
7583            table.validate_native_exec_cut(binding.old_files, false),
7584            Err(NativeExecCutError::Descriptor("slot number"))
7585        );
7586    }
7587
7588    #[test]
7589    fn native_exec_each_skipped_or_live_thread_transient_refuses() {
7590        for field in 0..26 {
7591            let (tool, mut thread, binding) = fixture();
7592            match field {
7593                0 => {
7594                    thread.parent_process_cpu_time =
7595                        Some(Arc::new(Mutex::new(ProcessCpuTime::default())))
7596                }
7597                1 => thread.parent_cpu_publication = Some(ChildCpuPublication::pending()),
7598                2 => {
7599                    thread.restart_block = Some(crate::syscalls::helpers::RestartBlock {
7600                        rip: 0x1234,
7601                        deadline: None,
7602                        call: crate::syscalls::helpers::RestartCall::Poll(
7603                            reverie::syscalls::Poll::new(),
7604                        ),
7605                    })
7606                }
7607                3 => thread.signal_register_projection = Some(unsafe { std::mem::zeroed() }),
7608                4 => thread.clone_flags = Some(CloneFlags::empty()),
7609                5 => {
7610                    thread.pending_vfork = Some(PendingVfork {
7611                        parent_dettid: binding.dettid,
7612                        parent_detpid: binding.detpid,
7613                        child_tid_addr: 0,
7614                        flags: CloneFlags::CLONE_VFORK,
7615                        exit_signal: libc::SIGCHLD,
7616                        child_priority_entropy: None,
7617                    })
7618                }
7619                6 => thread.own_signal_turn_hold = Some(libc::SIGALRM),
7620                7 => thread.sigalrm_handled = true,
7621                8 => thread.handler_restore_rt_reported = 1,
7622                9 => {
7623                    thread.initialized_random_auxv = Some((
7624                        crate::random::InitialImage {
7625                            pid: binding.physical_tid,
7626                            start_time_ticks: 1,
7627                            at_random: 0x234000,
7628                        },
7629                        [7; 16],
7630                        Vec::new(),
7631                    ))
7632                }
7633                10 => thread.uncharged_bootstrap_syscalls = 1,
7634                11 => thread.in_uncharged_bootstrap_syscall = true,
7635                12 => thread.yield_after_futex_wake = true,
7636                13 => {
7637                    thread.interrupt_at.insert(1);
7638                }
7639                14 => thread.replay_rcb_end = Some(1),
7640                15 => thread.last_rcb_timer = Some(1),
7641                16 => thread.last_rcb_timer_is_max = true,
7642                17 => thread.max_timeslice_end = Some(LogicalTime::from_nanos(1)),
7643                18 => thread.chaos_slowdown_active = true,
7644                19 => thread.nested_pid_namespace = true,
7645                20 => thread.thread_start_entered = false,
7646                21 => thread.past_global_first_execve = false,
7647                22 => {
7648                    thread.last_accounted_system_time =
7649                        thread.thread_logical_time.system_cpu_time() + Duration::from_nanos(1)
7650                }
7651                23 => {
7652                    thread.preemption_points =
7653                        Some(crate::preemptions::ThreadHistory::new().into_iter())
7654                }
7655                24 => thread.pending_chaos_epochs.push(ChaosEpochTransition {
7656                    logical_time: LogicalTime::from_nanos(1),
7657                    epoch: 1,
7658                    factor: RcbTimeMultiplier::from_f64(1.5),
7659                }),
7660                25 => {
7661                    thread.signal_task_identity = Some(reverie::SignalTaskIdentity {
7662                        process: reverie::SignalProcessId {
7663                            tgid: reverie::Pid::from_raw(binding.physical_tid),
7664                            generation: 0,
7665                        },
7666                        tid: reverie::Pid::from_raw(binding.physical_tid),
7667                        task_generation: 0,
7668                    })
7669                }
7670                _ => unreachable!(),
7671            }
7672            assert!(
7673                validate_old_native_exec_cut(&tool, &thread, &binding).is_err(),
7674                "field {field}"
7675            );
7676        }
7677    }
7678
7679    #[test]
7680    fn native_exec_robust_and_prepared_memory_must_match_the_actual_cut() {
7681        for field in 0..4 {
7682            let (tool, mut thread, binding) = fixture();
7683            thread.record_robust_list_head(Some(0x1000));
7684            {
7685                let mut robust = thread.robust_list_process.lock().unwrap();
7686                match field {
7687                    0 => {
7688                        robust.heads.insert(DetTid::from_raw(43), 0x2000);
7689                    }
7690                    1 => {
7691                        robust.pending.insert(
7692                            binding.dettid,
7693                            PendingRobustListWakes {
7694                                reason: RobustListExit::ExitGroup,
7695                                wakes: Vec::new(),
7696                            },
7697                        );
7698                    }
7699                    2 => {
7700                        robust
7701                            .matched_physical_exits
7702                            .insert(binding.dettid, thread.thread_logical_time.clone());
7703                    }
7704                    3 => robust.exec_pending.push((
7705                        binding.dettid,
7706                        RobustListWake {
7707                            futex: FutexID::private(binding.old_mm, 0x3000),
7708                        },
7709                    )),
7710                    _ => unreachable!(),
7711                }
7712            }
7713            assert!(
7714                validate_old_native_exec_cut(&tool, &thread, &binding).is_err(),
7715                "old field {field}"
7716            );
7717        }
7718        for field in 0..8 {
7719            let (tool, mut thread, binding) = fixture();
7720            let receipt = validate_old_native_exec_cut(&tool, &thread, &binding).unwrap();
7721            prepare(&mut thread, &binding);
7722            match field {
7723                0 => thread.memory_metadata.lock().unwrap().observe_brk(0x4000),
7724                1 => thread.memory_metadata.lock().unwrap().map_anonymous(
7725                    binding.prepared_mm(),
7726                    0x5000,
7727                    0x1000,
7728                ),
7729                2 => thread.record_robust_list_head(Some(0x1000)),
7730                3 => thread.stage_robust_list_wakes_for_exec(vec![(
7731                    binding.dettid,
7732                    vec![RobustListWake {
7733                        futex: FutexID::private(binding.prepared_mm(), 0x3000),
7734                    }],
7735                )]),
7736                4 => thread.stage_robust_list_wakes_for_exec(vec![(
7737                    DetTid::from_raw(43),
7738                    vec![RobustListWake {
7739                        futex: FutexID::private(binding.old_mm, 0x3000),
7740                    }],
7741                )]),
7742                5 => thread.file_metadata.lock().unwrap().files_id = binding.old_files,
7743                6 => {
7744                    thread.file_metadata.lock().unwrap().file_handles.insert(
7745                        3,
7746                        DetFd::new(
7747                            3,
7748                            OFlag::O_CLOEXEC,
7749                            FdType::Rng,
7750                            OpenFileId::new(binding.dettid, 1),
7751                        ),
7752                    );
7753                }
7754                7 => thread.mm_id = binding.old_mm,
7755                _ => unreachable!(),
7756            }
7757            assert!(
7758                capture_prepared_native_exec(&tool, &thread, &binding, &receipt).is_err(),
7759                "prepared field {field}"
7760            );
7761        }
7762    }
7763
7764    #[test]
7765    fn native_exec_model_lock_contention_is_a_refusal_without_mutation() {
7766        let (tool, thread, binding) = fixture();
7767        let before = state_bytes(&thread);
7768        macro_rules! locked {
7769            ($field:ident) => {{
7770                let guard = thread.$field.lock().unwrap();
7771                assert!(matches!(
7772                    validate_old_native_exec_cut(&tool, &thread, &binding),
7773                    Err(NativeExecCutError::LockUnavailable(_))
7774                ));
7775                drop(guard);
7776                assert_eq!(state_bytes(&thread), before);
7777            }};
7778        }
7779        locked!(file_metadata);
7780        locked!(process_cpu_time);
7781        locked!(guest_clock);
7782        locked!(resource_limits);
7783        locked!(posix_timers);
7784        locked!(robust_list_process);
7785        validate_old_native_exec_cut(&tool, &thread, &binding).unwrap();
7786    }
7787}
7788
7789fn thread_rng_from_parent_entropy(msg: &str, parent: &Pcg64Mcg, entropy: u128) -> Pcg64Mcg {
7790    thread_rng_from_parent_entropy_labeled(msg, parent, entropy, "entropy")
7791}
7792
7793fn thread_rng_from_parent_entropy_labeled(
7794    msg: &str,
7795    parent: &Pcg64Mcg,
7796    entropy: u128,
7797    identity_kind: &str,
7798) -> Pcg64Mcg {
7799    // Perform the default SeedableRng::from_seed procedure
7800    let mut seed = <Pcg64Mcg as SeedableRng>::Seed::default();
7801    // Generate a seed from the parent:
7802    parent.clone().fill_bytes(seed.as_mut());
7803    detlog!("RNG {} Generated new seed {:?}", msg, seed);
7804    // Pcg64Mcg forces its internal state odd, so seed bit zero carries no
7805    // entropy. DBT uses 96 bits for a stable process/thread sequence; mix those
7806    // bytes after the forced bit while retaining the existing DetTid layout.
7807    let entropy_bytes = entropy.to_le_bytes();
7808    for (seed_byte, entropy_byte) in seed[4..].iter_mut().zip(entropy_bytes) {
7809        *seed_byte ^= entropy_byte;
7810    }
7811    detlog!(
7812        "RNG {} seeding child {} {}: {:?} from parent {:?}",
7813        msg,
7814        identity_kind,
7815        entropy,
7816        seed,
7817        parent
7818    );
7819    let mut rng = Pcg64Mcg::from_seed(seed);
7820    // Pcg64Mcg integrates flipped bits across the state quickly. Some PRNGs don't.
7821    // Defensively ensure flipped bits "propagate":
7822    rng.next_u64();
7823    rng.next_u64();
7824    rng.next_u64();
7825    rng.next_u64();
7826    rng
7827}
7828
7829/// The procfs path that descriptor `fd` of the calling process is a
7830/// placeholder for, which this image of the process has not seen: a memfd
7831/// named for it and sealed as Detcore seals its placeholders, which a guest
7832/// could imitate (a known limitation, see
7833/// <https://github.com/rrnewton/hermit/issues/4263>). Read with raw
7834/// system calls (under in-guest backends the tool shares the guest's C
7835/// library).
7836/// The fixed procfs file the kernel opened at `fd`, if its descriptor link
7837/// names one (`ProcfsFile::snapshot_is_fixed`).
7838fn fixed_procfs_behind(fd: RawFd) -> Option<crate::procfs::ProcfsFile> {
7839    // The calling thread's own table: `/proc/self/fd` is the leader's.
7840    let link = std::ffi::CString::new(format!("/proc/thread-self/fd/{fd}")).ok()?;
7841    let mut target = [0_u8; 256];
7842    // SAFETY: the path is NUL-terminated and `target` is writable.
7843    let length = unsafe {
7844        crate::util::raw_syscall(
7845            libc::SYS_readlinkat,
7846            [
7847                libc::AT_FDCWD as u64,
7848                link.as_ptr() as u64,
7849                target.as_mut_ptr() as u64,
7850                target.len() as u64,
7851                0,
7852                0,
7853            ],
7854        )
7855    };
7856    let length = usize::try_from(length)
7857        .ok()
7858        .filter(|length| *length < target.len())?;
7859    let path = std::path::Path::new(
7860        <std::ffi::OsStr as std::os::unix::ffi::OsStrExt>::from_bytes(&target[..length]),
7861    );
7862    crate::procfs::ProcfsFile::from_path(path).filter(crate::procfs::ProcfsFile::snapshot_is_fixed)
7863}
7864
7865fn placeholder_behind(
7866    fd: RawFd,
7867    files: crate::procfs::RenderedFiles,
7868) -> Option<(&'static std::path::Path, Vec<u8>)> {
7869    // SAFETY: F_GET_SEALS only reads the descriptor's seals.
7870    let seals = unsafe {
7871        crate::util::raw_syscall(
7872            libc::SYS_fcntl,
7873            [fd as u64, libc::F_GET_SEALS as u64, 0, 0, 0, 0],
7874        )
7875    };
7876    // An `O_PATH` descriptor cannot show its seals (EBADF); its name decides.
7877    let wanted = i64::from(crate::syscalls::rendered_procfs::PLACEHOLDER_SEALS);
7878    if seals != -i64::from(libc::EBADF) && (seals < 0 || seals & wanted != wanted) {
7879        return None;
7880    }
7881    // The calling thread's own table: `/proc/self/fd` is the leader's.
7882    let link = std::ffi::CString::new(format!("/proc/thread-self/fd/{fd}")).ok()?;
7883    let mut target = [0_u8; crate::procfs::PLACEHOLDER_LINK_CAPACITY];
7884    // SAFETY: the path is NUL-terminated and `target` is writable.
7885    let length = unsafe {
7886        crate::util::raw_syscall(
7887            libc::SYS_readlinkat,
7888            [
7889                libc::AT_FDCWD as u64,
7890                link.as_ptr() as u64,
7891                target.as_mut_ptr() as u64,
7892                target.len() as u64,
7893                0,
7894                0,
7895            ],
7896        )
7897    };
7898    let length = usize::try_from(length).ok()?.min(target.len());
7899    crate::procfs::placeholder_link(&target[..length], files)
7900}
7901
7902#[cfg(test)]
7903mod native_main_state_tests {
7904    use super::*;
7905    use crate::native_exec::capture_prepared_native_exec;
7906    use crate::native_exec::tests::fixture;
7907    use crate::native_exec::tests::prepare;
7908    use crate::native_exec::tests::state_bytes;
7909    use crate::native_exec::validate_old_native_exec_cut;
7910    fn snapshot(
7911        tool: &crate::Detcore<crate::native_exec::NoopTool>,
7912        thread: &ThreadState<()>,
7913        binding: &crate::native_exec::NativeExecCutBinding,
7914        receipt: &crate::native_exec::NativeExecPreparationReceipt,
7915    ) -> crate::native_exec::DetcoreExecSnapshotV2 {
7916        let bytes = bincode::serde::encode_to_vec(
7917            capture_prepared_native_exec(tool, thread, binding, receipt).unwrap(),
7918            bincode::config::legacy(),
7919        )
7920        .unwrap();
7921        crate::native_exec::tests::decoded(&bytes)
7922    }
7923
7924    #[test]
7925    fn native_main_claimed_sigchld_refuses_live_and_decoded_without_reset() {
7926        let (tool, mut thread, binding) = fixture();
7927        thread.claimed_sigchld = true;
7928        let before = state_bytes(&thread);
7929        assert!(matches!(
7930            validate_old_native_exec_cut(&tool, &thread, &binding),
7931            Err(crate::native_exec::NativeExecCutError::LiveCapability(
7932                "claimed SIGCHLD"
7933            ))
7934        ));
7935        assert_eq!(state_bytes(&thread), before);
7936        thread.claimed_sigchld = false;
7937        let receipt = validate_old_native_exec_cut(&tool, &thread, &binding).unwrap();
7938        prepare(&mut thread, &binding);
7939        let mut payload = snapshot(&tool, &thread, &binding, &receipt);
7940        crate::native_exec::tests::thread_for_test(&mut payload).claimed_sigchld = true;
7941        assert!(matches!(
7942            payload.validate(&binding, &tool.cfg),
7943            Err(crate::native_exec::NativeExecCutError::LiveCapability(
7944                "claimed SIGCHLD"
7945            ))
7946        ));
7947        assert!(crate::native_exec::tests::thread_for_test(&mut payload).claimed_sigchld);
7948    }
7949
7950    fn mark_barrier(process: &mut RobustListProcessState, field: usize, owner: DetTid) {
7951        match field {
7952            0 => {
7953                process.tool_walked.insert(owner);
7954            }
7955            1 => process.exit_group_filed = true,
7956            2 => {
7957                process.exit_group_filers.insert(owner);
7958            }
7959            3 => process.exit_group_walker = Some(owner),
7960            4 => process.exit_group_walked = true,
7961            _ => unreachable!(),
7962        }
7963    }
7964
7965    #[test]
7966    fn native_main_robust_barrier_state_refuses_old_prepared_and_decoded() {
7967        for field in 0..5 {
7968            let (tool, thread, binding) = fixture();
7969            mark_barrier(
7970                &mut thread.robust_list_process.lock().unwrap(),
7971                field,
7972                binding.dettid,
7973            );
7974            let before = state_bytes(&thread);
7975            assert!(
7976                validate_old_native_exec_cut(&tool, &thread, &binding).is_err(),
7977                "old {field}"
7978            );
7979            assert_eq!(state_bytes(&thread), before);
7980
7981            let (tool, mut thread, binding) = fixture();
7982            let receipt = validate_old_native_exec_cut(&tool, &thread, &binding).unwrap();
7983            prepare(&mut thread, &binding);
7984            let mut payload = snapshot(&tool, &thread, &binding, &receipt);
7985            mark_barrier(
7986                &mut thread.robust_list_process.lock().unwrap(),
7987                field,
7988                binding.dettid,
7989            );
7990            let before = state_bytes(&thread);
7991            assert!(
7992                capture_prepared_native_exec(&tool, &thread, &binding, &receipt).is_err(),
7993                "prepared {field}"
7994            );
7995            assert_eq!(state_bytes(&thread), before);
7996            let decoded = crate::native_exec::tests::thread_for_test(&mut payload);
7997            mark_barrier(
7998                &mut decoded.robust_list_process.lock().unwrap(),
7999                field,
8000                binding.dettid,
8001            );
8002            let before = state_bytes(decoded);
8003            assert!(
8004                payload.validate(&binding, &tool.cfg).is_err(),
8005                "decoded {field}"
8006            );
8007            assert_eq!(
8008                state_bytes(crate::native_exec::tests::thread_for_test(&mut payload)),
8009                before
8010            );
8011        }
8012    }
8013
8014    #[test]
8015    fn native_main_nanosleep_restart_refuses_even_when_serde_skips_it() {
8016        for deadline in [None, Some(crate::types::LogicalTime::from_nanos(4567))] {
8017            let (tool, mut thread, binding) = fixture();
8018            let before = state_bytes(&thread);
8019            thread.restart_block = Some(crate::syscalls::helpers::RestartBlock {
8020                rip: 0x1234,
8021                deadline,
8022                call: crate::syscalls::helpers::RestartCall::Nanosleep(
8023                    reverie::syscalls::Nanosleep::new().into(),
8024                ),
8025            });
8026            assert_eq!(state_bytes(&thread), before);
8027            assert!(matches!(
8028                validate_old_native_exec_cut(&tool, &thread, &binding),
8029                Err(crate::native_exec::NativeExecCutError::LiveCapability(
8030                    "restart/projection"
8031                ))
8032            ));
8033            assert!(thread.restart_block.is_some());
8034        }
8035    }
8036
8037    #[test]
8038    fn native_main_rng_promotion_history_survives_snapshot_and_some_empty() {
8039        use std::os::fd::AsRawFd;
8040        crate::fd::install_test_shared_open_file_channel();
8041        {
8042            let (tool, mut thread, binding) = fixture();
8043            let local = std::fs::File::open("/dev/urandom").unwrap();
8044            thread
8045                .add_fd(local.as_raw_fd(), OFlag::O_RDONLY, FdType::Rng, None)
8046                .unwrap();
8047            assert!(thread.shared_open_files_for_exec().unwrap().is_none());
8048            let receipt = validate_old_native_exec_cut(&tool, &thread, &binding).unwrap();
8049            prepare(&mut thread, &binding);
8050            let (_, restored) = snapshot(&tool, &thread, &binding, &receipt)
8051                .into_validated_parts(&binding, &tool.cfg)
8052                .unwrap();
8053            assert!(restored.shared_open_files_for_exec().unwrap().is_none());
8054        }
8055        let (tool, mut thread, binding) = fixture();
8056        let creator = DetTid::from_raw(930001);
8057        thread.set_open_file_creator(creator);
8058        let file = std::fs::File::open("/dev/urandom").unwrap();
8059        let alias = nix::unistd::dup(&file).unwrap();
8060        let cloexec = nix::unistd::dup(&file).unwrap();
8061        let distinct = std::fs::File::open("/dev/urandom").unwrap();
8062        let (fd, alias_fd, cloexec_fd, distinct_fd) = (
8063            file.as_raw_fd(),
8064            alias.as_raw_fd(),
8065            cloexec.as_raw_fd(),
8066            distinct.as_raw_fd(),
8067        );
8068        thread
8069            .add_fd(fd, OFlag::O_RDONLY, FdType::Rng, None)
8070            .unwrap();
8071        thread.dup_fd(fd, alias_fd, OFlag::empty()).unwrap();
8072        thread.dup_fd(fd, cloexec_fd, OFlag::O_CLOEXEC).unwrap();
8073        thread
8074            .add_fd(distinct_fd, OFlag::O_RDONLY, FdType::Rng, None)
8075            .unwrap();
8076        assert!(
8077            thread.shared_open_files_for_exec().unwrap().is_none(),
8078            "local RNG is not promotion"
8079        );
8080        let high = thread
8081            .metadata()
8082            .allocate_open_file_id(creator, FdType::Rng);
8083        let high_socket = thread
8084            .metadata()
8085            .allocate_open_file_id(creator, FdType::Socket);
8086        thread.promote_shared_open_files().unwrap();
8087        let expected = thread.shared_open_files_for_exec().unwrap().unwrap();
8088        assert_eq!(expected.creator, creator);
8089        assert_eq!(expected.handles[&fd].id, expected.handles[&alias_fd].id);
8090        assert_ne!(expected.handles[&fd].id, expected.handles[&distinct_fd].id);
8091        assert!(!expected.handles.contains_key(&cloexec_fd));
8092        let old_table = Arc::clone(&thread.file_metadata);
8093        let receipt = validate_old_native_exec_cut(&tool, &thread, &binding).unwrap();
8094        prepare(&mut thread, &binding);
8095        assert!(
8096            old_table
8097                .lock()
8098                .unwrap()
8099                .file_handles
8100                .contains_key(&cloexec_fd)
8101        );
8102        let (_, restored) = snapshot(&tool, &thread, &binding, &receipt)
8103            .into_validated_parts(&binding, &tool.cfg)
8104            .unwrap();
8105        assert_eq!(
8106            restored.shared_open_files_for_exec().unwrap(),
8107            Some(expected)
8108        );
8109        assert_eq!(restored.open_file_creator, Some(creator));
8110        assert_eq!(
8111            restored.metadata().next_open_file_sequence,
8112            thread.metadata().next_open_file_sequence
8113        );
8114        assert_eq!(
8115            restored.metadata().next_socket_open_file_sequence,
8116            thread.metadata().next_socket_open_file_sequence
8117        );
8118        restored.metadata().file_handles[&alias_fd]
8119            .with_random_device_stream::<Errno>(|offset| {
8120                assert_eq!(offset, 0);
8121                Ok(11)
8122            })
8123            .unwrap();
8124        thread.metadata().file_handles[&fd]
8125            .with_random_device_stream::<Errno>(|offset| {
8126                assert_eq!(offset, 11);
8127                Ok(0)
8128            })
8129            .unwrap();
8130        // Both tables retain the same canonical shared ID, not a copied cursor.
8131        for slot in [fd, alias_fd, distinct_fd] {
8132            thread.remove_fd(slot);
8133        }
8134        let empty = thread.shared_open_files_for_exec().unwrap().unwrap();
8135        assert!(empty.handles.is_empty());
8136        assert_eq!(empty.creator, creator);
8137        assert_ne!(OpenFileId::new(creator, empty.next_sequence), high);
8138        assert_ne!(
8139            OpenFileId::new_socket(creator, empty.next_socket_sequence),
8140            high_socket
8141        );
8142        // Drop the test-owned metadata guard before the validator probes it.
8143        let old_files = thread.metadata().files_id;
8144        let binding2 = crate::native_exec::NativeExecCutBinding {
8145            old_mm: thread.mm_id,
8146            old_files,
8147            ..binding
8148        };
8149        let receipt2 = validate_old_native_exec_cut(&tool, &thread, &binding2).unwrap();
8150        prepare(&mut thread, &binding2);
8151        let (_, again) = snapshot(&tool, &thread, &binding2, &receipt2)
8152            .into_validated_parts(&binding2, &tool.cfg)
8153            .unwrap();
8154        assert_eq!(again.shared_open_files_for_exec().unwrap(), Some(empty));
8155    }
8156}