air_sys_syscall/io_uring/

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

//! Module `air-sys-syscall::io_uring` — façade typée d'io_uring (cible 6.12).
//!
//! Niveau d'abstraction 2 (ADR-022, Décision 1) : soumission/complétion typée.
//! Le niveau 1 (anneaux bruts) vivra dans [`raw`]. Les buffers suivent le
//! modèle de transfert d'ownership (ADR-022, Décision 3), garés dans un slab
//! pré-alloué (S1) ; le téardown est sûr par `Drop` quiescent +
//! [`IoUring::shutdown`] (S2).
//!
//! **Périmètre — Temps 1 (cœur).** Cycle de vie du ring (setup flags, mmaps SQ/
//! CQ/SQE, négociation des features), slab d'opérations en vol (S1), protocole
//! d'anneau acquire/release (§3.2 de la spec), soumission/complétion,
//! [`Completion`], téardown sûr (S2), introspection (probe + capabilities). Les
//! opérations métier `submit_*` (Temps 2a–2d) et les sous-modules
//! ([`shared`], [`multishot`], [`sandbox`], registration/provided/linked/cmd)
//! relèvent de PRs ultérieures.
//!
//! Référence normative : `docs/specs/layer-0/io-uring-1-core.md` (contrat) et
//! `docs/specs/layer-0/io-uring-0-inventaire.md` §7 (squelette).
//!
//! Les trois syscalls sous-jacents — `io_uring_setup` (425), `io_uring_enter`
//! (426), `io_uring_register` (427), numéros identiques x86_64/ARM64 — sont
//! appelés directement via `core::arch::asm!` (aucune dépendance externe).

use crate::mem::{Mapping, mmap_file};
use air_sys_types::Errno;
use air_sys_types::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
use air_sys_types::mem::{MapFlags, ProtectionFlags};
use alloc::boxed::Box;
use alloc::vec::Vec;
use core::marker::PhantomData;
use core::num::NonZeroU32;
use core::time::Duration;

pub mod multishot;
pub mod raw;
pub mod sandbox;
pub mod shared;

mod async_ops;
mod cmd;
mod fs_ops;
mod linked;
mod net_ops;
mod owned;
mod provided;
mod registration;
mod ring;
mod slab;
mod syscall;

use owned::OwnedOp;
use ring::{CompletionRing, SubmissionRing};
use slab::InflightSlab;

// Types de données purs (bitflags, opcodes) : définis dans `air-sys-types`,
// re-exportés ici pour offrir une façade `air_sys_syscall::io_uring::*` unique.
pub use air_sys_types::io_uring::{CompletionFlags, IoUringOpcode, SetupFlags, UringCmdFlags};

// Type d'attente `futex_waitv` (porte une `MmapRegion`) : défini avec ses
// façades dans `async_ops`, re-exporté sur la façade `io_uring`.
pub use async_ops::FutexWaiter;

// Trait des commandes passthrough `URING_CMD` (Temps 2d), défini avec ses
// façades dans `cmd`, re-exporté sur la façade `io_uring`.
pub use cmd::UringCommand;

// Surface du Temps 3a (registration : ressources fixes), définie dans
// `registration`, re-exportée sur la façade `io_uring`.
pub use registration::{
    ClockSource, FixedFdTable, FixedSlot, FixedSlotTarget, NapiConfig, Personality,
    RegisteredBufferSlice, RegisteredBuffers, WorkQueueWorkerLimits,
};

// Surface du Temps 3b (buffers fournis ring-mapped), définie dans `provided`,
// re-exportée sur la façade `io_uring`.
pub use provided::{
    ProvidedBuffer, ProvidedBufferRing, ProvidedBufferRingOptions, ProvidedBufferRingStatus,
};

// Surface du Temps 3c (opérations liées), définie dans `linked`, re-exportée sur
// la façade `io_uring`.
pub use linked::{ChainTokens, LinkedChainBuilder};

// Surface du Temps 3e (usage multi-thread), définie dans `shared`, re-exportée
// sur la façade `io_uring`.
pub use shared::{LockedIoUring, RingHandle, RingPool, SqpollIoUring};

// Surface du Temps 3f (confinement / sandbox), définie dans `sandbox`,
// re-exportée sur la façade `io_uring`.
pub use sandbox::{RegisterOp, RestrictionSet, SqeFlagSet};

// Surface du Temps 4 (accès brut niveau 1), définie dans `raw`, re-exportée sur
// la façade `io_uring`. `raw` reste par ailleurs le module des miroirs ABI.
pub use raw::{RAW_USER_DATA_TAG, RawCompletionQueueEntry, RawOpcode, RawSubmissionQueueEntry};

// ---------------------------------------------------------------------------
// Construction & cycle de vie
// ---------------------------------------------------------------------------

/// Anneau io_uring : FD + mmaps (SQ/CQ/SQE) + slab d'opérations en vol (S1) +
/// capabilities négociées.
///
/// `Send` mais **pas** `Sync` (ADR-022, Décision 6) : un reactor par thread.
/// Pour le multi-thread, voir [`shared`]. L'invariant de sûreté (S1/S2) : tant
/// qu'une opération est en vol, son buffer vit dans le slot du slab et le ring
/// ne peut être détruit sans quiescence — aucune écriture kernel ne tombe sur
/// de la mémoire libérée.
pub struct IoUring {
    /// FD du ring. `Option` pour la **discipline de téardown** : libéré (close)
    /// après quiescence, ou *fuité* (`forget`) si la quiescence échoue.
    fd: Option<OwnedFd>,
    /// Mmap de l'anneau SQ (et de la CQ si `SINGLE_MMAP`). `Option` : voir `fd`.
    sq_ring_map: Option<Mapping>,
    /// Mmap du tableau de SQE. `Option` : voir `fd`.
    sqes_map: Option<Mapping>,
    /// Mmap de l'anneau CQ, ou `None` si partagée avec `sq_ring_map`
    /// (`IORING_FEAT_SINGLE_MMAP`, toujours présent en 6.12).
    cq_ring_map: Option<Mapping>,
    /// Pointeurs/cache de l'anneau de soumission (dans `sq_ring_map`).
    sq: SubmissionRing,
    /// Pointeurs/cache de l'anneau de complétion.
    cq: CompletionRing,
    /// Slab d'opérations en vol (S1).
    slab: InflightSlab,
    /// Features négociées au setup (axe G).
    capabilities: IoUringCapabilities,
    /// Opcodes supportés par le kernel courant, indexés par numéro `IORING_OP_*`
    /// (mis en cache à la construction via `IORING_REGISTER_PROBE`, §9).
    supported_ops: [bool; 256],
    /// Options appliquées à la prochaine soumission ([`IoUring::with`]).
    pending_options: SubmitOptions,
    /// Personality appliquée à la prochaine soumission ([`IoUring::with_personality`]) :
    /// `0` = credentials du process (aucune personality). Posée dans
    /// `sqe.personality` puis remise à `0` (Temps 3a, registration §6).
    pending_personality: u16,
    /// Index du ring fd enregistré ([`IoUring::register_ring_fd`], Temps 3a §4),
    /// ou `None`. Quand présent, les `io_uring_enter` suivants l'utilisent avec
    /// `IORING_ENTER_REGISTERED_RING` (pas de résolution de FD).
    enter_ring_index: Option<u32>,
    /// `true` une fois le téardown effectué (par `shutdown` ou un `Drop`
    /// précédent) : empêche toute double libération (reminder S2).
    disposed: bool,
    /// Indices (`tail`) des SQE préparés via [`IoUring::raw_get_submission_queue_entry`]
    /// (Temps 4) depuis la dernière soumission, pour la **vérification debug** du
    /// tag `user_data` (§5). Vide tant que l'accès brut n'est pas utilisé (aucune
    /// allocation sur le happy path niveau 2) ; purgé à chaque `submit`.
    raw_pending: Vec<u32>,
    /// Marqueur `Send + !Sync` : `Cell<()>` est `Send` mais pas `Sync`, ce qui
    /// impose le « un reactor par thread » de la Décision 6 sans verrou.
    _not_sync: PhantomData<core::cell::Cell<()>>,
}

// SAFETY: `IoUring` est **`Send`** (ADR-022 Décision 6) : il peut être *déplacé*
// d'un thread à l'autre. Ses pointeurs bruts (`SubmissionRing`/`CompletionRing`)
// désignent des zones **mmappées** valides pour toute la durée de vie du ring
// (process-global, indépendantes du thread) ; le FD est process-global ; le slab
// S1 et les payloads possédés (`OwnedFd`/`Vec`/`Box`) sont tous `Send`. Déplacer
// le ring **transfère l'ownership exclusif** — `Send` concerne le transfert, pas
// le partage. Le partage concurrent (`Sync`) reste **interdit** : `_not_sync`
// (`PhantomData<Cell<()>>`) garde `IoUring: !Sync`, car le protocole d'ordering
// du Temps 1 ne synchronise pas userspace↔userspace (cf. `shared` §1). Un seul
// thread accède donc au ring à un instant donné (Send + !Sync = thread-per-core).
unsafe impl Send for IoUring {}

/// Construit un [`IoUring`] : applique setup flags et restrictions (S3) avant
/// l'activation, puis `io_uring_setup(2)`.
pub struct IoUringBuilder {
    entries: NonZeroU32,
    cq_entries: Option<NonZeroU32>,
    max_inflight: Option<NonZeroU32>,
    flags: SetupFlags,
    sqpoll_idle: Option<Duration>,
    sqpoll_cpu: Option<u32>,
    attach_wq_fd: Option<i32>,
    restrictions: Vec<Restriction>,
}

impl IoUringBuilder {
    /// Démarre un builder pour `entries` SQE (arrondi par le kernel à la
    /// puissance de 2 supérieure).
    #[must_use]
    pub fn new(entries: NonZeroU32) -> Self {
        Self {
            entries,
            cq_entries: None,
            max_inflight: None,
            flags: SetupFlags::empty(),
            sqpoll_idle: None,
            sqpoll_cpu: None,
            attach_wq_fd: None,
            restrictions: Vec::new(),
        }
    }

    /// Fixe explicitement la profondeur de la CQ (`IORING_SETUP_CQSIZE`).
    #[must_use]
    pub fn with_completion_queue_entries(mut self, entries: NonZeroU32) -> Self {
        self.cq_entries = Some(entries);
        self
    }

    /// Capacité du slab d'opérations en vol (S1). Défaut : `cq_entries`.
    #[must_use]
    pub fn max_inflight(mut self, n: NonZeroU32) -> Self {
        self.max_inflight = Some(n);
        self
    }

    /// Active des flags de setup (cf. [`SetupFlags`]).
    #[must_use]
    pub fn with_flags(mut self, flags: SetupFlags) -> Self {
        self.flags |= flags;
        self
    }

    /// Durée d'inactivité avant que le thread `SQPOLL` ne s'endorme
    /// (`SETUP_SQPOLL`, Temps 3e).
    #[must_use]
    pub fn with_sqpoll_idle(mut self, idle: Duration) -> Self {
        self.sqpoll_idle = Some(idle);
        self
    }

    /// Épingle le thread `SQPOLL` sur un CPU (`SETUP_SQ_AFF`).
    #[must_use]
    pub fn with_sqpoll_cpu(mut self, cpu: u32) -> Self {
        self.sqpoll_cpu = Some(cpu);
        self
    }

    /// Partage le pool io-wq d'un ring existant (`SETUP_ATTACH_WQ`).
    #[must_use]
    pub fn attach_work_queue(mut self, other: &IoUring) -> Self {
        self.attach_wq_fd = Some(other.fd_raw());
        self
    }

    /// Crée le ring désactivé (`R_DISABLED`) et applique des restrictions (S3,
    /// Temps 3f). Doit être suivi de [`IoUring::enable`].
    #[must_use]
    pub fn restrict(mut self, restrictions: &[Restriction]) -> Self {
        self.restrictions = restrictions.to_vec();
        self
    }

    /// Finalise : traduit la config en `io_uring_params`, appelle
    /// `io_uring_setup(2)`, mmappe les anneaux (§3.1), alloue le slab (§4) et
    /// lit les features. Si `restrict` a été utilisé, le ring est créé
    /// désactivé et doit être activé via [`IoUring::enable`].
    ///
    /// # Errors
    ///
    /// - [`Errno::EINVAL`] : paramètres ou combinaison de flags invalides
    ///   (remontés tels quels, sans masquage).
    /// - [`Errno::ENOMEM`] : mémoire insuffisante pour les anneaux/le slab.
    /// - [`Errno::EPERM`] : `SQPOLL`/affinité sans privilège selon la config.
    /// - [`Errno::EFAULT`] : pointeur de paramètres invalide.
    /// - [`Errno::ENOSYS`] : io_uring indisponible (kernel ancien, sandbox,
    ///   container durci) — **pas** de fallback caché (cf. ADR-022 D10).
    pub fn build(self) -> Result<IoUring, Errno> {
        let mut params = raw::IoUringParams {
            flags: self.flags.bits(),
            ..raw::IoUringParams::default()
        };
        if let Some(cq) = self.cq_entries {
            params.flags |= raw::IORING_SETUP_CQSIZE;
            params.cq_entries = cq.get();
        }
        if let Some(idle) = self.sqpoll_idle {
            params.sq_thread_idle = u32::try_from(idle.as_millis()).unwrap_or(u32::MAX);
        }
        if let Some(cpu) = self.sqpoll_cpu {
            params.sq_thread_cpu = cpu;
        }
        if let Some(wq_fd) = self.attach_wq_fd {
            params.flags |= raw::IORING_SETUP_ATTACH_WQ;
            params.wq_fd = u32::from_ne_bytes(wq_fd.to_ne_bytes());
        }
        if !self.restrictions.is_empty() {
            params.flags |= SetupFlags::R_DISABLED.bits();
        }

        let params_ptr = core::ptr::from_mut(&mut params) as u64;
        // SAFETY: `params_ptr` pointe une `IoUringParams` valide en lecture/
        // écriture pour la durée de l'appel ; `entries` est un scalaire.
        let ret = unsafe { syscall::setup(self.entries.get(), params_ptr) };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        let raw_fd = i32::try_from(ret).map_err(|_| Errno::EINVAL)?;
        // SAFETY: `io_uring_setup` a retourné un FD frais possédé.
        let fd = unsafe { OwnedFd::from_raw_fd(raw_fd) };

        if !self.restrictions.is_empty() {
            // Ring créé `R_DISABLED` ci-dessus : applique la liste blanche S3
            // (`REGISTER_RESTRICTIONS`, Temps 3f, sous-module `sandbox`) **tant
            // qu'il est désactivé** (le kernel refuse sinon). En cas d'échec, `fd`
            // (OwnedFd local) se ferme proprement au retour — aucune fuite. Le
            // ring reste désactivé : l'appelant l'active via `IoUring::enable`,
            // après quoi les restrictions sont **immuables** (imposé kernel).
            apply_restrictions(&fd, &self.restrictions)?;
        }

        let mappings = map_rings(&fd, &params, self.flags)?;
        let slab_capacity = self.max_inflight.map_or(params.cq_entries, NonZeroU32::get);
        let slab_capacity = NonZeroU32::new(slab_capacity).ok_or(Errno::EINVAL)?;
        let supported_ops = probe_supported_ops(fd.as_raw_fd());

        Ok(IoUring {
            fd: Some(fd),
            sq_ring_map: Some(mappings.sq_ring),
            sqes_map: Some(mappings.sqes),
            cq_ring_map: mappings.cq_ring,
            sq: mappings.sq,
            cq: mappings.cq,
            slab: InflightSlab::with_capacity(slab_capacity),
            capabilities: IoUringCapabilities {
                features: params.features,
            },
            supported_ops,
            pending_options: SubmitOptions::default(),
            pending_personality: 0,
            enter_ring_index: None,
            disposed: false,
            raw_pending: Vec::new(),
            _not_sync: PhantomData,
        })
    }
}

/// Mappings et holders d'anneaux résultant de la construction.
struct RingMappings {
    sq_ring: Mapping,
    sqes: Mapping,
    cq_ring: Option<Mapping>,
    sq: SubmissionRing,
    cq: CompletionRing,
}

/// mmappe les trois zones (§3.1) et construit les holders de pointeurs.
/// Tailles de mmap des trois zones, dérivées des `params` retournés par le
/// kernel. **Décode PUR** (aucun syscall) — frontière de décode de données
/// externes (Principe 3), fuzzée via [`fuzz_api`]. Arithmétique **checked** :
/// toute donnée kernel incohérente (offsets/entrées énormes) ⇒ `EINVAL`, jamais
/// d'overflow ni de panic.
struct RingSizes {
    single_mmap: bool,
    sq_map: usize,
    cq_map: usize,
    sqes: usize,
    /// Taille d'un SQE en octets (64, ou 128 si `SETUP_SQE128`).
    sqe_size: usize,
}

fn ring_sizes(params: &raw::IoUringParams, flags: SetupFlags) -> Result<RingSizes, Errno> {
    let single_mmap = params.features & raw::IORING_FEAT_SINGLE_MMAP != 0;
    let sqe_size: usize = if flags.contains(SetupFlags::SQE128) {
        128
    } else {
        64
    };
    let cqe_size: usize = if flags.contains(SetupFlags::CQE32) {
        32
    } else {
        16
    };

    let sq_entries = usize_of(params.sq_entries);
    let cq_entries = usize_of(params.cq_entries);
    let sq_ring_sz = usize_of(params.sq_off.array)
        .checked_add(sq_entries.checked_mul(4).ok_or(Errno::EINVAL)?)
        .ok_or(Errno::EINVAL)?;
    let cq_ring_sz = usize_of(params.cq_off.cqes)
        .checked_add(cq_entries.checked_mul(cqe_size).ok_or(Errno::EINVAL)?)
        .ok_or(Errno::EINVAL)?;
    let sqes = sq_entries.checked_mul(sqe_size).ok_or(Errno::EINVAL)?;

    let (sq_map, cq_map) = if single_mmap {
        let m = sq_ring_sz.max(cq_ring_sz);
        (m, m)
    } else {
        (sq_ring_sz, cq_ring_sz)
    };
    Ok(RingSizes {
        single_mmap,
        sq_map,
        cq_map,
        sqes,
        sqe_size,
    })
}

fn map_rings(
    fd: &OwnedFd,
    params: &raw::IoUringParams,
    flags: SetupFlags,
) -> Result<RingMappings, Errno> {
    let sizes = ring_sizes(params, flags)?;
    let single_mmap = sizes.single_mmap;

    let prot = ProtectionFlags::READ | ProtectionFlags::WRITE;
    let map = MapFlags::SHARED | MapFlags::POPULATE;

    let mut sq_ring = mmap_file(fd.as_fd(), sizes.sq_map, raw::IORING_OFF_SQ_RING, prot, map)?;
    let mut cq_ring = if single_mmap {
        None
    } else {
        Some(mmap_file(
            fd.as_fd(),
            sizes.cq_map,
            raw::IORING_OFF_CQ_RING,
            prot,
            map,
        )?)
    };
    let mut sqes = mmap_file(fd.as_fd(), sizes.sqes, raw::IORING_OFF_SQES, prot, map)?;

    let sq_base = sq_ring.as_mut_ptr();
    let cq_base = cq_ring.as_mut().map_or(sq_base, Mapping::as_mut_ptr);
    let sqes_base = sqes.as_mut_ptr();
    let sq_mask = params.sq_entries.wrapping_sub(1);
    let cq_mask = params.cq_entries.wrapping_sub(1);

    // SAFETY: les trois bases pointent des mmaps fraîches dimensionnées selon
    // les offsets kernel de `params` ; elles vivent dans l'`IoUring` (RAII) au
    // moins aussi longtemps que les holders qui en dérivent les pointeurs.
    let sq = unsafe {
        SubmissionRing::new(
            sq_base,
            sqes_base,
            sizes.sqe_size,
            &params.sq_off,
            sq_mask,
            params.sq_entries,
        )
    };
    // SAFETY: idem pour l'anneau CQ (zone propre ou partagée si SINGLE_MMAP).
    let cq = unsafe { CompletionRing::new(cq_base, &params.cq_off, cq_mask) };

    Ok(RingMappings {
        sq_ring,
        sqes,
        cq_ring,
        sq,
        cq,
    })
}

/// `u32` → `usize` (toujours valide sur cible LP64).
fn usize_of(v: u32) -> usize {
    usize::try_from(v).expect("usize ≥ u32 sur cible LP64")
}

/// Encode les [`Restriction`] en `struct io_uring_restriction` et les applique
/// via `IORING_REGISTER_RESTRICTIONS` (S3, Temps 3f, sous-module [`sandbox`]).
/// À n'appeler **que** sur un ring `R_DISABLED` (avant [`IoUring::enable`]) — le
/// kernel refuse autrement. **Default-deny** : dès qu'un opcode est mis en liste
/// blanche, le kernel refuse tout le reste (`-EACCES`).
fn apply_restrictions(fd: &OwnedFd, restrictions: &[Restriction]) -> Result<(), Errno> {
    let encoded: Vec<raw::IoUringRestriction> = restrictions
        .iter()
        .copied()
        .map(encode_restriction)
        .collect();
    let nr_args = u32::try_from(encoded.len()).map_err(|_| Errno::EINVAL)?;
    let arg = encoded.as_ptr() as u64;
    // SAFETY: `arg` pointe un tableau de `nr_args` `io_uring_restriction` valides,
    // vivants pour la durée de l'appel ; `fd` est un ring fd `R_DISABLED` possédé.
    // `REGISTER_RESTRICTIONS` lit l'argument sans le réécrire.
    let ret = unsafe {
        syscall::register(
            fd.as_raw_fd(),
            raw::IORING_REGISTER_RESTRICTIONS,
            arg,
            nr_args,
        )
    };
    if ret < 0 {
        return Err(raw::errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Traduit une [`Restriction`] en son `struct io_uring_restriction` : un opcode
/// de **type** de restriction + un `u8` selon ce type (numéro d'opcode de
/// soumission via [`opcode_number`], numéro de register-op, ou octet `IOSQE_*`).
fn encode_restriction(restriction: Restriction) -> raw::IoUringRestriction {
    let mut out = raw::IoUringRestriction::default();
    match restriction {
        Restriction::AllowOp(op) => {
            out.opcode = raw::IORING_RESTRICTION_SQE_OP;
            out.op_or_flags = opcode_number(op);
        }
        Restriction::AllowRegister(register_op) => {
            out.opcode = raw::IORING_RESTRICTION_REGISTER_OP;
            out.op_or_flags = register_op;
        }
        Restriction::SqeFlagsAllowed(options) => {
            out.opcode = raw::IORING_RESTRICTION_SQE_FLAGS_ALLOWED;
            out.op_or_flags = options.iosqe_flags();
        }
        Restriction::SqeFlagsRequired(options) => {
            out.opcode = raw::IORING_RESTRICTION_SQE_FLAGS_REQUIRED;
            out.op_or_flags = options.iosqe_flags();
        }
    }
    out
}

impl IoUring {
    /// Raccourci : `IoUringBuilder::new(entries).build()`.
    ///
    /// # Errors
    ///
    /// Voir [`IoUringBuilder::build`].
    pub fn new(entries: NonZeroU32) -> Result<Self, Errno> {
        IoUringBuilder::new(entries).build()
    }

    /// Active un ring créé avec `R_DISABLED` (`REGISTER_ENABLE_RINGS`).
    ///
    /// Inutile sur un ring déjà actif : retourne alors l'`EINVAL` du kernel.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINVAL`] : ring déjà actif (remonté tel quel).
    /// - [`Errno::EBADF`] : FD de ring invalide.
    pub fn enable(&mut self) -> Result<(), Errno> {
        // SAFETY: `fd` est un ring fd valide possédé ; `ENABLE_RINGS` ne lit
        // aucune mémoire utilisateur (arg/nr_args nuls).
        let ret =
            unsafe { syscall::register(self.fd_raw(), raw::IORING_REGISTER_ENABLE_RINGS, 0, 0) };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }

    /// Vrai si la CQ a débordé (`IORING_SQ_CQ_OVERFLOW`). Avec `FEAT_NODROP`
    /// (présent en 6.12) le kernel retient les complétions et les re-livre.
    #[must_use]
    pub fn completion_queue_overflowed(&self) -> bool {
        self.sq.flags() & raw::IORING_SQ_CQ_OVERFLOW != 0
    }

    /// Nombre de places libres dans la SQ (calculé par `tail - head` masqué).
    #[must_use]
    pub fn submission_queue_space_left(&self) -> u32 {
        self.sq.space_left()
    }

    /// Nombre d'opérations actuellement en vol (slots occupés du slab S1).
    #[must_use]
    pub fn in_flight(&self) -> u32 {
        self.slab.in_flight()
    }

    /// Nombre de CQE bruts prêts dans la CQ (introspection de test — sert à
    /// observer un CQE injecté par `msg_ring` côté cible, que `harvest_ready`
    /// filtrerait comme périmé faute de slot correspondant).
    #[cfg(test)]
    pub(crate) fn cq_ready(&self) -> u32 {
        self.cq.ready()
    }

    /// FD numérique du ring (toujours présent avant le téardown). `pub(crate)` :
    /// le sous-module `registration` (Temps 3a) appelle `io_uring_register(2)`
    /// directement sur ce FD.
    pub(crate) fn fd_raw(&self) -> i32 {
        self.fd.as_ref().map_or(-1, AsRawFd::as_raw_fd)
    }

    /// Cible d'un `io_uring_enter` : `(fd, flags additionnels)`. Avec un ring fd
    /// enregistré (Temps 3a §4), l'`fd` est l'**index** enregistré et le flag
    /// `IORING_ENTER_REGISTERED_RING` est OR-é ; sinon le FD ordinaire, sans flag.
    fn enter_target(&self) -> (i32, u32) {
        match self.enter_ring_index {
            // L'index est petit (table de rings enregistrés) ⇒ tient dans un i32.
            Some(index) => (index.cast_signed(), raw::IORING_ENTER_REGISTERED_RING),
            None => (self.fd_raw(), 0),
        }
    }

    /// Téardown propre (S2) : annule les ops en vol ([`IoUring::sync_cancel`]
    /// `Any`), draine la CQ jusqu'à `in_flight() == 0`, `munmap` les anneaux et
    /// ferme le FD. À préférer au `drop` implicite sur chemin chaud.
    ///
    /// # Errors
    ///
    /// Propage les erreurs de drainage/annulation (l'appelant décide de la
    /// suite) ; voir [`IoUring::sync_cancel`].
    pub fn shutdown(mut self) -> Result<(), Errno> {
        let result = self.do_teardown();
        // `do_teardown` a posé `disposed = true` et libéré/fuité les ressources.
        // À la sortie, `self` est dropé → `Drop` voit `disposed` et ne refait
        // **rien** (pas de double munmap/close/free — reminder S2 #3).
        result
    }

    /// Quiescence + libération **ou fuite contrôlée** des ressources (idempotent
    /// via `disposed`). Cœur de la décision S2 : on ne libère la mémoire que si
    /// le kernel ne peut plus y écrire (`in_flight == 0`).
    fn do_teardown(&mut self) -> Result<(), Errno> {
        if self.disposed {
            return Ok(());
        }
        self.disposed = true;
        if self.quiesce() {
            // RELEASE (sound : in_flight == 0, le kernel n'écrit plus) : munmap
            // des 3 zones, close du fd, par RAII. Ordre : mmaps puis fd.
            drop(self.sq_ring_map.take());
            drop(self.sqes_map.take());
            drop(self.cq_ring_map.take());
            drop(self.fd.take());
            Ok(())
        } else {
            // FUITE CONTRÔLÉE (Principe 5, reminder S2 #1) : la quiescence a
            // échoué (op non annulable / timeout) — le kernel peut encore écrire
            // dans les anneaux mmap et les buffers en vol. On ne libère RIEN
            // (forget) : une fuite bornée à ce ring est sound, un UAF jamais.
            leak_forget(self.sq_ring_map.take());
            leak_forget(self.sqes_map.take());
            leak_forget(self.cq_ring_map.take());
            leak_forget(self.fd.take());
            self.slab.leak_inflight_buffers();
            Err(Errno::EBUSY)
        }
    }

    /// Amène le ring à `in_flight == 0` : annule (best-effort) puis draine les
    /// complétions (y compris `-ECANCELED`, déroulement **nominal**, reminder
    /// S2 #2). Borné en temps. Retourne `true` si quiescent.
    fn quiesce(&mut self) -> bool {
        if self.slab.in_flight() == 0 {
            return true;
        }
        // (a) Annulation globale (best-effort : ENOENT/ETIME ignorés).
        let _ = self.sync_cancel(CancelTarget::Any);
        // (b) Drainage borné jusqu'à in_flight == 0.
        const MAX_ROUNDS: u32 = 64;
        for _ in 0..MAX_ROUNDS {
            // Consomme tout ce qui est prêt (les CQE `-ECANCELED` libèrent leur
            // slot via `harvest_ready`, sans propager d'erreur).
            while self.harvest_ready().is_some() {}
            if self.slab.in_flight() == 0 {
                return true;
            }
            // Bloque (timeout borné) pour au moins une complétion supplémentaire.
            if self.wait_bounded().is_err() {
                // EINTR/ETIME : on retente quelques rounds avant d'abandonner.
            }
        }
        self.slab.in_flight() == 0
    }

    /// `io_uring_enter(GETEVENTS, min_complete = 1)` avec un timeout court borné
    /// (100 ms via `EXT_ARG`), pour le drainage de quiescence.
    fn wait_bounded(&self) -> Result<(), Errno> {
        let ts = raw::KernelTimespec {
            tv_sec: 0,
            tv_nsec: 100_000_000,
        };
        let arg = raw::IoUringGeteventsArg {
            sigmask: 0,
            sigmask_sz: 0,
            min_wait_usec: 0,
            ts: core::ptr::from_ref(&ts) as u64,
        };
        let arg_sz = u64::try_from(core::mem::size_of::<raw::IoUringGeteventsArg>())
            .expect("taille getevents_arg ≤ u64");
        let (efd, eflag) = self.enter_target();
        // SAFETY: `fd`/index valide ; `arg`/`ts` vivants pour la durée de l'appel.
        let ret = unsafe {
            syscall::enter(
                efd,
                0,
                1,
                raw::IORING_ENTER_GETEVENTS | raw::IORING_ENTER_EXT_ARG | eflag,
                core::ptr::from_ref(&arg) as u64,
                arg_sz,
            )
        };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }
}

/// Interroge `IORING_REGISTER_PROBE` et retourne, par numéro d'opcode, le
/// support du kernel courant (mis en cache par [`IoUringBuilder::build`], §9).
///
/// Best-effort : si le probe échoue (kernel ancien, sandbox/`R_DISABLED`), tous
/// les opcodes sont marqués **non supportés** — conservateur, force le fallback
/// synchrone (ADR-022 D8).
fn probe_supported_ops(fd: i32) -> [bool; 256] {
    let mut probe = Box::new(raw::IoUringProbe {
        last_op: 0,
        ops_len: 0,
        resv: 0,
        resv2: [0; 3],
        ops: [raw::IoUringProbeOp::default(); 256],
    });
    let probe_ptr = core::ptr::from_mut(&mut *probe) as u64;
    // SAFETY: `fd` ring valide ; `probe` pointe une `io_uring_probe` vivante,
    // dimensionnée pour `IO_URING_PROBE_OPS` entrées, écrite par le kernel.
    let ret = unsafe {
        syscall::register(
            fd,
            raw::IORING_REGISTER_PROBE,
            probe_ptr,
            raw::IO_URING_PROBE_OPS,
        )
    };
    let mut supported = [false; 256];
    if ret < 0 {
        return supported;
    }
    for (op, entry) in probe.ops.iter().enumerate() {
        supported[op] = entry.flags & raw::IO_URING_OP_SUPPORTED != 0;
    }
    supported
}

/// Fuite contrôlée d'une ressource RAII optionnelle (`forget` si présente).
fn leak_forget<T>(resource: Option<T>) {
    if let Some(value) = resource {
        core::mem::forget(value);
    }
}

impl Drop for IoUring {
    /// Filet de sécurité (S2) : si des ops sont en vol, quiesce (annule +
    /// draine, **bloquant et best-effort**, boucle bornée) avant de libérer la
    /// mémoire. Coût (blocage potentiel) **assumé et documenté** : sur chemin
    /// chaud, préférer [`IoUring::shutdown`]. Un `Drop` qui laisserait le kernel
    /// écrire dans de la mémoire libérée serait un défaut de soundness
    /// inacceptable en couche 0 (Principe 5 : sur-sécuriser puis dégraisser).
    fn drop(&mut self) {
        // Filet de sécurité S2 : quiesce (annule + draine, **bloquant**,
        // best-effort borné) puis libère — ou **fuite** de façon contrôlée si la
        // quiescence échoue (jamais d'UAF). No-op si `shutdown` a déjà disposé.
        let _ = self.do_teardown();
    }
}

// ---------------------------------------------------------------------------
// Soumission
// ---------------------------------------------------------------------------

impl IoUring {
    /// Soumet les SQE en attente (`io_uring_enter`, sans attente). Retourne le
    /// nombre de SQE consommés par le kernel.
    ///
    /// Publie la queue SQ par un **store release** (§3.2) avant l'`enter`. En
    /// mode `SQPOLL` chaud, peut n'avoir **aucun** syscall à faire (juste la
    /// publication), ne réveillant le thread que si `SQ_NEED_WAKEUP`.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINTR`] : remonté tel quel (ADR-021 conv. 2 ; l'appelant écrit
    ///   sa propre boucle de retry).
    /// - [`Errno::EAGAIN`] : ressources momentanément indisponibles.
    /// - [`Errno::EBUSY`] : CQ pleine non drainée (selon contexte).
    /// - [`Errno::EINVAL`], [`Errno::EFAULT`], [`Errno::EBADF`].
    pub fn submit(&mut self) -> Result<u32, Errno> {
        self.debug_assert_raw_tags();
        let to_submit = self.sq.publish_and_pending();
        if to_submit == 0 {
            return Ok(0);
        }
        let (efd, eflag) = self.enter_target();
        // SAFETY: `fd`/index est valide ; pas d'argument étendu.
        let ret = unsafe { syscall::enter(efd, to_submit, 0, eflag, 0, 0) };
        if ret < 0 {
            // EINTR/EAGAIN remontés tels quels (ADR-021 conv. 2 — aucun retry).
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        Ok(u32::try_from(ret).unwrap_or(0))
    }

    /// Soumet puis attend au moins `want` complétions
    /// (`IORING_ENTER_GETEVENTS`, `min_complete = want`).
    ///
    /// # Errors
    ///
    /// Mêmes erreurs que [`IoUring::submit`] ; [`Errno::EINTR`] remonté tel quel.
    pub fn submit_and_wait(&mut self, want: u32) -> Result<u32, Errno> {
        self.debug_assert_raw_tags();
        let to_submit = self.sq.publish_and_pending();
        let (efd, eflag) = self.enter_target();
        // SAFETY: `fd`/index est valide ; pas d'argument étendu.
        let ret = unsafe {
            syscall::enter(
                efd,
                to_submit,
                want,
                raw::IORING_ENTER_GETEVENTS | eflag,
                0,
                0,
            )
        };
        if ret < 0 {
            // EINTR remonté tel quel (ADR-021 conv. 2).
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        Ok(u32::try_from(ret).unwrap_or(0))
    }

    /// Applique des options par-opération ([`SubmitOptions`]) à la **prochaine**
    /// soumission `submit_*`. Style builder (chaînable).
    pub fn with(&mut self, opts: SubmitOptions) -> &mut Self {
        self.pending_options = opts;
        self
    }

    /// Exécute la **prochaine** soumission `submit_*` avec les credentials d'une
    /// [`Personality`] enregistrée (`sqe.personality`, Temps 3a §6). Consommée
    /// pour cette seule opération. Style builder (chaînable).
    pub fn with_personality(&mut self, personality: Personality) -> &mut Self {
        self.pending_personality = personality.raw();
        self
    }

    /// Prépare et met en file un `IORING_OP_NOP` — la première opération de
    /// validation du cœur. Réserve un slot S1, écrit le SQE, et retourne le
    /// jeton ; la soumission effective se fait par [`IoUring::submit`] /
    /// [`IoUring::submit_and_wait`].
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins (back-pressure
    /// structurelle, **aucun** syscall — §4.3).
    pub fn submit_nop(&mut self) -> Result<SubmissionToken, Errno> {
        if self.sq.space_left() == 0 {
            return Err(Errno::EBUSY);
        }
        let token = self.slab.reserve(None).map_err(|_| Errno::EBUSY)?;
        // SAFETY: place SQ vérifiée > 0 ; le SQE est rempli intégralement
        // ci-dessous avant toute publication de la `tail`.
        let sqe = unsafe { self.sq.prepare() }.expect("place SQ vérifiée");
        let opts = self.pending_options;
        // SAFETY: `sqe` pointe un slot SQE valide fraîchement zéro-initialisé,
        // exclusivement détenu jusqu'à la publication.
        unsafe {
            (*sqe).opcode = raw::IORING_OP_NOP;
            (*sqe).flags = opts.iosqe_flags();
            (*sqe).user_data = token.to_user_data();
        }
        self.pending_options = SubmitOptions::default();
        if opts.skips_cqe_on_success() {
            // Aucun CQE attendu en cas de succès → libère le slot S1 dès la
            // soumission (§6.2). Un échec produirait un CQE périmé, filtré.
            self.slab.release(token);
        }
        Ok(token)
    }

    /// Moissonne une complétion **non périmée** déjà disponible (sans syscall),
    /// en filtrant les complétions périmées (§4.2). `None` si la CQ est vide.
    fn harvest_ready(&mut self) -> Option<Completion> {
        loop {
            let cqe = self.cq.peek()?;
            if cqe.user_data & raw::RAW_USER_DATA_TAG != 0 {
                // Complétion **brute** (Temps 4 §5) : ne PAS toucher au slab ni
                // consommer le CQE — laissé à `raw_peek_completion_queue_entry` /
                // `raw_advance_completion_queue`. La moisson gérée s'arrête ici
                // (FIFO : aucune complétion gérée disponible tant que cette brute,
                // en tête, n'est pas consommée par l'appelant).
                return None;
            }
            self.cq.advance();
            let flags = CompletionFlags::from_bits_truncate(cqe.flags);
            // Marquage multishot lu **avant** `complete` (qui peut libérer le slot
            // à la terminale) : permet à `Completion::multishot_token` de
            // distinguer un flux multishot d'une op mono-coup (Temps 3d).
            let multishot = self.slab.is_multishot(cqe.user_data);
            match self
                .slab
                .complete(cqe.user_data, flags.contains(CompletionFlags::MORE))
            {
                slab::SlotOutcome::Stale => {} // périmée : passer à la suivante
                slab::SlotOutcome::More => {
                    return Some(Completion {
                        token: SubmissionToken::from_user_data(cqe.user_data),
                        res: cqe.res,
                        raw_flags: cqe.flags,
                        payload: None,
                        multishot,
                    });
                }
                slab::SlotOutcome::Final { payload } => {
                    return Some(Completion {
                        token: SubmissionToken::from_user_data(cqe.user_data),
                        res: cqe.res,
                        raw_flags: cqe.flags,
                        payload,
                        multishot,
                    });
                }
            }
        }
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Temps 4 — accès brut niveau 1 (soupape ADR-022 Décision 1)
// ───────────────────────────────────────────────────────────────────────────
impl IoUring {
    /// Capacité totale de la SQ (entrées effectives, arrondi kernel). **Sûr.**
    #[must_use]
    pub fn submission_queue_capacity(&self) -> u32 {
        self.sq.capacity()
    }

    /// Emplacements SQ actuellement disponibles. **Sûr.**
    #[must_use]
    pub fn submission_queue_available(&self) -> u32 {
        self.sq.space_left()
    }

    /// Capacité totale de la CQ. **Sûr.**
    #[must_use]
    pub fn completion_queue_capacity(&self) -> u32 {
        self.cq.capacity()
    }

    /// Réserve un emplacement SQE libre et le rend pour **remplissage manuel**
    /// (accès brut niveau 1, Temps 4). `None` si la SQ est pleine. La
    /// **publication reste `submit()`/`submit_and_wait()`** (sûrs) : la façade
    /// fait le store release et garde la main sur l'ordering d'anneau ; l'`unsafe`
    /// ne porte donc QUE sur le **contenu** du SQE et la **validité des buffers**.
    ///
    /// # Safety
    ///
    /// L'appelant garantit (contrat §6 de la spec) :
    /// 1. **opcode valide** et supporté par le kernel courant ([`IoUring::supports_op`]/probe) ;
    /// 2. **cohérence des champs** du SQE (`fd`/`addr`/`len`/flags) pour cet opcode ;
    /// 3. **validité mémoire** : tout buffer pointé par `addr`/`addr2`/`addr3` reste
    ///    valide et **non déplacé jusqu'à la complétion** (le slab S1 ne le protège
    ///    **pas** en accès brut) ;
    /// 4. **tag `user_data`** : poser [`RAW_USER_DATA_TAG`] (§5) pour coexister avec
    ///    le niveau 2 sans collision (vérifié en build debug à la soumission) ;
    /// 5. **pas de double consommation** de la complétion correspondante
    ///    ([`IoUring::raw_advance_completion_queue`] cohérent avec les peeks).
    pub unsafe fn raw_get_submission_queue_entry(
        &mut self,
    ) -> Option<&mut RawSubmissionQueueEntry> {
        let tail = self.sq.local_tail();
        // SAFETY: préconditions déléguées à l'appelant (contrat ci-dessus) ;
        // `prepare` rend un slot fraîchement zéro-initialisé, exclusivement détenu
        // jusqu'à la publication par `submit`.
        let sqe = unsafe { self.sq.prepare() }?;
        self.raw_pending.push(tail);
        // SAFETY: `RawSubmissionQueueEntry` est `#[repr(transparent)]` sur
        // `IoUringSqe` (layout identique, asserté statiquement) ; `sqe` désigne un
        // slot SQE valide de la mmap, emprunté `&mut` exclusivement le temps du
        // remplissage (avant publication).
        Some(unsafe { &mut *sqe.cast::<RawSubmissionQueueEntry>() })
    }

    /// Inspecte la prochaine complétion **sans la consommer** (`None` si la CQ est
    /// vide). **Sûr** : lecture seule via le load acquire interne. L'interprétation
    /// de `res`/`flags` et la lecture du tag `user_data` (§5) sont à la charge de
    /// l'appelant (selon l'opcode soumis).
    #[must_use]
    pub fn raw_peek_completion_queue_entry(&self) -> Option<&RawCompletionQueueEntry> {
        let cqe = self.cq.peek_entry()?;
        // SAFETY: `cqe` pointe un slot CQE vivant de la mmap (stable tant qu'aucune
        // avance ; l'emprunt `&self` interdit `advance`/`&mut` concurrent) ;
        // `RawCompletionQueueEntry` est un miroir `#[repr(C)]` d'`IoUringCqe`
        // (layout identique, asserté).
        Some(unsafe { &*cqe.cast::<RawCompletionQueueEntry>() })
    }

    /// Consomme `n` complétions de la CQ (avance la tête + store release par la
    /// façade). **Sûr** : borné au nombre réellement prêt (Principe 4) ; l'appelant
    /// garantit la cohérence avec ses [`IoUring::raw_peek_completion_queue_entry`]
    /// (pas de double consommation, §6 pt 5).
    pub fn raw_advance_completion_queue(&mut self, n: u32) {
        let n = n.min(self.cq.ready());
        for _ in 0..n {
            self.cq.advance();
        }
    }

    /// Vérifie (build **debug**) que tout SQE préparé via
    /// [`IoUring::raw_get_submission_queue_entry`] porte [`RAW_USER_DATA_TAG`]
    /// (§5) — sinon une op brute collisionnerait avec l'encodage du slab S1. En
    /// release, `debug_assert!` est inerte ; la purge de `raw_pending` a lieu dans
    /// tous les cas (idempotente, sans allocation sur liste vide).
    fn debug_assert_raw_tags(&mut self) {
        // COUVERTURE (ADR-035, STRUCTURAL — cf. docs/COVERAGE-EXCEPTIONS.md,
        // section `io_uring`). Le `}` fermant ce bloc `if cfg!(debug_assertions)`
        // porte une région LLVM dégénérée à `count == 0` alors que le **corps**
        // de la boucle est prouvé exécuté (mesure : 308 itérations via les tests
        // `raw_nop_*`). Artefact d'instrumentation du `cfg!`-constant analogue aux
        // ombres `[True:0, False:0]` documentées en tête de registre — non
        // couvrable par aucun test.
        if cfg!(debug_assertions) {
            for &tail in &self.raw_pending {
                // SAFETY: `tail` désigne un SQE préparé pendant ce staging, non
                // encore publié ; lecture seule de son `user_data`.
                let user_data = unsafe { self.sq.sqe_user_data_at(tail) };
                debug_assert!(
                    user_data & raw::RAW_USER_DATA_TAG != 0,
                    "opération brute (Temps 4) soumise sans RAW_USER_DATA_TAG : \
                     collision possible avec le slab S1 (§5)"
                );
            }
        }
        self.raw_pending.clear();
    }
}

/// Jeton opaque reliant une soumission à sa complétion (décision S1).
///
/// Encapsule un index de slot du slab d'opérations en vol **et** une génération
/// (compteur anti-réutilisation, protège contre l'ABA et les complétions
/// périmées). Le `user_data` kernel est dérivé en interne — l'API ne laisse
/// **jamais** l'appelant manipuler un `user_data` brut.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SubmissionToken {
    slot: u32,
    generation: u32,
}

impl SubmissionToken {
    /// Construit un jeton à partir d'un index de slot et d'une génération.
    pub(crate) const fn new(slot: u32, generation: u32) -> Self {
        Self { slot, generation }
    }

    /// Index de slot dans le slab d'opérations en vol.
    pub(crate) const fn slot(self) -> u32 {
        self.slot
    }

    /// Génération du slot au moment de la réservation (anti-réutilisation/ABA).
    pub(crate) const fn generation(self) -> u32 {
        self.generation
    }

    /// Encode le jeton en `user_data` kernel :
    /// `((generation as u64) << 32) | (slot as u64)` (§4.2).
    pub(crate) fn to_user_data(self) -> u64 {
        // `wrapping_shl(32)` : la valeur (u32 élargie) ne déborde jamais sur 64
        // bits ; choix wrapping explicite pour rester lint-clean (Principe 2).
        u64::from(self.generation).wrapping_shl(32) | u64::from(self.slot)
    }

    /// Décode un `user_data` kernel en `(generation, slot)`.
    ///
    /// # Panics
    ///
    /// Jamais : les masques 32 bits garantissent que chaque moitié tient dans
    /// un `u32` (les `expect` sont structurellement inatteignables).
    pub(crate) fn from_user_data(user_data: u64) -> Self {
        let slot = u32::try_from(user_data & 0xFFFF_FFFF).expect("masque 32 bits bas");
        let generation = u32::try_from(user_data >> 32).expect("décalage 32 bits haut");
        Self { slot, generation }
    }
}

/// Jeton d'une opération multishot (un slot, plusieurs complétions). Voir
/// [`multishot`] (Temps 3d).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MultishotToken {
    slot: u32,
    generation: u32,
}

impl MultishotToken {
    /// Construit un jeton multishot à partir d'un index de slot et d'une
    /// génération (sémantique Temps 3d).
    pub(crate) const fn new(slot: u32, generation: u32) -> Self {
        Self { slot, generation }
    }

    /// `SubmissionToken` équivalent (même `(slot, generation)`) — pour
    /// l'annulation par jeton et la corrélation aux complétions.
    pub(crate) const fn as_submission(self) -> SubmissionToken {
        SubmissionToken::new(self.slot, self.generation)
    }
}

/// Options de soumission par-opération (flags `IOSQE_*` exposés sûrement).
///
/// Construit par combinateurs ; appliqué via [`IoUring::with`]. Les liens
/// (`IO_LINK`/`IO_HARDLINK`) passent par le `LinkedChainBuilder` (Temps 3c) ; la
/// sélection de buffer (`BUFFER_SELECT`) par `ProvidedBufferRing` (Temps 3b).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct SubmitOptions {
    // Représentation interne (Pass B) : bitmask IOSQE_*.
    flags: u32,
}

impl SubmitOptions {
    /// Active `IOSQE_IO_DRAIN` : draine les opérations déjà soumises avant
    /// celle-ci.
    #[must_use]
    pub fn drain(mut self) -> Self {
        self.flags |= u32::from(raw::IOSQE_IO_DRAIN);
        self
    }

    /// Active `IOSQE_ASYNC` : force l'exécution sur le pool io-wq.
    #[must_use]
    pub fn force_async(mut self) -> Self {
        self.flags |= u32::from(raw::IOSQE_ASYNC);
        self
    }

    /// Active `IOSQE_CQE_SKIP_SUCCESS` : pas de CQE en cas de succès (libère le
    /// slot S1 **à la soumission**). Nécessite la feature `FEAT_CQE_SKIP`.
    #[must_use]
    pub fn skip_cqe_on_success(mut self) -> Self {
        self.flags |= u32::from(raw::IOSQE_CQE_SKIP_SUCCESS);
        self
    }

    /// Active `IOSQE_FIXED_FILE` : le `fd` du SQE est un **index de slot fixe**
    /// (Temps 3a — `FixedSlot`/`fixed_fd_install`). Interne : posé par les
    /// façades fixed-file, jamais par l'appelant.
    pub(crate) fn fixed_file(mut self) -> Self {
        self.flags |= u32::from(raw::IOSQE_FIXED_FILE);
        self
    }

    /// Active `IOSQE_BUFFER_SELECT` : l'op sélectionne automatiquement un buffer
    /// dans un groupe fourni (Temps 3b). Interne : posé par les façades
    /// `submit_*_provided`, jamais par l'appelant.
    pub(crate) fn buffer_select(mut self) -> Self {
        self.flags |= u32::from(raw::IOSQE_BUFFER_SELECT);
        self
    }

    /// Octet de flags `IOSQE_*` à poser dans le SQE (tous < 256).
    fn iosqe_flags(self) -> u8 {
        u8::try_from(self.flags).unwrap_or(0)
    }

    /// Vrai si `skip_cqe_on_success` est demandé (libération anticipée du slot).
    fn skips_cqe_on_success(self) -> bool {
        self.flags & u32::from(raw::IOSQE_CQE_SKIP_SUCCESS) != 0
    }
}

// ---------------------------------------------------------------------------
// Complétion
// ---------------------------------------------------------------------------

impl IoUring {
    /// Attend (bloquant) la prochaine complétion et la consomme
    /// (`io_uring_enter(.., GETEVENTS, min_complete = 1)` ; lecture de la CQ par
    /// **load acquire**, §3.2). Les complétions **périmées** (génération de slot
    /// non concordante, §4.2) sont filtrées en silence.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINTR`] : remonté tel quel.
    /// - [`Errno::EBADF`].
    pub fn wait_completion(&mut self) -> Result<Completion, Errno> {
        loop {
            if let Some(completion) = self.harvest_ready() {
                return Ok(completion);
            }
            // Aucune complétion non périmée disponible : bloque jusqu'à au moins
            // une via `io_uring_enter(GETEVENTS, min_complete = 1)`.
            let (efd, eflag) = self.enter_target();
            // SAFETY: `fd`/index est valide ; pas d'argument étendu.
            let ret =
                unsafe { syscall::enter(efd, 0, 1, raw::IORING_ENTER_GETEVENTS | eflag, 0, 0) };
            if ret < 0 {
                // EINTR remonté tel quel (ADR-021 conv. 2). La boucle ne
                // re-`enter` que sur succès renvoyant des CQE périmés à filtrer.
                return Err(raw::errno_from_negative_syscall_ret(ret));
            }
        }
    }

    /// Attend une complétion avec délai maximal (`IORING_ENTER_EXT_ARG` +
    /// `io_uring_getevents_arg`, ou `ABS_TIMER` si `FEAT_MIN_TIMEOUT`).
    /// Retourne `Ok(None)` à l'expiration.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINTR`] : remonté tel quel.
    /// - [`Errno::EBADF`], [`Errno::EINVAL`].
    pub fn wait_completion_timeout(
        &mut self,
        timeout: Duration,
    ) -> Result<Option<Completion>, Errno> {
        if let Some(completion) = self.harvest_ready() {
            return Ok(Some(completion));
        }
        let ts = raw::KernelTimespec {
            tv_sec: i64::try_from(timeout.as_secs()).unwrap_or(i64::MAX),
            tv_nsec: i64::from(timeout.subsec_nanos()),
        };
        let arg = raw::IoUringGeteventsArg {
            sigmask: 0,
            sigmask_sz: 0,
            min_wait_usec: 0,
            ts: core::ptr::from_ref(&ts) as u64,
        };
        let arg_sz = u64::try_from(core::mem::size_of::<raw::IoUringGeteventsArg>())
            .expect("taille getevents_arg ≤ u64");
        let (efd, eflag) = self.enter_target();
        // SAFETY: `fd`/index valide ; `arg` pointe une `io_uring_getevents_arg`
        // vivante de taille `arg_sz` cohérente avec le flag `EXT_ARG`, et `ts`
        // reste en vie pendant l'appel (variables locales).
        let ret = unsafe {
            syscall::enter(
                efd,
                0,
                1,
                raw::IORING_ENTER_GETEVENTS | raw::IORING_ENTER_EXT_ARG | eflag,
                core::ptr::from_ref(&arg) as u64,
                arg_sz,
            )
        };
        if ret < 0 {
            let err = raw::errno_from_negative_syscall_ret(ret);
            if err == Errno::ETIME {
                // Expiration : aucune complétion dans le délai imparti.
                return Ok(None);
            }
            // EINTR et autres errno remontés tels quels (ADR-021 conv. 2).
            return Err(err);
        }
        Ok(self.harvest_ready())
    }

    /// Récupère une complétion si disponible, **sans bloquer** ni syscall
    /// (load acquire de la CQ). Filtre les complétions périmées.
    pub fn try_completion(&mut self) -> Option<Completion> {
        self.harvest_ready()
    }

    /// Itère les complétions actuellement disponibles dans la CQ, avançant
    /// `head` (store release) au fil de l'itération.
    pub fn completions(&mut self) -> CompletionIter<'_> {
        CompletionIter { ring: self }
    }

    /// Vrai si le kernel courant supporte `op` (`IORING_REGISTER_PROBE`, mis en
    /// cache à la construction ; ADR-022 Décision 8). Permet le fallback vers le
    /// syscall synchrone correspondant.
    #[must_use]
    pub fn supports_op(&self, op: IoUringOpcode) -> bool {
        self.supported_ops
            .get(usize::from(opcode_number(op)))
            .copied()
            .unwrap_or(false)
    }

    /// Features io_uring négociées au setup (axe G), exposées par prédicats
    /// stables.
    #[must_use]
    pub fn capabilities(&self) -> IoUringCapabilities {
        self.capabilities
    }

    /// Annulation synchrone globale ou ciblée (`IORING_REGISTER_SYNC_CANCEL`,
    /// avec timeout). Brique de [`IoUring::shutdown`] (S2). Retourne le nombre
    /// d'opérations annulées.
    ///
    /// # Errors
    ///
    /// - [`Errno::EINTR`] : remonté tel quel.
    /// - [`Errno::EALREADY`] : annulation déjà en cours pour la cible.
    /// - [`Errno::ENOENT`] : aucune opération ne correspond à la cible.
    /// - [`Errno::EINVAL`].
    pub fn sync_cancel(&mut self, target: CancelTarget<'_>) -> Result<u32, Errno> {
        let mut reg = raw::IoUringSyncCancelReg {
            // Timeout interne borné : le kernel attend jusqu'à 2 s que les
            // annulations postent leurs CQE, puis rend la main.
            timeout_sec: 2,
            ..raw::IoUringSyncCancelReg::default()
        };
        match target {
            CancelTarget::Token(token) => reg.addr = token.to_user_data(),
            CancelTarget::Fd(fd) => {
                reg.fd = fd.as_raw_fd();
                reg.flags = raw::IORING_ASYNC_CANCEL_FD;
            }
            CancelTarget::Op(op) => {
                reg.opcode = opcode_number(op);
                reg.flags = raw::IORING_ASYNC_CANCEL_OP;
            }
            CancelTarget::Any => reg.flags = raw::IORING_ASYNC_CANCEL_ANY,
        }
        let reg_ptr = core::ptr::from_ref(&reg) as u64;
        // SAFETY: `fd` ring valide ; `reg` pointe une `io_uring_sync_cancel_reg`
        // vivante (variable locale) pour la durée de l'appel (`nr_args = 1`).
        let ret = unsafe {
            syscall::register(self.fd_raw(), raw::IORING_REGISTER_SYNC_CANCEL, reg_ptr, 1)
        };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        Ok(u32::try_from(ret).unwrap_or(0))
    }
}

/// Numéro d'opcode kernel `IORING_OP_*` correspondant à un [`IoUringOpcode`].
///
/// Les 3 opcodes obsolètes (18 `OPENAT`, 31 `PROVIDE_BUFFERS`, 32
/// `REMOVE_BUFFERS`) ne figurent pas dans l'énumération : leurs numéros sont
/// donc absents (trous 18/31/32).
fn opcode_number(op: IoUringOpcode) -> u8 {
    match op {
        IoUringOpcode::Nop => 0,
        IoUringOpcode::Readv => 1,
        IoUringOpcode::Writev => 2,
        IoUringOpcode::Fsync => 3,
        IoUringOpcode::ReadFixed => 4,
        IoUringOpcode::WriteFixed => 5,
        IoUringOpcode::PollAdd => 6,
        IoUringOpcode::PollRemove => 7,
        IoUringOpcode::SyncFileRange => 8,
        IoUringOpcode::Sendmsg => 9,
        IoUringOpcode::Recvmsg => 10,
        IoUringOpcode::Timeout => 11,
        IoUringOpcode::TimeoutRemove => 12,
        IoUringOpcode::Accept => 13,
        IoUringOpcode::AsyncCancel => 14,
        IoUringOpcode::LinkTimeout => 15,
        IoUringOpcode::Connect => 16,
        IoUringOpcode::Fallocate => 17,
        IoUringOpcode::Close => 19,
        IoUringOpcode::FilesUpdate => 20,
        IoUringOpcode::Statx => 21,
        IoUringOpcode::Read => 22,
        IoUringOpcode::Write => 23,
        IoUringOpcode::Fadvise => 24,
        IoUringOpcode::Madvise => 25,
        IoUringOpcode::Send => 26,
        IoUringOpcode::Recv => 27,
        IoUringOpcode::Openat2 => 28,
        IoUringOpcode::EpollCtl => 29,
        IoUringOpcode::Splice => 30,
        IoUringOpcode::Tee => 33,
        IoUringOpcode::Shutdown => 34,
        IoUringOpcode::Renameat => 35,
        IoUringOpcode::Unlinkat => 36,
        IoUringOpcode::Mkdirat => 37,
        IoUringOpcode::Symlinkat => 38,
        IoUringOpcode::Linkat => 39,
        IoUringOpcode::MsgRing => 40,
        IoUringOpcode::Fsetxattr => 41,
        IoUringOpcode::Setxattr => 42,
        IoUringOpcode::Fgetxattr => 43,
        IoUringOpcode::Getxattr => 44,
        IoUringOpcode::Socket => 45,
        IoUringOpcode::UringCmd => 46,
        IoUringOpcode::SendZc => 47,
        IoUringOpcode::SendmsgZc => 48,
        IoUringOpcode::ReadMultishot => 49,
        IoUringOpcode::Waitid => 50,
        IoUringOpcode::FutexWait => 51,
        IoUringOpcode::FutexWake => 52,
        IoUringOpcode::FutexWaitv => 53,
        IoUringOpcode::FixedFdInstall => 54,
        IoUringOpcode::Ftruncate => 55,
        IoUringOpcode::Bind => 56,
        IoUringOpcode::Listen => 57,
        // `IoUringOpcode` est `#[non_exhaustive]` : un opcode d'un kernel futur
        // non encore mappé ⇒ numéro invalide (`255`), qui ne matchera aucune
        // opération réelle côté `sync_cancel`/restriction (plutôt qu'un faux
        // match sur l'opcode 0).
        _ => u8::MAX,
    }
}

/// Une complétion (CQE décodé). Au Temps 1, les interprétations sont
/// **génériques** ; les variantes typées riches (fd accepté/ouvert, etc.)
/// arrivent aux Temps 2a–2d (ADR-022 Décision 9). Convention de résultat : un
/// `res` négatif est un `-errno`, converti en `Err(Errno)` par les méthodes
/// `into_*` ; un `res ≥ 0` est la valeur utile.
pub struct Completion {
    /// Jeton décodé depuis `user_data`.
    token: SubmissionToken,
    /// Résultat brut du kernel (`res` du CQE).
    res: i32,
    /// Flags bruts du CQE (`IORING_CQE_F_*` + id de buffer dans les bits hauts).
    raw_flags: u32,
    /// Payload possédé récupéré du slot S1 (`None` si l'op n'en portait pas).
    /// Extrait par les accesseurs typés (`into_buffer_result`, `into_statx`…).
    payload: Option<OwnedOp>,
    /// `true` si cette complétion provient d'une opération **multishot** (Temps
    /// 3d) : le slot a été réservé multishot (lu avant `complete`). Sert à
    /// [`Completion::multishot_token`].
    multishot: bool,
}

impl Completion {
    /// Jeton de l'opération qui a produit cette complétion.
    #[must_use]
    pub fn token(&self) -> SubmissionToken {
        self.token
    }

    /// Jeton **multishot** si cette complétion provient d'une opération multishot
    /// (Temps 3d), `None` sinon. Toutes les complétions d'un même multishot
    /// (intermédiaires `CQE_F_MORE` **et** terminale) portent le **même** jeton ;
    /// [`Completion::has_more`] distingue les intermédiaires de la terminale.
    #[must_use]
    pub fn multishot_token(&self) -> Option<MultishotToken> {
        if self.multishot {
            Some(MultishotToken::new(
                self.token.slot(),
                self.token.generation(),
            ))
        } else {
            None
        }
    }

    /// Résultat brut du kernel (sémantique dépendante de l'op soumise).
    #[must_use]
    pub fn raw_result(&self) -> i32 {
        self.res
    }

    /// Flags de complétion (cf. [`CompletionFlags`]).
    #[must_use]
    pub fn flags(&self) -> CompletionFlags {
        CompletionFlags::from_bits_truncate(self.raw_flags)
    }

    /// `IORING_CQE_F_MORE` : d'autres complétions suivront (multishot).
    #[must_use]
    pub fn has_more(&self) -> bool {
        self.flags().contains(CompletionFlags::MORE)
    }

    /// `IORING_CQE_F_NOTIF` : complétion de notification zero-copy.
    #[must_use]
    pub fn is_notif(&self) -> bool {
        self.flags().contains(CompletionFlags::NOTIF)
    }

    /// ID du buffer fourni consommé (`IORING_CQE_F_BUFFER`), le cas échéant.
    /// L'identifiant occupe les 16 bits de poids fort des flags du CQE.
    #[must_use]
    pub fn buffer_id(&self) -> Option<u16> {
        if self.flags().contains(CompletionFlags::BUFFER) {
            Some(u16::try_from(self.raw_flags >> 16).unwrap_or(0))
        } else {
            None
        }
    }

    /// `IORING_CQE_F_SOCK_NONEMPTY` : données restantes lisibles après un `recv`.
    #[must_use]
    pub fn socket_has_pending_data(&self) -> bool {
        self.flags().contains(CompletionFlags::SOCK_NONEMPTY)
    }

    /// Interprétation générique : `res ≥ 0` → valeur utile, `res < 0` →
    /// `Err(Errno)` (= `-res`).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si le kernel a signalé un échec.
    pub fn into_result(self) -> Result<i32, Errno> {
        res_to_result(self.res)
    }

    /// Récupère le buffer **déplacé** hors du slot (S1, zéro copie) avec le
    /// nombre d'octets traités (`submit_read`/`submit_write`).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si l'opération a échoué (le buffer est
    /// alors consommé sans être restitué).
    pub fn into_buffer_result(self) -> Result<(Vec<u8>, usize), Errno> {
        let bytes = res_to_result(self.res)?;
        let length = usize::try_from(bytes).unwrap_or(0);
        let buffer = match self.payload {
            Some(OwnedOp::Bytes(buffer)) => buffer,
            // Op sans buffer `Bytes` (NOP, ou mauvais accesseur) : buffer vide.
            _ => Vec::new(),
        };
        Ok((buffer, length))
    }

    /// Récupère les buffers vectorisés **déplacés** hors du slot avec le nombre
    /// total d'octets traités (`submit_readv`/`submit_writev`).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si l'opération a échoué (les buffers
    /// sont alors consommés sans être restitués).
    pub fn into_vectored_result(self) -> Result<(Vec<Vec<u8>>, usize), Errno> {
        let bytes = res_to_result(self.res)?;
        let length = usize::try_from(bytes).unwrap_or(0);
        let buffers = match self.payload {
            Some(OwnedOp::Vectored { buffers, .. }) => buffers,
            _ => Vec::new(),
        };
        Ok((buffers, length))
    }

    /// Récupère le tampon `statx` **déplacé** hors du slot, rempli par le kernel
    /// (`submit_statx`).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si l'opération a échoué (le tampon est
    /// alors consommé sans être restitué).
    pub fn into_statx(self) -> Result<Box<air_sys_types::fs::Statx>, Errno> {
        res_to_result(self.res)?;
        match self.payload {
            Some(OwnedOp::Statx { out, .. }) => Ok(out),
            // Accesseur appelé sur une complétion sans tampon statx : tampon
            // zéro-initialisé (défensif ; jamais sur le chemin nominal `statx`).
            _ => Ok(Box::new(air_sys_types::fs::Statx::default())),
        }
    }

    /// Récupère le buffer de valeur xattr **déplacé** hors du slot avec la
    /// taille rendue par le kernel (`submit_getxattr`/`submit_fgetxattr`). La
    /// taille permet de retailler (un buffer trop court ⇒ `Err(ERANGE)`).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si l'opération a échoué (le buffer est
    /// alors consommé sans être restitué).
    pub fn into_xattr_result(self) -> Result<(Vec<u8>, usize), Errno> {
        let bytes = res_to_result(self.res)?;
        let length = usize::try_from(bytes).unwrap_or(0);
        let value = match self.payload {
            Some(OwnedOp::Xattr { value, .. }) => value,
            _ => Vec::new(),
        };
        Ok((value, length))
    }

    /// Récupère le descripteur ouvert par `submit_openat2`.
    ///
    /// `res` (≥ 0) est le numéro de FD ; il devient un [`OwnedFd`] possédé
    /// (CLOEXEC selon `how`). Le chemin source, gardé en vie dans le slot, est
    /// libéré ici.
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si l'ouverture a échoué.
    pub fn opened_fd(self) -> Result<OwnedFd, Errno> {
        let fd = res_to_result(self.res)?;
        // SAFETY: `res ≥ 0` est un FD frais possédé, retourné par `openat2` via
        // io_uring ; `from_raw_fd` en prend l'ownership exclusif (pas de double
        // close : le chemin parké est libéré, aucun autre détenteur).
        Ok(unsafe { OwnedFd::from_raw_fd(fd) })
    }

    /// Récupère le socket créé par `submit_socket` (CLOEXEC).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si la création a échoué.
    pub fn into_socket_fd(self) -> Result<OwnedFd, Errno> {
        let fd = res_to_result(self.res)?;
        // SAFETY: `res ≥ 0` est un FD socket frais possédé (`IORING_OP_SOCKET`) ;
        // `from_raw_fd` en prend l'ownership exclusif.
        Ok(unsafe { OwnedFd::from_raw_fd(fd) })
    }

    /// Récupère le socket accepté par `submit_accept` (CLOEXEC), sans adresse
    /// pair.
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si l'`accept` a échoué.
    pub fn accepted_fd(self) -> Result<OwnedFd, Errno> {
        let fd = res_to_result(self.res)?;
        // SAFETY: `res ≥ 0` est un FD socket connecté frais possédé
        // (`IORING_OP_ACCEPT`) ; ownership exclusif via `from_raw_fd`.
        Ok(unsafe { OwnedFd::from_raw_fd(fd) })
    }

    /// Récupère le socket accepté **et** l'adresse du pair
    /// (`submit_accept_with_peer`). L'adresse est décodée du stockage `sockaddr`
    /// possédé écrit par le kernel.
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si l'`accept` a échoué.
    pub fn into_accept_result(self) -> Result<(OwnedFd, air_sys_types::net::SocketAddr), Errno> {
        let fd = res_to_result(self.res)?;
        let address = match self.payload {
            Some(OwnedOp::Accept { addr, addrlen }) => {
                crate::net::raw_to_socket_addr(&addr.bytes, *addrlen)
                    // Décodage défensif : un kernel renvoyant une famille inconnue ou une
                    // longueur nulle ⇒ adresse « non nommée » plutôt que panique.
                    .unwrap_or(air_sys_types::net::SocketAddr::Unix(
                        air_sys_types::net::UnixSocketAddr::Unnamed,
                    ))
            }
            _ => air_sys_types::net::SocketAddr::Unix(air_sys_types::net::UnixSocketAddr::Unnamed),
        };
        // SAFETY: `res ≥ 0` est un FD socket connecté frais possédé ; ownership
        // exclusif via `from_raw_fd`.
        Ok((unsafe { OwnedFd::from_raw_fd(fd) }, address))
    }

    /// Décode le résultat d'un `submit_receive_message` : buffers reçus +
    /// métadonnées (`ReceiveMessageMeta`, adossé à `io_uring_recvmsg_out`). Les
    /// **FD reçus** via `SCM_RIGHTS` sont matérialisés en [`OwnedFd`] **CLOEXEC**
    /// (drapeau `MSG_CMSG_CLOEXEC` posé par la façade). Un cmsg tronqué
    /// (`MSG_CTRUNC`) est signalé via `meta.control_truncated()` ; les FD
    /// incomplets ne sont **jamais** matérialisés (le kernel les ferme) ⇒ aucune
    /// fuite de FD.
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si le `recvmsg` a échoué.
    pub fn into_receive_message_result(
        self,
    ) -> Result<
        (
            air_sys_types::net::OwnedReceiveMessage,
            air_sys_types::net::ReceiveMessageMeta,
        ),
        Errno,
    > {
        use air_sys_types::net::{MessageFlags, OwnedReceiveMessage, ReceiveMessageMeta};
        let bytes = res_to_result(self.res)?;
        let payloadlen = u32::try_from(bytes).unwrap_or(0);
        let Some(OwnedOp::RecvMsg(state)) = self.payload else {
            // Accesseur appelé sur une complétion sans état recvmsg : résultat
            // vide (défensif ; jamais sur le chemin nominal `recvmsg`).
            return Ok((
                OwnedReceiveMessage::default(),
                ReceiveMessageMeta {
                    namelen: 0,
                    controllen: 0,
                    payloadlen,
                    flags: MessageFlags::empty(),
                    address: None,
                    fds: Vec::new(),
                },
            ));
        };
        let owned::RecvMsgState {
            msghdr,
            buffers,
            name,
            control,
            ..
        } = *state;
        let namelen = msghdr.msg_namelen;
        let controllen_usize = usize::try_from(msghdr.msg_controllen).unwrap_or(0);
        let controllen = u32::try_from(msghdr.msg_controllen).unwrap_or(0);
        let flags = MessageFlags::from_bits_truncate(msghdr.msg_flags);
        // Extrait les FD complets du buffer de contrôle (jamais de FD partiel).
        let fds = crate::net::parse_scm_rights(&control, controllen_usize.min(control.len()));
        let address = if namelen > 0 {
            crate::net::raw_to_socket_addr(&name.bytes, namelen)
        } else {
            None
        };
        let control_capacity = control.len();
        let meta = ReceiveMessageMeta {
            namelen,
            controllen,
            payloadlen,
            flags,
            address,
            fds,
        };
        let message = OwnedReceiveMessage {
            buffers,
            control_capacity,
            flags,
        };
        Ok((message, meta))
    }

    /// Restitue le buffer zero-copy de `submit_send_zero_copy` à la complétion
    /// **NOTIF** (`is_notif`) — le kernel ne référence plus la mémoire. En cas
    /// d'**échec précoce** (CQE de résultat `res < 0` **sans** `F_MORE`, donc
    /// aucune NOTIF à venir), renvoie l'erreur ; le buffer est alors libéré (sûr,
    /// aucune fuite).
    ///
    /// Pour un `submit_send_message_zero_copy` **multi-buffers**, utiliser
    /// [`Completion::into_zero_copy_buffers`] (restitution intégrale, ADR-032) ;
    /// appelé ici, ses buffers sont **concaténés** sans perte d'octet (les
    /// frontières sont perdues, mais aucune donnée n'est *discardée*).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` sur le chemin d'échec précoce.
    pub fn into_zero_copy_buffer(self) -> Result<Vec<u8>, Errno> {
        let is_notif = self.flags().contains(CompletionFlags::NOTIF);
        let res = self.res;
        let buffer = match self.payload {
            Some(OwnedOp::Bytes(buffer)) => buffer,
            // ADR-032 : ne *discarde* jamais — concatène tous les buffers (aucun
            // octet perdu) plutôt que de ne rendre que le premier.
            Some(OwnedOp::SendMsg(state)) => state.buffers.into_iter().flatten().collect(),
            _ => Vec::new(),
        };
        if is_notif {
            // NOTIF : succès ; le `res` peut porter le bit « copié » (REPORT_USAGE),
            // ce n'est pas une erreur — la restitution est inconditionnelle.
            Ok(buffer)
        } else {
            // Échec précoce (résultat sans F_MORE) : propage l'erreur.
            res_to_result(res).map(|_| buffer)
        }
    }

    /// Restitue **l'intégralité** des buffers zero-copy d'un
    /// `submit_send_message_zero_copy` à la complétion **NOTIF** — **tous** les
    /// buffers du message, **intacts et dans l'ordre** (ADR-032, zéro perte de
    /// donnée). Le slot S1 les a tous retenus jusqu'au NOTIF. Pour un
    /// `submit_send_zero_copy` (mono-buffer), renvoie un `Vec` à un seul élément.
    ///
    /// Échec précoce (CQE résultat `res < 0` sans `F_MORE`) : renvoie l'erreur ;
    /// les buffers sont alors libérés (sûr, aucune fuite).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` sur le chemin d'échec précoce.
    pub fn into_zero_copy_buffers(self) -> Result<Vec<Vec<u8>>, Errno> {
        let is_notif = self.flags().contains(CompletionFlags::NOTIF);
        let res = self.res;
        let buffers = match self.payload {
            // `sendmsg_zc` : tous les buffers, dans l'ordre — jamais un sous-ensemble.
            Some(OwnedOp::SendMsg(state)) => state.buffers,
            // `send_zc` mono-buffer : enveloppé dans un `Vec` à un élément.
            Some(OwnedOp::Bytes(buffer)) => vec![buffer],
            _ => Vec::new(),
        };
        if is_notif {
            Ok(buffers)
        } else {
            res_to_result(res).map(|_| buffers)
        }
    }

    /// `IORING_NOTIF_USAGE_ZC_COPIED` : sur une complétion NOTIF avec
    /// `ZeroCopyFlags::REPORT_USAGE`, indique que le kernel a dû **copier** (pas
    /// de vrai zero-copy). `false` hors NOTIF ou sans `REPORT_USAGE`.
    #[must_use]
    pub fn zero_copy_copied(&self) -> bool {
        self.flags().contains(CompletionFlags::NOTIF)
            && (self.res & raw::IORING_NOTIF_USAGE_ZC_COPIED) != 0
    }

    /// Décode les événements prêts d'un `submit_poll_add` (`res ≥ 0` = bitset
    /// `PollEvents`).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si le poll a échoué.
    pub fn into_poll_result(self) -> Result<air_sys_types::io_uring::PollEvents, Errno> {
        let bits = res_to_result(self.res)?;
        // `res` ≥ 0 est un bitset d'événements (`u32`) — jamais négatif ici.
        let bits = u32::try_from(bits).unwrap_or(0);
        Ok(air_sys_types::io_uring::PollEvents::from_bits_truncate(
            bits,
        ))
    }

    /// Récupère le tampon `siginfo_t` **déplacé** hors du slot, rempli par le
    /// kernel (`submit_waitid`). À lire via
    /// [`SignalInfo::as_bytes`](air_sys_types::signal::SignalInfo::as_bytes).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si le `waitid` a échoué (le tampon est
    /// alors consommé sans être restitué).
    pub fn into_waitid_result(self) -> Result<Box<air_sys_types::signal::SignalInfo>, Errno> {
        res_to_result(self.res)?;
        match self.payload {
            Some(OwnedOp::Waitid(info)) => Ok(info),
            // Accesseur appelé hors chemin `waitid` : `siginfo` zéro-initialisé.
            _ => Ok(Box::new(air_sys_types::signal::SignalInfo::zeroed())),
        }
    }

    /// Construit une [`Completion`] de test (sans kernel) pour exercer les
    /// accesseurs typés sur des `(res, flags, payload)` arbitraires.
    #[cfg(test)]
    pub(crate) fn for_test(
        token: SubmissionToken,
        res: i32,
        raw_flags: u32,
        payload: Option<OwnedOp>,
    ) -> Self {
        Self {
            token,
            res,
            raw_flags,
            payload,
            multishot: false,
        }
    }

    /// Succès sans valeur de retour (close, fsync, nop…).
    ///
    /// # Errors
    ///
    /// [`Errno`] correspondant à `-res` si l'opération a échoué.
    pub fn completed(&self) -> Result<(), Errno> {
        res_to_result(self.res).map(|_| ())
    }
}

/// Convertit le `res` d'un CQE en `Result` : `res < 0` ⇒ `Err(-res)`, sinon
/// `Ok(res)`. Convention io_uring (ADR-022 Décision 9).
fn res_to_result(res: i32) -> Result<i32, Errno> {
    if res < 0 {
        // `res` négatif ⇒ `-res` est un errno kernel (1..=4095) non nul.
        // `checked_neg` ne renvoie `None` que pour `i32::MIN` (défensif, jamais
        // en pratique pour un CQE kernel).
        match res.checked_neg().and_then(core::num::NonZeroI32::new) {
            Some(nz) => Err(Errno::from_nonzero(nz)),
            None => Err(Errno::EINVAL),
        }
    } else {
        Ok(res)
    }
}

/// Surface de fuzzing (frontière de décode des données écrites par le kernel,
/// Principe 3). N'existe QUE sous `--cfg fuzzing` (posé par `cargo-fuzz`) :
/// zéro surface en build normal. Le harnais est **pur** (aucun syscall, aucun
/// ring réel) — on modélise un kernel buggé/hostile remplissant la mémoire
/// partagée. **Invariant : TOTALITÉ** — toute entrée donne une valeur typée ou
/// une erreur typée, jamais de panic/UB/accès hors-bornes.
#[cfg(fuzzing)]
pub mod fuzz_api {
    use super::owned::OwnedOp;
    use super::{Completion, SetupFlags, SubmissionToken, raw, ring_sizes};
    use crate::io_uring::slab::InflightSlab;
    use air_sys_types::fs::{Statx, StatxMask};
    // Crate `#![no_std]` (sauf `cfg(test)`) : sous `--cfg fuzzing` on n'est pas en
    // test, donc les types possédés viennent d'`alloc`, pas du prélude `std`. La
    // macro `vec!` reste fournie par `#[macro_use] extern crate alloc` (crate root).
    use alloc::boxed::Box;
    use alloc::ffi::CString;
    use alloc::vec::Vec;
    use core::num::NonZeroU32;

    /// Décode les **résultats kernel externes** des opérations 2a (`statx`,
    /// `getxattr`, `readv`) via les accesseurs typés de [`Completion`], pour
    /// tout `(res, raw_flags)` et tout contenu de tampon. Invariant de
    /// **totalité** : aucune entrée ne produit panic/UB — la valeur typée ou
    /// l'erreur typée, jamais autre chose. (Le kernel écrit `Statx`/la valeur
    /// xattr ; ce sont des données externes au sens du Principe 3.)
    pub fn decode_2a_results(res: i32, raw_flags: u32, mask: u32, value: Vec<u8>) {
        let token = SubmissionToken::new(0, 0);

        // statx : tampon écrit par le kernel, masque arbitraire.
        let mut out = Box::new(Statx::default());
        out.mask = mask;
        out.size = u64::from(raw_flags);
        let statx_completion = Completion {
            token,
            res,
            raw_flags,
            payload: Some(OwnedOp::Statx {
                out,
                path: CString::new("p").expect("pas de NUL"),
            }),
            multishot: false,
        };
        if let Ok(decoded) = statx_completion.into_statx() {
            let _ = decoded.has(StatxMask::from_bits_truncate(mask));
            let _ = decoded.size;
            let _ = decoded.mtime;
        }

        // getxattr : valeur de sortie de taille arbitraire.
        let xattr_completion = Completion {
            token,
            res,
            raw_flags,
            payload: Some(OwnedOp::Xattr {
                value: value.clone(),
                name: CString::new("n").expect("pas de NUL"),
                path: None,
            }),
            multishot: false,
        };
        let _ = xattr_completion.into_xattr_result();

        // readv : restitution vectorisée (un buffer + son iovec dérivé).
        let mut buffers = vec![value];
        let iovecs: Box<[raw::Iovec]> = buffers
            .iter_mut()
            .map(|buffer| raw::Iovec {
                iov_base: buffer.as_mut_ptr(),
                iov_len: buffer.len(),
            })
            .collect();
        let vectored_completion = Completion {
            token,
            res,
            raw_flags,
            payload: Some(OwnedOp::Vectored { buffers, iovecs }),
            multishot: false,
        };
        let _ = vectored_completion.into_vectored_result();
    }

    /// Décode les **complétions `URING_CMD` socket** (Temps 2d) : `getsockopt`
    /// restitue son **buffer de sortie** (rempli par le kernel) via
    /// `into_buffer_result` (avec `res` = longueur effective annoncée par le
    /// kernel — donnée externe, Principe 3) ; `inq`/`outq` via `into_result`.
    /// Invariant de **totalité** : pour tout `(res, value)`, ni panic ni UB —
    /// la longueur retournée peut dépasser `value.len()` si le kernel ment, mais
    /// l'accesseur ne déréférence pas au-delà du buffer (il rend `(Vec, usize)`).
    pub fn decode_2d_results(res: i32, value: Vec<u8>) {
        let token = SubmissionToken::new(0, 0);
        // getsockopt : buffer de sortie + longueur effective (`res`).
        let getsockopt_completion = Completion {
            token,
            res,
            raw_flags: 0,
            payload: Some(OwnedOp::Bytes(value)),
            multishot: false,
        };
        let _ = getsockopt_completion.into_buffer_result();
        // inq/outq : pas de buffer, `res` = compteur d'octets.
        let count_completion = Completion {
            token,
            res,
            raw_flags: 0,
            payload: None,
            multishot: false,
        };
        let _ = count_completion.completed();
        let _ = count_completion.into_result();
    }

    /// Décode les **données réseau externes** d'un `recvmsg` io_uring (Temps 2b)
    /// via `into_receive_message_result` : le **buffer de contrôle** (cmsg
    /// `SCM_RIGHTS`) et le **stockage d'adresse** (`sockaddr`) sont remplis par
    /// le kernel ⇒ entrées externes (Principe 3). Invariant de **totalité** :
    /// pour tout `(res, controllen, namelen, flags, control, name)`, le parsing
    /// (`parse_scm_rights` + `raw_to_socket_addr`) ne panique ni ne déborde. Les
    /// `i32` extraits du cmsg ne sont **pas** matérialisés en FD ici (on ne
    /// fournit pas de vrai descripteur), évitant toute fermeture parasite.
    pub fn decode_2b_recvmsg(
        res: i32,
        controllen: u32,
        namelen: u32,
        msg_flags: i32,
        control: Vec<u8>,
        name: Vec<u8>,
    ) {
        let mut name_storage = Box::new(crate::net::RawSockaddrStorage {
            bytes: [0u8; crate::net::MAX_SOCKADDR_LEN],
        });
        let take = name.len().min(crate::net::MAX_SOCKADDR_LEN);
        name_storage.bytes[..take].copy_from_slice(&name[..take]);
        let state = crate::io_uring::owned::RecvMsgState {
            msghdr: Box::new(raw::Msghdr {
                msg_namelen: namelen,
                msg_controllen: u64::from(controllen),
                msg_flags,
                ..raw::Msghdr::default()
            }),
            iovecs: Vec::new().into_boxed_slice(),
            buffers: Vec::new(),
            name: name_storage,
            control: control.into_boxed_slice(),
        };
        let completion = Completion {
            token: SubmissionToken::new(0, 0),
            res,
            raw_flags: 0,
            payload: Some(OwnedOp::RecvMsg(Box::new(state))),
            multishot: false,
        };
        if let Ok((_msg, meta)) = completion.into_receive_message_result() {
            let _ = meta.payload_truncated();
            let _ = meta.control_truncated();
            // Ne pas `drop` les FD ici : ce sont des `i32` arbitraires enveloppés
            // en `OwnedFd` ; on les **oublie** pour éviter de fermer des FD réels
            // du processus de fuzz (totalité sans effet de bord).
            for fd in meta.fds {
                core::mem::forget(fd);
            }
        }
    }

    /// Décode les **résultats kernel externes** des accesseurs 2c (`poll`,
    /// `waitid`) pour tout `res`. Invariant de **totalité** : `into_poll_result`
    /// (bitset d'événements écrit par le kernel) et `into_waitid_result` (tampon
    /// `siginfo` rempli par le kernel) ne paniquent ni ne débordent. Le tampon
    /// `siginfo` est de la **mémoire pure** (aucun FD) ⇒ droppé normalement.
    pub fn decode_2c_results(res: i32) {
        let token = SubmissionToken::new(0, 0);
        let poll = Completion {
            token,
            res,
            raw_flags: 0,
            payload: None,
            multishot: false,
        };
        let _ = poll.into_poll_result();
        let waitid = Completion {
            token,
            res,
            raw_flags: 0,
            payload: Some(OwnedOp::Waitid(Box::new(
                air_sys_types::signal::SignalInfo::zeroed(),
            ))),
            multishot: false,
        };
        if let Ok(info) = waitid.into_waitid_result() {
            let _ = info.as_bytes();
        }
    }

    /// Décode un CQE (champs bruts kernel) et exerce toutes les interprétations
    /// de [`Completion`] : aucune ne doit paniquer pour quelque entrée que ce
    /// soit (`res` incluant `i32::MIN`, flags arbitraires).
    pub fn decode_cqe(user_data: u64, res: i32, raw_flags: u32) {
        let completion = Completion {
            token: SubmissionToken::from_user_data(user_data),
            res,
            raw_flags,
            payload: None,
            multishot: false,
        };
        let _ = completion.token();
        let _ = completion.raw_result();
        let _ = completion.flags();
        let _ = completion.has_more();
        let _ = completion.is_notif();
        let _ = completion.buffer_id();
        let _ = completion.socket_has_pending_data();
        let _ = completion.completed();
        let _ = completion.into_result();
    }

    /// Décode une **complétion brute** (Temps 4) à partir de **données kernel
    /// externes** arbitraires (`user_data`/`res`/`flags`, Principe 3). Invariant de
    /// **totalité** : aucune entrée ne panique ; le routage du tag (§5) est total
    /// (brut ⇔ bit 63 posé) ; un `user_data` **non tagué** hostile passé au
    /// décodage géré (`SubmissionToken::from_user_data`) reste borné (jamais d'OOB,
    /// jamais de panic). Couvre la frontière de décode brut/géré coexistant.
    pub fn decode_raw_cqe(user_data: u64, res: i32, flags: u32) {
        let raw_cqe = raw::RawCompletionQueueEntry {
            user_data,
            res,
            flags,
        };
        // Lecture totale des champs (POD) — jamais de panic.
        let _ = raw_cqe.user_data;
        let _ = raw_cqe.res;
        let _ = raw_cqe.flags;
        // Routage du tag : exactement deux classes, exhaustives.
        if raw_cqe.user_data & raw::RAW_USER_DATA_TAG == 0 {
            // Classe « gérée » : le décodage slab doit rester borné même sur un
            // `user_data` hostile non tagué (S1).
            let _ = SubmissionToken::from_user_data(raw_cqe.user_data);
        }
    }

    /// Invariant de soundness S1 : un `user_data` **hostile** (slot arbitraire,
    /// potentiellement ≥ capacité) passé à `slab.complete` doit être **borné**
    /// (rejeté en périmé via `get`), jamais indexer le slab hors-bornes.
    pub fn slab_complete_is_bounded(capacity: u8, hostile_user_data: &[u64]) {
        let cap = NonZeroU32::new(u32::from(capacity).max(1)).expect("≥ 1");
        let mut slab = InflightSlab::with_capacity(cap);
        // Quelques réservations réelles pour avoir des slots en vol.
        let mut tokens = Vec::new();
        for _ in 0..u32::from(capacity).min(4) {
            if let Ok(t) = slab.reserve(None) {
                tokens.push(t);
            }
        }
        // Complétions hostiles entrelacées : aucune ne doit paniquer/OOB.
        for &user_data in hostile_user_data {
            let _ = slab.complete(user_data, user_data & 1 == 0);
        }
        for token in tokens {
            let _ = slab.complete(token.to_user_data(), false);
        }
    }

    /// Décode les tailles d'anneau depuis des `io_uring_params` bruts : toute
    /// combinaison d'entrées/offsets/features ⇒ `Ok`/`Err(EINVAL)`, jamais
    /// d'overflow ni de panic (arithmétique checked).
    pub fn ring_sizes_decode(
        sq_entries: u32,
        cq_entries: u32,
        sq_array_off: u32,
        cq_cqes_off: u32,
        features: u32,
        setup_bits: u32,
    ) {
        let mut params = raw::IoUringParams {
            sq_entries,
            cq_entries,
            features,
            ..raw::IoUringParams::default()
        };
        params.sq_off.array = sq_array_off;
        params.cq_off.cqes = cq_cqes_off;
        let _ = ring_sizes(&params, SetupFlags::from_bits_truncate(setup_bits));
    }
}

/// Itérateur sur les complétions disponibles d'un [`IoUring`] (emprunte le ring).
pub struct CompletionIter<'ring> {
    ring: &'ring mut IoUring,
}

impl Iterator for CompletionIter<'_> {
    type Item = Completion;

    fn next(&mut self) -> Option<Completion> {
        self.ring.harvest_ready()
    }
}

// ---------------------------------------------------------------------------
// Capacités, annulation, sandbox (types couplés au wrapper)
// ---------------------------------------------------------------------------

/// Miroir typé de `struct io_uring_params` (entrées/sorties de
/// `io_uring_setup(2)`).
///
/// Porte les setup flags demandés, les profondeurs effectives
/// (`sq_entries`/`cq_entries`, arrondies par le kernel), les `features`
/// négociées et les offsets d'anneau. Le layout `#[repr(C)]` réel est posé en
/// Pass B (les champs ABI conservent leurs noms kernel, ADR-029 zone
/// d'interface). Opaque au Temps 1.
#[derive(Debug, Clone, Copy)]
pub struct IoUringParams {
    // Layout #[repr(C)] complet posé en Pass B.
    _opaque: [u8; 0],
}

/// Features io_uring du kernel courant (axe G, 16 features en 6.12). Lues dans
/// `io_uring_params.features` après setup, exposées par **prédicats stables**.
#[derive(Debug, Clone, Copy)]
pub struct IoUringCapabilities {
    // Champ interne (Pass B) : bitmask IORING_FEAT_*.
    features: u32,
}

impl IoUringCapabilities {
    /// Vrai si le bit de feature `bit` (un `IORING_FEAT_*`) est négocié.
    fn has(&self, bit: u32) -> bool {
        self.features & bit != 0
    }

    /// `IORING_FEAT_SINGLE_MMAP` : SQ et CQ partagent une seule mmap.
    #[must_use]
    pub fn single_mmap(&self) -> bool {
        self.has(raw::IORING_FEAT_SINGLE_MMAP)
    }
    /// `IORING_FEAT_NODROP` : la CQ ne perd pas de complétions (overflow retenu).
    #[must_use]
    pub fn nodrop(&self) -> bool {
        self.has(raw::IORING_FEAT_NODROP)
    }
    /// `IORING_FEAT_SUBMIT_STABLE` : données de soumission stables après `enter`.
    #[must_use]
    pub fn submit_stable(&self) -> bool {
        self.has(raw::IORING_FEAT_SUBMIT_STABLE)
    }
    /// `IORING_FEAT_RW_CUR_POS` : offset `-1` = position courante du fichier.
    #[must_use]
    pub fn rw_cur_pos(&self) -> bool {
        self.has(raw::IORING_FEAT_RW_CUR_POS)
    }
    /// `IORING_FEAT_CUR_PERSONALITY` : applique la personnalité courante.
    #[must_use]
    pub fn cur_personality(&self) -> bool {
        self.has(raw::IORING_FEAT_CUR_PERSONALITY)
    }
    /// `IORING_FEAT_FAST_POLL` : poll interne rapide.
    #[must_use]
    pub fn fast_poll(&self) -> bool {
        self.has(raw::IORING_FEAT_FAST_POLL)
    }
    /// `IORING_FEAT_POLL_32BITS` : masques de poll 32 bits.
    #[must_use]
    pub fn poll_32bits(&self) -> bool {
        self.has(raw::IORING_FEAT_POLL_32BITS)
    }
    /// `IORING_FEAT_SQPOLL_NONFIXED` : SQPOLL sans FD fixes obligatoires.
    #[must_use]
    pub fn sqpoll_nonfixed(&self) -> bool {
        self.has(raw::IORING_FEAT_SQPOLL_NONFIXED)
    }
    /// `IORING_FEAT_EXT_ARG` : argument étendu d'`enter` (timeout d'attente).
    #[must_use]
    pub fn ext_arg(&self) -> bool {
        self.has(raw::IORING_FEAT_EXT_ARG)
    }
    /// `IORING_FEAT_NATIVE_WORKERS` : workers io-wq natifs.
    #[must_use]
    pub fn native_workers(&self) -> bool {
        self.has(raw::IORING_FEAT_NATIVE_WORKERS)
    }
    /// `IORING_FEAT_RSRC_TAGS` : étiquetage des ressources enregistrées.
    #[must_use]
    pub fn rsrc_tags(&self) -> bool {
        self.has(raw::IORING_FEAT_RSRC_TAGS)
    }
    /// `IORING_FEAT_CQE_SKIP` : support de `IOSQE_CQE_SKIP_SUCCESS`.
    #[must_use]
    pub fn cqe_skip(&self) -> bool {
        self.has(raw::IORING_FEAT_CQE_SKIP)
    }
    /// `IORING_FEAT_LINKED_FILE` : résolution de FD dans les chaînes liées.
    #[must_use]
    pub fn linked_file(&self) -> bool {
        self.has(raw::IORING_FEAT_LINKED_FILE)
    }
    /// `IORING_FEAT_REG_REG_RING` : enregistrement du ring fd via ring enregistré.
    #[must_use]
    pub fn reg_reg_ring(&self) -> bool {
        self.has(raw::IORING_FEAT_REG_REG_RING)
    }
    /// `IORING_FEAT_RECVSEND_BUNDLE` : recv/send groupés (bundle).
    #[must_use]
    pub fn recvsend_bundle(&self) -> bool {
        self.has(raw::IORING_FEAT_RECVSEND_BUNDLE)
    }
    /// `IORING_FEAT_MIN_TIMEOUT` : timeout minimal d'attente (`ABS_TIMER`).
    #[must_use]
    pub fn min_timeout(&self) -> bool {
        self.has(raw::IORING_FEAT_MIN_TIMEOUT)
    }
}

/// Cible d'une annulation synchrone ([`IoUring::sync_cancel`]).
///
/// Mappée sur les flags `IORING_ASYNC_CANCEL_*`. Le paramètre de durée de vie
/// `'fd` borne l'emprunt du descripteur ciblé par [`CancelTarget::Fd`].
#[derive(Debug, Clone, Copy)]
pub enum CancelTarget<'fd> {
    /// Annule l'opération identifiée par ce jeton (flag `USERDATA`).
    Token(SubmissionToken),
    /// Annule toutes les opérations portant sur ce descripteur (flag `FD`).
    Fd(BorrowedFd<'fd>),
    /// Annule toutes les opérations de cet opcode (flag `OP`).
    Op(IoUringOpcode),
    /// Annule **toutes** les opérations en vol (flag `ANY`).
    Any,
}

/// Restriction appliquée à un ring **avant** son activation (décision S3 ;
/// `struct io_uring_restriction`).
///
/// Posée via [`IoUringBuilder::restrict`], elle réduit la surface d'attaque du
/// ring (capability, Temps 3f / [`sandbox`]). Le ring est créé désactivé
/// (`R_DISABLED`) puis activé par [`IoUring::enable`].
#[derive(Debug, Clone, Copy)]
pub enum Restriction {
    /// N'autoriser que cet opcode de soumission.
    AllowOp(IoUringOpcode),
    /// N'autoriser que ce register opcode (numéro `IORING_REGISTER_*`).
    AllowRegister(u8),
    /// Flags SQE (`IOSQE_*`) autorisés.
    SqeFlagsAllowed(SubmitOptions),
    /// Flags SQE requis sur chaque soumission.
    SqeFlagsRequired(SubmitOptions),
}

#[cfg(test)]
mod token_tests {
    use super::SubmissionToken;

    #[test]
    fn user_data_round_trips_slot_and_generation() {
        for &(slot, generation) in &[
            (0u32, 0u32),
            (1, 0),
            (0, 1),
            (0xABCD, 0x1234),
            (u32::MAX, u32::MAX),
            (u32::MAX, 0),
            (0, u32::MAX),
        ] {
            let token = SubmissionToken::new(slot, generation);
            let decoded = SubmissionToken::from_user_data(token.to_user_data());
            assert_eq!(decoded.slot(), slot);
            assert_eq!(decoded.generation(), generation);
            assert_eq!(decoded, token);
        }
    }

    #[test]
    fn user_data_layout_is_generation_high_slot_low() {
        let token = SubmissionToken::new(0x0000_0007, 0x0000_0003);
        // generation dans les 32 bits hauts, slot dans les 32 bits bas.
        assert_eq!(token.to_user_data(), 0x0000_0003_0000_0007);
    }

    #[test]
    fn from_user_data_splits_halves() {
        let token = SubmissionToken::from_user_data(0xDEAD_BEEF_CAFE_F00D);
        assert_eq!(token.slot(), 0xCAFE_F00D);
        assert_eq!(token.generation(), 0xDEAD_BEEF);
    }

    proptest::proptest! {
        /// `user_data = (generation << 32) | slot` est bijectif sur tout
        /// `(slot, generation)` ∈ (u32, u32) : encodage/décodage sans perte.
        #[test]
        fn user_data_is_bijective(slot: u32, generation: u32) {
            let token = SubmissionToken::new(slot, generation);
            let decoded = SubmissionToken::from_user_data(token.to_user_data());
            proptest::prop_assert_eq!(decoded.slot(), slot);
            proptest::prop_assert_eq!(decoded.generation(), generation);
            proptest::prop_assert_eq!(decoded, token);
        }
    }
}

#[cfg(test)]
mod construction_tests {
    // Tests d'intégration kernel (cible 6.12) : exécutés sur les exécuteurs
    // Linux (speedy/raspi). Couvrent la construction du ring, la lecture des
    // features et le `Drop` propre (ring vide).
    use super::{IoUring, IoUringBuilder, SetupFlags};
    use core::num::NonZeroU32;

    fn entries(n: u32) -> NonZeroU32 {
        NonZeroU32::new(n).expect("entries non nul")
    }

    #[test]
    fn new_creates_a_ring_and_reports_capabilities() {
        let ring = IoUring::new(entries(8)).expect("io_uring_setup doit réussir sur 6.12");
        // En 6.12, SINGLE_MMAP et NODROP sont toujours présents.
        assert!(
            ring.capabilities().single_mmap(),
            "SINGLE_MMAP attendu en 6.12"
        );
        assert!(ring.capabilities().nodrop(), "NODROP attendu en 6.12");
        assert_eq!(ring.in_flight(), 0);
        // `entries` est arrondi à la puissance de 2 ≥ : au moins 8 places SQ.
        assert!(ring.submission_queue_space_left() >= 8);
        assert!(!ring.completion_queue_overflowed());
        // `Drop` (ring vide) ne doit pas paniquer.
    }

    #[test]
    fn builder_with_recommended_flags_builds() {
        let ring = IoUringBuilder::new(entries(16))
            .with_flags(SetupFlags::SINGLE_ISSUER | SetupFlags::DEFER_TASKRUN)
            .build()
            .expect("ring avec SINGLE_ISSUER|DEFER_TASKRUN");
        assert_eq!(ring.in_flight(), 0);
        assert!(ring.submission_queue_space_left() >= 16);
    }

    #[test]
    fn explicit_cq_size_is_honored() {
        let ring = IoUringBuilder::new(entries(8))
            .with_completion_queue_entries(entries(64))
            .build()
            .expect("ring avec CQSIZE explicite");
        // La CQ demandée (64) ≥ SQ (8) ; le slab par défaut suit cq_entries.
        assert_eq!(ring.in_flight(), 0);
    }

    #[test]
    fn distinct_rings_are_independent() {
        let a = IoUring::new(entries(8)).expect("ring a");
        let b = IoUring::new(entries(8)).expect("ring b");
        assert_eq!(a.in_flight(), 0);
        assert_eq!(b.in_flight(), 0);
    }

    #[test]
    fn probe_reports_core_ops_supported() {
        use super::IoUringOpcode;
        let ring = IoUring::new(entries(8)).expect("ring");
        // En 6.12, ces opcodes sont tous supportés (probe via REGISTER_PROBE).
        assert!(ring.supports_op(IoUringOpcode::Nop), "NOP supporté");
        assert!(ring.supports_op(IoUringOpcode::Read));
        assert!(ring.supports_op(IoUringOpcode::Write));
        assert!(ring.supports_op(IoUringOpcode::Accept));
        assert!(ring.supports_op(IoUringOpcode::Openat2));
    }
}

#[cfg(test)]
mod submission_tests {
    // Round-trip NOP end-to-end sur kernel 6.12 (soumission §6 + complétion §7).
    use super::{IoUring, IoUringBuilder, SubmitOptions};
    use air_sys_types::Errno;
    use core::num::NonZeroU32;
    use core::time::Duration;

    fn entries(n: u32) -> NonZeroU32 {
        NonZeroU32::new(n).expect("entries non nul")
    }

    #[test]
    fn nop_round_trips_with_submit_and_wait() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        let token = ring.submit_nop().expect("submit_nop");
        assert_eq!(ring.in_flight(), 1);
        let submitted = ring.submit_and_wait(1).expect("submit_and_wait");
        assert_eq!(submitted, 1);
        let completion = ring.wait_completion().expect("wait_completion");
        assert_eq!(completion.token(), token, "user_data round-trip");
        assert_eq!(completion.raw_result(), 0, "NOP res == 0");
        assert!(completion.completed().is_ok());
        assert!(!completion.has_more());
        assert_eq!(ring.in_flight(), 0, "slot S1 libéré à la complétion");
    }

    #[test]
    fn submit_returns_count_and_completions_iterates() {
        let mut ring = IoUring::new(entries(16)).expect("ring");
        for _ in 0..3 {
            ring.submit_nop().expect("submit_nop");
        }
        assert_eq!(ring.in_flight(), 3);
        assert_eq!(ring.submit_and_wait(3).expect("submit_and_wait"), 3);
        let mut count = 0;
        while count < 3 {
            // Draine au fur et à mesure (les 3 CQE peuvent arriver groupés).
            for completion in ring.completions() {
                assert_eq!(completion.raw_result(), 0);
                count += 1;
            }
        }
        assert_eq!(count, 3);
        assert_eq!(ring.in_flight(), 0);
    }

    #[test]
    fn try_completion_is_none_before_any_submission() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        assert!(ring.try_completion().is_none());
    }

    #[test]
    fn timeout_expires_on_empty_ring() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        let res = ring
            .wait_completion_timeout(Duration::from_millis(20))
            .expect("pas d'erreur");
        assert!(res.is_none(), "aucune complétion ⇒ None à l'expiration");
    }

    #[test]
    fn timeout_returns_completion_when_available() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        ring.submit_nop().expect("submit_nop");
        ring.submit().expect("submit");
        let res = ring
            .wait_completion_timeout(Duration::from_secs(1))
            .expect("pas d'erreur");
        let completion = res.expect("une complétion avant expiration");
        assert_eq!(completion.raw_result(), 0);
    }

    #[test]
    fn slab_back_pressure_returns_ebusy() {
        // Slab limité à 1 : la 2ᵉ op en vol est refusée AVANT tout syscall.
        let mut ring = IoUringBuilder::new(entries(8))
            .max_inflight(entries(1))
            .build()
            .expect("ring");
        let _t = ring.submit_nop().expect("1ʳᵉ op");
        assert_eq!(ring.submit_nop(), Err(Errno::EBUSY), "slab plein ⇒ EBUSY");
        // Après complétion, on peut re-soumettre.
        ring.submit_and_wait(1).expect("submit_and_wait");
        let _c = ring.wait_completion().expect("complétion");
        assert_eq!(ring.in_flight(), 0);
        // Ré-soumission possible après libération ; drainée pour laisser le ring
        // quiescent au Drop (la quiescence automatique arrive à l'incrément 5).
        ring.submit_nop().expect("ré-soumission après libération");
        ring.submit_and_wait(1).expect("submit_and_wait 2");
        let _c2 = ring.wait_completion().expect("complétion 2");
        assert_eq!(ring.in_flight(), 0);
    }

    #[test]
    fn skip_cqe_on_success_frees_slot_at_submission() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        ring.with(SubmitOptions::default().skip_cqe_on_success());
        ring.submit_nop().expect("submit_nop skip");
        // Slot libéré dès la soumission : aucune op en vol.
        assert_eq!(ring.in_flight(), 0);
        assert_eq!(ring.submit().expect("submit"), 1);
    }
}

#[cfg(test)]
mod coverage_tests {
    // Complète la couverture du cœur (prédicats de capacités, mapping d'opcodes,
    // méthodes builder/Completion, chemin de fuite S2) jusqu'à 100 % hors
    // exceptions documentées (docs/COVERAGE-EXCEPTIONS.md).
    use super::owned::OwnedOp;
    use super::syscall::sim::{self, Syscall};
    use super::{
        CancelTarget, Completion, CompletionFlags, IoUring, IoUringBuilder, IoUringOpcode,
        SetupFlags, SubmissionToken, SubmitOptions, opcode_number,
    };
    use air_sys_types::Errno;
    use air_sys_types::fd::BorrowedFd;
    use core::num::NonZeroU32;
    use core::time::Duration;

    fn entries(n: u32) -> NonZeroU32 {
        NonZeroU32::new(n).expect("entries non nul")
    }

    /// Appelle les 16 prédicats de `IoUringCapabilities` (axe G).
    #[test]
    fn all_capability_predicates_are_callable() {
        let ring = IoUring::new(entries(8)).expect("ring");
        let caps = ring.capabilities();
        // En 6.12, ces deux-là sont vrais ; les autres : on exerce juste l'appel.
        assert!(caps.single_mmap() && caps.nodrop());
        let _ = caps.submit_stable();
        let _ = caps.rw_cur_pos();
        let _ = caps.cur_personality();
        let _ = caps.fast_poll();
        let _ = caps.poll_32bits();
        let _ = caps.sqpoll_nonfixed();
        let _ = caps.ext_arg();
        let _ = caps.native_workers();
        let _ = caps.rsrc_tags();
        let _ = caps.cqe_skip();
        let _ = caps.linked_file();
        let _ = caps.reg_reg_ring();
        let _ = caps.recvsend_bundle();
        let _ = caps.min_timeout();
    }

    /// Couvre les 55 bras de `opcode_number` (le bras `_` = futur opcode
    /// `#[non_exhaustive]`, inatteignable, est consigné en exception).
    #[test]
    fn opcode_number_maps_all_retained_opcodes() {
        use IoUringOpcode::{
            Accept, AsyncCancel, Bind, Close, Connect, EpollCtl, Fadvise, Fallocate, Fgetxattr,
            FilesUpdate, FixedFdInstall, Fsetxattr, Fsync, Ftruncate, FutexWait, FutexWaitv,
            FutexWake, Getxattr, LinkTimeout, Linkat, Listen, Madvise, Mkdirat, MsgRing, Nop,
            Openat2, PollAdd, PollRemove, Read, ReadFixed, ReadMultishot, Readv, Recv, Recvmsg,
            Renameat, Send, SendZc, Sendmsg, SendmsgZc, Setxattr, Shutdown, Socket, Splice, Statx,
            Symlinkat, SyncFileRange, Tee, Timeout, TimeoutRemove, Unlinkat, UringCmd, Waitid,
            Write, WriteFixed, Writev,
        };
        let all = [
            Nop,
            Readv,
            Writev,
            Fsync,
            ReadFixed,
            WriteFixed,
            PollAdd,
            PollRemove,
            SyncFileRange,
            Sendmsg,
            Recvmsg,
            Timeout,
            TimeoutRemove,
            Accept,
            AsyncCancel,
            LinkTimeout,
            Connect,
            Fallocate,
            Close,
            FilesUpdate,
            Statx,
            Read,
            Write,
            Fadvise,
            Madvise,
            Send,
            Recv,
            Openat2,
            EpollCtl,
            Splice,
            Tee,
            Shutdown,
            Renameat,
            Unlinkat,
            Mkdirat,
            Symlinkat,
            Linkat,
            MsgRing,
            Fsetxattr,
            Setxattr,
            Fgetxattr,
            Getxattr,
            Socket,
            UringCmd,
            SendZc,
            SendmsgZc,
            ReadMultishot,
            Waitid,
            FutexWait,
            FutexWake,
            FutexWaitv,
            FixedFdInstall,
            Ftruncate,
            Bind,
            Listen,
        ];
        assert_eq!(all.len(), 55);
        assert_eq!(opcode_number(Nop), 0);
        assert_eq!(opcode_number(Listen), 57);
        for op in all {
            assert!(opcode_number(op) < 58);
        }
    }

    /// Exerce les méthodes builder non couvertes par le chemin nominal.
    #[test]
    fn builder_configurators_are_exercised() {
        let base = IoUring::new(entries(8)).expect("ring de base");
        let ring = IoUringBuilder::new(entries(8))
            .with_completion_queue_entries(entries(32))
            .max_inflight(entries(4))
            .with_sqpoll_idle(Duration::from_millis(10))
            .with_sqpoll_cpu(0)
            .attach_work_queue(&base)
            .with_flags(SetupFlags::SINGLE_ISSUER)
            .build()
            .expect("ring configuré (ATTACH_WQ partagé)");
        assert_eq!(ring.in_flight(), 0);
    }

    /// Exerce tous les accesseurs de `Completion` (round-trip NOP).
    #[test]
    fn completion_accessors_are_exercised() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        let token = ring.submit_nop().expect("nop");
        ring.submit_and_wait(1).expect("submit");
        let completion = ring.wait_completion().expect("complétion");
        assert_eq!(completion.token(), token);
        assert_eq!(completion.raw_result(), 0);
        let _ = completion.flags();
        assert!(!completion.has_more());
        assert!(!completion.is_notif());
        assert_eq!(completion.buffer_id(), None);
        assert!(!completion.socket_has_pending_data());
        assert!(completion.completed().is_ok());
        // NOP : pas de buffer transféré ⇒ buffer vide, 0 octet.
        let (buffer, length) = completion.into_buffer_result().expect("succès");
        assert!(buffer.is_empty());
        assert_eq!(length, 0);
    }

    /// `with(SubmitOptions::drain().force_async())` : exerce les combinateurs.
    #[test]
    fn submit_options_combinators_are_exercised() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        ring.with(SubmitOptions::default().drain().force_async());
        ring.submit_nop().expect("nop avec options");
        ring.submit_and_wait(1).expect("submit");
        let _ = ring.wait_completion().expect("complétion");
    }

    /// Chemin de **fuite contrôlée** S2 : si la quiescence n'aboutit pas
    /// (drainage en échec), `shutdown` fuite les ressources (sound) et rend
    /// `Err`. On force l'échec en injectant des `enter` en erreur pendant le
    /// drainage (l'op réservée n'est jamais complétée).
    #[test]
    fn teardown_leak_path_when_quiescence_fails() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        ring.submit_nop().expect("op réservée, jamais complétée");
        // `sync_cancel` (register) réel ; chaque `enter` de drainage échoue
        // immédiatement (assez d'injections pour épuiser la boucle bornée).
        for _ in 0..80 {
            sim::inject(Syscall::Enter, -4); // EINTR
        }
        // Quiescence impossible ⇒ fuite contrôlée ⇒ Err (jamais d'UAF/panic).
        assert_eq!(ring.shutdown(), Err(Errno::EBUSY));
        sim::clear();
    }

    /// `submit` sans rien en attente : aucun syscall, `Ok(0)`.
    #[test]
    fn submit_with_nothing_pending_returns_zero() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        assert_eq!(ring.submit(), Ok(0));
    }

    /// SQ pleine ⇒ `submit_nop` rend `EBUSY` (back-pressure SQ, avant le slab).
    #[test]
    fn submit_nop_on_full_sq_returns_ebusy() {
        // SQ = 4 entrées, slab = 8 : la SQ se remplit en premier.
        let mut ring = IoUringBuilder::new(entries(4))
            .max_inflight(entries(8))
            .build()
            .expect("ring");
        for _ in 0..4 {
            ring.submit_nop().expect("remplissage SQ");
        }
        assert_eq!(ring.submit_nop(), Err(Errno::EBUSY), "SQ pleine ⇒ EBUSY");
        // Nettoyage : draine les 4.
        ring.submit_and_wait(4).expect("submit");
        let mut n = 0;
        while n < 4 {
            for _ in ring.completions() {
                n += 1;
            }
        }
    }

    /// Couvre les variantes `Token`/`Fd`/`Op` de `sync_cancel` (register injecté).
    #[test]
    fn sync_cancel_target_variants_are_exercised() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        let token = SubmissionToken::new(0, 0);
        sim::inject(Syscall::Register, 0);
        assert_eq!(ring.sync_cancel(CancelTarget::Token(token)), Ok(0));
        sim::inject(Syscall::Register, 0);
        // SAFETY: fd 0 (stdin) emprunté brièvement pour construire la cible ;
        // l'appel register est intercepté (aucune annulation réelle).
        let borrowed = unsafe { BorrowedFd::borrow_raw(0) };
        assert_eq!(ring.sync_cancel(CancelTarget::Fd(borrowed)), Ok(0));
        sim::inject(Syscall::Register, 0);
        assert_eq!(
            ring.sync_cancel(CancelTarget::Op(IoUringOpcode::Read)),
            Ok(0)
        );
        sim::clear();
    }

    /// `enable` réussit quand `REGISTER_ENABLE_RINGS` rend `0` (ring désactivé).
    #[test]
    fn enable_succeeds_when_register_ok() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        sim::inject(Syscall::Register, 0);
        assert_eq!(ring.enable(), Ok(()));
        sim::clear();
    }

    /// Construit un ring avec `SQE128`/`CQE32` (couvre les tailles 128/32).
    #[test]
    fn build_with_sqe128_and_cqe32() {
        let ring = IoUringBuilder::new(entries(8))
            .with_flags(SetupFlags::SQE128 | SetupFlags::CQE32)
            .build()
            .expect("ring SQE128|CQE32 (supporté en 6.12)");
        assert_eq!(ring.in_flight(), 0);
    }

    // NB : le flux `restrict → build → enable`, l'application effective des
    // restrictions (`REGISTER_RESTRICTIONS`) et leur sémantique default-deny /
    // immuabilité sont couverts par les tests d'intégration kernel du sous-module
    // `sandbox` (Temps 3f).

    /// `Completion::buffer_id` quand le flag `BUFFER` est posé (id en bits hauts).
    #[test]
    fn completion_buffer_id_decodes_high_bits() {
        let raw_flags = CompletionFlags::BUFFER.bits() | (7u32 << 16);
        let completion = Completion {
            token: SubmissionToken::new(0, 0),
            res: 0,
            raw_flags,
            payload: None,
            multishot: false,
        };
        assert_eq!(completion.buffer_id(), Some(7));
    }

    /// `Completion` en échec : `res < 0` ⇒ `Err(errno)` ; `i32::MIN` ⇒ `EINVAL`.
    #[test]
    fn completion_error_results_are_decoded() {
        let failed = Completion {
            token: SubmissionToken::new(0, 0),
            res: -22, // EINVAL
            raw_flags: 0,
            payload: Some(OwnedOp::Bytes(vec![1, 2, 3])),
            multishot: false,
        };
        assert_eq!(failed.completed(), Err(Errno::EINVAL));
        assert_eq!(failed.into_result(), Err(Errno::EINVAL));

        let pathological = Completion {
            token: SubmissionToken::new(0, 0),
            res: i32::MIN, // `checked_neg` ⇒ None ⇒ EINVAL (défensif)
            raw_flags: 0,
            payload: None,
            multishot: false,
        };
        assert_eq!(pathological.into_result(), Err(Errno::EINVAL));
    }
}

#[cfg(test)]
mod simulator_tests {
    // Simulateur de syscalls : injecte des `-errno` aux frontières
    // setup/enter/register (sans kernel pour l'appel intercepté) afin de PROUVER
    // les contrats de comportement couche 0 (ADR-021) et de rendre atteignables
    // les branches d'erreur (levier du 100 % branches, incrément 8). L'errno
    // injecté transite par le MÊME décode (`errno_from_negative_syscall_ret`).
    use super::syscall::sim::{self, Syscall};
    use super::{CancelTarget, IoUring, IoUringOpcode};
    use air_sys_types::Errno;
    use core::num::NonZeroU32;
    use core::time::Duration;

    fn entries(n: u32) -> NonZeroU32 {
        NonZeroU32::new(n).expect("entries non nul")
    }

    /// `ENOSYS` au setup (kernel sans io_uring) ⇒ erreur PROPRE, pas de panic.
    #[test]
    fn setup_enosys_degrades_gracefully() {
        sim::clear();
        sim::inject(Syscall::Setup, -38);
        assert_eq!(IoUring::new(entries(8)).err(), Some(Errno::ENOSYS));
        sim::clear();
    }

    /// Autres erreurs de setup remontées telles quelles (sans masquage).
    #[test]
    fn setup_errors_are_surfaced_verbatim() {
        for (raw, expected) in [
            (-12i64, Errno::ENOMEM),
            (-22, Errno::EINVAL),
            (-1, Errno::EPERM),
        ] {
            sim::clear();
            sim::inject(Syscall::Setup, raw);
            assert_eq!(IoUring::new(entries(8)).err(), Some(expected));
        }
        sim::clear();
    }

    /// `EINTR` sur `submit_and_wait` ⇒ REMONTÉ, JAMAIS retried (ADR-021 #2).
    /// Une seule injection : si l'appel rebouclait, il ferait un vrai syscall —
    /// l'assert `Err(EINTR)` prouve l'absence de retry.
    #[test]
    fn submit_and_wait_raises_eintr_without_retry() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring réel");
        sim::inject(Syscall::Enter, -4); // EINTR, une seule fois
        assert_eq!(ring.submit_and_wait(1), Err(Errno::EINTR));
        sim::clear();
    }

    /// `EAGAIN` sur `submit` (ring avec op en attente) ⇒ back-pressure propre.
    #[test]
    fn submit_raises_eagain_cleanly() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        ring.submit_nop().expect("op en attente");
        sim::inject(Syscall::Enter, -11); // EAGAIN
        assert_eq!(ring.submit(), Err(Errno::EAGAIN));
        // Nettoyage : soumission/complétion réelles pour quiescer le ring.
        ring.submit_and_wait(1).expect("submit réel");
        let _ = ring.wait_completion().expect("complétion");
        sim::clear();
    }

    /// Compte de soumission partiel cohérent : `enter` rend `2` sur `3` soumis.
    #[test]
    fn submit_returns_partial_count_consistently() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        for _ in 0..3 {
            ring.submit_nop().expect("nop");
        }
        sim::inject(Syscall::Enter, 2); // le kernel n'en a consommé que 2
        assert_eq!(ring.submit(), Ok(2));
        // Nettoyage : draine réellement les 3 (la tail est publiée).
        ring.submit_and_wait(3).expect("submit réel");
        let mut harvested = 0;
        while harvested < 3 {
            for _ in ring.completions() {
                harvested += 1;
            }
        }
        sim::clear();
    }

    /// `EINTR` sur `wait_completion` ⇒ remonté tel quel.
    #[test]
    fn wait_completion_raises_eintr() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        sim::inject(Syscall::Enter, -4);
        assert_eq!(ring.wait_completion().err(), Some(Errno::EINTR));
        sim::clear();
    }

    /// `wait_completion_timeout` : `ETIME` ⇒ `Ok(None)` ; `EINTR` ⇒ `Err`.
    #[test]
    fn wait_completion_timeout_maps_etime_and_eintr() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        sim::inject(Syscall::Enter, -62); // ETIME
        let timed_out = ring.wait_completion_timeout(Duration::from_millis(1));
        assert!(matches!(timed_out, Ok(None)), "ETIME ⇒ Ok(None)");
        sim::inject(Syscall::Enter, -4); // EINTR
        assert_eq!(
            ring.wait_completion_timeout(Duration::from_millis(1)).err(),
            Some(Errno::EINTR)
        );
        sim::clear();
    }

    /// `sync_cancel` : `ENOENT` (aucune op à annuler) remonté.
    #[test]
    fn sync_cancel_surfaces_enoent() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        sim::inject(Syscall::Register, -2); // ENOENT
        assert_eq!(
            ring.sync_cancel(CancelTarget::Any).err(),
            Some(Errno::ENOENT)
        );
        sim::clear();
    }

    /// `enable` : `EINVAL` remonté tel quel.
    #[test]
    fn enable_surfaces_einval() {
        sim::clear();
        let mut ring = IoUring::new(entries(8)).expect("ring");
        sim::inject(Syscall::Register, -22); // EINVAL
        assert_eq!(ring.enable().err(), Some(Errno::EINVAL));
        sim::clear();
    }

    /// Probe en échec ⇒ tous les opcodes marqués non supportés (conservateur :
    /// force le fallback synchrone, pas de faux positif).
    #[test]
    fn probe_failure_reports_all_ops_unsupported() {
        sim::clear();
        sim::inject(Syscall::Register, -1); // le probe (register) échoue
        let ring = IoUring::new(entries(8)).expect("ring construit malgré probe KO");
        assert!(!ring.supports_op(IoUringOpcode::Nop));
        assert!(!ring.supports_op(IoUringOpcode::Read));
        sim::clear();
    }
}

#[cfg(test)]
mod teardown_tests {
    // Téardown S2 sur kernel 6.12 : shutdown propre, quiescence, Drop sûr.
    use super::IoUring;
    use core::num::NonZeroU32;

    fn entries(n: u32) -> NonZeroU32 {
        NonZeroU32::new(n).expect("entries non nul")
    }

    #[test]
    fn shutdown_on_empty_ring_succeeds() {
        let ring = IoUring::new(entries(8)).expect("ring");
        ring.shutdown().expect("shutdown propre d'un ring vide");
    }

    #[test]
    fn shutdown_quiesces_a_pending_op() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        ring.submit_nop().expect("submit_nop");
        ring.submit().expect("submit");
        // L'op est en vol et non moissonnée : `shutdown` doit quiescer (drainer)
        // avant de libérer, puis réussir.
        ring.shutdown().expect("shutdown quiesce l'op en vol");
    }

    #[test]
    fn drop_with_pending_op_quiesces_without_panic() {
        let mut ring = IoUring::new(entries(8)).expect("ring");
        ring.submit_nop().expect("submit_nop");
        ring.submit().expect("submit");
        // `Drop` implicite en fin de scope : quiesce + libère sans paniquer ni
        // laisser le kernel écrire dans de la mémoire libérée.
        drop(ring);
    }

    #[test]
    fn shutdown_is_not_double_freed_by_drop() {
        // `shutdown` consomme `self` ; son `Drop` interne ne doit pas re-dérouler
        // le téardown (drapeau `disposed`). Si double munmap/close, le kernel ou
        // le runtime paniquerait/abort — l'absence de panique vaut assertion.
        for _ in 0..16 {
            let ring = IoUring::new(entries(8)).expect("ring");
            ring.shutdown().expect("shutdown");
        }
    }
}