air_sys_types/

signal.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Signal Linux et types associés.
//!
//! Couvre la famille `signal` de la couche 0 (cf.
//! `docs/specs/layer-0/family-signal.md`). Périmètre :
//!
//! - Constantes [`Signal`] : 10 / ~31 signaux POSIX standards
//!   référencés par le code et les tests Air. **Reste stub partiel** —
//!   les ~21 restants (et les RT signals 32-64) seront ajoutés au fil
//!   des PRs qui les utiliseront. Le type [`Signal`] **borne**
//!   structurellement ses valeurs à `[1, 64]` (= `_NSIG` Linux) via
//!   [`Signal::try_from_raw`] : aucun signal hors de cette plage ne
//!   peut être construit publiquement.
//! - [`SignalInfo`] : payload `siginfo_t` opaque (128 octets) construit
//!   via des constructeurs Air (`new_queue`) pour le pattern SI_QUEUE
//!   utilisé par `rt_sigqueueinfo` et acceptable pour `pidfd_send_signal`.
//! - [`SignalValue`] : valeur associée à un signal-envoyé (`Integer(i32)`
//!   ou `Pointer(u64)`).
//! - [`SignalMask`] : ensemble de signaux comme bitmask `u64`.
//! - [`SignalFdInfo`] : structure retournée par la lecture d'un
//!   `signalfd`.
//! - [`SignalFdFlags`] : drapeaux de `signalfd4`.
//! - Sous-module [`synchronous_handler`] : `FatalSignal`, `SignalInfo`,
//!   `PreviousHandler` (cf. ADR-020 sigaction restreint).

use core::num::NonZeroI32;

use bitflags::bitflags;

use crate::process::Pid;

// ─────────────────────────────────────────────────────────────────────────
// Signal — newtype + constantes (stub partiel 10/~31).
// ─────────────────────────────────────────────────────────────────────────

/// Nombre maximum de signaux Linux (`_NSIG` dans `asm-generic/signal.h`).
///
/// Signal 1 = `SIGHUP`, signal 64 = `SIGRTMAX`. Aucun signal légitime au
/// dessus. Toute construction publique de [`Signal`] avec une valeur
/// hors `[1, 64]` est refusée à la borne — voir [`Signal::try_from_raw`].
const NSIG: i32 = 64;

/// Numéro de signal Unix/Linux.
///
/// Toujours dans `[1, 64]` par construction : le signal 0 n'existe pas
/// (sentinelle « pas de signal » exprimée par `Option<Signal>` cf.
/// convention 1 ADR-021), et Linux n'admet aucun signal > 64
/// (`_NSIG = 64`). La borne est validée à la construction
/// ([`Self::try_from_raw`]) — pas de runtime check ailleurs.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Signal(NonZeroI32);

impl Signal {
    /// `SIGHUP` — Hangup (1) : la fin d'un terminal de contrôle. Envoyé au shell de
    /// login d'`air-sshd` quand le client ferme le canal interactif (E.3).
    pub const SIGHUP: Self = Self(unwrap_nz(1));

    /// `SIGILL` — Illegal instruction (4).
    ///
    /// Référencé par cette PR : `FatalSignal::Ill` (sous-module
    /// `synchronous_handler`), tests d'install_fatal_handler.
    pub const SIGILL: Self = Self(unwrap_nz(4));

    /// `SIGTRAP` — Trace/breakpoint trap (5).
    pub const SIGTRAP: Self = Self(unwrap_nz(5));

    /// `SIGABRT` — Abort (6).
    pub const SIGABRT: Self = Self(unwrap_nz(6));

    /// `SIGBUS` — Bus error (7).
    ///
    /// Référencé par cette PR : `FatalSignal::Bus`.
    pub const SIGBUS: Self = Self(unwrap_nz(7));

    /// `SIGFPE` — Floating-point exception (8).
    ///
    /// Référencé par cette PR : `FatalSignal::Fpe`.
    pub const SIGFPE: Self = Self(unwrap_nz(8));

    /// `SIGKILL` — Kill (cannot be caught or ignored, 9).
    pub const SIGKILL: Self = Self(unwrap_nz(9));

    /// `SIGUSR1` — User-defined signal 1 (10, x86_64/aarch64).
    ///
    /// Référencé par cette PR : signal canonique pour les tests
    /// signalfd / block / tgkill / rt_sigqueueinfo.
    pub const SIGUSR1: Self = Self(unwrap_nz(10));

    /// `SIGPIPE` — Écriture sur un tube ou une socket dont le lecteur est parti (13).
    ///
    /// **Le PAL de la `std` `linux-air` le pose à `SIG_IGN` au démarrage**, comme le fait le
    /// PAL `unix` de l'amont — sans quoi tout binaire Air meurt sur signal 13 là où un
    /// programme Rust reçoit `Err(EPIPE)` et peut le traiter.
    ///
    /// Son absence de cette liste était l'anomalie : onze signaux y figuraient, et celui qui
    /// décide du sort de toute écriture sur un pair disparu n'y était pas.
    pub const SIGPIPE: Self = Self(unwrap_nz(13));

    /// `SIGSEGV` — Segmentation fault (11).
    ///
    /// Référencé par cette PR : `FatalSignal::Segv`.
    pub const SIGSEGV: Self = Self(unwrap_nz(11));

    /// `SIGCHLD` — Child status changed (17, x86_64/aarch64).
    pub const SIGCHLD: Self = Self(unwrap_nz(17));

    /// `SIGSTOP` — Stop process (cannot be caught or ignored, 19,
    /// x86_64/aarch64).
    pub const SIGSTOP: Self = Self(unwrap_nz(19));

    /// Tente de construire un `Signal` à partir d'un entier brut.
    ///
    /// **Borné à `[1, NSIG]` (= `[1, 64]` sur Linux).** `NSIG = 64` est
    /// le nombre maximum de signaux Unix POSIX standard + temps-réel
    /// supportés par Linux (cf. `_NSIG` dans `asm-generic/signal.h`).
    ///
    /// Retourne `None` si `raw <= 0` ou `raw > 64`. Aucune valeur hors
    /// de cette plage ne peut désigner un signal Linux valide ; les
    /// rejeter à la construction transforme l'invariant en garantie de
    /// type (Principe 4 — validation amont), plutôt qu'en `EINVAL`
    /// kernel observé au runtime sur `kill`/`tgkill`/etc.
    #[must_use]
    #[inline]
    pub const fn try_from_raw(raw: i32) -> Option<Self> {
        match NonZeroI32::new(raw) {
            Some(nz) if nz.get() > 0 && nz.get() <= NSIG => Some(Self(nz)),
            _ => None,
        }
    }

    /// Retourne la représentation brute (positive) du numéro de signal.
    #[must_use]
    #[inline]
    pub const fn as_raw(self) -> i32 {
        self.0.get()
    }
}

/// Helper const : construit un `NonZeroI32` dans la plage `[1, NSIG]`
/// depuis un littéral. Panique au compile-time si l'invariant est
/// violé — défense en profondeur pour que tout ajout futur de constante
/// `Signal::SIGXXX` avec une valeur hors plage soit rejeté à la
/// compilation, en plus de la borne runtime de [`Signal::try_from_raw`].
const fn unwrap_nz(n: i32) -> NonZeroI32 {
    if n <= 0 || n > NSIG {
        panic!("Signal constants must be in [1, 64]");
    }
    match NonZeroI32::new(n) {
        Some(v) => v,
        // Inatteignable : la garde au-dessus exige `n > 0`. Présent
        // pour satisfaire le contrôle exhaustif const.
        None => panic!("unreachable: n > 0 guaranteed by the check above"),
    }
}

// ─────────────────────────────────────────────────────────────────────────
// SignalValue — valeur attachée à un signal envoyé via SI_QUEUE.
// ─────────────────────────────────────────────────────────────────────────

/// Valeur attachée à un signal envoyé via le pattern SI_QUEUE
/// (`rt_sigqueueinfo`, ou `pidfd_send_signal` avec `info` non-null).
///
/// Côté kernel `siginfo_t`, c'est l'union `sigval_t { int si_int;
/// void *si_ptr; }` — discrimination via `si_code` (mais ici la
/// discrimination est portée par la variante Rust).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SignalValue {
    /// Variante `si_int`.
    Integer(i32),
    /// Variante `si_ptr`.
    Pointer(u64),
}

// ─────────────────────────────────────────────────────────────────────────
// SignalInfo — payload siginfo_t opaque.
// ─────────────────────────────────────────────────────────────────────────

// Constantes `si_code` extraites de `include/uapi/asm-generic/siginfo.h`.
// Identiques x86_64 / aarch64.
const SI_QUEUE: i32 = -1;

// Offsets dans la struct `siginfo_t` Linux générique (vérifiés sur
// `arch/x86/include/uapi/asm/siginfo.h` et `asm-generic/siginfo.h`).
//
// Layout des 16 premiers octets (toutes archs supportées) :
//   offset  0 : si_signo (i32)
//   offset  4 : si_errno (i32)
//   offset  8 : si_code (i32)
//   offset 12 : padding (4 octets, requis sur 64-bit pour aligner l'union)
//
// La variante union `_sigqueue` commence à l'offset 16 :
//   offset 16 : si_pid (i32)
//   offset 20 : si_uid (u32)
//   offset 24 : sigval_t (union { si_int, si_ptr }) — 8 octets
//
// La variante union `_sigchld` partage le début (si_pid, si_uid) mais
// utilise les octets suivants pour si_status / si_utime / si_stime.
const SIGINFO_OFFSET_SI_CODE: usize = 8;
const SIGINFO_OFFSET_SI_VALUE: usize = 24;
const SIGINFO_SIZE: usize = 128;

/// Payload `siginfo_t` opaque associé à un syscall d'envoi de signal
/// (`pidfd_send_signal`, `rt_sigqueueinfo`).
///
/// **Représentation interne.** Buffer brut de 128 octets, alignement 4,
/// layout `siginfo_t` Linux côté x86_64 et aarch64 (identique sur ces
/// deux architectures). Opaque côté API publique : on n'expose pas les
/// champs individuels — le kernel valide ses propres invariants
/// (notamment `si_code`) et un usage à champs ouverts serait un footgun
/// de sécurité (cf. la note dans `kernel/signal.c::do_rt_sigqueueinfo` :
/// « Not even root can pretend to send signals from the kernel »).
///
/// **Construction.** Pas de champ public. Seuls des constructeurs Air
/// disciplinés ([`Self::new_queue`]) fabriquent des `SignalInfo`
/// dont le kernel accepte le `si_code`. Cela ferme la dette d'ambiguïté
/// avec `SignalQueueInfo` consignée à la PR pidfd_* (le type
/// `SignalQueueInfo` a été retiré ; le concept est porté par
/// [`Self::new_queue`]).
#[repr(C)]
#[derive(Debug)]
pub struct SignalInfo {
    raw: [u8; SIGINFO_SIZE],
}

impl SignalInfo {
    /// Construit un `SignalInfo` pour le pattern **SI_QUEUE**
    /// (`rt_sigqueueinfo`, équivalent userspace de `sigqueue(3)`).
    ///
    /// Le `si_code` est fixé à `SI_QUEUE` (-1), seule valeur que le
    /// kernel accepte pour un envoi cross-process userspace
    /// (cf. `do_rt_sigqueueinfo` dans `kernel/signal.c`). Les champs
    /// `si_signo`, `si_pid`, `si_uid` sont laissés à zéro — le kernel
    /// les **écrase** avec les valeurs correctes au moment de la
    /// délivrance (`sig` du syscall, `pid`/`uid` de l'appelant).
    ///
    /// Le champ `si_value` (offset 24, 8 octets) reçoit la valeur
    /// fournie : variante `Integer(i32)` écrit les 4 premiers octets,
    /// variante `Pointer(u64)` écrit les 8 octets.
    #[must_use]
    pub fn new_queue(value: SignalValue) -> Self {
        let mut raw = [0_u8; SIGINFO_SIZE];
        // si_code = SI_QUEUE à l'offset 8.
        raw[SIGINFO_OFFSET_SI_CODE..SIGINFO_OFFSET_SI_CODE.saturating_add(4)]
            .copy_from_slice(&SI_QUEUE.to_ne_bytes());
        match value {
            SignalValue::Integer(i) => {
                raw[SIGINFO_OFFSET_SI_VALUE..SIGINFO_OFFSET_SI_VALUE.saturating_add(4)]
                    .copy_from_slice(&i.to_ne_bytes());
            }
            SignalValue::Pointer(p) => {
                raw[SIGINFO_OFFSET_SI_VALUE..SIGINFO_OFFSET_SI_VALUE.saturating_add(8)]
                    .copy_from_slice(&p.to_ne_bytes());
            }
        }
        Self { raw }
    }

    /// Accès lecture seule à la représentation brute, **uniquement** pour
    /// les wrappers de syscalls qui doivent passer un pointeur au kernel.
    /// Pas destiné à l'inspection des champs côté utilisateur (les
    /// constructeurs Air fixent les champs corrects ; le kernel les
    /// écrase à la délivrance).
    #[doc(hidden)]
    #[must_use]
    #[inline]
    pub fn as_bytes(&self) -> &[u8; SIGINFO_SIZE] {
        &self.raw
    }

    /// `siginfo_t` **zéro-initialisé** — tampon de sortie destiné à être
    /// **rempli par le kernel** (ex. `IORING_OP_WAITID`, où le kernel y écrit
    /// l'état du processus). Lire ensuite via [`Self::as_bytes`].
    #[must_use]
    #[inline]
    pub const fn zeroed() -> Self {
        Self {
            raw: [0_u8; SIGINFO_SIZE],
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────
// AltStack — pile de signal alternative (`stack_t`).
// ─────────────────────────────────────────────────────────────────────────

/// Pile de signal **alternative** (`stack_t` du kernel) — descellement additif ADR-085
/// pour la face libc `sigaltstack`. Disposition `#[repr(C)]` **exacte** de `stack_t`
/// (LP64 : `void *ss_sp` @0, `int ss_flags` @8, `size_t ss_size` @16 ; 24 octets), pour
/// être passée telle quelle au syscall.
///
/// Une pile alternative permet à un gestionnaire de signal de s'exécuter sur une pile
/// **dédiée** (indispensable pour traiter un `SIGSEGV` de **débordement de pile** — c'est
/// l'usage de `std`).
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct AltStack {
    /// `ss_sp` — base de la pile alternative (ignoré si `SS_DISABLE`).
    stack_pointer: *mut u8,
    /// `ss_flags` — `SS_DISABLE`/`SS_ONSTACK`/`SS_AUTODISARM`.
    flags: i32,
    /// `ss_size` — taille en octets de la pile alternative.
    size: usize,
}

/// `SS_ONSTACK` (1) — le thread s'exécute **actuellement** sur la pile alternative
/// (lecture seule, rendu par la requête).
pub const SS_ONSTACK: i32 = 1;
/// `SS_DISABLE` (2) — désactive la pile alternative.
pub const SS_DISABLE: i32 = 2;

impl AltStack {
    /// Construit une pile alternative **active** de base `stack_pointer` et `size` octets.
    #[must_use]
    pub fn new(stack_pointer: *mut u8, size: usize) -> Self {
        Self {
            stack_pointer,
            flags: 0,
            size,
        }
    }

    /// Construit une pile **désactivée** (`SS_DISABLE`) — pour retirer une pile alternative.
    #[must_use]
    pub fn disabled() -> Self {
        Self {
            stack_pointer: core::ptr::null_mut(),
            flags: SS_DISABLE,
            size: 0,
        }
    }

    /// Base de la pile alternative (`ss_sp`).
    #[must_use]
    pub fn stack_pointer(&self) -> *mut u8 {
        self.stack_pointer
    }

    /// Taille de la pile alternative (`ss_size`).
    #[must_use]
    pub fn size(&self) -> usize {
        self.size
    }

    /// Drapeaux bruts (`ss_flags`).
    #[must_use]
    pub fn flags(&self) -> i32 {
        self.flags
    }

    /// `true` si la pile est **désactivée** (`SS_DISABLE`).
    #[must_use]
    pub fn is_disabled(&self) -> bool {
        self.flags & SS_DISABLE != 0
    }

    /// `true` si le thread s'exécute **actuellement** sur la pile alternative
    /// (`SS_ONSTACK`) — pertinent sur la valeur **rendue** par une requête.
    #[must_use]
    pub fn is_on_stack(&self) -> bool {
        self.flags & SS_ONSTACK != 0
    }
}

// ─────────────────────────────────────────────────────────────────────────
// SignalMask — bitmask u64 (signaux 1-64).
// ─────────────────────────────────────────────────────────────────────────

/// Ensemble de signaux représenté comme bitmask `u64`.
///
/// Le bit `N` du mask correspond au signal `N + 1` (convention Linux
/// `sigset_t` : signal 1 = bit 0, signal 64 = bit 63). Les signaux
/// au-delà de 64 (RT signals étendus, rares) ne sont pas représentables
/// par ce stub — ils seront supportés via une représentation plus large
/// si nécessaire dans une PR ultérieure.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct SignalMask(u64);

impl SignalMask {
    /// Masque vide (aucun signal).
    #[must_use]
    #[inline]
    pub const fn empty() -> Self {
        Self(0)
    }

    /// Construit depuis sa représentation brute.
    #[must_use]
    #[inline]
    pub const fn from_bits(bits: u64) -> Self {
        Self(bits)
    }

    /// Représentation brute (bits 0-63 = signaux 1-64).
    #[must_use]
    #[inline]
    pub const fn bits(self) -> u64 {
        self.0
    }

    /// Construit un mask à partir d'une liste de signaux. Les signaux
    /// au-delà de 64 (rares) sont silencieusement ignorés.
    #[must_use]
    pub fn from_signals(signals: &[Signal]) -> Self {
        let mut bits = 0_u64;
        for sig in signals {
            // signal N → bit N-1 ; signal positif par construction.
            let bit_index = u32::try_from(sig.as_raw())
                .expect("Signal positive")
                .saturating_sub(1);
            // COVERAGE-UNREACHABLE: le `None` de `checked_shl` demanderait `bit_index >= 64`,
            // donc un signal hors de [1, 64] — que `Signal::try_from_raw` refuse déjà à la
            // construction. La branche est structurellement inatteignable ; elle est
            // conservée comme garde no-op au titre du Principe 2 (jamais l'opération nue),
            // et pour qu'un futur constructeur de `Signal` plus permissif ne devienne pas
            // un débordement silencieux. Elle tombera le jour où ce constructeur existera.
            if let Some(bit) = 1_u64.checked_shl(bit_index) {
                bits |= bit;
            }
        }
        Self(bits)
    }

    /// Indique si `sig` est dans le mask.
    ///
    /// **Défense en profondeur.** Le type `Signal` borne déjà ses valeurs
    /// à `[1, 64]` (cf. [`Signal::try_from_raw`]), donc `bit_index < 64`
    /// par construction et la branche `None` de `checked_shl` est
    /// structurellement inatteignable. Elle est conservée comme garde
    /// no-op (retourne `false`) au cas où un futur constructeur de
    /// `Signal` oublierait d'appliquer la borne — Principe 5 :
    /// sur-sécuriser, ne jamais corrompre.
    #[must_use]
    pub fn contains(self, sig: Signal) -> bool {
        let bit_index = u32::try_from(sig.as_raw())
            .expect("Signal positive")
            .saturating_sub(1);
        match 1_u64.checked_shl(bit_index) {
            Some(bit) => (self.0 & bit) != 0,
            None => false,
        }
    }

    /// Retourne un nouveau mask avec `sig` ajouté.
    ///
    /// Même garde no-op défensive que [`Self::contains`] : si jamais
    /// `bit_index >= 64`, retourne le mask inchangé (sans paniquer ni
    /// corrompre l'état).
    #[must_use]
    pub fn with(self, sig: Signal) -> Self {
        let bit_index = u32::try_from(sig.as_raw())
            .expect("Signal positive")
            .saturating_sub(1);
        match 1_u64.checked_shl(bit_index) {
            Some(bit) => Self(self.0 | bit),
            None => self,
        }
    }

    /// Retourne un nouveau mask avec `sig` retiré.
    ///
    /// Même garde no-op défensive que [`Self::contains`].
    #[must_use]
    pub fn without(self, sig: Signal) -> Self {
        let bit_index = u32::try_from(sig.as_raw())
            .expect("Signal positive")
            .saturating_sub(1);
        match 1_u64.checked_shl(bit_index) {
            Some(bit) => Self(self.0 & !bit),
            None => self,
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────
// SignalFdFlags + SignalFdInfo.
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Drapeaux pour [`signalfd_create`] (`signalfd4(2)`).
    ///
    /// **Note.** Le wrapper Air ajoute toujours `CLOEXEC` (cf.
    /// `family-signal.md` : « Tous les FDs créés sont CLOEXEC par
    /// défaut »). Les autres bits sont à la discrétion de l'appelant.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct SignalFdFlags: i32 {
        /// `SFD_NONBLOCK` : le FD est créé en mode non-bloquant.
        const NONBLOCK = 0o4000;
        /// `SFD_CLOEXEC` : automatiquement fermé à `execve`.
        const CLOEXEC = 0o2_000_000;
    }
}

/// Information lue depuis un `signalfd` (un `signalfd_siginfo`).
///
/// Layout C parsé par le wrapper depuis le buffer kernel ; les champs
/// non-pertinents pour le signal reçu sont à 0/None côté kernel.
#[derive(Debug, Clone, Copy)]
pub struct SignalFdInfo {
    /// Signal reçu.
    pub signal: Signal,
    /// `si_errno` (rarement utilisé).
    pub errno: i32,
    /// `si_code` (origine du signal : SI_USER, SI_KERNEL, CLD_EXITED, …).
    pub code: i32,
    /// `si_pid` : PID expéditeur. `None` si l'origine est le kernel (0).
    pub pid: Option<Pid>,
    /// `si_uid` : UID expéditeur.
    pub uid: u32,
    /// `ssi_fd` : FD source pour les signaux liés à un I/O (`SIGIO`).
    pub fd: i32,
    /// `ssi_tid` : ID du timer (spec Air : `timer_id`).
    pub timer_id: u32,
    /// `ssi_band` : pour `SIGIO`.
    pub band: u32,
    /// `ssi_overrun` : nombre d'overruns timer.
    pub overrun: u32,
    /// `ssi_trapno` : pour `SIGTRAP`.
    pub trap_no: u32,
    /// `ssi_status` : pour `SIGCHLD` (code de sortie ou signal fatal).
    pub status: i32,
    /// `ssi_int` : entier attaché pour SI_QUEUE-style.
    pub int: i32,
    /// `ssi_ptr` : pointeur attaché pour SI_QUEUE-style.
    pub ptr: u64,
    /// `ssi_utime` : pour `SIGCHLD`.
    pub utime: u64,
    /// `ssi_stime` : pour `SIGCHLD`.
    pub stime: u64,
    /// `ssi_addr` : pour `SIGSEGV`/`SIGBUS`/`SIGFPE`/`SIGILL`.
    pub addr: u64,
}

// ─────────────────────────────────────────────────────────────────────────
// Sous-module synchronous_handler (cf. ADR-020).
// ─────────────────────────────────────────────────────────────────────────

/// Sous-module restreint aux 4 signaux synchrones fatals
/// (cf. ADR-020). Les seuls types et fonctions Air permettant
/// d'installer un handler `sigaction` vivent ici ; la barrière est par
/// construction.
pub mod synchronous_handler {
    use super::Signal;

    /// Les quatre signaux synchrones fatals couverts par l'ADR-020.
    /// L'enum est restreint à ces 4 variantes ; aucune API Air n'expose
    /// d'autre signal pour `sigaction`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
    pub enum FatalSignal {
        /// `SIGSEGV` — segmentation fault.
        Segv,
        /// `SIGBUS` — bus error.
        Bus,
        /// `SIGFPE` — floating-point exception.
        Fpe,
        /// `SIGILL` — illegal instruction.
        Ill,
    }

    impl FatalSignal {
        /// Convertit en [`Signal`] correspondant.
        #[must_use]
        pub const fn as_signal(self) -> Signal {
            match self {
                Self::Segv => Signal::SIGSEGV,
                Self::Bus => Signal::SIGBUS,
                Self::Fpe => Signal::SIGFPE,
                Self::Ill => Signal::SIGILL,
            }
        }
    }

    /// `siginfo_t` parsé pour un handler fatal. **Layout C** miroir du
    /// `siginfo_t` Linux côté receiver — différent de
    /// [`super::SignalInfo`] qui est le builder côté sender.
    ///
    /// Champs exposés : les plus utiles à un crash reporter. Le reste
    /// du `siginfo_t` est dans `_padding`.
    #[repr(C)]
    pub struct SignalInfo {
        /// `si_signo` : signal reçu (devrait correspondre à
        /// [`FatalSignal::as_signal`] sur le handler installé).
        pub signal: core::ffi::c_int,
        /// `si_errno`.
        pub errno: core::ffi::c_int,
        /// `si_code` : type de fault (SEGV_MAPERR, SEGV_ACCERR, …).
        pub code: core::ffi::c_int,
        /// Padding à l'alignement union (4 octets sur 64-bit).
        pub _pad0: u32,
        /// `si_addr` : adresse mémoire fautive (pour SIGSEGV/SIGBUS).
        pub addr: u64,
        /// Reste de la struct (~104 octets restants pour atteindre 128).
        pub _trailing: [u8; 104],
    }

    /// Handler installé via `install_fatal_handler`
    /// (`air-sys-syscall::signal::synchronous_handler`). **Contrainte
    /// async-signal-safe** : le handler ne doit appeler que des fonctions
    /// listées dans `man 7 signal-safety` (typiquement `write`,
    /// `_exit`, opérations sur des `core::sync::atomic`).
    pub type FatalHandler = unsafe extern "C" fn(
        signum: core::ffi::c_int,
        info: *mut SignalInfo,
        context: *mut core::ffi::c_void,
    );

    /// Handler précédemment installé sur un `FatalSignal`, à passer à
    /// [`restore_handler`](crate::process::Pid) (dans
    /// `air-sys-syscall`). Représentation opaque : contient
    /// l'ancien `struct sigaction` kernel.
    #[repr(C)]
    pub struct PreviousHandler {
        /// Buffer brut du `struct sigaction` kernel précédent.
        /// Taille fixée à 32 octets — borne supérieure pour x86_64
        /// (32 octets) et aarch64 (24 octets, padded à 32 pour
        /// uniformité de représentation).
        pub(crate) raw: [u8; 32],
    }

    impl PreviousHandler {
        #[doc(hidden)]
        #[must_use]
        pub fn zeroed() -> Self {
            Self { raw: [0_u8; 32] }
        }

        #[doc(hidden)]
        #[must_use]
        pub fn as_bytes(&self) -> &[u8; 32] {
            &self.raw
        }

        #[doc(hidden)]
        pub fn as_bytes_mut(&mut self) -> &mut [u8; 32] {
            &mut self.raw
        }
    }

    /// Vérifications à la compilation des invariants ABI.
    const _: () = {
        assert!(core::mem::size_of::<SignalInfo>() == 128);
        assert!(core::mem::size_of::<PreviousHandler>() == 32);
    };
}

// ─────────────────────────────────────────────────────────────────────────
// Sous-module async_handler (cf. ADR-066) — types du descellement additif
// « rt_sigaction non-faute ».
// ─────────────────────────────────────────────────────────────────────────

/// Types du **handler asynchrone** des signaux **non-faute** (ADR-066).
///
/// Contrairement à [`synchronous_handler`] (restreint aux 4 fautes, ADR-020) qui
/// installe un handler **inerte** (le noyau force l'action par défaut sur les
/// fautes), ce sous-module décrit les attributs d'un `rt_sigaction` **réellement
/// installé** : le noyau détourne le thread vers le handler C à la délivrance
/// d'un signal **gérable** (`SIGINT`/`SIGTERM`/`SIGCHLD`/`SIGWINCH`/`SIGUSR1-2`/
/// temps-réel…). C'est la **fondation dual-face** : la libc C-ABI y bâtit
/// `sigaction`/`signal`, le PAL Rust y bâtit ses handlers.
///
/// Les **fonctions** qui consomment ces types (`install`/`restore`) vivent en
/// couche 0 dans `air-sys-syscall::signal::async_handler` — même partage
/// types/wrappers que `synchronous_handler`.
pub mod async_handler {
    use bitflags::bitflags;

    bitflags! {
        /// Drapeaux `sa_flags` d'un `rt_sigaction` (identiques x86_64/aarch64,
        /// `asm-generic`).
        ///
        /// **Exposés** : les drapeaux utiles à un handler applicatif. Le drapeau
        /// interne `SA_RESTORER` (`0x0400_0000`) n'apparaît **pas** ici : il est
        /// posé par le wrapper couche 0 sur x86_64 (trampoline `rt_sigreturn`
        /// fourni par Air) et n'a **pas** de sens sur aarch64 (retour via VDSO).
        /// C'est un attribut **typé** (ADR-021 §3), jamais un entier magique côté
        /// appelant.
        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
        pub struct SigActionFlags: u64 {
            /// `SA_NOCLDSTOP` : pas de `SIGCHLD` quand un enfant s'arrête/reprend.
            const NOCLDSTOP = 0x0000_0001;
            /// `SA_NOCLDWAIT` : les enfants ne deviennent pas zombies (`SIGCHLD`).
            const NOCLDWAIT = 0x0000_0002;
            /// `SA_SIGINFO` : handler à 3 arguments (`siginfo_t`/contexte).
            const SIGINFO = 0x0000_0004;
            /// `SA_ONSTACK` : exécute le handler sur la pile alternative
            /// (`sigaltstack`).
            const ONSTACK = 0x0800_0000;
            /// `SA_RESTART` : redémarre certains syscalls interrompus. **Air ne
            /// le force jamais** (ADR-021 conv.2 / ADR-064 §4) — mais un appelant
            /// C peut le demander explicitement.
            const RESTART = 0x1000_0000;
            /// `SA_NODEFER` : ne bloque pas le signal courant pendant le handler.
            const NODEFER = 0x4000_0000;
            /// `SA_RESETHAND` : restaure `SIG_DFL` après une première délivrance.
            const RESETHAND = 0x8000_0000;
        }
    }

    /// Disposition **précédente** d'un signal, capturée par `install` et rendue à
    /// `restore` (ADR-066). Représentation **opaque** : contient l'ancien
    /// `struct sigaction` kernel (borne 32 octets — x86_64 = 32, aarch64 = 24
    /// paddé à 32), même buffer que
    /// [`synchronous_handler::PreviousHandler`](super::synchronous_handler::PreviousHandler)
    /// mais **type distinct** pour garder étanches les deux faces (faute vs
    /// non-faute).
    #[repr(C)]
    #[derive(Debug)]
    pub struct PreviousDisposition {
        /// Buffer brut du `struct sigaction` kernel précédent.
        pub(crate) raw: [u8; 32],
    }

    impl PreviousDisposition {
        /// Buffer **zéro-initialisé** — tampon de sortie rempli par le kernel
        /// (`oldact` de `rt_sigaction`).
        #[doc(hidden)]
        #[must_use]
        pub fn zeroed() -> Self {
            Self { raw: [0_u8; 32] }
        }

        /// Vue lecture seule du buffer (pour le wrapper couche 0 qui le repasse au
        /// kernel lors du `restore`).
        #[doc(hidden)]
        #[must_use]
        pub fn as_bytes(&self) -> &[u8; 32] {
            &self.raw
        }

        /// Vue mutable du buffer (rempli par le kernel lors de l'`install`).
        #[doc(hidden)]
        pub fn as_bytes_mut(&mut self) -> &mut [u8; 32] {
            &mut self.raw
        }
    }

    /// Invariant ABI : la disposition précédente tient dans 32 octets.
    const _: () = {
        assert!(core::mem::size_of::<PreviousDisposition>() == 32);
    };
}

#[cfg(test)]
mod tests;