Doc

def test_justified_divergence_self_heals_in_next_block(
    fork_choice_test: ForkChoiceTestFiller,
) -> None:
    """
    A block adopts the votes that justify a slot from a fork it did not extend.

    Given
    -----
    - 4 validators; a slot needs 3 votes (2/3) to be justified.
    - the chain:
        genesis
        - common(1)
          - block_2(2) -> block_3(3)
          - fork_4(4)
    - block_3 includes V0's vote for block_2.
    - fork_4 includes V1, V2, V3's votes for common.
    - fork_4 reaches 3 votes, so it justifies slot 1.
    - block_3 has only 1 vote, so it justifies nothing.
    - the views diverge: node = slot 1, head chain = slot 0.

    When
    ----
    - block_5 is built on block_3, carrying no votes of its own.

    Then
    ----
    - block_5 pulls the slot-1 votes from the pool and includes them.
    - the head chain justifies slot 1, matching the node.
    - finalized stays at slot 0.
    """

def encode_bitlist(bits: Sequence[Boolean]) -> bytes:
    """
    Encode a variable-length bitlist to SSZ bytes.

    # Overview

    Data bits are packed little-endian within each byte.
    A single 1 bit is placed immediately after the last data bit.
    The trailing bit lets the decoder recover the original count.

    SSZ encodes bitlists as raw bytes with no length prefix.
    Without that trailing bit, [1, 0] and [1, 0, 0, 0, 0, 0, 0, 0] would share the byte 0x01.
    A trailing 1 bit is the smallest sentinel that disambiguates them.

    # Layout

        bits = [1, 0, 1]   ->  byte 0:  0 0 0 0 [1] 1 0 1   (delimiter at bit 3)
        bits = [1] * 8     ->  byte 0:  1 1 1 1 1 1 1 1
                               byte 1:  0 0 0 0 0 0 0 [1]   (delimiter spills)

    Args:
        bits: The variable-length bit data.

    Returns:
        SSZ-encoded bytes containing the data bits and the delimiter.
    """
    # Phase 1: handle the empty case.
    #
    # No data bits means the encoding is just the delimiter.
    num_bits = len(bits)
    if num_bits == 0:
        return b"\x01"

    # Phase 2: pack data bits little-endian into a byte array.
    #
    # Bit i of the input lands in byte i // 8 at position i % 8.
    byte_len = (num_bits + 7) // 8
    byte_array = bytearray(byte_len)
    for i, bit in enumerate(bits):
        if bit:
            byte_array[i // 8] |= 1 << (i % 8)

    # Phase 3: place the delimiter immediately after the last data bit.
    #
    # When the bit count is a multiple of 8, the delimiter has no room
    # in the existing array and spills into a fresh trailing byte.
    if num_bits % 8 == 0:
        return bytes(byte_array) + b"\x01"
    byte_array[num_bits // 8] |= 1 << (num_bits % 8)
    return bytes(byte_array)