poulpy_ckks/

lib.rs

#![feature(f128)]
#![cfg_attr(not(test), deny(clippy::disallowed_methods))]
#![cfg_attr(test, allow(clippy::disallowed_methods))]
#![deny(rustdoc::broken_intra_doc_links)]
//! # poulpy-ckks
//!
//! Backend-agnostic implementation of the CKKS (Cheon-Kim-Kim-Song)
//! homomorphic encryption scheme, built from `poulpy-core` and `poulpy-hal`.
//!
//! Public calls dispatch through explicit backend [`oep`] contracts. Public
//! [`reference`](mod@crate::reference) algorithms compose lower-layer operations;
//! simple CKKS compositions are crate-private derived defaults on the contracts.
//! A backend may replace a method while reusing the reference for other members
//! of its family. Replacements must compute the same circuit and pass parity
//! against a caller-selected validated implementation. Validation is transitive
//! for the operations and parameter ranges covered by those tests.
//!
//! The crate uses a bivariate polynomial representation over the Torus
//! (base-`2^{base2k}` digits) instead of the RNS representation used by
//! most other CKKS libraries. Public precision management is exposed through
//! [`CKKSMeta`]:
//!
//! - `log_delta`: base-2 logarithm of the encoded plaintext scaling factor
//! - `log_sparsity`: base-2 logarithm of the slot replication
//!
//! Remaining homomorphic headroom, `log_budget`, is derived from the wrapped
//! ciphertext or plaintext width as `k() - log_delta`; it is not stored in
//! [`CKKSMeta`].
//!
//! [`CKKSMeta`] also records the [`SlotsKind`] of a value: whether its slots are
//! known to be real, or may carry an imaginary part. Operations compose that
//! claim, keeping `Real` only when every operand is real, so a caller can state
//! it once at encoding time and have the pipelines specialize on it.
//!
//! Together they define the semantic torus width of a value:
//! `k() = log_delta + log_budget`.
//! Storage is rounded up to the next multiple of `base2k`, so the allocated
//! capacity `max_k()` may exceed the effective width `k()`. Arithmetic APIs
//! update this metadata for you; buffers always stay at their allocated
//! width, and allocating a destination at exactly the `k` you want is how
//! results are narrowed.
//!
//! Linear operations (additions, subtractions, plaintext additions, doubling,
//! negation, copies, multiplication by `±i`) do not normalize. Additions,
//! subtractions and doubling clear the wrapped GLWE's canonical flag, the others
//! keep their operand's, and the next operation that reads the digits through a
//! DFT (products, rotations, conjugation, keyswitching, decryption) normalizes a
//! flag-clear operand first. A value several such operations read is best
//! normalized once with `glwe_normalize_assign`, and serializing requires a
//! normalized ciphertext. Each lazy addition can grow the digits by one bit; a
//! sum of `n` terms stays within `i64` while `n <= 2^(63 - base2k)`.
//!
//! ## Modules
//!
//! | Module | Role |
//! |--------|------|
//! | [`approximation`] | Reusable minimax fitting, precision/depth selection, composite sign generation, and prepared interval-mapped polynomial evaluation |
//! | [`encoding`] / [`reference::encoding`] | Canonical slot ordering, quantization, and PaCo/SHIP embeddings, with explicit host reference helpers |
//! | [`layouts`] | CKKS ciphertext/plaintext wrappers and metadata-aware allocation helpers |
//! | [`presets`] | Ready-to-use parameter sets |
//! | [`api`] | The public op traits: leveled arithmetic (add, sub, mul, neg, rotate, conjugate), encryption, decryption, rescale, and scratch sizing |
//! | [`api::CKKSBootstrappingOps`] | API composition of encapsulated ModUp, DFT, and EvalMod; parameterized by [`layouts::BootstrappingPlan`] |
//! | [`api::CKKSPaCoOps`] | PaCo bootstrapping without ModUp or EvalMod; parameterized by [`layouts::PaCoPlan`] and a compiled [`layouts::PaCoContext`] |

use poulpy_core::layouts::{
    Base2K, Degree, GLWEInfos, GLWELayout, GLWEToBackendMut, GLWEToBackendRef, LWEInfos, Rank, TorusPrecision,
};
use poulpy_hal::layouts::Backend;
use poulpy_hal::layouts::CyclotomicOrder;
use poulpy_hal::layouts::Module;
use poulpy_hal::layouts::galois_element;

pub mod api;
pub mod approximation;
pub(crate) mod cosine;
pub(crate) mod delegates;
pub mod reference;

/// Re-exports for use inside this crate's exported macros (e.g.
/// [`impl_ckks_dft_reference`]), so an invoking backend crate does not need
/// `anyhow` as a direct dependency. Not part of the public API.
#[doc(hidden)]
pub mod __macro_reexports {
    pub use anyhow;
}
pub mod encoding;
mod error;
mod eval_lut;
pub mod layouts;
pub mod numerics;
/// One-stop imports for the common CKKS path.
///
/// `use poulpy_ckks::prelude::*;` brings in the op traits (add/sub/mul/…,
/// encrypt/decrypt, scratch sizing), the ciphertext/plaintext containers with
/// their allocation helpers, and the metadata types — everything the
/// encode → encrypt → evaluate → decrypt → decode loop needs from this crate.
/// Key material and the `Module`/scratch machinery come from `poulpy-core` and
/// `poulpy-hal`.
pub mod prelude {
    pub use crate::api::{
        CKKSAddOps, CKKSAllOpsTmpBytes, CKKSApproximationOps, CKKSConjugateOps, CKKSCopyOps, CKKSDecryptOps, CKKSEncodingHostOps,
        CKKSEncodingOps, CKKSEncryptOps, CKKSImagOps, CKKSModuleInfos, CKKSMulOps, CKKSNegOps, CKKSPlaintextVecOps, CKKSPow2Ops,
        CKKSRotateOps, CKKSSubOps,
    };
    pub use crate::layouts::{CKKSCiphertext, CKKSModuleAlloc, CKKSPlaintext, PolynomialApproximation};
    pub use crate::{
        CKKSCompositionError, CKKSError, CKKSInfos, CKKSLayout, CKKSMeta, CKKSResult, CoeffsMeta, Quad, SetCKKSInfos, SlotsKind,
    };
}
pub mod oep;
pub mod polynomial;
pub mod power_basis;
pub mod presets;
pub mod scalar;
#[cfg(feature = "test-utils")]
#[allow(clippy::disallowed_methods)]
pub mod test_suite;
pub use error::{CKKSCompositionError, CKKSError, CKKSResult};
pub(crate) use error::{
    checked_log_budget_sub, checked_mul_ct_log_budget, checked_mul_pt_log_budget, ckks_bail, ckks_ensure, ensure_base2k_match,
    ensure_plaintext_alignment, ensure_plaintext_coeff_in_range, ensure_plaintext_degree_embeds,
};
/// Quad-precision (IEEE 754 binary128) CKKS scalar.
///
/// Always the portable [`scalar::Quad`] newtype over the primitive `f128`, in
/// every configuration. Under the `libquadmath` feature on non-Apple x86_64
/// only its libm-backed math is routed through libquadmath (faster for
/// on-the-fly FFT-table builds); storage, codecs, and exact arithmetic are
/// unchanged, so the type — and its `bytemuck::Pod` encoding — is identical
/// across features.
pub use scalar::Quad;

/// Backend-compatible shared CKKS plaintext storage.
pub trait CKKSPlaintextToBackendRef<BE: Backend>: GLWEToBackendRef<BE> + GLWEInfos + CKKSInfos {}

impl<BE: Backend, T> CKKSPlaintextToBackendRef<BE> for T where T: GLWEToBackendRef<BE> + GLWEInfos + CKKSInfos {}

/// Backend-compatible mutable CKKS plaintext storage.
///
/// Implemented by owned plaintexts and scratch-backed plaintext views alike.
pub trait CKKSPlaintextToBackendMut<BE: Backend>: CKKSPlaintextToBackendRef<BE> + GLWEToBackendMut<BE> {}

impl<BE: Backend, T> CKKSPlaintextToBackendMut<BE> for T where T: CKKSPlaintextToBackendRef<BE> + GLWEToBackendMut<BE> {}

/// Marker bound for CKKS ciphertext type parameters.
///
/// Combines [`GLWEInfos`] (which already implies [`poulpy_core::layouts::LWEInfos`])
/// with [`CKKSInfos`] to collapse the repeated `GLWEInfos + CKKSInfos` pair found
/// throughout the API into a single, named constraint.
pub trait CKKSCtBounds: GLWEInfos + CKKSInfos {}

impl<T: GLWEInfos + CKKSInfos> CKKSCtBounds for T {}

/// Ring-dependent CKKS slot geometry and automorphism identifiers.
pub trait CKKSModuleInfos {
    /// Maximum number of slots: `N` real slots or `N/2` complex slots.
    fn ckks_max_slots(&self) -> usize;

    /// Automorphism identifier used by CKKS rotations and their evaluation keys.
    /// `rotation` is reduced modulo [`Self::ckks_max_slots`], so a negative shift rotates backwards.
    fn ckks_galois_element(&self, rotation: i64) -> i64;
}

impl<BE: Backend> CKKSModuleInfos for Module<BE> {
    fn ckks_max_slots(&self) -> usize {
        (self.cyclotomic_order() / 4) as usize
    }

    fn ckks_galois_element(&self, rotation: i64) -> i64 {
        // 5 has order `max_slots` in the Galois group on both rings.
        galois_element(rotation.rem_euclid(self.ckks_max_slots() as i64), self.cyclotomic_order())
    }
}

/// Which subfield the encoded slots are known to live in.
///
/// The reals are a subring of the complexes, so the two variants are ordered
/// claims rather than exclusive tags: [`SlotsKind::Real`] is the stronger one,
/// [`SlotsKind::Complex`] is always sound. Operations compose the claim with
/// [`SlotsKind::join`], which keeps `Real` only when every operand is `Real`.
/// `Complex` is the default, so a value that never states its kind is never
/// mistaken for a real one.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
pub enum SlotsKind {
    /// Every slot has a zero imaginary part.
    Real,
    /// Slots may carry a nonzero imaginary part.
    #[default]
    Complex,
}

impl SlotsKind {
    /// Kind of a value built from two operands: `Real` only when both are.
    pub fn join(self, other: Self) -> Self {
        match (self, other) {
            (Self::Real, Self::Real) => Self::Real,
            _ => Self::Complex,
        }
    }

    /// Kind of a value that lies in both fields: `Complex` only when both are.
    pub fn meet(self, other: Self) -> Self {
        match (self, other) {
            (Self::Complex, Self::Complex) => Self::Complex,
            _ => Self::Real,
        }
    }

    /// Whether the slots are known to be real.
    pub fn is_real(self) -> bool {
        self == Self::Real
    }
}

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
/// CKKS semantic precision metadata carried by ciphertexts and plaintexts.
///
/// `log_delta` is the scaling precision of the encoded value. The remaining
/// homomorphic headroom (`log_budget`) is *not* stored here: it is derived from
/// the wrapped GLWE's torus width `k` as `log_budget = k - log_delta`.
pub struct CKKSMeta {
    /// Base 2 logarithm of the decimal precision.
    pub log_delta: usize,
    /// Sparse-packing factor: `log2` of the coefficient gap (equivalently, of the
    /// slot replication). Dense packing has `N/2` complex slots in the standard
    /// ring or `N` real slots in the conjugate invariant ring. With
    /// `log_sparsity = s`, `M(X^{2^s})` carries `max_slots >> s` distinct slots,
    /// each replicated `2^s` times.
    ///
    /// A plaintext may store its `M` compactly, at the degree
    /// `ckks_pt_vec_alloc_compact` picks for its slot count; its own `n()` is
    /// then below the ring degree and every consumer reads it through the ring
    /// embedding. `log_sparsity` keeps counting the gap under the ring
    /// embedding, `log2` of the replication among the ring slots,
    /// whatever degree the plaintext is stored at.
    pub log_sparsity: usize,
    /// Subfield the slots are known to live in. See [`SlotsKind`].
    pub slots: SlotsKind,
}

/// Common metadata accessors for CKKS ciphertext and plaintext containers.
///
/// This trait exposes the semantic precision of a value independently from the
/// raw limb storage used by the underlying torus representation. `log_budget` is
/// derived from the container's torus width `k` (from the wrapped GLWE) and
/// `log_delta`, so it is only available on containers, not on a bare [`CKKSMeta`].
pub trait CKKSInfos: LWEInfos {
    /// Returns the complete metadata pair.
    fn meta(&self) -> CKKSMeta;

    /// Returns the base-2 logarithm of the encoded decimal scaling factor.
    fn log_delta(&self) -> usize {
        self.meta().log_delta
    }

    /// Returns the base-2 logarithm of the remaining homomorphic capacity,
    /// derived from the container's torus width: `k − log_delta`.
    fn log_budget(&self) -> usize {
        self.k().as_usize().saturating_sub(self.log_delta())
    }

    /// Returns the sparse-packing factor (`log2` of the coefficient gap / slot
    /// replication); `0` is dense. See [`CKKSMeta::log_sparsity`].
    fn log_sparsity(&self) -> usize {
        self.meta().log_sparsity
    }

    /// Returns the subfield the slots are known to live in. See [`SlotsKind`].
    fn slots(&self) -> SlotsKind {
        self.meta().slots
    }
}

/// Mutable CKKS metadata access for ciphertext/plaintext containers.
pub trait SetCKKSInfos: CKKSInfos {
    /// Replaces the semantic CKKS metadata (`log_delta`, `log_sparsity`). Does not
    /// touch the wrapped GLWE's torus width `k`, so `log_budget` is re-derived
    /// against the (unchanged) `k`. Use [`Self::set_log_delta`] to relabel the
    /// scale while preserving `log_budget`.
    fn set_meta(&mut self, meta: CKKSMeta);

    /// Sets the wrapped GLWE's torus width `k` (the total `log_delta + log_budget`).
    fn set_k(&mut self, k: TorusPrecision);

    /// Updates only the base-2 logarithm of the encoded scaling factor, preserving
    /// `log_budget` by shifting the torus width `k` accordingly.
    fn set_log_delta(&mut self, log_delta: usize) {
        let log_budget = self.log_budget();
        let mut meta = self.meta();
        meta.log_delta = log_delta;
        self.set_meta(meta);
        self.set_k((log_budget + log_delta).into());
    }

    /// Updates only the base-2 logarithm of the remaining homomorphic budget by
    /// setting the torus width `k = log_budget + log_delta`.
    fn set_log_budget(&mut self, log_budget: usize) {
        self.set_k((log_budget + self.log_delta()).into());
    }

    /// Updates only the sparse-packing factor. See [`CKKSMeta::log_sparsity`].
    fn set_log_sparsity(&mut self, log_sparsity: usize) {
        let mut meta = self.meta();
        meta.log_sparsity = log_sparsity;
        self.set_meta(meta);
    }

    /// Updates only the slot kind. See [`SlotsKind`].
    fn set_slots(&mut self, slots: SlotsKind) {
        let mut meta = self.meta();
        meta.slots = slots;
        self.set_meta(meta);
    }
}

/// Allocation / precision spec for a CKKS value.
///
/// Bundles a core [`GLWELayout`] — which carries `n`, `base2k`, the torus width
/// `k`, and `rank` — with the [`CKKSMeta`] (`log_delta`, `log_sparsity`). The
/// budget is derived as `log_budget = k - log_delta`, so `k` lives in the GLWE
/// layout exactly as it does on a wrapped ciphertext/plaintext.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CKKSLayout {
    pub glwe_layout: GLWELayout,
    pub meta: CKKSMeta,
}

/// Coefficient metadata for plan-compiled operands: the DFT factor diagonals
/// ([`layouts::DFTPlan`]), the EvalMod polynomial coefficients
/// ([`layouts::EvalModPlan`]), and the BSGS polynomial encoders
/// ([`polynomial::EncodeBSGS`]).
///
/// The reduced form of a [`CKKSLayout`]: only the torus width `k` the operand
/// plaintexts are allocated with and the [`CKKSMeta`] they are stamped with.
/// Plans carry no ring or radix information — `n` follows the module and
/// `base2k` is passed explicitly at compile time — so there is nothing to fill
/// with placeholders.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CoeffsMeta {
    /// Torus width the operand plaintexts are allocated with.
    pub k: TorusPrecision,
    /// CKKS metadata (`log_delta`, `log_sparsity`) the operands are stamped with.
    pub meta: CKKSMeta,
}

impl CoeffsMeta {
    /// Dense (`log_sparsity = 0`) coefficient meta with
    /// `k = log_delta + log_budget`.
    pub fn from_delta_budget(log_delta: usize, log_budget: usize) -> Self {
        Self {
            k: (log_delta + log_budget).into(),
            meta: CKKSMeta {
                log_delta,
                log_sparsity: 0,
                slots: SlotsKind::Complex,
            },
        }
    }

    /// The operand encoding scale.
    pub fn log_delta(&self) -> usize {
        self.meta.log_delta
    }

    /// The operand headroom: `k − log_delta` (saturating).
    pub fn log_budget(&self) -> usize {
        usize::from(self.k).saturating_sub(self.meta.log_delta)
    }
}

/// Narrowing conversion: keeps `k` and the [`CKKSMeta`], drops the ring/radix
/// fields plans never consume.
impl From<CKKSLayout> for CoeffsMeta {
    fn from(layout: CKKSLayout) -> Self {
        Self {
            k: layout.glwe_layout.k,
            meta: layout.meta,
        }
    }
}

impl LWEInfos for CKKSLayout {
    fn n(&self) -> Degree {
        self.glwe_layout.n()
    }

    fn base2k(&self) -> Base2K {
        self.glwe_layout.base2k()
    }

    fn max_size(&self) -> usize {
        self.glwe_layout.max_size()
    }

    fn k(&self) -> TorusPrecision {
        self.glwe_layout.k()
    }
}

impl GLWEInfos for CKKSLayout {
    fn rank(&self) -> Rank {
        self.glwe_layout.rank()
    }
}

impl CKKSInfos for CKKSLayout {
    fn meta(&self) -> CKKSMeta {
        self.meta
    }
}

/// Bits a binary add/sub must shift its result down to fit `res`: the excess of
/// the **natural result width** — `min(log_delta) + min(log_budget)`, the meta
/// the operation stamps — over the destination's requested `res.k()`. Using the natural width (rather
/// than `min(a.k, b.k)`, which is `≥` it whenever deltas *and* budgets both
/// differ) charges exactly the budget the narrower destination forces and no
/// more; the larger-delta operand's truncated tail lies below the claimed
/// `min(log_delta)` precision. This mirrors the mul family's
/// `(res_log_budget + res_log_delta).saturating_sub(res_max_k)`.
pub(crate) fn ckks_offset_binary<R, A, B>(res: &R, a: &A, b: &B) -> usize
where
    R: CKKSInfos + ?Sized,
    A: CKKSInfos + ?Sized,
    B: CKKSInfos + ?Sized,
{
    let natural_k = a.log_delta().min(b.log_delta()) + a.log_budget().min(b.log_budget());
    natural_k.saturating_sub(res.k().as_usize())
}

pub(crate) fn ckks_offset_unary<R, A>(res: &R, a: &A) -> usize
where
    R: CKKSInfos + ?Sized,
    A: CKKSInfos + ?Sized,
{
    a.k().as_usize().saturating_sub(res.k().as_usize())
}

/// Whether a limb-wise op can read `a` into `res` without normalizing: `res`
/// holds every limb of a non-canonical `a` (its carries may sit beyond `a.k()`).
pub(crate) fn ckks_holds_limbs<BE, R, A>(res: &R, a: &A) -> bool
where
    BE: Backend,
    R: GLWEToBackendRef<BE>,
    A: GLWEToBackendRef<BE>,
{
    a.is_canonical() || res.to_backend_ref().max_size() >= a.to_backend_ref().max_size()
}

/// Whether a limb-wise unary op can write `src` into `dst` without normalizing.
pub(crate) fn ckks_unary_exact<BE, R, A>(res: &R, a: &A) -> bool
where
    BE: Backend,
    R: GLWEToBackendRef<BE> + CKKSInfos,
    A: GLWEToBackendRef<BE> + CKKSInfos,
{
    ckks_offset_unary(res, a) == 0 && ckks_holds_limbs(res, a)
}

/// Shared unary-op preamble: stamps `src`'s metadata with the budget charged
/// by `offset + extra_charge` and `extra_log_delta` bits moved under
/// `log_delta`, then aligns `src` into `dst` (left shift by
/// `offset + extra_shift`). Validates **before** mutating, so on `Err`
/// (insufficient budget) `dst` is untouched. Returns the computed offset.
///
/// This is the single implementation of the "shift + stamp" sequence the
/// copy/pow2/add-pt/sub-pt into-ops previously hand-rolled (H1 in the 2026-07
/// review was a drift bug in exactly this preamble).
#[allow(clippy::too_many_arguments)]
pub(crate) fn ckks_shift_stamp_unary<BE, M, Dst, Src>(
    module: &M,
    op: &'static str,
    dst: &mut Dst,
    src: &Src,
    extra_shift: usize,
    extra_charge: usize,
    extra_log_delta: usize,
    scratch: &mut poulpy_hal::layouts::ScratchArena<'_, BE>,
) -> CKKSResult<()>
where
    BE: Backend,
    M: poulpy_core::GLWEShift<BE> + ?Sized,
    Dst: GLWEToBackendMut<BE> + CKKSInfos + SetCKKSInfos,
    Src: GLWEToBackendRef<BE> + CKKSInfos,
{
    let offset = ckks_offset_unary(dst, src);
    let log_budget = checked_log_budget_sub(op, src.log_budget(), offset + extra_charge)?;
    // Stamp first, and stamp the final metadata: the shift normalizes at
    // `dst.k()`, so the label has to be the width the result will carry, not
    // whatever `dst` held before and not an intermediate. `div_pow2` charges
    // `bits` to the budget and moves them under `log_delta`; doing the second
    // half after the shift would have it round `bits` too low. `offset` is
    // computed against the pre-stamp `dst`.
    dst.set_meta(src.meta());
    dst.set_log_budget(log_budget);
    if extra_log_delta != 0 {
        dst.set_log_delta(src.log_delta() + extra_log_delta);
    }
    module.glwe_lsh(dst, src, offset + extra_shift, scratch);
    Ok(())
}

/// Copies `src` into `dst` with `src`'s metadata: verbatim when `dst` is wide
/// enough, otherwise through [`ckks_shift_stamp_unary`], which charges the
/// offset to the budget and normalizes. Validates before mutating.
pub(crate) fn ckks_copy_stamp_unary<BE, M, Dst, Src>(
    module: &M,
    op: &'static str,
    dst: &mut Dst,
    src: &Src,
    scratch: &mut poulpy_hal::layouts::ScratchArena<'_, BE>,
) -> CKKSResult<()>
where
    BE: Backend,
    M: poulpy_core::GLWECopy<BE> + poulpy_core::GLWEShift<BE> + ?Sized,
    Dst: GLWEToBackendMut<BE> + CKKSInfos + SetCKKSInfos,
    Src: GLWEToBackendRef<BE> + CKKSInfos,
{
    if !ckks_unary_exact(dst, src) {
        return ckks_shift_stamp_unary(module, op, dst, src, 0, 0, 0, scratch);
    }
    // The scratch queries size the copy for the destination as allocated, so it
    // runs before the relabel.
    module.glwe_copy(dst, src, scratch);
    dst.set_meta(src.meta());
    dst.set_log_budget(src.log_budget());
    // The copy is exact: lowering `k` back to `src`'s keeps `src`'s form.
    dst.set_canonical(src.is_canonical());
    Ok(())
}

#[cfg(test)]
mod slots_kind_tests {
    use super::SlotsKind::{self, Complex, Real};

    #[test]
    fn join_keeps_real_only_when_both_operands_are_real() {
        assert_eq!(Real.join(Real), Real);
        assert_eq!(Real.join(Complex), Complex);
        assert_eq!(Complex.join(Real), Complex);
        assert_eq!(Complex.join(Complex), Complex);
    }

    #[test]
    fn meet_keeps_complex_only_when_both_operands_are_complex() {
        assert_eq!(Real.meet(Real), Real);
        assert_eq!(Real.meet(Complex), Real);
        assert_eq!(Complex.meet(Real), Real);
        assert_eq!(Complex.meet(Complex), Complex);
    }

    #[test]
    fn unstated_kind_is_complex() {
        assert_eq!(SlotsKind::default(), Complex);
        assert!(!SlotsKind::default().is_real());
    }
}

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

    fn layout(log_delta: usize, log_budget: usize) -> CKKSLayout {
        CKKSLayout {
            glwe_layout: poulpy_core::layouts::GLWELayout {
                n: Degree(0),
                base2k: Base2K(1),
                k: (log_delta + log_budget).into(),
                rank: Rank(1),
            },
            meta: CKKSMeta {
                log_delta,
                log_sparsity: 0,
                slots: SlotsKind::Complex,
            },
        }
    }

    /// The binary offset charges exactly the natural result width's excess over
    /// the destination — not `min(a.k, b.k)`, which over-charges when deltas
    /// and budgets both differ.
    #[test]
    fn offset_binary_charges_natural_result_width() {
        // Deltas AND budgets differ: natural width = 30 + 20 = 50, while
        // min(a.k, b.k) = 55 — the old formula charged 5 spurious bits.
        let a = layout(40, 20); // k = 60
        let b = layout(30, 25); // k = 55
        let res = layout(30, 20); // max_k = 50
        assert_eq!(ckks_offset_binary(&res, &a, &b), 0);

        // A genuinely narrower destination still charges the difference.
        let narrow = layout(30, 12); // max_k = 42
        assert_eq!(ckks_offset_binary(&narrow, &a, &b), 8);

        // Degenerate cases match the old formula: equal budgets…
        let c = layout(40, 25); // k = 65
        let d = layout(30, 25); // k = 55
        assert_eq!(ckks_offset_binary(&narrow, &c, &d), (30 + 25) - 42);
        // …and equal deltas.
        let e = layout(30, 30); // k = 60
        assert_eq!(ckks_offset_binary(&narrow, &d, &e), (30 + 25) - 42);
    }
}