fuzz.cpp

/*
    serialize

    Copyright © 2016 - 2026, Más Bandwidth LLC.

    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer
           in the documentation and/or other materials provided with the distribution.

        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived
           from this software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
    USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

/*
    libFuzzer harness for serialize.

    Every input runs three passes:

    1. Hostile read (FuzzRead). ReadStream is the trust boundary of this library: it must survive
       arbitrary hostile bytes, failing reads by returning false, never by corrupting memory or
       tripping an assert. Build with asserts enabled (Debug config) plus ASan/UBSan so all three
       failure modes are caught.

    2. The same hostile bytes through InitializePadded, from a source allocation with no slack.
       The source is heap allocated at exactly the payload size so ASan fences the byte after it.

    3. Differential round trip (FuzzRoundTrip). Values generated from the input are written with
       WriteStream, read back with ReadStream, and compared. Any write/read asymmetry traps.
       MeasureStream runs the same ops and must never measure fewer bits than were written.

    The first bytes of the fuzz input are an op program selecting which serialize_* calls run and
    with what parameters. The remaining bytes are the hostile bitstream for pass 1 and the value
    pool for pass 2. This lets coverage-guided fuzzing explore interleavings of every primitive.
*/

#include "serialize.h"

#include <stdlib.h>
#include <vector>

#define fuzz_check( condition ) do { if ( !(condition) ) { __builtin_trap(); } } while (0)

// hands out bytes from the fuzz input, wrapping around when exhausted. both round trip passes
// regenerate the identical value sequence, so nothing needs to be stored between passes.

struct ValuePool
{
    const uint8_t * data;
    size_t size;
    size_t index;

    ValuePool( const uint8_t * data_in, size_t size_in ) : data( data_in ), size( size_in ), index( 0 ) {}

    uint8_t NextByte()
    {
        if ( size == 0 )
            return 0;
        if ( index >= size )
            index = 0;
        return data[index++];
    }

    uint32_t NextUint32()
    {
        uint32_t value = 0;
        for ( int i = 0; i < 4; i++ )
            value = ( value << 8 ) | NextByte();
        return value;
    }

    uint64_t NextUint64()
    {
        return ( uint64_t( NextUint32() ) << 32 ) | NextUint32();
    }
};

// pass 1: hostile read. arbitrary bytes go in, reads must fail cleanly or produce in-contract values.

template <typename Stream> bool FuzzRead( Stream & stream, const uint8_t * ops, int numOps )
{
    uint8_t bytes[256];
    char string[256];

    for ( int i = 0; i < numOps; i++ )
    {
        const int select = ops[i] & 15;
        const int param = ops[i] >> 4;              // [0,15]

        switch ( select )
        {
            case 0:
            {
                uint32_t value = 0;
                const int bits = param + 1;         // [1,16]
                serialize_bits( stream, value, bits );
                fuzz_check( value < ( 1U << bits ) );
            }
            break;

            case 1:
            {
                uint32_t value = 0;
                const int bits = param + 17;        // [17,32]
                serialize_bits( stream, value, bits );
                fuzz_check( bits == 32 || value < ( 1U << bits ) );
            }
            break;

            case 2:
            {
                int32_t value = 0;
                serialize_int( stream, value, -100, +100 );
                fuzz_check( value >= -100 && value <= +100 );
            }
            break;

            case 3:
            {
                int32_t value = 0;
                serialize_int( stream, value, INT32_MIN, INT32_MAX );
                int64_t value64 = 0;
                serialize_int64( stream, value64, INT64_MIN, INT64_MAX );
                const int64_t bound = int64_t( param + 1 ) << 35;               // spans of varying width exercise bits_required64
                int64_t ranged64 = 0;
                serialize_int64( stream, ranged64, -bound, +bound );
                fuzz_check( ranged64 >= -bound && ranged64 <= +bound );

                // fixed point: bounds are compile time, so the configurations are fixed. values read
                // off hostile bytes must decode within the raw bounds or fail the read.
                int32_t fixed32 = 0;
                serialize_fixed( stream, fixed32, 16, 16, -1000, +1000 );
                fuzz_check( fixed32 >= -1000 * 65536 && fixed32 <= 1000 * 65536 );

                int64_t fixed64 = 0;
                serialize_fixed( stream, fixed64, 48, 16, -100000000000LL, +100000000000LL );
                fuzz_check( fixed64 >= -100000000000LL * 65536 && fixed64 <= 100000000000LL * 65536 );

                serialize::int128_t wide = 0;                                   // exists on every platform: native or emulated
                serialize_fixed( stream, wide, 112, 16, -1152921504606846976LL, +1152921504606846976LL );        // ±2^60 units: a raw range past 64 bits
                fuzz_check( wide >= serialize::int128_t( -1152921504606846976LL ) * serialize::int128_t( 65536 ) );
                fuzz_check( wide <= serialize::int128_t( +1152921504606846976LL ) * serialize::int128_t( 65536 ) );

                // ranged 128 bit integers, with the bound width varying by param so the run walks
                // every group structure: one group, two, three and four. hostile bytes must decode
                // inside the bounds or fail the read — never clamp, never wrap.
                const serialize::int128_t bound128 = serialize::int128_t( 1 ) << ( 20 + ( param % 100 ) );
                serialize::int128_t ranged128 = 0;
                serialize_int128( stream, ranged128, -bound128, +bound128 );
                fuzz_check( ranged128 >= -bound128 && ranged128 <= +bound128 );

                serialize::int128_t full128 = 0;
                serialize_int128( stream, full128, serialize::int128_t( serialize::uint128_t( 1 ) << 127 ), serialize::int128_t( ~( serialize::uint128_t( 1 ) << 127 ) ) );
            }
            break;

            case 4:
            {
                bool value = false;
                serialize_bool( stream, value );
            }
            break;

            case 5:
            {
                // finite values only: whatever the bytes, an accepted float is never NaN or infinite
                float value = 0.0f;
                serialize_float( stream, value );
                uint32_t value_bits = 0;
                memcpy( &value_bits, &value, 4 );
                fuzz_check( serialize::float_bits_are_finite( value_bits ) );
            }
            break;

            case 6:
            {
                double value = 0.0;
                serialize_double( stream, value );
                uint64_t value_bits = 0;
                memcpy( &value_bits, &value, 8 );
                fuzz_check( serialize::double_bits_are_finite( value_bits ) );
            }
            break;

            case 7:
            {
                float value = 0.0f;
                serialize_compressed_float( stream, value, -10.0f, +10.0f, 0.01f );
                uint32_t value_bits = 0;
                memcpy( &value_bits, &value, 4 );
                fuzz_check( serialize::float_bits_are_finite( value_bits ) );
            }
            break;

            case 8:
            {
                uint64_t value = 0;
                serialize_uint64( stream, value );
                serialize::uint128_t value128 = 0;                      // exists on every platform: native or emulated
                serialize_uint128( stream, value128 );
            }
            break;

            case 9:
            {
                const int numBytes = param * 16 + 1;                    // [1,241]
                serialize_bytes( stream, bytes, numBytes );
            }
            break;

            case 10:
            {
                serialize_string( stream, string, (int) sizeof( string ) );
                fuzz_check( strlen( string ) < sizeof( string ) );
            }
            break;

            case 11:
            {
                // the end of the object: an accepted end leaves nothing in the stream
                serialize_end( stream );
                fuzz_check( stream.GetBitsProcessed() % 8 == 0 );
                uint32_t after = 0;
                fuzz_check( stream.SerializeBits( after, 1 ) == false );
                return false;
            }

            case 12:
            {
                serialize_align( stream );
            }
            break;

            case 13:
            {
                int previous = param * 1000;                    // int_relative's domain starts at 0: a negative previous is caller error
                int current = 0;
                serialize_int_relative( stream, previous, current );
            }
            break;

            case 14:
            {
                const int32_t max = ( param + 1 ) * 1000;               // ranges of varying width exercise bits_required
                int32_t value = 0;
                serialize_int( stream, value, 0, max );
                fuzz_check( value >= 0 && value <= max );
            }
            break;

            case 15:
            {
                uint8_t value8 = 0;
                serialize_uint8( stream, value8 );
                uint16_t value16 = 0;
                serialize_uint16( stream, value16 );
                uint32_t value32 = 0;
                serialize_uint32( stream, value32 );
            }
            break;
        }
    }

    return true;
}

// pass 2: differential round trip. run once with WriteStream (and MeasureStream), then again with
// ReadStream over the bytes just written. every case must consume the same pool bytes when writing
// and reading, so the read pass regenerates the exact values the write pass produced.

template <typename Stream> bool FuzzRoundTrip( Stream & stream, const uint8_t * ops, int numOps, ValuePool & pool )
{
    for ( int i = 0; i < numOps; i++ )
    {
        const int select = ops[i] & 15;
        const int param = ops[i] >> 4;              // [0,15]

        switch ( select )
        {
            case 0:
            case 1:
            {
                const int bits = ( select == 0 ) ? param + 1 : param + 17;                      // [1,32]
                const uint32_t mask = ( bits == 32 ) ? 0xFFFFFFFF : ( ( 1U << bits ) - 1 );
                const uint32_t expected = pool.NextUint32() & mask;
                uint32_t value = Stream::IsWriting ? expected : 0;
                serialize_bits( stream, value, bits );
                if ( Stream::IsReading )
                {
                    fuzz_check( value == expected );
                }
            }
            break;

            case 2:
            {
                const int32_t expected = -100 + int32_t( pool.NextUint32() % 201 );
                int32_t value = Stream::IsWriting ? expected : 0;
                serialize_int( stream, value, -100, +100 );
                if ( Stream::IsReading )
                {
                    fuzz_check( value == expected );
                }
            }
            break;

            case 3:
            {
                const int32_t expected = (int32_t) pool.NextUint32();
                int32_t value = Stream::IsWriting ? expected : 0;
                serialize_int( stream, value, INT32_MIN, INT32_MAX );
                if ( Stream::IsReading )
                {
                    fuzz_check( value == expected );
                }

                const int64_t expected64 = (int64_t) pool.NextUint64();
                int64_t value64 = Stream::IsWriting ? expected64 : 0;
                serialize_int64( stream, value64, INT64_MIN, INT64_MAX );
                if ( Stream::IsReading )
                {
                    fuzz_check( value64 == expected64 );
                }

                const int64_t bound = int64_t( param + 1 ) << 35;               // spans of varying width exercise bits_required64
                const uint64_t span = uint64_t( bound ) * 2 + 1;
                const int64_t expected_ranged = -bound + int64_t( pool.NextUint64() % span );
                int64_t ranged64 = Stream::IsWriting ? expected_ranged : 0;
                serialize_int64( stream, ranged64, -bound, +bound );
                if ( Stream::IsReading )
                {
                    fuzz_check( ranged64 == expected_ranged );
                }

                // fixed point: raw values generated uniformly inside the raw bounds must round trip exactly
                const uint32_t fixed32_range = 2000U * 65536;                   // bounds [-1000,+1000] whole units in Q16.16
                const int32_t expected_fixed32 = int32_t( uint32_t( -1000 * 65536 ) + pool.NextUint32() % ( fixed32_range + 1 ) );
                int32_t fixed32 = Stream::IsWriting ? expected_fixed32 : 0;
                serialize_fixed( stream, fixed32, 16, 16, -1000, +1000 );
                if ( Stream::IsReading )
                {
                    fuzz_check( fixed32 == expected_fixed32 );
                }

                const uint64_t fixed64_range = uint64_t( 200000000000ULL ) * 65536;     // bounds [-1e11,+1e11] whole units in Q48.16
                const int64_t expected_fixed64 = int64_t( uint64_t( -100000000000LL * 65536 ) + pool.NextUint64() % ( fixed64_range + 1 ) );
                int64_t fixed64 = Stream::IsWriting ? expected_fixed64 : 0;
                serialize_fixed( stream, fixed64, 48, 16, -100000000000LL, +100000000000LL );
                if ( Stream::IsReading )
                {
                    fuzz_check( fixed64 == expected_fixed64 );
                }

                // wide fixed point: bounds ±2^60 whole units in Q112.16 give a raw range of 2^77,
                // exercising the multi group path with values that cannot fit in 64 bits. the wide
                // types exist on every platform: native __int128 or the emulated pair.
                const serialize::uint128_t wide_range = serialize::uint128_t( 1152921504606846976ULL ) << 17;    // ( 2 * 2^60 ) << 16
                const uint64_t wide_pool_high = pool.NextUint64();
                const uint64_t wide_pool_low = pool.NextUint64();
                const serialize::uint128_t wide_pool = ( serialize::uint128_t( wide_pool_high ) << 64 ) | wide_pool_low;
                const serialize::uint128_t wide_raw_min = serialize::uint128_t( serialize::int128_t( -1152921504606846976LL ) ) << 16;
                const serialize::int128_t expected_wide = serialize::int128_t( wide_raw_min + wide_pool % ( wide_range + serialize::uint128_t( 1 ) ) );
                serialize::int128_t wide = Stream::IsWriting ? expected_wide : serialize::int128_t( 0 );
                serialize_fixed( stream, wide, 112, 16, -1152921504606846976LL, +1152921504606846976LL );
                if ( Stream::IsReading )
                {
                    fuzz_check( wide == expected_wide );
                }
            }
            break;

            case 4:
            {
                const bool expected = ( pool.NextByte() & 1 ) != 0;
                bool value = Stream::IsWriting ? expected : false;
                serialize_bool( stream, value );
                if ( Stream::IsReading )
                {
                    fuzz_check( value == expected );
                }
            }
            break;

            case 5:
            {
                // arbitrary FINITE bit patterns, -0 and subnormals included: floats round trip bit
                // exact. NaN and infinity are non-conforming on write and assert in this harness, so
                // a non-finite pattern has its exponent cleared, which keeps the sign and mantissa
                // entropy as a subnormal. Hostile non-finite bytes reach the read path in pass 1
                const uint32_t raw_bits = pool.NextUint32();
                const uint32_t expected_bits = serialize::float_bits_are_finite( raw_bits ) ? raw_bits : ( raw_bits & 0x807FFFFF );
                float value = 0.0f;
                if ( Stream::IsWriting )
                {
                    memcpy( &value, &expected_bits, 4 );
                }
                serialize_float( stream, value );
                if ( Stream::IsReading )
                {
                    uint32_t value_bits = 0;
                    memcpy( &value_bits, &value, 4 );
                    fuzz_check( value_bits == expected_bits );
                }
            }
            break;

            case 6:
            {
                const uint64_t raw_bits = pool.NextUint64();
                const uint64_t expected_bits = serialize::double_bits_are_finite( raw_bits ) ? raw_bits : ( raw_bits & 0x800FFFFFFFFFFFFFULL );
                double value = 0.0;
                if ( Stream::IsWriting )
                {
                    memcpy( &value, &expected_bits, 8 );
                }
                serialize_double( stream, value );
                if ( Stream::IsReading )
                {
                    uint64_t value_bits = 0;
                    memcpy( &value_bits, &value, 8 );
                    fuzz_check( value_bits == expected_bits );
                }
            }
            break;

            case 7:
            {
                // arbitrary FINITE bit patterns: out of range values must clamp into [min,max] on
                // write, and finite in range values must round trip within the resolution. non-finite
                // values are non-conforming on write (STANDARD.md, adopted 2026-08-15) and assert out
                // in debug, so the writer is fed only finite input: clearing the exponent of a
                // non-finite pattern yields a subnormal, keeping the sign and mantissa entropy.
                // hostile non-finite coverage belongs to the read path, which stage one exercises.
                const uint32_t raw_bits = pool.NextUint32();
                const bool raw_finite = ( raw_bits & 0x7FFFFFFF ) < 0x7F800000;
                const uint32_t expected_bits = raw_finite ? raw_bits : ( raw_bits & 0x807FFFFF );
                float expected = 0.0f;
                memcpy( &expected, &expected_bits, 4 );
                float value = Stream::IsWriting ? expected : 0.0f;
                serialize_compressed_float( stream, value, -10.0f, +10.0f, 0.01f );
                if ( Stream::IsReading )
                {
                    fuzz_check( value >= -10.001f && value <= +10.001f );
                    const bool finite = ( expected_bits & 0x7FFFFFFF ) < 0x7F800000;            // bit test: immune to fast math
                    if ( finite && expected >= -10.0f && expected <= +10.0f )
                    {
                        fuzz_check( fabs( value - expected ) <= 0.011f );
                    }
                }
            }
            break;

            case 8:
            {
                const uint64_t expected = pool.NextUint64();
                uint64_t value = Stream::IsWriting ? expected : 0;
                serialize_uint64( stream, value );
                if ( Stream::IsReading )
                {
                    fuzz_check( value == expected );
                }

                const uint64_t expected128_high = pool.NextUint64();
                const uint64_t expected128_low = pool.NextUint64();
                const serialize::uint128_t expected128 = ( serialize::uint128_t( expected128_high ) << 64 ) | expected128_low;
                serialize::uint128_t value128 = Stream::IsWriting ? expected128 : serialize::uint128_t( 0 );
                serialize_uint128( stream, value128 );
                if ( Stream::IsReading )
                {
                    fuzz_check( value128 == expected128 );
                }
            }
            break;

            case 9:
            {
                const int numBytes = param * 16 + 1;                    // [1,241]
                uint8_t expected[256];
                for ( int j = 0; j < numBytes; j++ )
                    expected[j] = pool.NextByte();
                uint8_t value[256];
                if ( Stream::IsWriting )
                {
                    memcpy( value, expected, numBytes );
                }
                serialize_bytes( stream, value, numBytes );
                if ( Stream::IsReading )
                {
                    fuzz_check( memcmp( value, expected, numBytes ) == 0 );
                }
            }
            break;

            case 10:
            {
                char expected[32];
                const int length = pool.NextByte() % ( sizeof( expected ) - 1 );
                for ( int j = 0; j < length; j++ )
                {
                    // masked to ASCII: the string payload is well-formed UTF-8 by the
                    // writer's contract (debug-asserted, and asserts are live in this
                    // harness), and the reader REFUSES malformed payloads (STANDARD.md,
                    // adopted 2026-08-15), so the differential round trip must generate
                    // conforming content. Arbitrary bytes still reach the READ path via
                    // FuzzRead.
                    const uint8_t c = pool.NextByte() & 0x7F;
                    expected[j] = ( c != 0 ) ? (char) c : ' ';
                }
                expected[length] = '\0';
                char value[32];
                if ( Stream::IsWriting )
                {
                    memcpy( value, expected, length + 1 );
                }
                serialize_string( stream, value, (int) sizeof( value ) );
                if ( Stream::IsReading )
                {
                    fuzz_check( strcmp( value, expected ) == 0 );
                }
            }
            break;

            case 11:
            {
                // a string of real text: random Unicode scalar values, encoded as UTF-8 here, so
                // every length of sequence and every plane reaches the writer and must come back
                // byte for byte. NUL and the surrogate block are not scalar text and are skipped
                char expected[40];                                      // seven four byte characters at most, and the terminator
                int length = 0;
                const int characters = pool.NextByte() % 8;
                for ( int j = 0; j < characters; j++ )
                {
                    uint32_t code = pool.NextUint32() % 0x110000;
                    if ( code == 0 || ( code >= 0xD800 && code <= 0xDFFF ) )
                        code = 0x7881;                                  // 碁
                    if ( code < 0x80 )
                    {
                        expected[length++] = (char) code;
                    }
                    else if ( code < 0x800 )
                    {
                        expected[length++] = (char) ( 0xC0 | ( code >> 6 ) );
                        expected[length++] = (char) ( 0x80 | ( code & 0x3F ) );
                    }
                    else if ( code < 0x10000 )
                    {
                        expected[length++] = (char) ( 0xE0 | ( code >> 12 ) );
                        expected[length++] = (char) ( 0x80 | ( ( code >> 6 ) & 0x3F ) );
                        expected[length++] = (char) ( 0x80 | ( code & 0x3F ) );
                    }
                    else
                    {
                        expected[length++] = (char) ( 0xF0 | ( code >> 18 ) );
                        expected[length++] = (char) ( 0x80 | ( ( code >> 12 ) & 0x3F ) );
                        expected[length++] = (char) ( 0x80 | ( ( code >> 6 ) & 0x3F ) );
                        expected[length++] = (char) ( 0x80 | ( code & 0x3F ) );
                    }
                }
                expected[length] = '\0';
                char value[40];
                if ( Stream::IsWriting )
                {
                    memcpy( value, expected, length + 1 );
                }
                serialize_string( stream, value, (int) sizeof( value ) );
                if ( Stream::IsReading )
                {
                    fuzz_check( strcmp( value, expected ) == 0 );
                }
            }
            break;

            case 12:
            {
                serialize_align( stream );
            }
            break;

            case 13:
            {
                const int previous = param * 1000;              // int_relative's domain starts at 0: a negative previous is caller error
                const int expected = previous + 1 + int( pool.NextUint32() % 1000000 );         // strictly greater than previous
                int value = Stream::IsWriting ? expected : 0;
                serialize_int_relative( stream, previous, value );
                if ( Stream::IsReading )
                {
                    fuzz_check( value == expected );
                }
            }
            break;

            case 14:
            {
                const int32_t max = ( param + 1 ) * 1000;               // ranges of varying width exercise bits_required
                const int32_t expected = int32_t( pool.NextUint32() % uint32_t( max + 1 ) );
                int32_t value = Stream::IsWriting ? expected : 0;
                serialize_int( stream, value, 0, max );
                if ( Stream::IsReading )
                {
                    fuzz_check( value == expected );
                }
            }
            break;

            case 15:
            {
                const uint8_t expected8 = pool.NextByte();
                const uint16_t expected16 = (uint16_t) pool.NextUint32();
                const uint32_t expected32 = pool.NextUint32();
                uint8_t value8 = Stream::IsWriting ? expected8 : (uint8_t) 0;
                uint16_t value16 = Stream::IsWriting ? expected16 : (uint16_t) 0;
                uint32_t value32 = Stream::IsWriting ? expected32 : 0;
                serialize_uint8( stream, value8 );
                serialize_uint16( stream, value16 );
                serialize_uint32( stream, value32 );
                if ( Stream::IsReading )
                {
                    fuzz_check( value8 == expected8 );
                    fuzz_check( value16 == expected16 );
                    fuzz_check( value32 == expected32 );
                }
            }
            break;
        }
    }

    return true;
}

extern "C" int LLVMFuzzerTestOneInput( const uint8_t * data, size_t size )
{
    const int NumOps = 32;

    if ( size <= NumOps || size > NumOps + 4096 )
    {
        return 0;
    }

    const uint8_t * ops = data;
    const uint8_t * payload = data + NumOps;
    const size_t payloadBytes = size - NumOps;

    // pass 1: hostile read of arbitrary bytes
    {
        // the buffer allocation must extend at least 8 bytes past the data, because the bit reader loads 64 bit windows
        std::vector<uint8_t> buffer( payloadBytes + 8, 0 );
        memcpy( buffer.data(), payload, payloadBytes );

        serialize::ReadStream stream( buffer.data(), (int) payloadBytes );

        FuzzRead( stream, ops, NumOps );
    }

    // pass 2: the same hostile bytes, through InitializePadded, from a source
    // allocation with no slack. The destination is not zeroed first, so a byte
    // the reader can touch that the wrapper failed to write shows up as a
    // finding rather than a silent zero.
    {
        uint8_t * exact = (uint8_t *) malloc( payloadBytes );
        uint8_t * padded = (uint8_t *) malloc( payloadBytes + 8 );
        if ( exact == NULL || padded == NULL )
        {
            free( exact );
            free( padded );
            return 0;
        }
        memcpy( exact, payload, payloadBytes );
        serialize::ReadStream stream;
        fuzz_check( stream.InitializePadded( padded, (int64_t) ( payloadBytes + 8 ), exact, (int64_t) payloadBytes ) == true );
        FuzzRead( stream, ops, NumOps );
        free( exact );
        free( padded );
    }

    // pass 3: differential round trip of values generated from the same bytes
    {
        // worst case is ~260 bytes per op (a 241 byte serialize_bytes plus alignment), so 32 ops fit comfortably
        const int WriteBufferSize = 16 * 1024;
        alignas( 4 ) uint8_t writeBuffer[WriteBufferSize];
        memset( writeBuffer, 0, sizeof( writeBuffer ) );

        serialize::WriteStream writeStream( writeBuffer, WriteBufferSize );
        ValuePool writePool( payload, payloadBytes );
        fuzz_check( FuzzRoundTrip( writeStream, ops, NumOps, writePool ) == true );             // writing in-range values must always succeed
        writeStream.Flush();

        serialize::MeasureStream measureStream;
        ValuePool measurePool( payload, payloadBytes );
        fuzz_check( FuzzRoundTrip( measureStream, ops, NumOps, measurePool ) == true );
        fuzz_check( measureStream.GetBitsProcessed() >= writeStream.GetBitsProcessed() );       // measure must be conservative

        // the 16KB writeBuffer extends well past the written bytes, satisfying the reader's 8-bytes-past allocation contract
        serialize::ReadStream readStream( writeBuffer, writeStream.GetBytesProcessed() );
        ValuePool readPool( payload, payloadBytes );
        fuzz_check( FuzzRoundTrip( readStream, ops, NumOps, readPool ) == true );               // reading back our own data must always succeed
        fuzz_check( readStream.SerializeEnd() == true );                                        // and it ends exactly where the writer stopped

        // one byte more than the writer reported is trailing data, refused at the end
        serialize::ReadStream longerStream( writeBuffer, writeStream.GetBytesProcessed() + 1 );
        ValuePool longerPool( payload, payloadBytes );
        fuzz_check( FuzzRoundTrip( longerStream, ops, NumOps, longerPool ) == true );
        fuzz_check( longerStream.SerializeEnd() == false );
        fuzz_check( longerStream.GetRefusal() == serialize::REFUSAL_TRAILING_DATA );
    }

    return 0;
}