air_sys_syscall/

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/.

//! Wrappers de la famille `signal`.
//!
//! Cf. `docs/specs/layer-0/family-signal.md` et `ADR-020-strategie-signaux`.
//!
//! Périmètre :
//! - Sous-section 1 (signalfd + masques) : [`signalfd_create`],
//!   [`signalfd_create_blocking`], [`SignalFd::read`],
//!   [`SignalFd::update_mask`], [`block_signals`], [`unblock_signals`],
//!   [`set_signal_mask`], [`current_signal_mask`], [`wait_for_signal`].
//! - Sous-section 2 (envoi) : [`kill`], [`tgkill`], [`rt_sigqueueinfo`].
//! - Sous-section 3 (sigaction restreint FAUTES) : sous-module
//!   [`synchronous_handler`] avec [`synchronous_handler::install_fatal_handler`]
//!   et [`synchronous_handler::restore_handler`] (handler **inerte** ; le noyau
//!   force l'action par défaut sur les 4 fautes, ADR-020).
//! - Sous-section 4 (sigaction async NON-faute, ADR-066) : sous-module
//!   [`async_handler`] avec [`async_handler::install`]/[`async_handler::restore`]
//!   (handler **réellement installé** — le noyau appelle le handler C à la
//!   délivrance d'un signal gérable ; trampoline `rt_sigreturn` fourni sur
//!   x86_64), et [`rt_sigpending`] (ensemble des signaux pendants).

use air_sys_types::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
use core::num::NonZeroI32;
use core::time::Duration;

use air_sys_types::{
    AltStack, Errno, Pid, Signal, SignalFdFlags, SignalFdInfo, SignalInfo, SignalMask, Tid,
};

#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
compile_error!("air-sys-syscall::signal supporte uniquement x86_64 et aarch64 (ADR-014).");

// ─────────────────────────────────────────────────────────────────────────
// SignalFd — wrapper RAII opaque autour d'un signalfd kernel.
// ─────────────────────────────────────────────────────────────────────────

/// FD `signalfd` (cf. `signalfd4(2)`). Drop ferme le FD via [`OwnedFd`].
#[derive(Debug)]
pub struct SignalFd(OwnedFd);

impl SignalFd {
    /// Construit depuis un `OwnedFd` déjà ouvert sur un signalfd.
    #[must_use]
    #[inline]
    pub const fn from_owned_fd(fd: OwnedFd) -> Self {
        Self(fd)
    }

    /// Vue empruntée du FD sous-jacent.
    #[must_use]
    pub fn as_fd(&self) -> BorrowedFd<'_> {
        use air_sys_types::fd::AsFd;
        self.0.as_fd()
    }

    /// Consomme et restitue le `OwnedFd`.
    #[must_use]
    pub fn into_fd(self) -> OwnedFd {
        self.0
    }

    /// Lit le prochain événement signal disponible sur le `signalfd`.
    ///
    /// Bloque si le FD est en mode bloquant (par défaut) et qu'aucun
    /// signal n'est pendant ; retourne immédiatement avec
    /// [`Errno::EAGAIN`] si le FD est en mode `NONBLOCK` et aucun
    /// signal n'est disponible.
    ///
    /// # Errors
    ///
    /// - [`Errno::EAGAIN`] : mode non-bloquant, aucun signal pendant.
    /// - [`Errno::EINTR`] : interrompu par un signal (remonté tel quel
    ///   per convention 2 ADR-021).
    pub fn read(&self) -> Result<SignalFdInfo, Errno> {
        let mut buffer = [0_u8; SIGNALFD_SIGINFO_SIZE];
        let ptr: *mut u8 = buffer.as_mut_ptr();
        let length = u64::try_from(SIGNALFD_SIGINFO_SIZE)
            .expect("buffer fixe SIGNALFD_SIGINFO_SIZE tient en u64");
        // SAFETY:
        // - SYS_read sur un signalfd valide écrit exactement 128 octets
        //   dans `buffer` (taille du `signalfd_siginfo`) ou retourne une
        //   erreur. `buffer` est local valide pour la durée du syscall.
        let ret = unsafe { raw_syscall_read(self.0.as_raw_fd(), ptr as u64, length) };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        // Lecture partielle d'un signalfd impossible (atomique côté kernel) ;
        // ret == 128 ou erreur.
        debug_assert_eq!(ret, i64::from(SIGNALFD_SIGINFO_SIZE_I32));
        Ok(parse_signalfd_siginfo(&buffer))
    }

    /// Met à jour le mask de signaux capturés par ce `signalfd`.
    ///
    /// Équivalent à un nouvel appel `signalfd4(self, &mask, ...)` qui
    /// remplace atomiquement le mask interne du FD.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINVAL`] : mask invalide.
    pub fn update_mask(&mut self, mask: &SignalMask) -> Result<(), Errno> {
        let bits = mask.bits();
        let mask_ptr: *const u64 = &bits;
        // SAFETY: signalfd4(fd_existant, &mask, sizeof(u64), 0). Le
        // kernel lit 8 octets à mask_ptr (sigset_t kernel = 1 mot sur
        // archs où _NSIG = 64). Flags=0 préserve les flags existants
        // (NONBLOCK/CLOEXEC) du FD.
        let ret = unsafe {
            raw_syscall_signalfd4(self.0.as_raw_fd(), mask_ptr as u64, SIGSET_SIZE_U64, 0_i32)
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }
}

// ─────────────────────────────────────────────────────────────────────────
// signalfd_create / signalfd_create_blocking.
// ─────────────────────────────────────────────────────────────────────────

/// Crée un `signalfd` pour les signaux du `mask`.
///
/// Le drapeau `CLOEXEC` est **toujours** ajouté par le wrapper (cf.
/// discipline universelle couche 0 : tous les FDs créés par Air sont
/// `O_CLOEXEC`).
///
/// **Important.** Créer un signalfd ne suffit pas à empêcher la
/// délivrance normale des signaux du `mask` (handler ou comportement
/// par défaut). Il faut **aussi** bloquer ces signaux dans le mask du
/// thread via [`block_signals`]. Le helper [`signalfd_create_blocking`]
/// combine les deux étapes.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : mask invalide.
/// - `EMFILE`/`ENFILE` (stub Errno) : limites de FDs atteintes.
pub fn signalfd_create(mask: &SignalMask, flags: SignalFdFlags) -> Result<SignalFd, Errno> {
    let bits = mask.bits();
    let mask_ptr: *const u64 = &bits;
    let kernel_flags = flags.bits() | SignalFdFlags::CLOEXEC.bits();
    // SAFETY: signalfd4(-1, &mask, sizeof(u64), flags) crée un nouveau
    // FD ; le kernel lit 8 octets à mask_ptr. Pas d'écriture en mémoire
    // utilisateur. -1 = créer un nouveau (vs réutiliser un existant).
    let ret =
        unsafe { raw_syscall_signalfd4(-1_i32, mask_ptr as u64, SIGSET_SIZE_U64, kernel_flags) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let new_fd = ret as i32;
    // SAFETY: kernel vient de transférer la propriété d'un fd valide.
    let owned = unsafe { OwnedFd::from_raw_fd(new_fd) };
    Ok(SignalFd::from_owned_fd(owned))
}

/// Helper canonique : bloque les signaux du `mask` dans le thread
/// appelant **puis** crée un `signalfd` pour ces mêmes signaux.
///
/// Pattern recommandé par `family-signal.md` et ADR-020.
///
/// **Note.** Le blocage est PER-THREAD ; il s'applique au thread qui
/// appelle cette fonction. À combiner avec un `MaskGuard` RAII dans le
/// code de test pour ne pas contaminer les threads/tests suivants.
///
/// # Errors
///
/// - Toutes les erreurs de [`block_signals`] et [`signalfd_create`].
pub fn signalfd_create_blocking(
    mask: &SignalMask,
    flags: SignalFdFlags,
) -> Result<SignalFd, Errno> {
    let _ = block_signals(mask)?;
    signalfd_create(mask, flags)
}

// ─────────────────────────────────────────────────────────────────────────
// Masques de signaux : rt_sigprocmask wrappers.
// ─────────────────────────────────────────────────────────────────────────

const SIG_BLOCK: i32 = 0;
const SIG_UNBLOCK: i32 = 1;
const SIG_SETMASK: i32 = 2;
const SIGSET_SIZE_U64: u64 = 8;

/// Bloque les signaux du `mask` dans le mask courant du thread (union).
/// Retourne l'ancien mask (avant modification).
///
/// `SIGKILL` et `SIGSTOP` sont silencieusement ignorés par le kernel
/// (non bloquables).
///
/// # Errors
///
/// - [`Errno::EINVAL`] : sigsetsize invalide.
pub fn block_signals(mask: &SignalMask) -> Result<SignalMask, Errno> {
    rt_sigprocmask(SIG_BLOCK, Some(mask))
}

/// Déblocque les signaux du `mask` dans le mask courant du thread
/// (différence). Retourne l'ancien mask.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : sigsetsize invalide.
pub fn unblock_signals(mask: &SignalMask) -> Result<SignalMask, Errno> {
    rt_sigprocmask(SIG_UNBLOCK, Some(mask))
}

/// Remplace **totalement** le mask de signaux du thread par `mask`.
/// Retourne l'ancien mask.
///
/// Usage typique : restauration du mask original via un guard RAII.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : sigsetsize invalide.
pub fn set_signal_mask(mask: &SignalMask) -> Result<SignalMask, Errno> {
    rt_sigprocmask(SIG_SETMASK, Some(mask))
}

/// Lit le mask de signaux courant sans modification.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : ne se produit pas en pratique.
pub fn current_signal_mask() -> Result<SignalMask, Errno> {
    rt_sigprocmask(SIG_SETMASK, None)
}

/// Helper interne : encapsule l'appel `rt_sigprocmask` quelle que soit
/// l'opération (SIG_BLOCK/UNBLOCK/SETMASK). `set = None` signifie
/// « lecture seule ».
fn rt_sigprocmask(how: i32, set: Option<&SignalMask>) -> Result<SignalMask, Errno> {
    let set_bits: u64 = set.map_or(0, |m| m.bits());
    let set_ptr: u64 = match set {
        Some(_) => {
            let p: *const u64 = &set_bits;
            p as u64
        }
        None => 0,
    };
    let mut old_bits: u64 = 0;
    let old_ptr: *mut u64 = &mut old_bits;
    // SAFETY: rt_sigprocmask lit `set` si non-null (8 octets), écrit
    // `oldset` (8 octets). Les deux pointeurs sont locaux ; sigsetsize=8
    // correspond à la taille kernel `sigset_t` sur x86_64/aarch64.
    let ret = unsafe { raw_syscall_rt_sigprocmask(how, set_ptr, old_ptr as u64, SIGSET_SIZE_U64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(SignalMask::from_bits(old_bits))
}

/// Lit l'ensemble des signaux **pendants** (`rt_sigpending(2)`).
///
/// Retourne le [`SignalMask`] des signaux **en attente** de délivrance pour le
/// thread appelant (union des pendants par-thread et par-process), c.-à-d.
/// générés mais pas encore délivrés — typiquement parce qu'ils sont **bloqués**
/// dans le masque courant. Brique de `sigpending(3)` de la libc (via la couche 1
/// `air-signal`).
///
/// **Kernel = bible** : cette fonction **expose** l'état pendant du noyau, elle
/// n'en maintient aucun (ADR-064 §6).
///
/// # Errors
///
/// - [`Errno::EFAULT`] : inatteignable via cette API (le buffer est un local
///   vivant). En pratique `rt_sigpending` ne peut pas échouer avec un
///   `sigsetsize` correct (fixé à 8 par le wrapper).
pub fn rt_sigpending() -> Result<SignalMask, Errno> {
    let mut pending_bits: u64 = 0;
    let set_ptr: *mut u64 = &mut pending_bits;
    // SAFETY: rt_sigpending écrit 8 octets (sigset_t kernel = 1 mot sur
    // x86_64/aarch64) à `set_ptr`, local vivant pour la durée de l'appel.
    // sigsetsize=8 correspond à la taille kernel `sigset_t`.
    let ret = unsafe { raw_syscall_rt_sigpending(set_ptr as u64, SIGSET_SIZE_U64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(SignalMask::from_bits(pending_bits))
}

// ─────────────────────────────────────────────────────────────────────────
// wait_for_signal — helper signalfd temporaire.
// ─────────────────────────────────────────────────────────────────────────

/// Attend l'arrivée d'un signal du `mask`, avec timeout optionnel.
///
/// Implémentation : crée un `signalfd` temporaire pour `mask`, bloque
/// ces signaux dans le thread, lit l'événement (bloquant ou avec
/// timeout via `ppoll`).
///
/// **Note périmètre.** Cette PR n'implémente que la variante
/// `timeout = None` (lecture bloquante via `read` sur le signalfd) ;
/// la variante `Some(duration)` nécessite `ppoll` qui sera ajouté dans
/// la PR `family-time` (timers). En `Some(_)`, retourne actuellement
/// [`Errno::EINVAL`] — l'API publique reste conforme spec mais la
/// branche timeout est documentée comme TODO.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `timeout.is_some()` (non encore implémenté
///   sans wrapper `ppoll`).
/// - Toutes les erreurs de [`signalfd_create_blocking`] et de
///   [`SignalFd::read`].
pub fn wait_for_signal(
    mask: &SignalMask,
    timeout: Option<Duration>,
) -> Result<SignalFdInfo, Errno> {
    if timeout.is_some() {
        return Err(Errno::EINVAL);
    }
    let sfd = signalfd_create_blocking(mask, SignalFdFlags::empty())?;
    sfd.read()
}

// ─────────────────────────────────────────────────────────────────────────
// Envoi de signaux : kill, tgkill, rt_sigqueueinfo.
// ─────────────────────────────────────────────────────────────────────────

/// Envoie `signal` au processus `pid`.
///
/// `signal = None` correspond au "signal 0" Linux : test d'existence du
/// processus sans envoyer de signal effectif (cf. convention 1
/// ADR-021).
///
/// **Recommandation Air.** Pour un processus enfant dont on possède un
/// `PidFd`, préférer [`pidfd_send_signal`](crate::process::pidfd_send_signal)
/// — pas de race sur le PID recyclé.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : signal invalide.
/// - [`Errno::EPERM`] : permissions insuffisantes.
/// - [`Errno::ESRCH`] : processus inexistant.
pub fn kill(pid: Pid, signal: Option<Signal>) -> Result<(), Errno> {
    let sig_arg = signal.map_or(0_i32, |s| s.as_raw());
    // SAFETY: kill(2) ne touche pas la mémoire utilisateur.
    let ret = unsafe { raw_syscall_kill(pid.as_raw(), sig_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Envoie `signal` à **tout un groupe de processus** (`kill(2)` avec un `pid` négatif) —
/// **descellement additif [ADR-085](../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md)**
/// pour la face libc `killpg` (le type positif-seul [`Pid`] interdit d'exprimer le `pid`
/// négatif « groupe » via [`kill`]). `group = None` cible le **groupe de l'appelant**
/// (sentinelle kernel `0` typée en `Option`, ADR-021 conv. 1) ; `Some(g)` cible le groupe
/// `g` (le kernel reçoit `-g`). `signal = None` = test d'existence.
pub fn kill_process_group(group: Option<Pid>, signal: Option<Signal>) -> Result<(), Errno> {
    let sig_arg = signal.map_or(0_i32, |s| s.as_raw());
    // `None` ⇒ `0` (groupe de l'appelant) ; `Some(g)` ⇒ `-g` (g > 0 ⇒ pas de débordement).
    let target = group.map_or(0_i32, |g| g.as_raw().wrapping_neg());
    // SAFETY: kill(2) ne touche pas la mémoire utilisateur.
    let ret = unsafe { raw_syscall_kill(target, sig_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Installe (`new`) et/ou interroge (`old`) la **pile de signal alternative** du thread
/// (`sigaltstack(2)`) — **descellement additif [ADR-085](../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md)**
/// pour la face libc. `new = None` ne change rien ; `old = None` ne rapporte rien.
/// Requis par `std` (traitement d'un `SIGSEGV` de débordement de pile sur pile dédiée).
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `new.flags` invalide, ou `new.size < MINSIGSTKSZ`.
/// - [`Errno::EPERM`] : tentative de désactivation alors que le thread est **sur** la pile
///   alternative (`SS_ONSTACK`).
/// - [`Errno::EFAULT`] : `new`/`old` hors de l'espace adressable (impossible via `&`).
pub fn sigaltstack(new: Option<&AltStack>, old: Option<&mut AltStack>) -> Result<(), Errno> {
    let new_ptr = new.map_or(0_u64, |stack| core::ptr::from_ref(stack) as u64);
    let old_ptr = old.map_or(0_u64, |stack| core::ptr::from_mut(stack) as u64);
    // SAFETY: le kernel **lit** `*new` (24 octets, `stack_t`) si `new_ptr != 0`, et
    // **écrit** `*old` (24 octets) si `old_ptr != 0` ; les deux proviennent de références
    // Rust valides et correctement dimensionnées (`AltStack` est `#[repr(C)]` = `stack_t`).
    let ret = unsafe { raw_syscall_sigaltstack(new_ptr, old_ptr) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Envoie `signal` au thread `tid` du process `tgid`.
///
/// Plus précis que [`kill`] : cible un thread spécifique d'un processus
/// multi-thread. Indispensable pour les patterns de signaling
/// intra-process déterministes (notamment dans les tests qui veulent
/// délivrer un signal à un thread précis sans contaminer les autres
/// workers).
///
/// `signal = None` : test d'existence (convention 1 ADR-021).
///
/// # Errors
///
/// - Mêmes que [`kill`].
pub fn tgkill(tgid: Pid, tid: Tid, signal: Option<Signal>) -> Result<(), Errno> {
    let sig_arg = signal.map_or(0_i32, |s| s.as_raw());
    // SAFETY: tgkill(2) ne touche pas la mémoire utilisateur.
    let ret = unsafe { raw_syscall_tgkill(tgid.as_raw(), tid.as_raw(), sig_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Envoie `signal` au processus `pid` avec un payload `siginfo_t`
/// (pattern SI_QUEUE — `sigqueue(3)` côté userspace).
///
/// `info` est construit côté appelant via
/// [`SignalInfo::new_queue`](air_sys_types::SignalInfo::new_queue). Le
/// kernel écrase `si_signo` avec `signal` à la délivrance.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : signal invalide.
/// - [`Errno::EPERM`] : tentative d'envoi cross-process avec un
///   `si_code` non autorisé (impossible via notre constructeur qui
///   fixe `si_code = SI_QUEUE`).
/// - [`Errno::ESRCH`] : processus inexistant.
pub fn rt_sigqueueinfo(pid: Pid, signal: Signal, info: &SignalInfo) -> Result<(), Errno> {
    let info_ptr: *const u8 = info.as_bytes().as_ptr();
    // SAFETY: rt_sigqueueinfo(2) lit 128 octets à `info_ptr` (taille
    // siginfo_t Linux côté x86_64/aarch64). Pas d'écriture user.
    let ret =
        unsafe { raw_syscall_rt_sigqueueinfo(pid.as_raw(), signal.as_raw(), info_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// signalfd_siginfo : parsing du buffer kernel vers SignalFdInfo.
// ─────────────────────────────────────────────────────────────────────────

const SIGNALFD_SIGINFO_SIZE: usize = 128;
const SIGNALFD_SIGINFO_SIZE_I32: i32 = 128;

// Offsets dans `struct signalfd_siginfo` (uapi/linux/signalfd.h).
// Identiques x86_64/aarch64.
const SFI_SSI_SIGNO: usize = 0;
const SFI_SSI_ERRNO: usize = 4;
const SFI_SSI_CODE: usize = 8;
const SFI_SSI_PID: usize = 12;
const SFI_SSI_UID: usize = 16;
const SFI_SSI_FD: usize = 20;
const SFI_SSI_TID: usize = 24;
const SFI_SSI_BAND: usize = 28;
const SFI_SSI_OVERRUN: usize = 32;
const SFI_SSI_TRAPNO: usize = 36;
const SFI_SSI_STATUS: usize = 40;
const SFI_SSI_INT: usize = 44;
const SFI_SSI_PTR: usize = 48;
const SFI_SSI_UTIME: usize = 56;
const SFI_SSI_STIME: usize = 64;
const SFI_SSI_ADDR: usize = 72;

fn read_u32(buffer: &[u8], offset: usize) -> u32 {
    u32::from_ne_bytes(
        buffer[offset..offset.saturating_add(4)]
            .try_into()
            .expect("4 octets"),
    )
}

fn read_i32(buffer: &[u8], offset: usize) -> i32 {
    i32::from_ne_bytes(
        buffer[offset..offset.saturating_add(4)]
            .try_into()
            .expect("4 octets"),
    )
}

fn read_u64(buffer: &[u8], offset: usize) -> u64 {
    u64::from_ne_bytes(
        buffer[offset..offset.saturating_add(8)]
            .try_into()
            .expect("8 octets"),
    )
}

fn parse_signalfd_siginfo(buffer: &[u8; SIGNALFD_SIGINFO_SIZE]) -> SignalFdInfo {
    let signo = read_u32(buffer, SFI_SSI_SIGNO);
    // Le kernel garantit `signo` > 0 pour tout événement signalfd réel.
    let signal = Signal::try_from_raw(i32::try_from(signo).expect("ssi_signo fit en i32"))
        .expect("kernel : signalfd événement avec signo > 0");

    let pid_raw = read_u32(buffer, SFI_SSI_PID);
    // `ssi_pid == 0` quand le signal vient du kernel (SI_KERNEL) ; on
    // applique la convention 1 ADR-021 et retourne `None` dans ce cas.
    let pid = if pid_raw == 0 {
        None
    } else {
        Some(
            Pid::try_from_raw(i32::try_from(pid_raw).expect("ssi_pid fit en i32"))
                .expect("ssi_pid > 0 ici"),
        )
    };

    SignalFdInfo {
        signal,
        errno: read_i32(buffer, SFI_SSI_ERRNO),
        code: read_i32(buffer, SFI_SSI_CODE),
        pid,
        uid: read_u32(buffer, SFI_SSI_UID),
        fd: read_i32(buffer, SFI_SSI_FD),
        timer_id: read_u32(buffer, SFI_SSI_TID),
        band: read_u32(buffer, SFI_SSI_BAND),
        overrun: read_u32(buffer, SFI_SSI_OVERRUN),
        trap_no: read_u32(buffer, SFI_SSI_TRAPNO),
        status: read_i32(buffer, SFI_SSI_STATUS),
        int: read_i32(buffer, SFI_SSI_INT),
        ptr: read_u64(buffer, SFI_SSI_PTR),
        utime: read_u64(buffer, SFI_SSI_UTIME),
        stime: read_u64(buffer, SFI_SSI_STIME),
        addr: read_u64(buffer, SFI_SSI_ADDR),
    }
}

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

pub mod synchronous_handler {
    //! Wrappers `sigaction` **restreints aux 4 signaux synchrones fatals**
    //! (cf. ADR-020).
    //!
    //! L'API entière est `unsafe` : l'appelant doit garantir que le
    //! handler installé respecte la contrainte async-signal-safe
    //! (cf. `man 7 signal-safety`).

    use air_sys_types::Errno;
    use air_sys_types::signal::synchronous_handler::{FatalHandler, FatalSignal, PreviousHandler};

    use super::{SIGSET_SIZE_U64, errno_from_negative_syscall_ret};

    // SA_SIGINFO = 4 (constant ABI Linux, identique x86_64/aarch64).
    const SA_SIGINFO: u64 = 4;

    /// Installe `handler` comme handler du signal fatal `signal`.
    /// Retourne l'ancien handler dans `PreviousHandler` pour pouvoir
    /// restaurer via [`restore_handler`].
    ///
    /// # Safety
    ///
    /// L'appelant doit garantir que `handler` est **async-signal-safe**
    /// (cf. `man 7 signal-safety`). Concrètement : pas de `malloc`, pas
    /// de `printf`, pas de mutex, pas de `Mutex` Rust, pas d'allocations
    /// indirectes (incluant les `format!`). Les appels typiques admis :
    /// `write(STDERR_FILENO, ...)`, opérations `core::sync::atomic`,
    /// `_exit(N)`. Voir l'ADR-020 pour les patterns de crash reporter.
    pub unsafe fn install_fatal_handler(
        signal: FatalSignal,
        handler: FatalHandler,
    ) -> Result<PreviousHandler, Errno> {
        let mut new_sa = KernelSigaction::zeroed();
        new_sa.sa_handler = handler as usize as u64;
        new_sa.sa_flags = SA_SIGINFO;
        // sa_mask = 0 (aucun signal additionnel bloqué pendant le
        // handler). sa_restorer = 0 sur x86_64 → kernel utilise le
        // trampoline VDSO ; absent sur aarch64.

        let mut previous = PreviousHandler::zeroed();
        let new_ptr: *const KernelSigaction = &new_sa;
        let old_ptr: *mut [u8; 32] = previous.as_bytes_mut();

        // SAFETY: rt_sigaction(2). Le kernel lit `new_sa`
        // (KernelSigaction valide, locale) et écrit jusqu'à 32 octets à
        // `old_ptr` (capacité de `PreviousHandler`). sigsetsize=8
        // correspond à la taille kernel `sigset_t`.
        let ret = unsafe {
            raw_syscall_rt_sigaction(
                signal.as_signal().as_raw(),
                new_ptr as u64,
                old_ptr as u64,
                SIGSET_SIZE_U64,
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(previous)
    }

    /// Restaure le handler `previous` pour le signal `signal`.
    ///
    /// # Safety
    ///
    /// `previous` doit avoir été obtenu par un appel précédent à
    /// [`install_fatal_handler`] sur le **même** `signal`. Restaurer un
    /// `PreviousHandler` qui ne provient pas du même signal est
    /// undefined behavior côté kernel.
    pub unsafe fn restore_handler(
        signal: FatalSignal,
        previous: PreviousHandler,
    ) -> Result<(), Errno> {
        let prev_ptr: *const [u8; 32] = previous.as_bytes();
        // SAFETY: rt_sigaction(2). Le kernel lit jusqu'à 32 octets à
        // `prev_ptr` (KernelSigaction est ≤ 32 octets sur x86_64/aarch64).
        // Pas d'écriture (oldset=NULL).
        let ret = unsafe {
            raw_syscall_rt_sigaction(
                signal.as_signal().as_raw(),
                prev_ptr as u64,
                0_u64,
                SIGSET_SIZE_U64,
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }

    /// Représentation interne du `struct sigaction` kernel.
    ///
    /// Layout :
    /// - offset 0  : `sa_handler` (pointer, 8 octets)
    /// - offset 8  : `sa_flags` (unsigned long, 8 octets)
    /// - offset 16 : `sa_restorer` (x86_64 uniquement, 8 octets)
    /// - offset 24 (x86_64) ou 16 (aarch64) : `sa_mask` (sigset_t, 8 octets)
    ///
    /// Sur aarch64, `sa_restorer` est absent (le kernel utilise VDSO
    /// pour le retour). On utilise donc deux layouts compatibles avec
    /// le syscall :
    /// - x86_64 : 32 octets.
    /// - aarch64 : 24 octets, paddé à 32 pour uniformiser le buffer
    ///   `PreviousHandler` (les 8 derniers octets sont ignorés par le
    ///   kernel sur aarch64).
    #[repr(C)]
    #[cfg(target_arch = "x86_64")]
    struct KernelSigaction {
        sa_handler: u64,
        sa_flags: u64,
        sa_restorer: u64,
        sa_mask: u64,
    }

    #[cfg(target_arch = "x86_64")]
    impl KernelSigaction {
        const fn zeroed() -> Self {
            Self {
                sa_handler: 0,
                sa_flags: 0,
                sa_restorer: 0,
                sa_mask: 0,
            }
        }
    }

    #[repr(C)]
    #[cfg(target_arch = "aarch64")]
    struct KernelSigaction {
        sa_handler: u64,
        sa_flags: u64,
        sa_mask: u64,
    }

    #[cfg(target_arch = "aarch64")]
    impl KernelSigaction {
        const fn zeroed() -> Self {
            Self {
                sa_handler: 0,
                sa_flags: 0,
                sa_mask: 0,
            }
        }
    }

    #[cfg(target_arch = "x86_64")]
    #[inline]
    unsafe fn raw_syscall_rt_sigaction(
        signum: i32,
        new_sa: u64,
        old_sa: u64,
        sigsetsize: u64,
    ) -> i64 {
        let ret: i64;
        // SAFETY: SYS_rt_sigaction (x86_64 = 13). Le kernel lit `new_sa`
        // (KernelSigaction, 32 octets), écrit `old_sa` (32 octets) si
        // non-null. ABI standard ; pas de `readonly` (écriture sur
        // `*old_sa`).
        unsafe {
            core::arch::asm!(
                "syscall",
                in("rax") 13_i64,
                in("rdi") i64::from(signum),
                in("rsi") new_sa,
                in("rdx") old_sa,
                in("r10") sigsetsize,
                lateout("rax") ret,
                lateout("rcx") _,
                lateout("r11") _,
                options(nostack, preserves_flags),
            );
        }
        ret
    }

    #[cfg(target_arch = "aarch64")]
    #[inline]
    unsafe fn raw_syscall_rt_sigaction(
        signum: i32,
        new_sa: u64,
        old_sa: u64,
        sigsetsize: u64,
    ) -> i64 {
        let ret: i64;
        // SAFETY: SYS_rt_sigaction (aarch64 = 134).
        unsafe {
            core::arch::asm!(
                "svc 0",
                in("x8") 134_i64,
                inout("x0") i64::from(signum) => ret,
                in("x1") new_sa,
                in("x2") old_sa,
                in("x3") sigsetsize,
                options(nostack, preserves_flags),
            );
        }
        ret
    }

    /// Test : KernelSigaction tient dans le buffer 32 octets de
    /// PreviousHandler.
    const _: () = {
        assert!(core::mem::size_of::<KernelSigaction>() <= 32);
    };

    /// Fonction `c_int` utilitaire pour les tests : ne fait rien (handler
    /// vide), mais respecte la signature `FatalHandler`.
    ///
    /// Used by tests. Marked async-signal-safe (no allocation, no I/O,
    /// just returns).
    ///
    /// # Safety
    ///
    /// Trivially safe : no operations.
    #[cfg(test)]
    pub(super) unsafe extern "C" fn noop_handler(
        _signum: core::ffi::c_int,
        _info: *mut air_sys_types::signal::synchronous_handler::SignalInfo,
        _context: *mut core::ffi::c_void,
    ) {
        // Vide. Trivially async-signal-safe.
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Sous-module async_handler : rt_sigaction NON-faute réel (cf. ADR-066).
// ─────────────────────────────────────────────────────────────────────────

// Trampoline `rt_sigreturn` pour x86_64. À la fin d'un handler **non-faute**, le
// noyau ne revient PAS directement au code interrompu : il saute à l'adresse
// `sa_restorer`, dont la seule mission est d'invoquer `rt_sigreturn` (NR 15) pour
// restaurer le contexte pré-signal empilé par le noyau (sigframe). Sur x86_64 la
// libc/`std` fournit ce trampoline ; sans libc (Air), on le fournit nous-mêmes.
// Sur aarch64, le noyau route le retour par le VDSO — **aucun** `sa_restorer`.
//
// SAFETY: le corps asm n'est **jamais** appelé depuis Rust ; c'est le **noyau**
// qui y saute à la fin du handler, avec `%rsp` pointant sur le sigframe. Il ne
// fait qu'exécuter `rt_sigreturn` (`mov $15, %rax; syscall`), syscall qui ne
// retourne pas (il restaure le contexte). Aucun prologue/épilogue (pas de cadre
// de pile), aucun accès mémoire propre : conforme au contrat ABI de `sa_restorer`.
#[cfg(target_arch = "x86_64")]
core::arch::global_asm!(
    ".p2align 4",
    ".globl __air_rt_sigreturn_trampoline",
    ".hidden __air_rt_sigreturn_trampoline",
    "__air_rt_sigreturn_trampoline:",
    "mov rax, 15", // __NR_rt_sigreturn (x86_64)
    "syscall",
);

#[cfg(target_arch = "x86_64")]
unsafe extern "C" {
    /// Symbole du trampoline `rt_sigreturn` défini par le `global_asm!`
    /// ci-dessus. Jamais appelé depuis Rust — seule son **adresse** est posée
    /// dans `sa_restorer`.
    fn __air_rt_sigreturn_trampoline();
}

pub mod async_handler {
    //! Wrappers `rt_sigaction` pour les signaux **non-faute** — handler
    //! **réellement installé** (cf. ADR-064 : délivrance async réelle ; ADR-066 :
    //! descellement additif couche 0).
    //!
    //! Contrairement à [`synchronous_handler`](super::synchronous_handler)
    //! (restreint aux 4 fautes, handler **inerte** — le noyau force l'action par
    //! défaut), ce sous-module installe un `rt_sigaction` **effectif** : le noyau
    //! détourne le thread vers le handler C à la délivrance d'un signal
    //! **gérable**. C'est la **fondation dual-face** que la libc (`sigaction`) et
    //! le PAL consomment via la couche 1 `air-signal`.
    //!
    //! **API entièrement `unsafe`** : l'appelant garantit que le handler est
    //! **async-signal-safe** (`man 7 signal-safety`) — précondition invérifiable
    //! par le compilateur, portée par l'appelant (identique à
    //! `synchronous_handler`).

    use air_sys_types::Errno;
    use air_sys_types::signal::async_handler::{PreviousDisposition, SigActionFlags};
    use air_sys_types::{Signal, SignalMask};

    use super::{SIGSET_SIZE_U64, errno_from_negative_syscall_ret};

    /// `SA_RESTORER` (`0x0400_0000`) — **x86_64 uniquement**. Signale au noyau que
    /// `sa_restorer` porte l'adresse du trampoline de retour de handler.
    #[cfg(target_arch = "x86_64")]
    const SA_RESTORER: u64 = 0x0400_0000;

    /// Valeur `sa_handler` = `SIG_DFL` (action par défaut du noyau).
    pub const SIG_DFL: usize = 0;
    /// Valeur `sa_handler` = `SIG_IGN` (signal ignoré). **Sûr** (constante noyau,
    /// aucun code utilisateur) — cf. ADR-064 §2.
    pub const SIG_IGN: usize = 1;

    /// Installe une disposition pour le signal **non-faute** `signal` via
    /// `rt_sigaction(2)`, et rend la disposition **précédente** (pour
    /// [`restore`]).
    ///
    /// - `handler_sa` : valeur brute de `sa_handler` — [`SIG_DFL`] (`0`),
    ///   [`SIG_IGN`] (`1`), ou l'**adresse** d'une fonction handler
    ///   `extern "C"` (cast `usize`). C'est la couche 1 (`air-signal`) qui
    ///   fournit le type de handler ; la couche 0 reste agnostique (adresse
    ///   brute).
    /// - `flags` : [`SigActionFlags`] (`SA_SIGINFO`/`SA_RESTART`/…). Sur x86_64,
    ///   le wrapper **ajoute** `SA_RESTORER` et pose `sa_restorer` sur le
    ///   trampoline `rt_sigreturn` d'Air (obligatoire sans libc). Sur aarch64, le
    ///   retour passe par le VDSO — aucun `sa_restorer`.
    /// - `mask` : signaux **additionnels** bloqués pendant l'exécution du handler.
    ///
    /// # Safety
    ///
    /// Si `handler_sa` désigne une fonction (≠ [`SIG_DFL`]/[`SIG_IGN`]), l'appelant
    /// doit garantir qu'elle est **async-signal-safe** (`man 7 signal-safety`) :
    /// pas de `malloc`, pas de verrou, pas d'I/O bufferisée, etc. Le noyau peut
    /// l'invoquer à un point **arbitraire** du programme. Poser [`SIG_DFL`] ou
    /// [`SIG_IGN`] est en soi sûr (aucun code utilisateur), mais l'API reste
    /// `unsafe` pour une frontière uniforme.
    ///
    /// Ce wrapper est réservé aux signaux **non-faute** : installer un handler
    /// pour `SIGSEGV`/`SIGBUS`/`SIGFPE`/`SIGILL` est le domaine (inerte) de
    /// [`synchronous_handler`](super::synchronous_handler) (ADR-020/ADR-064).
    ///
    /// # Errors
    ///
    /// - [`Errno::EINVAL`] : `signal` non-catchable (`SIGKILL`/`SIGSTOP`).
    pub unsafe fn install(
        signal: Signal,
        handler_sa: usize,
        flags: SigActionFlags,
        mask: SignalMask,
    ) -> Result<PreviousDisposition, Errno> {
        let mut new_sa = KernelSigaction::zeroed();
        // `usize → u64` : Air ne cible que des arches 64 bits (ADR-014) — même
        // idiome que `synchronous_handler::install_fatal_handler`
        // (`handler as usize as u64`), lossless, sans conversion faillible.
        new_sa.sa_handler = handler_sa as u64;
        new_sa.sa_mask = mask.bits();

        // Drapeaux : ceux de l'appelant, plus `SA_RESTORER` sur x86_64 (le noyau
        // a besoin d'un trampoline de retour ; sans libc, Air le fournit).
        let kernel_flags = flags.bits();
        #[cfg(target_arch = "x86_64")]
        {
            new_sa.sa_flags = kernel_flags | SA_RESTORER;
            // Adresse du trampoline `rt_sigreturn` (fn item → usize → u64,
            // 64 bits : lossless).
            new_sa.sa_restorer = super::__air_rt_sigreturn_trampoline as *const () as usize as u64;
        }
        #[cfg(target_arch = "aarch64")]
        {
            new_sa.sa_flags = kernel_flags;
        }

        let mut previous = PreviousDisposition::zeroed();
        let new_ptr: *const KernelSigaction = &new_sa;
        let old_ptr: *mut u8 = previous.as_bytes_mut().as_mut_ptr();

        // SAFETY: rt_sigaction(2). Le kernel lit `new_sa` (KernelSigaction valide,
        // locale) et écrit jusqu'à 32 octets à `old_ptr` (capacité de
        // `PreviousDisposition`). sigsetsize=8 = taille kernel `sigset_t`. Le
        // handler éventuel respecte l'async-signal-safety par contrat `unsafe`.
        let ret = unsafe {
            raw_syscall_rt_sigaction(
                signal.as_raw(),
                new_ptr as u64,
                old_ptr as u64,
                SIGSET_SIZE_U64,
            )
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(previous)
    }

    /// Restaure la disposition `previous` pour le signal `signal`.
    ///
    /// # Safety
    ///
    /// `previous` doit provenir d'un [`install`] précédent sur le **même**
    /// `signal`. Restaurer une disposition d'un autre signal est un comportement
    /// indéfini côté noyau.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINVAL`] : `signal` non-catchable (ne se produit pas si
    ///   `previous` vient d'un `install` réussi sur ce signal).
    pub unsafe fn restore(signal: Signal, previous: PreviousDisposition) -> Result<(), Errno> {
        let prev_ptr: *const u8 = previous.as_bytes().as_ptr();
        // SAFETY: rt_sigaction(2). Le kernel lit jusqu'à 32 octets à `prev_ptr`
        // (KernelSigaction ≤ 32 octets). Pas d'écriture (oldset=NULL).
        let ret = unsafe {
            raw_syscall_rt_sigaction(signal.as_raw(), prev_ptr as u64, 0_u64, SIGSET_SIZE_U64)
        };
        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }

    /// Représentation interne du `struct sigaction` kernel (cf.
    /// [`synchronous_handler`](super::synchronous_handler) — même layout ABI,
    /// dupliqué pour ne PAS toucher au sous-module des fautes).
    ///
    /// - offset 0  : `sa_handler` (8) ; offset 8 : `sa_flags` (8) ;
    /// - x86_64 : offset 16 `sa_restorer` (8), offset 24 `sa_mask` (8) — 32 octets ;
    /// - aarch64 : offset 16 `sa_mask` (8), **pas** de `sa_restorer` — 24 octets.
    #[repr(C)]
    #[cfg(target_arch = "x86_64")]
    struct KernelSigaction {
        sa_handler: u64,
        sa_flags: u64,
        sa_restorer: u64,
        sa_mask: u64,
    }

    #[cfg(target_arch = "x86_64")]
    impl KernelSigaction {
        const fn zeroed() -> Self {
            Self {
                sa_handler: 0,
                sa_flags: 0,
                sa_restorer: 0,
                sa_mask: 0,
            }
        }
    }

    #[repr(C)]
    #[cfg(target_arch = "aarch64")]
    struct KernelSigaction {
        sa_handler: u64,
        sa_flags: u64,
        sa_mask: u64,
    }

    #[cfg(target_arch = "aarch64")]
    impl KernelSigaction {
        const fn zeroed() -> Self {
            Self {
                sa_handler: 0,
                sa_flags: 0,
                sa_mask: 0,
            }
        }
    }

    /// `KernelSigaction` tient dans le buffer 32 octets de `PreviousDisposition`.
    const _: () = {
        assert!(core::mem::size_of::<KernelSigaction>() <= 32);
    };

    #[cfg(target_arch = "x86_64")]
    #[inline]
    unsafe fn raw_syscall_rt_sigaction(
        signum: i32,
        new_sa: u64,
        old_sa: u64,
        sigsetsize: u64,
    ) -> i64 {
        let ret: i64;
        // SAFETY: SYS_rt_sigaction (x86_64 = 13). Le kernel lit `new_sa`
        // (KernelSigaction, 32 octets), écrit `old_sa` (32 octets) si non-null.
        unsafe {
            core::arch::asm!(
                "syscall",
                in("rax") 13_i64,
                in("rdi") i64::from(signum),
                in("rsi") new_sa,
                in("rdx") old_sa,
                in("r10") sigsetsize,
                lateout("rax") ret,
                lateout("rcx") _,
                lateout("r11") _,
                options(nostack, preserves_flags),
            );
        }
        ret
    }

    #[cfg(target_arch = "aarch64")]
    #[inline]
    unsafe fn raw_syscall_rt_sigaction(
        signum: i32,
        new_sa: u64,
        old_sa: u64,
        sigsetsize: u64,
    ) -> i64 {
        let ret: i64;
        // SAFETY: SYS_rt_sigaction (aarch64 = 134).
        unsafe {
            core::arch::asm!(
                "svc 0",
                in("x8") 134_i64,
                inout("x0") i64::from(signum) => ret,
                in("x1") new_sa,
                in("x2") old_sa,
                in("x3") sigsetsize,
                options(nostack, preserves_flags),
            );
        }
        ret
    }
}

// ─────────────────────────────────────────────────────────────────────────
// asm! wrappers x86_64 / aarch64.
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_signalfd4(fd: i32, mask: u64, sigsetsize: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_signalfd4 (x86_64 = 289). Le kernel lit `*mask` (8
    // octets) ; pas d'écriture en mémoire utilisateur (`readonly` OK).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 289_i64,
            in("rdi") i64::from(fd),
            in("rsi") mask,
            in("rdx") sigsetsize,
            in("r10") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_signalfd4(fd: i32, mask: u64, sigsetsize: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_signalfd4 (aarch64 = 74).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 74_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") mask,
            in("x2") sigsetsize,
            in("x3") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_rt_sigprocmask(how: i32, set: u64, oldset: u64, sigsetsize: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigprocmask (x86_64 = 14). Le kernel lit `*set` si
    // non-null (8 octets) ; écrit `*oldset` si non-null (8 octets). Pas
    // de `readonly` (écriture sur oldset).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 14_i64,
            in("rdi") i64::from(how),
            in("rsi") set,
            in("rdx") oldset,
            in("r10") sigsetsize,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_rt_sigprocmask(how: i32, set: u64, oldset: u64, sigsetsize: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigprocmask (aarch64 = 135).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 135_i64,
            inout("x0") i64::from(how) => ret,
            in("x1") set,
            in("x2") oldset,
            in("x3") sigsetsize,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sigaltstack(new: u64, old: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sigaltstack (x86_64 = 131). Le kernel **lit** `*new` (24 octets) si
    // `new != 0` et **écrit** `*old` (24 octets) si `old != 0` — pas de `readonly`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 131_i64,
            in("rdi") new,
            in("rsi") old,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sigaltstack(new: u64, old: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sigaltstack (aarch64 = 132). Mêmes contrats mémoire que x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 132_i64,
            inout("x0") new => ret,
            in("x1") old,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_rt_sigpending(set: u64, sigsetsize: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigpending (x86_64 = 127). Le kernel **écrit** 8 octets à
    // `set` (sigset_t) ; pas de `readonly`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 127_i64,
            in("rdi") set,
            in("rsi") sigsetsize,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_rt_sigpending(set: u64, sigsetsize: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigpending (aarch64 = 136).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 136_i64,
            inout("x0") set => ret,
            in("x1") sigsetsize,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_kill(pid: i32, sig: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_kill (x86_64 = 62). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 62_i64,
            in("rdi") i64::from(pid),
            in("rsi") i64::from(sig),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_kill(pid: i32, sig: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_kill (aarch64 = 129).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 129_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") i64::from(sig),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_tgkill(tgid: i32, tid: i32, sig: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_tgkill (x86_64 = 234). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 234_i64,
            in("rdi") i64::from(tgid),
            in("rsi") i64::from(tid),
            in("rdx") i64::from(sig),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_tgkill(tgid: i32, tid: i32, sig: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_tgkill (aarch64 = 131).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 131_i64,
            inout("x0") i64::from(tgid) => ret,
            in("x1") i64::from(tid),
            in("x2") i64::from(sig),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_rt_sigqueueinfo(pid: i32, sig: i32, info: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigqueueinfo (x86_64 = 129). Le kernel lit 128
    // octets à `info` (siginfo_t). Pas d'écriture user (`readonly`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 129_i64,
            in("rdi") i64::from(pid),
            in("rsi") i64::from(sig),
            in("rdx") info,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_rt_sigqueueinfo(pid: i32, sig: i32, info: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_rt_sigqueueinfo (aarch64 = 138).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 138_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") i64::from(sig),
            in("x2") info,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_read(fd: i32, buffer: u64, count: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_read (x86_64 = 0). Le kernel écrit jusqu'à `count`
    // octets à `buffer`. Pour signalfd, exactement 128 octets pour un
    // événement complet.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 0_i64,
            in("rdi") i64::from(fd),
            in("rsi") buffer,
            in("rdx") count,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_read(fd: i32, buffer: u64, count: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_read (aarch64 = 63).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 63_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") buffer,
            in("x2") count,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helper de conversion errno (réplique de celui de process.rs ; un
// futur refactor pourra centraliser).
// ─────────────────────────────────────────────────────────────────────────

fn errno_from_negative_syscall_ret(ret: i64) -> Errno {
    debug_assert!(ret < 0 && ret > -4096);
    #[allow(clippy::cast_possible_truncation)]
    let raw = ret.wrapping_neg() as i32;
    let nz = NonZeroI32::new(raw).expect("errno strictement positif par construction");
    Errno::from_nonzero(nz)
}

// ─────────────────────────────────────────────────────────────────────────
// Tests.
// ─────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    use crate::process::{clone3, getpid, gettid, waitid};
    use air_sys_types::signal::async_handler::SigActionFlags;
    use air_sys_types::{
        CloneArgs, CloneFlags, CloneResult, SignalValue, WaitEvent, WaitOptions, WaitTarget,
    };
    use core::ffi::{c_int, c_void};
    use core::sync::atomic::{AtomicBool, Ordering};
    use std::sync::Mutex;

    /// Sérialise les tests qui installent un handler **process-wide** : sans ce
    /// verrou, deux tests parallèles s'écraseraient mutuellement la disposition
    /// du signal (le handler est un état par-process). Empoisonnement toléré (on
    /// récupère l'inner) : un panic d'un test précédent ne doit pas bloquer les
    /// suivants.
    static ASYNC_INSTALL_LOCK: Mutex<()> = Mutex::new(());

    /// Drapeau armé par [`async_test_handler`] : prouve que le noyau a **appelé**
    /// le handler async (délivrance réelle, ADR-066).
    static ASYNC_HANDLER_FIRED: AtomicBool = AtomicBool::new(false);

    /// Handler async de test — **async-signal-safe** (un unique store atomique,
    /// aucune allocation, aucune I/O). Installé pour `SIGUSR1` et déclenché par
    /// auto-`tgkill` (chemin déterministe).
    extern "C" fn async_test_handler(_signum: c_int, _info: *mut c_void, _context: *mut c_void) {
        ASYNC_HANDLER_FIRED.store(true, Ordering::SeqCst);
    }

    /// Flush du profil de couverture LLVM de l'enfant forké **avant**
    /// `exit_group` (qui court-circuite l'atexit LLVM). Sans ce flush, le
    /// corps des wrappers exercés dans l'enfant (install/restore handler,
    /// signalfd, kill, rt_sigqueueinfo…) apparaît non couvert.
    /// `LLVM_PROFILE_FILE` contient `%p` → un `.profraw` par enfant, fusionné.
    /// Aucun verrou I/O dans cette famille → le flush en fin d'enfant suffit.
    // Intentionnellement VIDE — **async-signal-safety**. Un enfant forké via
    // `clone3` hérite d'un espace d'adressage COPIÉ : si un thread frère tenait le
    // lock interne de `malloc` au moment du `clone3`, ce lock est copié VERROUILLÉ
    // (son détenteur n'existe pas dans l'enfant) ; `__llvm_profile_write_file`
    // **alloue** → le premier `malloc` de l'enfant deadlocke sur ce futex. On NE
    // flushe donc PAS dans l'enfant : ses lignes sont des exceptions **CHILD-EXIT**
    // (ADR-035), prouvées par le code de sortie observé via `waitid`. NE PAS
    // réintroduire de flush ici (flaky deadlock couche 0).
    fn flush_child_coverage() {}

    /// Sortie d'un enfant forké de test : termine via `exit_group`. NE FLUSHE PLUS
    /// le profil (cf. [`flush_child_coverage`], désormais vide pour rester
    /// async-signal-safe). Les lignes de l'enfant sont des exceptions CHILD-EXIT.
    fn child_exit(status: i32) -> ! {
        flush_child_coverage();
        crate::process::exit_group(status)
    }

    /// Guard RAII : capture le mask courant du thread à la construction,
    /// le restaure intégralement à la destruction via `SIG_SETMASK`.
    ///
    /// **Utilisation systématique en TOUTE PREMIÈRE LIGNE** de chaque
    /// test qui touche au mask de signaux (sinon contamination du
    /// worker thread cargo pour les tests suivants).
    struct MaskGuard {
        original: SignalMask,
    }
    impl MaskGuard {
        fn new() -> Self {
            Self {
                original: current_signal_mask().expect("current_signal_mask doit réussir"),
            }
        }
    }
    impl Drop for MaskGuard {
        fn drop(&mut self) {
            // SIG_SETMASK = remplacement TOTAL (jamais SIG_BLOCK/UNBLOCK
            // relatif). C'est le seul moyen de restaurer fidèlement le
            // mask initial.
            let _ = set_signal_mask(&self.original);
        }
    }

    // ── current_signal_mask / set_signal_mask ─────────────────────────

    #[test]
    fn current_signal_mask_returns_ok() {
        let _guard = MaskGuard::new();
        let _mask = current_signal_mask().expect("current_signal_mask doit réussir");
    }

    #[test]
    fn mask_block_unblock_round_trip() {
        let _guard = MaskGuard::new();
        let target = SignalMask::from_signals(&[Signal::SIGUSR1]);

        let before = current_signal_mask().expect("read");
        assert!(
            !before.contains(Signal::SIGUSR1),
            "SIGUSR1 ne doit pas être bloqué initialement"
        );

        let _previous = block_signals(&target).expect("block");
        let after_block = current_signal_mask().expect("read");
        assert!(
            after_block.contains(Signal::SIGUSR1),
            "SIGUSR1 doit être bloqué après block_signals"
        );

        let _previous = unblock_signals(&target).expect("unblock");
        let after_unblock = current_signal_mask().expect("read");
        assert!(!after_unblock.contains(Signal::SIGUSR1));
    }

    #[test]
    fn set_signal_mask_replaces_total() {
        let _guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        let _old = set_signal_mask(&mask).expect("set");
        let read_back = current_signal_mask().expect("read");
        assert_eq!(read_back.bits(), mask.bits());
    }

    // ── signalfd + delivery via tgkill (per-thread isolation) ─────────

    #[test]
    fn signalfd_blocking_create_and_read_via_tgkill_self_tid() {
        let _guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        let sfd = signalfd_create_blocking(&mask, SignalFdFlags::empty())
            .expect("signalfd_create_blocking");

        // tgkill cible CE thread précisément ; pas de routage à un autre
        // thread = déterminisme + isolation des workers cargo.
        tgkill(getpid(), gettid(), Some(Signal::SIGUSR1)).expect("tgkill");
        let info = sfd.read().expect("read signalfd");
        assert_eq!(info.signal, Signal::SIGUSR1);
    }

    #[test]
    fn signalfd_update_mask_after_creation() {
        let _guard = MaskGuard::new();
        let initial = SignalMask::from_signals(&[Signal::SIGUSR1]);
        let mut sfd = signalfd_create_blocking(&initial, SignalFdFlags::empty()).expect("create");

        let updated = SignalMask::from_signals(&[Signal::SIGUSR1, Signal::SIGCHLD]);
        block_signals(&updated).expect("block SIGCHLD too");
        sfd.update_mask(&updated).expect("update_mask");
        // Pas de delivery test ici — on vérifie juste que le syscall
        // update_mask réussit sans erreur. Le read suivant exercerait
        // une délivrance, déjà couvert par le test précédent.
    }

    #[test]
    fn signalfd_into_fd_returns_owned_fd() {
        let _guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        let sfd = signalfd_create(&mask, SignalFdFlags::empty()).expect("create");
        let _owned: OwnedFd = sfd.into_fd();
    }

    #[test]
    fn signalfd_as_fd_borrows() {
        let _guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        let sfd = signalfd_create(&mask, SignalFdFlags::empty()).expect("create");
        let _borrowed = sfd.as_fd();
    }

    // ── wait_for_signal ───────────────────────────────────────────────

    #[test]
    fn wait_for_signal_bloquant_recoit_sigusr1() {
        let _guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        block_signals(&mask).expect("block");
        tgkill(getpid(), gettid(), Some(Signal::SIGUSR1)).expect("tgkill");
        let info = wait_for_signal(&mask, None).expect("wait_for_signal");
        assert_eq!(info.signal, Signal::SIGUSR1);
    }

    #[test]
    fn wait_for_signal_with_timeout_returns_einval_not_yet_implemented() {
        let _guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        let err = wait_for_signal(&mask, Some(Duration::from_millis(10)))
            .expect_err("timeout pas encore supporté");
        assert_eq!(err, Errno::EINVAL);
    }

    // ── kill / tgkill / signal 0 (Option<Signal> None) ────────────────

    #[test]
    fn kill_signal_none_tests_process_existence() {
        // signal=None ⇔ "signal 0" = test d'existence sans envoi.
        // Sur self, doit réussir.
        kill(getpid(), None).expect("kill self avec signal 0 doit réussir");
    }

    #[test]
    fn kill_on_nonexistent_pid_returns_esrch() {
        let nope = Pid::try_from_raw(0x7FFF_FFFE).expect("pid littéral");
        let err = kill(nope, None).expect_err("kill PID inexistant");
        assert_eq!(err, Errno::ESRCH);
    }

    #[test]
    fn kill_process_group_self_and_nonexistent() {
        // `group = None` + `signal = None` : test d'existence du **groupe de l'appelant**
        // (aucun signal envoyé) ⇒ succès.
        kill_process_group(None, None).expect("groupe de l'appelant existe");
        // Groupe **inexistant** (id positif jamais alloué) ⇒ `ESRCH`.
        let nope = Pid::try_from_raw(0x7FFF_FFFE).expect("pgid littéral");
        assert_eq!(
            kill_process_group(Some(nope), None).expect_err("groupe inexistant"),
            Errno::ESRCH
        );
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn sigaltstack_query_install_disable_and_reject_small() {
        // Interroge la pile alternative **actuelle** (`old` seul) — succès (chemin `old`).
        let mut current = AltStack::disabled();
        sigaltstack(None, Some(&mut current)).expect("interroge la pile alternative");

        // Installe une pile alternative de **16 Kio** (> `MINSIGSTKSZ`) et récupère l'ancienne.
        let mut buffer = vec![0_u8; 16384];
        let stack = AltStack::new(buffer.as_mut_ptr(), buffer.len());
        let mut previous = AltStack::disabled();
        sigaltstack(Some(&stack), Some(&mut previous)).expect("installe la pile alternative");

        // **Désactive** (restaure l'état du thread) AVANT que `buffer` ne soit libéré.
        sigaltstack(Some(&AltStack::disabled()), None).expect("désactive la pile alternative");

        // Taille **trop petite** (8 octets < `MINSIGSTKSZ`) ⇒ erreur (chemin `Err`) :
        // `ENOMEM` sur les kernels récents, `EINVAL` sur les anciens.
        let mut tiny = [0_u8; 8];
        let small = AltStack::new(tiny.as_mut_ptr(), tiny.len());
        let err = sigaltstack(Some(&small), None).expect_err("pile trop petite");
        assert!(
            err == Errno::ENOMEM || err == Errno::EINVAL,
            "attendu ENOMEM/EINVAL, obtenu : {err:?}"
        );
    }

    #[test]
    fn tgkill_signal_none_to_self_tid_succeeds() {
        // signal=None sur self_tid = test d'existence.
        tgkill(getpid(), gettid(), None).expect("tgkill self avec signal 0");
    }

    #[test]
    fn tgkill_on_nonexistent_tid_returns_esrch() {
        // Couvre la branche d'erreur (`ret < 0`) de `tgkill` : un tid
        // au-delà de `PID_MAX_LIMIT` (~2^22) n'existe pas → ESRCH.
        let nope = Tid::try_from_raw(0x7FFF_FFFE).expect("tid littéral");
        let err = tgkill(getpid(), nope, None).expect_err("tgkill TID inexistant");
        assert_eq!(err, Errno::ESRCH);
    }

    #[test]
    fn signalfd_nonblocking_read_with_no_pending_signal_returns_eagain() {
        // Couvre la branche d'erreur (`ret < 0`) de `SignalFd::read` : un
        // signalfd NONBLOCK sans signal pendant retourne EAGAIN
        // immédiatement (aucun signal n'est bloqué/envoyé ici).
        let _guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        let sfd = signalfd_create(&mask, SignalFdFlags::NONBLOCK).expect("create nonblock");
        let err = sfd.read().expect_err("aucun signal pendant → EAGAIN");
        assert_eq!(err, Errno::EAGAIN);
    }

    #[test]
    fn tgkill_delivers_sigusr1_to_self_tid() {
        let _guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        let sfd = signalfd_create_blocking(&mask, SignalFdFlags::empty()).expect("create");
        tgkill(getpid(), gettid(), Some(Signal::SIGUSR1)).expect("tgkill");
        let info = sfd.read().expect("read");
        assert_eq!(info.signal, Signal::SIGUSR1);
    }

    #[test]
    fn kill_in_forked_child_delivers_signal_to_self() {
        // `kill(getpid(), sig)` est dangereux en multi-thread (routing
        // non contrôlé). En enfant fork'é mono-thread, c'est sûr.
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique.
        let result = unsafe { clone3(&args) }.expect("clone3");
        match result {
            CloneResult::Child => {
                // Enfant : block SIGUSR1, create signalfd, kill(self),
                // read, exit avec code 0 si OK.
                let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
                if block_signals(&mask).is_err() {
                    child_exit(50);
                }
                let sfd = match signalfd_create(&mask, SignalFdFlags::empty()) {
                    Ok(s) => s,
                    Err(_) => child_exit(51),
                };
                if kill(getpid(), Some(Signal::SIGUSR1)).is_err() {
                    child_exit(52);
                }
                match sfd.read() {
                    Ok(info) if info.signal == Signal::SIGUSR1 => child_exit(0),
                    Ok(_) => child_exit(53),
                    Err(_) => child_exit(54),
                }
            }
            CloneResult::Parent { child_pid, .. } => {
                let status =
                    waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED).expect("waitid");
                let s = status.expect("event");
                assert!(
                    matches!(s.event, WaitEvent::Exited { code: 0 }),
                    "kill in forked child should succeed, event={:?}",
                    s.event
                );
            }
        }
    }

    // ── rt_sigqueueinfo ────────────────────────────────────────────────

    #[test]
    fn rt_sigqueueinfo_with_integer_value_in_forked_child() {
        // `rt_sigqueueinfo` cible un PROCESS (`pid`), pas un thread.
        // En multi-thread (cargo test workers parallèles), le kernel
        // route le signal vers un thread qui ne le bloque pas → un
        // worker collatéral pourrait recevoir SIGUSR1 et terminer le
        // process de test. Isolation par fork-enfant mono-thread.
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique.
        let result = unsafe { clone3(&args) }.expect("clone3");
        match result {
            CloneResult::Child => {
                let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
                if block_signals(&mask).is_err() {
                    child_exit(70);
                }
                let sfd = match signalfd_create(&mask, SignalFdFlags::empty()) {
                    Ok(s) => s,
                    Err(_) => child_exit(71),
                };
                let info = SignalInfo::new_queue(SignalValue::Integer(0xABCD));
                if rt_sigqueueinfo(getpid(), Signal::SIGUSR1, &info).is_err() {
                    child_exit(72);
                }
                match sfd.read() {
                    Ok(e) if e.signal == Signal::SIGUSR1 && e.int == 0xABCD && e.code == -1 => {
                        child_exit(0);
                    }
                    Ok(_) => child_exit(73),
                    Err(_) => child_exit(74),
                }
            }
            CloneResult::Parent { child_pid, .. } => {
                let status =
                    waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED).expect("waitid");
                let s = status.expect("event");
                assert!(
                    matches!(s.event, WaitEvent::Exited { code: 0 }),
                    "rt_sigqueueinfo Integer doit aboutir, event={:?}",
                    s.event
                );
            }
        }
    }

    #[test]
    fn rt_sigqueueinfo_with_pointer_value_in_forked_child() {
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique.
        let result = unsafe { clone3(&args) }.expect("clone3");
        match result {
            CloneResult::Child => {
                let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
                if block_signals(&mask).is_err() {
                    child_exit(80);
                }
                let sfd = match signalfd_create(&mask, SignalFdFlags::empty()) {
                    Ok(s) => s,
                    Err(_) => child_exit(81),
                };
                let payload: u64 = 0xCAFE_BABE_DEAD_BEEF;
                let info = SignalInfo::new_queue(SignalValue::Pointer(payload));
                if rt_sigqueueinfo(getpid(), Signal::SIGUSR1, &info).is_err() {
                    child_exit(82);
                }
                match sfd.read() {
                    Ok(e) if e.signal == Signal::SIGUSR1 && e.ptr == payload && e.code == -1 => {
                        child_exit(0);
                    }
                    Ok(_) => child_exit(83),
                    Err(_) => child_exit(84),
                }
            }
            CloneResult::Parent { child_pid, .. } => {
                let status =
                    waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED).expect("waitid");
                let s = status.expect("event");
                assert!(
                    matches!(s.event, WaitEvent::Exited { code: 0 }),
                    "rt_sigqueueinfo Pointer doit aboutir, event={:?}",
                    s.event
                );
            }
        }
    }

    #[test]
    fn rt_sigqueueinfo_on_nonexistent_pid_returns_esrch() {
        let nope = Pid::try_from_raw(0x7FFF_FFFE).expect("pid littéral");
        let info = SignalInfo::new_queue(SignalValue::Integer(0));
        let err = rt_sigqueueinfo(nope, Signal::SIGUSR1, &info)
            .expect_err("rt_sigqueueinfo PID inexistant");
        assert_eq!(err, Errno::ESRCH);
    }

    // ── synchronous_handler ────────────────────────────────────────────

    #[test]
    fn install_and_restore_fatal_handler_in_forked_child() {
        // Les handlers sont PROCESS-WIDE. Pour ne pas contaminer le
        // process de test, on installe/restaure dans un enfant fork'é.
        use air_sys_types::signal::synchronous_handler::FatalSignal;
        use synchronous_handler::noop_handler;

        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique.
        let result = unsafe { clone3(&args) }.expect("clone3");
        match result {
            CloneResult::Child => {
                // SAFETY: noop_handler est trivialement async-signal-safe
                // (ne fait rien).
                let previous = unsafe {
                    synchronous_handler::install_fatal_handler(FatalSignal::Segv, noop_handler)
                };
                let Ok(previous) = previous else {
                    child_exit(60);
                };
                // Restaurer immédiatement (pas de signal déclenché, on
                // valide juste la roundtrip d'install/restore).
                // SAFETY: previous a été obtenu par install_fatal_handler
                // sur le même FatalSignal::Segv.
                if unsafe { synchronous_handler::restore_handler(FatalSignal::Segv, previous) }
                    .is_err()
                {
                    child_exit(61);
                }
                child_exit(0);
            }
            CloneResult::Parent { child_pid, .. } => {
                let status =
                    waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED).expect("waitid");
                let s = status.expect("event");
                assert!(
                    matches!(s.event, WaitEvent::Exited { code: 0 }),
                    "install + restore fatal handler doit réussir, event={:?}",
                    s.event
                );
            }
        }
    }

    #[test]
    fn noop_handler_is_callable_directly() {
        // `noop_handler` n'est jamais invoqué par le kernel dans les tests
        // (aucun signal fatal n'est déclenché — hors périmètre). Son corps
        // (vide, trivialement async-signal-safe) est couvert en l'appelant
        // directement avec des pointeurs nuls qu'il ne déréférence pas.
        use synchronous_handler::noop_handler;
        // SAFETY: `noop_handler` a un corps vide ; il ne lit ni n'écrit
        // aucun des pointeurs passés. Appel trivialement sûr.
        unsafe {
            noop_handler(0, core::ptr::null_mut(), core::ptr::null_mut());
        }
    }

    // ── errno_from_negative_syscall_ret (réplique locale) ─────────────

    #[test]
    fn errno_from_negative_syscall_ret_maps_known_codes() {
        assert_eq!(errno_from_negative_syscall_ret(-1), Errno::EPERM);
        assert_eq!(errno_from_negative_syscall_ret(-3), Errno::ESRCH);
        assert_eq!(errno_from_negative_syscall_ret(-4), Errno::EINTR);
        assert_eq!(errno_from_negative_syscall_ret(-22), Errno::EINVAL);
    }

    // Les deux tests suivants couvrent les deux opérandes du
    // `debug_assert!(ret < 0 && ret > -4096)` : chacun force un côté faux
    // (`ret == 0` viole `ret < 0` ; `ret == -5000` viole `ret > -4096`).
    #[test]
    #[should_panic(expected = "ret < 0 && ret > -4096")]
    fn errno_from_negative_syscall_ret_panics_on_non_negative() {
        let _ = errno_from_negative_syscall_ret(0);
    }

    #[test]
    #[should_panic(expected = "ret < 0 && ret > -4096")]
    fn errno_from_negative_syscall_ret_panics_below_errno_range() {
        let _ = errno_from_negative_syscall_ret(-5000);
    }

    // ── parse_signalfd_siginfo : unit-tests sur buffer synthétique ────

    #[test]
    fn parse_signalfd_siginfo_decodes_sigusr1_event() {
        let mut buffer = [0_u8; 128];
        // ssi_signo = SIGUSR1 = 10 à offset 0.
        buffer[0..4].copy_from_slice(&10_u32.to_ne_bytes());
        // ssi_pid = 1234 à offset 12.
        buffer[12..16].copy_from_slice(&1234_u32.to_ne_bytes());
        // ssi_uid = 1000 à offset 16.
        buffer[16..20].copy_from_slice(&1000_u32.to_ne_bytes());
        // ssi_int = 0xABCD à offset 44.
        buffer[44..48].copy_from_slice(&0xABCD_i32.to_ne_bytes());

        let info = parse_signalfd_siginfo(&buffer);
        assert_eq!(info.signal, Signal::SIGUSR1);
        assert_eq!(info.pid.map(|p| p.as_raw()), Some(1234));
        assert_eq!(info.uid, 1000);
        assert_eq!(info.int, 0xABCD);
    }

    #[test]
    fn parse_signalfd_siginfo_kernel_origin_pid_is_none() {
        let mut buffer = [0_u8; 128];
        buffer[0..4].copy_from_slice(&10_u32.to_ne_bytes()); // SIGUSR1
        // ssi_pid = 0 (origine kernel) → pid = None (convention 1 ADR-021).
        let info = parse_signalfd_siginfo(&buffer);
        assert!(info.pid.is_none());
    }

    // ── async_handler (ADR-066) : install/restore + délivrance async réelle ───

    #[test]
    fn async_handler_install_fires_and_restores_in_thread() {
        // Sérialisé (disposition process-wide) ; chemin 100 % déterministe et
        // host-couvert : install → auto-`tgkill` → handler exécuté → restore.
        let _serialize = ASYNC_INSTALL_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let _mask_guard = MaskGuard::new();
        // SIGUSR1 doit être **débloqué** dans ce thread : sinon le signal reste
        // pendant au lieu d'invoquer le handler.
        unblock_signals(&SignalMask::from_signals(&[Signal::SIGUSR1])).expect("unblock SIGUSR1");
        ASYNC_HANDLER_FIRED.store(false, Ordering::SeqCst);

        let handler: extern "C" fn(c_int, *mut c_void, *mut c_void) = async_test_handler;
        let handler_sa = handler as usize;
        // SAFETY: `async_test_handler` est async-signal-safe (un seul store
        // atomique). SIGUSR1 est un signal non-faute gérable.
        let previous = unsafe {
            async_handler::install(
                Signal::SIGUSR1,
                handler_sa,
                SigActionFlags::SIGINFO,
                SignalMask::empty(),
            )
        }
        .expect("install async handler");

        // Auto-délivrance ciblée sur CE thread (déterministe, pas de contamination
        // d'un worker frère). Au retour de `tgkill`, le signal débloqué a déjà été
        // délivré → le handler a tourné **et** est revenu (sur x86_64, via le
        // trampoline `rt_sigreturn` d'Air : atteindre l'assert prouve le retour).
        tgkill(getpid(), gettid(), Some(Signal::SIGUSR1)).expect("tgkill self");
        assert!(
            ASYNC_HANDLER_FIRED.load(Ordering::SeqCst),
            "le handler async non-faute doit être exécuté par le noyau"
        );

        // SAFETY: `previous` provient de l'`install` ci-dessus, sur le même signal.
        unsafe { async_handler::restore(Signal::SIGUSR1, previous) }.expect("restore");
    }

    #[test]
    fn async_handler_install_ign_then_dfl_round_trip() {
        // Couvre les valeurs `sa_handler` SIG_IGN(1)/SIG_DFL(0) et la restauration.
        let _serialize = ASYNC_INSTALL_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        // SAFETY: SIG_IGN/SIG_DFL sont des constantes noyau — aucun code
        // utilisateur, trivialement sûres.
        let prev_original = unsafe {
            async_handler::install(
                Signal::SIGUSR1,
                async_handler::SIG_IGN,
                SigActionFlags::empty(),
                SignalMask::empty(),
            )
        }
        .expect("install SIG_IGN");
        // SAFETY: idem — SIG_DFL.
        let prev_ign = unsafe {
            async_handler::install(
                Signal::SIGUSR1,
                async_handler::SIG_DFL,
                SigActionFlags::empty(),
                SignalMask::empty(),
            )
        }
        .expect("install SIG_DFL");
        // Restaure en pile inverse : SIG_IGN puis la disposition d'origine.
        // SAFETY: chaque `previous` vient d'un `install` sur SIGUSR1.
        unsafe { async_handler::restore(Signal::SIGUSR1, prev_ign) }.expect("restore SIG_IGN");
        unsafe { async_handler::restore(Signal::SIGUSR1, prev_original) }.expect("restore origin");
    }

    #[test]
    fn async_handler_install_on_sigkill_returns_einval() {
        // Couvre le bras d'erreur (`ret < 0`) d'`install` : `SIGKILL` n'est pas
        // catchable → le noyau rejette `rt_sigaction` avec EINVAL, sans changer
        // aucune disposition (sûr sans sérialisation).
        // SAFETY: SIG_DFL — aucun handler utilisateur.
        let err = unsafe {
            async_handler::install(
                Signal::SIGKILL,
                async_handler::SIG_DFL,
                SigActionFlags::empty(),
                SignalMask::empty(),
            )
        }
        .expect_err("SIGKILL non catchable");
        assert_eq!(err, Errno::EINVAL);
    }

    // ── rt_sigpending (ADR-066) ────────────────────────────────────────

    #[test]
    fn rt_sigpending_reports_blocked_pending_signal() {
        let _mask_guard = MaskGuard::new();
        let mask = SignalMask::from_signals(&[Signal::SIGUSR1]);
        // Bloque SIGUSR1 + crée un signalfd (pour drainer proprement à la fin).
        let sfd = signalfd_create_blocking(&mask, SignalFdFlags::empty()).expect("signalfd");

        let before = rt_sigpending().expect("rt_sigpending initial");
        assert!(
            !before.contains(Signal::SIGUSR1),
            "aucun SIGUSR1 pendant au départ"
        );

        tgkill(getpid(), gettid(), Some(Signal::SIGUSR1)).expect("tgkill self");
        let after = rt_sigpending().expect("rt_sigpending après tgkill");
        assert!(
            after.contains(Signal::SIGUSR1),
            "SIGUSR1 bloqué et généré doit apparaître pendant"
        );

        // Draine le signal pendant AVANT que `MaskGuard` ne restaure le masque :
        // sinon débloquer SIGUSR1 le délivrerait avec l'action par défaut
        // (terminate), tuant le process de test.
        let info = sfd.read().expect("drain signalfd");
        assert_eq!(info.signal, Signal::SIGUSR1);
    }
}