# Protocol fixtures

QuackDB keeps cross-implementation binary fixtures under `test/fixtures/quack_ts/`.

The core fixtures are generated by the independent `quack-ts` implementation and assert byte-for-byte compatibility for scalar and nested `DataChunk` and `AppendRequest` encoding. Extra decode fixtures cover protocol values that are awkward to construct in broad fixtures or need targeted regression coverage.

## quack-ts parity

| Fixture | Direction | Status |
| --- | --- | --- |
| `data_chunk_scalar.bin` | encode/decode `DataChunk` | Covered |
| `data_chunk_nested.bin` | encode/decode `DataChunk` | Covered |
| `append_request_scalar.bin` | encode `AppendRequest` | Covered |
| `append_request_nested.bin` | encode `AppendRequest` | Covered |
| `data_chunk_bignum_extra.bin` | decode `BIGNUM` values | Covered |
| `data_chunk_temporal_extra.bin` | decode nanosecond/time-zone temporal values and intervals | Covered |
| `data_chunk_spatial_extra.bin` | decode `GEOMETRY` bytes | Covered |
| `data_chunk_nested_nulls_extra.bin` | decode null-heavy nested values | Covered |

Parity expectations:

- Encoded scalar and nested chunks should match the independent fixtures byte-for-byte.
- Decode-only fixtures should assert semantic values when QuackDB intentionally exposes a more Elixir-friendly shape than the fixture generator input.
- Malformed fixtures are QuackDB-owned regression fixtures, not quack-ts parity fixtures.

## Malformed fixtures

Malformed fixtures are intentionally invalid protocol messages used to verify that the decoder rejects corrupt input with a structured `QuackDB.Error` instead of crashing or silently returning the wrong value.

| Fixture | Expected error | Invariant |
| --- | --- | --- |
| `test/fixtures/quackdb_malformed/data_chunk_bignum_bad_size.bin` | `:invalid_bignum` | `BIGNUM` payload claims a two-byte magnitude but only includes one byte. |
| `test/fixtures/quackdb_malformed/data_chunk_extra_vector.bin` | `:data_chunk_type_mismatch` | Chunk declares zero logical types but encodes one `INTEGER` vector. |
| `test/fixtures/quackdb_malformed/data_chunk_missing_vector.bin` | `:data_chunk_type_mismatch` | Chunk declares one `INTEGER` logical type but encodes zero vectors. |

## Backlog

- Malformed vector bodies for unsupported compressed vector encodings.
- Malformed logical type metadata fixtures for unsupported or partial type families.
- `UNION` and `VARIANT` logical type fixtures if DuckDB Quack exposes stable payloads that can be captured or generated independently.
- Extension/custom type metadata fixtures once DuckDB exposes stable payloads.
- FSST vector fixtures once DuckDB Quack serializes compressed FSST vectors instead of flattening them.

Every new fixture should document the exact invariant it covers. Avoid arbitrary random corrupt bytes.