wots_rhdl/

top.rs

//! Three-cluster SHA-profile signer top.
//!
//! [`SignerTop`] is the narrow global layer above three structurally identical
//! four-context lane clusters. It admits at most one job per cycle, preserves
//! each cluster's local `0..=3` tag namespace, and merges only registered
//! 512-bit cluster beats plus compact error metadata. Complete context results
//! and context RAM ports never cross this boundary.
//!
//! The data path has two explicit ownership stages. A rotating arbiter first
//! registers one cluster as frame owner. On the following cycle, a canonical
//! cluster beat may enter the one-entry global elastic register. The owner stays
//! locked through beat 34, so frames cannot interleave. When that final beat is
//! captured, its cluster may release local credit because the global register
//! now owns the transfer. External delivery is counted separately when the
//! downstream consumer accepts the registered final beat.
//!
//! While an output beat is stalled, every data and metadata bit remains stable.
//! If the consumer accepts it, the register may capture the next beat in the
//! same cycle. Capturing a final beat also pre-grants a different already-primed
//! cluster. Consequently that next cluster can refill the global register in
//! the stalled final beat's eventual downstream-handshake cycle, without an
//! extra inter-frame output bubble after the registered grant stage.
//!
//! Error completions use an independent one-entry elastic merge. The selected
//! cluster alone receives `error_ready`; after capture, the global register
//! owns the job identity, local context, and cluster identity until the host
//! accepts exactly one notification.
//!
//! Canonical `keep`, `last`, final padding, beat count, and frame job identity
//! are checked before a cluster receives data `ready`. A violation is never
//! captured, latches a structural fault, and requires shared reset. Shared reset
//! also flushes all three clusters, grant state, output-valid bits, and error
//! ownership. Resetless beat/job registers are ignored while their resettable
//! valid bits are clear.
//!
//! This module is Rust/RHDL source. Behavioral or generated-hierarchy evidence
//! does not imply synthesis, placement, routing, resource, timing, throughput,
//! side-channel, or FPGA-card evidence.

use rhdl::{core::ReplicatedSynchronous, prelude::*};
use rhdl_fpga::core::dff::DFF;
use rhdl_primitives::NoResetDff;
use sha256_rhdl::lane::{ExternalFullCompressionLane, InlineCompressionLane};

use crate::{
    blocks::HashBytes,
    cluster::{CompressionLaneComponent, LaneLocalBeat, LaneLocalCluster, LaneLocalClusterInput},
    digits::MessageBytes,
};

/// Number of independently placed lane-local signer clusters.
pub const SIGNER_CLUSTER_COUNT: usize = 3;
/// Number of beats in one canonical fused output frame.
pub const SIGNER_FRAME_BEATS: usize = 35;

const _: () = {
    assert!(SIGNER_CLUSTER_COUNT == 3);
    assert!(SIGNER_FRAME_BEATS == 35);
};

/// One selectable registered cluster beat.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalFrameSource {
    /// A complete local registered beat is available.
    pub valid: bool,
    /// Registered cluster beat and opaque job metadata.
    pub beat: LaneLocalBeat,
}

/// Global output beat with source-cluster identity outside SHA state.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct SignerOutputBeat {
    /// Canonical 512-bit fused-result transfer.
    pub beat: LaneLocalBeat,
    /// Cluster `0..=2` that produced the frame.
    pub cluster: b2,
}

/// Inputs for defensive canonical-control and frame-identity validation.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalBeatValidationInput {
    /// Candidate registered cluster beat.
    pub beat: LaneLocalBeat,
    /// Expected frame beat index `0..=34`.
    pub expected_beat: b6,
    /// Job identity retained from beat zero.
    pub expected_job_id: b32,
    /// Whether the retained identity must already match.
    pub check_job_id: bool,
}

/// Validate one candidate before granting its cluster `ready`.
///
/// Beats 0 through 33 require all 64 byte lanes and must not assert `last`.
/// Beat 34 requires only its low 32 lanes, asserts `last`, and keeps invalid high
/// lanes zero. Every beat after beat zero must retain the same opaque job ID.
#[kernel]
#[allow(clippy::comparison_chain, clippy::needless_range_loop)] // Pinned RHDL does not lower ordering matches or iterators.
pub fn global_beat_is_canonical_kernel(input: GlobalBeatValidationInput) -> bool {
    let job_matches = !input.check_job_id || input.beat.job_id == input.expected_job_id;
    let mut final_padding_zero = true;
    for lane in 32..64 {
        if input.beat.data[lane] != b8(0) {
            final_padding_zero = false;
        }
    }
    let control_matches = if input.expected_beat < b6(34) {
        input.beat.keep == b64(0xffff_ffff_ffff_ffff) && !input.beat.last
    } else if input.expected_beat == b6(34) {
        input.beat.keep == b64(0xffff_ffff) && input.beat.last && final_padding_zero
    } else {
        false
    };
    job_matches && control_matches
}

/// Three-way rotating selection result.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalLaneSelection {
    /// At least one eligible cluster exists.
    pub valid: bool,
    /// Selected cluster `0..=2`.
    pub cluster: b2,
    /// Cursor following the selected cluster.
    pub next_cursor: b2,
}

/// Select one of three eligible clusters with rotating fairness.
#[kernel]
#[allow(clippy::assign_op_pattern)] // Compound assignment is not lowered by pinned RHDL.
pub fn select_global_lane_kernel(
    eligible: [bool; SIGNER_CLUSTER_COUNT],
    cursor: b2,
) -> GlobalLaneSelection {
    let normalized_cursor = if cursor < b2(3) { cursor } else { b2(0) };
    let mut selection = GlobalLaneSelection {
        next_cursor: normalized_cursor,
        ..GlobalLaneSelection::default()
    };
    let mut scan = normalized_cursor;
    for _offset in 0..SIGNER_CLUSTER_COUNT {
        if !selection.valid && eligible[scan] {
            selection.valid = true;
            selection.cluster = scan;
            selection.next_cursor = if scan == b2(2) { b2(0) } else { scan + b2(1) };
        }
        scan = if scan == b2(2) { b2(0) } else { scan + b2(1) };
    }
    selection
}

/// Input to the registered, frame-locked data merge.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalFrameMergeInput {
    /// Registered beat heads from clusters zero through two.
    pub clusters: [GlobalFrameSource; SIGNER_CLUSTER_COUNT],
    /// Downstream acceptance for the global output register.
    pub output_ready: bool,
}

/// Data-merge controls, registered output, and audit pulses.
#[allow(clippy::struct_excessive_bools)] // Independent handshake and audit wires.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalFrameMergeOutput {
    /// Ready is asserted only to the locked cluster when a canonical beat fits.
    pub cluster_ready: [bool; SIGNER_CLUSTER_COUNT],
    /// A global registered output beat is available.
    pub output_valid: bool,
    /// Registered beat and source identity, stable under downstream stalls.
    pub output: SignerOutputBeat,
    /// One frame currently owns the cluster-side merge.
    pub frame_active: bool,
    /// Locked cluster, meaningful while `frame_active`.
    pub frame_cluster: b2,
    /// Next cluster-side beat index expected from the owner.
    pub expected_beat: b6,
    /// A cluster beat entered the global register this cycle.
    pub captured: bool,
    /// Captured beat was beat 34 and returned local cluster credit.
    pub captured_final: bool,
    /// Registered final beat transferred to the external consumer this cycle.
    pub delivered_final: bool,
    /// Sticky canonical-control, job-identity, or ownership fault.
    pub fault: bool,
}

/// Narrow resettable state for [`GlobalFrameMerge`].
#[allow(clippy::struct_excessive_bools)] // Each bit is an independent protocol owner.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalFrameMergeControl {
    /// Rotating frame-grant cursor.
    pub cursor: b2,
    /// One cluster owns the cluster-side frame merge.
    pub frame_active: bool,
    /// Current frame owner.
    pub frame_cluster: b2,
    /// Next expected beat index.
    pub expected_beat: b6,
    /// One global output beat is retained.
    pub output_valid: bool,
    /// Source cluster stored alongside the output beat.
    pub output_cluster: b2,
    /// Sticky structural fault.
    pub fault: bool,
}

/// Registered global frame merge with one elastic output slot.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct GlobalFrameMerge {
    control: DFF<GlobalFrameMergeControl>,
    frame_job_id: NoResetDff<b32>,
    output: NoResetDff<LaneLocalBeat>,
}

impl Default for GlobalFrameMerge {
    fn default() -> Self {
        Self {
            control: DFF::new(GlobalFrameMergeControl::default()),
            frame_job_id: NoResetDff::new(),
            output: NoResetDff::new(),
        }
    }
}

impl SynchronousIO for GlobalFrameMerge {
    type I = GlobalFrameMergeInput;
    type O = GlobalFrameMergeOutput;
    type Kernel = global_frame_merge_kernel;
}

#[kernel]
fn select_frame_source_kernel(
    sources: [GlobalFrameSource; SIGNER_CLUSTER_COUNT],
    cluster: b2,
) -> GlobalFrameSource {
    match cluster {
        Bits::<2>(0) => sources[0],
        Bits::<2>(1) => sources[1],
        _ => sources[2],
    }
}

/// State transition for [`GlobalFrameMerge`].
#[kernel]
pub fn global_frame_merge_kernel(
    clock_reset: ClockReset,
    input: GlobalFrameMergeInput,
    q: GlobalFrameMergeQ,
) -> (GlobalFrameMergeOutput, GlobalFrameMergeD) {
    let resetting = clock_reset.reset.any();
    let mut control = q.control;
    let mut frame_job_id = q.frame_job_id;
    let mut output_beat = q.output;
    let mut cluster_ready = [false; SIGNER_CLUSTER_COUNT];
    let mut captured = false;
    let mut captured_final = false;

    let ownership_fault = q.control.cursor >= b2(3)
        || (q.control.frame_active && q.control.frame_cluster >= b2(3))
        || (q.control.frame_active && q.control.expected_beat >= b6(35))
        || (q.control.output_valid && q.control.output_cluster >= b2(3));
    let output_valid = !resetting && q.control.output_valid && !q.control.fault && !ownership_fault;
    let output_handshake = output_valid && input.output_ready;
    let delivered_final = output_handshake && q.output.last;
    let output_capacity = !q.control.output_valid || output_handshake;
    if output_handshake {
        control.output_valid = false;
    }

    if !resetting && ownership_fault {
        control.fault = true;
        control.frame_active = false;
    }

    if !resetting && q.control.frame_active && !q.control.fault && !ownership_fault {
        let source = select_frame_source_kernel(input.clusters, q.control.frame_cluster);
        if source.valid {
            let canonical = global_beat_is_canonical_kernel(GlobalBeatValidationInput {
                beat: source.beat,
                expected_beat: q.control.expected_beat,
                expected_job_id: q.frame_job_id,
                check_job_id: q.control.expected_beat != b6(0),
            });
            if !canonical {
                control.fault = true;
                control.frame_active = false;
            } else if output_capacity {
                cluster_ready[q.control.frame_cluster] = true;
                output_beat = source.beat;
                control.output_cluster = q.control.frame_cluster;
                control.output_valid = true;
                captured = true;
                if q.control.expected_beat == b6(0) {
                    frame_job_id = source.beat.job_id;
                }
                if q.control.expected_beat == b6(34) {
                    captured_final = true;
                    control.frame_active = false;
                    control.expected_beat = b6(0);

                    // Register a different already-primed owner while the
                    // final beat moves into the global output register. That
                    // owner can refill on the final beat's later handshake.
                    let eligible = [
                        input.clusters[0].valid && q.control.frame_cluster != b2(0),
                        input.clusters[1].valid && q.control.frame_cluster != b2(1),
                        input.clusters[2].valid && q.control.frame_cluster != b2(2),
                    ];
                    let selection = select_global_lane_kernel(eligible, q.control.cursor);
                    if selection.valid {
                        control.frame_active = true;
                        control.frame_cluster = selection.cluster;
                        control.cursor = selection.next_cursor;
                    }
                } else {
                    control.expected_beat = q.control.expected_beat + b6(1);
                }
            }
        }
    } else if !resetting && !q.control.fault && !ownership_fault {
        let eligible = [
            input.clusters[0].valid,
            input.clusters[1].valid,
            input.clusters[2].valid,
        ];
        let selection = select_global_lane_kernel(eligible, q.control.cursor);
        if selection.valid {
            control.frame_active = true;
            control.frame_cluster = selection.cluster;
            control.expected_beat = b6(0);
            control.cursor = selection.next_cursor;
        }
    }

    if resetting {
        control = GlobalFrameMergeControl::default();
        cluster_ready = [false; SIGNER_CLUSTER_COUNT];
        captured = false;
        captured_final = false;
    }

    let output = GlobalFrameMergeOutput {
        cluster_ready,
        output_valid,
        output: SignerOutputBeat {
            beat: q.output,
            cluster: q.control.output_cluster,
        },
        frame_active: !resetting && q.control.frame_active,
        frame_cluster: q.control.frame_cluster,
        expected_beat: q.control.expected_beat,
        captured,
        captured_final,
        delivered_final,
        fault: !resetting && q.control.fault,
    };
    let d = GlobalFrameMergeD {
        control,
        frame_job_id,
        output: output_beat,
    };
    (output, d)
}

/// One held lane-local error completion offered to the global merge.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalErrorSource {
    /// A lane-local error completion is held.
    pub valid: bool,
    /// Opaque job identity retained by the lane cluster.
    pub job_id: b32,
    /// Local context `0..=3` that owned the failed job.
    pub context: b2,
}

/// Error completion returned to the host with global cluster identity.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct SignerErrorCompletion {
    /// Opaque failed-job identity.
    pub job_id: b32,
    /// Source cluster `0..=2`.
    pub cluster: b2,
    /// Source-local context `0..=3`.
    pub context: b2,
}

/// Input to the independent global error merge.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalErrorMergeInput {
    /// Held lane-local error completions.
    pub clusters: [GlobalErrorSource; SIGNER_CLUSTER_COUNT],
    /// Host acceptance for the global held error register.
    pub error_ready: bool,
}

/// Registered error output and per-cluster capture handshakes.
#[allow(clippy::struct_excessive_bools)] // Independent handshake and audit wires.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalErrorMergeOutput {
    /// Ready is asserted only to the selected lane-local error source.
    pub cluster_ready: [bool; SIGNER_CLUSTER_COUNT],
    /// A registered error completion is held for the host.
    pub error_valid: bool,
    /// Registered error metadata, stable under backpressure.
    pub error: SignerErrorCompletion,
    /// A cluster error entered the global register this cycle.
    pub captured: bool,
    /// A registered error transferred to the host this cycle.
    pub delivered: bool,
    /// Sticky cursor or ownership fault.
    pub fault: bool,
}

/// Resettable control for [`GlobalErrorMerge`].
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct GlobalErrorMergeControl {
    /// Rotating capture cursor.
    pub cursor: b2,
    /// One global error completion is retained.
    pub output_valid: bool,
    /// Source cluster stored with the output metadata.
    pub output_cluster: b2,
    /// Source-local context stored with the output metadata.
    pub output_context: b2,
    /// Sticky structural fault.
    pub fault: bool,
}

/// Independent one-entry elastic error-completion merge.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct GlobalErrorMerge {
    control: DFF<GlobalErrorMergeControl>,
    job_id: NoResetDff<b32>,
}

impl Default for GlobalErrorMerge {
    fn default() -> Self {
        Self {
            control: DFF::new(GlobalErrorMergeControl::default()),
            job_id: NoResetDff::new(),
        }
    }
}

impl SynchronousIO for GlobalErrorMerge {
    type I = GlobalErrorMergeInput;
    type O = GlobalErrorMergeOutput;
    type Kernel = global_error_merge_kernel;
}

/// State transition for [`GlobalErrorMerge`].
#[kernel]
pub fn global_error_merge_kernel(
    clock_reset: ClockReset,
    input: GlobalErrorMergeInput,
    q: GlobalErrorMergeQ,
) -> (GlobalErrorMergeOutput, GlobalErrorMergeD) {
    let resetting = clock_reset.reset.any();
    let mut control = q.control;
    let mut job_id = q.job_id;
    let mut cluster_ready = [false; SIGNER_CLUSTER_COUNT];
    let mut captured = false;
    let ownership_fault =
        q.control.cursor >= b2(3) || (q.control.output_valid && q.control.output_cluster >= b2(3));
    let error_valid = !resetting && q.control.output_valid && !q.control.fault && !ownership_fault;
    let delivered = error_valid && input.error_ready;
    let capacity = !q.control.output_valid || delivered;
    if delivered {
        control.output_valid = false;
    }

    if !resetting && ownership_fault {
        control.fault = true;
        control.output_valid = false;
    }

    if !resetting && !q.control.fault && !ownership_fault && capacity {
        let eligible = [
            input.clusters[0].valid,
            input.clusters[1].valid,
            input.clusters[2].valid,
        ];
        let selection = select_global_lane_kernel(eligible, q.control.cursor);
        if selection.valid {
            cluster_ready[selection.cluster] = true;
            control.cursor = selection.next_cursor;
            control.output_valid = true;
            control.output_cluster = selection.cluster;
            let selected = match selection.cluster {
                Bits::<2>(0) => input.clusters[0],
                Bits::<2>(1) => input.clusters[1],
                _ => input.clusters[2],
            };
            control.output_context = selected.context;
            job_id = selected.job_id;
            captured = true;
        }
    }

    if resetting {
        control = GlobalErrorMergeControl::default();
        cluster_ready = [false; SIGNER_CLUSTER_COUNT];
        captured = false;
    }

    let output = GlobalErrorMergeOutput {
        cluster_ready,
        error_valid,
        error: SignerErrorCompletion {
            job_id: q.job_id,
            cluster: q.control.output_cluster,
            context: q.control.output_context,
        },
        captured,
        delivered,
        fault: !resetting && q.control.fault,
    };
    let d = GlobalErrorMergeD { control, job_id };
    (output, d)
}

/// External streaming input to the three-cluster signer top.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct SignerTopInput {
    /// Offer one private-seed fused signing operation.
    pub start_valid: bool,
    /// Private seed consumed by the operation.
    pub private_seed: HashBytes,
    /// Already-hashed message selecting WOTS positions.
    pub message: MessageBytes,
    /// Opaque identity returned with data or error completion.
    pub job_id: b32,
    /// Downstream acceptance for the registered data output.
    pub output_ready: bool,
    /// Host acceptance for the independent registered error output.
    pub error_ready: bool,
}

/// Global signer status, data output, and independent error output.
///
/// `output` is meaningful only while `output_valid` is true, and `error` is
/// meaningful only while `error_valid` is true. Each registered payload remains
/// stable while its valid signal is asserted and the corresponding ready input
/// is false. When a valid signal is false, its resetless payload bits may be
/// stale or unspecified and must not be consumed.
#[allow(clippy::struct_excessive_bools)] // Independent host and audit handshakes.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct SignerTopOutput {
    /// At least one cluster can accept the offered job.
    pub start_ready: bool,
    /// The offered job transferred this cycle.
    pub start_accepted: bool,
    /// Cluster selected for the offered job.
    pub start_cluster: b2,
    /// Per-cluster admission readiness.
    pub cluster_start_ready: [bool; SIGNER_CLUSTER_COUNT],
    /// Per-cluster active-context status.
    pub cluster_context_active: [[bool; 4]; SIGNER_CLUSTER_COUNT],
    /// Per-cluster sticky fault status.
    pub cluster_fault: [bool; SIGNER_CLUSTER_COUNT],
    /// Per-cluster successful final-capture credit releases.
    pub cluster_credit_release: [bool; SIGNER_CLUSTER_COUNT],
    /// A registered global data beat is available and `output` is meaningful.
    pub output_valid: bool,
    /// Registered data beat and source cluster.
    ///
    /// Meaningful only when `output_valid`; stable while `output_valid` is true
    /// and the input `output_ready` is false.
    pub output: SignerOutputBeat,
    /// External consumer accepted a final data beat this cycle.
    pub delivered_final: bool,
    /// A registered global error completion is available and `error` is
    /// meaningful.
    pub error_valid: bool,
    /// Registered error metadata.
    ///
    /// Meaningful only when `error_valid`; stable while `error_valid` is true
    /// and the input `error_ready` is false.
    pub error: SignerErrorCompletion,
    /// Host accepted one error completion this cycle.
    pub delivered_error: bool,
    /// Sticky cluster or global structural fault.
    pub fault: bool,
}

/// Narrow resettable global admission/fault state.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct SignerTopControl {
    /// Rotating one-job admission cursor.
    pub admission_cursor: b2,
    /// Sticky union of cluster and merge faults.
    pub fault: bool,
}

/// Exactly three identical four-context lane clusters and narrow global merges.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct SignerTop<
    const ROUNDS: usize,
    const ADDRESS_BITS: usize,
    L = InlineCompressionLane<ROUNDS, ADDRESS_BITS>,
> where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
    L: CompressionLaneComponent,
{
    clusters:
        ReplicatedSynchronous<LaneLocalCluster<ROUNDS, ADDRESS_BITS, L>, SIGNER_CLUSTER_COUNT>,
    frames: GlobalFrameMerge,
    errors: GlobalErrorMerge,
    control: DFF<SignerTopControl>,
}

impl<const ROUNDS: usize, const ADDRESS_BITS: usize, L> Default
    for SignerTop<ROUNDS, ADDRESS_BITS, L>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
    L: CompressionLaneComponent + Default,
{
    fn default() -> Self {
        Self {
            clusters: ReplicatedSynchronous::new(LaneLocalCluster::default()),
            frames: GlobalFrameMerge::default(),
            errors: GlobalErrorMerge::default(),
            control: DFF::new(SignerTopControl::default()),
        }
    }
}

impl<const ROUNDS: usize, const ADDRESS_BITS: usize, L> SynchronousIO
    for SignerTop<ROUNDS, ADDRESS_BITS, L>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
    L: CompressionLaneComponent,
{
    type I = SignerTopInput;
    type O = SignerTopOutput;
    type Kernel = signer_top_with_lane_kernel<ROUNDS, ADDRESS_BITS, L>;
}

/// State transition and narrow global connectivity for an injected lane.
#[kernel]
#[allow(clippy::needless_range_loop)] // Iterators are not lowered by pinned RHDL kernels.
pub fn signer_top_with_lane_kernel<
    const ROUNDS: usize,
    const ADDRESS_BITS: usize,
    L: CompressionLaneComponent,
>(
    clock_reset: ClockReset,
    input: SignerTopInput,
    q: SignerTopQ<ROUNDS, ADDRESS_BITS, L>,
) -> (SignerTopOutput, SignerTopD<ROUNDS, ADDRESS_BITS, L>)
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    let resetting = clock_reset.reset.any();
    let cluster_start_ready = [
        q.clusters[0].start_ready,
        q.clusters[1].start_ready,
        q.clusters[2].start_ready,
    ];
    let cluster_fault = [
        q.clusters[0].fault,
        q.clusters[1].fault,
        q.clusters[2].fault,
    ];
    let observed_fault = cluster_fault[0]
        || cluster_fault[1]
        || cluster_fault[2]
        || q.frames.fault
        || q.errors.fault
        || q.control.admission_cursor >= b2(3);
    let fault = q.control.fault || observed_fault;
    let admission = select_global_lane_kernel(cluster_start_ready, q.control.admission_cursor);
    let start_ready = !resetting && !fault && admission.valid;
    let start_accepted = start_ready && input.start_valid;

    let mut control = q.control;
    if start_accepted {
        control.admission_cursor = admission.next_cursor;
    }
    if !resetting && observed_fault {
        control.fault = true;
    }
    if resetting {
        control = SignerTopControl::default();
    }

    let mut cluster_inputs = [LaneLocalClusterInput::default(); SIGNER_CLUSTER_COUNT];
    for cluster in 0..SIGNER_CLUSTER_COUNT {
        cluster_inputs[cluster].output_ready = !resetting && q.frames.cluster_ready[cluster];
        cluster_inputs[cluster].error_ready = !resetting && q.errors.cluster_ready[cluster];
    }
    if start_accepted {
        cluster_inputs[admission.cluster].start_valid = true;
        cluster_inputs[admission.cluster].private_seed = input.private_seed;
        cluster_inputs[admission.cluster].message = input.message;
        cluster_inputs[admission.cluster].job_id = input.job_id;
    }

    let frame_sources = [
        GlobalFrameSource {
            valid: q.clusters[0].output_valid,
            beat: q.clusters[0].output,
        },
        GlobalFrameSource {
            valid: q.clusters[1].output_valid,
            beat: q.clusters[1].output,
        },
        GlobalFrameSource {
            valid: q.clusters[2].output_valid,
            beat: q.clusters[2].output,
        },
    ];
    let error_sources = [
        GlobalErrorSource {
            valid: q.clusters[0].error_valid,
            job_id: q.clusters[0].error_job_id,
            context: q.clusters[0].error_context,
        },
        GlobalErrorSource {
            valid: q.clusters[1].error_valid,
            job_id: q.clusters[1].error_job_id,
            context: q.clusters[1].error_context,
        },
        GlobalErrorSource {
            valid: q.clusters[2].error_valid,
            job_id: q.clusters[2].error_job_id,
            context: q.clusters[2].error_context,
        },
    ];

    let output = SignerTopOutput {
        start_ready,
        start_accepted,
        start_cluster: admission.cluster,
        cluster_start_ready: if resetting || fault {
            [false; SIGNER_CLUSTER_COUNT]
        } else {
            cluster_start_ready
        },
        cluster_context_active: [
            q.clusters[0].context_active,
            q.clusters[1].context_active,
            q.clusters[2].context_active,
        ],
        cluster_fault: if resetting {
            [false; SIGNER_CLUSTER_COUNT]
        } else {
            cluster_fault
        },
        cluster_credit_release: [
            !resetting && q.clusters[0].output_credit_release,
            !resetting && q.clusters[1].output_credit_release,
            !resetting && q.clusters[2].output_credit_release,
        ],
        output_valid: !resetting && q.frames.output_valid,
        output: q.frames.output,
        delivered_final: !resetting && q.frames.delivered_final,
        error_valid: !resetting && q.errors.error_valid,
        error: q.errors.error,
        delivered_error: !resetting && q.errors.delivered,
        fault: !resetting && fault,
    };
    let d = SignerTopD::<ROUNDS, ADDRESS_BITS, L> {
        clusters: cluster_inputs,
        frames: GlobalFrameMergeInput {
            clusters: frame_sources,
            output_ready: input.output_ready,
        },
        errors: GlobalErrorMergeInput {
            clusters: error_sources,
            error_ready: input.error_ready,
        },
        control,
    };
    (output, d)
}

/// Native-lane transition retained for the original two-const API.
///
/// Generic parent lowering uses [`signer_top_with_lane_kernel`]. This wrapper
/// keeps callers of `signer_top_kernel::<ROUNDS, ADDRESS_BITS>`
/// source-compatible while selecting the checked inline lane.
#[kernel]
pub fn signer_top_kernel<const ROUNDS: usize, const ADDRESS_BITS: usize>(
    clock_reset: ClockReset,
    input: SignerTopInput,
    q: SignerTopQ<ROUNDS, ADDRESS_BITS>,
) -> (SignerTopOutput, SignerTopD<ROUNDS, ADDRESS_BITS>)
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    signer_top_with_lane_kernel::<ROUNDS, ADDRESS_BITS, InlineCompressionLane<ROUNDS, ADDRESS_BITS>>(
        clock_reset,
        input,
        q,
    )
}

/// Production three-cluster, 64-round SHA-profile signer top.
pub type Sha256SignerTop = SignerTop<64, 6>;

/// Production signer skeleton linked with a separately generated full SHA lane.
///
/// Behavioral simulation is identical to [`Sha256SignerTop`]. Its emitted HDL
/// intentionally leaves `sha256_compression_lane` unresolved until the exact
/// RHDL-generated lane artifact is supplied to an external parser.
pub type ModularSha256SignerTop = SignerTop<64, 6, ExternalFullCompressionLane>;

impl<const ROUNDS: usize, const ADDRESS_BITS: usize, L> SignerTop<ROUNDS, ADDRESS_BITS, L>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
    L: CompressionLaneComponent,
{
    /// Reads per-context compression-acceptance pulses from software simulation state.
    ///
    /// This hidden host helper is not part of [`SignerTopInput`],
    /// [`SignerTopOutput`], or the generated hardware interface. It exists so
    /// source-simulation gates can audit the exact amount of accepted SHA work
    /// without widening the production datapath or reproducing scheduler state
    /// in a test-only model.
    #[doc(hidden)]
    #[must_use]
    pub fn simulation_request_accepted(
        state: &<Self as Synchronous>::S,
    ) -> [[bool; 4]; SIGNER_CLUSTER_COUNT] {
        [
            state.0.clusters[0].request_accepted,
            state.0.clusters[1].request_accepted,
            state.0.clusters[2].request_accepted,
        ]
    }
}

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

    fn ready_cluster() -> LaneLocalClusterOutput {
        LaneLocalClusterOutput {
            start_ready: true,
            ..LaneLocalClusterOutput::default()
        }
    }

    fn ready_top_q() -> SignerTopQ<4, 2> {
        SignerTopQ::<4, 2> {
            clusters: [ready_cluster(); SIGNER_CLUSTER_COUNT],
            frames: GlobalFrameMergeOutput::default(),
            errors: GlobalErrorMergeOutput::default(),
            control: SignerTopControl::default(),
        }
    }

    #[test]
    fn admissions_fail_closed_on_every_fault_source_until_shared_reset() {
        let active_clock = clock_reset(clock(false), reset(false));
        let reset_clock = clock_reset(clock(false), reset(true));
        let offered = SignerTopInput {
            start_valid: true,
            ..SignerTopInput::default()
        };

        let (healthy, _) = signer_top_kernel::<4, 2>(active_clock, offered, ready_top_q());
        assert!(healthy.start_ready);
        assert!(healthy.start_accepted);

        for fault_source in 0..6 {
            let mut q = ready_top_q();
            match fault_source {
                0 => q.clusters[0].fault = true,
                1 => q.clusters[1].fault = true,
                2 => q.clusters[2].fault = true,
                3 => q.frames.fault = true,
                4 => q.errors.fault = true,
                _ => q.control.admission_cursor = b2(3),
            }
            let (faulted, d) = signer_top_kernel::<4, 2>(active_clock, offered, q);
            assert!(faulted.fault);
            assert!(!faulted.start_ready);
            assert!(!faulted.start_accepted);
            assert_eq!(faulted.cluster_start_ready, [false; SIGNER_CLUSTER_COUNT]);
            assert!(d.control.fault);
        }

        let mut sticky_q = ready_top_q();
        sticky_q.control.fault = true;
        let (sticky, sticky_d) = signer_top_kernel::<4, 2>(active_clock, offered, sticky_q);
        assert!(sticky.fault);
        assert!(!sticky.start_ready);
        assert!(!sticky.start_accepted);
        assert!(sticky_d.control.fault);

        let (during_reset, reset_d) = signer_top_kernel::<4, 2>(reset_clock, offered, sticky_q);
        assert!(!during_reset.fault);
        assert!(!during_reset.start_ready);
        assert!(!during_reset.start_accepted);
        assert_eq!(reset_d.control, SignerTopControl::default());

        let (recovered, _) = signer_top_kernel::<4, 2>(active_clock, offered, ready_top_q());
        assert!(recovered.start_ready);
        assert!(recovered.start_accepted);
        assert!(!recovered.fault);
    }

    #[test]
    fn error_and_data_ownership_are_independent_at_the_top_boundary() {
        let mut q = ready_top_q();
        let data = LaneLocalBeat {
            data: [b8(0x5a); 64],
            keep: b64(0xffff_ffff_ffff_ffff),
            last: false,
            job_id: b32(0x1234_5678),
        };
        q.frames.output_valid = true;
        q.frames.output = SignerOutputBeat {
            beat: data,
            cluster: b2(1),
        };
        q.frames.frame_active = true;
        q.frames.frame_cluster = b2(1);
        q.frames.cluster_ready = [false, true, false];
        q.errors.error_valid = true;
        q.errors.error = SignerErrorCompletion {
            job_id: b32(0xdead_beef),
            cluster: b2(0),
            context: b2(3),
        };
        q.errors.cluster_ready = [true, false, false];
        q.errors.delivered = true;

        let input = SignerTopInput {
            output_ready: false,
            error_ready: true,
            ..SignerTopInput::default()
        };
        let (output, d) =
            signer_top_kernel::<4, 2>(clock_reset(clock(false), reset(false)), input, q);
        assert!(output.output_valid);
        assert_eq!(output.output.beat, data);
        assert_eq!(output.output.cluster, b2(1));
        assert!(output.error_valid);
        assert_eq!(output.error.job_id, b32(0xdead_beef));
        assert_eq!(output.error.cluster, b2(0));
        assert_eq!(output.error.context, b2(3));
        assert!(output.delivered_error);

        // Each merge drives only its corresponding cluster handshake and host
        // ready input; neither channel can consume or rewrite the other.
        assert!(d.clusters[0].error_ready);
        assert!(!d.clusters[0].output_ready);
        assert!(d.clusters[1].output_ready);
        assert!(!d.clusters[1].error_ready);
        assert!(!d.clusters[2].output_ready);
        assert!(!d.clusters[2].error_ready);
        assert!(!d.frames.output_ready);
        assert!(d.errors.error_ready);
    }

    #[test]
    fn invalid_internal_merge_ownership_never_grants_or_delivers() {
        let active_clock = clock_reset(clock(false), reset(false));
        let frame_source = GlobalFrameSource {
            valid: true,
            beat: LaneLocalBeat {
                data: [b8(0x33); 64],
                keep: b64(0xffff_ffff_ffff_ffff),
                last: false,
                job_id: b32(0x1111_2222),
            },
        };
        let frame_input = GlobalFrameMergeInput {
            clusters: [frame_source; SIGNER_CLUSTER_COUNT],
            output_ready: true,
        };
        for corruption in 0..4 {
            let mut control = GlobalFrameMergeControl {
                frame_active: true,
                output_valid: true,
                ..GlobalFrameMergeControl::default()
            };
            match corruption {
                0 => control.cursor = b2(3),
                1 => control.frame_cluster = b2(3),
                2 => control.expected_beat = b6(35),
                _ => control.output_cluster = b2(3),
            }
            let q = GlobalFrameMergeQ {
                control,
                frame_job_id: b32(0x1111_2222),
                output: frame_source.beat,
            };
            let (output, d) = global_frame_merge_kernel(active_clock, frame_input, q);
            assert!(!output.output_valid);
            assert!(!output.delivered_final);
            assert!(!output.captured);
            assert_eq!(output.cluster_ready, [false; SIGNER_CLUSTER_COUNT]);
            assert!(d.control.fault);
            assert!(!d.control.frame_active);
        }

        let error_input = GlobalErrorMergeInput {
            clusters: [GlobalErrorSource {
                valid: true,
                job_id: b32(0xaaaa_5555),
                context: b2(2),
            }; SIGNER_CLUSTER_COUNT],
            error_ready: true,
        };
        for invalid_output_owner in [false, true] {
            let q = GlobalErrorMergeQ {
                control: GlobalErrorMergeControl {
                    cursor: if invalid_output_owner { b2(0) } else { b2(3) },
                    output_valid: invalid_output_owner,
                    output_cluster: if invalid_output_owner { b2(3) } else { b2(0) },
                    ..GlobalErrorMergeControl::default()
                },
                job_id: b32(0xaaaa_5555),
            };
            let (output, d) = global_error_merge_kernel(active_clock, error_input, q);
            assert!(!output.error_valid);
            assert!(!output.delivered);
            assert!(!output.captured);
            assert_eq!(output.cluster_ready, [false; SIGNER_CLUSTER_COUNT]);
            assert!(d.control.fault);
            assert!(!d.control.output_valid);
        }
    }
}