air_sys_syscall/

process.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 `process`.
//!
//! Cf. `docs/specs/layer-0/family-process.md`. Couvre l'identité (`getpid`,
//! `gettid`), la création/attente (`clone3`, `waitid`, `exit_group`), l'`exec`
//! et la redirection (`execve`, `execveat`, `dup3`, `fchdir`, `chdir`), les
//! groupes/sessions, `prctl` (opérations individuelles), les rlimits, les
//! capabilities et l'affinité CPU.
//!
//! Les wrappers exécutent les syscalls Linux directement via
//! `core::arch::asm!` ; la libc n'est pas dans le chemin d'appel
//! (cf. CLAUDE.md : « variantes modernes préférées, syscalls non wrappés
//! listés dans UNSUPPORTED.md »).

use air_sys_types::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd, RawFd};
use alloc::vec::Vec;
use core::convert::Infallible;
use core::ffi::c_char;
use core::marker::PhantomData;
use core::num::NonZeroI32;

use alloc::ffi::CString;
use core::ffi::CStr;

use air_sys_types::fs::{DirFd, Mode};
use air_sys_types::system::CpuSet;
use air_sys_types::{
    Capability, CapabilityMask, CapabilitySet, CapabilityTarget, CloneArgs, CloneFlags,
    CloneResult, DumpableMode, Dup3Flags, Errno, ExecveatFlags, Gid, Pid, PidFd, PidFdOpenFlags,
    ResGid, ResUid, Resource, Rlimit, RlimitValue, Rusage, RusageWho, Signal, SignalInfo,
    StackSpecification, Tid, Uid, WaitEvent, WaitOptions, WaitStatus, WaitTarget,
};

#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
compile_error!(
    "air-sys-syscall ne supporte que x86_64 et aarch64 (cf. ADR-014 catalogue matériel)."
);

/// Retourne le PID du processus appelant.
///
/// Fonction **totale** : le syscall `getpid(2)` ne peut pas échouer et POSIX
/// garantit que le PID retourné est strictement positif. C'est pourquoi la
/// signature retourne `Pid` directement, sans `Result`.
///
/// # Performance
///
/// Très peu coûteux (~30-50 ns via vDSO sur les kernels récents) ; ici on
/// appelle le syscall en direct sans passer par la vDSO, donc on est du
/// côté haut de cette fourchette.
#[must_use]
pub fn getpid() -> Pid {
    let raw = raw_syscall_getpid();
    // POSIX/Linux : `getpid` retourne un `pid_t` (i32) strictement positif.
    // La troncature de i64 à i32 est intentionnelle ; les 32 bits hauts sont
    // garantis nuls pour un PID valide.
    #[allow(clippy::cast_possible_truncation)]
    let pid_raw = raw as i32;
    // Construction *vérifiée* du `NonZeroI32` : un `new_unchecked` ici
    // (Principe 5 : pas d'optimisation avant mesure, et plus grave : si l'asm!
    // au-dessus est jamais mal câblé, `new_unchecked(0)` est un UB silencieux,
    // alors qu'un `.expect()` rend la violation d'invariant bruyante et
    // diagnostiquable). La branche d'échec n'est pas exécutable sur un kernel
    // POSIX conforme.
    let nz = NonZeroI32::new(pid_raw)
        .expect("kernel a violé l'invariant POSIX : getpid doit retourner > 0");
    Pid::from_nonzero(nz)
}

/// Retourne le TID du thread appelant.
///
/// Fonction **totale** : le syscall `gettid(2)` ne peut pas échouer et le
/// kernel garantit un TID strictement positif. Sur Linux, chaque thread a un
/// TID distinct ; le thread principal d'un processus a `gettid() == getpid()`.
///
/// Le type de retour [`Tid`] est **distinct** de [`Pid`] pour empêcher par
/// typage la confusion entre identifiant de thread et identifiant de
/// processus (cf. ADR-021 convention 1, et Principe d'ingénierie 7).
#[must_use]
pub fn gettid() -> Tid {
    let raw = raw_syscall_gettid();
    // Même invariant que getpid : TID strictement positif, fits in i32.
    #[allow(clippy::cast_possible_truncation)]
    let tid_raw = raw as i32;
    // Construction *vérifiée* (cf. justification dans `getpid` ci-dessus).
    let nz = NonZeroI32::new(tid_raw)
        .expect("kernel a violé l'invariant POSIX : gettid doit retourner > 0");
    Tid::from_nonzero(nz)
}

// ── Helpers spécifiques à l'architecture ─────────────────────────────────
//
// Une fonction par couple (syscall, architecture). Pas de wrapper générique
// (cf. convention 3 ADR-021 : pas de wrapper générique pour les syscalls
// multiplexés ; ici les helpers sont privés et chaque syscall a sa propre
// fonction dédiée, donc l'esprit de la convention est respecté).

#[cfg(target_arch = "x86_64")]
#[inline]
fn raw_syscall_getpid() -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_getpid (x86_64 = 39) ne touche à aucune mémoire utilisateur.
    // - L'ABI syscall x86_64 prend le numéro de syscall dans RAX, retourne
    //   en RAX, et clobbe RCX (RIP de retour) et R11 (RFLAGS sauvegardé).
    //   Les autres registres caller-saved sont préservés.
    // - `nostack` est correct car le syscall n'utilise pas la pile.
    // - `readonly` est correct car ce syscall ne modifie aucune mémoire
    //   accessible au programme.
    // - `preserves_flags` est correct car le kernel restaure RFLAGS via R11
    //   au retour (le clobber explicite de R11 ci-dessus le couvre).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 39_i64,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
fn raw_syscall_gettid() -> i64 {
    let ret: i64;
    // SAFETY: identique à `raw_syscall_getpid` ci-dessus, avec SYS_gettid
    // (x86_64 = 186) à la place. Aucune mémoire utilisateur n'est touchée.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 186_i64,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
fn raw_syscall_getpid() -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_getpid (aarch64 = 172) ne touche à aucune mémoire utilisateur.
    // - L'ABI syscall aarch64 prend le numéro dans X8 et retourne en X0.
    //   Les registres caller-saved en dehors de X0 sont préservés.
    // - `nostack`, `readonly`, `preserves_flags` : mêmes justifications que
    //   pour la branche x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 172_i64,
            lateout("x0") ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
fn raw_syscall_gettid() -> i64 {
    let ret: i64;
    // SAFETY: identique à `raw_syscall_getpid` ci-dessus, avec SYS_gettid
    // (aarch64 = 178) à la place. Aucune mémoire utilisateur n'est touchée.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 178_i64,
            lateout("x0") ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// clone3
// ─────────────────────────────────────────────────────────────────────────

/// Structure d'arguments transmise au kernel (`struct clone_args` de
/// `linux/sched.h`). Représente le ABI Linux 5.7+ (88 octets).
///
/// Les champs sont des `u64` même quand ils encodent des pointeurs (les
/// adresses kernel n'utilisent que les premiers 48 bits sur x86_64/aarch64,
/// mais l'ABI réserve 64 bits pour forward-compat).
#[repr(C)]
#[derive(Default)]
struct KernelCloneArgs {
    flags: u64,
    pidfd: u64,
    child_tid: u64,
    parent_tid: u64,
    exit_signal: u64,
    stack: u64,
    stack_size: u64,
    tls: u64,
    set_tid: u64,
    set_tid_size: u64,
    cgroup: u64,
}

/// Construit la structure ABI kernel à partir de [`CloneArgs`] Air.
///
/// Extrait en fonction privée pour pouvoir tester unitairement le mapping
/// `exit_signal` (notamment la branche `None` qui ne peut pas être
/// observée bout-en-bout via fork — le kernel détache l'enfant quand
/// `exit_signal = 0` et `waitid` retourne alors `ECHILD`).
fn build_kernel_clone_args(args: &CloneArgs, pidfd_addr: u64) -> KernelCloneArgs {
    let exit_signal_u64: u64 = args.exit_signal.map_or(0, |sig| {
        // sig.as_raw() > 0 par construction (NonZeroI32) → cast sign-safe.
        #[allow(clippy::cast_sign_loss)]
        {
            sig.as_raw() as u64
        }
    });

    // Pile : `None` → 0/0 (fork classique) ; `Some` → base + taille (thread).
    // `clone3` valide que `stack == None` (fork) ; `clone_thread` exige `Some`.
    let (stack_addr, stack_size) = match args.stack {
        Some(s) => (s.addr as u64, s.size as u64),
        None => (0, 0),
    };

    KernelCloneArgs {
        flags: args.flags.bits(),
        pidfd: pidfd_addr,
        child_tid: args.child_tid.map_or(0, |r| r.as_ptr() as u64),
        parent_tid: args.parent_tid.map_or(0, |r| r.as_ptr() as u64),
        exit_signal: exit_signal_u64,
        stack: stack_addr,
        stack_size,
        tls: args.tls.unwrap_or(0),
        set_tid: 0,
        set_tid_size: 0,
        cgroup: 0,
    }
}

/// Crée un nouveau processus via le syscall `clone3(2)`.
///
/// Cf. `docs/specs/layer-0/family-process.md` section `clone3`. La fonction
/// retourne **deux fois** en cas de succès : une fois côté parent (avec le
/// PID enfant, et un `PidFd` si [`CloneFlags::PIDFD`] était positionné),
/// une fois côté enfant (avec [`CloneResult::Child`]). Le `match` sur le
/// résultat est le seul moyen sûr de discriminer.
///
/// # Périmètre
///
/// `clone3` est dédié à la **création de processus** style fork ; la création
/// de **thread** passe par [`clone_thread`] (modèle de retour distinct, cf. sa
/// doc et la note d'implémentation au-dessus de `clone_thread`) :
///
/// - `args.flags` peut contenir tous les bits hors [`CloneFlags::VM`] /
///   [`CloneFlags::THREAD`] / [`CloneFlags::SIGHAND`] : ces drapeaux de
///   création de thread sont refusés ici avec [`Errno::EINVAL`] (leur retour
///   `CloneResult::Child` serait *unsound* sur une pile neuve — voir
///   `clone_thread`).
/// - `args.stack` doit être `None` (refusé sinon avec [`Errno::EINVAL`] ; une
///   pile dédiée n'a de sens que pour un thread → `clone_thread`).
/// - `args.exit_signal` est typiquement `Some(Signal::SIGCHLD)`.
///
/// # Safety
///
/// `clone3` peut créer un thread partageant la mémoire avec le parent
/// (`CLONE_VM`), situation que Rust ne peut pas vérifier. L'appelant doit
/// donc garantir, selon le scénario :
///
/// - **Fork classique** (sans `CLONE_VM`) — aucune précondition
///   particulière sur la mémoire. L'enfant possède une copie CoW de
///   l'espace d'adressage du parent ; tous les invariants Rust restent
///   valables des deux côtés.
///
/// - **Création de thread** (`CLONE_VM | CLONE_THREAD | CLONE_SIGHAND`)
///   — non géré par `clone3` ; l'appel échoue avec [`Errno::EINVAL`]. Utiliser
///   [`clone_thread`], qui exécute le thread via un trampoline assembleur (pas
///   de retour Rust sur pile neuve) et expose le *join* par
///   `CLONE_CHILD_CLEARTID`.
///
/// - **Namespaces** (`CLONE_NEWUSER`, `CLONE_NEWNS`, `CLONE_NEWPID`, …)
///   — l'appelant doit posséder les capabilities nécessaires
///   (typiquement `CAP_SYS_ADMIN`) ; à défaut, le syscall retourne
///   [`Errno::EPERM`]. Sur Ubuntu 24.04, les user namespaces non
///   privilégiés sont restreints par AppArmor
///   (`kernel.apparmor_restrict_unprivileged_userns=1`) et l'appel
///   échoue avec [`Errno::EPERM`] même côté unprivileged.
///
/// - **« Retourne deux fois »** — après succès, le syscall est exécuté
///   côté parent **et** côté enfant ; les deux retours apparaissent ici
///   comme `Ok(_)` distincts. L'enfant doit terminer son travail
///   (typiquement par `std::process::exit` ou un futur `exit_group`
///   wrapper) ; revenir « plus loin » dans le code appelant produit
///   généralement un comportement surprenant pour l'utilisateur.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : combinaison de flags refusée par cette PR
///   (création de thread) ou par le kernel (configuration invalide).
/// - [`Errno::EPERM`] : capabilities insuffisantes (NEWUSER refusé,
///   AppArmor, …).
/// - `EAGAIN` (constante non encore définie dans le stub partiel `Errno`)
///   : limites système atteintes (nombre de processus).
/// - `ENOMEM` (idem) : mémoire kernel insuffisante.
/// - `EUSERS` (idem) : trop de namespaces utilisateurs créés.
/// - `ENOSYS` (idem) : kernel antérieur à 5.3 (`clone3` indisponible).
///
/// Les constantes nommées en prose ci-dessus seront promues en
/// `pub const` au fil des PRs qui les rencontrent réellement
/// (cf. note « stub partiel » en tête du module `errno`).
pub unsafe fn clone3(args: &CloneArgs) -> Result<CloneResult, Errno> {
    // Refus explicite des cas non testés (Principe 4 : valider en amont).
    if args.stack.is_some() {
        return Err(Errno::EINVAL);
    }
    if args
        .flags
        .intersects(CloneFlags::VM | CloneFlags::THREAD | CloneFlags::SIGHAND)
    {
        return Err(Errno::EINVAL);
    }

    let want_pidfd = args.flags.contains(CloneFlags::PIDFD);
    let mut pidfd_storage: i32 = -1;

    let pidfd_addr: u64 = if want_pidfd {
        // Adresse du i32 que le kernel renseignera côté parent en cas de succès.
        let ptr: *mut i32 = &mut pidfd_storage;
        ptr as u64
    } else {
        0
    };

    let kernel_args = build_kernel_clone_args(args, pidfd_addr);

    let args_ptr: *const KernelCloneArgs = &kernel_args;
    // size_of::<KernelCloneArgs>() = 88. Air ne cible que des cibles
    // 64-bit (cf. ADR-014) ; `usize == u64`, donc le cast est exact.
    #[allow(clippy::cast_lossless)]
    let args_size: u64 = core::mem::size_of::<KernelCloneArgs>() as u64;

    // SAFETY:
    // - args_ptr pointe sur `kernel_args` (local valide pour toute la fonction).
    // - args_size est exactement size_of::<KernelCloneArgs>().
    // - Si CLONE_PIDFD est positionné, pidfd_addr pointe sur `pidfd_storage`
    //   qui est local valide ; le kernel y écrit côté parent uniquement.
    // - Aucune autre adresse mémoire utilisateur n'est passée au kernel
    //   (parent_tid/child_tid/stack/set_tid/cgroup sont à 0).
    // - Sémantique « retourne deux fois » : voir doc de la fonction.
    let ret = unsafe { raw_syscall_clone3(args_ptr as u64, args_size) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    if ret == 0 {
        // Côté enfant : ne pas lire `pidfd_storage` (le kernel n'a écrit que
        // côté parent ; la copie CoW du child contient la valeur initiale).
        return Ok(CloneResult::Child);
    }

    // Côté parent : `ret` est le PID enfant, borné par `PID_MAX_LIMIT`
    // (= 2^22 sur 64-bit Linux), bien en deçà de `i32::MAX`. Troncature
    // intentionnelle, sûre par construction.
    #[allow(clippy::cast_possible_truncation)]
    let child_pid_raw = ret as i32;
    let child_pid = Pid::try_from_raw(child_pid_raw)
        .expect("clone3 retour parent : PID strictement positif (POSIX)");

    let child_pidfd = if want_pidfd {
        let raw_fd = pidfd_storage;
        // SAFETY: le kernel a écrit un fd valide dans `pidfd_storage` côté
        // parent après succès de clone3 avec CLONE_PIDFD. Air en prend
        // ownership ; OwnedFd::Drop fermera le fd.
        let owned = unsafe { OwnedFd::from_raw_fd(raw_fd) };
        Some(PidFd::from_owned_fd(owned))
    } else {
        None
    };

    Ok(CloneResult::Parent {
        child_pid,
        child_pidfd,
    })
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_clone3(args_ptr: u64, args_size: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_clone3 (x86_64 = 435). Le kernel lit `args_size` octets à
    //   l'adresse `args_ptr` (validité garantie par l'appelant) ; il peut
    //   écrire à des sous-pointeurs (pidfd/parent_tid/child_tid) si
    //   demandés. L'appelant a respecté ces préconditions.
    // - L'ABI syscall x86_64 prend le numéro dans RAX, arg1/arg2 dans
    //   RDI/RSI ; retourne en RAX ; clobbe RCX (RIP) et R11 (RFLAGS).
    // - **Pas de `readonly`** : clone3 écrit dans la mémoire utilisateur
    //   (output pointers) ; `readonly` serait incorrect ici.
    // - Sémantique « retourne deux fois » : le syscall revient côté
    //   parent (rax = pid > 0) et côté enfant (rax = 0). Les deux
    //   retours sortent normalement de cette fonction.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 435_i64,
            in("rdi") args_ptr,
            in("rsi") args_size,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_clone3(args_ptr: u64, args_size: u64) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 syscall ABI : numéro en X8,
    // arg1/arg2 en X0/X1, retour en X0. svc 0 effectue le syscall.
    // Comme x86_64, **pas de `readonly`** (clone3 écrit en mémoire user).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 435_i64,
            inout("x0") args_ptr => ret,
            in("x1") args_size,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// clone_thread — création d'un thread (CLONE_VM) via clone3 + trampoline asm.
//
// Pourquoi une fonction DISTINCTE de `clone3` (et non un simple
// `CloneResult::Child` étendu) ? Parce que le modèle « clone3 retourne deux
// fois dans du Rust » est **unsound** pour un thread doté d'une pile NEUVE :
// après le syscall, l'enfant reprend l'exécution avec `sp` = sommet de la pile
// fournie. Laisser le code Rust « revenir » (épilogue de fonction : restauration
// de registres callee-saved + `ret`/`blr x30`) lirait des **ordures** sur cette
// pile vierge → crash. La discipline universelle (glibc/musl) est donc :
// l'enfant ne **revient jamais** dans le code Rust appelant ; un trampoline en
// assembleur appelle directement un point d'entrée `extern "C"` fourni, puis
// termine le thread via `SYS_exit`. C'est ce que fait `clone_thread`.
//
// `clone3` reste, lui, dédié au **fork** (pas de pile neuve, l'enfant partage la
// copie CoW de la pile parent : `CloneResult::Child` y est sound) et **rejette**
// `stack`/`CLONE_VM` en amont.
// ─────────────────────────────────────────────────────────────────────────

/// Taille minimale (octets) acceptée pour la pile d'un thread `clone_thread`.
/// Une page suffit largement au point d'entrée minimal ; les piles réelles sont
/// dimensionnées par l'appelant (la libc Air, couche 1).
const MIN_THREAD_STACK_SIZE: usize = 4096;

/// Crée un **thread** (mémoire partagée, `CLONE_VM`) via `clone3(2)`.
///
/// Contrairement à [`clone3`] (réservé au fork), `clone_thread` ne « retourne
/// pas deux fois » : le nouveau thread exécute le point d'entrée `entry(arg)`
/// **sur sa pile dédiée** via un trampoline assembleur, puis — si `entry`
/// revient — termine le **seul** thread courant par `SYS_exit` (jamais
/// `exit_group`). Seul le **parent** revient de cette fonction, avec le [`Tid`]
/// du nouveau thread.
///
/// # Join (terminaison observable)
///
/// Les threads `CLONE_THREAD` ne sont **pas** *waitable* via `waitid`. Le *join*
/// se fait par `CLONE_CHILD_CLEARTID` : positionner [`CloneFlags::CHILD_CLEARTID`]
/// et renseigner [`CloneArgs::child_tid`] sur un mot [`core::sync::atomic::AtomicU32`]
/// partagé. À la mort du thread, le kernel remet ce mot à `0` et émet un
/// `FUTEX_WAKE` (de portée **partagée** — sans `FUTEX_PRIVATE_FLAG`) dessus. Pour
/// initialiser le mot avec le TID **sans course**, ajouter
/// [`CloneFlags::PARENT_SETTID`] avec [`CloneArgs::parent_tid`] sur le **même**
/// mot (écrit par le kernel, côté parent, avant le retour). Le parent joint
/// alors en bouclant `futex_wait` jusqu'à lire `0` (cf. la famille
/// [`futex`](crate::futex)).
///
/// # Errors
///
/// - [`Errno::EINVAL`] si la validation amont échoue : `stack` absent,
///   [`CloneFlags::VM`] absent, adresse de pile nulle, taille `< 4096`, `addr`
///   ou `size` non alignés sur 16, ou sommet de pile en débordement. Le kernel
///   peut aussi rendre `EINVAL` pour une combinaison de drapeaux incohérente
///   (p. ex. `CLONE_THREAD` avec un `exit_signal`).
/// - `EAGAIN`/`ENOMEM` (stub partiel `Errno`) : limites système / mémoire kernel.
///
/// # Safety
///
/// Hautement `unsafe`. L'appelant doit garantir :
///
/// - **Pile.** `stack` désigne une région mémoire valide, possédée, exclusivement
///   réservée au nouveau thread, d'au moins `size` octets, et **non libérée**
///   tant que le thread n'est pas joint (sinon use-after-free de la pile).
/// - **Point d'entrée.** `entry` ne doit exécuter que des opérations sûres dans
///   ce contexte naissant : **aucune** variable `thread_local` (sauf
///   [`CloneArgs::tls`] fourni avec un bloc TLS valide via [`CloneFlags::SETTLS`]),
///   pas d'`unwind`/panic traversant le trampoline, pas de dépendance à un état
///   d'initialisation propre au thread. Les écritures en mémoire **partagée**
///   (VM commune) doivent être thread-safe (`Atomic*`).
/// - **`arg`.** Sa signification est définie par `entry` ; s'il encode un
///   pointeur, la cible doit rester vivante et correctement synchronisée.
/// - **Join.** `child_tid`/`parent_tid` (si fournis) pointent un `AtomicU32`
///   vivant jusqu'à la fin du *join*.
pub unsafe fn clone_thread(
    args: &CloneArgs,
    entry: extern "C" fn(usize),
    arg: usize,
) -> Result<Tid, Errno> {
    // ── Validation amont (Principe 4) ───────────────────────────────────
    let stack: StackSpecification = args.stack.ok_or(Errno::EINVAL)?;
    // Un thread partage l'espace d'adressage : CLONE_VM est obligatoire (sinon
    // la pile neuve ne sert à rien et le join par mot partagé est impossible).
    if !args.flags.contains(CloneFlags::VM) {
        return Err(Errno::EINVAL);
    }
    if stack.addr.is_null() {
        return Err(Errno::EINVAL);
    }
    if stack.size < MIN_THREAD_STACK_SIZE {
        return Err(Errno::EINVAL);
    }
    let base = stack.addr.addr();
    // Alignement 16 de la base ET de la taille ⇒ sommet (`base + size`) aligné 16
    // (exigence ABI x86_64/aarch64 au point d'entrée). `& 0xF` : pas d'arithmétique.
    if base & 0xF != 0 || stack.size & 0xF != 0 {
        return Err(Errno::EINVAL);
    }
    // Sommet de pile sans débordement d'adresse (Principe 2 : pas d'« + » nu).
    base.checked_add(stack.size).ok_or(Errno::EINVAL)?;

    // Un thread n'a pas de pidfd : pidfd_addr = 0 (CLONE_PIDFD non pris en charge
    // par ce chemin ; il appartient au fork).
    let kernel_args = build_kernel_clone_args(args, 0);
    let args_ptr: *const KernelCloneArgs = &kernel_args;
    // size_of::<KernelCloneArgs>() = 88 ; cibles 64-bit uniquement (ADR-014).
    #[allow(clippy::cast_lossless)]
    let args_size: u64 = core::mem::size_of::<KernelCloneArgs>() as u64;

    // SAFETY:
    // - `args_ptr` pointe `kernel_args` (local vivant pour toute la fonction) ;
    //   `args_size` est exactement sa taille. Le kernel lit cette structure et,
    //   via `child_tid`/`parent_tid`, peut écrire les mots `AtomicU32` fournis
    //   (validité garantie par le contrat `unsafe` de cette fonction).
    // - Le côté ENFANT ne revient pas ici (le trampoline appelle `entry(arg)`
    //   sur la pile neuve puis `SYS_exit`) : aucun retour Rust sur pile vierge.
    // - Le côté PARENT reçoit `ret` (TID > 0, ou -errno) et le rend normalement.
    let ret = unsafe { raw_syscall_clone3_thread(args_ptr as u64, args_size, entry, arg) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // `ret == 0` est inobservable ici (l'enfant ne revient jamais dans ce code).
    // Le parent reçoit le TID enfant, borné par `PID_MAX_LIMIT` ≪ `i32::MAX`.
    #[allow(clippy::cast_possible_truncation)]
    let tid_raw = ret as i32;
    let tid = Tid::try_from_raw(tid_raw)
        .expect("clone_thread retour parent : TID strictement positif (POSIX)");
    Ok(tid)
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_clone3_thread(
    args_ptr: u64,
    args_size: u64,
    entry: extern "C" fn(usize),
    arg: usize,
) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_clone3 (x86_64 = 435) crée le thread ; le kernel lit `args_size`
    //   octets à `args_ptr` (struct clone_args valide) et règle `sp` de l'enfant
    //   au sommet de la pile (`stack`/`stack_size` du struct).
    // - « Retourne deux fois » : côté PARENT `rax` = TID (> 0) ou -errno → on
    //   branche en `2:` et rend `rax` à Rust. Côté ENFANT `rax` = 0 : on NE
    //   revient PAS dans le code Rust (sa pile est vierge). On place `arg` dans
    //   rdi puis on `call` `entry` (ABI C) sur la pile neuve. Si `entry` revient,
    //   on termine le SEUL thread courant via SYS_exit (x86_64 = 60), jamais
    //   exit_group. `ud2` est un garde-fou inatteignable.
    // - Clobbers du PARENT uniquement (l'enfant ne rend jamais la main au
    //   compilateur) : rax (ret), rcx et r11 (clobbés par `syscall`), drapeaux
    //   (pas de `preserves_flags`). `entry`/`arg` sont **épinglés** sur des
    //   registres callee-saved (r12/r13) que `syscall` ne touche pas : un
    //   registre callee-saved choisi par le compilateur (`in(reg)`) pourrait
    //   être rcx/r11 et serait écrasé par le `syscall` AVANT l'usage enfant
    //   (l'allocateur suppose les `lateout` produits *après* les `in` lus).
    //   `inout("rdi")` documente que rdi (args_ptr puis arg) est écrasé. Pas de
    //   `nostack` : le `call` enfant pousse sur la pile (neuve).
    unsafe {
        core::arch::asm!(
            "syscall",
            "test rax, rax",
            "jnz 2f",
            "mov rdi, r13",
            "call r12",
            "mov rax, 60", // SYS_exit (x86_64 = 60) : termine CE thread.
            "xor edi, edi",
            "syscall",
            "ud2",
            "2:",
            inout("rax") 435_i64 => ret, // SYS_clone3 (x86_64 = 435).
            inout("rdi") args_ptr => _,
            in("rsi") args_size,
            in("r12") entry,
            in("r13") arg,
            lateout("rcx") _,
            lateout("r11") _,
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_clone3_thread(
    args_ptr: u64,
    args_size: u64,
    entry: extern "C" fn(usize),
    arg: usize,
) -> i64 {
    let ret: i64;
    // SAFETY: voir la version x86_64. ABI aarch64 : SYS_clone3 (aarch64 = 435)
    // en X8, args en X0/X1, retour en X0. Côté ENFANT (`x0 == 0`) : `arg` → x0,
    // `blr` `entry` sur la pile neuve, puis SYS_exit (aarch64 = 93) — jamais
    // exit_group. `udf #0` garde-fou inatteignable. Clobbers du PARENT
    // uniquement : x0 (ret) ; `x8` est `in` (réécrit côté enfant, consommé).
    // `entry`/`arg` sont **épinglés** sur des registres callee-saved (x21/x20)
    // intacts jusqu'à leur usage enfant (symétrie avec x86_64). Pas de `nostack`
    // (`blr` enfant utilise la pile).
    unsafe {
        core::arch::asm!(
            "svc 0",
            "cbnz x0, 2f",
            "mov x0, x20",
            "blr x21",
            "mov x8, #93", // SYS_exit (aarch64 = 93) : termine CE thread.
            "mov x0, #0",
            "svc 0",
            "udf #0",
            "2:",
            in("x8") 435_i64, // SYS_clone3 (aarch64 = 435).
            inout("x0") args_ptr => ret,
            in("x1") args_size,
            in("x21") entry,
            in("x20") arg,
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// exit_group — terminaison immédiate du processus, sans cleanup userspace.
//
// Helper **interne** (`pub(crate)`, hors API publique gelée) : c'est la
// discipline de sortie correcte pour l'enfant d'un `clone3` fork dans un
// programme multi-thread. `std::process::exit` exécute les atexit handlers
// (flush stdio, machinerie de capture du harnais de test…) qui peuvent
// **deadlocker** sur des mutex hérités verrouillés par les threads du parent
// — inexistants dans l'enfant. Observé sur aarch64 (`futex_do_wait`) là où
// x86_64 masquait le bug. `exit_group` est un syscall direct : aucun verrou,
// aucun atexit, terminaison atomique de tous les threads du processus.
// ─────────────────────────────────────────────────────────────────────────

/// Termine immédiatement le processus appelant (tous ses threads) avec le
/// code `status`, via le syscall `child_exit(2)`.
///
/// Ne retourne jamais (`!`). N'exécute **aucun** atexit handler, ne flush
/// **aucun** buffer userspace : c'est précisément ce qui la rend sûre comme
/// sortie d'un enfant forké d'un programme multi-thread (cf. note ci-dessus).
///
/// Primitive publique (spec `family-process`, sous-section 3) : c'est le
/// chemin de sortie correct pour l'**enfant d'un `clone3` fork** dont l'`exec`
/// a échoué — terminer immédiatement, sans réveiller la machinerie userspace
/// héritée du parent. `air-process` (couche 1) l'utilise après un `execve`
/// raté dans l'enfant. Le code de sortie observé par `waitid`/`wait` est
/// `status & 0xFF`.
pub fn exit_group(status: i32) -> ! {
    // SAFETY: `exit_group(2)` ne lit ni n'écrit aucune mémoire utilisateur ;
    // il termine le processus et ne retourne pas. `options(noreturn)` est
    // donc correct.
    unsafe { raw_syscall_exit_group(status) }
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_exit_group(status: i32) -> ! {
    // SAFETY: SYS_exit_group (x86_64 = 231) ne touche aucune mémoire
    // utilisateur et ne retourne jamais. `noreturn` autorisé.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 231_i64,
            in("rdi") i64::from(status),
            options(nostack, noreturn),
        );
    }
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_exit_group(status: i32) -> ! {
    // SAFETY: SYS_exit_group (aarch64 = 94) ne touche aucune mémoire
    // utilisateur et ne retourne jamais. `noreturn` autorisé.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 94_i64,
            in("x0") i64::from(status),
            options(nostack, noreturn),
        );
    }
}

// ─────────────────────────────────────────────────────────────────────────
// waitid
// ─────────────────────────────────────────────────────────────────────────

// `idtype` du syscall waitid (cf. `linux/wait.h`).
const P_ALL: i64 = 0;
const P_PID: i64 = 1;
const P_PGID: i64 = 2;
const P_PIDFD: i64 = 3;

// `si_code` valeurs pour SIGCHLD (cf. `linux/signal.h`).
const CLD_EXITED: i32 = 1;
const CLD_KILLED: i32 = 2;
const CLD_DUMPED: i32 = 3;
const CLD_TRAPPED: i32 = 4;
const CLD_STOPPED: i32 = 5;
const CLD_CONTINUED: i32 = 6;

/// Représentation locale du `siginfo_t` Linux pour SIGCHLD.
///
/// Layout vérifié sur x86_64 et aarch64 (deux seules architectures Air,
/// cf. ADR-014) : 128 octets, union 8-octets alignée à l'offset 16. Les
/// champs `si_pid`/`si_uid`/`si_status` sont au début de la variante
/// `_sigchld` de l'union ; les offsets reflètent cette disposition.
#[repr(C)]
#[derive(Clone, Copy)]
struct KernelSiginfo {
    si_signo: i32,
    si_errno: i32,
    si_code: i32,
    _pad0: i32,
    si_pid: i32,
    si_uid: u32,
    si_status: i32,
    _trailing: [u8; 100],
}

impl KernelSiginfo {
    fn zeroed() -> Self {
        Self {
            si_signo: 0,
            si_errno: 0,
            si_code: 0,
            _pad0: 0,
            si_pid: 0,
            si_uid: 0,
            si_status: 0,
            _trailing: [0u8; 100],
        }
    }
}

const _: () = {
    // Vérifie à la compilation que KernelSiginfo fait bien 128 octets : si le
    // layout C devait dériver (futur portage), cette assertion explose.
    assert!(core::mem::size_of::<KernelSiginfo>() == 128);
};

/// Attend un événement sur un processus enfant via le syscall `waitid(2)`.
///
/// Cf. `docs/specs/layer-0/family-process.md` section `waitid`. Retourne :
///
/// - `Ok(Some(status))` si un événement a été reçu.
/// - `Ok(None)` si [`WaitOptions::NOHANG`] était positionné et qu'aucun
///   événement n'était disponible (kernel renvoie une `siginfo` zéroée).
/// - `Err(Errno::EINTR)` si l'attente a été interrompue par un signal :
///   **non retried automatiquement** (convention 2 ADR-021). L'appelant
///   qui veut retry écrit la boucle explicitement.
///
/// # Errors
///
/// - [`Errno::ECHILD`] : aucun enfant à attendre dans la cible.
/// - [`Errno::EINTR`] : interrompu par un signal, voir ci-dessus.
/// - [`Errno::EINVAL`] : options invalides (aucun parmi
///   `EXITED`/`STOPPED`/`CONTINUED` positionné) ou cible invalide.
pub fn waitid(target: WaitTarget<'_>, options: WaitOptions) -> Result<Option<WaitStatus>, Errno> {
    use air_sys_types::fd::AsRawFd;

    let (idtype, id_i64) = match target {
        WaitTarget::AnyChild => (P_ALL, 0_i64),
        WaitTarget::Pid(p) => (P_PID, i64::from(p.as_raw())),
        WaitTarget::ProcessGroup(p) => (P_PGID, i64::from(p.as_raw())),
        WaitTarget::AnyProcessGroup => (P_PGID, 0_i64),
        WaitTarget::PidFd(fd) => (P_PIDFD, i64::from(fd.as_raw_fd())),
    };

    let mut info = KernelSiginfo::zeroed();
    let info_ptr: *mut KernelSiginfo = &mut info;

    let options_i64 = i64::from(options.bits());

    // SAFETY:
    // - info_ptr pointe sur un KernelSiginfo local (128 octets, alignement 4) que
    //   le kernel renseigne au plus jusqu'à 128 octets — taille fixe et
    //   exactement celle qu'attend l'ABI Linux pour `siginfo_t`.
    // - rusage = 0 : on n'expose pas le 5e argument optionnel.
    let ret = unsafe { raw_syscall_waitid(idtype, id_i64, info_ptr as u64, options_i64) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // Cas NOHANG sans événement : le kernel laisse `siginfo` zéroé
    // (en particulier si_signo == 0, parce qu'un événement waitid réel
    // a toujours si_signo = SIGCHLD = 17 sur x86_64/aarch64).
    if info.si_signo == 0 {
        return Ok(None);
    }

    let pid = Pid::try_from_raw(info.si_pid)
        .expect("waitid : si_pid positif pour un événement enfant réel");
    let event = siginfo_to_wait_event(&info);

    Ok(Some(WaitStatus {
        pid,
        uid: info.si_uid,
        event,
    }))
}

/// Helper privé : convertit un `KernelSiginfo` rempli par le kernel en
/// [`WaitEvent`] typé. Extrait du corps de [`waitid`] pour pouvoir être
/// testé unitairement avec des `KernelSiginfo` synthétisés en mémoire — ce qui
/// permet de couvrir les 5 variantes (Exited, Killed, Stopped, Continued,
/// Trapped) sans dépendre de scénarios kernel réels.
///
/// **Limite connue** : ce test sur KernelSiginfo synthétisés couvre la *logique
/// de dispatch* mais ne valide pas le *remplissage* effectif de
/// `siginfo_t` par le kernel pour chaque code `CLD_*`. Voir `docs/JOURNAL.md`,
/// session 2026-05-22 (suite : clone3+waitid), trou de couverture acté.
fn siginfo_to_wait_event(info: &KernelSiginfo) -> WaitEvent {
    match info.si_code {
        CLD_EXITED => WaitEvent::Exited {
            code: info.si_status,
        },
        CLD_KILLED => WaitEvent::Killed {
            signal: Signal::try_from_raw(info.si_status)
                .expect("CLD_KILLED : si_status est un numéro de signal valide"),
            core_dumped: false,
        },
        CLD_DUMPED => WaitEvent::Killed {
            signal: Signal::try_from_raw(info.si_status)
                .expect("CLD_DUMPED : si_status est un numéro de signal valide"),
            core_dumped: true,
        },
        CLD_TRAPPED => WaitEvent::Trapped {
            signal: Signal::try_from_raw(info.si_status)
                .expect("CLD_TRAPPED : si_status est un numéro de signal valide"),
        },
        CLD_STOPPED => WaitEvent::Stopped {
            signal: Signal::try_from_raw(info.si_status)
                .expect("CLD_STOPPED : si_status est un numéro de signal valide"),
        },
        CLD_CONTINUED => WaitEvent::Continued,
        unknown => unreachable!("kernel a renseigné un si_code inconnu pour SIGCHLD : {unknown}"),
    }
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_waitid(idtype: i64, id: i64, infop: u64, options: i64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_waitid (x86_64 = 247). Le kernel écrit dans `infop` au plus
    //   128 octets — validité garantie par l'appelant (KernelSiginfo local).
    // - rusage (5e arg) à 0 : non utilisé.
    // - x86_64 syscall ABI : numéro en RAX, args en RDI/RSI/RDX/R10/R8/R9 ;
    //   retour en RAX ; clobbe RCX et R11.
    // - **Pas de `readonly`** : le kernel écrit dans `*infop`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 247_i64,
            in("rdi") idtype,
            in("rsi") id,
            in("rdx") infop,
            in("r10") options,
            in("r8") 0_i64,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_waitid(idtype: i64, id: i64, infop: u64, options: i64) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 syscall ABI :
    // numéro en X8 (= 95), args en X0..X4 (5 args, le 5e = rusage = 0).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 95_i64,
            inout("x0") idtype => ret,
            in("x1") id,
            in("x2") infop,
            in("x3") options,
            in("x4") 0_i64,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// pidfd_open
// ─────────────────────────────────────────────────────────────────────────

/// Ouvre un pidfd qui référence le processus identifié par `pid`.
///
/// Cf. `docs/specs/layer-0/family-process.md`, sous-section 3,
/// `pidfd_open`. Le pidfd retourné reste valide même après la mort du
/// processus original (pas de race sur le PID recyclé). Il peut être
/// utilisé par [`waitid`] (variant `WaitTarget::PidFd`),
/// [`pidfd_send_signal`], [`pidfd_getfd`], et par les syscalls
/// `poll`/`epoll` pour détecter la mort du processus.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : un bit invalide dans `flags`.
/// - [`Errno::ESRCH`] : aucun processus n'a ce PID.
/// - `ENOMEM` (stub partiel `Errno`) : mémoire kernel insuffisante.
pub fn pidfd_open(pid: Pid, flags: PidFdOpenFlags) -> Result<PidFd, Errno> {
    // SAFETY:
    // - `pidfd_open(2)` ne lit ni n'écrit aucune mémoire utilisateur :
    //   il prend deux scalaires et retourne un fd.
    // - L'ABI x86_64 / aarch64 est documentée dans
    //   `raw_syscall_pidfd_open` (clobbers, options).
    let ret = unsafe { raw_syscall_pidfd_open(pid.as_raw(), flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // `ret` est un fd kernel valide. Linux borne les fd à `i32::MAX`
    // (`/proc/sys/fs/file-max` n'excède pas cette limite par construction
    // dans le kernel), donc la troncature est exacte.
    #[allow(clippy::cast_possible_truncation)]
    let new_fd: RawFd = ret as RawFd;
    // SAFETY: le kernel vient d'allouer un fd valide et nous en a
    // transféré la propriété ; Air le wrappe immédiatement dans
    // `OwnedFd` puis dans `PidFd`. La fermeture est garantie par Drop.
    let owned = unsafe { OwnedFd::from_raw_fd(new_fd) };
    Ok(PidFd::from_owned_fd(owned))
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_pidfd_open(pid: i32, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_pidfd_open (x86_64 = 434) ne touche à aucune mémoire
    //   utilisateur ; il ne fait que retourner un fd.
    // - ABI syscall x86_64 : numéro en RAX, arg1/arg2 en RDI/RSI ;
    //   retour en RAX ; clobbe RCX (RIP) et R11 (RFLAGS).
    // - `readonly` correct : pas d'écriture en mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 434_i64,
            in("rdi") i64::from(pid),
            in("rsi") 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_pidfd_open(pid: i32, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: ABI aarch64 ; numéro en X8, args en X0/X1, retour en X0.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 434_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// pidfd_send_signal
// ─────────────────────────────────────────────────────────────────────────

/// Envoie un signal au processus référencé par `pidfd`.
///
/// Cf. `docs/specs/layer-0/family-process.md`, sous-section 3,
/// `pidfd_send_signal`. À préférer à un futur `kill(pid, sig)` quand un
/// pidfd est disponible : pas de race sur le PID recyclé.
///
/// # `info`
///
/// Si `Some(info)`, le kernel utilise le `siginfo_t` fourni (sémantique
/// `rt_sigqueueinfo`). Si `None`, le kernel synthétise un `siginfo_t`
/// avec `si_code = SI_USER`, équivalent à un `kill(2)` standard.
///
/// **Note périmètre.** Cette PR n'expose **aucun constructeur public**
/// pour [`SignalInfo`] (stub partiel) ; depuis l'extérieur de la crate,
/// seul `None` est passable. Le bras `Some(_)` du wrapper reste
/// type-reachable mais value-unreachable jusqu'à la PR `family-signal`.
///
/// # Errors
///
/// - [`Errno::EBADF`] : pidfd invalide.
/// - [`Errno::EINVAL`] : signal invalide.
/// - [`Errno::EPERM`] : permissions insuffisantes pour signaler cette cible.
/// - [`Errno::ESRCH`] : le processus référencé n'existe plus.
pub fn pidfd_send_signal(
    pidfd: BorrowedFd<'_>,
    signal: Signal,
    info: Option<&SignalInfo>,
) -> Result<(), Errno> {
    let info_ptr: u64 = match info {
        Some(i) => {
            let p: *const SignalInfo = i;
            p as u64
        }
        None => 0,
    };

    // SAFETY:
    // - `pidfd_send_signal(2)` lit `*info` si le pointeur est non nul ;
    //   il ne **modifie** aucune mémoire utilisateur (`readonly` OK).
    // - Si `info_ptr == 0` (cas `None`), le kernel synthétise un siginfo.
    // - L'appelant garantit que `pidfd` est ouvert (BorrowedFd typé).
    // - `flags` (5e arg) est réservé : doit valoir 0.
    let ret = unsafe {
        raw_syscall_pidfd_send_signal(pidfd.as_raw_fd(), signal.as_raw(), info_ptr, 0_u32)
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_pidfd_send_signal(pidfd: i32, signal: i32, info: u64, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_pidfd_send_signal (x86_64 = 424). Lecture seulement de
    //   `*info` (et seulement si non-null) ; pas d'écriture en mémoire
    //   utilisateur, d'où `readonly`.
    // - ABI x86_64 : args en RDI/RSI/RDX/R10 ; retour en RAX ; clobbe
    //   RCX et R11.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 424_i64,
            in("rdi") i64::from(pidfd),
            in("rsi") i64::from(signal),
            in("rdx") info,
            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_pidfd_send_signal(pidfd: i32, signal: i32, info: u64, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: ABI aarch64 (numéro en X8, args en X0..X3).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 424_i64,
            inout("x0") i64::from(pidfd) => ret,
            in("x1") i64::from(signal),
            in("x2") info,
            in("x3") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// pidfd_getfd
// ─────────────────────────────────────────────────────────────────────────

/// Duplique un FD ouvert dans le processus référencé par `pidfd`.
///
/// Cf. `docs/specs/layer-0/family-process.md`, sous-section 3,
/// `pidfd_getfd`. Cas d'usage spécialisé : debuggers, outils de
/// surveillance, transfert de ressources entre processus coopérant.
///
/// Le FD retourné est **propriété de l'appelant** ([`OwnedFd`]) ; il
/// pointe sur la même entrée du file table que `target_fd` côté
/// processus cible. La fermeture côté cible ne ferme pas la copie locale,
/// et réciproquement.
///
/// # Errors
///
/// - [`Errno::EBADF`] : `pidfd` invalide, ou `target_fd` non ouvert
///   dans le processus cible.
/// - [`Errno::EPERM`] : pas de `CAP_SYS_PTRACE` et pas le même
///   utilisateur que la cible. Sur Ubuntu, Yama `ptrace_scope ≥ 2`
///   peut également bloquer.
/// - [`Errno::EINVAL`] : `flags` non nul (réservé).
/// - [`Errno::ESRCH`] : le processus référencé n'existe plus.
pub fn pidfd_getfd(pidfd: BorrowedFd<'_>, target_fd: RawFd, flags: u32) -> Result<OwnedFd, Errno> {
    // SAFETY:
    // - `pidfd_getfd(2)` ne touche aucune mémoire utilisateur : il
    //   alloue côté kernel une nouvelle entrée dans la file table de
    //   l'appelant pointant sur la même file que `target_fd` côté cible.
    // - `flags` est réservé (doit être 0 sur kernel actuel).
    let ret = unsafe { raw_syscall_pidfd_getfd(pidfd.as_raw_fd(), target_fd, flags) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let new_fd: RawFd = ret as RawFd;
    // SAFETY: kernel vient de transférer la propriété d'un fd valide.
    Ok(unsafe { OwnedFd::from_raw_fd(new_fd) })
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_pidfd_getfd(pidfd: i32, target_fd: i32, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_pidfd_getfd (x86_64 = 438) ne lit ni n'écrit en
    // mémoire utilisateur (`readonly`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 438_i64,
            in("rdi") i64::from(pidfd),
            in("rsi") i64::from(target_fd),
            in("rdx") 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_pidfd_getfd(pidfd: i32, target_fd: i32, flags: u32) -> i64 {
    let ret: i64;
    // SAFETY: ABI aarch64 ; numéro en X8 (= 438), args en X0..X2.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 438_i64,
            inout("x0") i64::from(pidfd) => ret,
            in("x1") i64::from(target_fd),
            in("x2") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Groupes et sessions (sous-section 4 de family-process.md).
// ─────────────────────────────────────────────────────────────────────────

/// Place `pid` dans le process group `pgid`.
///
/// Cf. `docs/specs/layer-0/family-process.md` sous-section 4. Sémantique
/// POSIX standard ; cas d'usage : shells, démons, applications terminal.
///
/// `pid = None` désigne le processus courant (cf. ADR-021 convention 1,
/// remplaçant la sentinelle kernel `0`). `pgid = None` désigne « créer un
/// nouveau process group dont le leader est `pid` » (sentinelle `0` côté
/// kernel).
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `pgid` ne désigne pas un process group valide
///   dans la session courante.
/// - [`Errno::EPERM`] : `pid` n'est pas l'appelant ou un de ses enfants,
///   ou tentative de déplacer un processus hors session.
/// - [`Errno::ESRCH`] : `pid` n'existe pas.
pub fn setpgid(pid: Option<Pid>, pgid: Option<Pid>) -> Result<(), Errno> {
    let pid_arg = pid.map_or(0_i32, |p| p.as_raw());
    let pgid_arg = pgid.map_or(0_i32, |p| p.as_raw());
    // SAFETY: setpgid(2) ne touche aucune mémoire utilisateur ; lecture
    // des deux pid_t scalaires.
    let ret = unsafe { raw_syscall_setpgid(pid_arg, pgid_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Retourne le process group ID de `pid` (ou du processus courant si `None`).
///
/// # Errors
///
/// - [`Errno::ESRCH`] : `pid` n'existe pas.
pub fn getpgid(pid: Option<Pid>) -> Result<Pid, Errno> {
    let pid_arg = pid.map_or(0_i32, |p| p.as_raw());
    // SAFETY: getpgid(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe { raw_syscall_getpgid(pid_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // PGID retourné est un pid_t > 0 (process group ID = pid du leader,
    // qui est lui-même positif). Troncature exacte.
    #[allow(clippy::cast_possible_truncation)]
    let raw = ret as i32;
    Ok(Pid::try_from_raw(raw).expect("kernel : pgid strictement positif"))
}

/// Crée une nouvelle session avec l'appelant comme session leader, et le
/// place dans un nouveau process group dont il est le leader. Retourne le
/// nouveau session ID.
///
/// # Errors
///
/// - [`Errno::EPERM`] : l'appelant est déjà process group leader (le test
///   runner cargo est typiquement un pgrp leader → `setsid` échoue, ce
///   qui est exploité par les tests).
pub fn setsid() -> Result<Pid, Errno> {
    // SAFETY: setsid(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe { raw_syscall_setsid() };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let raw = ret as i32;
    Ok(Pid::try_from_raw(raw).expect("kernel : nouveau SID strictement positif"))
}

/// Retourne le session ID de `pid` (ou du processus courant si `None`).
///
/// # Errors
///
/// - [`Errno::EPERM`] : `pid` est dans une session différente de l'appelant
///   et le kernel refuse de divulguer (rare).
/// - [`Errno::ESRCH`] : `pid` n'existe pas.
pub fn getsid(pid: Option<Pid>) -> Result<Pid, Errno> {
    let pid_arg = pid.map_or(0_i32, |p| p.as_raw());
    // SAFETY: getsid(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe { raw_syscall_getsid(pid_arg) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let raw = ret as i32;
    Ok(Pid::try_from_raw(raw).expect("kernel : SID strictement positif"))
}

// ─────────────────────────────────────────────────────────────────────────
// Séparation de privilèges (privsep) — setgroups/getgroups + setres*id/getres*id
//
// Spec : `docs/specs/layer-0/family-process-privsep.md`.
//
// Opérations **privilégiées** (`CAP_SETUID`/`CAP_SETGID` ou root). Prérequis
// d'un `drop_privileges` correct (`air-process`, couche 1) : larguer les
// **groupes supplémentaires** ET fixer le ***saved-set*-id** — sans quoi un
// `setuid`/`setgid` simple laisse regagner les privilèges.
// ─────────────────────────────────────────────────────────────────────────

/// `NGROUPS_MAX` (Linux) : nombre maximal de groupes supplémentaires. Au-delà,
/// `setgroups(2)` rend `EINVAL` ; on le valide **en amont** (Principe 4).
const NGROUPS_MAX: usize = 65536;

/// Encode un `Option<Gid>` pour `setresgid` : `None` ⇒ `(gid_t)-1` (composante
/// **inchangée**), `Some(g)` ⇒ sa valeur brute. La sentinelle `-1` n'est jamais
/// exposée à l'appelant (ADR-021 conv. 1).
fn opt_gid_to_raw(gid: Option<Gid>) -> u32 {
    gid.map_or(u32::MAX, Gid::as_raw)
}

/// Encode un `Option<Uid>` pour `setresuid` (`None` ⇒ `(uid_t)-1`). Voir
/// [`opt_gid_to_raw`].
fn opt_uid_to_raw(uid: Option<Uid>) -> u32 {
    uid.map_or(u32::MAX, Uid::as_raw)
}

/// Remplace la liste des **groupes supplémentaires** du processus (`setgroups`).
///
/// Pour une réduction de privilèges, passer **`&[]`** (largage total) tant qu'on
/// est privilégié : la liste vide est la valeur **normale** du privsep, pas une
/// sentinelle. Le layout de `&[Gid]` coïncide avec `&[gid_t]` (`Gid` est
/// `#[repr(transparent)]`), donc aucune copie n'est nécessaire.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : plus de `NGROUPS_MAX` (65536) groupes (validé en amont).
/// - [`Errno::EPERM`] : `CAP_SETGID` absent.
/// - [`Errno::EFAULT`] : `groups` hors de l'espace d'adressage (n'arrive pas avec
///   une tranche Rust valide).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::process::set_groups;
/// // Largage total des groupes supplémentaires (étape d'un privsep).
/// set_groups(&[]).expect("CAP_SETGID requis");
/// ```
pub fn set_groups(groups: &[Gid]) -> Result<(), Errno> {
    // Validation amont (Principe 4) : borne kernel.
    if groups.len() > NGROUPS_MAX {
        return Err(Errno::EINVAL);
    }
    let size = groups.len();
    let list_ptr = groups.as_ptr() as u64;
    // SAFETY: setgroups(2) **lit** `size` entrées `gid_t` à `list_ptr` et n'écrit
    // aucune mémoire utilisateur. `groups` est une tranche Rust valide pour la
    // durée de l'appel ; `Gid` est `#[repr(transparent)]` sur `u32` (= `gid_t`),
    // donc le pointeur et le compte décrivent un tableau de `gid_t` correct.
    // `size ≤ NGROUPS_MAX` est validé ci-dessus.
    let ret = unsafe { raw_syscall_setgroups(size, list_ptr) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit la liste courante des **groupes supplémentaires** (`getgroups`) dans le
/// `buffer` fourni — **zéro allocation** — et retourne la sous-tranche remplie.
///
/// Vérification défensive de `drop_privileges` (Principe 5 : confirmer la
/// réduction). Le `buffer` doit pouvoir contenir tous les groupes courants.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `buffer` trop petit pour la liste complète.
/// - [`Errno::EFAULT`] : `buffer` invalide (n'arrive pas avec une tranche Rust).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::process::get_groups;
/// use air_sys_types::Gid;
/// let mut buf = [Gid::from_raw(0); 64];
/// let groups = get_groups(&mut buf).expect("getgroups");
/// assert!(groups.len() <= 64);
/// ```
pub fn get_groups(buffer: &mut [Gid]) -> Result<&[Gid], Errno> {
    let size = buffer.len();
    let list_ptr = buffer.as_mut_ptr() as u64;
    // SAFETY: getgroups(2) **écrit** jusqu'à `size` entrées `gid_t` à `list_ptr`
    // et retourne le nombre écrit. `buffer` est une tranche mutable valide pour
    // la durée de l'appel ; `Gid` est `#[repr(transparent)]` sur `gid_t`.
    let ret = unsafe { raw_syscall_getgroups(size, list_ptr) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // `ret` = nombre de groupes écrits (`0 ≤ ret ≤ size`). Conversion exacte.
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    let count = ret as usize;
    // `count ≤ size` garanti par le kernel ; `get` évite toute indexation
    // panic-able (le bras `None` est structurellement inatteignable).
    buffer.get(..count).ok_or(Errno::EINVAL)
}

/// Fixe **real + effective + saved** GID en un seul appel (`setresgid`).
///
/// À effectuer **avant** [`set_resuid`] (on ne peut plus changer de GID une fois
/// l'UID réduit). `None` pour une composante = « **inchangée** » (sentinelle
/// kernel `(gid_t)-1` typée, ADR-021 conv. 1). Fixer le *saved-set-gid* est ce
/// qui interdit le **retour** au GID privilégié.
///
/// # Errors
///
/// - [`Errno::EPERM`] : changement non autorisé (sans `CAP_SETGID`).
/// - [`Errno::EINVAL`] : un des GID n'est pas valide.
pub fn set_resgid(
    real: Option<Gid>,
    effective: Option<Gid>,
    saved: Option<Gid>,
) -> Result<(), Errno> {
    let real = opt_gid_to_raw(real);
    let effective = opt_gid_to_raw(effective);
    let saved = opt_gid_to_raw(saved);
    // SAFETY: setresgid(2) ne touche aucune mémoire utilisateur (3 scalaires
    // `gid_t`). `(gid_t)-1` laisse la composante inchangée.
    let ret = unsafe { raw_syscall_setresgid(real, effective, saved) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Fixe **real + effective + saved** UID en un seul appel (`setresuid`).
///
/// À effectuer **après** [`set_resgid`] (et après [`set_groups`]). `None` =
/// composante inchangée (`(uid_t)-1` typé). Fixer le *saved-set-uid* rend la
/// réduction de privilèges **irréversible** — garantie qu'un `setuid` simple ne
/// donne pas de façon fiable.
///
/// # Errors
///
/// - [`Errno::EPERM`] : changement non autorisé (sans `CAP_SETUID`).
/// - [`Errno::EINVAL`] : un des UID n'est pas valide.
pub fn set_resuid(
    real: Option<Uid>,
    effective: Option<Uid>,
    saved: Option<Uid>,
) -> Result<(), Errno> {
    let real = opt_uid_to_raw(real);
    let effective = opt_uid_to_raw(effective);
    let saved = opt_uid_to_raw(saved);
    // SAFETY: setresuid(2) ne touche aucune mémoire utilisateur (3 scalaires
    // `uid_t`). `(uid_t)-1` laisse la composante inchangée.
    let ret = unsafe { raw_syscall_setresuid(real, effective, saved) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit les trois composantes GID **réelle / effective / sauvegardée**
/// (`getresgid`) — vérification défensive (confirmer qu'on ne peut plus revenir
/// en arrière).
///
/// # Errors
///
/// - [`Errno::EFAULT`] : pointeurs invalides (n'arrive pas : pile locale).
pub fn get_resgid() -> Result<ResGid, Errno> {
    let mut real: u32 = 0;
    let mut effective: u32 = 0;
    let mut saved: u32 = 0;
    // SAFETY: getresgid(2) **écrit** trois `gid_t` aux pointeurs fournis. Les
    // trois variables locales sont vivantes, alignées et exclusivement
    // empruntées (`from_mut`) pour la durée de l'appel.
    let ret = unsafe {
        raw_syscall_getresgid(
            core::ptr::from_mut(&mut real) as u64,
            core::ptr::from_mut(&mut effective) as u64,
            core::ptr::from_mut(&mut saved) as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(ResGid {
        real: Gid::from_raw(real),
        effective: Gid::from_raw(effective),
        saved: Gid::from_raw(saved),
    })
}

/// Lit les trois composantes UID **réelle / effective / sauvegardée**
/// (`getresuid`) — vérification défensive.
///
/// # Errors
///
/// - [`Errno::EFAULT`] : pointeurs invalides (n'arrive pas : pile locale).
pub fn get_resuid() -> Result<ResUid, Errno> {
    let mut real: u32 = 0;
    let mut effective: u32 = 0;
    let mut saved: u32 = 0;
    // SAFETY: getresuid(2) **écrit** trois `uid_t` aux pointeurs fournis. Voir
    // [`get_resgid`] pour les préconditions (variables pile vivantes/alignées).
    let ret = unsafe {
        raw_syscall_getresuid(
            core::ptr::from_mut(&mut real) as u64,
            core::ptr::from_mut(&mut effective) as u64,
            core::ptr::from_mut(&mut saved) as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(ResUid {
        real: Uid::from_raw(real),
        effective: Uid::from_raw(effective),
        saved: Uid::from_raw(saved),
    })
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_setpgid(pid: i32, pgid: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setpgid (x86_64 = 109) — pas d'accès mémoire utilisateur ;
    // ABI x86_64 standard (RAX=nr, RDI/RSI=args ; clobbers RCX/R11).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 109_i64,
            in("rdi") i64::from(pid),
            in("rsi") i64::from(pgid),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

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

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_setsid() -> i64 {
    let ret: i64;
    // SAFETY: SYS_setsid (x86_64 = 112) — pas d'accès mémoire utilisateur,
    // pas d'argument.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 112_i64,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

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

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_setpgid(pid: i32, pgid: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setpgid (aarch64 = 154) — ABI standard, no mem access.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 154_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") i64::from(pgid),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

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

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_setsid() -> i64 {
    let ret: i64;
    // SAFETY: SYS_setsid (aarch64 = 157).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 157_i64,
            lateout("x0") ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

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

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — privsep (numéros vérifiés sur l'uapi 6.12 par arche :
// x86_64 = unistd_64.h, aarch64 = asm-generic/unistd.h).
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_setgroups(size: usize, list: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setgroups (x86_64 = 116). **Lit** `size` `gid_t` à `list` ;
    // n'écrit aucune mémoire utilisateur (`readonly`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 116_i64,
            in("rdi") size,
            in("rsi") list,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_setgroups(size: usize, list: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setgroups (aarch64 = 159). Lit la liste ; n'écrit rien.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 159_i64,
            inout("x0") size => ret,
            in("x1") list,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getgroups(size: usize, list: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getgroups (x86_64 = 115). **Écrit** jusqu'à `size` `gid_t` à
    // `list` (pas de `readonly`). Retourne le nombre écrit ou `-errno`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 115_i64,
            in("rdi") size,
            in("rsi") list,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getgroups(size: usize, list: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getgroups (aarch64 = 158). Écrit la liste (pas de `readonly`).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 158_i64,
            inout("x0") size => ret,
            in("x1") list,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_setresgid(real: u32, effective: u32, saved: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setresgid (x86_64 = 119). Trois scalaires `gid_t` ; aucun
    // accès mémoire utilisateur (`readonly`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 119_i64,
            in("rdi") i64::from(real),
            in("rsi") i64::from(effective),
            in("rdx") i64::from(saved),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_setresgid(real: u32, effective: u32, saved: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setresgid (aarch64 = 149). Trois scalaires ; pas d'accès mém.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 149_i64,
            inout("x0") i64::from(real) => ret,
            in("x1") i64::from(effective),
            in("x2") i64::from(saved),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_setresuid(real: u32, effective: u32, saved: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setresuid (x86_64 = 117). Trois scalaires `uid_t` ; `readonly`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 117_i64,
            in("rdi") i64::from(real),
            in("rsi") i64::from(effective),
            in("rdx") i64::from(saved),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_setresuid(real: u32, effective: u32, saved: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setresuid (aarch64 = 147). Trois scalaires ; pas d'accès mém.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 147_i64,
            inout("x0") i64::from(real) => ret,
            in("x1") i64::from(effective),
            in("x2") i64::from(saved),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getresgid(real: u64, effective: u64, saved: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getresgid (x86_64 = 120). **Écrit** trois `gid_t` aux trois
    // pointeurs (pas de `readonly`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 120_i64,
            in("rdi") real,
            in("rsi") effective,
            in("rdx") saved,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getresgid(real: u64, effective: u64, saved: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getresgid (aarch64 = 150). Écrit trois `gid_t` (pas readonly).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 150_i64,
            inout("x0") real => ret,
            in("x1") effective,
            in("x2") saved,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getresuid(real: u64, effective: u64, saved: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getresuid (x86_64 = 118). **Écrit** trois `uid_t` aux trois
    // pointeurs (pas de `readonly`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 118_i64,
            in("rdi") real,
            in("rsi") effective,
            in("rdx") saved,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getresuid(real: u64, effective: u64, saved: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getresuid (aarch64 = 148). Écrit trois `uid_t` (pas readonly).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 148_i64,
            inout("x0") real => ret,
            in("x1") effective,
            in("x2") saved,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// prctl (sous-section 5 de family-process.md).
//
// Convention 3 ADR-021 : `prctl(op, args...)` n'est PAS exposé. Chaque
// opération est exposée comme fonction dédiée typée. Le helper
// `raw_syscall_prctl` est strictement interne au module.
// ─────────────────────────────────────────────────────────────────────────

// Opérations `prctl(2)` exposées par cette PR (cf. `include/uapi/linux/prctl.h`).
const PR_SET_PDEATHSIG: i32 = 1;
const PR_GET_PDEATHSIG: i32 = 2;
const PR_GET_DUMPABLE: i32 = 3;
const PR_SET_DUMPABLE: i32 = 4;
const PR_GET_KEEPCAPS: i32 = 7;
const PR_SET_KEEPCAPS: i32 = 8;
const PR_SET_NAME: i32 = 15;
const PR_GET_NAME: i32 = 16;
const PR_SET_TIMERSLACK: i32 = 29;
const PR_SET_NO_NEW_PRIVS: i32 = 38;
const PR_GET_NO_NEW_PRIVS: i32 = 39;
const PR_CAP_AMBIENT: i32 = 47;

// Sous-opérations de PR_CAP_AMBIENT (arg2).
const PR_CAP_AMBIENT_IS_SET: u64 = 1;
const PR_CAP_AMBIENT_RAISE: u64 = 2;
const PR_CAP_AMBIENT_LOWER: u64 = 3;
const PR_CAP_AMBIENT_CLEAR_ALL: u64 = 4;

/// Définit le signal envoyé au processus courant à la mort de son parent.
///
/// `None` désactive la notification (le kernel envoie 0, traité comme
/// « aucun signal »).
///
/// # Errors
///
/// - [`Errno::EINVAL`] : signal hors plage.
pub fn set_parent_death_signal(signal: Option<Signal>) -> Result<(), Errno> {
    let sig_arg: u64 = signal.map_or(0_u64, |s| {
        // s.as_raw() > 0 par construction (NonZeroI32). Cast sign-safe.
        #[allow(clippy::cast_sign_loss)]
        {
            s.as_raw() as u64
        }
    });
    // SAFETY: PR_SET_PDEATHSIG — pas d'accès mémoire utilisateur.
    let ret = unsafe { raw_syscall_prctl(PR_SET_PDEATHSIG, sig_arg, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Retourne le signal envoyé au processus à la mort du parent.
/// `Ok(None)` si la notification est désactivée.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : ne se produit pas pour PR_GET_PDEATHSIG en
///   pratique.
pub fn get_parent_death_signal() -> Result<Option<Signal>, Errno> {
    // Le kernel écrit le signal dans `*(int *)arg2`.
    let mut out: i32 = 0;
    let out_ptr: *mut i32 = &mut out;
    // SAFETY: PR_GET_PDEATHSIG écrit un int à arg2 ; `out` est local
    // valide pour toute la durée du syscall.
    let ret = unsafe { raw_syscall_prctl(PR_GET_PDEATHSIG, out_ptr as u64, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(Signal::try_from_raw(out))
}

/// Active le bit `no_new_privs` du processus.
///
/// **Opération irréversible.** Une fois positionné, ce bit ne peut pas
/// être effacé pour la durée de vie du processus — toute tentative
/// (`set_no_new_privs` après coup, ou via execve d'un binaire SUID) est
/// neutralisée par le kernel. Conséquence pour les tests : exécuter
/// `set_no_new_privs()` dans un test contamine **tous les tests
/// ultérieurs** dans la même process. Cette PR ne teste donc que
/// `get_no_new_privs()` ; le set est laissé à la PR `family-security`
/// (seccomp) qui s'exécute dans un processus enfant fork'é.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : ne se produit pas en pratique.
pub fn set_no_new_privs() -> Result<(), Errno> {
    // arg2 doit être 1 selon le contrat kernel ; toute autre valeur
    // retourne EINVAL.
    // SAFETY: PR_SET_NO_NEW_PRIVS — pas d'accès mémoire utilisateur.
    let ret = unsafe { raw_syscall_prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Indique si le bit `no_new_privs` est positionné pour le processus.
///
/// # Errors
///
/// - Aucune en pratique pour cette opération.
pub fn get_no_new_privs() -> Result<bool, Errno> {
    // SAFETY: PR_GET_NO_NEW_PRIVS — pas d'accès mémoire utilisateur ; la
    // valeur est retournée comme code de retour du syscall (0 ou 1).
    let ret = unsafe { raw_syscall_prctl(PR_GET_NO_NEW_PRIVS, 0, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(ret != 0)
}

/// Définit le nom du thread (max 15 caractères + NUL).
///
/// Le kernel tronque silencieusement à 15 caractères si `name` est plus
/// long. Le nom est utilisé par `/proc/PID/task/TID/comm` et exposé par
/// `top`/`ps -L`.
///
/// # Errors
///
/// - `EFAULT` : pointeur invalide ; ne se produit pas via l'API safe.
pub fn set_thread_name(name: &CStr) -> Result<(), Errno> {
    let ptr = name.as_ptr();
    // SAFETY: PR_SET_NAME lit la C-string à arg2 (kernel tronque à 16
    // octets). `name` est un &CStr valide pour la durée du call.
    let ret = unsafe { raw_syscall_prctl(PR_SET_NAME, ptr as u64, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Retourne le nom du thread courant.
///
/// # Allocation
///
/// Convention 4 ADR-021 exception explicite : « la sémantique exige un
/// type owned ». Le kernel écrit ≤ 16 octets dans un buffer transient ;
/// le caller récupère une `CString` qui peut sortir du frame. Allocation
/// bornée à 16 octets (un seul `Box<[u8]>`), happy-path.
///
/// # Errors
///
/// - Aucune en pratique pour cette opération.
pub fn get_thread_name() -> Result<CString, Errno> {
    let mut buffer: [u8; 16] = [0; 16];
    let ptr: *mut u8 = buffer.as_mut_ptr();
    // SAFETY: PR_GET_NAME écrit exactement 16 octets dans `*(char *)arg2` ;
    // `buffer` est local valide pour la durée du call. Le kernel garantit la
    // terminaison NUL (en tronquant si nécessaire).
    let ret = unsafe { raw_syscall_prctl(PR_GET_NAME, ptr as u64, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // Le buffer est garanti contenir au moins un NUL (le kernel tronque
    // à 15 caractères + NUL). On extrait la C-string jusqu'au premier NUL.
    let length = buffer.iter().position(|&b| b == 0).unwrap_or(16);
    // CString::new exige absence de NUL interne ; on passe les bytes
    // *avant* le NUL trouvé.
    Ok(CString::new(&buffer[..length])
        .expect("buffer kernel sans NUL interne avant le terminateur"))
}

/// Définit le mode `dumpable` du processus.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : valeur hors plage (ne se produit pas via l'API
///   typée).
pub fn set_dumpable(mode: DumpableMode) -> Result<(), Errno> {
    let mode_arg = u64::from(mode as u32);
    // SAFETY: PR_SET_DUMPABLE — pas d'accès mémoire utilisateur.
    let ret = unsafe { raw_syscall_prctl(PR_SET_DUMPABLE, mode_arg, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Retourne le mode `dumpable` actuel.
///
/// # Errors
///
/// - Aucune en pratique pour cette opération.
pub fn get_dumpable() -> Result<DumpableMode, Errno> {
    // SAFETY: PR_GET_DUMPABLE — pas d'accès mémoire utilisateur ;
    // valeur retournée comme code de retour.
    let ret = unsafe { raw_syscall_prctl(PR_GET_DUMPABLE, 0, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    match ret {
        0 => Ok(DumpableMode::NotDumpable),
        1 => Ok(DumpableMode::Dumpable),
        2 => Ok(DumpableMode::SuidDumpable),
        // Le kernel garantit 0, 1, ou 2. Sortie hors plage = bug kernel.
        other => unreachable!("PR_GET_DUMPABLE a retourné {other}, hors plage [0,2]"),
    }
}

/// Définit le bit `keep_caps` : si vrai, les capabilities `permitted`
/// sont conservées lors d'un changement d'UID effectif vers non-zéro.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : valeur invalide (ne se produit pas via l'API typée).
pub fn set_keep_caps(keep: bool) -> Result<(), Errno> {
    let arg: u64 = u64::from(keep);
    // SAFETY: PR_SET_KEEPCAPS — pas d'accès mémoire utilisateur.
    let ret = unsafe { raw_syscall_prctl(PR_SET_KEEPCAPS, arg, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Indique si le bit `keep_caps` est positionné.
///
/// # Errors
///
/// - Aucune en pratique pour cette opération.
pub fn get_keep_caps() -> Result<bool, Errno> {
    // SAFETY: PR_GET_KEEPCAPS — pas d'accès mémoire utilisateur.
    let ret = unsafe { raw_syscall_prctl(PR_GET_KEEPCAPS, 0, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(ret != 0)
}

/// Définit la « timer slack » du processus (nanosecondes).
///
/// Le timer slack permet au kernel d'agréger les timers proches pour
/// réduire les wake-ups. `0` réinitialise à la valeur par défaut héritée.
///
/// # Errors
///
/// - Aucune en pratique.
pub fn set_timer_slack(slack_ns: u64) -> Result<(), Errno> {
    // SAFETY: PR_SET_TIMERSLACK — pas d'accès mémoire utilisateur.
    let ret = unsafe { raw_syscall_prctl(PR_SET_TIMERSLACK, slack_ns, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Ajoute `cap` à l'ensemble ambient du thread.
///
/// L'ensemble ambient est transmis à `execve`, contrairement aux
/// inheritable seuls. Exige `cap` dans `permitted ∩ inheritable`.
///
/// # Errors
///
/// - [`Errno::EPERM`] : `cap` n'est pas dans permitted ∩ inheritable, ou
///   `SECBIT_NO_CAP_AMBIENT_RAISE` est positionné.
/// - [`Errno::EINVAL`] : valeur de capability inconnue côté kernel.
pub fn cap_ambient_raise(cap: Capability) -> Result<(), Errno> {
    // SAFETY: PR_CAP_AMBIENT/RAISE — pas d'accès mémoire utilisateur.
    let ret = unsafe {
        raw_syscall_prctl(
            PR_CAP_AMBIENT,
            PR_CAP_AMBIENT_RAISE,
            u64::from(cap.as_raw()),
            0,
            0,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Retire `cap` de l'ensemble ambient.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : valeur de capability inconnue côté kernel.
pub fn cap_ambient_lower(cap: Capability) -> Result<(), Errno> {
    // SAFETY: PR_CAP_AMBIENT/LOWER — pas d'accès mémoire utilisateur.
    let ret = unsafe {
        raw_syscall_prctl(
            PR_CAP_AMBIENT,
            PR_CAP_AMBIENT_LOWER,
            u64::from(cap.as_raw()),
            0,
            0,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Vide totalement l'ensemble ambient du thread.
///
/// # Errors
///
/// - Aucune en pratique.
pub fn cap_ambient_clear_all() -> Result<(), Errno> {
    // SAFETY: PR_CAP_AMBIENT/CLEAR_ALL — pas d'accès mémoire utilisateur.
    let ret = unsafe { raw_syscall_prctl(PR_CAP_AMBIENT, PR_CAP_AMBIENT_CLEAR_ALL, 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Indique si `cap` est dans l'ensemble ambient.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : valeur de capability inconnue côté kernel.
pub fn cap_ambient_is_set(cap: Capability) -> Result<bool, Errno> {
    // SAFETY: PR_CAP_AMBIENT/IS_SET — pas d'accès mémoire utilisateur ;
    // valeur retournée comme code de retour (0 ou 1).
    let ret = unsafe {
        raw_syscall_prctl(
            PR_CAP_AMBIENT,
            PR_CAP_AMBIENT_IS_SET,
            u64::from(cap.as_raw()),
            0,
            0,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(ret != 0)
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_prctl(op: i32, arg2: u64, arg3: u64, arg4: u64, arg5: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_prctl (x86_64 = 157). Selon `op`, le kernel peut lire
    // ou écrire à des pointeurs passés via arg2..arg5 ; les fonctions
    // d'opération individuelles (au-dessus) garantissent la validité de
    // ces pointeurs lorsqu'elles en passent. Sans pointeur, pas
    // d'accès mémoire utilisateur.
    //
    // **Pas de `readonly`** : certaines opérations (PR_GET_NAME,
    // PR_GET_PDEATHSIG) font écrire le kernel à un pointeur user.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 157_i64,
            in("rdi") i64::from(op),
            in("rsi") arg2,
            in("rdx") arg3,
            in("r10") arg4,
            in("r8") arg5,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_prctl(op: i32, arg2: u64, arg3: u64, arg4: u64, arg5: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_prctl (aarch64 = 167). Mêmes considérations que x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 167_i64,
            inout("x0") i64::from(op) => ret,
            in("x1") arg2,
            in("x2") arg3,
            in("x3") arg4,
            in("x4") arg5,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// rlimits (sous-section 6 de family-process.md).
//
// `prlimit64` est le syscall préféré ; `getrlimit`/`setrlimit` legacy
// sont exposés mais routés au plus simple. La représentation kernel de
// `struct rlimit64` est { u64 rlim_cur ; u64 rlim_max }, identique à
// `struct rlimit` sur LP64. On la traduit en `Rlimit` via mapping
// `RLIM_INFINITY <-> RlimitValue::Infinity`.
// ─────────────────────────────────────────────────────────────────────────

#[repr(C)]
#[derive(Default, Clone, Copy)]
struct KernelRlimit64 {
    rlim_cur: u64,
    rlim_max: u64,
}

const RLIM_INFINITY: u64 = u64::MAX;

fn rlim_value_to_kernel(v: RlimitValue) -> u64 {
    match v {
        RlimitValue::Finite(n) => n,
        RlimitValue::Infinity => RLIM_INFINITY,
    }
}

fn rlim_value_from_kernel(n: u64) -> RlimitValue {
    if n == RLIM_INFINITY {
        RlimitValue::Infinity
    } else {
        RlimitValue::Finite(n)
    }
}

fn rlimit_to_kernel(r: Rlimit) -> KernelRlimit64 {
    KernelRlimit64 {
        rlim_cur: rlim_value_to_kernel(r.soft),
        rlim_max: rlim_value_to_kernel(r.hard),
    }
}

fn rlimit_from_kernel(k: KernelRlimit64) -> Rlimit {
    Rlimit {
        soft: rlim_value_from_kernel(k.rlim_cur),
        hard: rlim_value_from_kernel(k.rlim_max),
    }
}

/// Retourne la `Rlimit` courante du processus pour `resource`.
///
/// Air recommande [`prlimit`] qui est plus expressif (cible un autre
/// processus, opération atomique) ; `getrlimit` est exposé pour
/// compatibilité.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : ressource inconnue (impossible via l'API typée).
pub fn getrlimit(resource: Resource) -> Result<Rlimit, Errno> {
    // Délègue à prlimit(self, resource, None) pour ne pas dupliquer
    // l'asm! et bénéficier de la même conversion.
    prlimit(None, resource, None)
}

/// Définit la `Rlimit` courante du processus pour `resource`.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : valeurs incohérentes (soft > hard, …).
/// - [`Errno::EPERM`] : tentative de relever la hard limit sans
///   `CAP_SYS_RESOURCE`.
pub fn setrlimit(resource: Resource, limit: Rlimit) -> Result<(), Errno> {
    // Délègue à prlimit(self, resource, Some(limit)) ; on ignore l'ancienne
    // valeur retournée.
    let _ = prlimit(None, resource, Some(limit))?;
    Ok(())
}

/// `prlimit64` : lit et/ou modifie atomiquement la `Rlimit` d'un
/// processus.
///
/// `pid = None` désigne le processus courant. Retourne **toujours** la
/// limite *avant* modification (équivalent kernel "old_limit").
///
/// # Errors
///
/// - [`Errno::EINVAL`] : valeurs incohérentes.
/// - [`Errno::EPERM`] : tentative de relever la hard limit sans
///   `CAP_SYS_RESOURCE`, ou ciblage d'un autre processus sans droits.
/// - [`Errno::ESRCH`] : `pid` n'existe pas.
pub fn prlimit(
    pid: Option<Pid>,
    resource: Resource,
    new_limit: Option<Rlimit>,
) -> Result<Rlimit, Errno> {
    let pid_arg = pid.map_or(0_i32, |p| p.as_raw());

    let new_buf: Option<KernelRlimit64> = new_limit.map(rlimit_to_kernel);
    let new_ptr: u64 = match &new_buf {
        Some(b) => {
            let p: *const KernelRlimit64 = b;
            p as u64
        }
        None => 0,
    };

    let mut old_buf = KernelRlimit64::default();
    let old_ptr: *mut KernelRlimit64 = &mut old_buf;

    // SAFETY: prlimit64(2) lit `new_limit` si non-null, écrit `old_limit`
    // si non-null. Nous fournissons toujours `old_ptr` valide ; `new_ptr`
    // est null ou pointe sur `new_buf` valide pour la durée du call.
    let ret = unsafe { raw_syscall_prlimit64(pid_arg, resource as u32, new_ptr, old_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(rlimit_from_kernel(old_buf))
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_prlimit64(pid: i32, resource: u32, new_limit: u64, old_limit: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_prlimit64 (x86_64 = 302). Le kernel lit `new_limit`
    // (16 octets) si non-null ; écrit `old_limit` (16 octets) si non-null.
    // Pas de `readonly` (écriture sur `*old_limit`).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 302_i64,
            in("rdi") i64::from(pid),
            in("rsi") i64::from(resource),
            in("rdx") new_limit,
            in("r10") old_limit,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_prlimit64(pid: i32, resource: u32, new_limit: u64, old_limit: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_prlimit64 (aarch64 = 261). Mêmes considérations.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 261_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") i64::from(resource),
            in("x2") new_limit,
            in("x3") old_limit,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// capget / capset (sous-section 7 de family-process.md).
//
// Version 3 capabilities (kernel ≥ 2.6.25) : header + array de 2 data
// structs ; chaque data struct contient `(effective, permitted,
// inheritable)` en `u32`. Index 0 = bits 0-31, index 1 = bits 32-63.
//
// La conversion `CapabilityMask (u64) ↔ (lo, hi)` est faite par les
// helpers privés `mask_to_words` / `words_to_mask` ci-dessous, testés
// explicitement pour qu'une éventuelle inversion lo/hi soit détectée
// (cf. JOURNAL session 2026-05-24).
// ─────────────────────────────────────────────────────────────────────────

const LINUX_CAPABILITY_VERSION_3: u32 = 0x2008_0522;

#[repr(C)]
struct KernelCapHeader {
    version: u32,
    pid: i32,
}

#[repr(C)]
#[derive(Default, Clone, Copy)]
struct KernelCapData {
    effective: u32,
    permitted: u32,
    inheritable: u32,
}

fn mask_to_words(mask: CapabilityMask) -> (u32, u32) {
    let bits = mask.bits();
    // Troncature exacte : `bits & 0xFFFF_FFFF` fit dans u32 par
    // construction.
    #[allow(clippy::cast_possible_truncation)]
    let lo = (bits & 0xFFFF_FFFF) as u32;
    // Troncature exacte : après `>> 32`, la valeur résiduelle est dans
    // `[0, u32::MAX]`.
    #[allow(clippy::cast_possible_truncation)]
    let hi = (bits >> 32) as u32;
    (lo, hi)
}

fn words_to_mask(lo: u32, hi: u32) -> CapabilityMask {
    let bits = (u64::from(hi) << 32) | u64::from(lo);
    CapabilityMask::from_bits(bits)
}

fn cap_target_to_kernel_pid(target: CapabilityTarget) -> i32 {
    match target {
        CapabilityTarget::CurrentThread => 0,
        CapabilityTarget::Thread(tid) => tid.as_raw(),
        CapabilityTarget::Process(pid) => pid.as_raw(),
    }
}

/// Lit les capabilities du thread cible.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : version capabilities non supportée par le kernel
///   (Air utilise version 3, supportée depuis 2.6.25).
/// - [`Errno::EPERM`] : ciblage d'un thread sans droits (rare en lecture).
pub fn capget(target: CapabilityTarget) -> Result<CapabilitySet, Errno> {
    let mut header = KernelCapHeader {
        version: LINUX_CAPABILITY_VERSION_3,
        pid: cap_target_to_kernel_pid(target),
    };
    let mut data: [KernelCapData; 2] = [KernelCapData::default(); 2];
    let header_ptr: *mut KernelCapHeader = &mut header;
    let data_ptr: *mut KernelCapData = data.as_mut_ptr();
    // SAFETY: capget(2) lit `*header` et écrit deux `KernelCapData`
    // consécutives à `data_ptr` ; les deux pointeurs sont locaux et
    // valides pour la durée du call.
    let ret = unsafe { raw_syscall_capget(header_ptr as u64, data_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(CapabilitySet {
        effective: words_to_mask(data[0].effective, data[1].effective),
        permitted: words_to_mask(data[0].permitted, data[1].permitted),
        inheritable: words_to_mask(data[0].inheritable, data[1].inheritable),
    })
}

/// Écrit les capabilities du thread cible.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : version capabilities ou layout invalides.
/// - [`Errno::EPERM`] : tentative d'élever une capability hors permitted,
///   ou modification d'un autre thread sans droits.
pub fn capset(target: CapabilityTarget, set: &CapabilitySet) -> Result<(), Errno> {
    let mut header = KernelCapHeader {
        version: LINUX_CAPABILITY_VERSION_3,
        pid: cap_target_to_kernel_pid(target),
    };
    let (e_lo, e_hi) = mask_to_words(set.effective);
    let (p_lo, p_hi) = mask_to_words(set.permitted);
    let (i_lo, i_hi) = mask_to_words(set.inheritable);
    let data: [KernelCapData; 2] = [
        KernelCapData {
            effective: e_lo,
            permitted: p_lo,
            inheritable: i_lo,
        },
        KernelCapData {
            effective: e_hi,
            permitted: p_hi,
            inheritable: i_hi,
        },
    ];
    let header_ptr: *mut KernelCapHeader = &mut header;
    let data_ptr: *const KernelCapData = data.as_ptr();
    // SAFETY: capset(2) lit `*header` et lit deux `KernelCapData`
    // consécutives à `data_ptr`. Tout est local et valide pour la durée
    // du call.
    let ret = unsafe { raw_syscall_capset(header_ptr as u64, data_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_capget(header: u64, data: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_capget (x86_64 = 125). Le kernel lit `*header` (8 octets)
    // et écrit 2 × 12 octets à `data`. Pas de `readonly` (écriture).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 125_i64,
            in("rdi") header,
            in("rsi") data,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_capset(header: u64, data: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_capset (x86_64 = 126). Lecture seule de `*header` et
    // `*data` côté user ; `readonly` correct.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 126_i64,
            in("rdi") header,
            in("rsi") data,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

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

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_capset(header: u64, data: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_capset (aarch64 = 91). `readonly` car lecture seule.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 91_i64,
            inout("x0") header => ret,
            in("x1") data,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helper interne de conversion `errno`.
// ─────────────────────────────────────────────────────────────────────────

/// Convertit une valeur de retour de syscall strictement négative en
/// [`Errno`]. Le kernel borne les errno à `[-4095, -1]` (`MAX_ERRNO`).
fn errno_from_negative_syscall_ret(ret: i64) -> Errno {
    debug_assert!(ret < 0 && ret > -4096);
    // `ret.wrapping_neg()` est donc dans `[1, 4095]` — toujours fit in i32.
    #[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)
}

// ─────────────────────────────────────────────────────────────────────────
// Affinité CPU — sched_setaffinity / sched_getaffinity
// Cf. `docs/specs/layer-0/family-process-affinity.md`.
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sched_setaffinity(pid: i32, len: u64, mask: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_sched_setaffinity (x86_64 = 203). Le kernel **lit** `len` octets à
    //   `mask` (jamais d'écriture) → `readonly` correct ; validité du buffer
    //   garantie par l'appelant (`CpuSet` local, 128 octets).
    // - x86_64 ABI : numéro en RAX, args en RDI/RSI/RDX ; retour RAX ; clobbe
    //   RCX/R11.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 203_i64,
            in("rdi") i64::from(pid),
            in("rsi") len,
            in("rdx") mask,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sched_setaffinity(pid: i32, len: u64, mask: u64) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 ABI : numéro en X8 (= 122), args en
    // X0/X1/X2, retour en X0. Le kernel **lit** `mask` → `readonly`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 122_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") len,
            in("x2") mask,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sched_getaffinity(pid: i32, len: u64, mask: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_sched_getaffinity (x86_64 = 204). Le kernel **écrit** jusqu'à `len`
    //   octets à `mask` → **pas de `readonly`** ; validité/taille du buffer
    //   garanties par l'appelant (`CpuSet` local, 128 octets).
    // - Retourne le nombre d'octets écrits (≥ 0) ou `-errno`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 204_i64,
            in("rdi") i64::from(pid),
            in("rsi") len,
            in("rdx") mask,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sched_getaffinity(pid: i32, len: u64, mask: u64) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 ABI : numéro en X8 (= 123), args en
    // X0/X1/X2, retour en X0. Le kernel **écrit** dans `mask` → pas de `readonly`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 123_i64,
            inout("x0") i64::from(pid) => ret,
            in("x1") len,
            in("x2") mask,
            options(nostack, preserves_flags),
        );
    }
    ret
}

/// Identifiant de tâche pour les opérations d'affinité : `None` = **tâche
/// appelante** (sentinelle kernel `0` typée en `Option`, ADR-021 conv. 1).
fn affinity_pid(tid: Option<Tid>) -> i32 {
    // `0` = la tâche appelante (jamais exposé comme entier magique).
    tid.map_or(0, Tid::as_raw)
}

/// Fixe l'**affinité CPU** d'une tâche (`sched_setaffinity(2)`) : la tâche ne sera
/// ordonnancée que sur les CPU présents dans `cpus`. `tid = None` cible la tâche
/// appelante. Débloque `air-thread::cpu_affinity` (couche 1).
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `cpus` ne contient **aucun** CPU autorisé/en ligne.
/// - [`Errno::ESRCH`] : aucune tâche ne porte ce `tid`.
/// - [`Errno::EPERM`] : privilèges insuffisants pour changer l'affinité de `tid`.
pub fn set_cpu_affinity(tid: Option<Tid>, cpus: &CpuSet) -> Result<(), Errno> {
    let bytes = cpus.as_bytes();
    let len = bytes.len() as u64;
    let mask = bytes.as_ptr() as u64;
    // SAFETY: `mask` pointe les `len` octets (= 128) du `CpuSet` de l'appelant,
    // valides en lecture pour la durée de l'appel ; le kernel ne les écrit pas.
    let ret = unsafe { raw_syscall_sched_setaffinity(affinity_pid(tid), len, mask) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit l'**affinité CPU** courante d'une tâche (`sched_getaffinity(2)`) **dans**
/// `cpus` (buffer fourni, zéro allocation). `tid = None` cible la tâche appelante.
///
/// # Errors
///
/// - [`Errno::ESRCH`] : aucune tâche ne porte ce `tid`.
/// - [`Errno::EINVAL`] : taille de masque incohérente (ne se produit pas avec un
///   `CpuSet` de [`air_sys_types::system::CPU_SETSIZE`] bits).
pub fn get_cpu_affinity(tid: Option<Tid>, cpus: &mut CpuSet) -> Result<(), Errno> {
    let len = core::mem::size_of::<CpuSet>() as u64;
    let mask = core::ptr::from_mut(cpus).cast::<u8>() as u64;
    // SAFETY: `mask` pointe les `len` octets (= 128) du `CpuSet` **mutable** de
    // l'appelant ; le kernel y écrit au plus `len` octets (le bitmap d'affinité).
    // `CpuSet` est `#[repr(C)]` sans padding ⇒ tout motif d'octets est valide.
    let ret = unsafe { raw_syscall_sched_getaffinity(affinity_pid(tid), len, mask) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// exec / redirection — execve, execveat, dup3, fchdir, chdir.
//
// Surface pilotée par le contrat de la couche 1 (`air-process`) : lancer un
// programme (exec), rediriger ses stdin/stdout/stderr (dup3) et fixer son
// répertoire de travail (fchdir / chdir). Cf. `docs/specs/layer-0/
// family-process.md`, section « exec / redirection ».
// ─────────────────────────────────────────────────────────────────────────

/// `AT_FDCWD` : base « répertoire courant » des opérations `*at` (sentinelle
/// kernel `-100`, typée [`DirFd::Cwd`] côté Air, cf. ADR-021 convention 1).
const AT_FDCWD: i32 = -100;

/// Convertit une [`DirFd`] en l'entier attendu par l'ABI syscall (`AT_FDCWD`
/// pour [`DirFd::Cwd`], sinon le fd emprunté).
fn dirfd_to_raw(dirfd: DirFd<'_>) -> i32 {
    match dirfd {
        DirFd::Cwd => AT_FDCWD,
        DirFd::Fd(fd) => fd.as_raw_fd(),
    }
}

/// Tableau de pointeurs C terminé par `NULL`, pour le marshalling d'`argv` /
/// `envp` vers `execve(2)` / `execveat(2)`.
///
/// Ces syscalls attendent un argument de type `char *const argv[]` : une suite
/// de pointeurs vers des chaînes C **terminée par un pointeur `NULL`**. Ce type
/// matérialise cette **frontière de marshalling**, qui est *fuzzée*
/// (`fuzz/fuzz_targets/fuzz_exec_argv.rs`) : construction depuis une liste
/// arbitraire (vide, longue), terminaison `NULL` toujours présente, ordre
/// préservé.
///
/// **Rejet des NUL embarqués — par construction.** Un argument C ne peut pas
/// contenir d'octet NUL (il y serait interprété comme terminateur). L'entrée
/// étant une tranche de [`CStr`] — type qui **garantit** l'absence de NUL
/// interne — l'invariant est assuré *en amont*, là où l'appelant construit ses
/// `&CStr` (typiquement via `CStr::from_bytes_with_nul` ou `CString::new`, qui
/// rejettent proprement un NUL embarqué). Aucune revalidation n'est donc
/// nécessaire ici (Principe 4 : « parse, don't validate »).
///
/// **Allocation.** La construction alloue un [`Vec`] de `items.len() + 1`
/// pointeurs : c'est l'exception d'allocation documentée d'ADR-021 §4 (buffer
/// dynamique *intrinsèque* — sa taille dépend du nombre d'arguments, inconnu à
/// la compilation). Les chaînes elles-mêmes ne sont **pas** copiées : les
/// pointeurs empruntent les [`CStr`] fournis (d'où la durée de vie `'a`).
pub struct CStrArray<'a> {
    /// Pointeurs vers chaque `CStr`, suivis d'un pointeur `NULL` final.
    /// Invariant : `ptrs.len() >= 1` et `ptrs[ptrs.len() - 1].is_null()`.
    ptrs: Vec<*const c_char>,
    /// Lie la durée de vie des pointeurs à celle de la tranche source.
    _borrow: PhantomData<&'a [&'a CStr]>,
}

impl<'a> CStrArray<'a> {
    /// Construit le tableau `NULL`-terminé à partir de `items`.
    ///
    /// Une tranche **vide** produit un tableau ne contenant que le `NULL` final
    /// (`argv = { NULL }`, soit `argc == 0`) — accepté par le kernel.
    #[must_use]
    pub fn new(items: &'a [&'a CStr]) -> Self {
        // `+ 1` pour le terminateur NULL. `saturating_add` par discipline
        // (Principe 2) ; la capacité d'une tranche ne peut pas atteindre
        // `usize::MAX`, donc la saturation ne se déclenche jamais.
        let mut ptrs = Vec::with_capacity(items.len().saturating_add(1));
        for item in items {
            ptrs.push(item.as_ptr());
        }
        ptrs.push(core::ptr::null());
        Self {
            ptrs,
            _borrow: PhantomData,
        }
    }

    /// Nombre d'arguments (hors terminateur `NULL`).
    #[must_use]
    pub fn len(&self) -> usize {
        // Invariant : `ptrs` contient toujours le `NULL` final en sus.
        self.ptrs.len().saturating_sub(1)
    }

    /// Vrai si la liste est vide (le tableau ne contient que le `NULL` final).
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Pointeur vers le tableau de pointeurs, à transmettre au syscall.
    #[inline]
    fn as_ptr(&self) -> *const *const c_char {
        self.ptrs.as_ptr()
    }
}

/// Remplace l'image mémoire du processus courant par l'exécutable situé à
/// `path`, avec les arguments `argv` et l'environnement `envp`.
///
/// Cf. `docs/specs/layer-0/family-process.md`. En cas de **succès, ne retourne
/// jamais** (le processus exécute désormais le nouveau binaire) — d'où le type
/// `Result<Infallible, Errno>` (ADR-021 convention 5). En cas d'échec, retourne
/// `Err(errno)`.
///
/// `argv` / `envp` sont des tranches de [`CStr`] ; le wrapper en construit les
/// tableaux de pointeurs C `NULL`-terminés via [`CStrArray`]. Par convention
/// POSIX, `argv[0]` est le nom du programme ; une tranche vide est acceptée par
/// le kernel (`argc == 0`).
///
/// Pour exécuter un binaire désigné par un **fd** (sans race sur le chemin),
/// préférer [`execveat`] avec [`ExecveatFlags::EMPTY_PATH`].
///
/// # Errors
///
/// - [`Errno::EACCES`] : `path` n'est pas exécutable, un répertoire du chemin
///   interdit la traversée, ou le système de fichiers est monté `noexec`.
/// - [`Errno::ENOENT`] : `path` (ou l'interpréteur `#!` d'un script) n'existe
///   pas.
/// - [`Errno::ENOEXEC`] : `path` existe mais n'est pas dans un format
///   exécutable reconnu (ni ELF, ni script avec `#!`).
/// - [`Errno::E2BIG`] : `argv` + `envp` dépassent la limite kernel (`ARG_MAX`).
/// - `ENOMEM`, `ETXTBSY`, `ELOOP`, … : cf. `execve(2)`.
pub fn execve(path: &CStr, argv: &[&CStr], envp: &[&CStr]) -> Result<Infallible, Errno> {
    // L'allocation des tableaux de pointeurs ([`CStrArray::new`]) a lieu **ici**.
    // Le cœur (syscall, sans allocation) est délégué à [`execve_prepared`], que
    // les appelants en chemin **post-fork** invoquent directement avec des
    // [`CStrArray`] matérialisés **avant** le fork (async-signal-safety).
    let c_argv = CStrArray::new(argv);
    let c_envp = CStrArray::new(envp);
    execve_prepared(path, &c_argv, &c_envp)
}

/// Variante d'[`execve`] **sans allocation** : reçoit des tableaux de pointeurs
/// `argv`/`envp` **déjà construits** ([`CStrArray`]).
///
/// Destinée au chemin **post-fork / pré-`execve`** : l'appelant matérialise les
/// [`CStrArray`] dans le parent **avant** `clone3`/`fork`, puis les passe ici
/// depuis l'enfant. Cette fonction n'alloue rien — seul un syscall est émis —
/// donc elle est sûre dans la fenêtre fork→exec où aucune allocation (verrou
/// allocateur potentiellement tenu par un autre thread au moment du fork) n'est
/// permise. [`execve`] délègue à cette fonction après avoir bâti ses tableaux.
///
/// En cas de **succès, ne retourne jamais** (image mémoire remplacée). En cas
/// d'échec, retourne `Err(errno)`.
///
/// # Errors
///
/// Identiques à [`execve`] (`EACCES`, `ENOENT`, `ENOEXEC`, `E2BIG`, …).
pub fn execve_prepared(
    path: &CStr,
    argv: &CStrArray<'_>,
    envp: &CStrArray<'_>,
) -> Result<Infallible, Errno> {
    // SAFETY:
    // - `path` est un `CStr` valide NUL-terminé (le kernel le lit jusqu'au NUL).
    // - `argv`/`envp` exposent chacun un tableau de pointeurs C valide, terminé
    //   par NULL, vivant pour toute la durée de l'appel ; les chaînes pointées
    //   sont les `CStr` empruntés, vivants eux aussi (durée de vie liée par
    //   `CStrArray<'a>`). Le kernel ne fait que **lire** ces données.
    // - Succès : le syscall ne revient pas (image remplacée). Échec : ret < 0.
    let ret = unsafe {
        raw_syscall_execve(
            path.as_ptr() as u64,
            argv.as_ptr() as u64,
            envp.as_ptr() as u64,
        )
    };
    // Seul un échec ramène ici : `ret` est toujours `< 0`. La conversion errno
    // impose elle-même `ret ∈ [-4095, -1]` (debug_assert interne).
    Err(errno_from_negative_syscall_ret(ret))
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_execve(path: u64, argv: u64, envp: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_execve (x86_64 = 59). Le kernel **lit** la chaîne `path` (jusqu'au
    //   NUL) et les tableaux `argv`/`envp` (jusqu'au pointeur NULL, puis chaque
    //   chaîne jusqu'à son NUL) ; il n'écrit aucune mémoire utilisateur →
    //   `readonly` correct. Validité garantie par l'appelant.
    // - Succès : ne revient pas (image remplacée). Échec : ret = -errno.
    // - x86_64 ABI : numéro en RAX, args en RDI/RSI/RDX ; retour RAX ; clobbe
    //   RCX/R11.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 59_i64,
            in("rdi") path,
            in("rsi") argv,
            in("rdx") envp,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_execve(path: u64, argv: u64, envp: u64) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 ABI : SYS_execve (aarch64 = 221),
    // numéro en X8, args en X0/X1/X2, retour en X0. Lecture seule → `readonly`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 221_i64,
            inout("x0") path => ret,
            in("x1") argv,
            in("x2") envp,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

/// Variante *at d'[`execve`] (préférée par ADR-021) : résout l'exécutable
/// relativement à `dirfd`, ou — avec [`ExecveatFlags::EMPTY_PATH`] et
/// `path == c""` — exécute **directement** le binaire désigné par `dirfd`
/// (un fd ouvert sur l'exécutable, typiquement avec `O_PATH`), éliminant toute
/// race entre l'ouverture/vérification et l'exec.
///
/// Cf. `docs/specs/layer-0/family-process.md`. Comme [`execve`], **ne retourne
/// jamais en cas de succès**.
///
/// # Errors
///
/// Mêmes erreurs qu'[`execve`], plus :
///
/// - [`Errno::EBADF`] : `dirfd` n'est ni `AT_FDCWD` ni un fd ouvert valide.
/// - [`Errno::ENOENT`] : `path` est vide sans [`ExecveatFlags::EMPTY_PATH`].
/// - [`Errno::ELOOP`] : composant final symbolique avec
///   [`ExecveatFlags::SYMLINK_NOFOLLOW`].
pub fn execveat(
    dirfd: DirFd<'_>,
    path: &CStr,
    argv: &[&CStr],
    envp: &[&CStr],
    flags: ExecveatFlags,
) -> Result<Infallible, Errno> {
    let c_argv = CStrArray::new(argv);
    let c_envp = CStrArray::new(envp);
    // SAFETY: identique à `execve` pour `path`/`argv`/`envp` (lecture seule),
    // plus :
    // - `dirfd` est `AT_FDCWD` ou un fd valide emprunté (résolution relative,
    //   ou exécutable direct si `EMPTY_PATH`).
    // - `flags` est un masque `AT_*` valide (typé `ExecveatFlags`).
    let ret = unsafe {
        raw_syscall_execveat(
            dirfd_to_raw(dirfd),
            path.as_ptr() as u64,
            c_argv.as_ptr() as u64,
            c_envp.as_ptr() as u64,
            flags.bits(),
        )
    };
    // Seul un échec ramène ici : `ret` est toujours `< 0`.
    Err(errno_from_negative_syscall_ret(ret))
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_execveat(dirfd: i32, path: u64, argv: u64, envp: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_execveat (x86_64 = 322). Lecture seule de `path`/`argv`/`envp` (cf.
    //   `raw_syscall_execve`) → `readonly`. `dirfd` (étendu en signe : AT_FDCWD
    //   = -100 ou fd valide) et `flags` sont des scalaires.
    // - Succès : ne revient pas. Échec : ret = -errno.
    // - x86_64 ABI : args en RDI/RSI/RDX/R10/R8.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 322_i64,
            in("rdi") i64::from(dirfd),
            in("rsi") path,
            in("rdx") argv,
            in("r10") envp,
            in("r8") 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_execveat(dirfd: i32, path: u64, argv: u64, envp: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 ABI : SYS_execveat (aarch64 = 281),
    // numéro en X8, args en X0..X4, retour en X0. Lecture seule → `readonly`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 281_i64,
            inout("x0") i64::from(dirfd) => ret,
            in("x1") path,
            in("x2") argv,
            in("x3") envp,
            in("x4") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

/// Duplique le descripteur `old` vers le numéro `new` (`dup3(2)`), en fermant
/// atomiquement `new` s'il était ouvert. Retourne le nouveau descripteur,
/// possédé ([`OwnedFd`], fermé au `Drop`).
///
/// Cf. `docs/specs/layer-0/family-process.md`. Variante **moderne** de `dup2`
/// (ADR-021) : les drapeaux sont explicites ([`Dup3Flags`], seul `O_CLOEXEC`
/// est valide). Cas d'usage couche 1 : rediriger les flux standard d'un enfant
/// (`dup3(pipe, STDOUT_FILENO, …)`) juste avant l'`exec`.
///
/// À la différence de `dup2`, `dup3` **échoue** (`EINVAL`) si `old == new` :
/// pas de no-op silencieux. Le numéro `new` doit donc différer de `old`.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `flags` invalides, **ou** `old == new`.
/// - [`Errno::EBADF`] : `new` hors de la plage autorisée (`> RLIMIT_NOFILE`).
/// - [`Errno::EBUSY`] : course (rare) avec `open`/`dup` concurrents sur `new`.
/// - [`Errno::EINTR`] : interrompu par un signal (remonté tel quel, ADR-021
///   convention 2).
pub fn dup3(old: BorrowedFd<'_>, new: RawFd, flags: Dup3Flags) -> Result<OwnedFd, Errno> {
    // SAFETY: `dup3(2)` ne touche aucune mémoire utilisateur ; il installe une
    // copie de l'entrée de table de fd `old` au numéro `new` (fermant `new` au
    // préalable s'il était ouvert), de manière atomique. `flags` (typé) ne peut
    // valoir que `O_CLOEXEC`.
    let ret = unsafe { raw_syscall_dup3(old.as_raw_fd(), new, flags.bits()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // Succès : `ret == new` (le numéro demandé), donc tient dans un `i32`.
    #[allow(clippy::cast_possible_truncation)]
    let new_fd = ret as RawFd;
    // SAFETY: le kernel vient d'installer un fd valide au numéro `new`, dont
    // Air prend désormais la propriété exclusive (fermé par `OwnedFd::Drop`).
    Ok(unsafe { OwnedFd::from_raw_fd(new_fd) })
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_dup3(oldfd: i32, newfd: i32, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_dup3 (x86_64 = 292) ne touche aucune mémoire utilisateur
    // (`readonly`). Args étendus en signe (fd ≥ 0 ici ; l'extension reste
    // correcte). x86_64 ABI : args en RDI/RSI/RDX.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 292_i64,
            in("rdi") i64::from(oldfd),
            in("rsi") i64::from(newfd),
            in("rdx") 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_dup3(oldfd: i32, newfd: i32, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 ABI : SYS_dup3 (aarch64 = 24),
    // numéro en X8, args en X0/X1/X2, retour en X0. Lecture seule → `readonly`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 24_i64,
            inout("x0") i64::from(oldfd) => ret,
            in("x1") i64::from(newfd),
            in("x2") i64::from(flags),
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

/// Change le répertoire de travail courant du processus pour celui référencé
/// par le descripteur `dir` (`fchdir(2)`).
///
/// Cf. `docs/specs/layer-0/family-process.md`. Variante par fd de [`chdir`] :
/// pas de race sur le chemin (le répertoire est déjà ouvert et épinglé). Cas
/// d'usage couche 1 : fixer le `current_dir` d'un enfant à partir d'un fd
/// vérifié, juste avant l'`exec`.
///
/// # Errors
///
/// - [`Errno::EBADF`] : `dir` n'est pas un descripteur ouvert valide.
/// - [`Errno::ENOTDIR`] : `dir` ne référence pas un répertoire.
/// - [`Errno::EACCES`] : permission de recherche refusée sur le répertoire.
pub fn fchdir(dir: BorrowedFd<'_>) -> Result<(), Errno> {
    // SAFETY: `fchdir(2)` ne touche aucune mémoire utilisateur ; il bascule le
    // répertoire courant du processus vers le répertoire référencé par `dir`.
    let ret = unsafe { raw_syscall_fchdir(dir.as_raw_fd()) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_fchdir(fd: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_fchdir (x86_64 = 81) ne touche aucune mémoire utilisateur
    // (`readonly`). x86_64 ABI : argument unique en RDI.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 81_i64,
            in("rdi") i64::from(fd),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_fchdir(fd: i32) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 ABI : SYS_fchdir (aarch64 = 50),
    // numéro en X8, argument en X0, retour en X0. Lecture seule → `readonly`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 50_i64,
            inout("x0") i64::from(fd) => ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

/// Change le répertoire de travail courant du processus pour `path`
/// (`chdir(2)`).
///
/// Cf. `docs/specs/layer-0/family-process.md`. Cas d'usage couche 1 : fixer le
/// `current_dir` d'un enfant juste avant l'`exec`. Préférer [`fchdir`] quand un
/// fd de répertoire est disponible (pas de race sur le chemin).
///
/// # Errors
///
/// - [`Errno::ENOENT`] : `path` n'existe pas.
/// - [`Errno::ENOTDIR`] : un composant de `path` n'est pas un répertoire.
/// - [`Errno::EACCES`] : permission de recherche refusée.
/// - [`Errno::ENAMETOOLONG`] : `path` trop long.
pub fn chdir(path: &CStr) -> Result<(), Errno> {
    // SAFETY: `chdir(2)` **lit** la chaîne `path` (jusqu'au NUL) et n'écrit
    // aucune mémoire utilisateur → `readonly`. `path` est un `CStr` valide.
    let ret = unsafe { raw_syscall_chdir(path.as_ptr() as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Change le **répertoire racine** du processus vers `path` (`chroot(2)`) —
/// **descellement additif [ADR-085](../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md)**
/// pour la face libc. Confinement de processus (`CAP_SYS_CHROOT` requis).
///
/// # Errors
///
/// - [`Errno::EPERM`] : `CAP_SYS_CHROOT` manquant.
/// - [`Errno::ENOENT`] : `path` n'existe pas.
/// - [`Errno::ENOTDIR`] : un composant de `path` n'est pas un répertoire.
pub fn chroot(path: &CStr) -> Result<(), Errno> {
    // SAFETY: `chroot(2)` **lit** la chaîne `path` (jusqu'au NUL) et n'écrit aucune
    // mémoire utilisateur → `readonly`. `path` est un `CStr` valide.
    let ret = unsafe { raw_syscall_chroot(path.as_ptr() as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_chdir(path: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_chdir (x86_64 = 80). Le kernel **lit** la chaîne `path`
    // (jusqu'au NUL), validité garantie par l'appelant ; aucune écriture
    // utilisateur → `readonly`. x86_64 ABI : argument unique en RDI.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 80_i64,
            in("rdi") path,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_chdir(path: u64) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 ABI : SYS_chdir (aarch64 = 49),
    // numéro en X8, argument (pointeur `path`) en X0, retour en X0. Lecture
    // seule → `readonly`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 49_i64,
            inout("x0") path => ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_chroot(path: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_chroot (x86_64 = 161). Le kernel **lit** la chaîne `path` (jusqu'au
    // NUL), validité garantie par l'appelant ; aucune écriture utilisateur → `readonly`.
    // x86_64 ABI : argument unique en RDI.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 161_i64,
            in("rdi") path,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_chroot(path: u64) -> i64 {
    let ret: i64;
    // SAFETY: voir version x86_64 ; aarch64 ABI : SYS_chroot (aarch64 = 51), numéro en
    // X8, argument (pointeur `path`) en X0, retour en X0. Lecture seule → `readonly`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 51_i64,
            inout("x0") path => ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

/// API de fuzzing **pure** (sans syscall) de la frontière de marshalling
/// `argv`/`envp` ([`CStrArray`]). Le harnais cargo-fuzz
/// (`fuzz/fuzz_targets/fuzz_exec_argv.rs`) y délègue ; l'oracle vit ici pour
/// accéder aux internes de [`CStrArray`] (le tableau de pointeurs) tout en
/// restant testé et couvert. Suit le pattern de [`crate::io_uring::fuzz_api`].
pub mod fuzz_api {
    use super::CStrArray;
    use alloc::ffi::CString;
    use alloc::vec::Vec;
    use core::ffi::{CStr, c_char};

    /// Exerce la chaîne « octets bruts → `CString` → `CStrArray` » et la
    /// **parcourt** jusqu'au terminateur `NULL`, garantissant l'absence de
    /// panic / UB pour **toute** entrée (Principe 3 — frontière) :
    ///
    /// - **rejet propre des NUL embarqués** : `CString::new` rend `Err` (jamais
    ///   panic) dès qu'un morceau contient un octet NUL ; ces morceaux sont
    ///   simplement écartés ;
    /// - **totalité** : la construction du tableau ne panique jamais (liste
    ///   vide, ou très longue) ;
    /// - **terminaison NULL & validité** : le parcours s'arrête sur le `NULL`
    ///   final et relit chaque chaîne C (tout pointeur invalide ou toute
    ///   terminaison manquante ferait crasher sous sanitizer/libFuzzer).
    ///
    /// L'oracle *structurel* exact (ordre, exactitude des pointeurs) est
    /// vérifié par les tests unitaires `cstr_array_*`.
    pub fn marshal_exec_args(chunks: Vec<Vec<u8>>) {
        // Frontière 1 — NUL embarqué rejeté proprement (Err, jamais panic).
        let owned: Vec<CString> = chunks
            .iter()
            .filter_map(|chunk| CString::new(chunk.as_slice()).ok())
            .collect();
        let refs: Vec<&CStr> = owned.iter().map(CString::as_c_str).collect();

        // Frontière 2 — construction du tableau de pointeurs C NULL-terminé.
        let arr = CStrArray::new(&refs);
        let _ = arr.len();
        let _ = arr.is_empty();

        // Parcours jusqu'au terminateur NULL en relisant chaque chaîne : tout
        // écart (pointeur invalide, terminaison absente) ferait crasher la
        // cible libFuzzer.
        let base = arr.as_ptr();
        let mut i = 0_usize;
        loop {
            // SAFETY: `base` pointe `refs.len() + 1` pointeurs ; on s'arrête au
            // premier NULL (présent par construction en position `refs.len()`),
            // donc `i` reste borné par `refs.len()`.
            let ptr: *const c_char = unsafe { *base.add(i) };
            if ptr.is_null() {
                break;
            }
            // SAFETY: `ptr` non NULL ⇒ i-ème chaîne C vivante (empruntée à
            // `owned`), NUL-terminée par construction de `CStr`.
            let s = unsafe { CStr::from_ptr(ptr) };
            let _ = s.to_bytes();
            i = i.saturating_add(1);
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Runtime & libc — re-sceau `couche-0-v1.7` (ADR-051)
//
// 6 syscalls ajoutés pour le runtime Air (air-rt) et l'objectif libc :
// `getppid`, `set_tid_address`, `sched_yield`, `umask`, `getcwd`, `getrusage`.
// (Le 7ᵉ, `arch_prctl`, est x86_64-only et vit dans `crate::arch`.)
// Conventions ADR-021 : fonction dédiée typée, `Option`/newtypes, pas de
// sentinelle, zéro alloc sur le happy path.
// ─────────────────────────────────────────────────────────────────────────

/// Retourne le PID du **parent** du processus appelant (`getppid(2)`).
///
/// Retourne `None` lorsque le kernel rend `0`, c.-à-d. quand le parent n'est
/// **pas visible** dans le *PID namespace* du processus (ré-parentage hors
/// namespace). Le `0` du kernel — qui n'est pas un PID valide — est ainsi
/// re-présenté en `Option` plutôt qu'exposé comme sentinelle (ADR-021 §1).
#[must_use]
pub fn getppid() -> Option<Pid> {
    let raw = raw_syscall_getppid();
    // PID : `pid_t` (i32) ; les 32 bits hauts sont nuls pour une valeur valide.
    #[allow(clippy::cast_possible_truncation)]
    let raw32 = raw as i32;
    // `try_from_raw` rend `None` pour `0` (parent hors namespace).
    Pid::try_from_raw(raw32)
}

#[cfg(target_arch = "x86_64")]
#[inline]
fn raw_syscall_getppid() -> i64 {
    let ret: i64;
    // SAFETY: SYS_getppid (x86_64 = 110) ne touche aucune mémoire utilisateur ;
    // clobbe RCX/R11 comme tout `syscall` x86_64.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 110_i64,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
fn raw_syscall_getppid() -> i64 {
    let ret: i64;
    // SAFETY: SYS_getppid (aarch64 = 173) ne touche aucune mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 173_i64,
            lateout("x0") ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

/// Enregistre l'adresse `clear_child_tid` du thread appelant et retourne son TID
/// (`set_tid_address(2)`). À la **fin du thread**, le kernel écrit `0` à cette
/// adresse et émet un `FUTEX_WAKE` dessus — primitif de *join* (cf.
/// [`clone_thread`] et la famille [`futex`](crate::futex)).
///
/// `None` désenregistre (passe `NULL`). L'appel **ne peut pas échouer** et rend
/// toujours le TID appelant (`> 0`).
///
/// # Safety
///
/// Si `clear_child_tid` est `Some(addr)`, le kernel **conservera `addr`** et y
/// écrira à la terminaison du thread. L'appelant doit garantir que la mémoire
/// pointée reste **valide jusqu'à la fin du thread** (sinon écriture kernel dans
/// de la mémoire libérée). Même discipline que [`CloneArgs::child_tid`].
pub unsafe fn set_tid_address(clear_child_tid: Option<&core::sync::atomic::AtomicU32>) -> Tid {
    let ptr = clear_child_tid.map_or(0_usize, |a| core::ptr::from_ref(a) as usize);
    // SAFETY: l'appel délègue ; la liveness de `ptr` jusqu'à la mort du thread
    // relève du contrat `unsafe` de cette fonction.
    let raw = unsafe { raw_syscall_set_tid_address(ptr) };
    // Le kernel rend le TID appelant, strictement positif.
    #[allow(clippy::cast_possible_truncation)]
    let tid_raw = raw as i32;
    let nz = NonZeroI32::new(tid_raw).expect("set_tid_address : TID appelant > 0");
    Tid::from_nonzero(nz)
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_set_tid_address(tidptr: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_set_tid_address (x86_64 = 218). Le kernel **enregistre**
    // `tidptr` pour écriture à la mort du thread ; il n'écrit pas pendant
    // l'appel. La validité/liveness de `tidptr` relève du contrat de l'appelant.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 218_i64,
            in("rdi") tidptr,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_set_tid_address(tidptr: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_set_tid_address (aarch64 = 96). Voir la branche x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 96_i64,
            in("x0") tidptr,
            lateout("x0") ret,
            options(nostack, preserves_flags),
        );
    }
    ret
}

/// Cède volontairement le CPU à un autre thread prêt (`sched_yield(2)`).
///
/// Sous Linux, `sched_yield` **réussit toujours** (retour `0`) ; la fonction est
/// donc totale.
pub fn sched_yield() {
    let _ = raw_syscall_sched_yield();
}

#[cfg(target_arch = "x86_64")]
#[inline]
fn raw_syscall_sched_yield() -> i64 {
    let ret: i64;
    // SAFETY: SYS_sched_yield (x86_64 = 24) ne touche aucune mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 24_i64,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
fn raw_syscall_sched_yield() -> i64 {
    let ret: i64;
    // SAFETY: SYS_sched_yield (aarch64 = 124) ne touche aucune mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 124_i64,
            lateout("x0") ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

/// Fixe le **masque de création de fichiers** du processus et retourne l'ancien
/// (`umask(2)`). Opération **totale** (ne peut pas échouer).
#[must_use]
pub fn umask(new_mask: Mode) -> Mode {
    let previous = raw_syscall_umask(u64::from(new_mask));
    // L'ancien masque tient dans `mode_t` (12 bits significatifs) ⇒ conversion
    // sûre, jamais lossy (Principe 2 : pas d'`as` lossy).
    u32::try_from(previous).expect("umask : ancien masque dans la plage mode_t")
}

#[cfg(target_arch = "x86_64")]
#[inline]
fn raw_syscall_umask(mask: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_umask (x86_64 = 95) ne touche aucune mémoire utilisateur ;
    // rend l'ancien masque.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 95_i64,
            in("rdi") mask,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
fn raw_syscall_umask(mask: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_umask (aarch64 = 166). Voir la branche x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 166_i64,
            in("x0") mask,
            lateout("x0") ret,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

/// Écrit le **répertoire courant** (chemin absolu) dans `buf` et retourne la
/// tranche d'octets correspondante, **sans** l'octet NUL terminal (`getcwd(2)`).
///
/// Le chemin est traité comme des **octets** (jamais supposé UTF-8 — Principe 3).
/// L'appelant fournit le buffer (zéro allocation, ADR-021 §4).
///
/// # Errors
///
/// - [`Errno::ERANGE`] si `buf` est trop petit pour contenir le chemin + NUL.
/// - Autres `Errno` propagés (p. ex. permissions de lecture d'un composant).
pub fn getcwd(buf: &mut [u8]) -> Result<&[u8], Errno> {
    let size = u64::try_from(buf.len()).expect("getcwd : taille de buffer dans u64");
    let ptr = buf.as_mut_ptr() as usize;
    // SAFETY: `ptr`/`size` décrivent `buf` (emprunt `&mut` valide) ; le kernel y
    // écrit au plus `size` octets.
    let ret = unsafe { raw_syscall_getcwd(ptr, size) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // `getcwd(2)` rend la longueur **NUL compris** (≥ 1) ; on retourne les
    // octets sans le NUL final.
    let total = usize::try_from(ret).expect("getcwd : longueur non négative");
    let path_length = total
        .checked_sub(1)
        .expect("getcwd : longueur ≥ 1 (NUL terminal compris)");
    // TODO(ADR-029/Principe 3) : remplacer l'indexation directe `&buf[..path_length]`
    // par `buf.get(..path_length)` (slicing via `Option`, jamais d'indexation qui
    // panique). Ici `path_length < total ≤ buf.len()` ⇒ borné par construction, donc
    // sûr ; reste à convertir le `Option<&[u8]>` rendu en `Result` (p. ex.
    // `.expect("getcwd : tranche bornée par construction")` ou un bras d'erreur).
    Ok(&buf[..path_length])
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getcwd(buf: usize, size: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getcwd (x86_64 = 79) écrit jusqu'à `size` octets à `buf`.
    // Validité de `buf`/`size` : contrat de l'appelant. Pas de `readonly` (écrit
    // la mémoire pointée).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 79_i64,
            in("rdi") buf,
            in("rsi") size,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getcwd(buf: usize, size: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getcwd (aarch64 = 17). Voir la branche x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 17_i64,
            in("x0") buf,
            in("x1") size,
            lateout("x0") ret,
            options(nostack),
        );
    }
    ret
}

/// Renseigne les **statistiques de ressources** (`getrusage(2)`) pour la cible
/// [`RusageWho`] demandée.
///
/// # Errors
///
/// `getrusage(2)` ne peut échouer que sur `who` invalide (`EINVAL`) ou pointeur
/// invalide (`EFAULT`) — deux cas **rendus impossibles** par l'API typée
/// (`RusageWho` est un enum, le buffer est interne et valide). Le bras `Err` est
/// donc inatteignable via cette fonction (cf. `COVERAGE-EXCEPTIONS.md`,
/// STRUCTURAL/EFAULT-SAFE) ; la signature reste `Result` par honnêteté kernel.
pub fn getrusage(who: RusageWho) -> Result<Rusage, Errno> {
    let who_raw: i64 = match who {
        RusageWho::SelfProcess => 0,
        RusageWho::Children => -1,
        RusageWho::Thread => 1,
    };
    let mut usage = Rusage::default();
    let ptr = core::ptr::from_mut(&mut usage) as usize;
    // SAFETY: `ptr` désigne `usage` (local valide, taille `struct rusage`) ; le
    // kernel y écrit la structure. `who_raw` provient d'un enum ⇒ toujours valide.
    let ret = unsafe { raw_syscall_getrusage(who_raw, ptr) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(usage)
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getrusage(who: i64, usage: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getrusage (x86_64 = 98) écrit une `struct rusage` à `usage`.
    // Validité : contrat de l'appelant. Pas de `readonly` (écrit la mémoire).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 98_i64,
            in("rdi") who,
            in("rsi") usage,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getrusage(who: i64, usage: usize) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getrusage (aarch64 = 165). Voir la branche x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 165_i64,
            in("x0") who,
            in("x1") usage,
            lateout("x0") ret,
            options(nostack),
        );
    }
    ret
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::test_support::{sfd, sraw};

    // ── Affinité CPU (sched_set/getaffinity) ──────────────────────────────
    use core::num::NonZeroI32;

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn cpu_affinity_round_trips_on_calling_task() {
        let mut original = CpuSet::new();
        get_cpu_affinity(None, &mut original).expect("get affinité courante");
        assert!(original.count() >= 1, "au moins un CPU en ligne");
        // Restreint à CPU 0 (toujours en ligne) puis relit.
        let mut only0 = CpuSet::new();
        assert!(only0.set(0));
        set_cpu_affinity(None, &only0).expect("set CPU 0");
        let mut read_back = CpuSet::new();
        get_cpu_affinity(None, &mut read_back).expect("get après set");
        assert!(read_back.contains(0));
        assert_eq!(read_back.count(), 1, "exactement CPU 0");
        // Restaure l'affinité d'origine (ne pas perturber le runner).
        set_cpu_affinity(None, &original).expect("restauration");
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn cpu_affinity_by_explicit_calling_tid() {
        // Branche `Some(tid)` d'`affinity_pid` (tâche appelante explicite).
        let tid = gettid();
        let mut current = CpuSet::new();
        get_cpu_affinity(Some(tid), &mut current).expect("get par tid");
        assert!(current.count() >= 1);
        set_cpu_affinity(Some(tid), &current).expect("set par tid (idempotent)");
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn empty_cpu_set_is_einval() {
        // Aucun CPU autorisé → le kernel refuse (EINVAL).
        let empty = CpuSet::new();
        assert!(matches!(set_cpu_affinity(None, &empty), Err(Errno::EINVAL)));
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn nonexistent_tid_is_esrch() {
        // `Tid` très improbable d'exister → ESRCH (couvre la branche d'erreur).
        let bogus = Tid::from_nonzero(NonZeroI32::new(0x3FFF_FFFF).expect("nz"));
        let mut cpus = CpuSet::new();
        assert!(matches!(
            get_cpu_affinity(Some(bogus), &mut cpus),
            Err(Errno::ESRCH)
        ));
    }

    use crate::fs::dup_fd;
    use std::sync::{Arc, Barrier, Mutex};
    use std::thread;

    /// Écrit le profil de couverture LLVM de l'enfant forké avant `exit_group`
    /// (qui court-circuite l'atexit LLVM). Sans flush, le corps des wrappers
    /// exercés dans l'enfant (clone3/prctl/…) 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();
        exit_group(status)
    }

    /// Sérialise les tests qui **observent la fermeture d'un fd** (drop puis
    /// re-`borrow_raw` du même numéro pour vérifier `EBADF`).
    ///
    /// Défense en deux temps, complémentaire de [`high_unreusable_fd_target`] :
    /// le fd HAUT écarte la réutilisation par le churn de fd des AUTRES tests
    /// (qui allouent toujours des numéros BAS) ; ce verrou empêche les
    /// tests-frères de viser le MÊME numéro haut au même instant — sinon, l'un
    /// libère ce numéro pendant que l'autre le ré-alloue, et la course revient
    /// (déplacée sur le fd haut). Zéro dépendance externe (pas de `serial_test`),
    /// sans `--test-threads=1`. Cf. `docs/CI.md`.
    static FD_OBSERVATION_LOCK: Mutex<()> = Mutex::new(());

    /// Prend [`FD_OBSERVATION_LOCK`] en ignorant l'empoisonnement : si un test
    /// du groupe a paniqué en tenant le verrou, on veut voir CET échec, pas une
    /// cascade d'erreurs « poisoned » sur les tests suivants.
    fn fd_observation_lock() -> std::sync::MutexGuard<'static, ()> {
        FD_OBSERVATION_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
    }

    /// Numéro de fd « haut », **non réutilisable**, pour observer une fermeture
    /// de fd sans flakiness sous instrumentation de couverture.
    ///
    /// Un `open`/`dup` concurrent alloue **toujours** le plus petit fd libre
    /// (numéros bas). Un fd proche de la limite douce `RLIMIT_NOFILE` ne peut
    /// donc jamais être réutilisé tant que le processus n'est pas en épuisement
    /// de fd (jamais en test). On vise `min(soft - 1, 4096)` : assez haut pour
    /// être hors d'atteinte de toute allocation concurrente, assez bas pour
    /// rester légal (< `soft`) et ne pas dimensionner inutilement la table de
    /// fd du kernel. Cf. `docs/CI.md` (course de réutilisation de fd).
    fn high_unreusable_fd_target() -> RawFd {
        const CAP: u64 = 4096;
        let soft = match getrlimit(Resource::NoFile) {
            Ok(Rlimit {
                soft: RlimitValue::Finite(n),
                ..
            }) => n,
            // Limite illimitée ou illisible : le plafond `CAP` reste sûr.
            _ => CAP.saturating_add(1),
        };
        let target = soft.saturating_sub(1).min(CAP);
        RawFd::try_from(target).unwrap_or(RawFd::MAX)
    }

    // ── getpid ────────────────────────────────────────────────────────

    #[test]
    fn getpid_returns_valid_pid() {
        let pid = getpid();
        assert!(pid.as_raw() > 0, "PID doit être strictement positif");
    }

    #[test]
    fn getpid_is_consistent_across_calls() {
        // Invariant : `getpid` lit l'identité du processus appelant ; deux
        // appels consécutifs depuis le même processus doivent renvoyer la
        // même valeur.
        let p1 = getpid();
        let p2 = getpid();
        assert_eq!(p1, p2);
    }

    // ── gettid ────────────────────────────────────────────────────────

    #[test]
    fn gettid_returns_valid_tid() {
        let tid = gettid();
        assert!(tid.as_raw() > 0, "TID doit être strictement positif");
    }

    #[test]
    fn gettid_is_consistent_within_thread() {
        let t1 = gettid();
        let t2 = gettid();
        assert_eq!(t1, t2, "le TID est stable pour un thread donné");
    }

    #[test]
    fn gettid_distinguishes_distinct_threads() {
        // Invariant testé : deux threads vivants simultanément ont des
        // TIDs distincts. La barrière garantit que les deux threads sont
        // encore en vie au moment où chacun lit son TID — donc aucun TID
        // ne peut être recyclé par le kernel.
        let barrier = Arc::new(Barrier::new(2));

        let b1 = Arc::clone(&barrier);
        let h1 = thread::spawn(move || {
            let tid = gettid();
            b1.wait();
            tid
        });

        let b2 = Arc::clone(&barrier);
        let h2 = thread::spawn(move || {
            let tid = gettid();
            b2.wait();
            tid
        });

        let tid1 = h1.join().expect("le thread 1 ne doit pas paniquer");
        let tid2 = h2.join().expect("le thread 2 ne doit pas paniquer");
        // Invariant kernel : deux threads vivants ont des TIDs distincts.
        assert_ne!(tid1, tid2);
    }

    #[test]
    fn worker_thread_tid_differs_from_process_pid() {
        // Corollaire de l'invariant « gettid == getpid pour le thread
        // principal » : pour un thread *non* principal, gettid != getpid.
        // Le thread principal du processus est vérifié séparément par
        // l'intégration `tests/main_thread_invariant.rs` (binaire avec
        // `harness = false`, ce qui place le code sur le thread principal).
        let pid = getpid();
        let handle = thread::spawn(move || (gettid(), getpid()));
        let (worker_tid, worker_pid) = handle.join().expect("le worker ne doit pas paniquer");
        // Le PID est global au processus : tous les threads observent le même.
        assert_eq!(worker_pid, pid);
        // Un thread worker (non-principal) doit avoir un TID distinct du PID.
        assert_ne!(worker_tid.as_raw(), pid.as_raw());
    }

    // ── clone3 / waitid : tests bout-en-bout ─────────────────────────
    //
    // Discipline de sortie de l'enfant (CRITIQUE, cf. exit_group ci-dessus) :
    // - Chaque test enfant termine via `child_exit(N)` (flush du profil de
    //   couverture LLVM puis `exit_group(N)`) — un syscall direct, sans atexit
    //   handler ni flush userspace (jamais `execve` dans cette PR ; le 5e test
    //   de la spec — exec dans l'enfant — est déféré à la PR `execve`).
    // - On **ne** peut **pas** utiliser `std::process::exit` ici : dans
    //   l'enfant d'un `clone3` fork issu du harnais de test multi-thread,
    //   les atexit handlers (flush stdio, capture du harnais) deadlockent
    //   sur des mutex hérités verrouillés par les threads du parent absents
    //   dans l'enfant. Reproduit sur aarch64 (`futex_do_wait`), masqué sur
    //   x86_64.
    // - Conséquence coverage : l'enfant n'écrit plus de `.profraw` (pas
    //   d'atexit LLVM). Les rares lignes exécutées **uniquement** côté enfant
    //   (le bras `CloneResult::Child` et la ligne `ret == 0` de `clone3`)
    //   ne sont donc pas comptées par la couverture. Couverture éventuelle de
    //   ces lignes : harnais dédié hors `cargo test` parallèle, ou exception
    //   documentée (cf. docs/COVERAGE-EXCEPTIONS.md).
    //
    // Tests environnement-dépendants :
    // - Le test namespaces (NEWUSER) est skippé si AppArmor restreint les
    //   user namespaces non privilégiés (cas Ubuntu 24.04 par défaut).
    // - Le test capabilities (NEWPID sans NEWUSER) est skippé si on est
    //   root (auquel cas le syscall réussirait au lieu de retourner EPERM).
    // - Détails : `apparmor_restricts_userns()` et `is_root()` ci-dessous.

    /// Vrai si `kernel.apparmor_restrict_unprivileged_userns` vaut 1.
    /// Sur Ubuntu 24.04+, ce sysctl est positionné par défaut et bloque
    /// `CLONE_NEWUSER` pour les processus non privilégiés (renvoie EPERM
    /// avant même l'exécution du syscall, via une hook AppArmor).
    fn apparmor_restricts_userns() -> bool {
        std::fs::read_to_string("/proc/sys/kernel/apparmor_restrict_unprivileged_userns")
            .map(|s| s.trim() == "1")
            .unwrap_or(false)
    }

    /// Vrai si l'EUID courant est 0 (root). Lecture via `/proc/self/status`
    /// — pas de wrapper `geteuid` côté Air à ce stade. Les `.expect()`
    /// portent sur des invariants Linux solides (procfs présent, format
    /// stable de `/proc/PID/status`) ; leur branche d'échec est
    /// inatteignable en pratique.
    fn is_root() -> bool {
        let status = std::fs::read_to_string("/proc/self/status")
            .expect("/proc/self/status doit être lisible sur Linux");
        let uid_line = status
            .lines()
            .find(|l| l.starts_with("Uid:"))
            .expect("/proc/self/status doit contenir une ligne 'Uid:'");
        // Format : "Uid:\tREAL\tEFFECTIVE\tSAVED\tFS".
        let euid: u32 = uid_line
            .split_whitespace()
            .nth(2)
            .and_then(|s| s.parse().ok())
            .expect("EUID parsable dans /proc/self/status");
        euid == 0
    }

    #[test]
    fn clone3_fork_exit_observed_by_waitid_exited() {
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique (pas de CLONE_VM, pas de namespaces).
        // Aucune mémoire partagée, aucune capability requise.
        let result = unsafe { clone3(&args) }.expect("clone3 doit réussir");
        match result {
            CloneResult::Child => {
                // L'enfant écrit son profil LLVM (atexit) puis termine.
                child_exit(42);
            }
            CloneResult::Parent {
                child_pid,
                child_pidfd,
            } => {
                assert!(child_pidfd.is_none());
                let status = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid doit réussir");
                let s = status.expect("événement EXITED disponible");
                assert_eq!(s.pid, child_pid);
                assert!(matches!(s.event, WaitEvent::Exited { code: 42 }));
            }
        }
    }

    #[test]
    fn build_kernel_clone_args_maps_exit_signal_some_and_none() {
        // Branche `Some(sig)` : le signal est encodé sur les 8 bits de
        // poids faible de `clone_args.exit_signal`.
        let args_some = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        let k = build_kernel_clone_args(&args_some, 0);
        assert_eq!(
            k.exit_signal,
            u64::from(Signal::SIGCHLD.as_raw().unsigned_abs())
        );

        // Branche `None` : 0 transmis au kernel — Air ne reproduit pas le
        // comportement de fork() qui force SIGCHLD ; l'appelant choisit.
        // Cette branche n'est pas testable bout-en-bout via clone3+waitid
        // sur Linux : avec `exit_signal=0`, le kernel détache l'enfant et
        // `waitid` retourne `ECHILD`. Cf. JOURNAL.md session
        // 2026-05-22 (suite clone3+waitid).
        let args_none = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: None,
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        let k = build_kernel_clone_args(&args_none, 0);
        assert_eq!(k.exit_signal, 0);
    }

    #[test]
    fn build_kernel_clone_args_propagates_flags_and_pidfd_addr() {
        let args = CloneArgs {
            flags: CloneFlags::PIDFD | CloneFlags::NEWUSER,
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        let k = build_kernel_clone_args(&args, 0xdead_beef_u64);
        assert_eq!(k.flags, (CloneFlags::PIDFD | CloneFlags::NEWUSER).bits());
        assert_eq!(k.pidfd, 0xdead_beef_u64);
        // Champs non utilisés par cette PR : tous à zéro.
        assert_eq!(k.child_tid, 0);
        assert_eq!(k.parent_tid, 0);
        assert_eq!(k.stack, 0);
        assert_eq!(k.stack_size, 0);
        assert_eq!(k.tls, 0);
        assert_eq!(k.set_tid, 0);
        assert_eq!(k.set_tid_size, 0);
        assert_eq!(k.cgroup, 0);
    }

    #[test]
    fn clone3_with_pidfd_yields_owned_pidfd_usable_for_waitid() {
        let args = CloneArgs {
            flags: CloneFlags::PIDFD,
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique + CLONE_PIDFD ; pas de mémoire partagée.
        let result = unsafe { clone3(&args) }.expect("clone3 doit réussir");
        match result {
            CloneResult::Child => {
                child_exit(7);
            }
            CloneResult::Parent {
                child_pid,
                child_pidfd,
            } => {
                let pidfd = child_pidfd.expect("CLONE_PIDFD était demandé");
                let status = waitid(WaitTarget::PidFd(pidfd.as_fd()), WaitOptions::EXITED)
                    .expect("waitid via pidfd doit réussir");
                let s = status.expect("événement EXITED disponible");
                assert_eq!(s.pid, child_pid);
                assert!(matches!(s.event, WaitEvent::Exited { code: 7 }));
            }
        }
    }

    /// `pidfd_send_signal` avec un **`siginfo` explicite** (`Some(&info)`) : couvre
    /// le bras `Some(_)` du wrapper (jadis value-unreachable faute de constructeur
    /// `SignalInfo` public — désormais disponible via `SignalInfo::new_queue`,
    /// **sans aucun ajout de surface**).
    ///
    /// Le bras `Some(i) => …` est **exercé** dès qu'on passe `Some(&info)` (il
    /// marshale `info_ptr` **avant** le syscall). On envoie vers un pidfd **de
    /// soi-même** : `pidfd_send_signal` exige `si_signo == sig`, or `new_queue`
    /// (destiné à `rt_sigqueueinfo`, où le kernel **écrase** `si_signo`) le laisse
    /// à 0 ⇒ le kernel **rejette par `EINVAL` AVANT toute délivrance** — l'appel est
    /// donc **sûr même vers soi-même** (aucun signal n'est envoyé). Vérifié
    /// empiriquement (un envoi `SIGKILL`+`new_queue` ne tue pas la cible).
    #[test]
    #[cfg_attr(miri, ignore = "pidfd/signaux non supportés par Miri")]
    fn pidfd_send_signal_with_explicit_siginfo_exercises_some_arm() {
        use air_sys_types::{SignalInfo, SignalValue};

        let self_pidfd = pidfd_open(getpid(), PidFdOpenFlags::empty()).expect("pidfd_open self");
        let info = SignalInfo::new_queue(SignalValue::Integer(0x5A5A));
        // ── CIBLE : bras `Some(&info)` (info_ptr non nul) marshalé. ──
        let result = pidfd_send_signal(self_pidfd.as_fd(), Signal::SIGUSR1, Some(&info));
        assert_eq!(
            result,
            Err(Errno::EINVAL),
            "siginfo explicite : bras Some exercé ; rejet EINVAL (si_signo=0 ≠ sig), \
             aucun signal délivré"
        );
    }

    #[test]
    fn waitid_decodes_child_killed_by_signal() {
        // **Ce que ce test prouve.** `waitid` décode correctement un
        // événement enfant terminé par signal en `WaitEvent::Killed`
        // (branche `CLD_KILLED` ou `CLD_DUMPED` du dispatch
        // `siginfo_to_wait_event`). L'enfant produit l'événement en
        // s'auto-`abort()` — pour le kernel et pour `waitid`, le siginfo
        // résultant est strictement équivalent à « le parent a envoyé
        // SIGABRT » : `si_code = CLD_KILLED`/`CLD_DUMPED`,
        // `si_status = SIGABRT`. La branche du dispatch exercée est la
        // même que pour le scénario canonique.
        //
        // **Scénario canonique disponible depuis la PR pidfd_*.** Pour
        // une orchestration parent → enfant réelle (parent envoie un
        // signal qui tue l'enfant), voir le test
        // `pidfd_send_signal_canonical_parent_kills_child_with_sigkill`
        // ci-dessous. Ce test-ci reste utile : il exerce le décodage
        // `CLD_DUMPED` (SIGABRT dump-friendly) alors que le canonique
        // exerce `CLD_KILLED` (SIGKILL pur).
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique, pas de mémoire partagée.
        let result = unsafe { clone3(&args) }.expect("clone3 doit réussir");
        match result {
            CloneResult::Child => {
                // SIGABRT raised; child dies. `abort()` bypasses atexit,
                // donc cette ligne n'incrémente PAS le compteur LLVM côté
                // child (trou de couverture acté dans JOURNAL).
                std::process::abort();
            }
            CloneResult::Parent { child_pid, .. } => {
                let status = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid doit réussir");
                let s = status.expect("événement EXITED disponible");
                assert!(matches!(
                    s.event,
                    WaitEvent::Killed { signal, .. } if signal.as_raw() == Signal::SIGABRT.as_raw()
                ));
            }
        }
    }

    #[test]
    fn waitid_dispatches_processgroup_and_anyprocessgroup() {
        // Exerce les bras `WaitTarget::ProcessGroup(_)` et
        // `WaitTarget::AnyProcessGroup` du dispatch interne de `waitid`.
        // NOHANG garantit un retour immédiat. **NOWAIT** (peek) est
        // crucial : sans lui, cet appel concurrent à d'autres tests qui
        // forkent et reapent leurs enfants risquerait de **consommer**
        // un événement appartenant à un autre test, lui faisant voir
        // `ECHILD`. NOWAIT garde l'événement waitable pour son
        // propriétaire légitime.
        let pid = getpid();
        let opts = WaitOptions::EXITED | WaitOptions::NOHANG | WaitOptions::NOWAIT;
        let _ = waitid(WaitTarget::ProcessGroup(pid), opts);
        let _ = waitid(WaitTarget::AnyProcessGroup, opts);
    }

    #[test]
    fn waitid_nohang_returns_none_when_no_event_yet() {
        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 doit réussir");
        match result {
            CloneResult::Child => {
                // Sleep long pour laisser au parent le temps de la fenêtre
                // NOHANG. 200 ms est largement suffisant sur n'importe
                // quelle CI réaliste.
                std::thread::sleep(std::time::Duration::from_millis(200));
                child_exit(0);
            }
            CloneResult::Parent { child_pid, .. } => {
                let status = waitid(
                    WaitTarget::Pid(child_pid),
                    WaitOptions::EXITED | WaitOptions::NOHANG,
                )
                .expect("waitid avec NOHANG doit réussir");
                assert!(status.is_none());
                // Cleanup : on attend l'enfant bloquant pour ne pas laisser
                // de zombie aux tests suivants.
                let _ = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid bloquant final doit réussir");
            }
        }
    }

    #[test]
    fn clone3_rejects_stack_argument() {
        // `clone3` est dédié au fork : une pile dédiée (création de thread) doit
        // être refusée en amont, sans toucher au kernel (Principe 4 : validation
        // amont). La création de thread avec pile passe par `clone_thread`.
        let dummy_buf: [u8; 16] = [0; 16];
        let mut buffer = dummy_buf;
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: Some(air_sys_types::StackSpecification {
                addr: buffer.as_mut_ptr(),
                size: buffer.len(),
            }),
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: le wrapper rejette `stack` avant tout syscall.
        let result = unsafe { clone3(&args) };
        assert_eq!(result.err(), Some(Errno::EINVAL));
    }

    #[test]
    fn clone3_rejects_thread_creation_flags() {
        // CLONE_VM / CLONE_THREAD / CLONE_SIGHAND ne sont pas supportés
        // dans cette PR ; le wrapper doit les refuser en amont.
        let args = CloneArgs {
            flags: CloneFlags::VM,
            exit_signal: None,
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: refus en amont, sans syscall.
        let result = unsafe { clone3(&args) };
        assert_eq!(result.err(), Some(Errno::EINVAL));
    }

    // ── clone_thread : création de thread (CLONE_VM) + join par CHILD_CLEARTID ─
    //
    // Marqueur écrit par l'enfant dans la VM partagée ; valeur arbitraire non
    // nulle, distincte de l'état initial (0) et d'un TID plausible.
    const THREAD_MARKER: u32 = 0xABCD_1234;

    /// Point d'entrée du thread de test : écrit `THREAD_MARKER` dans le mot
    /// atomique pointé par `arg` (mémoire partagée via `CLONE_VM`).
    ///
    /// **Discipline côté enfant** : opération **brute**, async-signal-safe — une
    /// seule écriture atomique, **aucun** accès TLS ni allocation. Côté kernel,
    /// le trampoline `clone_thread` termine le thread via `SYS_exit` au retour.
    ///
    /// Cette fonction est **aussi** appelée directement côté parent par
    /// `thread_marker_entry_writes_marker_directly` (couverture de son corps :
    /// l'invocation enfant ne flushe pas le profil LLVM).
    extern "C" fn thread_marker_entry(arg: usize) {
        // SAFETY (test) : `arg` est l'adresse d'un `AtomicU32` vivant fourni par
        // l'appelant (parent), partagé via la VM commune. Alignement et validité
        // garantis par le site d'appel.
        let marker = unsafe { &*(arg as *const core::sync::atomic::AtomicU32) };
        marker.store(THREAD_MARKER, core::sync::atomic::Ordering::Release);
    }

    #[test]
    fn thread_marker_entry_writes_marker_directly() {
        // Couvre le corps de `thread_marker_entry` côté parent (le profil LLVM
        // de son exécution enfant n'est pas flushable : SYS_exit direct).
        use core::sync::atomic::{AtomicU32, Ordering};
        let word = AtomicU32::new(0);
        let ptr = core::ptr::addr_of!(word) as usize;
        thread_marker_entry(ptr);
        assert_eq!(word.load(Ordering::Acquire), THREAD_MARKER);
    }

    #[test]
    #[cfg_attr(miri, ignore = "clone3/futex non supportés par Miri")]
    fn clone_thread_spawns_runs_and_joins_via_child_cleartid() {
        use crate::futex::futex_wait;
        use crate::mem::{mmap_anonymous, munmap};
        use air_sys_types::mem::{MapFlags, ProtectionFlags};
        use air_sys_types::{FutexScope, TidReceiver};
        use core::sync::atomic::{AtomicU32, Ordering};

        // Pile dédiée du thread : 64 KiB, page-alignée (mmap) ⇒ sommet aligné 16.
        const STACK_SIZE: usize = 64 * 1024;
        let mut stack = mmap_anonymous(
            STACK_SIZE,
            ProtectionFlags::READ | ProtectionFlags::WRITE,
            MapFlags::PRIVATE | MapFlags::STACK,
        )
        .expect("mmap pile thread");

        // Marqueur partagé (VM commune) écrit par l'enfant, lu par le parent.
        let marker = AtomicU32::new(0);
        // Mot du join : `PARENT_SETTID` y écrit le TID (sans course, côté parent
        // avant retour) ; `CHILD_CLEARTID` le remet à 0 + `FUTEX_WAKE` à la mort
        // du thread.
        let tid_word = AtomicU32::new(0);

        let flags = CloneFlags::VM
            | CloneFlags::FS
            | CloneFlags::FILES
            | CloneFlags::SIGHAND
            | CloneFlags::THREAD
            | CloneFlags::SYSVSEM
            | CloneFlags::PARENT_SETTID
            | CloneFlags::CHILD_CLEARTID;

        let args = CloneArgs {
            flags,
            // CLONE_THREAD interdit tout signal de sortie.
            exit_signal: None,
            stack: Some(StackSpecification {
                addr: stack.as_mut_ptr(),
                size: STACK_SIZE,
            }),
            child_tid: Some(TidReceiver::new(&tid_word)),
            parent_tid: Some(TidReceiver::new(&tid_word)),
            tls: None,
        };

        let marker_ptr = core::ptr::addr_of!(marker) as usize;
        // SAFETY: pile dédiée valide, non libérée avant le join ; `thread_marker_entry`
        // n'utilise ni TLS ni alloc et n'écrit qu'un mot atomique partagé vivant ;
        // `tid_word` reste vivant jusqu'à la fin du join.
        let tid = unsafe { clone_thread(&args, thread_marker_entry, marker_ptr) }
            .expect("clone_thread doit réussir");
        assert!(tid.as_raw() > 0, "TID enfant strictement positif");

        // Join : le kernel a écrit le TID dans `tid_word` (PARENT_SETTID) ; il le
        // remet à 0 + `FUTEX_WAKE` (portée **partagée**) à la mort du thread.
        // Robustesse : `futex_wait` borné par un court timeout, puis relecture du
        // mot — le kernel écrit toujours 0, indépendamment du réveil ; la boucle
        // converge même si la portée du futex différait.
        loop {
            let v = tid_word.load(Ordering::Acquire);
            if v == 0 {
                break;
            }
            let _ = futex_wait(
                &tid_word,
                v,
                Some(core::time::Duration::from_millis(100)),
                FutexScope::Shared,
            );
        }

        assert_eq!(
            marker.load(Ordering::Acquire),
            THREAD_MARKER,
            "l'enfant doit avoir écrit le marqueur dans la VM partagée"
        );

        // La pile n'est libérée qu'après le join (thread mort) : pas d'UAF.
        munmap(stack).expect("munmap pile thread");
    }

    #[test]
    #[cfg_attr(miri, ignore = "clone3 non supporté par Miri")]
    fn clone_thread_kernel_rejection_surfaces_errno() {
        // Couvre le bras d'erreur de `clone_thread` (échec AU SYSCALL, après la
        // validation amont). `CLONE_THREAD` sans `CLONE_SIGHAND` viole un
        // invariant *inconditionnel* de `copy_process`
        // (`THREAD ⟹ SIGHAND ⟹ VM`) : le kernel rend `EINVAL` **avant** de créer
        // quoi que ce soit — aucun thread n'est lancé, `entry` n'est jamais
        // exécuté. Déterministe sur tout Linux.
        use crate::mem::{mmap_anonymous, munmap};
        use air_sys_types::mem::{MapFlags, ProtectionFlags};

        const STACK_SIZE: usize = 64 * 1024;
        let mut stack = mmap_anonymous(
            STACK_SIZE,
            ProtectionFlags::READ | ProtectionFlags::WRITE,
            MapFlags::PRIVATE | MapFlags::STACK,
        )
        .expect("mmap pile thread");

        let args = CloneArgs {
            // VM présent (passe la validation amont) mais THREAD sans SIGHAND.
            flags: CloneFlags::VM | CloneFlags::THREAD,
            exit_signal: None,
            stack: Some(StackSpecification {
                addr: stack.as_mut_ptr(),
                size: STACK_SIZE,
            }),
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: le kernel rejette la combinaison de drapeaux (EINVAL) avant
        // toute création de thread ; `entry` n'est jamais appelé. La pile reste
        // intacte et est libérée ensuite.
        let r = unsafe { clone_thread(&args, thread_marker_entry, 0) };
        assert_eq!(r.err(), Some(Errno::EINVAL));

        munmap(stack).expect("munmap pile thread");
    }

    /// Construit une `StackSpecification` à adresse/taille **contrôlées** pour
    /// les tests de validation (jamais déréférencée : rejet en amont).
    fn fake_stack(addr: usize, size: usize) -> StackSpecification {
        StackSpecification {
            addr: core::ptr::without_provenance_mut::<u8>(addr),
            size,
        }
    }

    #[test]
    fn clone_thread_validation_rejects_bad_inputs() {
        let entry = thread_marker_entry;
        // (a) pile absente (avec CLONE_VM) → EINVAL.
        let a = CloneArgs {
            flags: CloneFlags::VM,
            exit_signal: None,
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        assert_eq!(
            unsafe { clone_thread(&a, entry, 0) }.err(),
            Some(Errno::EINVAL),
            "pile absente"
        );

        // (b) pile présente mais CLONE_VM absent → EINVAL.
        let b = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: None,
            stack: Some(fake_stack(0x10000, 8192)),
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        assert_eq!(
            unsafe { clone_thread(&b, entry, 0) }.err(),
            Some(Errno::EINVAL),
            "CLONE_VM absent"
        );

        // Base commune pour les cas (c)..(g) : CLONE_VM présent.
        let with_stack = |s: StackSpecification| CloneArgs {
            flags: CloneFlags::VM,
            exit_signal: None,
            stack: Some(s),
            child_tid: None,
            parent_tid: None,
            tls: None,
        };

        // (c) adresse de pile nulle → EINVAL.
        let c = with_stack(fake_stack(0, 8192));
        assert_eq!(
            unsafe { clone_thread(&c, entry, 0) }.err(),
            Some(Errno::EINVAL),
            "addr nulle"
        );

        // (d) taille < MIN_THREAD_STACK_SIZE → EINVAL.
        let d = with_stack(fake_stack(0x10000, 16));
        assert_eq!(
            unsafe { clone_thread(&d, entry, 0) }.err(),
            Some(Errno::EINVAL),
            "taille trop petite"
        );

        // (e) `addr` non alignée sur 16 → EINVAL (1er opérande du `||`).
        let e = with_stack(fake_stack(0x10001, 8192));
        assert_eq!(
            unsafe { clone_thread(&e, entry, 0) }.err(),
            Some(Errno::EINVAL),
            "addr non alignée 16"
        );

        // (f) `size` non alignée sur 16 (addr alignée) → EINVAL (2e opérande).
        let f = with_stack(fake_stack(0x10000, 8192 + 1));
        assert_eq!(
            unsafe { clone_thread(&f, entry, 0) }.err(),
            Some(Errno::EINVAL),
            "size non alignée 16"
        );

        // (g) sommet `addr + size` en débordement d'adresse → EINVAL.
        let g = with_stack(fake_stack(0xFFFF_FFFF_FFFF_F000, 0x2000));
        assert_eq!(
            unsafe { clone_thread(&g, entry, 0) }.err(),
            Some(Errno::EINVAL),
            "débordement du sommet de pile"
        );
    }

    #[test]
    fn build_kernel_clone_args_maps_thread_fields() {
        // Mapping des champs de thread : stack/stack_size, tls, child_tid, parent_tid.
        use air_sys_types::TidReceiver;
        use core::sync::atomic::AtomicU32;
        let word = AtomicU32::new(0);
        let recv = TidReceiver::new(&word);
        let args = CloneArgs {
            flags: CloneFlags::VM | CloneFlags::THREAD,
            exit_signal: None,
            stack: Some(fake_stack(0x4000, 0x8000)),
            child_tid: Some(recv),
            parent_tid: Some(recv),
            tls: Some(0xDEAD_0000),
        };
        let k = build_kernel_clone_args(&args, 0);
        assert_eq!(k.flags, (CloneFlags::VM | CloneFlags::THREAD).bits());
        assert_eq!(k.stack, 0x4000);
        assert_eq!(k.stack_size, 0x8000);
        assert_eq!(k.tls, 0xDEAD_0000);
        assert_eq!(k.child_tid, recv.as_ptr() as u64);
        assert_eq!(k.parent_tid, recv.as_ptr() as u64);
        // Champs hors périmètre : toujours nuls.
        assert_eq!(k.pidfd, 0);
        assert_eq!(k.set_tid, 0);
        assert_eq!(k.set_tid_size, 0);
        assert_eq!(k.cgroup, 0);
    }

    #[test]
    fn clone3_with_new_user_namespace_runs_or_skips() {
        if apparmor_restricts_userns() {
            eprintln!(
                "SKIP clone3_with_new_user_namespace_runs_or_skips : \
                 kernel.apparmor_restrict_unprivileged_userns=1 sur cet \
                 environnement (Ubuntu 24.04+ par défaut)."
            );
            return;
        }
        let args = CloneArgs {
            flags: CloneFlags::NEWUSER,
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: création de processus dans un user namespace ;
        // l'appelant n'a pas besoin de capability sur un système qui
        // autorise les userns non privilégiés.
        let result = unsafe { clone3(&args) }
            .expect("clone3 NEWUSER doit réussir sans restriction AppArmor");
        match result {
            CloneResult::Child => {
                child_exit(0);
            }
            CloneResult::Parent { child_pid, .. } => {
                let status = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid doit réussir");
                let s = status.expect("événement disponible");
                assert!(matches!(s.event, WaitEvent::Exited { code: 0 }));
            }
        }
    }

    #[test]
    fn clone3_newpid_without_caps_returns_eperm() {
        if is_root() {
            eprintln!(
                "SKIP clone3_newpid_without_caps_returns_eperm : \
                 le test runner s'exécute en root, le scénario \
                 « capabilities insuffisantes » est inapplicable."
            );
            return;
        }
        let args = CloneArgs {
            // NEWPID seul (sans NEWUSER) exige CAP_SYS_ADMIN dans le
            // namespace utilisateur courant ; un non-root est refusé.
            flags: CloneFlags::NEWPID,
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: si EPERM est retourné, aucun fork n'a eu lieu. Le test
        // a été skippé en amont si on est root, donc la branche `Ok(_)`
        // est inatteignable sur un environnement conforme.
        let result = unsafe { clone3(&args) };
        assert_eq!(result.err(), Some(Errno::EPERM));
    }

    #[test]
    fn waitid_invalid_options_returns_einval() {
        // Le kernel exige au moins un parmi EXITED/STOPPED/CONTINUED.
        let result = waitid(WaitTarget::AnyChild, WaitOptions::empty());
        assert_eq!(result.err(), Some(Errno::EINVAL));
    }

    // ── siginfo_to_wait_event : dispatch testé sur KernelSiginfo synthétiques ─
    //
    // Voir docs/JOURNAL.md (session 2026-05-22, suite clone3+waitid) :
    // ces tests couvrent la **logique de dispatch** des 5 variantes de
    // WaitEvent. Le remplissage réel de `siginfo_t` par le kernel n'est
    // testé bout-en-bout que pour Exited et Killed (les deux tests
    // ci-dessus). Stopped/Continued/Trapped restent un trou de couverture
    // assumé pour ce périmètre.

    fn make_siginfo(si_code: i32, si_status: i32) -> KernelSiginfo {
        let mut info = KernelSiginfo::zeroed();
        info.si_signo = Signal::SIGCHLD.as_raw();
        info.si_code = si_code;
        info.si_pid = 1234;
        info.si_uid = 1000;
        info.si_status = si_status;
        info
    }

    #[test]
    fn dispatch_cld_exited() {
        let info = make_siginfo(CLD_EXITED, 42);
        assert_eq!(siginfo_to_wait_event(&info), WaitEvent::Exited { code: 42 });
    }

    #[test]
    fn dispatch_cld_killed_no_dump() {
        let info = make_siginfo(CLD_KILLED, Signal::SIGKILL.as_raw());
        assert_eq!(
            siginfo_to_wait_event(&info),
            WaitEvent::Killed {
                signal: Signal::SIGKILL,
                core_dumped: false,
            }
        );
    }

    #[test]
    fn dispatch_cld_dumped_sets_core_dumped_true() {
        let info = make_siginfo(CLD_DUMPED, Signal::SIGSEGV.as_raw());
        assert_eq!(
            siginfo_to_wait_event(&info),
            WaitEvent::Killed {
                signal: Signal::SIGSEGV,
                core_dumped: true,
            }
        );
    }

    #[test]
    fn dispatch_cld_stopped() {
        let info = make_siginfo(CLD_STOPPED, Signal::SIGSTOP.as_raw());
        assert_eq!(
            siginfo_to_wait_event(&info),
            WaitEvent::Stopped {
                signal: Signal::SIGSTOP,
            }
        );
    }

    #[test]
    fn dispatch_cld_trapped() {
        let info = make_siginfo(CLD_TRAPPED, Signal::SIGTRAP.as_raw());
        assert_eq!(
            siginfo_to_wait_event(&info),
            WaitEvent::Trapped {
                signal: Signal::SIGTRAP,
            }
        );
    }

    #[test]
    fn dispatch_cld_continued() {
        // si_status est ignoré pour CLD_CONTINUED ; on passe 0.
        let info = make_siginfo(CLD_CONTINUED, 0);
        assert_eq!(siginfo_to_wait_event(&info), WaitEvent::Continued);
    }

    #[test]
    #[should_panic(expected = "si_code inconnu")]
    fn dispatch_unknown_cld_code_panics() {
        // Couvre la branche `unreachable!` de siginfo_to_wait_event.
        // Cette branche ne peut être atteinte que si le kernel renseigne
        // un si_code hors {1..=6} — situation impossible en pratique mais
        // testée pour fermer la couverture du match.
        let info = make_siginfo(99, 0);
        let _ = siginfo_to_wait_event(&info);
    }

    // ── errno_from_negative_syscall_ret : conversion brute → typée ─

    #[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(-9), Errno::EBADF);
        assert_eq!(errno_from_negative_syscall_ret(-10), Errno::ECHILD);
        assert_eq!(errno_from_negative_syscall_ret(-22), Errno::EINVAL);
    }

    // Couvrent les deux opérandes du `debug_assert!(ret < 0 && ret > -4096)` :
    // `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);
    }

    // ── pidfd_open / pidfd_send_signal / pidfd_getfd ─────────────────
    //
    // Stratégie de coverage post-fork (identique aux PRs précédentes) :
    // les enfants terminent par `exit_group(N)` quand c'est
    // possible (flush LLVM via atexit). Pour le test canonique SIGKILL,
    // la ligne `loop { sleep }` côté enfant reste non-couverte (SIGKILL
    // bypasse atexit), trou acté dans JOURNAL session clone3+waitid.

    /// Vrai si Yama interdit le ptrace même sur un enfant direct (scope ≥ 2).
    /// Sur Ubuntu, ptrace_scope vaut 1 par défaut (parent → enfant
    /// autorisé), donc `pidfd_getfd` sur notre propre enfant passe.
    fn yama_blocks_ptrace_on_own_child() -> bool {
        let Ok(s) = std::fs::read_to_string("/proc/sys/kernel/yama/ptrace_scope") else {
            return false;
        };
        let scope: u32 = s.trim().parse().unwrap_or(0);
        scope >= 2
    }

    #[test]
    fn pidfd_open_returns_pidfd_usable_for_waitid_over_child_lifetime() {
        // Couvre : (a) `pidfd_open` happy path ; (b) le pidfd reste valide
        // pendant *et après* la mort du processus cible (jusqu'au reap).
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique, pas de mémoire partagée.
        let result = unsafe { clone3(&args) }.expect("clone3 doit réussir");
        match result {
            CloneResult::Child => {
                // Petit délai : laisse au parent le temps d'ouvrir le
                // pidfd avant qu'on exit (pas strictement nécessaire — le
                // kernel garde l'entrée en process table jusqu'au reap —
                // mais rend la nature « post-mortem » du pidfd observable).
                std::thread::sleep(std::time::Duration::from_millis(20));
                child_exit(11);
            }
            CloneResult::Parent { child_pid, .. } => {
                let pidfd = pidfd_open(child_pid, PidFdOpenFlags::empty())
                    .expect("pidfd_open sur enfant vivant doit réussir");
                let status = waitid(WaitTarget::PidFd(pidfd.as_fd()), WaitOptions::EXITED)
                    .expect("waitid via pidfd post-mortem doit réussir");
                let s = status.expect("événement EXITED disponible");
                assert_eq!(s.pid, child_pid);
                assert!(matches!(s.event, WaitEvent::Exited { code: 11 }));
            }
        }
    }

    #[test]
    fn pidfd_open_returns_esrch_for_nonexistent_pid() {
        // PID_MAX_LIMIT sur Linux 64-bit est typiquement 2^22 = 4 194 304.
        // 0x7FFF_FFFE (~2.1 G) est très au-delà : aucun processus ne peut
        // jamais avoir ce PID. Le kernel retourne ESRCH.
        let nonexistent = Pid::try_from_raw(0x7FFF_FFFE).expect("PID littéral valide");
        let result = pidfd_open(nonexistent, PidFdOpenFlags::empty());
        assert_eq!(result.err(), Some(Errno::ESRCH));
    }

    #[test]
    fn pidfd_drop_closes_underlying_fd() {
        // **Ce que ce test prouve.** Le `Drop` du wrapper RAII — `PidFd` est un
        // `PidFd(OwnedFd)` sans `Drop` propre, son `Drop` EST donc celui
        // d'`OwnedFd` qui appelle `close(fd)` — ferme bien le descripteur
        // sous-jacent. Vérifié en post-drop : on tente `waitid` sur le numéro
        // fermé via `BorrowedFd::borrow_raw` ; le kernel doit retourner `EBADF`.
        //
        // **Immunité à la course de réutilisation de fd (sinon flaky sous
        // couverture).** Cargo teste en parallèle ; un autre thread peut
        // allouer un fd qui RÉUTILISE le numéro qu'on vient de fermer, dans la
        // fenêtre entre `drop` et l'observation — `waitid` ne verrait alors pas
        // `EBADF` mais le nouveau fd valide (faux négatif). L'instrumentation
        // de couverture élargit cette fenêtre et rendait le test flaky
        // (cf. `docs/CI.md`). Parade *par construction* : on duplique le pidfd
        // vers un numéro de fd HAUT (`high_unreusable_fd_target`), puis on
        // observe la fermeture de CE numéro. Une allocation concurrente prend
        // toujours le plus PETIT fd libre, jamais ce numéro haut → réutilisation
        // impossible — et `FD_OBSERVATION_LOCK` empêche les tests-frères de
        // viser ce même numéro haut au même instant. Pas de `--test-threads=1`.
        let _obs = fd_observation_lock();
        let pidfd = pidfd_open(getpid(), PidFdOpenFlags::empty())
            .expect("pidfd_open sur self doit réussir");
        let high = dup_fd(pidfd.as_fd(), high_unreusable_fd_target())
            .expect("dup_fd vers un fd haut doit réussir");
        // Le fd bas du pidfd peut être réutilisé après ce drop : sans effet, on
        // n'observe que le fd HAUT ci-dessous.
        drop(pidfd);
        let raw_fd: RawFd = high.as_raw_fd();
        // Ferme le fd HAUT : c'est le sujet de l'observation, et il est hors
        // d'atteinte de toute réutilisation concurrente.
        drop(high);
        // SAFETY: on re-borrow un fd qu'on sait fermé ET non réutilisable
        // (numéro haut). Usage strictement limité à la transmission au kernel
        // pour vérifier `EBADF` ; on ne lit ni n'écrit aucune ressource.
        let dangling = unsafe { BorrowedFd::borrow_raw(raw_fd) };
        let err = waitid(WaitTarget::PidFd(dangling), WaitOptions::EXITED)
            .expect_err("waitid sur fd fermé doit échouer");
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn pidfd_send_signal_on_closed_pidfd_returns_ebadf() {
        // Couvre le chemin d'erreur de `pidfd_send_signal` (le scénario
        // canonique SIGKILL ci-dessous exerce seulement le chemin happy).
        // Immunité réutilisation de fd : même technique de fd HAUT que
        // `pidfd_drop_closes_underlying_fd` (cf. son commentaire).
        let _obs = fd_observation_lock();
        let pidfd = pidfd_open(getpid(), PidFdOpenFlags::empty())
            .expect("pidfd_open sur self doit réussir");
        let high = dup_fd(pidfd.as_fd(), high_unreusable_fd_target())
            .expect("dup_fd vers un fd haut doit réussir");
        drop(pidfd);
        let raw_fd: RawFd = high.as_raw_fd();
        drop(high);
        // SAFETY: re-borrow d'un fd fermé ET non réutilisable (numéro haut),
        // utilisé strictement pour vérifier le retour kernel `EBADF`.
        let dangling = unsafe { BorrowedFd::borrow_raw(raw_fd) };
        let err = pidfd_send_signal(dangling, Signal::SIGKILL, None)
            .expect_err("pidfd_send_signal sur fd fermé doit échouer");
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn pidfd_getfd_on_closed_pidfd_returns_ebadf() {
        // Couvre le chemin d'erreur de `pidfd_getfd`. Même technique de fd HAUT
        // immunisée contre la réutilisation que les tests `EBADF` ci-dessus.
        let _obs = fd_observation_lock();
        let pidfd = pidfd_open(getpid(), PidFdOpenFlags::empty())
            .expect("pidfd_open sur self doit réussir");
        let high = dup_fd(pidfd.as_fd(), high_unreusable_fd_target())
            .expect("dup_fd vers un fd haut doit réussir");
        drop(pidfd);
        let raw_fd: RawFd = high.as_raw_fd();
        drop(high);
        // SAFETY: re-borrow d'un fd fermé ET non réutilisable (numéro haut).
        let dangling = unsafe { BorrowedFd::borrow_raw(raw_fd) };
        // `0` est un fd potentiellement ouvert côté cible (stdin) — peu importe
        // ici, le kernel rejette d'abord sur le pidfd fermé avec EBADF.
        let err = pidfd_getfd(dangling, 0, 0).expect_err("pidfd_getfd sur fd fermé doit échouer");
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn pidfd_send_signal_canonical_parent_kills_child_with_sigkill() {
        // **Scénario canonique.** Le parent fork un enfant qui dort, lui
        // envoie SIGKILL via `pidfd_send_signal`, puis `waitid` observe
        // `WaitEvent::Killed { signal: SIGKILL, .. }`. C'est ce qui se
        // passe en production réelle (orchestration parent → enfant),
        // contrairement au scénario d'équivalence-kernel de
        // `waitid_decodes_child_killed_by_signal` (auto-abort).
        let args = CloneArgs {
            flags: CloneFlags::PIDFD,
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique avec pidfd, pas de mémoire partagée.
        let result = unsafe { clone3(&args) }.expect("clone3 doit réussir");
        match result {
            CloneResult::Child => {
                // Le parent va nous tuer via SIGKILL. SIGKILL est
                // uncaught, donc on ne reprendra jamais d'ici. La ligne
                // n'est PAS couverte par LLVM (le profile n'est pas
                // flushé avant SIGKILL), trou acté.
                loop {
                    std::thread::sleep(std::time::Duration::from_secs(60));
                }
            }
            CloneResult::Parent {
                child_pid,
                child_pidfd,
            } => {
                let pidfd = child_pidfd.expect("CLONE_PIDFD demandé");
                // Brève attente pour que l'enfant atteigne sa boucle
                // (réduit la probabilité d'envoyer SIGKILL avant que
                // l'enfant ait commencé son sleep — sans incidence sur
                // l'observation `waitid`).
                std::thread::sleep(std::time::Duration::from_millis(20));
                pidfd_send_signal(pidfd.as_fd(), Signal::SIGKILL, None)
                    .expect("pidfd_send_signal SIGKILL doit réussir");
                let status = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid doit réussir");
                let s = status.expect("événement disponible");
                assert!(matches!(
                    s.event,
                    WaitEvent::Killed { signal, .. } if signal.as_raw() == Signal::SIGKILL.as_raw()
                ));
            }
        }
    }

    #[test]
    fn pidfd_getfd_duplicates_fd_from_child() {
        if yama_blocks_ptrace_on_own_child() {
            eprintln!(
                "SKIP pidfd_getfd_duplicates_fd_from_child : \
                 kernel.yama.ptrace_scope >= 2 sur cet environnement \
                 (blocage explicite, indépendant de parent → enfant)."
            );
            return;
        }

        // On ouvre `/dev/null` AVANT le fork : parent et enfant héritent
        // tous deux du même fd (numéro identique, même entrée en file
        // table). Après le fork, le parent demande au kernel — via
        // `pidfd_getfd` ciblé sur l'enfant — un duplicata de CE numéro
        // de fd côté enfant. Le duplicata est un nouveau fd côté parent
        // pointant sur la même file que le fd cible.
        use std::os::fd::IntoRawFd;
        let placeholder = std::fs::File::open("/dev/null").expect("open /dev/null");
        let placeholder_raw: RawFd = placeholder.into_raw_fd();

        let args = CloneArgs {
            flags: CloneFlags::PIDFD,
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique avec pidfd.
        let result = unsafe { clone3(&args) }.expect("clone3 doit réussir");
        match result {
            CloneResult::Child => {
                // Sleep assez long pour que le parent ait le temps
                // d'invoquer pidfd_getfd avant qu'on exit (relâcherait
                // le fd côté enfant).
                std::thread::sleep(std::time::Duration::from_millis(80));
                child_exit(0);
            }
            CloneResult::Parent {
                child_pid,
                child_pidfd,
            } => {
                let pidfd = child_pidfd.expect("CLONE_PIDFD demandé");
                let dup: OwnedFd = pidfd_getfd(pidfd.as_fd(), placeholder_raw, 0)
                    .expect("pidfd_getfd doit réussir");
                // `dup` est un fd côté parent pointant sur le même
                // `/dev/null` que celui qu'on avait ouvert avant fork.
                // Son numéro est nouveau (différent de `placeholder_raw`,
                // sauf collision improbable). Le simple fait que le
                // syscall ait réussi prouve la duplication ; on libère.
                let dup_raw = dup.as_raw_fd();
                assert!(dup_raw >= 0, "fd dupliqué doit être valide");
                drop(dup);
                // On nettoie aussi le `placeholder_raw` côté parent, qui
                // n'a jamais été wrappé dans un OwnedFd après le
                // `into_raw_fd()` initial.
                // SAFETY: `placeholder_raw` est un fd valide que nous
                // détenons (créé par `File::into_raw_fd`, transféré).
                drop(unsafe { OwnedFd::from_raw_fd(placeholder_raw) });
                let _ = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid final pour reaper");
            }
        }
    }

    // ── Groupes et sessions ───────────────────────────────────────────

    #[test]
    fn getpgid_none_returns_positive_pgid() {
        let pgid = getpgid(None).expect("getpgid(None) doit réussir");
        assert!(pgid.as_raw() > 0);
    }

    #[test]
    fn getpgid_self_equals_getpgid_none() {
        let self_pid = getpid();
        let via_none = getpgid(None).expect("getpgid(None)");
        let via_self = getpgid(Some(self_pid)).expect("getpgid(self)");
        assert_eq!(via_none, via_self);
    }

    #[test]
    fn getsid_none_returns_positive_sid() {
        let sid = getsid(None).expect("getsid(None) doit réussir");
        assert!(sid.as_raw() > 0);
    }

    #[test]
    fn getpgid_on_nonexistent_pid_returns_esrch() {
        // PID > PID_MAX_LIMIT (~2^22) ; couvre la branche d'erreur.
        let nope = Pid::try_from_raw(0x7FFF_FFFE).expect("pid littéral");
        let err = getpgid(Some(nope)).expect_err("getpgid PID inexistant");
        assert_eq!(err, Errno::ESRCH);
    }

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

    #[test]
    fn setsid_returns_eperm_when_caller_is_pgrp_leader() {
        // Le test runner cargo est lancé typiquement comme leader de son
        // process group ; setsid échoue alors avec EPERM. C'est le cas
        // canonique vérifié ici. Si l'environnement nous a placés dans
        // une situation où setsid réussit, on serait propriétaire d'une
        // nouvelle session — ce qui contaminerait les tests suivants.
        // On skippe proprement dans ce cas hypothétique.
        let self_pid = getpid();
        let pgid = getpgid(None).expect("getpgid");
        if self_pid != pgid {
            eprintln!(
                "SKIP setsid_returns_eperm_when_caller_is_pgrp_leader : \
                 l'appelant n'est pas pgrp leader (pid={} != pgid={}), \
                 scénario EPERM inapplicable",
                self_pid.as_raw(),
                pgid.as_raw()
            );
            return;
        }
        let err = setsid().expect_err("setsid sur pgrp leader doit échouer");
        assert_eq!(err, Errno::EPERM);
    }

    #[test]
    fn setpgid_self_to_own_pgrp_is_idempotent() {
        // Place self dans son propre process group (déjà le cas). C'est
        // une opération idempotente qui exerce le wrapper sans changer
        // d'état observable.
        let our_pgid = getpgid(None).expect("getpgid");
        setpgid(None, Some(our_pgid)).expect("setpgid(None, our_pgid) doit réussir");
    }

    #[test]
    fn setpgid_on_nonexistent_pid_returns_esrch() {
        // Couvre la branche d'erreur de setpgid.
        let nope = Pid::try_from_raw(0x7FFF_FFFE).expect("pid littéral");
        let err = setpgid(Some(nope), None).expect_err("setpgid PID inexistant");
        assert_eq!(err, Errno::ESRCH);
    }

    #[test]
    fn setsid_succeeds_in_forked_child() {
        // Le test runner cargo n'est typiquement PAS pgrp leader → on ne
        // peut pas tester `setsid` happy-path directement (cf. test
        // `setsid_returns_eperm_when_caller_is_pgrp_leader`).
        // On fork donc un enfant : l'enfant hérite du pgrp du parent
        // (n'est pas leader), et `setsid()` y SUCCÈDE en créant une
        // nouvelle session avec lui-même comme leader+SID. L'enfant
        // encode le résultat dans son code de sortie.
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique, pas de mémoire partagée.
        let result = unsafe { clone3(&args) }.expect("clone3");
        match result {
            CloneResult::Child => match setsid() {
                Ok(new_sid) => {
                    // L'enfant doit voir new_sid == son propre PID (il
                    // devient session leader). Encoder dans le code de
                    // sortie permet au parent de vérifier.
                    let child_pid = getpid();
                    if new_sid == child_pid {
                        child_exit(0);
                    } else {
                        child_exit(1);
                    }
                }
                Err(_) => child_exit(2),
            },
            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 }),
                    "setsid dans enfant doit réussir (event={:?})",
                    s.event
                );
            }
        }
    }

    #[test]
    fn setsid_returns_eperm_when_already_pgrp_leader_in_forked_child() {
        // Couvre la branche d'erreur (EPERM) de `setsid`. L'enfant fork'é
        // se rend pgrp leader (`setpgid(None, None)`) puis appelle
        // `setsid` qui DOIT échouer avec EPERM (un pgrp leader ne peut
        // pas créer une nouvelle session). Le code de sortie de l'enfant
        // encode le résultat.
        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 => {
                if setpgid(None, None).is_err() {
                    child_exit(40);
                }
                match setsid() {
                    Ok(_) => child_exit(41),
                    Err(e) if e == Errno::EPERM => child_exit(0),
                    Err(_) => child_exit(42),
                }
            }
            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 }),
                    "setsid sur pgrp leader doit retourner EPERM, event={:?}",
                    s.event
                );
            }
        }
    }

    #[test]
    fn set_dumpable_round_trip_in_forked_child() {
        // `set_dumpable` est process-wide. Pour ne pas contaminer les
        // autres tests, on round-trippe dans un enfant fork'é qui meurt
        // immédiatement après vérification.
        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 => {
                // Round-trip : NotDumpable ↔ Dumpable. `SuidDumpable` (=2)
                // est déprécié et rejeté par les kernels Linux récents
                // (EINVAL), donc non testé ici — le wrapper le supporte
                // pour conformité spec mais sa branche kernel reste
                // hors test sur ces noyaux.
                if set_dumpable(DumpableMode::NotDumpable).is_err() {
                    child_exit(10);
                }
                if !matches!(get_dumpable(), Ok(DumpableMode::NotDumpable)) {
                    child_exit(11);
                }
                if set_dumpable(DumpableMode::Dumpable).is_err() {
                    child_exit(12);
                }
                if !matches!(get_dumpable(), Ok(DumpableMode::Dumpable)) {
                    child_exit(13);
                }
                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 }),
                    "round-trip dumpable doit réussir, event={:?}",
                    s.event
                );
            }
        }
    }

    #[test]
    fn set_keep_caps_round_trip_in_forked_child() {
        // `set_keep_caps` est process-wide (touche les credentials du
        // process). Même technique : round-trip dans un enfant fork'é.
        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 => {
                if set_keep_caps(true).is_err() {
                    child_exit(20);
                }
                if !matches!(get_keep_caps(), Ok(true)) {
                    child_exit(21);
                }
                if set_keep_caps(false).is_err() {
                    child_exit(22);
                }
                if !matches!(get_keep_caps(), Ok(false)) {
                    child_exit(23);
                }
                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 }),
                    "round-trip keep_caps doit réussir, event={:?}",
                    s.event
                );
            }
        }
    }

    // ── prctl ─────────────────────────────────────────────────────────

    #[test]
    fn get_no_new_privs_returns_ok() {
        // Lecture seule — on ne SET PAS (irréversible côté process,
        // contaminerait les tests suivants). Le wrapper renvoie Ok(bool).
        let _value = get_no_new_privs().expect("get_no_new_privs doit réussir");
    }

    #[test]
    fn get_dumpable_returns_known_mode() {
        // Lecture seule pour éviter de contaminer d'autres tests (le bit
        // dumpable est process-wide).
        let mode = get_dumpable().expect("get_dumpable doit réussir");
        assert!(matches!(
            mode,
            DumpableMode::NotDumpable | DumpableMode::Dumpable | DumpableMode::SuidDumpable
        ));
    }

    #[test]
    fn thread_name_round_trip() {
        // PR_SET_NAME / PR_GET_NAME sont per-thread. cargo test exécute
        // chaque #[test] sur son propre worker thread, donc on peut
        // round-tripper sans contaminer les autres.
        let new_name = c"air-prctl-test";
        set_thread_name(new_name).expect("set_thread_name");
        let read_back = get_thread_name().expect("get_thread_name");
        assert_eq!(read_back.as_c_str(), new_name);
    }

    #[test]
    fn thread_name_kernel_truncates_at_15_chars() {
        // Le kernel tronque à 15 caractères + NUL. On passe 20 caractères
        // et on vérifie que get_thread_name récupère les 15 premiers.
        let long_name = c"abcdefghijklmnopqrst"; // 20 caractères
        set_thread_name(long_name).expect("set_thread_name long");
        let read_back = get_thread_name().expect("get_thread_name long");
        assert_eq!(read_back.to_bytes(), b"abcdefghijklmno"); // 15 premiers
    }

    #[test]
    fn parent_death_signal_round_trip() {
        // Per-thread sur Linux moderne. On utilise SIGKILL qui est déjà
        // dans le stub Signal ; round-trip Some/None/Some.
        set_parent_death_signal(Some(Signal::SIGKILL)).expect("set Some(SIGKILL)");
        let got = get_parent_death_signal().expect("get");
        assert_eq!(got, Some(Signal::SIGKILL));

        set_parent_death_signal(None).expect("set None");
        let got = get_parent_death_signal().expect("get after clear");
        assert_eq!(got, None);
    }

    #[test]
    fn set_timer_slack_accepts_zero_and_finite_values() {
        // 0 réinitialise à la valeur par défaut héritée. Toute autre
        // valeur est acceptée. On n'a pas get_timer_slack côté Air
        // (non listé par la spec) ; on vérifie juste l'absence d'erreur.
        set_timer_slack(0).expect("reset to default");
        set_timer_slack(50_000).expect("50 µs slack");
    }

    #[test]
    fn cap_ambient_is_set_returns_ok_for_known_capability() {
        // Un thread non-root n'a aucune capability ambiante par défaut ;
        // le test vérifie que le wrapper retourne Ok(false), pas qu'il
        // donne une valeur particulière.
        let _value =
            cap_ambient_is_set(Capability::SysAdmin).expect("cap_ambient_is_set doit réussir");
    }

    #[test]
    fn cap_ambient_lower_succeeds_unconditionally() {
        // PR_CAP_AMBIENT_LOWER clear le bit sans erreur même s'il n'était
        // pas positionné. Per-thread, donc safe.
        cap_ambient_lower(Capability::SysAdmin).expect("cap_ambient_lower doit réussir");
    }

    #[test]
    fn cap_ambient_clear_all_succeeds() {
        // Per-thread, idempotent.
        cap_ambient_clear_all().expect("cap_ambient_clear_all doit réussir");
    }

    #[test]
    fn cap_ambient_raise_non_permitted_returns_eperm() {
        if is_root() {
            eprintln!(
                "SKIP cap_ambient_raise_non_permitted_returns_eperm : \
                 le runner s'exécute en root, scénario EPERM inapplicable."
            );
            return;
        }
        // SysAdmin n'est jamais dans permitted∩inheritable pour un user
        // non-root standard → raise échoue avec EPERM.
        let err = cap_ambient_raise(Capability::SysAdmin)
            .expect_err("cap_ambient_raise non-root doit échouer");
        assert_eq!(err, Errno::EPERM);
    }

    // ── rlimits ───────────────────────────────────────────────────────

    #[test]
    fn prlimit_no_op_round_trip_returns_current_value() {
        // Lit la valeur courante, la ré-écrit (no-op), vérifie qu'on
        // retrouve la même valeur. Exerce getrlimit ET setrlimit côtés
        // wrapper, sans modifier l'état process-wide.
        let original = prlimit(None, Resource::NoFile, None).expect("prlimit read");
        let _back = prlimit(None, Resource::NoFile, Some(original)).expect("prlimit noop set");
        let verified = prlimit(None, Resource::NoFile, None).expect("prlimit verify");
        assert_eq!(verified, original);
    }

    #[test]
    fn getrlimit_legacy_alias_returns_same_as_prlimit() {
        let via_legacy = getrlimit(Resource::NoFile).expect("getrlimit");
        let via_prlimit = prlimit(None, Resource::NoFile, None).expect("prlimit");
        assert_eq!(via_legacy, via_prlimit);
    }

    #[test]
    fn setrlimit_legacy_alias_lower_soft_round_trip_then_restore() {
        // setrlimit modifie l'état process-wide ; on restore en fin de
        // test. Le test exerce la branche `setrlimit -> prlimit(Some)`
        // et la lecture suivante.
        let original = getrlimit(Resource::NoFile).expect("get original");
        let lowered_soft = match original.soft {
            RlimitValue::Finite(n) => match n.checked_sub(1) {
                Some(m) if m > 0 => RlimitValue::Finite(m),
                _ => {
                    eprintln!(
                        "SKIP setrlimit_legacy_alias_lower_soft_round_trip_then_restore : \
                         soft NoFile trop basse pour décrémenter"
                    );
                    return;
                }
            },
            RlimitValue::Infinity => {
                eprintln!(
                    "SKIP setrlimit_legacy_alias_lower_soft_round_trip_then_restore : \
                     soft NoFile est Infinity, scénario décrément inapplicable"
                );
                return;
            }
        };

        let lowered = Rlimit {
            soft: lowered_soft,
            hard: original.hard,
        };
        setrlimit(Resource::NoFile, lowered).expect("setrlimit lowered");
        let verified = getrlimit(Resource::NoFile).expect("verify lowered");
        assert_eq!(verified.soft, lowered.soft);

        // Restauration.
        setrlimit(Resource::NoFile, original).expect("restore original");
    }

    #[test]
    fn setrlimit_raising_hard_limit_returns_eperm_for_non_root() {
        if is_root() {
            eprintln!(
                "SKIP setrlimit_raising_hard_limit_returns_eperm_for_non_root : \
                 runner en root, scénario EPERM inapplicable."
            );
            return;
        }
        let original = getrlimit(Resource::NoFile).expect("get");
        let raised_hard = match original.hard {
            RlimitValue::Finite(h) => match h.checked_add(1) {
                Some(new_h) => RlimitValue::Finite(new_h),
                None => {
                    eprintln!("SKIP : hard NoFile = u64::MAX, ne peut être incrémentée");
                    return;
                }
            },
            RlimitValue::Infinity => {
                eprintln!("SKIP : hard NoFile = Infinity, impossible de la « relever »");
                return;
            }
        };
        let attempted = Rlimit {
            soft: original.soft,
            hard: raised_hard,
        };
        let err = setrlimit(Resource::NoFile, attempted)
            .expect_err("setrlimit raise hard doit échouer non-root");
        assert_eq!(err, Errno::EPERM);
    }

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

    // ── capget / capset ────────────────────────────────────────────────

    #[test]
    fn capget_current_thread_returns_ok() {
        let _set = capget(CapabilityTarget::CurrentThread).expect("capget(CurrentThread)");
    }

    #[test]
    fn capget_via_process_target_returns_same_as_current_thread() {
        // Couvre le bras `CapabilityTarget::Process(_)` du helper de dispatch
        // `cap_target_to_kernel_pid` (les autres tests n'utilisent que
        // `CurrentThread` et `Thread`). Pour le thread principal du
        // processus, `Thread(getpid())` et `Process(getpid())` ciblent la
        // même tâche kernel — donc les capabilities retournées sont
        // identiques (à la nuance près que sur des threads worker, le
        // PID renvoie le thread principal).
        let self_pid = getpid();
        let via_current = capget(CapabilityTarget::CurrentThread).expect("current");
        let via_process = capget(CapabilityTarget::Process(self_pid)).expect("process");
        // On vérifie que l'opération réussit ; les capabilities entre
        // threads d'un même processus peuvent différer (CAP_AUDIT_WRITE
        // par exemple peut être thread-spécifique), donc on ne fait
        // qu'asserter la viabilité du chemin de dispatch.
        let _ = (via_current, via_process);
    }

    #[test]
    fn rlim_value_infinity_round_trips_through_kernel_encoding() {
        // Couvre les deux branches `RlimitValue::Infinity` du codec
        // `rlim_value_to_kernel` / `rlim_value_from_kernel`. Sur Ubuntu
        // (et la plupart des distros), `Resource::Stack` a `hard =
        // Infinity` par défaut — donc lire+écrire+relire exerce les
        // deux conversions.
        let original = getrlimit(Resource::Stack).expect("getrlimit Stack");
        // Écrire la même valeur (no-op) : exerce `rlim_value_to_kernel`
        // pour les deux variantes (Finite pour soft, Infinity pour hard
        // si c'est le cas).
        setrlimit(Resource::Stack, original).expect("setrlimit no-op Stack");
        let verified = getrlimit(Resource::Stack).expect("re-read");
        assert_eq!(verified, original);

        // Vérification directe que au moins une des deux limites est
        // Infinity dans l'environnement (sinon le test ne couvre pas la
        // branche visée).
        let touches_infinity = matches!(
            (original.soft, original.hard),
            (RlimitValue::Infinity, _) | (_, RlimitValue::Infinity)
        );
        if !touches_infinity {
            eprintln!(
                "SKIP rlim_value_infinity_round_trips_through_kernel_encoding : \
                 Stack rlimit ne contient pas Infinity sur cet environnement \
                 (soft={:?}, hard={:?}), la branche Infinity n'est pas couverte.",
                original.soft, original.hard
            );
        }
    }

    #[test]
    fn capget_self_thread_equals_capget_current() {
        let self_tid = gettid();
        let via_current = capget(CapabilityTarget::CurrentThread).expect("capget current");
        let via_thread = capget(CapabilityTarget::Thread(self_tid)).expect("capget self thread");
        assert_eq!(via_current, via_thread);
    }

    #[test]
    fn capset_no_op_with_current_values_succeeds() {
        let current = capget(CapabilityTarget::CurrentThread).expect("capget");
        // Réécrire les mêmes valeurs : opération autorisée pour tout
        // thread, n'élève rien.
        capset(CapabilityTarget::CurrentThread, &current).expect("capset no-op");
    }

    #[test]
    fn capset_raise_non_permitted_returns_eperm() {
        if is_root() {
            eprintln!(
                "SKIP capset_raise_non_permitted_returns_eperm : \
                 runner en root, scénario EPERM inapplicable."
            );
            return;
        }
        let current = capget(CapabilityTarget::CurrentThread).expect("capget");
        if current.permitted.contains(Capability::SysAdmin) {
            eprintln!(
                "SKIP : SysAdmin est déjà dans permitted (file capabilities ?), \
                 scénario EPERM inapplicable."
            );
            return;
        }
        // Tente d'ajouter SysAdmin à effective alors qu'il n'est pas
        // dans permitted → kernel refuse (effective ⊆ permitted).
        let attempted = CapabilitySet {
            effective: current.effective.with(Capability::SysAdmin),
            permitted: current.permitted,
            inheritable: current.inheritable,
        };
        let err = capset(CapabilityTarget::CurrentThread, &attempted)
            .expect_err("capset élévation doit échouer non-root");
        assert_eq!(err, Errno::EPERM);
    }

    // ── mask_to_words / words_to_mask : placement absolu lo/hi ────────
    //
    // Une éventuelle inversion lo/hi dans `mask_to_words` se compenserait
    // dans un simple round-trip via `words_to_mask`. Ces tests vérifient
    // le placement ABSOLU des bits dans chaque mot, indépendamment du
    // round-trip — ils catchent l'inversion.

    #[test]
    fn mask_to_words_places_bit_0_in_lo() {
        let mask = CapabilityMask::from_bits(1_u64);
        let (lo, hi) = mask_to_words(mask);
        assert_eq!(lo, 1, "bit 0 doit aller en mot bas");
        assert_eq!(hi, 0, "bit 0 NE DOIT PAS aller en mot haut");
    }

    #[test]
    fn mask_to_words_places_bit_32_in_hi() {
        let mask = CapabilityMask::from_bits(1_u64 << 32);
        let (lo, hi) = mask_to_words(mask);
        assert_eq!(lo, 0, "bit 32 NE DOIT PAS aller en mot bas");
        assert_eq!(hi, 1, "bit 32 doit aller en mot haut");
    }

    #[test]
    fn words_to_mask_recombines_with_correct_placement() {
        // (lo=1, hi=0) doit donner bit 0 dans le mask, pas bit 32.
        let m1 = words_to_mask(1, 0);
        assert_eq!(m1.bits(), 1_u64);

        // (lo=0, hi=1) doit donner bit 32 dans le mask, pas bit 0.
        let m2 = words_to_mask(0, 1);
        assert_eq!(m2.bits(), 1_u64 << 32);

        // Combiné : bits dans les deux mots à la fois.
        let m3 = words_to_mask(0xFF, 0x01);
        assert_eq!(m3.bits(), (1_u64 << 32) | 0xFF_u64);
    }

    #[test]
    fn mask_words_round_trip_preserves_known_capability() {
        // Sanity check : Capability::SysAdmin (bit 21, mot bas) survit
        // un round-trip complet.
        let original = CapabilityMask::empty().with(Capability::SysAdmin);
        let (lo, hi) = mask_to_words(original);
        let recovered = words_to_mask(lo, hi);
        assert_eq!(recovered, original);
        assert!(recovered.contains(Capability::SysAdmin));
        // SysAdmin = 21, donc mot bas exclusivement.
        assert_eq!(lo, 1_u32 << 21);
        assert_eq!(hi, 0);
    }

    // ── Séparation de privilèges (privsep) ────────────────────────────────
    //
    // Les mutations de credentials sont **irréversibles** (saved-set) : on les
    // exécute dans des **enfants forkés** disposables (correctness via le code
    // de sortie observé par `waitid`). Les *getters* (read-only) et l'encodage
    // `Option → -1` sont couverts **en processus**. Tests privilégiés gardés par
    // `is_root()` (skip propre sinon → exception PRIVILEGE).
    //
    // Couverture des *setters* : un enfant qui **reste root** jusqu'au
    // `child_exit` voit son profil LLVM flushé (cf. `flush_child_coverage`), donc
    // leurs chemins **succès** sont comptabilisés ; leurs chemins **erreur**
    // (EPERM après réduction) sont prouvés fonctionnellement par l'enfant
    // « drop » (flush impossible une fois non-root → exception).

    /// Forke un enfant (fork classique), exécute `body` dans l'enfant (qui
    /// retourne son **code de sortie** : `0` = succès, `N != 0` = étape `N`
    /// échouée), termine l'enfant via `child_exit` (flush de couverture), et
    /// retourne le code observé par le parent via `waitid`.
    fn run_child(body: impl FnOnce() -> i32) -> i32 {
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique (pas de CLONE_VM, pas de namespaces) ; aucune
        // mémoire partagée, aucune capability requise pour le fork lui-même.
        match unsafe { clone3(&args) }.expect("clone3 doit réussir") {
            CloneResult::Child => child_exit(body()),
            CloneResult::Parent { child_pid, .. } => {
                let status = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid")
                    .expect("événement EXITED disponible");
                match status.event {
                    WaitEvent::Exited { code } => code,
                    other => panic!("événement de sortie inattendu : {other:?}"),
                }
            }
        }
    }

    #[test]
    fn privsep_opt_encoding_round_trips() {
        // `None` → sentinelle `-1` ; `Some(id)` → sa valeur brute.
        assert_eq!(opt_gid_to_raw(None), u32::MAX);
        assert_eq!(opt_uid_to_raw(None), u32::MAX);
        assert_eq!(opt_gid_to_raw(Some(Gid::ROOT)), 0);
        assert_eq!(opt_uid_to_raw(Some(Uid::from_raw(1000))), 1000);
        assert_eq!(opt_gid_to_raw(Some(Gid::from_raw(u32::MAX))), u32::MAX);
    }

    proptest::proptest! {
        /// Encodage `Option<Uid/Gid>` → `u32` : `None` ⇒ `-1`, `Some(v)` ⇒ `v`.
        #[test]
        fn prop_opt_encoding(value in proptest::option::of(0u32..=u32::MAX)) {
            let expected = value.unwrap_or(u32::MAX);
            proptest::prop_assert_eq!(opt_gid_to_raw(value.map(Gid::from_raw)), expected);
            proptest::prop_assert_eq!(opt_uid_to_raw(value.map(Uid::from_raw)), expected);
        }
    }

    #[test]
    fn set_groups_too_many_is_einval() {
        // > NGROUPS_MAX ⇒ EINVAL **en amont** (Principe 4), sans privilège ni
        // syscall ni mutation : ne touche pas les credentials du test.
        let groups = vec![Gid::ROOT; NGROUPS_MAX + 1];
        assert_eq!(set_groups(&groups), Err(Errno::EINVAL));
    }

    #[test]
    fn privsep_getters_read_own_credentials() {
        // Read-only : couvre les chemins **succès** de getres*/getgroups sans
        // privilège ni mutation. Buffer généreux (≤ 1024 groupes supplémentaires
        // — au-delà de tout utilisateur réel).
        let ru = get_resuid().expect("getresuid");
        let rg = get_resgid().expect("getresgid");
        // Un processus de test normal a real == effective.
        assert_eq!(ru.real, ru.effective);
        assert_eq!(rg.real, rg.effective);
        let mut buf = vec![Gid::ROOT; 1024];
        let groups = get_groups(&mut buf).expect("getgroups (≤ 1024 groupes)");
        assert!(groups.len() <= 1024);
    }

    // Les corps d'enfant ci-dessous sont **sans branche locale** : conditions
    // combinées par `&` (ET bit-à-bit, non court-circuitant) et `==`/`is_ok`, de
    // sorte qu'un enfant qui largue ses privilèges (flush de couverture
    // impossible) n'introduise **aucune** branche non couverte. La correction est
    // prouvée par le code de sortie (`0` = succès) observé par le parent.

    #[test]
    fn privsep_setters_succeed_as_root() {
        if !is_root() {
            return; // PRIVILEGE : nécessite CAP_SETUID/CAP_SETGID.
        }
        // Enfant qui **reste root** (uid 0) : son profil de couverture est flushé,
        // couvrant les chemins **succès** des setters (no-op root → root) et
        // l'erreur EINVAL de `get_groups` (buffer trop petit).
        let code = run_child(|| {
            let mut small = [Gid::ROOT; 1];
            let mut buf = [Gid::ROOT; 8];
            let ok = set_groups(&[]).is_ok()
                & set_groups(&[Gid::from_raw(1), Gid::from_raw(2)]).is_ok()
                & (get_groups(&mut small) == Err(Errno::EINVAL))
                & (get_groups(&mut buf).map(<[Gid]>::len) == Ok(2))
                & set_resgid(Some(Gid::ROOT), Some(Gid::ROOT), Some(Gid::ROOT)).is_ok()
                & set_resuid(Some(Uid::ROOT), Some(Uid::ROOT), Some(Uid::ROOT)).is_ok()
                & (get_resuid()
                    == Ok(ResUid {
                        real: Uid::ROOT,
                        effective: Uid::ROOT,
                        saved: Uid::ROOT,
                    }))
                & (get_resgid()
                    == Ok(ResGid {
                        real: Gid::ROOT,
                        effective: Gid::ROOT,
                        saved: Gid::ROOT,
                    }));
            i32::from(!ok)
        });
        assert_eq!(code, 0, "séquence privsep (root) échouée");
    }

    #[test]
    fn privsep_drop_is_irreversible() {
        if !is_root() {
            return; // PRIVILEGE.
        }
        // `nobody`/`nogroup` (ids numériques standard, pas besoin d'entrée passwd).
        const NOBODY_UID: u32 = 65534;
        const NOBODY_GID: u32 = 65534;
        let code = run_child(|| {
            let gid = Gid::from_raw(NOBODY_GID);
            let uid = Uid::from_raw(NOBODY_UID);
            // Ordre **correct** du privsep : groupes → GID → UID.
            let dropped = set_groups(&[]).is_ok()
                & set_resgid(Some(gid), Some(gid), Some(gid)).is_ok()
                & set_resuid(Some(uid), Some(uid), Some(uid)).is_ok();
            // **Le cœur** : saved-set fixé ⇒ regain root impossible, et plus de
            // `CAP_SETGID` ⇒ pas de réajout de groupe ; tout figé sur la cible.
            let locked = (set_resuid(Some(Uid::ROOT), None, None) == Err(Errno::EPERM))
                & (set_resgid(Some(Gid::ROOT), None, None) == Err(Errno::EPERM))
                & (set_groups(&[Gid::ROOT]) == Err(Errno::EPERM))
                & (get_resuid()
                    == Ok(ResUid {
                        real: uid,
                        effective: uid,
                        saved: uid,
                    }))
                & (get_resgid()
                    == Ok(ResGid {
                        real: gid,
                        effective: gid,
                        saved: gid,
                    }));
            i32::from(!(dropped & locked))
        });
        assert_eq!(code, 0, "regain de privilège possible ou drop incorrect");
    }

    #[test]
    fn privsep_resuid_none_changes_only_effective() {
        if !is_root() {
            return; // PRIVILEGE.
        }
        const NOBODY_UID: u32 = 65534;
        let code = run_child(|| {
            let uid = Uid::from_raw(NOBODY_UID);
            // `None` pour real et saved : seul l'effective change (root le peut).
            let ok = set_resuid(None, Some(uid), None).is_ok()
                & (get_resuid()
                    == Ok(ResUid {
                        real: Uid::ROOT,
                        effective: uid,
                        saved: Uid::ROOT,
                    }));
            i32::from(!ok)
        });
        assert_eq!(code, 0, "None ne devrait changer que l'effective");
    }

    // ── exec / redirection : execve, execveat, dup3, fchdir, chdir ────────
    //
    // Stratégie de test (cf. CLAUDE.md, rigueur couche 0) :
    // - `execve`/`execveat` ne peuvent PAS s'auto-tester dans le process de
    //   test : un exec réussi REMPLACE l'image du process et n'en revient
    //   jamais. On teste donc :
    //   * les chemins d'ERREUR **en process** (ENOENT/EACCES/ENOEXEC) — l'exec
    //     échoué retourne, ce qui couvre le corps complet du wrapper ;
    //   * un exec RÉUSSI dans un **enfant forké** (`clone3`) qui exécute
    //     `/usr/bin/true` (sortie 0) ou ouvre un fd dessus ; le parent vérifie
    //     le code de sortie via `waitid`.
    // - `dup3`/`fchdir`/`chdir` sont testables directement. Les SUCCÈS de
    //   `fchdir`/`chdir` mutent le cwd (état **process-global**) : ils sont donc
    //   exécutés dans un enfant forké pour ne pas perturber les tests `fs`
    //   concurrents qui résolvent des chemins relatifs depuis le cwd.

    use air_sys_types::fd::AsFd;

    // Vérification alloc-free du cwd dans les enfants forkés (cf. `fork_run`) :
    // `statx` remplit une structure sur la pile (aucun heap), donc utilisable
    // post-fork là où `std::fs::read_link` (qui alloue) ne l'est pas.
    use crate::fs::statx;
    use air_sys_types::fs::{StatxFlags, StatxMask};

    // Création de fichier alloc-free dans un enfant forké (cf. `fork_run`) :
    // syscalls bruts au lieu de `std::fs::write`/`set_permissions` (qui allouent
    // ET dont le fd en écriture, ouvert côté parent, exposerait une course
    // `ETXTBSY` via héritage à un `clone3` concurrent).
    use crate::fs::{close, fchmodat, openat, write};
    use air_sys_types::fs::OpenFlags;

    /// Forke via `clone3`, exécute `child` dans l'enfant (qui termine via
    /// `child_exit` avec le code retourné), et renvoie le code de sortie observé
    /// par le parent via `waitid`. `child` ne doit JAMAIS paniquer — un `panic`
    /// dans un enfant forké d'un harnais multi-thread corromprait le protocole
    /// de sortie enfant→parent ; il rapporte ses échecs par un code ≠ 0.
    ///
    /// **La closure `child` DOIT être async-signal-safe : aucune allocation,
    /// aucun verrou.** Le harnais de test est multi-threadé (tests `io_uring`
    /// concurrents : workers/SQPOLL). Si le `clone3` survient pendant qu'un
    /// thread sibling tient le **verrou d'allocateur de la glibc**, le premier
    /// `malloc` de l'enfant deadlock en `futex_wait` (l'état du verrou est copié
    /// *locked*, et le thread qui le détenait n'existe pas dans l'enfant) → le
    /// parent `waitid` à l'infini. La closure ne doit donc faire QUE des
    /// syscalls sur des données **pré-construites dans le parent avant le fork**
    /// (`execve_prepared`/[`execveat_prepared`] sur des `CStrArray` matérialisés,
    /// `chdir`/`fchdir`/`statx`, comparaisons d'`Errno`) : zéro `format!`,
    /// `String`, `Vec`, `CString::new`, `std::fs::*`, `File::open` ou `println!`.
    /// Tout setup allouant (création/écriture de fichier, ouverture de fd,
    /// marshalling argv/envp) se fait côté parent ; le nettoyage aussi.
    fn fork_run(child: impl FnOnce() -> i32) -> i32 {
        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork classique (pas de CLONE_VM ni de namespace) : aucune
        // mémoire partagée, aucune capability requise.
        match unsafe { clone3(&args) }.expect("clone3 doit réussir") {
            CloneResult::Child => child_exit(child()),
            CloneResult::Parent { child_pid, .. } => {
                let status = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid doit réussir")
                    .expect("événement EXITED disponible");
                match status.event {
                    WaitEvent::Exited { code } => code,
                    other => panic!("attendu Exited, obtenu : {other:?}"),
                }
            }
        }
    }

    /// Invoque `execveat` **sans allocation**, depuis des [`CStrArray`]
    /// pré-construits dans le parent. Pendant qu'[`execveat`] (production)
    /// alloue ses tableaux argv/envp via [`CStrArray::new`], ce shim de test
    /// reproduit son cœur (le seul syscall) en sautant cette construction : il
    /// est donc utilisable depuis la closure de [`fork_run`], qui doit rester
    /// async-signal-safe. Renvoie toujours l'`Errno` d'échec — un succès remplace
    /// l'image du process et ne revient jamais.
    fn execveat_prepared(
        dirfd: DirFd<'_>,
        path: &CStr,
        argv: &CStrArray<'_>,
        envp: &CStrArray<'_>,
        flags: ExecveatFlags,
    ) -> Errno {
        // SAFETY: même contrat que `execveat` — `path` est un `CStr` valide
        // NUL-terminé ; `argv`/`envp` exposent des tableaux de pointeurs C
        // valides, NULL-terminés, vivants pour l'appel (matérialisés AVANT le
        // fork dans le parent) ; `dirfd` est `AT_FDCWD` ou un fd valide
        // emprunté ; `flags` est un masque `AT_*` typé. Le kernel ne fait que
        // lire ces données.
        let ret = unsafe {
            raw_syscall_execveat(
                dirfd_to_raw(dirfd),
                path.as_ptr() as u64,
                argv.as_ptr() as u64,
                envp.as_ptr() as u64,
                flags.bits(),
            )
        };
        errno_from_negative_syscall_ret(ret)
    }

    // ── CStrArray (marshalling argv/envp, pur — aussi fuzzé) ──────────────

    #[test]
    fn cstr_array_empty_contains_only_null() {
        let arr = CStrArray::new(&[]);
        assert_eq!(arr.len(), 0);
        assert!(arr.is_empty());
        // SAFETY: `as_ptr` renvoie un tableau valide d'au moins un pointeur
        // (le terminateur). On lit le premier élément.
        let first = unsafe { *arr.as_ptr() };
        assert!(first.is_null(), "tableau vide ⇒ uniquement le NULL final");
    }

    #[test]
    fn cstr_array_preserves_order_and_null_terminates() {
        let items: [&CStr; 3] = [c"argv0", c"deux", c"trois"];
        let arr = CStrArray::new(&items);
        assert_eq!(arr.len(), 3);
        assert!(!arr.is_empty());
        let base = arr.as_ptr();
        for (i, item) in items.iter().enumerate() {
            // SAFETY: `i < 3` ⇒ dans les bornes du tableau (3 pointeurs + NULL).
            let ptr = unsafe { *base.add(i) };
            // SAFETY: `ptr` pointe la i-ème chaîne C, vivante (empruntée à
            // `items`), NUL-terminée par construction de `CStr`.
            let got = unsafe { CStr::from_ptr(ptr) };
            assert_eq!(got, *item, "ordre préservé en position {i}");
        }
        // Terminateur NULL en position 3.
        // SAFETY: position du terminateur, dans les bornes (4 éléments).
        let term = unsafe { *base.add(3) };
        assert!(term.is_null(), "terminaison NULL présente");
    }

    #[test]
    fn fuzz_api_marshal_exec_args_is_total() {
        // Liste vide (le tableau ne contient que le NULL : boucle s'arrête en 0).
        fuzz_api::marshal_exec_args(vec![]);
        // Morceaux valides + un morceau à NUL embarqué (écarté proprement) +
        // un argument vide (valide). Couvre le parcours non vide.
        fuzz_api::marshal_exec_args(vec![
            b"prog".to_vec(),
            b"--flag".to_vec(),
            b"avec\0nul".to_vec(),
            b"".to_vec(),
        ]);
    }

    // ── execve / execveat ────────────────────────────────────────────────

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execve_enoent_on_missing_path() {
        // En process : un exec échoué RETOURNE, couvrant tout le corps du
        // wrapper (marshalling + syscall + conversion errno).
        let err = execve(c"/nonexistent/air-exec-test-xyz", &[c"x"], &[]).unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execve_eacces_on_non_executable_file() {
        // `/proc/self/status` est un fichier régulier sans aucun bit `x`
        // (toujours présent sur Linux, jamais ouvert en écriture ⇒ pas de
        // course `ETXTBSY`). L'exécution exige au moins un bit `x`, même pour
        // root (CAP_DAC_OVERRIDE n'accorde l'exécution que si un bit `x` existe)
        // ⇒ EACCES de façon déterministe.
        let err = execve(c"/proc/self/status", &[c"x"], &[]).unwrap_err();
        assert_eq!(err, Errno::EACCES);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execve_enoexec_on_unknown_format() {
        // Préparation côté PARENT (allocation autorisée ; cf. la règle
        // async-signal-safe de `fork_run`) : on construit le `CString` du chemin
        // et les tableaux argv/envp. Le fichier au format invalide (ni ELF, ni
        // `#!`) est en revanche créé **dans l'enfant**, via des **syscalls bruts**
        // (`openat`/`write`/`fchmodat`/`close`) qui n'allouent pas : le fd en
        // écriture reste donc **privé à cet enfant mono-thread** (aucun `clone3`
        // concurrent ne peut l'hériter) et il est **fermé avant l'`execve`** ⇒
        // pas de course `ETXTBSY`. `std::fs::write`/`set_permissions` sont
        // proscrits ici : ils allouent (deadlock allocateur post-fork) et, si on
        // les déportait côté parent, leur fd en écriture rouvrirait la course
        // `ETXTBSY`. Le format invalide donne ENOEXEC, rapporté par le code de
        // sortie.
        let path = format!("/tmp/air-enoexec-{}", std::process::id());
        let cpath = CString::new(path.clone().into_bytes()).expect("chemin /tmp sans NUL");
        let argv: [&CStr; 1] = [c"x"];
        let argv_array = CStrArray::new(&argv);
        let envp: [&CStr; 0] = [];
        let envp_array = CStrArray::new(&envp);

        let code = fork_run(|| {
            let bytes: &[u8] = b"\xff\xfe pas un binaire";
            // Les erreurs de setup sont ignorées (comme l'étaient les
            // `std::fs::write`/`set_permissions` de la version précédente) : un
            // échec de création laisserait l'`execve` renvoyer ENOENT/EACCES, et
            // l'assertion finale tomberait avec un message clair. `fchmodat`
            // force 0o755 indépendamment de l'umask (qui pourrait masquer le bit
            // `x` du propriétaire et donner EACCES au lieu d'ENOEXEC). Le fd en
            // écriture est fermé AVANT l'`execve` ⇒ pas de course `ETXTBSY`.
            // `.map` (combinateur de `core`) plutôt qu'un `if let` : la
            // discrimination Ok/Err vit dans la bibliothèque (hors couverture de
            // ce fichier), comme l'étaient les branches internes du
            // `std::fs::write` précédent — pas de branche `process.rs` ajoutée.
            let _ = openat(
                DirFd::Cwd,
                &cpath,
                OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::TRUNC,
                0o755,
            )
            .map(|fd| {
                let _ = write(fd.as_fd(), bytes);
                let _ = fchmodat(DirFd::Cwd, &cpath, 0o755, 0);
                let _ = close(fd);
            });
            let err = execve_prepared(&cpath, &argv_array, &envp_array).unwrap_err();
            i32::from(err != Errno::ENOEXEC)
        });

        let _ = std::fs::remove_file(&path); // nettoyage côté PARENT
        assert_eq!(code, 0, "execve d'un format inconnu doit donner ENOEXEC");
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execve_runs_binary_in_forked_child() {
        // Tableaux argv/envp matérialisés côté PARENT ; l'enfant ne fait qu'un
        // `execve_prepared` (alloc-free, async-signal-safe — cf. `fork_run`).
        let argv: [&CStr; 1] = [c"true"];
        let argv_array = CStrArray::new(&argv);
        let envp: [&CStr; 0] = [];
        let envp_array = CStrArray::new(&envp);
        let code = fork_run(|| {
            // Succès ⇒ `/usr/bin/true` s'exécute et sort 0 ; on n'arrive après
            // l'exec QUE s'il a échoué.
            let _ = execve_prepared(c"/usr/bin/true", &argv_array, &envp_array);
            1
        });
        assert_eq!(code, 0, "execve(/usr/bin/true) doit aboutir à un exit 0");
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execveat_enoent_on_missing_path() {
        // En process (échec retourné) : couvre le corps d'`execveat` et le bras
        // `DirFd::Cwd` de `dirfd_to_raw`.
        let err = execveat(
            DirFd::Cwd,
            c"/nonexistent/air-execveat-xyz",
            &[c"x"],
            &[],
            ExecveatFlags::empty(),
        )
        .unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execveat_empty_path_executes_open_fd() {
        // EMPTY_PATH : l'exécutable est désigné directement par le fd ouvert.
        // Ouverture du fd et tableaux argv/envp matérialisés côté PARENT ;
        // l'enfant ne fait qu'un `execveat_prepared` (alloc-free) sur le
        // `BorrowedFd` emprunté — cf. la règle async-signal-safe de `fork_run`.
        let file = std::fs::File::open("/usr/bin/true").expect("ouverture de /usr/bin/true");
        let fd = sfd(&file);
        let argv: [&CStr; 1] = [c"true"];
        let argv_array = CStrArray::new(&argv);
        let envp: [&CStr; 0] = [];
        let envp_array = CStrArray::new(&envp);
        let code = fork_run(|| {
            let _ = execveat_prepared(
                DirFd::Fd(fd),
                c"",
                &argv_array,
                &envp_array,
                ExecveatFlags::EMPTY_PATH,
            );
            1 // execveat a échoué
        });
        assert_eq!(
            code, 0,
            "execveat(EMPTY_PATH, fd /usr/bin/true) doit sortir 0"
        );
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execveat_relative_path_executes() {
        // Résolution relative : dirfd sur /usr/bin, chemin « true ». Couvre le
        // bras `DirFd::Fd` de `dirfd_to_raw`. Ouverture du dirfd et tableaux
        // argv/envp côté PARENT ; l'enfant ne fait qu'un `execveat_prepared`
        // (alloc-free) — cf. la règle async-signal-safe de `fork_run`.
        let dir = std::fs::File::open("/usr/bin").expect("ouverture de /usr/bin");
        let fd = sfd(&dir);
        let argv: [&CStr; 1] = [c"true"];
        let argv_array = CStrArray::new(&argv);
        let envp: [&CStr; 0] = [];
        let envp_array = CStrArray::new(&envp);
        let code = fork_run(|| {
            let _ = execveat_prepared(
                DirFd::Fd(fd),
                c"true",
                &argv_array,
                &envp_array,
                ExecveatFlags::empty(),
            );
            1
        });
        assert_eq!(code, 0, "execveat(dirfd=/usr/bin, \"true\") doit sortir 0");
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execveat_with_dir_fd_enoent() {
        // En process (échec retourné) : couvre le bras `DirFd::Fd` de
        // `dirfd_to_raw`. Chemin relatif inexistant sous un dirfd ouvert ⇒
        // ENOENT, sans remplacer l'image du process.
        let root = std::fs::File::open("/").expect("ouverture de /");
        let err = execveat(
            DirFd::Fd(sfd(&root)),
            c"air-execveat-no-such-relative",
            &[c"x"],
            &[],
            ExecveatFlags::empty(),
        )
        .unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn execveat_prepared_returns_errno_in_process() {
        // Couvre le shim de test `execveat_prepared` **en process** : dans les
        // enfants forkés, un `execveat` réussi remplace l'image AVANT
        // `child_exit`, donc la couverture du shim n'y est jamais flushée. Ici,
        // un chemin inexistant fait RETOURNER le shim (ENOENT) — exactement le
        // même appel (tableaux pré-construits) que côté enfant, sans remplacer
        // l'image. Analogue de la couverture d'`execve_prepared` via `execve`.
        let argv: [&CStr; 1] = [c"x"];
        let argv_array = CStrArray::new(&argv);
        let envp: [&CStr; 0] = [];
        let envp_array = CStrArray::new(&envp);
        let err = execveat_prepared(
            DirFd::Cwd,
            c"/nonexistent/air-execveat-prepared-xyz",
            &argv_array,
            &envp_array,
            ExecveatFlags::empty(),
        );
        assert_eq!(err, Errno::ENOENT);
    }

    // ── dup3 ──────────────────────────────────────────────────────────────

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn dup3_redirects_onto_target_and_owns_result() {
        // Sérialise l'usage d'un fd HAUT non réutilisable (cf. doc du lock).
        let _guard = fd_observation_lock();
        let target = high_unreusable_fd_target();
        let null = std::fs::OpenOptions::new()
            .read(true)
            .write(true)
            .open("/dev/null")
            .expect("ouverture de /dev/null");
        let dup = dup3(sfd(&null), target, Dup3Flags::CLOEXEC).expect("dup3 doit réussir");
        assert_eq!(
            dup.as_raw_fd(),
            target,
            "dup3 installe le nouveau fd au numéro demandé"
        );
        // `drop(dup)` ferme `target` ; `drop(null)` ferme l'original.
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn dup3_same_old_new_is_einval() {
        let null = std::fs::File::open("/dev/null").expect("ouverture de /dev/null");
        let raw = sraw(&null);
        // `dup3` exige `old != new` (différence avec `dup2`) : EINVAL.
        let err = dup3(sfd(&null), raw, Dup3Flags::empty()).unwrap_err();
        assert_eq!(err, Errno::EINVAL);
    }

    // ── fchdir / chdir ────────────────────────────────────────────────────

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn fchdir_error_on_non_directory() {
        // /dev/null n'est pas un répertoire ⇒ ENOTDIR (cwd inchangé : sûr en
        // process). Couvre le corps + le bras d'erreur de `fchdir`.
        let null = std::fs::File::open("/dev/null").expect("ouverture de /dev/null");
        let err = fchdir(sfd(&null)).unwrap_err();
        assert_eq!(err, Errno::ENOTDIR);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn chdir_error_on_missing_path() {
        // Chemin inexistant ⇒ ENOENT (cwd inchangé : sûr en process).
        let err = chdir(c"/nonexistent/air-chdir-test").unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn chroot_root_noop_or_eperm() {
        // `chroot("/")` : sur un runner **privilégié** (CI root), la racine est déjà `/`
        // ⇒ **no-op inoffensif** (`Ok`) ; sinon `EPERM`. La ligne est exercée dans les
        // deux cas. Chemin **succès** = exception PRIVILEGE (`CAP_SYS_CHROOT`).
        let result = chroot(c"/");
        assert!(
            result.is_ok() || result == Err(Errno::EPERM),
            "chroot(/) doit rendre Ok (root) ou EPERM (non privilégié) : {result:?}"
        );
        // Chemin **inexistant** : `ENOENT` (root) ou `EPERM` (non-root) ⇒ toujours `Err`.
        assert!(chroot(c"/air/no/such/root-xyz").is_err());
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn chdir_changes_cwd_in_forked_child() {
        // Mutation du cwd (process-global) ⇒ enfant forké. Vérifie le succès ET
        // l'effet réel **sans allocation** (async-signal-safe — cf. `fork_run`) :
        // après `chdir("/")`, le cwd (".") doit désigner la même inode (ino +
        // dev) que "/". `statx` remplit une structure sur la pile (zéro heap),
        // contrairement à `std::fs::read_link` qui alloue un `PathBuf`.
        // Combinateurs de `core` (`.ok()`/`.zip()`/`.is_some_and()`) plutôt
        // qu'un `match` : la discrimination Ok/Err des deux `statx` et le `&&` de
        // la comparaison vivent dans la bibliothèque (hors couverture de ce
        // fichier). Seul subsiste le `&&` du `chdir` (sa branche d'échec, comme
        // dans la version `read_link` précédente).
        let code = fork_run(|| {
            let same = chdir(c"/").is_ok()
                && statx(DirFd::Cwd, c".", StatxFlags::empty(), StatxMask::INO)
                    .ok()
                    .zip(statx(DirFd::Cwd, c"/", StatxFlags::empty(), StatxMask::INO).ok())
                    .is_some_and(|(cwd, root)| {
                        (cwd.ino, cwd.dev_major, cwd.dev_minor)
                            == (root.ino, root.dev_major, root.dev_minor)
                    });
            i32::from(!same)
        });
        assert_eq!(code, 0, "chdir(/) doit positionner le cwd à /");
    }

    #[test]
    #[cfg_attr(miri, ignore = "syscalls non supportés par Miri")]
    fn fchdir_changes_cwd_in_forked_child() {
        // Ouverture du fd sur "/" côté PARENT ; l'enfant ne fait que `fchdir`
        // puis vérifie l'effet via `statx` (alloc-free), sans `read_link` qui
        // allouerait — cf. la règle async-signal-safe de `fork_run`.
        let root = std::fs::File::open("/").expect("ouverture de /");
        let fd = sfd(&root);
        // Combinateurs de `core` (cf. `chdir_changes_cwd_in_forked_child`) :
        // pas de branche `process.rs` au-delà de l'échec de `fchdir`.
        let code = fork_run(|| {
            let same = fchdir(fd).is_ok()
                && statx(DirFd::Cwd, c".", StatxFlags::empty(), StatxMask::INO)
                    .ok()
                    .zip(statx(DirFd::Cwd, c"/", StatxFlags::empty(), StatxMask::INO).ok())
                    .is_some_and(|(cwd, target)| {
                        (cwd.ino, cwd.dev_major, cwd.dev_minor)
                            == (target.ino, target.dev_major, target.dev_minor)
                    });
            i32::from(!same)
        });
        assert_eq!(code, 0, "fchdir(fd /) doit positionner le cwd à /");
    }
}

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

    #[test]
    fn getppid_returns_some_positive() {
        // Le parent du runner de test est toujours visible dans son namespace.
        let ppid = getppid().expect("parent visible dans le PID namespace");
        assert!(ppid.as_raw() > 0);
    }

    #[test]
    fn sched_yield_is_callable() {
        // Fonction totale : ne panique pas, ne retourne rien.
        sched_yield();
    }

    #[test]
    fn umask_roundtrip_restores_previous() {
        // umask rend l'ANCIEN masque. On pose 0o022, on lit (et restaure) :
        let previous = umask(0o022);
        let seen = umask(previous); // rend 0o022 (ce qu'on venait de poser) + restaure
        assert_eq!(seen, 0o022);
        // Filet : on remet bien l'état initial.
        let _ = umask(previous);
    }

    #[test]
    fn getcwd_matches_std_current_dir() {
        let mut buf = [0_u8; 4096];
        let cwd = getcwd(&mut buf).expect("getcwd dans un buffer large");
        let expected = std::env::current_dir().expect("cwd std");
        assert_eq!(cwd, expected.as_os_str().as_encoded_bytes());
    }

    #[test]
    fn getcwd_buffer_too_small_is_erange() {
        let mut tiny = [0_u8; 1];
        // ERANGE == 34 (Linux) ; l'enum Errno partiel ne l'expose pas forcément
        // en constante nommée → on le construit explicitement.
        let erange = Errno::from_nonzero(NonZeroI32::new(34).expect("34 != 0"));
        assert_eq!(getcwd(&mut tiny), Err(erange));
    }

    #[test]
    fn getrusage_self_succeeds_and_fills() {
        let usage = getrusage(RusageWho::SelfProcess).expect("getrusage(SELF)");
        // Un processus en cours a forcément déclenché des fautes de page mineures.
        assert!(usage.ru_minflt >= 0);
    }

    #[test]
    fn getrusage_children_and_thread_variants() {
        // Couvre les deux autres bras de l'enum `who`.
        let _ = getrusage(RusageWho::Children).expect("getrusage(CHILDREN)");
        let _ = getrusage(RusageWho::Thread).expect("getrusage(THREAD)");
    }

    /// Emplacements partagés `'static` (VM commune via `CLONE_VM`) que l'enfant
    /// du test `None` de [`set_tid_address`] publie : le TID rendu par le syscall
    /// et un drapeau de fin. `None` ne fournit **aucun** mot kernel de fin de
    /// thread (pas de `clear_child_tid` ré-mis à 0) — l'enfant signale donc
    /// lui-même sa progression au parent via ces atomiques.
    struct SetTidNoneSlots {
        /// TID rendu par `set_tid_address(None)` (l'appelant = le thread enfant).
        tid: core::sync::atomic::AtomicI32,
        /// `0` tant que l'enfant n'a pas publié `tid` ; `1` une fois écrit.
        done: core::sync::atomic::AtomicU32,
    }

    /// Point d'entrée du thread de test pour le chemin `None` de
    /// [`set_tid_address`] : interprète `arg` comme l'adresse d'un
    /// [`SetTidNoneSlots`] `'static` partagé, appelle `set_tid_address(None)`
    /// (qui **désenregistre** `clear_child_tid` et **rend** le TID appelant),
    /// publie ce TID, lève le drapeau `done`, réveille le parent, puis
    /// **retourne** — le trampoline [`clone_thread`] termine alors le thread
    /// (`SYS_exit`).
    ///
    /// **Discipline côté enfant** : async-signal-safe, **zéro glibc** — deux
    /// syscalls seulement (`set_tid_address`, `futex_wake`), aucun accès TLS,
    /// aucune allocation.
    extern "C" fn set_tid_address_none_entry(arg: usize) {
        use air_sys_types::{FutexScope, FutexWakeCount};
        use core::sync::atomic::Ordering;
        // SAFETY (test) : `arg` est l'adresse d'un `SetTidNoneSlots` `'static`
        // (`Box::leak`, jamais libéré) fourni par le parent et partagé via la VM
        // commune. Alignement et validité garantis par le site d'appel.
        let slots = unsafe { &*(arg as *const SetTidNoneSlots) };
        // SAFETY: thread possédé par Air (jamais réapé par glibc, contrairement à
        // un `std::thread` détaché) ; `set_tid_address(None)` désenregistre
        // `clear_child_tid` — sans effet ici car aucun `CHILD_CLEARTID` n'a été
        // enregistré pour ce thread (pas de mot de join kernel concurrent à
        // écraser). Le syscall est total : il rend le TID de l'appelant.
        let tid = unsafe { set_tid_address(None) };
        slots.tid.store(tid.as_raw(), Ordering::SeqCst);
        // `Release` : apparie le `Acquire` du parent — `tid` est visible avant
        // que `done` ne passe à 1.
        slots.done.store(1, Ordering::Release);
        // Réveille le parent éventuellement endormi dans `futex_wait` sur `done`
        // (le timeout du parent le ferait converger même sans ce réveil).
        let _ = crate::futex::futex_wake(&slots.done, FutexWakeCount::ALL, FutexScope::Shared);
        // Retour → trampoline `clone_thread` → `SYS_exit`.
    }

    #[test]
    #[cfg_attr(miri, ignore = "clone3/futex non supportés par Miri")]
    fn set_tid_address_none_returns_caller_tid() {
        use crate::futex::futex_wait;
        use crate::mem::mmap_anonymous;
        use air_sys_types::FutexScope;
        use air_sys_types::mem::{MapFlags, ProtectionFlags};
        use core::sync::atomic::{AtomicI32, AtomicU32, Ordering};
        use core::time::Duration;

        // Test SOUND du chemin `None` : on prouve que `set_tid_address(None)`
        // rend le TID de l'appelant **sur un thread possédé par Air**
        // (`clone_thread`, couche 0), **sans pthread glibc**. L'ancienne version
        // spawnait un `std::thread` détaché et y appelait `set_tid_address(None)`,
        // ce qui mettait à NULL le `clear_child_tid` que glibc utilise pour réaper
        // ses threads détachés — détournant le teardown glibc et pendant par
        // intermittence sous charge ARM (cohabitation Air/glibc unsound, même
        // classe de bug que le frère `_some`). Ici aucun `CHILD_CLEARTID` n'est
        // enregistré (pas de conflit), et l'attente parent est **bornée** par une
        // deadline (échec rapide et diagnostique, jamais un hang de 30 min).

        // `None` ne fournit AUCUN mot kernel de fin de thread : l'enfant publie
        // lui-même `tid` + `done` dans des emplacements `'static` partagés
        // (`Box::leak`, jamais libérés ⇒ le kernel/enfant peut y écrire sans
        // risque d'UAF), et le parent attend `done` via un `futex_wait` borné.
        let slots: &'static SetTidNoneSlots = Box::leak(Box::new(SetTidNoneSlots {
            tid: AtomicI32::new(0),
            done: AtomicU32::new(0),
        }));
        let slots_ptr = core::ptr::from_ref(slots) as usize;

        // Pile dédiée du thread : 64 KiB, page-alignée (mmap) ⇒ sommet aligné 16.
        const STACK_SIZE: usize = 64 * 1024;
        let mut stack = mmap_anonymous(
            STACK_SIZE,
            ProtectionFlags::READ | ProtectionFlags::WRITE,
            MapFlags::PRIVATE | MapFlags::STACK,
        )
        .expect("mmap pile thread");
        let stack_ptr = stack.as_mut_ptr();

        // PAS de `CHILD_CLEARTID`/`PARENT_SETTID` : on n'enregistre aucun mot de
        // join kernel (il entrerait en conflit avec le `set_tid_address(None)` du
        // child).
        let flags = CloneFlags::VM
            | CloneFlags::FS
            | CloneFlags::FILES
            | CloneFlags::SIGHAND
            | CloneFlags::THREAD
            | CloneFlags::SYSVSEM;

        let args = CloneArgs {
            flags,
            // CLONE_THREAD interdit tout signal de sortie.
            exit_signal: None,
            stack: Some(StackSpecification {
                addr: stack_ptr,
                size: STACK_SIZE,
            }),
            child_tid: None,
            parent_tid: None,
            tls: None,
        };

        // SAFETY: pile dédiée valide et **jamais libérée** (voir le `forget`
        // ci-dessous) → vivante au-delà de la durée de vie du thread ;
        // `set_tid_address_none_entry` n'utilise ni TLS ni alloc et n'opère que
        // sur `slots` (`'static`, partagé via la VM commune) ; aucun mot de join
        // kernel n'est enregistré.
        let child_tid = unsafe { clone_thread(&args, set_tid_address_none_entry, slots_ptr) }
            .expect("clone_thread doit réussir");
        assert!(child_tid.as_raw() > 0, "TID enfant strictement positif");

        // Fuite **délibérée** de la pile : `set_tid_address(None)` ne laisse aucun
        // mot kernel pour savoir quand le thread a fini d'utiliser sa pile (le
        // trampoline s'exécute encore dessus juste avant `SYS_exit`) → la libérer
        // serait un UAF. `forget` neutralise le `Drop` (munmap) de `Mapping` :
        // la région reste mappée à vie. Le leak de pile (test-only) est la
        // discipline déjà retenue pour ce motif (cf. frère `_some`).
        core::mem::forget(stack);

        // Attente **bornée** de la publication : `futex_wait` borné à 100 ms ; la
        // deadline absolue (50 réveils ⇒ ≤ 5 s) garantit un échec **rapide**
        // plutôt qu'un hang. Le child fait `store(done, 1)` + `futex_wake` ; un
        // réveil manqué est rattrapé par le re-poll après timeout — la boucle
        // converge dans tous les cas.
        const MAX_WAITS: u32 = 50; // 50 × 100 ms = 5 s de borne.
        let mut waits = 0_u32;
        while slots.done.load(Ordering::Acquire) == 0 {
            let _ = futex_wait(
                &slots.done,
                0,
                Some(Duration::from_millis(100)),
                FutexScope::Shared,
            );
            waits = waits.saturating_add(1);
            assert!(
                waits < MAX_WAITS,
                "l'enfant doit publier son TID via set_tid_address(None) \
                 (deadline {MAX_WAITS} × 100 ms expirée — publication non observée)"
            );
        }

        // `set_tid_address(None)` rend le TID de l'appelant (le thread enfant) :
        // c'est exactement le TID rendu par `clone_thread` au parent.
        let observed = slots.tid.load(Ordering::Acquire);
        assert!(
            observed > 0,
            "set_tid_address(None) rend le TID appelant (> 0)"
        );
        assert_eq!(
            observed,
            child_tid.as_raw(),
            "le TID rendu par set_tid_address(None) doit être celui du thread enfant"
        );
    }

    /// Point d'entrée du thread de test pour le chemin `Some` de
    /// [`set_tid_address`] : interprète `arg` comme l'adresse d'un `AtomicU32`
    /// `'static` partagé (VM commune via `CLONE_VM`), y **enregistre**
    /// `clear_child_tid`, puis **retourne** — le trampoline [`clone_thread`]
    /// termine alors le thread (`SYS_exit`) et le kernel remet le mot à `0` +
    /// `FUTEX_WAKE`.
    ///
    /// **Discipline côté enfant** : async-signal-safe, **zéro glibc** — un seul
    /// syscall (`set_tid_address`), aucun accès TLS, aucune allocation.
    extern "C" fn set_tid_address_some_entry(arg: usize) {
        // SAFETY (test) : `arg` est l'adresse d'un `AtomicU32` `'static`
        // (`Box::leak`, jamais libéré) fourni par le parent et partagé via la VM
        // commune. Alignement et validité garantis par le site d'appel.
        let slot = unsafe { &*(arg as *const core::sync::atomic::AtomicU32) };
        // SAFETY: `slot` est `'static` : le kernel pourra y écrire `0` à la mort
        // du thread sans risque d'usage-après-libération (contrat de
        // `set_tid_address`). Aucun mot de join kernel (`CHILD_CLEARTID`) n'a été
        // enregistré pour ce thread → pas de conflit avec ce `clear_child_tid`.
        let _ = unsafe { set_tid_address(Some(slot)) };
        // Retour → trampoline `clone_thread` → `SYS_exit` → clear + FUTEX_WAKE.
    }

    #[test]
    #[cfg_attr(miri, ignore = "clone3/futex non supportés par Miri")]
    fn set_tid_address_some_is_cleared_by_kernel_on_thread_exit() {
        use crate::futex::futex_wait;
        use crate::mem::{mmap_anonymous, munmap};
        use air_sys_types::FutexScope;
        use air_sys_types::mem::{MapFlags, ProtectionFlags};
        use core::sync::atomic::{AtomicU32, Ordering};
        use core::time::Duration;

        // Test SOUND du chemin `Some` : on prouve la sémantique kernel
        // (`set_tid_address(Some(ptr))` ⇒ le kernel remet `ptr` à 0 +
        // `FUTEX_WAKE` à la sortie du thread) **sans pthread glibc**. L'ancienne
        // version spawnait un `std::thread` détaché et écrasait son
        // `clear_child_tid` — celui que glibc utilise pour réaper ses threads
        // détachés —, ce qui détournait le teardown glibc et pendait par
        // intermittence sous charge ARM (cohabitation Air/glibc unsound). Ici le
        // thread est créé par `clone_thread` (couche 0), **sans** `CHILD_CLEARTID`
        // (aucun mot de join kernel concurrent), et l'attente parent est **bornée**
        // par une deadline (échec rapide et diagnostique, jamais un hang).

        // Pile dédiée du thread : 64 KiB, page-alignée (mmap) ⇒ sommet aligné 16.
        const STACK_SIZE: usize = 64 * 1024;
        let mut stack = mmap_anonymous(
            STACK_SIZE,
            ProtectionFlags::READ | ProtectionFlags::WRITE,
            MapFlags::PRIVATE | MapFlags::STACK,
        )
        .expect("mmap pile thread");

        // `slot` à adresse **stable** et durée de vie `'static` (`Box::leak`) :
        // l'enfant y enregistre `clear_child_tid` et le kernel y écrit `0` à la
        // mort du thread. Le leak (test-only) garantit qu'aucun chemin — y compris
        // une deadline expirée qui dépile par `panic!` — ne libère la mémoire
        // pendant que le kernel peut encore y écrire (pas d'UAF).
        let slot: &'static AtomicU32 = Box::leak(Box::new(AtomicU32::new(0xFFFF_FFFF)));
        let slot_ptr = core::ptr::from_ref(slot) as usize;

        // PAS de `CHILD_CLEARTID`/`PARENT_SETTID` : on n'enregistre aucun mot de
        // join kernel (il entrerait en conflit avec le `set_tid_address` du child).
        let flags = CloneFlags::VM
            | CloneFlags::FS
            | CloneFlags::FILES
            | CloneFlags::SIGHAND
            | CloneFlags::THREAD
            | CloneFlags::SYSVSEM;

        let args = CloneArgs {
            flags,
            // CLONE_THREAD interdit tout signal de sortie.
            exit_signal: None,
            stack: Some(StackSpecification {
                addr: stack.as_mut_ptr(),
                size: STACK_SIZE,
            }),
            child_tid: None,
            parent_tid: None,
            tls: None,
        };

        // SAFETY: pile dédiée valide (libérée seulement après la mort du thread) ;
        // `set_tid_address_some_entry` n'utilise ni TLS ni alloc et n'opère que sur
        // `slot` (`'static`, partagé via la VM commune) ; aucun mot de join kernel
        // n'est enregistré.
        let tid = unsafe { clone_thread(&args, set_tid_address_some_entry, slot_ptr) }
            .expect("clone_thread doit réussir");
        assert!(tid.as_raw() > 0, "TID enfant strictement positif");

        // Attente **bornée** : le kernel remet `slot` à 0 (+ `FUTEX_WAKE`) à la
        // mort du thread. `futex_wait` est borné par 100 ms ; la deadline absolue
        // (50 réveils ⇒ ≤ 5 s) garantit un échec **rapide** plutôt qu'un hang de
        // 30 min. Si la portée du futex différait, le timeout fait re-poller le
        // mot — le kernel écrit toujours 0, donc la boucle converge.
        const MAX_WAITS: u32 = 50; // 50 × 100 ms = 5 s de borne.
        let mut waits = 0_u32;
        loop {
            let v = slot.load(Ordering::Acquire);
            if v == 0 {
                break;
            }
            let _ = futex_wait(
                slot,
                v,
                Some(Duration::from_millis(100)),
                FutexScope::Shared,
            );
            waits = waits.saturating_add(1);
            assert!(
                waits < MAX_WAITS,
                "clear_child_tid doit être remis à 0 à la sortie du thread \
                 (deadline {MAX_WAITS} × 100 ms expirée — sémantique kernel \
                 `set_tid_address(Some)` non observée)"
            );
        }

        // Le mot a été remis à 0 ⇒ le thread est mort : la pile n'est plus
        // utilisée, on peut la libérer sans UAF.
        munmap(stack).expect("munmap pile thread");
    }
}