rhdl_dsig_scalable_core/

planner.rs

//! DSig as a component of the shared chip planner and TUI
//! ([`rhdl_fpga_planner`]), next to Ed25519 Sign/Verify and the shared SHA-512.
//!
//! # The problem
//!
//! DSig is not built alone. The comparison paper puts a DSig signer and
//! verifier, an Ed25519 signer and verifier and a shared SHA-512 line on one
//! chip, and asks "with this much area, how many operations per second does
//! each get?" The shared chip planner (`rhdl_fpga_planner`, a sibling crate
//! with a terminal UI, or TUI) answers that by giving each design a *share*
//! of the chip (LUTs, DSPs, block RAM, UltraRAM) and asking it for a *plan*.
//! So DSig must speak the planner's language: the [`Component`] trait.
//!
//! # The reasoning
//!
//! [`crate::config`] already knows what DSig costs and how fast it is. This
//! module does not repeat those measurements; it imports them and adds the
//! knobs the comparison wants to explore. Some of those choices have never
//! been synthesized, so their costs are **estimates**, and every [`Plan`]
//! says whether it rests on measurement (`measured`).
//!
//! Two lessons shaped the plan search:
//!
//! * **A share is not the device.** Moving S-boxes into spare RAM must use
//!   the RAM in DSig's share, not the whole chip's, or every partial share
//!   fails the RAM check ([`config::Build::fill_within`]).
//! * **Small shares still deserve an answer.** The smallest *built* engine
//!   has two slices (~207k LUT with S-boxes in RAM). A one-slice engine is
//!   offered as a **model** so a small share still plans something.
//!
//! # The decision
//!
//! Two components:
//!
//! * [`Dsig`], the signer we build. Its plan is the largest slice count that
//!   fits the share.
//! * [`DsigVerify`], a **model** of a verifier that is not built yet, so the
//!   paper can compare sign and verify on the same footing.
//!
//! What the verifier model counts, step by step (nothing here is built):
//!
#![doc = concat!("<div style=\"overflow-x:auto\">", include_str!("../docs/images/dsig-verify.svg"), "</div>")]
//!
//! ```text
//!   rhdl_fpga_planner (TUI)
//!       │ Share {lut, dsp, bram36, uram}, Context {mhz, ...}
//!       ▼
//!   Dsig::plan ── for slices in 1..=16 ─────▶ Dsig::cost(slices, share) ──▶ fits?
//!       │                                         │ yes: keep, try next size
//!       │                                         │ no : stop, record the limit
//!       ▼                                         ▼
//!   Plan {cost, rate = slices·f/period (own core: min with K·f/895), demands, ...}
//!       │
//!       ▼
//!   Dsig::build_flags ──▶ DSIG_SLICES, DSIG_CHAIN, DSIG_SBOX_PLACEMENT
//! ```
//!
//! The cost model of one slice is taken apart into lanes so a knob can swap a
//! lane:
//!
//! ```text
//!   slice = slice_rest + factory BLAKE3 lane + 3 × chain lane
//!   slice_rest = SLICE_LUT − 3 × HARAKA_LANE_LUT − BLAKE3_LANE_LUT
//!   kernel = slices × slice + glue (+ Ed25519 core when DSig has its own)
//! ```
//!
//! # Knobs that the signer and verifier share
//!
//! A verifier can only check what the signer made, so the scheme knobs
//! (HBSS, chain hash, SHA lanes, `w`, `K`) are [shared](Knob::shared): the
//! TUI lists them once, under DSig sign, and sets both modules.
//!
//! # Where the certificates come from
//!
//! Every batch of `K` keys is certified by one Ed25519 signature. Two ways:
//!
//! * **the chip's Ed25519 sign module** (default): DSig sends its batch roots
//!   to the paper's Ed25519 signer, which the planner sizes for `1/K` of
//!   DSig's rate. DSig's own cost then has no Ed25519 core.
//! * **inside DSig (as built)**: the hardware built today carries its own
//!   small Ed25519 signer (`ED25519_LUT`), capping DSig at `K × f / 895`.
//!   The plan [covers](Plan::covers) Ed25519 signing, so the chip's Ed25519
//!   sign module is not needed; counting both would count the signer twice.
//!
//! Knobs of [`Dsig`] (and, where they apply, [`DsigVerify`]):
//!
//! | Knob | Choices | What it changes | Status |
//! |---|---|---|---|
//! | HBSS | W-OTS+, HORS | the hash-based one-time scheme | W-OTS+ built; HORS **not implemented** (no plan) |
//! | chain hash | Haraka-512, BLAKE3, SHA-512 | the lane in every slice (`chain-*` feature) | built, simulated |
//! | SHA lanes | own, shared line | SHA-512 chains on DSig's own pipelines, or as clients of the shared line | own: built; shared: **model** |
//! | Winternitz w | 4, 16 | the HBSS: chain length and chain count | 4 built; 16 **model** |
//! | batch K | 128, 64, 256 | keys per Ed25519 certificate | 128 built; others **model** |
//! | S-box RAM | fill, LUT only | Haraka S-boxes in the share's spare UltraRAM / block RAM | built |
//! | BLAKE3 adders | LUT, DSP | 32-bit adders of every BLAKE3 lane in DSP48E2s | **planned**, estimated |
//! | Ed25519 certificates | chip's Ed25519 sign module, inside DSig | who signs batch roots (above) | inside: built |
//! | message | 16 B (profile 1), 64 B (profile 2) | signed message length, `DSIG_MESSAGE_BYTES`: profile 2 signs uBFT's whole 48-byte signed context; one more digest compression per signature (an idle timetable residue, so the same rate) | 16: built, measured; 64: simulated, cost **estimated** |
//!
//! Slice counts: any of 1 to 16. 2, 4 and 8 are built (`DSIG_SLICES=N`), and 2 is measured on the card (build v3: 786,432 signatures
//! at 6,019,465/s, 34.06 cycles per signature); the others are a **model**
//! with the same per-slice cost and `slices × f / key period` rate.
//!
//! Costs: measured (routed `slices-2` link and Vivado OOC) for the Haraka lane,
//! the BLAKE3 lane, the slice and the Ed25519 core; **estimates** for the
//! SHA-512 lane, the DSP-adder BLAKE3 lane, the one-slice build and S-box
//! savings (see [`config`](crate::config)).

use crate::config::{
    self, DEVICE_URAM, KERNEL_BRAM36, ED25519_BRAM36, ED25519_CYCLES_PER_SIGN, ED25519_DSP, ED25519_LUT,
    GLUE_BRAM36, GLUE_LUT, LANES_PER_SLICE, LUTS_PER_LUT_SBOX, SBOXES_PER_LANE, SLICE_BRAM36, SLICE_LUT,
    SLICE_URAM,
};
use rhdl_fpga_planner::{BuildFlags, Component, Context, Cost, Flow, Knob, Plan, Role, SHA512_BLOCKS, Share};

// ------------------------------------------------------------- lane costs
//
// A slice is split into lanes here so the "chain hash" knob can swap one lane
// kind for another. Measured lanes come from Vivado out-of-context (OOC)
// place-and-route; the rest are marked estimates.

/// Haraka chain-step lane, Vivado OOC routed.
///
/// Unit: CLB LUTs per lane, all S-boxes in LUTs. A slice has three.
pub const HARAKA_LANE_LUT: f64 = 23_902.0;
/// BLAKE3 compression lane, Vivado OOC routed.
///
/// Unit: CLB LUTs per lane. Each slice's key factory has one, the
/// certificate unit has one more, and with the BLAKE3 chain hash it also
/// replaces each Haraka lane.
pub const BLAKE3_LANE_LUT: f64 = 16_422.0;

/// Kernel CLB LUTs of build v5 after **synthesis** (not routed): `slices-4`,
/// T-tables in AES rounds 3–8 (`DSIG_TABLE_MASK=0x1f8`), Ed25519 inside.
///
/// For build v3, synthesis (301,465) and routing (296,868) agreed within 2 %.
pub const V5_KERNEL_LUT_SYNTH: f64 = 358_614.0;

/// One Haraka chain-step lane with T-tables in rounds 3–8 (**from
/// synthesis**): what is left of a v5 slice after the parts a v3 slice also
/// has.
///
/// ```text
/// v5 slice  = (358,614 − Ed25519 25,383 − glue 20,564) / 4      = 78,167
/// rest      = v3 slice 127,502 − 3 × 23,902 − BLAKE3 16,422      = 39,374
/// lane      = (78,167 − 39,374 − 16,422) / 3                     ≈  7,457
/// ```
///
/// Unit: CLB LUTs per lane (versus 23,902 with LUT S-boxes).
pub const HARAKA_TABLE_LANE_LUT: f64 =
    ((V5_KERNEL_LUT_SYNTH - ED25519_LUT - GLUE_LUT) / 4.0 - (SLICE_LUT - 3.0 * HARAKA_LANE_LUT - BLAKE3_LANE_LUT)
        - BLAKE3_LANE_LUT)
        / 3.0;

/// BRAM36 tiles of one T-table lane: 176 dual-port BRAM18 ROMs (32 per
/// table round in rounds 3–6, 24 in rounds 7–8 where 16 bytes are never
/// observed). Build v5 synthesized 2,135 RAMB18 for its 12 lanes and caches.
pub const HARAKA_TABLE_LANE_BRAM36: f64 = 88.0;

/// T-table lookups per AES round that can become a table round, rounds 3
/// to 8 in order (rounds 7 and 8 have 16 bytes nobody observes).
const TABLE_ROUND_LOOKUPS: [f64; 6] = [64.0, 64.0, 64.0, 64.0, 48.0, 48.0];

/// Choices of the "table rounds" knob: how many AES rounds of every Haraka
/// lane, counting up from round 3, use T-tables (`DSIG_TABLE_MASK`).
const TABLE_ROUNDS: [&str; 8] = [
    "0 (LUT S-boxes; v3, routed)",
    "1: r3 (interp.)",
    "2: r3–4 (interp.)",
    "3: r3–5 (interp.)",
    "4: r3–6 (interp.)",
    "5: r3–7 (interp.)",
    "6: r3–8 (v5, synth)",
    "auto (fastest in share)",
];

/// The "table rounds" value meaning *auto*: [`Component::plan`] tries 0..=6
/// inside its share and keeps the fastest.
pub const AUTO_TABLE_ROUNDS: u32 = 7;

/// The best of several fixed-table-rounds plans: highest rate, then fewer
/// BRAM36 (block RAM is what a T-table chip runs out of), then fewer LUTs.
///
/// This is what *auto* does. Because each component chooses inside the share
/// the planner gave it, lending LUTs or block RAM to DSig automatically moves
/// the choice toward more or fewer table rounds.
fn best_over_table_rounds(plans: impl Iterator<Item = Plan>) -> Option<Plan> {
    plans.reduce(|best, p| {
        let better = p.rate > best.rate
            || (p.rate == best.rate
                && (p.cost.bram36, p.cost.lut) < (best.cost.bram36, best.cost.lut));
        if better { p } else { best }
    })
}

/// Table lookups (S-boxes replaced by T-table reads) in one lane's first
/// `rounds` table rounds, counting up from round 3.
#[must_use]
pub fn table_lookups(rounds: u32) -> f64 {
    TABLE_ROUND_LOOKUPS.iter().take(rounds as usize).sum()
}

/// LUTs and BRAM36 of one Haraka lane with its first `rounds` table rounds
/// (0..=6, from round 3).
///
/// The two ends are builds: 0 is the routed v3 lane ([`HARAKA_LANE_LUT`]),
/// 6 the lane derived from v5's synthesis ([`HARAKA_TABLE_LANE_LUT`]). In
/// between, the LUT saving is **interpolated** per table lookup (352 lookups
/// save 16,445 LUTs, ~46.7 each) and the block RAM is exact: two lookups per
/// dual-port BRAM18, so a quarter of a BRAM36 per lookup. This is the lever
/// for a BRAM-bound chip: fewer table rounds per lane cost LUTs but free
/// block RAM for more lanes.
#[must_use]
pub fn table_lane(rounds: u32) -> (f64, f64) {
    let lookups: f64 = TABLE_ROUND_LOOKUPS.iter().take(rounds as usize).sum();
    let saving_per_lookup = (HARAKA_LANE_LUT - HARAKA_TABLE_LANE_LUT) / TABLE_ROUND_LOOKUPS.iter().sum::<f64>();
    (HARAKA_LANE_LUT - lookups * saving_per_lookup, lookups / 4.0)
}

/// Whether the cost of a lane with `rounds` table rounds comes from a build
/// (0 = v3 routed, 6 = v5 synthesis) rather than the interpolation. Every
/// count is buildable (`DSIG_TABLE_MASK`); only the cost is interpolated.
fn table_rounds_built(rounds: u32) -> bool {
    rounds == 0 || rounds == 6
}

/// Choices of the "table RAM" knob: where T-table lookups live.
const TABLE_RAM: [&str; 2] = ["block RAM (built)", "block RAM, then URAM (model)"];

/// Table lookups one UltraRAM serves: one per port of a dual-port
/// 4,096 × 72 URAM (a 256 × 32 T-table fills 1/16 of it). Block RAM serves
/// four per BRAM36 (two per BRAM18), so URAM is the poorer home per tile,
/// but a slices-4 kernel leaves ~670 of the device's 960 unused while block
/// RAM is the wall.
pub const LOOKUPS_PER_URAM: f64 = 2.0;

/// LUTs of the loader one lane needs when any of its T-tables are in URAM:
/// **estimate**. UltraRAM cannot be preloaded by the bitstream, so after
/// every reset an 8-bit counter walks the 256 entries and writes each table
/// (as [`crate::aes_table::SboxLoader`] does for URAM S-boxes); the lane
/// reports not-ready until it finishes. Not built for T-tables.
pub const TABLE_LOADER_LUT: f64 = 200.0;

/// Splits `bram36` worth of table block RAM into what fits in `free_bram36`
/// and the rest moved to URAM (at most `free_uram`): returns (BRAM36 kept,
/// URAM used). What fits in neither stays in block RAM, so an over-full
/// share shows up as a block RAM limit.
fn spill_tables(bram36: f64, free_bram36: f64, free_uram: f64) -> (f64, f64) {
    let kept = bram36.min(free_bram36.max(0.0));
    // Lookups that did not fit, at four per BRAM36.
    let over = (bram36 - kept) * 4.0;
    let uram = (over / LOOKUPS_PER_URAM).ceil().min(free_uram.max(0.0));
    (bram36 - uram * LOOKUPS_PER_URAM / 4.0, uram)
}
/// BLAKE3 lane with its ~224 32-bit adders in DSPs: **estimate**
/// (each adder ~32 LUTs → one DSP48E2).
///
/// Unit: CLB LUTs per lane. This knob is planned, not built.
pub const BLAKE3_DSP_LANE_LUT: f64 = 16_422.0 - 224.0 * 32.0;
/// DSPs of a BLAKE3 lane with DSP adders: **estimate**.
///
/// Unit: DSP48E2s per lane, one per adder.
pub const BLAKE3_LANE_DSP: u32 = 224;
/// SHA-512 lane (`rhdl_sha512_pipelined`, 80 unrolled rounds): **estimate**
/// until synthesized (80 × ~420 + 64 × ~150 LUTs).
///
/// Unit: CLB LUTs per lane, used only when the chain hash is SHA-512 and
/// the lanes are DSig's own.
pub const SHA512_LANE_LUT: f64 = 43_200.0;
/// A TOML string: the TUI writes flag values verbatim into
/// `build-config.toml`, so strings carry their own quotes.
fn quoted(value: &str) -> String {
    format!("{value:?}")
}

/// The `buildable` flag, and `not_buildable` listing every reason a plan
/// cannot be built as planned today; `measure/export_build.py` refuses such
/// a table. Same keys as the Ed25519 planner.
fn buildable<'a>(gaps: impl Iterator<Item = &'a str>) -> BuildFlags {
    let gaps: Vec<&str> = gaps.collect();
    let mut flags = vec![("buildable".into(), gaps.is_empty().to_string())];
    if !gaps.is_empty() {
        flags.push(("not_buildable".into(), quoted(&gaps.join("; "))));
    }
    flags
}

/// A chain lane that sends its blocks to the shared SHA-512 line instead of
/// hashing them itself: block assembly, a tag FIFO and the truncation
/// (**estimate**).
///
/// Unit: CLB LUTs per lane.
pub const SHA512_CLIENT_LUT: f64 = 1_500.0;
/// Latency of one chain step, in cycles, for Haraka-512, BLAKE3 and SHA-512
/// (indexed by the chain-hash knob; measured in simulation).
pub const CHAIN_LATENCY: [f64; 3] = [20.0, 28.0, 82.0];

/// Choices of the verifier's "certificate checks" knob.
const VERIFY_CERTS: [&str; 2] = ["chip's Ed25519 verify module", "own Ed25519 verify core (as built)"];

/// Display names of the message-length choices (index 1 = profile 2).
pub const MESSAGES: [&str; 2] = ["16 B (profile 1)", "64 B (profile 2, uBFT context)"];
/// Profile 2's extra LUTs per slice (**estimate**, not synthesized): the
/// signer's tail block and CV registers (24 words) with their muxes and
/// the factory's chained-message request path.
const MESSAGE64_SLICE_LUT: f64 = 1_200.0;
/// Profile 2's extra LUTs per verify unit (**estimate**): the loader's tail
/// row and the hasher's second digest step.
const MESSAGE64_VERIFY_LUT: f64 = 400.0;

/// Display names of the chain-hash choices, indexed by `chain_hash`.
const HASHES: [&str; 3] = ["Haraka-512", "BLAKE3", "SHA-512"];
/// Display names of the SHA-lane choices.
const SHA_ROUTES: [&str; 2] = ["own lanes", "shared line (model)"];
/// The Winternitz parameters offered; index 0 is the built one.
const WINTERNITZ: [u32; 2] = [4, 16];
/// The batch sizes offered; index 0 is the built one.
const BATCHES: [u32; 3] = [128, 64, 256];

// ------------------------------------------------------------------- HBSS

/// Which hash-based one-time signature scheme DSig uses.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum Scheme {
    /// W-OTS+ (Winternitz chains): what the hardware implements.
    #[default]
    WotsPlus,
    /// HORS (few-time signatures from a set of revealed secrets): offered
    /// so the TUI and build flags are ready, but **not implemented**, and
    /// there is no cost model yet, so it plans nothing.
    Hors,
}

/// The schemes in the order of the HBSS knob.
const SCHEMES: [Scheme; 2] = [Scheme::WotsPlus, Scheme::Hors];

/// What the planner says when the HBSS knob is set to HORS.
const HORS_TODO: &str = "HORS is not implemented yet (no hardware, no cost model): set HBSS back to W-OTS+";

/// The hash-based one-time signature scheme (HBSS) and its batching.
///
/// DSig signs with W-OTS+: a message digest is cut into base-`w` digits, one
/// hash chain per digit plus a few checksum chains. Each chain is hashed
/// `w − 1` times at key generation. Larger `w` means fewer, longer chains:
/// shorter signatures, more hashing. The built hardware is `w = 4`, 128-bit
/// digests (64 digits + 4 checksum digits = 68 chains of 3 steps) and
/// `K = 128` keys per batch; every other combination is a **model**.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Hbss {
    /// The scheme; only W-OTS+ has hardware and a cost model.
    pub scheme: Scheme,
    /// Winternitz parameter: digits are base `w`, chains have `w − 1` steps.
    pub w: u32,
    /// Keys per batch, certified by one Ed25519 signature (`K`).
    pub batch: u32,
}

impl Default for Hbss {
    fn default() -> Self {
        Self { scheme: Scheme::WotsPlus, w: 4, batch: 128 }
    }
}

impl Hbss {
    /// Bits of the message digest that the digits encode.
    pub const DIGEST_BITS: u32 = 128;

    /// The scheme the hardware implements.
    #[must_use]
    pub fn built(self) -> bool {
        self.scheme == Scheme::WotsPlus && self.w == 4 && self.batch == 128
    }

    /// Message digits: `128 / log2 w`.
    #[must_use]
    pub fn message_digits(self) -> u32 {
        Self::DIGEST_BITS / self.w.trailing_zeros()
    }

    /// Checksum digits: the fewest base-`w` digits that can hold the largest
    /// checksum, `message_digits × (w − 1)`.
    #[must_use]
    pub fn checksum_digits(self) -> u32 {
        // Largest possible checksum value.
        let max = u64::from(self.message_digits()) * u64::from(self.w - 1);
        // Count digits until w^d exceeds it.
        let mut digits = 0;
        let mut reach = 1_u64;
        while reach <= max {
            reach *= u64::from(self.w);
            digits += 1;
        }
        digits
    }

    /// Hash chains per key (68 for the built scheme).
    #[must_use]
    pub fn chains(self) -> u32 {
        self.message_digits() + self.checksum_digits()
    }

    /// Chain steps to make one key: every chain hashed `w − 1` times (204).
    #[must_use]
    pub fn steps_per_key(self) -> f64 {
        f64::from(self.chains() * (self.w - 1))
    }

    /// BLAKE3 compressions to make one key: 3 for seeds and nonces, the XOF
    /// that makes 18 secret bytes per chain, the commitment over 18 endpoint
    /// bytes per chain (plus a 16-byte prefix), and 2 for the Merkle leaf.
    #[must_use]
    pub fn blake3_per_key(self) -> f64 {
        // Bytes of chain material per key.
        let bytes = f64::from(self.chains()) * 18.0;
        3.0 + (bytes / 64.0).ceil() + ((bytes + 16.0) / 64.0).ceil() + 2.0
    }

    /// Cycles one slice needs per key: its three chain lanes do three steps
    /// per clock, its BLAKE3 lane one compression per clock, and the chain
    /// engine takes one chain per clock. The busiest of the three sets the
    /// period. For the built scheme every term but BLAKE3 is 68.
    #[must_use]
    pub fn key_period(self) -> f64 {
        (self.steps_per_key() / f64::from(LANES_PER_SLICE))
            .ceil()
            .max(self.blake3_per_key())
            .max(f64::from(self.chains()))
    }

    /// Merkle levels from a key to its batch root: `log2 K`.
    #[must_use]
    pub fn merkle_height(self) -> u32 {
        self.batch.trailing_zeros()
    }

    /// Signature bytes: one 18-byte node per chain, one 32-byte sibling per
    /// Merkle level, and 194 bytes of fixed fields (nonces, indices, root,
    /// certificate). 1,642 for the built scheme.
    #[must_use]
    pub fn signature_bytes(self) -> u32 {
        self.chains() * 18 + self.merkle_height() * 32 + 194
    }

    /// Expected chain steps to finish one verification. The built scheme
    /// uses [`VERIFY_CHAIN_STEPS`]; for other `w` each chain needs on average
    /// half its length.
    #[must_use]
    pub fn verify_steps(self) -> f64 {
        if self.w == 4 {
            VERIFY_CHAIN_STEPS * f64::from(self.chains()) / 68.0
        } else {
            f64::from(self.chains() * (self.w - 1)) / 2.0
        }
    }

    /// BLAKE3 compressions per verification: the endpoint commitment (its
    /// blocks plus one parent per extra 1 KiB chunk), the message digest and
    /// one per Merkle level. 21 + 1 + 7 = 29 for the built scheme, as the
    /// hardware counts (native simulation: 29.00 per record).
    #[must_use]
    pub fn verify_blake3(self) -> f64 {
        let bytes = f64::from(self.chains()) * 18.0 + 16.0;
        (bytes / 64.0).ceil() + ((bytes / 1024.0).ceil() - 1.0) + 1.0 + f64::from(self.merkle_height())
    }

    /// A short label, e.g. `W-OTS+ w=4, 68 chains, K=128, 1642 B`.
    #[must_use]
    pub fn label(self) -> String {
        format!(
            "W-OTS+ w={}, {} chains, K={}, {} B sig",
            self.w,
            self.chains(),
            self.batch,
            self.signature_bytes()
        )
    }

    /// Knobs for the scheme, `w` and `K`, all shared between DSig sign and
    /// verify.
    fn knobs(self) -> [Knob; 3] {
        [
            Knob::choice("HBSS", SCHEMES.iter().position(|&x| x == self.scheme).unwrap_or(0), &["W-OTS+", "HORS (not implemented)"]).shared(),
            Knob::choice(
                "Winternitz w",
                WINTERNITZ.iter().position(|&w| w == self.w).unwrap_or(0),
                &["4", "16 (model)"],
            )
            .shared(),
            Knob::choice(
                "batch K",
                BATCHES.iter().position(|&k| k == self.batch).unwrap_or(0),
                &["128", "64 (model)", "256 (model)"],
            )
            .shared(),
        ]
    }

    /// Applies HBSS knob `index` (0 scheme, 1 `w`, 2 `K`) set to choice
    /// `pick`.
    fn set(&mut self, index: usize, pick: usize) {
        match index {
            0 => self.scheme = SCHEMES[pick.min(SCHEMES.len() - 1)],
            1 => self.w = WINTERNITZ[pick.min(WINTERNITZ.len() - 1)],
            _ => self.batch = BATCHES[pick.min(BATCHES.len() - 1)],
        }
    }
}

/// The certificate ceiling: one Ed25519 signature per batch of `K` keys,
/// one Ed25519 signature every [`ED25519_CYCLES_PER_SIGN`] cycles.
fn certificate_ceiling(hbss: Hbss, mhz: f64) -> f64 {
    f64::from(hbss.batch) * mhz * 1e6 / ED25519_CYCLES_PER_SIGN
}

// ----------------------------------------------------------------- signer

/// The DSig component.
///
/// The signer as the chip planner sees it. Its fields are the planner knobs;
/// [`Component::knobs`] shows them and [`Component::set_knob`] changes them.
/// Only the default chain hash (Haraka-512) with the default HBSS matches the
/// preserved `DSIG_FPGA_W4_HARAKA_BLAKE3_V1` profile.
#[derive(Clone, Debug)]
pub struct Dsig {
    /// 0 Haraka-512, 1 BLAKE3, 2 SHA-512.
    ///
    /// Index into the hash name list; picks the lane type of every slice
    /// (the `DSIG_CHAIN` build variable).
    pub chain_hash: usize,
    /// SHA-512 chains only: hash on the shared SHA-512 line instead of
    /// DSig's own pipelines (**model**). The line's blocks then go to DSig
    /// as well as Ed25519, so the planner balances them.
    pub sha_shared: bool,
    /// The hash-based scheme and its batch size.
    pub hbss: Hbss,
    /// Profile 2: sign 64-byte messages (`DSIG_MESSAGE_BYTES=64`).
    pub message64: bool,
    /// Fill the share's spare RAM with Haraka S-boxes.
    ///
    /// `true` uses [`config::Build::fill_within`]; `false` keeps every
    /// S-box in LUTs. Only matters for Haraka-512.
    pub sbox_ram: bool,
    /// BLAKE3 adders in DSPs.
    ///
    /// Planned and estimated only: trades LUTs for DSPs in every BLAKE3 lane.
    pub blake3_dsp: bool,
    /// Certify batches with DSig's own Ed25519 core (as built) instead of the
    /// chip's Ed25519 sign module.
    pub own_ed25519: bool,
    /// AES rounds of every Haraka lane, from round 3 up, computed with
    /// block-RAM T-tables (0..=6; see [`table_lane`]), or
    /// [`AUTO_TABLE_ROUNDS`] (the default) to pick the fastest inside the
    /// share, so block RAM the share leaves over becomes signing speed. 0 is
    /// build v3 (LUT S-boxes, routed), 6 is build v5 (rounds 3–8, synthesis).
    /// Any value above 0 overrides "S-box RAM": the remaining S-boxes stay in
    /// LUTs.
    pub table_rounds: u32,
    /// T-table lookups that do not fit the share's block RAM move to its
    /// spare UltraRAM ([`LOOKUPS_PER_URAM`], plus a [`TABLE_LOADER_LUT`]
    /// loader per lane). **Model**: the URAM T-table and its loader are not
    /// built. On by default (the user's choice: spare URAM should speed DSig
    /// up); the detail line and `not_buildable` mark a plan that uses it.
    pub table_uram: bool,
}

/// Haraka-512 chains, the built HBSS, auto table rounds (as many T-table
/// rounds as the share's block RAM makes fastest), BLAKE3 adders in LUTs,
/// certificates from the chip's Ed25519 sign module (the modular chip of the
/// paper). Set "Ed25519 certificates" to "inside DSig" for the routed,
/// measured kernel; turn "S-box RAM" to "fill" to explore the (estimated) RAM
/// placement.
impl Default for Dsig {
    fn default() -> Self {
        Self {
            chain_hash: 0,
            sha_shared: false,
            hbss: Hbss::default(),
            message64: false,
            sbox_ram: false,
            blake3_dsp: false,
            own_ed25519: false,
            table_rounds: AUTO_TABLE_ROUNDS,
            table_uram: true,
        }
    }
}

impl Dsig {
    /// Largest slice count the planner may choose. Every count from 1 is
    /// tried; 2, 4 and 8 are built (`DSIG_SLICES=N`, see
    /// [`Dsig::BUILT_SLICES`]); the rest are a **model** with the same
    /// per-slice cost (1 needs 7-bit key numbers in a slice, today 6).
    pub const MAX_SLICES: u32 = 16;
    /// Slice counts `DSIG_SLICES` accepts.
    pub const BUILT_SLICES: [u32; 3] = [2, 4, 8];

    /// Whether the chain lanes hash on the shared SHA-512 line.
    #[must_use]
    pub fn uses_shared_line(&self) -> bool {
        self.chain_hash == 2 && self.sha_shared
    }

    /// The S-box placement for `slices` slices inside `share`.
    ///
    /// Only Haraka lanes with "S-box RAM" on place S-boxes. The T-tables
    /// (and their URAM spill) take RAM first; the S-boxes of the remaining
    /// rounds then fill what is left, block RAM first (no loader), then
    /// UltraRAM, in dual-port pairs: four per BRAM36, two per URAM.
    #[must_use]
    pub fn placement(&self, slices: u32, share: &Share) -> config::Build {
        if self.chain_hash != 0 || !self.sbox_ram {
            return config::Build::lut_only(slices);
        }
        let lanes = f64::from(slices * LANES_PER_SLICE);
        let (_, table_bram, table_uram) = self.tables(slices, share);
        let own = if self.own_ed25519 { 1.0 } else { 0.0 };
        let fixed = f64::from(slices) * SLICE_BRAM36 + own * ED25519_BRAM36 + GLUE_BRAM36;
        let free_bram = f64::from(share.bram36).min(KERNEL_BRAM36) - fixed - table_bram;
        let free_uram = f64::from(share.uram.min(DEVICE_URAM)) - f64::from(slices * SLICE_URAM) - table_uram;
        // Boxes a lane still has once its table rounds are tables.
        let boxes = SBOXES_PER_LANE - table_lookups(self.table_rounds) as u32;
        let bram = ((4.0 * free_bram / lanes).floor().max(0.0) as u32).min(boxes);
        let uram = ((2.0 * free_uram / lanes).floor().max(0.0) as u32).min(boxes - bram);
        config::Build { slices, uram_per_lane: uram, bram_per_lane: bram }
    }

    /// T-table RAM of `slices` slices inside `share`: (lookups per lane,
    /// BRAM36, URAM). With "table RAM" on URAM, the lookups the share's
    /// block RAM cannot hold move to its spare UltraRAM.
    fn tables(&self, slices: u32, share: &Share) -> (f64, f64, f64) {
        if self.chain_hash != 0 || self.table_rounds == 0 {
            return (0.0, 0.0, 0.0);
        }
        let lanes = f64::from(slices * LANES_PER_SLICE);
        let own = if self.own_ed25519 { 1.0 } else { 0.0 };
        let fixed = f64::from(slices) * SLICE_BRAM36 + own * ED25519_BRAM36 + GLUE_BRAM36;
        let bram = table_lane(self.table_rounds).1 * lanes;
        let (bram, uram) = if self.table_uram {
            spill_tables(
                bram,
                f64::from(share.bram36).min(KERNEL_BRAM36) - fixed,
                f64::from(share.uram.min(DEVICE_URAM)) - f64::from(slices * SLICE_URAM),
            )
        } else {
            (bram, 0.0)
        };
        (table_lookups(self.table_rounds), bram, uram)
    }

    /// Cost of `slices` slices inside `share` with the current knobs, plus a
    /// description.
    ///
    /// The whole kernel: `slices` slices, the Ed25519 core and the glue. The
    /// returned string is the one-line description shown in the planner.
    #[must_use]
    pub fn cost(&self, slices: u32, share: &Share) -> (Cost, String) {
        // Chain lanes in the whole kernel (three per slice).
        let lanes = f64::from(slices * LANES_PER_SLICE);
        // LUTs of one factory BLAKE3 lane under the adder knob.
        let factory_blake3 = if self.blake3_dsp { BLAKE3_DSP_LANE_LUT } else { BLAKE3_LANE_LUT };
        // DSPs of one BLAKE3 lane under the adder knob (0 when off).
        let blake3_dsp_per = if self.blake3_dsp { BLAKE3_LANE_DSP } else { 0 };
        // A slice without its three chain lanes or its factory BLAKE3 lane.
        let slice_rest = SLICE_LUT - 3.0 * HARAKA_LANE_LUT - BLAKE3_LANE_LUT;
        // The S-box placement (all-LUT unless Haraka with S-box RAM).
        let build = self.placement(slices, share);
        // Per-lane LUTs and DSPs of the chosen chain hash.
        let (lane_lut, lane_dsp) = match self.chain_hash {
            // Haraka: the measured lane minus the LUTs freed by each S-box
            // moved to RAM.
            // Haraka with T-tables: the per-lane figure derived from build v5.
            // Either way, each S-box placed in RAM frees its LUTs, and a
            // lane with UltraRAM S-boxes adds its loader.
            0 => {
                let base = if self.table_rounds > 0 { table_lane(self.table_rounds).0 } else { HARAKA_LANE_LUT };
                let placed = f64::from(build.uram_per_lane + build.bram_per_lane);
                let loader = if build.uram_per_lane > 0 { config::LOADER_LUT } else { 0.0 };
                (base - placed * LUTS_PER_LUT_SBOX + loader, 0)
            }
            // BLAKE3 chains: each chain lane is another BLAKE3 lane.
            1 => (factory_blake3, blake3_dsp_per),
            // SHA-512 chains on the shared line: only a small client per lane.
            _ if self.sha_shared => (SHA512_CLIENT_LUT, 0),
            // SHA-512 chains on DSig's own pipelines.
            _ => (SHA512_LANE_LUT, 0),
        };
        // Slice count as f64 for the LUT sum.
        let s = f64::from(slices);
        // Kernel LUTs: per-slice rest and factory lane, every chain lane, the
        // Ed25519 core and the glue (which contains the cert unit's BLAKE3
        // lane, so the DSP-adder saving is applied to it once here).
        // The Ed25519 certificate core, when DSig carries its own.
        let own = if self.own_ed25519 { 1.0 } else { 0.0 };
        let message = if self.message64 { MESSAGE64_SLICE_LUT } else { 0.0 };
        let lut = s * (slice_rest + factory_blake3 + message) + lanes * lane_lut + own * ED25519_LUT + GLUE_LUT
            + if self.blake3_dsp { -224.0 * 32.0 } else { 0.0 }; // the cert unit's BLAKE3 lane
        // Kernel DSPs: Ed25519, then one BLAKE3 lane per slice plus the cert
        // unit's (hence `slices + 1`), then any DSPs in the chain lanes.
        let dsp = u32::from(self.own_ed25519) * ED25519_DSP + (slices + 1) * blake3_dsp_per + slices * LANES_PER_SLICE * lane_dsp;
        // RAM taken by placed S-boxes: one URAM each, or half a BRAM36 each.
        // UltraRAM S-boxes: one URAM per pair, rounded up per lane.
        let uram_placed = build.uram_per_lane.div_ceil(2) * slices * LANES_PER_SLICE;
        // Block RAM outside the tables and S-boxes: caches, Ed25519, glue.
        let fixed_bram = s * SLICE_BRAM36 + own * ED25519_BRAM36 + GLUE_BRAM36;
        // T-table RAM, spilled to URAM if "table RAM" allows it.
        let (_, table_bram, table_uram) = self.tables(slices, share);
        // A loader in every lane, once any table is in URAM.
        let lut = lut + if table_uram > 0.0 { lanes * TABLE_LOADER_LUT } else { 0.0 };
        // Block-RAM S-boxes: two per BRAM18, a quarter of a BRAM36 each.
        let bram_placed = f64::from(build.bram_per_lane) * lanes / 4.0 + table_bram;
        // The planner's integer cost; LUTs are clamped at zero so an
        // aggressive estimate can never go negative.
        let cost = Cost {
            lut: lut.max(0.0) as u32,
            dsp,
            bram36: (fixed_bram + bram_placed).ceil() as u32,
            uram: slices * SLICE_URAM + uram_placed + table_uram as u32,
        };
        // The human-readable line: hash, routing, S-box split, scheme.
        let route = if self.uses_shared_line() { " on the shared line" } else { "" };
        let tables = if self.chain_hash == 0 && self.table_rounds > 0 {
            format!(
                ", T-tables in {} rounds/lane ({}){}",
                self.table_rounds,
                if table_rounds_built(self.table_rounds) { "v5 synth" } else { "cost interpolated" },
                if table_uram > 0.0 { format!(", {table_uram:.0} URAM of tables (model)") } else { String::new() }
            )
        } else {
            String::new()
        };
        let sboxes = if build.uram_per_lane + build.bram_per_lane > 0 {
            let left = SBOXES_PER_LANE - table_lookups(self.table_rounds) as u32;
            format!(
                "{tables}, S-boxes/lane {} URAM + {} BRAM + {} LUT (pairs, est.)",
                build.uram_per_lane,
                build.bram_per_lane,
                left - build.uram_per_lane - build.bram_per_lane
            )
        } else {
            tables
        };
        let status = if self.measured(slices) {
            "built, card-measured 6.02M/s"
        } else if Self::BUILT_SLICES.contains(&slices) {
            "built"
        } else {
            "model"
        };
        let certs = if self.own_ed25519 { "own Ed25519 core" } else { "certs by Ed25519 sign module" };
        let detail = format!(
            "{slices} slice{} ({status}), {} chains{route}{sboxes}; {}; {certs}",
            if slices == 1 { "" } else { "s" },
            HASHES[self.chain_hash],
            self.hbss.label()
        );
        (cost, detail)
    }

    /// Signatures per second of `slices` slices at `mhz`.
    ///
    /// The slice ceiling `slices × f / key period`; with DSig's own Ed25519
    /// core also capped by the certificate ceiling `K × f / 895` (otherwise
    /// the planner sizes the chip's Ed25519 signer for `1/K` of this rate). Unlike
    /// [`config::Build::signatures_per_second`] it leaves out the frame-write
    /// stage, which is never the limit at these slice counts in that model.
    /// With the shared SHA-512 line, the line's supply is checked by the
    /// planner through this plan's demand, not here.
    #[must_use]
    pub fn rate(&self, slices: u32, mhz: f64) -> f64 {
        // The slower of "keys made" and "batches certified × K".
        let keys = f64::from(slices) * mhz * 1e6 / self.hbss.key_period();
        if self.own_ed25519 { keys.min(certificate_ceiling(self.hbss, mhz)) } else { keys }
    }

    /// Whether this configuration rests on measurement: the routed
    /// all-LUT Haraka two-slice kernel with the built scheme and its own
    /// Ed25519 core (build v3, measured on the card).
    fn measured(&self, slices: u32) -> bool {
        self.chain_hash == 0
            && !self.blake3_dsp
            && slices == 2
            && !self.sbox_ram
            // (No table rounds, so "table RAM" has nothing to place.)
            && self.table_rounds == 0
            && self.hbss.built()
            && self.own_ed25519
    }
}

/// How the chip planner talks to the DSig signer.
impl Component for Dsig {
    /// The row label in the planner.
    fn name(&self) -> String {
        "DSig sign".into()
    }

    /// Tells the planner this component supplies DSig signatures.
    fn role(&self) -> Role {
        Role::DsigSign
    }

    /// The knobs, in the order [`Component::set_knob`] indexes them:
    /// 0 HBSS, 1 chain hash, 2 SHA lanes, 3 Winternitz w, 4 batch K (these
    /// five shared with [`DsigVerify`]), 5 S-box RAM, 6 BLAKE3 adders,
    /// 7 Ed25519 certificates, 8 table rounds, 9 table RAM (the last two
    /// the signer's own; the verify unit has separate ones).
    fn knobs(&self) -> Vec<Knob> {
        let [scheme, w, batch] = self.hbss.knobs();
        vec![
            scheme,
            Knob::choice("chain hash", self.chain_hash, &HASHES).shared(),
            Knob::choice("SHA lanes", usize::from(self.sha_shared), &SHA_ROUTES).shared(),
            w,
            batch,
            // Choice 0 is "fill", so the flag is inverted for the index.
            Knob::choice("S-box RAM", usize::from(!self.sbox_ram), &["fill", "LUT only"]),
            Knob::choice("BLAKE3 adders", usize::from(self.blake3_dsp), &["LUT", "DSP (est.)"]),
            Knob::choice(
                "Ed25519 certs",
                usize::from(self.own_ed25519),
                &["chip's Ed25519 sign module", "inside DSig (as built: own small signer)"],
            ),
            Knob::choice("table rounds", self.table_rounds as usize, &TABLE_ROUNDS),
            Knob::choice("table RAM", usize::from(self.table_uram), &TABLE_RAM),
            Knob::choice("certificate checks", usize::from(self.own_ed25519), &VERIFY_CERTS),
            Knob::choice("message", usize::from(self.message64), &MESSAGES).shared(),
        ]
    }

    /// Applies a knob change from the planner. `value` is the chosen index
    /// as a float; out-of-range indices are clamped to the last choice.
    fn set_knob(&mut self, index: usize, value: f64) {
        // The chosen index, never negative.
        let pick = value.max(0.0) as usize;
        match index {
            0 => self.hbss.set(0, pick),
            1 => self.chain_hash = pick.min(2),
            2 => self.sha_shared = pick >= 1,
            3 => self.hbss.set(1, pick),
            4 => self.hbss.set(2, pick),
            // Index 0 ("fill") means S-boxes in RAM.
            5 => self.sbox_ram = pick == 0,
            6 => self.blake3_dsp = pick >= 1,
            7 => self.own_ed25519 = pick >= 1,
            8 => self.table_rounds = pick.min(AUTO_TABLE_ROUNDS as usize) as u32,
            9 => self.table_uram = pick >= 1,
            10 => self.own_ed25519 = pick >= 1,
            _ => self.message64 = pick >= 1,
        }
    }

    /// HORS has no plan yet.
    fn unavailable(&self) -> Option<String> {
        (self.hbss.scheme == Scheme::Hors).then(|| HORS_TODO.into())
    }

    /// The largest slice count whose cost fits `share`, or `None` if even
    /// one slice does not fit (or the HBSS is HORS, which has no model).
    ///
    /// Sizes are tried smallest first. The first size that does not fit stops
    /// the search, and the resource it ran out of becomes the plan's `limit`,
    /// so the planner can tell the user what to add.
    fn plan(&self, share: &Share, cx: &Context) -> Option<Plan> {
        // Auto: plan every fixed table-round count and keep the best.
        if self.table_rounds == AUTO_TABLE_ROUNDS {
            return best_over_table_rounds((0..=6).filter_map(|rounds| {
                Dsig { table_rounds: rounds, ..self.clone() }.plan(share, cx)
            }));
        }
        // The clock the planner is evaluating at.
        let mhz = cx.mhz;
        // The best fitting plan so far.
        let mut best: Option<Plan> = None;
        if self.hbss.scheme != Scheme::WotsPlus {
            return None;
        }
        for slices in 1..=Self::MAX_SLICES {
            // Kernel cost of this size under the current knobs and share.
            let (cost, detail) = self.cost(slices, share);
            if !cost.fits(share) {
                // Too big: say what ran out (if a smaller size fit) and stop.
                if let Some(plan) = best.as_mut() {
                    plan.limit = cost.limit(share).into();
                }
                break;
            }
            // Fits: record it and try the next larger size.
            let rate = self.rate(slices, mhz);
            // Blocks the chain lanes take from the shared line, if they use it.
            let demands = if self.uses_shared_line() {
                vec![Flow {
                    service: SHA512_BLOCKS,
                    per_second: rate * self.hbss.steps_per_key(),
                }]
            } else {
                Vec::new()
            };
            // What caps the rate: the slices or the certificate core.
            let capped = self.own_ed25519 && certificate_ceiling(self.hbss, mhz) < f64::from(slices) * mhz * 1e6 / self.hbss.key_period();
            best = Some(Plan {
                cost,
                rate,
                unit: "signatures",
                limit: if capped { "Ed25519 certificate core".into() } else { String::new() },
                detail,
                demands,
                supplies: vec![Flow {
                    service: "dsig signatures",
                    per_second: rate,
                }],
                measured: self.measured(slices),
                latency_cycles: SIGN_LATENCY_CYCLES,
                // Little's law: requests in flight = rate × time in system.
                in_flight: rate * SIGN_LATENCY_CYCLES / (mhz * 1e6),
                // Keys per Ed25519 certificate: sets Ed25519 sign need (1/K)
                // and the verify cache-hit fraction.
                batch: Some(f64::from(self.hbss.batch)),
                // With its own core DSig signs its certificates itself.
                covers: if self.own_ed25519 { vec![Role::Ed25519Sign] } else { Vec::new() },
            });
        }
        if let Some(plan) = best.as_mut() {
            // Every size fit: the limit is the design itself, not the share.
            if plan.limit.is_empty() {
                plan.limit = format!("slice count ({} is the model's largest)", Self::MAX_SLICES);
            }
        }
        best
    }

    /// The build variables that build `plan` (`DSIG_SLICES`, `DSIG_CHAIN`
    /// and, for Haraka, `DSIG_TABLE_MASK` and `DSIG_SBOX_PLACEMENT`; see
    /// `build.rs`).
    ///
    /// The slice count is recovered from the plan's detail line (it starts
    /// with the count). Haraka builds also get the matching
    /// `DSIG_SBOX_PLACEMENT`, which needs the share; the TUI writes these
    /// for the plan it shows, so the placement is recomputed from the plan's
    /// own RAM cost.
    fn build_flags(&self, plan: &Plan) -> BuildFlags {
        // Slice count: the first word of the detail line.
        let slices: u32 = plan.detail.split_whitespace().next().and_then(|n| n.parse().ok()).unwrap_or(2);
        // `DSIG_CHAIN` value of the chosen chain hash.
        let chain = ["haraka", "blake3", "sha512"][self.chain_hash];
        // `key = value` pairs the TUI writes out; keys are prefixed `dsig.`.
        let mut flags = vec![
            ("dsig.DSIG_SLICES".into(), slices.to_string()),
            ("dsig.DSIG_CHAIN".into(), quoted(chain)),
            ("dsig.DSIG_MESSAGE_BYTES".into(), if self.message64 { "64" } else { "16" }.into()),
        ];
        if !self.own_ed25519 {
            flags.push(("dsig.certificates".into(), quoted("chip Ed25519 sign module (root port; not built)")));
        }
        // Table rounds the plan used (auto resolves to a fixed count per
        // plan; the detail line names it), and whether any table is in URAM.
        let rounds: u32 = plan
            .detail
            .split("T-tables in ")
            .nth(1)
            .and_then(|t| t.split_whitespace().next())
            .and_then(|n| n.parse().ok())
            .unwrap_or(0);
        let uram_tables = plan.detail.contains("URAM of tables");
        // S-box placement only exists for Haraka lanes; the plan's own RAM
        // cost is exactly the RAM its placement was allowed to use.
        if self.chain_hash == 0 {
            // T-table rounds 3 .. 3 + rounds (`DSIG_TABLE_MASK`, bits 3..=8).
            flags.push(("dsig.DSIG_TABLE_MASK".into(), quoted(&format!("{:#x}", ((1_u32 << rounds) - 1) << 3))));
            let build = Dsig { table_rounds: rounds, ..self.clone() }.placement(slices, &plan.cost);
            flags.push((
                "dsig.DSIG_SBOX_PLACEMENT".into(),
                quoted(&format!("uram={},bram={}", build.uram_per_lane, build.bram_per_lane)),
            ));
        }
        // Every reason this plan cannot be built as planned today.
        let slice_gap = format!("{slices} slice{} (DSIG_SLICES builds 2, 4 or 8)", if slices == 1 { "" } else { "s" });
        let gaps = [
            (!self.hbss.built(), "HBSS parameters other than W-OTS+ w=4, K=128"),
            (!Self::BUILT_SLICES.contains(&slices), slice_gap.as_str()),
            (self.uses_shared_line(), "chain lanes on the shared SHA-512 line"),
            (self.message64, "64-byte messages (profile 2): simulated, not yet exported or card-built"),
            (self.blake3_dsp, "BLAKE3 adders in DSPs"),
            (!self.own_ed25519, "certificates from the chip's Ed25519 sign module"),
            (uram_tables, "T-tables in UltraRAM"),
        ];
        flags.extend(buildable(gaps.iter().filter(|(gap, _)| *gap).map(|(_, why)| *why)));
        flags
    }
}

/// Idle signing latency: **native simulation** (cycle-accurate RHDL, not the
/// card) of the slice signer behind the uBFT service's request stream
/// (`tests/ubft_signer.rs`, 2 slices, 8 isolated requests after the first
/// certificate: 171–188 cycles, mean 173.1, every frame the reference
/// signature). A key is cached and its certificate made, so this is the
/// message digest, the 68-cycle schedule slot it waits for, the node reads
/// from the key cache, the 26-beat frame and the relay registers. It replaces
/// an unmeasured 64-cycle estimate (28 BLAKE3 + 26 beats + ~10 registers)
/// that left out the schedule wait and the cache reads. The batch kernel's
/// HBM reader and writer add their own cycles (not measured).
///
/// Unit: clock cycles. The planner uses it for idle latency and, with
/// Little's law, for the number of signatures in flight.
pub const SIGN_LATENCY_CYCLES: f64 = 173.0;

/// Idle signing latency of the **whole uBFT service kernel**
/// ([`crate::ubft::UbftEngine`]): native simulation, `tests/ubft_engine.rs`,
/// request beat to the frame's last beat, 6 isolated requests after the
/// first certificate. Profile 1: 207–217 cycles, mean 208.7 (1.01–1.06 µs
/// at 205 MHz); profile 2 (64-byte messages): 207–257, mean 215.3. It is
/// [`SIGN_LATENCY_CYCLES`] (the signer alone) plus the engine's stream
/// registers and arbitration, about 36 cycles. The uBFT signing component
/// uses this one, since a replica sees the whole kernel.
#[cfg(feature = "ubft")]
pub const UBFT_SIGN_LATENCY_CYCLES: f64 = 209.0;

// ------------------------------------------------------------ verify model
//
// The verifier is built ([`crate::verify`]): units of three recirculating
// chain lanes and one BLAKE3 lane, plus (as built) the Ed25519 project's
// known-key verify core for certificates. A unit walks each chain from the
// revealed node to its end, rebuilds the endpoint commitment, then climbs
// the Merkle path to the batch root:
//
//   revealed nodes ──(3 − digit) chain steps each──▶ 68 ends
//        ──21 BLAKE3──▶ commitment ──7 BLAKE3──▶ root ──(cache miss)──▶ Ed25519
//
// Where each figure comes from:
//
// | Figure | Value | Provenance |
// |---|---|---|
// | core cost, Haraka, 4 table rounds | 89,627 LUT, 282 BRAM36 | verifier kernel build v1 routed (31e0144, mean of 3 cores); alone (OOC, fba2a3d) 80,211 LUT, 273 BRAM36, WNS +0.258 ns |
// | cycles per verification | 35.12 | native simulation, 256 records (91bebd0) |
// | idle latency of the hash path | 729 cycles | native simulation, one record, instant certificate |
// | unit I/O (reader, writer, its share of the cluster) | 6,083 LUT | build v1 routed |
// | Ed25519 verify core (fix14) | 79,532 LUT, 698 DSP, 43 BRAM36, 176 URAM | build v3 routed (OOC 007zzr: 84,435 LUT, WNS +0.072 ns) |
// | kernel timing at 205 MHz | met, WNS +0.016 ns, 368,713 LUT | build v3 routed |
// | kernel rate on the card | ≥ 16,959,195 verifications/s, 3 units | build v3, finite burst of 1,572,864 |
// | its rate and latency | 0.279M/s; 52,670 cycles isolated, 63,026 median loaded | Ed25519 project, native simulation |

/// Expected chain steps to finish one DSig verification: 68 W-OTS+ chains
/// (w = 4) each need `3 − digit` steps; the 64 message digits are uniform
/// (mean 1.5 steps) and the 4 checksum digits skew low.
///
/// Unit: chain steps per verification (expected value). Native simulation
/// of 256 real records measured 101.4.
pub const VERIFY_CHAIN_STEPS: f64 = 105.0;
/// CLB LUTs of one routed verify core (Haraka lanes with
/// [`VERIFY_CORE_TABLE_ROUNDS`] table rounds) inside the kernel:
/// **measured**, mean of the three cores of verifier build v1 (Vivado
/// 2023.2 routed, 89,495–89,716). Routed alone (OOC) it was 80,211.
pub const VERIFY_CORE_LUT: f64 = 89_627.0;
/// Block-RAM tiles of that core in the kernel (88 RAMB36 + 388 RAMB18):
/// **measured**, build v1.
pub const VERIFY_CORE_BRAM36: f64 = 282.0;
/// Table rounds of the measured core's lanes (`DSIG_TABLE_MASK=0x078`).
pub const VERIFY_CORE_TABLE_ROUNDS: u32 = 4;
/// LUTs of a unit beyond its core: HBM reader and writer and its share of
/// the cluster (registered links, registers, arbiter). **Measured**, build
/// v1: (366,916 engine − 79,786 Ed25519) / 3 units − 89,627 per core.
pub const VERIFY_UNIT_IO_LUT: f64 = 6_083.0;
/// Cycles per verification of one core for the built scheme: **native
/// simulation** (two whole batches, steady state).
pub const VERIFY_CYCLES_MEASURED: f64 = 35.12;
/// Idle latency of the hash path for the built scheme (first beat to
/// verdict, certificate already checked): **native simulation**.
pub const VERIFY_LATENCY_MEASURED: f64 = 729.0;
/// The Ed25519 known-key verify core a verifier embeds (fix14, constant
/// banks as `ConstRom`): CLB LUTs inside the verifier kernel, **measured**
/// (build v3, routed, `engine/c1`: 79,532). Alone it routes at 84,435 with
/// WNS +0.072 ns (Ed25519 project, 007zzr; fix12 in build v1: 79,786 in
/// context, 82,184 alone).
pub const VERIFY_ED25519_LUT: f64 = 79_532.0;
/// The verifier kernel's card rate: **measured** (build v3, three units,
/// 1,572,864 valid signatures in 19,012,289 cycles at 205.00 MHz, finite
/// burst `vrun-clean-1`): 12.09 cycles per signature for the kernel, 36.3
/// per unit.
pub const VERIFY_CARD_RATE: f64 = 16_959_195.0;
/// Units in the card-measured verifier kernel.
pub const VERIFY_CARD_UNITS: u32 = 3;
/// Its DSP slices (**measured**, 007zzi).
pub const VERIFY_ED25519_DSP: u32 = 698;
/// Its block-RAM tiles (41 RAMB36 + 4 RAMB18; **measured**, 007zzi).
pub const VERIFY_ED25519_BRAM36: u32 = 43;
/// Its UltraRAMs (**measured**, 007zzi).
pub const VERIFY_ED25519_URAM: u32 = 176;
/// Its certificate checks per second at 205 MHz: **native simulation**
/// (Ed25519 project, fix12 dcb2e6e: 600 verifications, 735.25 cycles each).
pub const VERIFY_ED25519_RATE: f64 = 278_810.0;
/// Its latency per check, saturated median: **native simulation** (Ed25519
/// project: min 54,144, median 63,026, p90 81,738 cycles; isolated ~52k).
/// The verifier's verdict queue hides it after a run's first batch.
pub const VERIFY_ED25519_LATENCY: f64 = 63_026.0;
/// Its latency for an isolated check: **native simulation** (Ed25519
/// project, one request at a time, 4 samples: 52,642–52,672, median 52,670).
pub const VERIFY_ED25519_ISOLATED: f64 = 52_670.0;

/// DSig verification (built: [`crate::verify`]).
///
/// A verify unit has three chain lanes and one BLAKE3 lane, like a slice.
/// Its rate is set by its busier side: chain steps over three lanes, or
/// BLAKE3 compressions on one lane. The Ed25519 certificate check (`1 − h`
/// of verifications) is done by the Ed25519 verify component, not here.
/// Its knobs must match the signer's for the two to verify each other.
#[derive(Clone, Debug)]
pub struct DsigVerify {
    /// 0 Haraka-512, 1 BLAKE3, 2 SHA-512 (must match the signer).
    pub chain_hash: usize,
    /// SHA-512 chains on the shared line instead of own pipelines.
    pub sha_shared: bool,
    /// The hash-based scheme (must match the signer).
    pub hbss: Hbss,
    /// Profile 2: 64-byte messages (must match the signer).
    pub message64: bool,
    /// Table rounds of the unit's three Haraka lanes (0..=6, see
    /// [`table_lane`], or [`AUTO_TABLE_ROUNDS`], the default). Independent of the signer's: the verify unit is
    /// separate hardware, so a BRAM-bound chip can give tables to one and
    /// LUT S-boxes to the other.
    pub table_rounds: u32,
    /// Table lookups beyond the share's block RAM go to its UltraRAM, as
    /// [`Dsig::table_uram`]. **Model.** On by default, like the signer's.
    pub table_uram: bool,
    /// Certificates are checked by the verifier's own Ed25519 verify core
    /// (as built) instead of the chip's Ed25519 verify module.
    pub own_ed25519: bool,
}

/// Haraka-512 chains, the built HBSS and auto table rounds, matching the
/// default signer; certificates on the chip's Ed25519 verify module.
impl Default for DsigVerify {
    fn default() -> Self {
        Self {
            chain_hash: 0,
            sha_shared: false,
            hbss: Hbss::default(),
            message64: false,
            table_rounds: AUTO_TABLE_ROUNDS,
            table_uram: true,
            own_ed25519: false,
        }
    }
}

impl DsigVerify {
    /// Whether the chain lanes hash on the shared SHA-512 line.
    #[must_use]
    pub fn uses_shared_line(&self) -> bool {
        self.chain_hash == 2 && self.sha_shared
    }

    /// LUTs and block RAM of a verify core beyond its three chain lanes:
    /// the measured core minus its three lanes (as the lane model prices
    /// them). The BLAKE3 lane, scheduler, banks and cache are all in here.
    #[must_use]
    pub fn core_rest() -> (f64, f64) {
        let (lane_lut, lane_bram) = table_lane(VERIFY_CORE_TABLE_ROUNDS);
        (VERIFY_CORE_LUT - 3.0 * lane_lut, VERIFY_CORE_BRAM36 - 3.0 * lane_bram)
    }

    /// Cost of one verify unit: three chain lanes of the chosen hash, the
    /// measured rest of the core, and the unit's HBM I/O.
    #[must_use]
    pub fn unit_cost(&self) -> Cost {
        // LUTs of one chain lane of the selected hash and routing.
        let lane = match self.chain_hash {
            0 => table_lane(self.table_rounds).0,
            1 => BLAKE3_LANE_LUT,
            _ if self.sha_shared => SHA512_CLIENT_LUT,
            _ => SHA512_LANE_LUT,
        };
        let (rest_lut, rest_bram) = Self::core_rest();
        Cost {
            lut: (3.0 * lane + rest_lut + VERIFY_UNIT_IO_LUT + if self.message64 { MESSAGE64_VERIFY_LUT } else { 0.0 }) as u32,
            dsp: 0,
            bram36: (rest_bram + if self.chain_hash == 0 { 3.0 * table_lane(self.table_rounds).1 } else { 0.0 }).ceil()
                as u32,
            uram: 0,
        }
    }

    /// The embedded Ed25519 verify core, when certificates are checked inside.
    #[must_use]
    pub fn ed25519_cost(&self) -> Cost {
        if self.own_ed25519 {
            Cost {
                lut: VERIFY_ED25519_LUT as u32,
                dsp: VERIFY_ED25519_DSP,
                bram36: VERIFY_ED25519_BRAM36,
                uram: VERIFY_ED25519_URAM,
            }
        } else {
            Cost::default()
        }
    }

    /// Whether this configuration is the one measured (costs from Vivado,
    /// period from simulation).
    #[must_use]
    pub fn is_measured(&self) -> bool {
        self.chain_hash == 0
            && self.table_rounds == VERIFY_CORE_TABLE_ROUNDS
            && self.hbss == Hbss::default()
            && !self.table_uram
    }

    /// Cost of `units` units inside `share`, and the URAM their tables took.
    ///
    /// Without "table RAM" on URAM this is `units × unit_cost`. With it, the
    /// table block RAM that the share cannot hold moves to UltraRAM, and every
    /// lane gets a [`TABLE_LOADER_LUT`] loader.
    #[must_use]
    pub fn units_cost(&self, units: u32, share: &Share) -> (Cost, f64) {
        let total = Cost::default().add(self.unit_cost(), units).add(self.ed25519_cost(), 1);
        let table_bram = if self.chain_hash == 0 { 3.0 * table_lane(self.table_rounds).1 * f64::from(units) } else { 0.0 };
        if !self.table_uram || table_bram == 0.0 {
            return (total, 0.0);
        }
        let fixed = f64::from(total.bram36) - table_bram;
        let (kept, uram) = spill_tables(table_bram, f64::from(share.bram36) - fixed, f64::from(share.uram));
        let loaders = if uram > 0.0 { 3.0 * f64::from(units) * TABLE_LOADER_LUT } else { 0.0 };
        let cost = Cost {
            lut: total.lut + loaders as u32,
            bram36: (fixed + kept).ceil() as u32,
            uram: total.uram + uram as u32,
            ..total
        };
        (cost, uram)
    }

    /// Cycles per verification of one unit: the busier of chain steps over
    /// three lanes and BLAKE3 compressions on one lane (35 for the built
    /// scheme: 105 / 3 versus 29). The built scheme uses the measured period.
    #[must_use]
    pub fn cycles_per_verify(&self) -> f64 {
        if self.hbss == Hbss::default() && self.chain_hash == 0 {
            VERIFY_CYCLES_MEASURED
        } else {
            (self.hbss.verify_steps() / 3.0).max(self.hbss.verify_blake3())
        }
    }

    /// Idle latency of the hash path. The built scheme uses the measured
    /// figure; others scale it by their chain and commitment depth.
    #[must_use]
    pub fn latency_cycles(&self) -> f64 {
        let model = |v: &DsigVerify| {
            f64::from(v.hbss.w - 1) * (CHAIN_LATENCY[v.chain_hash] + 1.0) + v.hbss.verify_blake3() * 34.0
        };
        VERIFY_LATENCY_MEASURED * model(self) / model(&DsigVerify::default())
    }
}

/// How the chip planner talks to the verifier model.
impl Component for DsigVerify {
    /// The row label.
    fn name(&self) -> String {
        "DSig verify".into()
    }

    /// Tells the planner this component supplies DSig verifications.
    fn role(&self) -> Role {
        Role::DsigVerify
    }

    /// Knobs: 0 HBSS, 1 chain hash, 2 SHA lanes, 3 Winternitz w, 4 batch K,
    /// 5 table rounds, 6 table RAM. The first five are shared with the
    /// signer (the TUI shows them under DSig sign); the last two are the
    /// unit's own.
    fn knobs(&self) -> Vec<Knob> {
        let [scheme, w, batch] = self.hbss.knobs();
        vec![
            scheme,
            Knob::choice("chain hash", self.chain_hash, &HASHES).shared(),
            Knob::choice("SHA lanes", usize::from(self.sha_shared), &SHA_ROUTES).shared(),
            w,
            batch,
            Knob::choice("table rounds", self.table_rounds as usize, &TABLE_ROUNDS),
            Knob::choice("table RAM", usize::from(self.table_uram), &TABLE_RAM),
            Knob::choice("certificate checks", usize::from(self.own_ed25519), &VERIFY_CERTS),
            Knob::choice("message", usize::from(self.message64), &MESSAGES).shared(),
        ]
    }

    /// Applies a knob change, clamping out-of-range indices.
    fn set_knob(&mut self, index: usize, value: f64) {
        let pick = value.max(0.0) as usize;
        match index {
            0 => self.hbss.set(0, pick),
            1 => self.chain_hash = pick.min(2),
            2 => self.sha_shared = pick >= 1,
            3 => self.hbss.set(1, pick),
            4 => self.hbss.set(2, pick),
            5 => self.table_rounds = pick.min(AUTO_TABLE_ROUNDS as usize) as u32,
            6 => self.table_uram = pick >= 1,
            7 => self.own_ed25519 = pick >= 1,
            _ => self.message64 = pick >= 1,
        }
    }

    /// HORS has no plan yet.
    fn unavailable(&self) -> Option<String> {
        (self.hbss.scheme == Scheme::Hors).then(|| HORS_TODO.into())
    }

    /// `DSIG_VERIFY_UNITS` and the lanes' table mask; what is not built yet
    /// is named.
    fn build_flags(&self, plan: &Plan) -> BuildFlags {
        let units: u32 = plan.detail.split_whitespace().next().and_then(|n| n.parse().ok()).unwrap_or(1);
        let mut gaps = Vec::new();
        if !self.own_ed25519 {
            gaps.push("certificates on the chip's Ed25519 verify module (built kernel embeds its own)");
        }
        if self.table_uram && plan.detail.contains("URAM of tables") {
            gaps.push("T-tables in URAM (model)");
        }
        if self.hbss != Hbss::default() {
            gaps.push("only W-OTS+ w=4, K=128 is built");
        }
        if self.message64 {
            gaps.push("64-byte messages (profile 2): simulated, not yet exported or card-built");
        }
        let mut flags = buildable(gaps.into_iter());
        flags.push(("dsig.DSIG_VERIFY_UNITS".into(), units.to_string()));
        flags.push(("dsig.DSIG_MESSAGE_BYTES".into(), if self.message64 { "64" } else { "16" }.into()));
        if self.chain_hash == 0 {
            let rounds = if self.table_rounds == AUTO_TABLE_ROUNDS { VERIFY_CORE_TABLE_ROUNDS } else { self.table_rounds };
            flags.push(("dsig.DSIG_TABLE_MASK".into(), quoted(&format!("{:#x}", ((1_u32 << rounds) - 1) << 3))));
        }
        flags.push(("dsig.DSIG_CHAIN".into(), quoted(["haraka", "blake3", "sha512"][self.chain_hash])));
        flags
    }

    /// As many identical verify units as the share's LUTs and BRAM allow.
    ///
    /// Unlike the signer, units scale one by one, so the plan is a simple
    /// division. The Ed25519 check on cache misses is planned separately.
    fn plan(&self, share: &Share, cx: &Context) -> Option<Plan> {
        if self.hbss.scheme != Scheme::WotsPlus {
            return None;
        }
        // Auto: plan every fixed table-round count and keep the best.
        if self.table_rounds == AUTO_TABLE_ROUNDS {
            return best_over_table_rounds((0..=6).filter_map(|rounds| {
                DsigVerify { table_rounds: rounds, ..self.clone() }.plan(share, cx)
            }));
        }
        // One unit's cost.
        let unit = self.unit_cost();
        let ed = self.ed25519_cost();
        if ed.lut > share.lut || ed.dsp > share.dsp || ed.bram36 > share.bram36 || ed.uram > share.uram {
            return None;
        }
        // Whole units that fit next to the Ed25519 core (if any), limited by
        // LUTs or by BRAM, whichever is tighter (`max(1)` avoids dividing by
        // zero).
        let mut units = ((share.lut - ed.lut) / unit.lut.max(1)).min((share.bram36 - ed.bram36) / unit.bram36.max(1));
        // With tables allowed in URAM, add units while the spilled cost fits.
        if self.table_uram {
            while self.units_cost(units + 1, share).0.fits(share) {
                units += 1;
            }
        }
        if units == 0 {
            return None;
        }
        // Verifications per second of all units together; an own Ed25519
        // core caps them at one certificate check per K verifications.
        let mut rate = f64::from(units) * cx.mhz * 1e6 / self.cycles_per_verify();
        if self.own_ed25519 {
            rate = rate.min(VERIFY_ED25519_RATE * cx.mhz / 205.0 * f64::from(self.hbss.batch));
        }
        // Idle latency of one verification.
        // Idle latency of the hash path, plus (with an own Ed25519 core) the
        // certificate check for the share of verifications whose batch is
        // not already checked: (1 − h) × the isolated check latency.
        let mut latency = self.latency_cycles();
        if self.own_ed25519 {
            latency += (1.0 - cx.cache_hit(f64::from(self.hbss.batch))) * VERIFY_ED25519_ISOLATED;
        }
        // Total cost of `units` units, and URAM taken by their tables.
        let (cost, table_uram) = self.units_cost(units, share);
        // Blocks taken from the shared line, if the lanes use it.
        let demands = if self.uses_shared_line() {
            vec![Flow {
                service: SHA512_BLOCKS,
                per_second: rate * self.hbss.verify_steps(),
            }]
        } else {
            Vec::new()
        };
        Some(Plan {
            cost,
            rate,
            unit: "verifications",
            // What would run out first if one more unit were added.
            limit: self.units_cost(units + 1, share).0.limit(share).into(),
            detail: format!(
                "{units} units × 3 {} lanes{} + 1 BLAKE3 lane; {:.2} cycles/verify ({}); {}; hit rate {:.1} %{}",
                HASHES[self.chain_hash],
                if self.chain_hash != 0 || self.table_rounds == 0 {
                    String::new()
                } else if table_uram > 0.0 {
                    format!(" ({} table rounds, {table_uram:.0} URAM of tables)", self.table_rounds)
                } else {
                    format!(" ({} table rounds)", self.table_rounds)
                },
                self.cycles_per_verify(),
                if self.hbss == Hbss::default() && self.chain_hash == 0 { "native sim" } else { "model" },
                self.hbss.label(),
                100.0 * cx.cache_hit(f64::from(self.hbss.batch)),
                if self.own_ed25519 { "; own Ed25519 verify core" } else { "" }
            ),
            demands,
            supplies: vec![Flow {
                service: "dsig verifies",
                per_second: rate,
            }],
            measured: self.is_measured(),
            latency_cycles: latency,
            in_flight: rate * latency / (cx.mhz * 1e6),
            batch: Some(f64::from(self.hbss.batch)),
            covers: if self.own_ed25519 { vec![Role::Ed25519Verify] } else { Vec::new() },
        })
    }
}

/// Checks that the planner component agrees with measurement and behaves
/// sensibly as the budget grows.
// ------------------------------------------------------------ uBFT service
//
// DSig as uBFT's signature service (`crate::ubft`, feature `ubft`): the
// planner's uBFT modes (`rhdl_fpga_planner::ubft`) plan these two modules
// beside the uBFT replica. A slot needs one signature and 2f verifications,
// so the right build is the smallest one, and its idle latency is the
// headline: more slices or units would not shorten a lone request.

/// Isolated verify latency of the uBFT service with its certificate already
/// checked: **native simulation** (`tests/ubft_blocks.rs`, instant Ed25519
/// model, header handshake to verdict: 732–736 cycles; the verify core alone
/// is [`VERIFY_LATENCY_MEASURED`]).
#[cfg(feature = "ubft")]
pub const UBFT_VERIFY_LATENCY_CYCLES: f64 = 734.0;

/// Slice counts the uBFT signer can be built with (`DSIG_SLICES`).
#[cfg(feature = "ubft")]
pub const UBFT_SLICES: [u32; 3] = [2, 4, 8];
/// Their names in the Tuner.
#[cfg(feature = "ubft")]
const UBFT_SLICE_NAMES: [&str; 3] = ["2", "4", "8"];
/// The uBFT services' profile-1 gate in the Tuner.
#[cfg(feature = "ubft")]
const UBFT_PROFILE1: [&str; 2] = ["refused (U33)", "allowed (U33 open)"];

/// The reason a uBFT plan in profile 1 is not buildable unless allowed:
/// profile 1 signs view, slot, k and m only, so the session, the role and
/// the CTB fields of uBFT's 48-byte context are not authenticated (audit
/// finding U33) and the CTB role cannot be signed at all.
#[cfg(feature = "ubft")]
const UBFT_PROFILE1_GAP: &str =
    "uBFT with 16-byte messages (profile 1) leaves U33 open and cannot sign CTB; set 'profile 1 for uBFT' to allowed";

/// The uBFT services' message settings, shared by signer and verifier.
/// Profile 2 is the default: it signs uBFT's whole context.
#[cfg(feature = "ubft")]
#[derive(Clone, Copy, Debug)]
pub struct UbftMessage {
    /// Profile 2: 64-byte messages (`DSIG_MESSAGE_BYTES=64`).
    pub message64: bool,
    /// Accept profile 1 under uBFT anyway (`dsig.allow_profile1_ubft`).
    pub allow_profile1: bool,
}

#[cfg(feature = "ubft")]
impl Default for UbftMessage {
    /// Profile 2, profile 1 refused.
    fn default() -> Self {
        Self { message64: true, allow_profile1: false }
    }
}

#[cfg(feature = "ubft")]
impl UbftMessage {
    /// Its two knobs, both shared by the uBFT signer and verifier.
    fn knobs(self) -> [Knob; 2] {
        [
            Knob::choice("message", usize::from(self.message64), &MESSAGES).shared(),
            Knob::choice("profile 1 for uBFT", usize::from(self.allow_profile1), &UBFT_PROFILE1).shared(),
        ]
    }
    /// Sets knob `index` (0: message, 1: the profile-1 gate).
    fn set(&mut self, index: usize, value: f64) {
        match index {
            0 => self.message64 = value >= 1.0,
            1 => self.allow_profile1 = value >= 1.0,
            _ => {}
        }
    }
    /// Whether the plan can be built, the message length and the gate.
    fn flags(self) -> BuildFlags {
        let refused = !self.message64 && !self.allow_profile1;
        let mut flags = buildable(refused.then_some(UBFT_PROFILE1_GAP).into_iter());
        flags.push(("dsig.DSIG_MESSAGE_BYTES".into(), if self.message64 { "64" } else { "16" }.into()));
        flags.push(("dsig.allow_profile1_ubft".into(), self.allow_profile1.to_string()));
        flags
    }
}

/// DSig signing as a uBFT service: the batch signer's slices and certificate
/// unit behind a request stream ([`crate::ubft::UbftSigner`]), with its own
/// Ed25519 certificate core and the T-table rounds of the measured builds.
#[cfg(feature = "ubft")]
#[derive(Clone, Debug)]
pub struct DsigUbftSign {
    /// Slices (2 is the smallest buildable signer).
    pub slices: u32,
    /// Message profile and the profile-1 gate.
    pub message: UbftMessage,
}

#[cfg(feature = "ubft")]
impl Default for DsigUbftSign {
    /// Two slices: the smallest build; a uBFT slot needs one signature.
    /// Profile 2.
    fn default() -> Self {
        Self { slices: 2, message: UbftMessage::default() }
    }
}

#[cfg(feature = "ubft")]
impl DsigUbftSign {
    /// The signer model it prices with.
    fn inner(&self) -> Dsig {
        Dsig {
            own_ed25519: true,
            table_rounds: 4,
            message64: self.message.message64,
            ..Dsig::default()
        }
    }
}

#[cfg(feature = "ubft")]
impl Component for DsigUbftSign {
    fn name(&self) -> String {
        "DSig sign (uBFT service)".into()
    }
    fn role(&self) -> Role {
        Role::DsigSign
    }
    /// The slice count, a choice of exactly the counts `DSIG_SLICES`
    /// builds (2, 4, 8; its value is the index into [`UBFT_SLICES`]); then
    /// the message profile and the profile-1 gate ([`UbftMessage`]).
    fn knobs(&self) -> Vec<Knob> {
        let index = UBFT_SLICES.iter().position(|&n| n == self.slices).unwrap_or(0);
        let mut knobs = vec![Knob::choice("slices", index, &UBFT_SLICE_NAMES)];
        knobs.extend(self.message.knobs());
        knobs
    }
    fn set_knob(&mut self, index: usize, value: f64) {
        if index == 0 {
            self.slices = UBFT_SLICES[(value.max(0.0) as usize).min(UBFT_SLICES.len() - 1)];
        } else {
            self.message.set(index - 1, value);
        }
    }
    fn plan(&self, share: &Share, cx: &Context) -> Option<Plan> {
        let inner = self.inner();
        let (cost, detail) = inner.cost(self.slices, share);
        if !cost.fits(share) {
            return None;
        }
        let rate = inner.rate(self.slices, cx.mhz);
        Some(Plan {
            cost,
            rate,
            unit: "signatures",
            limit: "fixed size (a slot needs one signature)".into(),
            detail: format!(
                "uBFT service, {detail}; isolated latency {UBFT_SIGN_LATENCY_CYCLES:.0} cycles through the whole kernel (native sim); AXI4-Stream requests"
            ),
            demands: Vec::new(),
            supplies: vec![Flow {
                service: "dsig signatures",
                per_second: rate,
            }],
            measured: false,
            latency_cycles: UBFT_SIGN_LATENCY_CYCLES,
            in_flight: 1.0,
            batch: Some(f64::from(inner.hbss.batch)),
            covers: vec![Role::Ed25519Sign],
        })
    }
    fn build_flags(&self, _plan: &Plan) -> BuildFlags {
        // Every slice count it offers lowers (`DSIG_SLICES` = 2, 4 or 8),
        // in either message profile (the uBFT exporter builds both); the
        // 2-slice service is the one being routed.
        let mut flags = self.message.flags();
        flags.extend([
            ("dsig.DSIG_SLICES".into(), self.slices.to_string()),
            ("dsig.DSIG_TABLE_MASK".into(), quoted("0x78")),
            ("dsig.features".into(), quoted("ubft")),
        ]);
        flags
    }
    fn ubft(&self) -> bool {
        true
    }
}

/// DSig verification as a uBFT service: one verify core behind a request
/// stream ([`crate::ubft::UbftVerifier`]) and the Ed25519 known-key verify
/// core with one key slot per peer replica.
#[cfg(feature = "ubft")]
#[derive(Clone, Debug, Default)]
pub struct DsigUbftVerify {
    /// Message profile and the profile-1 gate (shared with the signer).
    pub message: UbftMessage,
}

#[cfg(feature = "ubft")]
impl DsigUbftVerify {
    /// The verifier model it prices with.
    fn inner(&self) -> DsigVerify {
        DsigVerify {
            own_ed25519: true,
            table_rounds: 4,
            table_uram: false,
            message64: self.message.message64,
            ..DsigVerify::default()
        }
    }
}

#[cfg(feature = "ubft")]
impl Component for DsigUbftVerify {
    fn name(&self) -> String {
        "DSig verify (uBFT service)".into()
    }
    fn role(&self) -> Role {
        Role::DsigVerify
    }
    /// The message profile and the profile-1 gate ([`UbftMessage`]).
    fn knobs(&self) -> Vec<Knob> {
        self.message.knobs().to_vec()
    }
    fn set_knob(&mut self, index: usize, value: f64) {
        self.message.set(index, value);
    }
    fn plan(&self, share: &Share, cx: &Context) -> Option<Plan> {
        let inner = self.inner();
        let (cost, _) = inner.units_cost(1, share);
        if !cost.fits(share) {
            return None;
        }
        let batch = f64::from(inner.hbss.batch);
        let rate = (cx.mhz * 1e6 / inner.cycles_per_verify()).min(VERIFY_ED25519_RATE * cx.mhz / 205.0 * batch);
        // A miss waits for one Ed25519 check; hits do not.
        let latency = UBFT_VERIFY_LATENCY_CYCLES + (1.0 - cx.cache_hit(batch)) * VERIFY_ED25519_ISOLATED;
        Some(Plan {
            cost,
            rate,
            unit: "verifications",
            limit: "fixed size (a slot needs 2f verifications)".into(),
            detail: format!(
                "uBFT service, 1 unit; {:.0} cycles with the certificate cached (native sim), +{VERIFY_ED25519_ISOLATED:.0} on a miss; \
                 8 trusted-key slots (capacity 8; max active membership 7); hit rate {:.1} %",
                UBFT_VERIFY_LATENCY_CYCLES,
                100.0 * cx.cache_hit(batch)
            ),
            demands: Vec::new(),
            supplies: Vec::new(),
            measured: false,
            latency_cycles: latency,
            in_flight: 1.0,
            batch: Some(batch),
            covers: vec![Role::Ed25519Verify],
        })
    }
    fn build_flags(&self, _plan: &Plan) -> BuildFlags {
        let mut flags = self.message.flags();
        flags.push(("dsig.features".into(), quoted("ubft")));
        flags
    }
    fn ubft(&self) -> bool {
        true
    }
}

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

    /// The whole device as one share.
    fn device() -> Share {
        Share { lut: 1_303_680, dsp: 9_024, bram36: 2_016, uram: 960 }
    }

    /// The lane split must add back up to the routed kernel (within 1,000
    /// LUTs) for the one build that was actually routed.
    #[test]
    fn the_haraka_two_slice_cost_matches_the_routed_link() {
        // Default knobs except all S-boxes in LUTs, as in the routed link.
        let dsig = Dsig { sbox_ram: false, own_ed25519: true, table_rounds: 0, ..Dsig::default() };
        let (cost, _) = dsig.cost(2, &device());
        // Routed slices-2 link: 301,037 CLB LUT for the kernel.
        assert!((f64::from(cost.lut) - 301_037.0).abs() < 1_000.0, "{cost:?}");
        // The card-measured build stays labelled measured with the default
        // "table RAM" (it has no tables to place).
        assert!(dsig.measured(2));
    }

    /// With T-table lanes, the four-slice kernel adds back up to build v5's
    /// synthesized LUTs, and its block RAM fits the kernel region (1,776
    /// BRAM36), unlike build v4.
    #[test]
    fn the_table_four_slice_cost_matches_the_v5_synthesis() {
        let dsig = Dsig { own_ed25519: true, table_rounds: 6, ..Dsig::default() };
        let (cost, line) = dsig.cost(4, &device());
        assert!((f64::from(cost.lut) - V5_KERNEL_LUT_SYNTH).abs() < 10.0, "{cost:?}");
        assert!(cost.bram36 < 1_776, "{cost:?}");
        assert!(line.contains("T-tables"), "{line}");
        assert!(!dsig.measured(4) && !dsig.measured(2), "synthesis is not a measurement");
        // A table lane is about a third of a LUT S-box lane.
        assert!((7_000.0..8_000.0).contains(&HARAKA_TABLE_LANE_LUT));
        // The interpolation meets both builds and trades LUTs for BRAM.
        assert_eq!(table_lane(0), (HARAKA_LANE_LUT, 0.0));
        assert!((table_lane(6).0 - HARAKA_TABLE_LANE_LUT).abs() < 1e-6);
        assert_eq!(table_lane(6).1, HARAKA_TABLE_LANE_BRAM36);
        for n in 0..6 {
            assert!(table_lane(n + 1).0 < table_lane(n).0 && table_lane(n + 1).1 > table_lane(n).1);
        }
        assert!(table_rounds_built(6) && !table_rounds_built(3));
    }

    /// Auto is never worse than any fixed table-round count, for the signer
    /// and the verify unit, in a LUT-rich and a BRAM-poor share.
    #[test]
    fn auto_table_rounds_is_the_best_fixed_count() {
        let cx = Context::default();
        let shares = [
            Share { lut: 600_000, dsp: 2_000, bram36: 600, uram: 900 },
            Share { lut: 300_000, dsp: 2_000, bram36: 1_700, uram: 900 },
        ];
        for share in shares {
            let rate = |p: Option<Plan>| p.map_or(0.0, |p| p.rate);
            let auto = rate(Dsig { table_rounds: AUTO_TABLE_ROUNDS, ..Dsig::default() }.plan(&share, &cx));
            let auto_v = rate(DsigVerify { table_rounds: AUTO_TABLE_ROUNDS, ..DsigVerify::default() }.plan(&share, &cx));
            for rounds in 0..=6 {
                assert!(auto >= rate(Dsig { table_rounds: rounds, ..Dsig::default() }.plan(&share, &cx)));
                assert!(auto_v >= rate(DsigVerify { table_rounds: rounds, ..DsigVerify::default() }.plan(&share, &cx)));
            }
        }
    }

    /// The built scheme's derived numbers match the hardware constants.
    #[test]
    fn the_built_scheme_matches_the_hardware() {
        let h = Hbss::default();
        assert_eq!(h.chains(), crate::CHAINS as u32);
        assert_eq!(h.steps_per_key(), 204.0);
        assert_eq!(h.key_period(), config::KEY_PERIOD);
        assert_eq!(h.signature_bytes(), 1_642);
        assert_eq!(h.merkle_height(), crate::MERKLE_HEIGHT as u32);
        assert_eq!(Hbss { w: 16, ..Hbss::default() }.chains(), 35);
    }

    /// Tables in URAM: on a share with little block RAM the signer and the
    /// verifier both get faster, never slower, and the plan still fits.
    #[test]
    fn table_uram_turns_spare_ultraram_into_speed() {
        let cx = Context::default();
        let rate = |p: Option<Plan>| p.map_or(0.0, |p| p.rate);
        let share = Share { lut: 600_000, dsp: 2_000, bram36: 900, uram: 900 };
        for rounds in [6, AUTO_TABLE_ROUNDS] {
            let bram = Dsig { table_rounds: rounds, table_uram: false, ..Dsig::default() };
            let uram = Dsig { table_uram: true, ..bram.clone() };
            let plan = uram.plan(&share, &cx).expect("a plan");
            assert!(plan.cost.fits(&share), "{plan:?}");
            assert!(plan.rate >= rate(bram.plan(&share, &cx)));
            let vbram = DsigVerify { table_rounds: rounds, table_uram: false, ..DsigVerify::default() };
            let vuram = DsigVerify { table_uram: true, ..vbram.clone() };
            let vplan = vuram.plan(&share, &cx).expect("a plan");
            assert!(vplan.cost.fits(&share), "{vplan:?}");
            assert!(vplan.rate >= rate(vbram.plan(&share, &cx)));
        }
        // Six table rounds per lane: block RAM caps the signer, URAM lifts it.
        let six = Dsig { table_rounds: 6, table_uram: false, ..Dsig::default() };
        let lifted = Dsig { table_uram: true, ..six.clone() }.plan(&share, &cx).unwrap();
        assert!(lifted.rate > rate(six.plan(&share, &cx)), "{}", lifted.detail);
        assert!(lifted.cost.uram > 0 && lifted.detail.contains("URAM of tables"));
    }

    /// Monotonicity: more LUTs must not lower the planned rate.
    #[test]
    fn more_budget_never_gives_fewer_signatures() {
        let dsig = Dsig::default();
        let cx = Context::default();
        let mut last = 0.0;
        for lut in (100_000..=1_000_000).step_by(50_000) {
            let share = Share { lut, ..device() };
            let rate = dsig.plan(&share, &cx).map_or(0.0, |p| p.rate);
            assert!(rate >= last, "{lut}");
            last = rate;
        }
    }

    /// A partial share of the chip's RAM still plans (the bug the TUI hit:
    /// S-box placement used to size itself for the whole device).
    #[test]
    fn a_quarter_of_the_chip_still_plans_a_signer() {
        let share = Share { lut: 230_000, dsp: 1_125, bram36: 504, uram: 240 };
        let plan = Dsig { sbox_ram: true, table_rounds: 0, ..Dsig::default() }.plan(&share, &Context::default()).expect("a plan");
        assert!(plan.cost.fits(&share), "{plan:?}");
        assert!(plan.rate > 0.0);
    }

    /// The shared "message" knob reaches signer and verifier, adds its
    /// (estimated) LUTs, and keeps the signing rate.
    #[test]
    fn the_message_knob_is_shared_priced_and_flagged() {
        let mut signer = Dsig::default();
        let mut verify = DsigVerify::default();
        let share = Share { lut: 600_000, ..device() };
        let (base, _) = signer.cost(2, &share);
        let base_unit = verify.unit_cost();
        let at = |knobs: &[Knob]| knobs.iter().position(|k| k.name == "message").unwrap();
        let (si, vi) = (at(&signer.knobs()), at(&verify.knobs()));
        assert!(signer.knobs()[si].shared && verify.knobs()[vi].shared);
        // The "certificate checks" knob sets its own field (it used to fall
        // through to "table RAM").
        let ci = signer.knobs().iter().position(|k| k.name == "certificate checks").unwrap();
        signer.set_knob(ci, 1.0);
        assert!(signer.own_ed25519 && signer.table_uram);
        signer.set_knob(ci, 0.0);
        signer.set_knob(si, 1.0);
        verify.set_knob(vi, 1.0);
        assert!(signer.message64 && verify.message64);
        let (wide, _) = signer.cost(2, &share);
        assert_eq!(wide.lut, base.lut + 2 * MESSAGE64_SLICE_LUT as u32);
        assert_eq!(verify.unit_cost().lut, base_unit.lut + MESSAGE64_VERIFY_LUT as u32);
        assert_eq!(signer.rate(2, 205.0), Dsig::default().rate(2, 205.0), "same signing rate");
    }

    /// The rate grows with every slice the share holds (not only at 2, 4,
    /// 8), and a cheaper chain hash buys more slices in the same LUTs.
    #[test]
    fn rate_scales_slice_by_slice_and_with_the_hash() {
        let cx = Context::default();
        let share = Share { lut: 600_000, ..device() };
        // LUT S-boxes on both sides: the comparison is about LUTs per slice.
        let haraka = Dsig { table_rounds: 0, ..Dsig::default() }.plan(&share, &cx).unwrap();
        let blake3 = Dsig { chain_hash: 1, table_rounds: 0, ..Dsig::default() }.plan(&share, &cx).unwrap();
        assert!(blake3.rate > haraka.rate, "{} vs {}", blake3.detail, haraka.detail);
        let slices = |p: &Plan| p.detail.split_whitespace().next().unwrap().parse::<u32>().unwrap();
        assert!((haraka.rate - f64::from(slices(&haraka)) * 205e6 / 68.0).abs() < 1.0);
    }

    /// HORS plans nothing and says why; DSig's own Ed25519 core covers
    /// Ed25519 signing.
    #[test]
    fn hors_is_unavailable_and_own_core_covers_ed25519_sign() {
        let mut d = Dsig::default();
        d.set_knob(0, 1.0);
        assert!(d.plan(&device(), &Context::default()).is_none() && d.unavailable().is_some());
        let own = Dsig { own_ed25519: true, ..Dsig::default() };
        let plan = own.plan(&device(), &Context::default()).unwrap();
        assert_eq!(plan.covers, vec![Role::Ed25519Sign]);
        assert!(Dsig::default().plan(&device(), &Context::default()).unwrap().covers.is_empty());
    }

    /// SHA-512 chains on the shared line demand 204 blocks per signature;
    /// on own lanes they demand none.
    #[test]
    fn shared_sha_chains_demand_line_blocks() {
        let cx = Context::default();
        let own = Dsig { chain_hash: 2, ..Dsig::default() };
        let shared = Dsig { sha_shared: true, ..own.clone() };
        let p = shared.plan(&device(), &cx).unwrap();
        assert_eq!(p.demands[0].per_second, p.rate * 204.0);
        assert!(own.plan(&device(), &cx).unwrap().demands.is_empty());
    }

    /// The uBFT signer offers exactly the slice counts DSIG_SLICES builds.
    #[cfg(feature = "ubft")]
    #[test]
    fn ubft_signer_slices_are_the_buildable_counts() {
        let mut signer = DsigUbftSign::default();
        let knob = &signer.knobs()[0];
        assert_eq!(knob.choices, ["2", "4", "8"]);
        for (index, slices) in UBFT_SLICES.iter().enumerate() {
            signer.set_knob(0, index as f64);
            assert_eq!(signer.slices, *slices);
            assert_eq!(signer.knobs()[0].value, index as f64);
        }
        signer.set_knob(0, 9.0);
        assert_eq!(signer.slices, 8, "out of range clamps to the last choice");
    }

    /// uBFT defaults to profile 2; profile 1 is buildable only when the
    /// gate allows it, in both services, and the flags say which.
    #[cfg(feature = "ubft")]
    #[test]
    fn ubft_defaults_to_profile_2_and_gates_profile_1() {
        let flag = |flags: &BuildFlags, key: &str| flags.iter().find(|(k, _)| k == key).map(|(_, v)| v.clone());
        let cx = Context::default();
        let mut signer = DsigUbftSign::default();
        let mut verify = DsigUbftVerify::default();
        let components: [&mut dyn Component; 2] = [&mut signer, &mut verify];
        for c in components {
            let knobs = c.knobs();
            let at = knobs.iter().position(|k| k.name == "message").unwrap();
            assert!(knobs[at].shared && knobs[at + 1].shared && knobs[at + 1].name == "profile 1 for uBFT");
            assert_eq!(knobs[at].value, 1.0, "profile 2 by default");
            let plan = c.plan(&device(), &cx).unwrap();
            let f = c.build_flags(&plan);
            assert_eq!(flag(&f, "buildable").as_deref(), Some("true"));
            assert_eq!(flag(&f, "dsig.DSIG_MESSAGE_BYTES").as_deref(), Some("64"));
            assert_eq!(flag(&f, "dsig.allow_profile1_ubft").as_deref(), Some("false"));
            // Profile 1, refused: priced, but not buildable, with the reason.
            c.set_knob(at, 0.0);
            let plan = c.plan(&device(), &cx).unwrap();
            let f = c.build_flags(&plan);
            assert_eq!(flag(&f, "buildable").as_deref(), Some("false"));
            assert!(flag(&f, "not_buildable").unwrap().contains("U33"));
            assert_eq!(flag(&f, "dsig.DSIG_MESSAGE_BYTES").as_deref(), Some("16"));
            // Profile 1, allowed.
            c.set_knob(at + 1, 1.0);
            let f = c.build_flags(&plan);
            assert_eq!(flag(&f, "buildable").as_deref(), Some("true"));
            assert_eq!(flag(&f, "dsig.allow_profile1_ubft").as_deref(), Some("true"));
        }
        // Profile 2 prices its extra digest block.
        let p1 = DsigUbftSign { message: UbftMessage { message64: false, allow_profile1: true }, ..DsigUbftSign::default() };
        let lut = |c: &dyn Component| c.plan(&device(), &cx).unwrap().cost.lut;
        assert!(lut(&DsigUbftSign::default()) > lut(&p1));
    }
}