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_CAPBSET_READ: i32 = 23;
const PR_CAPBSET_DROP: i32 = 24;
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)
}

/// Teste si `cap` est présente dans le **bounding set** du processus
/// (`prctl(PR_CAPBSET_READ)`). Non destructif.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `cap` n'est pas une capability reconnue du kernel.
pub fn capbset_read(cap: Capability) -> Result<bool, Errno> {
    // SAFETY: PR_CAPBSET_READ — pas d'accès mémoire utilisateur ; résultat (0/1)
    // rendu comme code de retour.
    let ret = unsafe { raw_syscall_prctl(PR_CAPBSET_READ, u64::from(cap.as_raw()), 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(ret != 0)
}

/// Retire `cap` du **bounding set** du processus (`prctl(PR_CAPBSET_DROP)`).
///
/// **Irréversible** : une capability retirée du bounding set ne peut plus jamais être
/// ajoutée à l'ensemble *permitted* d'un descendant, **même** par un processus root.
/// Durcissement de moindre autorité du monitor (ADR-122 §6) : après avoir réduit ses
/// ensembles à la cible, le monitor largue du bounding set tout ce qu'il n'utilisera
/// jamais, se privant définitivement de la capacité de le regagner.
///
/// # Errors
///
/// - [`Errno::EPERM`] : l'appelant n'a pas `CAP_SETPCAP`.
/// - [`Errno::EINVAL`] : `cap` n'est pas une capability reconnue du kernel.
pub fn capbset_drop(cap: Capability) -> Result<(), Errno> {
    // SAFETY: PR_CAPBSET_DROP — pas d'accès mémoire utilisateur ; arg2 = numéro de cap.
    let ret = unsafe { raw_syscall_prctl(PR_CAPBSET_DROP, u64::from(cap.as_raw()), 0, 0, 0) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

#[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
}

// ─────────────────────────────────────────────────────────────────────────
// `unshare` — une seule opération, dédiée ([ADR-186] D2, [ADR-021] §3).
//
// `unshare(2)` multiplexe des usages sans rapport entre eux : espaces de noms, table
// des descripteurs, attributs `fs`… Aucun `unshare(flags)` générique n'est exposé.
// Seule l'opération qui **interroge le noyau sur le groupe de fils** l'est ; toute
// autre viendra, le cas échéant, avec sa propre fonction et sa propre raison.
//
// [ADR-186]: ../../../docs/adrs/ADR-186-fil-unique-avant-fork-verifie-par-le-noyau-fr.md
// [ADR-021]: ../../../docs/adrs/ADR-021-conventions-couche-0-fr.md
// ─────────────────────────────────────────────────────────────────────────

/// `CLONE_THREAD` (`linux/sched.h`).
const CLONE_THREAD: u64 = 0x0001_0000;

/// Demande au **noyau** si le processus appelant est **seul dans son groupe de fils** :
/// `unshare(CLONE_THREAD)` ([ADR-186] D1).
///
/// Quand l'appelant est seul, il n'y a rien à défaire : l'appel réussit et **ne change
/// rien**. Quand le groupe compte une autre tâche, le noyau refuse avec `EINVAL`
/// (`unshare(2)`, « *CLONE_THREAD … was specified in flags, and the caller is
/// multithreaded* »). C'est le noyau qui compte, sans lire aucun chemin : ni `/proc`,
/// ni Landlock n'interviennent.
///
/// **Ce que le noyau compte comme « une autre tâche »** — mesuré le 2026-09-26
/// (ADR-186 §1.3) :
/// - tout fil ordinaire vivant ;
/// - un fil de travail d'io_uring (`iou-wrk-…`), qui ne disparaît plus une fois créé,
///   même anneau fermé — alors qu'il n'exécute jamais de code utilisateur ;
/// - un fil qui vient de se terminer, un court instant après son `join`.
///
/// La réponse ne se trompe donc que dans un sens : elle peut dire « plusieurs » quand
/// aucun fil utilisateur ne vit, jamais « seul » quand il y en a un.
///
/// # Errors
///
/// - [`Errno::EINVAL`] : le groupe de fils compte au moins une autre tâche (voir
///   ci-dessus). C'est la réponse « non », pas une panne.
/// - Toute autre erreur est celle du noyau ou d'un filtre seccomp (par exemple un
///   filtre qui rend `EPERM`) : elle ne dit **rien** du nombre de fils.
///
/// [ADR-186]: ../../../docs/adrs/ADR-186-fil-unique-avant-fork-verifie-par-le-noyau-fr.md
pub fn unshare_thread_group() -> Result<(), Errno> {
    // SAFETY: `unshare(CLONE_THREAD)` ne lit ni n'écrit aucune mémoire utilisateur ; seul
    // l'entier `CLONE_THREAD` est transmis.
    let ret = unsafe { raw_syscall_unshare(CLONE_THREAD) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_unshare(flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_unshare (x86_64 = 272). Un seul argument entier, aucun pointeur :
    // pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 272_i64,
            in("rdi") flags,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_unshare(flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_unshare (aarch64 = 97). Mêmes considérations que x86_64.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 97_i64,
            inout("x0") flags => ret,
            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;

#[cfg(test)]
mod v1_7_runtime_libc_tests;