lac 0.1.0

//! Wire-format conformance fixtures.
//!
//! Each `DecodeFixture` pins a `(samples, bytes)` pair at the byte
//! level. A second implementation of LAC MUST produce `samples` when
//! fed `bytes` to its decoder. This test suite is the canonical
//! reference for decoder conformance: byte-identical `bytes` across
//! implementations aren't required (encoders have latitude in order /
//! partition / k selection), but byte-identical decoder output is.
//!
//! # How this file works
//!
//! - `DECODE_FIXTURES` holds the pinned vectors.
//! - `decode_fixtures` runs each fixture's bytes through `decode_frame`
//!   and asserts the output matches. This is the conformance test.
//! - `encode_matches_fixtures` runs each fixture's samples through the
//!   reference encoder and asserts the bytes match. This catches
//!   unintentional drift in the reference's encoder strategy; a
//!   deliberate change (e.g. adding a new predictor or order) will fail
//!   this test and require regenerating the fixtures.
//! - `generate_vectors` (ignored by default) prints the current
//!   reference encoder output in a paste-ready format. Run via
//!   `cargo test --test conformance generate_vectors --
//!   --ignored --nocapture` to refresh the fixtures after an
//!   intentional encoder change.
//!
//! # Rejection fixtures
//!
//! `REJECT_FIXTURES` pins header-level malformed inputs to their
//! expected `DecodeError` variants. These are hand-constructed — the
//! encoder never emits them — so they verify decoder rejection paths
//! across implementations.

use lac::{DecodeError, decode_frame, encode_frame};

// ── Decode / encode fixtures ────────────────────────────────────────────────

struct DecodeFixture {
    name: &'static str,
    samples: &'static [i32],
    bytes: &'static [u8],
}

/// Pinned wire-format vectors. Populated from the reference encoder
/// via `generate_vectors` below. See `ENCODER_PIN` comment at the top
/// of the generator for the rationale on why this doubles as a drift
/// canary for the encoder.
const DECODE_FIXTURES: &[DecodeFixture] = &[
    // ── Degenerate / smallest frames ───────────────────────────────
    DecodeFixture {
        name: "single_zero",
        samples: &[0],
        bytes: &[0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x01, 0x04],
    },
    DecodeFixture {
        name: "silence_4",
        samples: &[0, 0, 0, 0],
        bytes: &[0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x04, 0x07, 0x80],
    },
    DecodeFixture {
        name: "silence_8",
        samples: &[0, 0, 0, 0, 0, 0, 0, 0],
        bytes: &[0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x08, 0x07, 0xf8],
    },
    // ── Single-sample polarity + magnitude boundaries ──────────────
    DecodeFixture {
        name: "single_pos_one",
        samples: &[1],
        bytes: &[0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x01, 0x01],
    },
    DecodeFixture {
        name: "single_neg_one",
        samples: &[-1],
        bytes: &[0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02],
    },
    DecodeFixture {
        name: "single_full_scale_pos",
        samples: &[(1 << 23) - 1],
        bytes: &[
            0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x01, 0xbb, 0xff, 0xff, 0xf8,
        ],
    },
    DecodeFixture {
        name: "single_full_scale_neg",
        samples: &[-((1 << 23) - 1)],
        bytes: &[
            0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x01, 0xbb, 0xff, 0xff, 0xf4,
        ],
    },
    // ── DC and near-DC content ─────────────────────────────────────
    DecodeFixture {
        name: "dc_100_4",
        samples: &[100, 100, 100, 100],
        bytes: &[
            0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x04, 0x3b, 0x21, 0x90, 0xc8, 0x64, 0x00,
        ],
    },
    // ── Alternating polarity (Nyquist-like) ────────────────────────
    DecodeFixture {
        name: "alternating_small_4",
        samples: &[1000, -1000, 1000, -1000],
        bytes: &[
            0x1a, 0xcc, 0x00, 0x00, 0x00, 0x00, 0x04, 0x53, 0xe8, 0x3e, 0x7b, 0xe8, 0x3e, 0x78,
        ],
    },
    // ── Smooth polynomial — fixed predictor territory ──────────────
    DecodeFixture {
        name: "linear_ramp_8",
        samples: &[0, 100, 200, 300, 400, 500, 600, 700],
        bytes: &[
            0x1a, 0xcc, 0x02, 0x02, 0x02, 0x00, 0x08, 0x40, 0x00, 0xe0, 0x00, 0x34, 0x01, 0x20,
            0x18, 0x30, 0x60,
        ],
    },
    // ── 16-sample growing-amplitude (exercises partition + LPC) ────
    DecodeFixture {
        name: "lfsr_noise_16",
        samples: &[
            21, -100, 42, -200, 51, -400, 71, -800, 90, -1600, 110, -3200, 130, -6400, 151, -12800,
        ],
        bytes: &[
            0x1a, 0xcc, 0x00, 0x01, 0x00, 0x00, 0x10, 0x44, 0xab, 0x8f, 0x54, 0x63, 0xec, 0xc2,
            0x3f, 0x8e, 0x02, 0x7e, 0xc8, 0x5a, 0x71, 0xfe, 0x1b, 0x8c, 0x7f, 0xc4, 0x10, 0x47,
            0xfe, 0x25, 0xc0, 0x4f, 0xfc,
        ],
    },
];

// ── Rejection fixtures ──────────────────────────────────────────────────────

struct RejectFixture {
    name: &'static str,
    bytes: &'static [u8],
    expected: DecodeError,
}

const REJECT_FIXTURES: &[RejectFixture] = &[
    RejectFixture {
        name: "bad_sync_word",
        // Sync byte flipped to 0xFF; rest is a well-formed minimal
        // verbatim header so the decoder only rejects on the first
        // check.
        bytes: &[0xFF, 0xCC, 0x00, 0x00, 0x00, 0x00, 0x01],
        expected: DecodeError::BadSyncWord { got: 0xFFCC },
    },
    RejectFixture {
        name: "prediction_order_above_max",
        bytes: &[0x1A, 0xCC, 0x21, 0x00, 0x00, 0x00, 0x01],
        expected: DecodeError::InvalidPredictionOrder { got: 33 },
    },
    RejectFixture {
        name: "partition_order_above_max",
        bytes: &[0x1A, 0xCC, 0x00, 0x08, 0x00, 0x00, 0x01],
        expected: DecodeError::InvalidPartitionOrder { got: 8 },
    },
    RejectFixture {
        name: "coefficient_shift_above_max",
        // Non-zero prediction_order so the shift is actually used.
        // 2 bytes of (zero) coefficient follow so the header is
        // structurally valid before the shift check fires.
        bytes: &[0x1A, 0xCC, 0x01, 0x00, 0x06, 0x00, 0x01, 0x00, 0x00],
        expected: DecodeError::InvalidCoefficientShift { got: 6 },
    },
    RejectFixture {
        name: "coefficient_shift_without_order",
        // order = 0, shift = 3 — contradictory per spec §3.4.
        bytes: &[0x1A, 0xCC, 0x00, 0x00, 0x03, 0x00, 0x01],
        expected: DecodeError::CoefficientShiftWithoutOrder { shift: 3 },
    },
    RejectFixture {
        name: "zero_frame_sample_count",
        bytes: &[0x1A, 0xCC, 0x00, 0x00, 0x00, 0x00, 0x00],
        expected: DecodeError::InvalidParameter,
    },
    RejectFixture {
        name: "frame_count_not_divisible_by_partition_count",
        // partition_order = 3 → 8 partitions, count = 7 doesn't divide.
        bytes: &[0x1A, 0xCC, 0x00, 0x03, 0x00, 0x00, 0x07],
        expected: DecodeError::InvalidParameter,
    },
    RejectFixture {
        name: "truncated_before_header_complete",
        // Only 3 bytes — below the 7-byte fixed header minimum.
        bytes: &[0x1A, 0xCC, 0x00],
        expected: DecodeError::Truncated,
    },
    RejectFixture {
        name: "truncated_before_coefficients",
        // prediction_order = 2 claims 4 trailing coefficient bytes,
        // but only 7 bytes are present.
        bytes: &[0x1A, 0xCC, 0x02, 0x00, 0x00, 0x00, 0x04],
        expected: DecodeError::Truncated,
    },
    RejectFixture {
        name: "truncated_before_rice_bitstream",
        // Fully valid 7-byte header with count=1 and order=0 (no
        // coefficients), then no Rice bytes at all. Decoder reads the
        // header, enters Rice decode, tries to read the 5-bit `k`
        // field, and fails. Covers the third truncation class in
        // spec §6 (Rice-bitstream-level, distinct from header and
        // coefficient-array truncations above).
        bytes: &[0x1A, 0xCC, 0x00, 0x00, 0x00, 0x00, 0x01],
        expected: DecodeError::Truncated,
    },
    RejectFixture {
        name: "rice_k_above_max",
        // Valid 7-byte verbatim header; first Rice byte stores `k=31`
        // in its high 5 bits (31 = 0b11111, left-shifted 3 = 0xF8).
        // The decoder reads `k` and rejects immediately — never
        // proceeds to the codeword — per spec §4.1 (k must be in
        // [0, 23]).
        bytes: &[0x1A, 0xCC, 0x00, 0x00, 0x00, 0x00, 0x01, 0xF8],
        expected: DecodeError::InvalidParameter,
    },
];

// ── Tests ───────────────────────────────────────────────────────────────────

#[test]
fn decode_fixtures() {
    // The canonical conformance check: every fixture's bytes must
    // decode to the claimed samples. Any second implementation's
    // decoder that fails this test is non-conformant.
    for f in DECODE_FIXTURES {
        if f.bytes.is_empty() {
            // Placeholder fixture — regenerate with `generate_vectors`.
            continue;
        }
        let decoded = decode_frame(f.bytes)
            .unwrap_or_else(|e| panic!("fixture {}: decode failed with {e:?}", f.name));
        assert_eq!(
            decoded, f.samples,
            "fixture {}: decoded samples mismatch",
            f.name
        );
    }
}

#[test]
fn encode_matches_fixtures() {
    // Drift canary: the reference encoder currently produces these
    // exact bytes for these inputs. A deliberate change to the
    // encoder's search strategy (new predictor, different grid,
    // different tie-break) will fail this test and should be followed
    // by regenerating the `bytes` fields via `generate_vectors`.
    //
    // Second implementations are not obligated to produce byte-
    // identical output, so this test is reference-specific.
    for f in DECODE_FIXTURES {
        if f.bytes.is_empty() {
            continue;
        }
        let encoded = encode_frame(f.samples);
        assert_eq!(
            &encoded[..],
            f.bytes,
            "fixture {}: encoder output drifted from pinned bytes",
            f.name
        );
    }
}

#[test]
fn reject_fixtures() {
    for f in REJECT_FIXTURES {
        match decode_frame(f.bytes) {
            Ok(samples) => panic!(
                "fixture {}: expected {:?}, got Ok with {} samples",
                f.name,
                f.expected,
                samples.len()
            ),
            Err(e) => assert_eq!(e, f.expected, "fixture {}: wrong error variant", f.name),
        }
    }
}

/// Spec §6 rejection class 10: decoder **must** reject any codeword
/// whose unary run length exceeds `u32::MAX >> k` (equivalently
/// `q > (2³² − 1) / 2^k`). Lives here rather than in `REJECT_FIXTURES`
/// because the minimal triggering payload is ~75 bytes of mostly
/// zeros — a const array of that shape is noise, and the construction
/// logic (`k = 23`, so `q_max = 511`; emit 512 unary zeros; then
/// terminator + zero remainder) documents the intent better than a
/// hex blob.
#[test]
fn reject_unary_run_above_cap() {
    // Header: sync + order=0 + po=0 + shift=0 + count=1. Rice section
    // begins at byte 7 with no coefficients in between.
    let mut bytes: Vec<u8> = vec![0x1A, 0xCC, 0x00, 0x00, 0x00, 0x00, 0x01];

    // Rice payload, built bit-by-bit via the codec's own BitWriter
    // analogue below. Doing it with raw byte arithmetic here would
    // duplicate bit-ordering logic that already lives in `bit_io`.
    // We construct the payload into a separate Vec and append.
    //
    // Payload structure (541 bits total, padded to 544 = 68 bytes):
    //   - 5 bits: k = 23           (triggers q_max = u32::MAX >> 23 = 511)
    //   - 512 bits: unary zeros    (one past the cap)
    //   - 1 bit: terminator = 1
    //   - 23 bits: remainder = 0
    let mut rice: Vec<u8> = Vec::with_capacity(68);
    let mut bit_accum: u32 = 0;
    let mut bits_in_accum: u32 = 0;
    let push_bits = |value: u32, count: u32, rice: &mut Vec<u8>, accum: &mut u32, n: &mut u32| {
        for i in (0..count).rev() {
            let bit = (value >> i) & 1;
            *accum = (*accum << 1) | bit;
            *n += 1;
            if *n == 8 {
                rice.push(*accum as u8);
                *accum = 0;
                *n = 0;
            }
        }
    };
    push_bits(23, 5, &mut rice, &mut bit_accum, &mut bits_in_accum); // k = 23
    for _ in 0..512 {
        push_bits(0, 1, &mut rice, &mut bit_accum, &mut bits_in_accum);
    }
    push_bits(1, 1, &mut rice, &mut bit_accum, &mut bits_in_accum); // terminator
    push_bits(0, 23, &mut rice, &mut bit_accum, &mut bits_in_accum); // remainder
    // Flush partial byte (left-aligned, matching spec §4.3).
    if bits_in_accum > 0 {
        rice.push((bit_accum << (8 - bits_in_accum)) as u8);
    }

    bytes.extend_from_slice(&rice);
    assert_eq!(bytes.len(), 7 + 68, "unexpected fixture length");

    assert_eq!(
        decode_frame(&bytes),
        Err(DecodeError::InvalidParameter),
        "q=512 with k=23 exceeds u32::MAX >> k = 511; decoder must reject \
         with InvalidParameter per spec §4.2"
    );
}

#[test]
#[ignore = "helper for refreshing the pinned byte literals"]
fn generate_vectors() {
    // Prints DECODE_FIXTURES entries in paste-ready format. Run with
    //   cargo test --test conformance generate_vectors -- --ignored --nocapture
    // then copy the output over the existing fixture bodies. Intended
    // for use after a deliberate change to encoder strategy; refuses
    // to run in normal test flow to avoid accidental acceptance of
    // silent drift.
    for f in DECODE_FIXTURES {
        let encoded = encode_frame(f.samples);
        eprintln!("    DecodeFixture {{");
        eprintln!("        name: {:?},", f.name);
        eprint!("        samples: &[");
        for (i, s) in f.samples.iter().enumerate() {
            if i > 0 {
                eprint!(", ");
            }
            eprint!("{s}");
        }
        eprintln!("],");
        eprint!("        bytes: &[");
        for (i, b) in encoded.iter().enumerate() {
            if i > 0 {
                eprint!(", ");
            }
            eprint!("{b:#04x}");
        }
        eprintln!("],");
        eprintln!("    }},");
    }
}